Skip to content
Prerelease Docs
/
/
/
Updated Common Transactio...
Edit

Updated Common Transaction Fields

This page describes the new fields and flags added to all transactions to support Sponsored Fees and Reserves. These fields extend the existing common transaction fields.

(Requires the Sponsor amendment )

New Common Fields

The following fields are added to the common transaction fields:

Field NameJSON TypeInternal TypeRequired?Description
SponsorStringAccountIDNoThe address of the sponsoring account.
SponsorFlagsNumberUInt32NoFlags indicating the type of sponsorship. If included, at least one flag must be set.
SponsorSignatureObjectObjectNoContains the signing information for the sponsorship.

SponsorFlags

The SponsorFlags field allows the user to specify which sponsorship type(s) they wish to participate in.

Flag NameHex ValueDecimal ValueDescription
spfSponsorFee0x000000011Sponsoring the fee of the transaction.
spfSponsorReserve0x000000022Sponsoring the reserve for any objects created in the transaction.
Note

Both flags can be used together in a single transaction. At least one flag must be set if the Sponsor field is included.

Pseudo-transactions do not support either sponsorship flag as they simply don't have fees or reserves at all. For all other transactions:

Note

Fee-sponsored transactions cannot be queued. If a fee-sponsored transaction does not make it into the open ledger, it fails with telCAN_NOT_QUEUE instead of entering the transaction queue.

SponsorSignature

The SponsorSignature field is an object containing the sponsor's signing information.

Field NameJSON TypeInternal TypeRequired?Description
SigningPubKeyStringBlobNoThe SigningPubKey for the Sponsor, if single-signing.
TxnSignatureStringBlobNoA signature of the transaction from the sponsor, to indicate their approval of this transaction, if single-signing.
SignersArrayArrayNoAn array of signatures of the transaction from the sponsor's signers to indicate their approval of this transaction, if the sponsor is multi-signing.

These fields are not included in transaction signatures, though they are still included in the stored transaction. There is no additional transaction fee for using TxnSignature.

Note

A sponsor signature is only required if no pre-funded Sponsorship ledger entry exists, or if the lsfSponsorshipRequireSignForFee or lsfSponsorshipRequireSignForReserve flags are enabled on the Sponsorship ledger entry.

Transaction Fee Calculation

If the SponsorSignature.Signers field is necessary, the total fee of the transaction will be increased due to the extra signatures that need to be processed. This is similar to the additional fees for multi-signing.

The total fee calculation for signatures is:

(1 + |tx.Signers| + |tx.SponsorSignature.Signers|) × base_fee (+ any transaction-specific fees)

Batch Transactions

The SponsorFlags apply at opposite levels of a Batch. Reserve sponsorship goes on the inner transactions, because the outer Batch doesn't support spfSponsorReserve. Fee sponsorship works the other way, so spfSponsorFee is valid only on the outer Batch, not on the inner transactions.

When a reserve sponsor co-signs an inner transaction, that transaction's SponsorSignature field must be present but empty. The sponsor signs the outer Batch transaction instead and appears as a BatchSigners entry.

Delegated Transactions

For transactions that include a Delegate field, note the following:

  • Fee sponsorship applies to the delegate, since the delegate pays the transaction fee.
  • When using pre-funded fee sponsorship, the delegate must be the sponsee instead of the account sending the transaction.
  • Reserve sponsorship cannot be combined with delegation and fails with temINVALID.

Error Cases

The following failure conditions have been added to transactions using the sponsorship fields:

Error CodeDescription
temDISABLEDThe Sponsor amendment is not enabled.
temMALFORMEDThe transaction is malformed. This can occur when:
  • The sponsor and the transaction sender are the same account.
  • The transaction includes a sponsor signature but does not specify a sponsor.
  • The sponsor signature contains an invalid combination of signing fields.
temINVALIDThe transaction has an invalid sponsor configuration. This can occur when:
  • The sponsor signature is invalid.
  • The transaction combines the spfSponsorReserve flag with a Delegate field. Reserve sponsorship cannot be combined with delegation.
temINVALID_FLAGThe transaction has invalid flags. This can occur when:
  • The SponsorFlags field contains invalid flags. Valid flags are spfSponsorFee and spfSponsorReserve.
  • The transaction includes SponsorFlags but does not specify a sponsor.
  • The SponsorFlags field is included but set to zero.
  • The spfSponsorReserve flag is set on a transaction type that does not support reserve sponsorship.
terNO_ACCOUNTThe sponsor account does not exist.
tefBAD_AUTHThe sponsor signature is invalid. The public key does not match the sponsor account's master key or regular key, or the key type is unknown.
tefNOT_MULTI_SIGNINGThe sponsor account does not have a signer list.
tefBAD_SIGNATUREThe sponsor multi-signature is invalid. A signer is not in the signer list, a public key is invalid, or a signature is invalid.
tefBAD_QUORUMThe sponsor multi-signature does not meet the required quorum.
terNO_PERMISSIONThe transaction does not meet the sponsorship requirements. This can occur when:
  • The transaction requires a sponsor signature, but none was provided and no pre-funded Sponsorship exists.
  • The Sponsorship requires a signature for fee sponsorship.
  • The Sponsorship requires a signature for reserve sponsorship.
terINSUF_FEE_BThe sponsor cannot pay the transaction fee: the co-signing sponsor's balance above its own reserve, or the pre-funded Sponsorship's FeeAmount (capped by MaxFee), is insufficient. Returned against the open ledger, or when the fee payer has nothing spendable at all.
tecINSUFF_FEEThe same insufficient-fee condition as terINSUF_FEE_B, returned when the transaction is applied in a closed ledger and the fee payer has some spendable balance (non-zero) but not enough.
tecINSUFFICIENT_RESERVEThe sponsor does not have enough XRP to cover the reserve, or the pre-funded Sponsorship does not have enough RemainingOwnerCount.