Skip to main content

Ledger Entries

Data is stored on the ledger as ledger entries, akin to key-value stores. Each key is a LedgerKey entry defined in protocol XDR, with values as LedgerEntry instances. Keys define which object we reference, while entries contain the data stored at that key in protocol XDR.

Because LedgerEntries are a full record of ledger data, they include the identifying key. These fungible key identifiers and fields lower excess variables, using the same subset of XDR structure. There are 10 different forms a ledger key can take:

Account​

The AccountEntry holistically defines a Stellar account, including its balance, sequence number, thresholds, signers, and flags. See Accounts section.

  • Key: Identified by AccountID
  • Entry: Full account record including balance, sequence number, thresholds, flags, home domain, and list of signers. Tracks subentries that drive the minimum balance requirement.

Trustline​

The TrustLineEntry defines a balance line to a non-native asset issued on the network. Created and updated via changeTrustOp.

  • Key: (AccountID, asset)
  • Entry: Trustline state for a non-native asset. Stores the asset balance, limit, authorization flags, and trading liability counters.

Offer​

The OfferEntry represents an offer made on the SDEX orderbook. See Liquidity on Stellar DEX section.

  • Key: (sellerID, offerID)
  • Entry: A single offer on the DEX. Contains the selling and buying assets, amount, price, and passive flags.

Account Data​

A DataEntry stores key-value data entries attached to an account. Used through the manageDataOp.

  • Key: (accountID, dataName)
  • Entry: Arbitrary key-value pair (DataValue) attached to an account.

Claimable Balance​

The ClaimableBalanceEntry tracks a balance that may or may not actively be claimable. See Claimable Balances guide.

  • Key: balanceID
  • Entry: Tracks the asset, amount, claimants, predicates, and optional flags.

Liquidity Pool​

The LiquidityPoolEntry defines the configuration of a constant-product liquidity pool between two assets. See Liquidity on Stellar section.

  • Key: liquidityPoolID
  • Entry: Holds pool parameters (two assets, fee rate), reserves, total pool shares, and a pool's trustline count (to prevent entry scanning).

Contract Data​

ContractDataEntry stores a piece of data under a contract-defined key. See Persisting Contract Data section.

  • Key: (contract, key, durability)
  • Entry: Stores the SCVal value associated with that key under the contract. Used for Soroban data storage alongside keys.

Contract Code​

The ContractCodeEntry contains the Wasm bytecode of a Soroban contract. See Smart Contracts Overview page.

  • Key: hash of the Wasm module.
  • Entry: Contains the Wasm bytecode and associated cost inputs to deploy or invoke contracts. Fee metadata takes into account component factors like number of instructions, functions, and variables.

Config Setting​

The ConfigSettingEntry holds governed network configuration values for over a dozen rules. See Soroban Settings section.

  • Key: configSettingID (index of setting in list)
  • Entry: Active value of a network-level parameter (e.g., protocol limits, compute fees, state archival). The whole validator quorum set has to agree on these values.

TTL​

The TTLEntry defines the time-to-live of an associated contract data or code entry.

  • Key: keyHash (hash of associated LedgerKey).
  • Entry: Defines the expiration ledger sequence (liveUntilLedgerSeq) for temporary objects such as contract data or code.

Working with ledger entries​

Most products only need to reason about a subset of ledger entries—for example, accounts, trustlines, and liquidity pools cover the majority of asset and trading use cases. Once you understand how to build and parse a few representative keys and entries, you can extrapolate the same patterns to the remaining entry types.

Ledger entries are always mutated through transactions: operations either create, update, or delete these records as part of applying a transaction set. Use getLedgerEntries when you need to fetch the raw on-ledger representation for debugging or cross-checking derived data.