LogoLogo
  • Welcome
  • Where to Start
    • Introduction
    • list of Operations
    • Bantu Stack
  • Tutorials
    • Create Account
    • Send and Receive Payments
    • Follow Received Payments
    • Securing Web-based Projects
  • Issue Assets
    • Overview
    • Anatomy of an Asset
    • Issue an Asset
    • Publish Information About an Asset
    • Control Access to an Asset
  • Building Apps
    • Overview
    • Project Setup
    • Key Management Basics
    • Create a Basic Wallet
    • Make XBN Payments
    • Handle Custom Assets
  • Run a Core Node
    • index
    • running-node
    • network-upgrades
    • tier-1-orgs
    • installation
    • prerequisites
    • configuring
    • publishing history archives
    • commands
    • monitoring
  • Run API Server
    • prerequisites
    • quickstart
    • index
    • installing
    • monitoring
    • Running
    • configuring
  • Software and SDKs
    • index
  • Glossary
    • scp
    • Claimable Balance
    • XDR
    • Assets
    • BUDS
    • Inflation
    • Miscellaneous Core Objects
    • Testnet
    • Accounts
    • Network Passphrase
    • Ledger
    • Versioning
    • Sponsored Reserves
    • Operations
    • Decentralized Exchange
    • Fees
    • XBN Supply
    • Fee Bumps
    • Channels
    • Transactions
    • Minimum Balance
    • Multisig
  • Docs
    • Index
  • API
    • Introduction
      • Index
      • Response Format
      • Streaming
      • Rate Limiting
      • XDR
      • Pagination
        • Index
        • Page Arguments
    • Resources
      • Untitled
      • Overview
      • Ledgers
        • index
        • Object
        • Single
        • Transactions
        • Operations
        • Payments
        • Effects
        • List
      • Transactions
        • Index
        • Object
        • Single
        • Operations
        • Effects
        • List
      • Operations
        • Index
        • Object
          • Index
          • Create Account
          • Payment
          • Path Payment Strict Send
          • Path Payment Strict Receive
          • Sell Offer
          • Buy Offer
          • Passive Sell Offer
          • Set Options
          • Change Trust
          • Allow Trust
          • Account Merge
          • Manage Data
          • Bump Sequence
          • Create Claimable Balance
          • Claim Claimable Balance
          • Begin Sponsoring Future Reserves
          • End Sponsoring Future Reserves
          • Revoke Sponsorship
        • Single
        • Effects
        • List
        • List Payments
      • Effects
        • Index
        • Types
        • List
      • Accounts
        • Index
        • Object
        • Transactions
        • List
        • Single
        • Operations
        • Payments
        • Effects
        • Offers
        • Trades
        • Data
      • Offers
        • Index
        • Object
        • Single
        • List
      • Trades
        • Index
        • Object
        • List
      • Assets
        • Index
        • Object
        • List
      • Claimable Balances
        • Index
        • Object
        • Single
        • List
    • Aggregations
      • Index
      • Order Books
        • Index
        • object
        • Single
      • Paths
        • Index
        • Object
        • Strict Receive
        • Strict Send
      • Trade Aggregations
        • Index
        • Object
        • List
      • Fee Stats
        • Index
        • Object
        • Single
    • Errors
      • Index
      • Response
      • HTTP Status Codes
        • Index
        • Standard
        • Expansion Specific
          • Index
          • Transaction Failed
          • Transaction Malformed
          • Before History
          • Stale History
          • Timeout
      • Result Codes
        • Index
        • Transactions
        • Operations
        • Operation Specific
          • Index
          • Create Account
          • Payment
          • Path Payment Strict Receive
          • Path Payment Strict Send
          • Manage Sell Offer
          • Manage Buy Offer
          • Create Passive Sell Offer
          • Set Options
          • Change Trust
          • Allow Trust
          • Account Merge
          • Manage Data
          • Bump Sequence
Powered by GitBook
On this page
  • Fee-Bump Transaction Attributes
  • Existing Transaction Envelope
  • Fee Account
  • Fee
  • Fee-Bump Transaction Envelopes
  • Validity of a Fee-Bump Transaction
  • Application
  • Result Codes

Was this helpful?

  1. Glossary

Fee Bumps

PreviousXBN SupplyNextChannels

Last updated 4 years ago

Was this helpful?

A fee-bump transaction enables any account to pay the fee for an existing 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 , a fee-bump transaction contains a single .

Fee-Bump Transaction Attributes

Existing 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 wrapped with requisite signatures in a .

In addition to a transaction envelope, each fee-bump transaction has the following attributes:

Fee Account

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.

Fee

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 .

Replace-by-Fee

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.

Fee-Bump Transaction Envelopes

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.

Validity of a Fee-Bump Transaction

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 Account Balance — The fee account must have a sufficient XBN balance to cover the fee.

Application

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.

Result Codes

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

Fee — The fee must be greater than or equal to the 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 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 for more.

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 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 is FEE_BUMP_INNER_FAILED, and the fee-bump transaction is invalid because the inner transaction is invalid.

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 .

Fee-bump transactions share result codes with regular transactions. They're listed in a table below. Error reference for operations can be found in doc.

One of the operations failed (check for errors).

Fee would bring account below .

is too small.

The fee bump inner transaction failed. See for more info.

Network Passphrases
Transactions
List of Operations
network minimum fee
replace-by-fee
List of operations
minimum reserve
Fee
Fee Bumps
transaction
operations
transaction
Fees
transaction envelope
transaction envelope
Validity of a Transaction