From 439c75f88357f397040a4e05e97ddb1fd344d180 Mon Sep 17 00:00:00 2001 From: Mayukha Vadari Date: Fri, 10 Jul 2026 11:13:27 -0400 Subject: [PATCH] add docstrings --- include/xrpl/ledger/helpers/SponsorHelpers.h | 79 ++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/include/xrpl/ledger/helpers/SponsorHelpers.h b/include/xrpl/ledger/helpers/SponsorHelpers.h index 6050efb610..0fbe7961e1 100644 --- a/include/xrpl/ledger/helpers/SponsorHelpers.h +++ b/include/xrpl/ledger/helpers/SponsorHelpers.h @@ -54,12 +54,14 @@ isReserveSponsorAllowed(TxType txType) return std::ranges::find(kReserveSponsorAllowed, txType) != kReserveSponsorAllowed.end(); } +/** Whether the transaction's fee is sponsored (sfSponsor present + spfSponsorFee set). */ inline bool isFeeSponsored(STTx const& tx) { return tx.isFieldPresent(sfSponsor) && ((tx.getFieldU32(sfSponsorFlags) & spfSponsorFee) != 0u); } +/** Whether the transaction's reserve is sponsored (sfSponsor present + spfSponsorReserve set). */ inline bool isReserveSponsored(STTx const& tx) { @@ -67,12 +69,28 @@ isReserveSponsored(STTx const& tx) ((tx.getFieldU32(sfSponsorFlags) & spfSponsorReserve) != 0u); } +/** Return the AccountID of the transaction's reserve sponsor, or nullopt if unsponsored. */ std::optional getTxReserveSponsorID(STTx const& tx); +/** Return a mutable SLE for the transaction's reserve sponsor account. + * + * @param ctx The apply-view context (view + tx) + * @return The sponsor account SLE, a null pointer if the tx is not + * reserve-sponsored, or tecINTERNAL if the sponsor account cannot + * be loaded (an already-checked invariant). + */ std::expected getTxReserveSponsor(ApplyViewContext ctx); +/** Return a read-only SLE for the transaction's reserve sponsor account. + * + * @param view The ledger read view + * @param tx The transaction to inspect + * @return The sponsor account SLE, a null pointer if the tx is not + * reserve-sponsored, or tecINTERNAL if the sponsor account cannot + * be loaded (an already-checked invariant). + */ std::expected getTxReserveSponsor(ReadView const& view, STTx const& tx); @@ -92,15 +110,38 @@ getTxReserveSponsor(ReadView const& view, STTx const& tx); [[nodiscard]] std::expected getEffectiveTxReserveSponsor(ApplyViewContext ctx, SLE::const_ref accountSle); +/** Return the AccountID stored in the given sponsor field of a ledger entry, or nullopt if absent. + */ std::optional getLedgerEntryReserveSponsorID(SLE::const_ref sle, SF_ACCOUNT const& field = sfSponsor); +/** Return a mutable SLE for the reserve sponsor recorded on a ledger entry. + * + * Reads the sponsor AccountID from @p field on @p sle and peeks the + * corresponding account root in @p view. + * + * @param view The mutable apply view + * @param sle The ledger entry whose sponsor field is inspected + * @param field The field that holds the sponsor AccountID (defaults to sfSponsor) + * @return The sponsor account SLE, or a null pointer if the entry is unsponsored. + */ SLE::pointer getLedgerEntryReserveSponsor( ApplyView& view, SLE::const_ref sle, SF_ACCOUNT const& field = sfSponsor); +/** Stamp a reserve sponsor onto a ledger entry using an explicit sponsor SLE. + * + * Sets @p field on @p sle to the AccountID from @p sponsorSle. A no-op when + * @p sponsorSle is null (unsponsored). For RippleState entries the field must + * be sfHighSponsor or sfLowSponsor; for all other entry types it must be + * sfSponsor. + * + * @param sle The ledger entry to stamp + * @param sponsorSle The sponsor's account root SLE (null → no-op) + * @param field The sponsor field to set (defaults to sfSponsor) + */ void addSponsorToLedgerEntry( SLE::ref sle, @@ -118,18 +159,56 @@ addSponsorToLedgerEntry( void addSponsorToLedgerEntry(ApplyViewContext ctx, SLE::ref sle, SF_ACCOUNT const& field = sfSponsor); +/** Remove the reserve sponsor field from a ledger entry. + * + * A no-op when @p field is not present on @p sle. For RippleState entries + * the field must be sfHighSponsor or sfLowSponsor; for all other entry types + * it must be sfSponsor. + * + * @param sle The ledger entry to modify + * @param field The sponsor field to clear (defaults to sfSponsor) + */ void removeSponsorFromLedgerEntry(SLE::ref sle, SF_ACCOUNT const& field = sfSponsor); +/** Resolve the owner AccountID of a ledger entry for sponsorship purposes. + * + * Ownership rules vary by entry type. For RippleState entries the owner is + * whichever side of the trust line holds the reserve and matches @p account. + * For credentials, the owner is the subject once accepted and the issuer + * before acceptance. + * + * @param view The ledger read view (used for SignerList lookup) + * @param sle The ledger entry whose owner is resolved + * @param account The candidate account to match against + * @return The owning AccountID, or nullopt if @p account does not own @p sle. + */ std::optional getLedgerEntryOwner(ReadView const& view, SLE const& sle, AccountID const& account); +/** Whether this ledger entry type can have a reserve sponsor attached to it. */ bool isLedgerEntrySupportedBySponsorship(SLE const& sle); +/** Return the number of owner-count units the ledger entry consumes. + * + * Most entries cost 1. Exceptions: Oracles scale with their price-data series + * size, Vaults cost 2 (vault + pseudo-account), and legacy SignerList entries + * (pre-MultiSignReserve) cost 2 + signer count. + */ std::uint32_t getLedgerEntryOwnerCount(SLE const& sle); +/** Return the SField used to store the reserve sponsor for @p owner on @p sle. + * + * For most entry types this is sfSponsor. RippleState entries use + * sfHighSponsor or sfLowSponsor depending on which side of the trust line + * @p owner holds. + * + * @param sle The ledger entry + * @param owner The account whose sponsor field is needed + * @return sfHighSponsor, sfLowSponsor, or sfSponsor as appropriate. + */ SF_ACCOUNT const& getLedgerEntrySponsorField(SLE const& sle, AccountID const& owner);