Fee Bumps
A fee-bump transaction enables any account to pay the fee for an existing transaction without the need to re-sign the existing transaction or manage sequence numbers. They're useful if you need to increase the fee on a pre-signed transaction, or if you want to build a service that covers user fees. Unlike a regular transaction, which contains 1-100 operations, a fee-bump transaction contains a single transaction envelope.
Each fee-bump transaction encloses a single transaction envelope, which itself encloses a single inner transaction. Before creating a fee-bump transaction, in other words, you must first have a transaction wrapped with requisite signatures in a transaction envelope.
In addition to a transaction envelope, each fee-bump transaction has the following attributes:
The account that provides the fee for the fee-bump transaction. It incurs the fee instead of the source account specified in the inner transaction. The sequence number for the fee-bump transaction, however, is still taken from the source account specified in the inner transaction.
The maximum per-operation fee you are willing to pay for the fee-bump transaction.
A fee-bump transaction has an effective number of operations equal to one plus the number of operations in the inner transaction. Therefore, the minimum fee for a fee-bump transaction is one base fee more than the minimum fee for the inner transaction, and the fee rate is normalized by one plus the number of operations in the inner transaction. For more info on fee rate calculation, see Fees.
You can use a fee-bump transaction to increase the fee on a transaction originating from your own account — something you may want to consider if a transaction is failing to make the ledger due to surge pricing. However, there is a condition: if you submit two distinct transactions with the same source account and sequence number, and the second transaction is a fee-bump transaction, the second transaction will be included in the transaction queue in place of the first transaction if and only if the fee bid of the second transaction is at least 10x the fee bid of the first transaction. Though that limit may seem somewhat arbitrary, it was a deliberate design decision to limit DOS attacks without introducing too much complexity to the protocol.
Once a fee-bump transaction is ready to be signed, it's wrapped in a transaction envelope, which contains the fee-bump transaction as well as the signature of the fee account specified in the fee-bump transaction.
Ultimately, transaction envelopes are passed around the network and are included in transaction sets, as opposed to raw transaction objects.
A fee-bump transaction goes through a series of checks in its lifecycle to determine validity. For a fee-bump transaction to be valid, the following conditions must be met:
- Fee Account — The fee account for the fee-bump transaction must exist on the ledger.
- Fee — The fee must be greater than or equal to the network minimum fee for the number of operations in the inner transaction, +1 for the fee bump. It must also be greater than or equal to the fee specfied in the inner transaction. Additionally, if the fee-bump transaction is taking advantage of the replace-by-fee feature, in which a transaction envelope in the transaction queue is replaced by a fee-bump transaction envelope with the same sequence number and source account, the fee must be at least 10x higher.
- Fee Account Signature — The fee-bump transaction envelope must contain a valid signaure for the fee account. Additionally, the weight of that signature must meet the low threshold for the fee account, and the appropriate network passphrase must be part of the transaction hash signed by the fee account. See Network Passphrases for more.
- Fee Account Balance — The fee account must have a sufficient XBN balance to cover the fee.
- Inner Transaction — For a fee-bump to succeed, the inner transaction must be valid, which means that it must meet the requirements described in the Validity of a Transaction section. If validation of the inner transaction is successful, then the result is
FEE_BUMP_INNER_SUCCESS, and the validation results from the validation of the inner transaction appear in the inner result. If the inner transaction is invalid, the result isFEE_BUMP_INNER_FAILED, and the fee-bump transaction is invalid because the inner transaction is invalid.
The sole purpose of a fee-bump transaction is to get an inner transaction included in a transaction set. Since the fee-bump transaction has no side-effects other than paying a fee — and at the time the fee is paid the outer transaction must have been valid (otherwise nodes would not have voted for it) — there is no reason to check the validity of the fee-bump transaction at apply time. Therefore, the sequence number of the inner transaction is always consumed at apply time. The inner transaction, however, will still have its validity checked at apply time.
Every fee-bump transaction result contains a complete inner transaction result. This inner-transaction result is exactly what would have been produced had there been no fee-bump transaction, except that the inner fee will always be 0.
A fee-bump transaction is essentially a wrapper around a transaction that has been bundled with requisite signatures into a transaction envelope. Therefore, before creating a fee-bump transaction, you must first create a regular transaction and transacrtion envelope. For more on regular transaction creation and a summary of the lifecycle of a transaction, see Transactions.
Fee-bump transactions share result codes with regular transactions. They're listed in a table below. Error reference for operations can be found in List of Operations doc.
Result | Code | Description |
FEE_BUMP_INNNER_SUCCESS | 1 | The inner transaction contained in the fee bump succeeded. |
SUCCESS | 0 | All operations contained in the transaction succeeded. |
FAILED | -1 | |
TOO_EARLY | -2 | Ledger closeTime before minTime value in the transaction. |
TOO_LATE | -3 | Ledger closeTime after maxTime value in the transaction. |
MISSING_OPERATION | -4 | No operation was specified. |
BAD_SEQ | -5 | Sequence number does not match source account. |
BAD_AUTH | -6 | Too few valid signatures / wrong network. |
INSUFFICIENT_BALANCE | -7 | |
NO_ACCOUNT | -8 | Source account not found. |
INSUFFICIENT_FEE | -9 | |
BAD_AUTH_EXTRA | -10 | Unused signatures attached to transaction. |
INTERNAL_ERROR | -11 | An unknown error occured. |
NOT_SUPPORTED | -12 | The transaction type is not supported |
FEE_BUMP_INNER_FAILED | -13 |
Last modified 2yr ago