Ledger

A ledger represents the state of the Bantu universe at a given point in time. It’s shared across all the nodes that make up the network, and contains the list of all accounts and balances, all orders on the distributed exchange, and any other data that persists.

Every Bantu Consensus Protocol (SCP) round, the network reaches consensus on which transaction set to apply to the last closed ledger; when the new set is applied, a new "last closed ledger" is defined.

Each ledger is cryptographically linked to a unique previous ledger, creating a historical ledger chain that goes back to the genesis ledger, which is the first ledger in the history of the network.

The sequence number of a ledger is defined recursively:

• The genesis ledger has sequence number 1

• The ledger directly following a ledger with sequence number n has sequence number n+1

Ledger header

Every ledger has a ledger header. This header has references to the actual data within the ledger as well as a reference to the previous ledger. References here are cryptographic hashes of the content being referenced — the hashes behave like pointers in typical data structures but with added security guarantees.

You can think of the historical ledger chain as a linked list of ledger headers:

[Genesis] <---- [LedgerHeader_1] <----- ... <---- [LedgerHeader_n]

Every ledger header has the following fields:

• Version: Protocol version of this ledger.

• Previous Ledger Hash: Hash of the previous ledger. Forms a chain of ledgers stretching back to the genesis ledger.

• SCP value: During consensus all the validating nodes in the network run SCP and come to an agreement about a particular value, which is a transaction set they will apply to a ledger. This value is stored here and in the next three fields (transaction set hash, close time, and upgrades).

  • Transaction set hash: Hash of the transaction set that was applied to the previous ledger.

  • Close time: When the network closed this ledger. UNIX timestamp.

  • Upgrades: How the network adjusts overall values like the base fee and agrees to network-wide changes like switching to a new protocol version. This field is usually empty. When there is a network-wide upgrade in the works, the SDF will inform and help coordinate participants using the #validators channel on Keybase. So if you run a validator, it’s important to join and monitor that channel. For more info, see versioning.

• Transaction set result hash: Hash of the results of applying the transaction set. This data is not, strictly speaking, necessary for validating the results of the transactions. However, it makes it easier for entities to validate the result of a given transaction without having to apply the transaction set to the previous ledger.

• Bucket list hash: Hash of all the objects in this ledger. The data structure that contains all the objects is called the bucket list.

• Ledger sequence: The sequence number of this ledger.

• Total coins: Total number of lumens in existence.

• Fee pool: Number of lumens that have been paid in fees. This number will be added to the inflation pool and reset to 0 the next time inflation runs. Note this is denominated in lumens, even though a transaction’s fee field is in stroops.

• Inflation sequence: Number of times inflation has been run.

• ID pool: The last used global ID. These IDs are used for generating objects.

• Maximum Number of Transactions: The maximum number of operations validators have agreed to process in a given ledger. If more transactions are submitted than this number, the network will enter into surge pricing mode, which uses a VCG auction to decide which to include in a ledger. For more info, see fees and surge pricing

• Base fee: The fee the network charges per operation in a transaction. This field is in stroops, which are 1/10,000,000th of a lumen.

• Base reserve: The reserve the network uses when calculating an account's minimum balance.

• Skip list: Hashes of ledgers in the past. Allows you to jump back in time in the ledger chain without walking back ledger by ledger. There are 4 ledger hashes stored in the skip list. Each slot contains the oldest ledger that is mod of either 50 5000 50000 or 500000 depending on index skipList[0] mod(50), skipList[1] mod(5000), etc.

Ledger Entries

The ledger is a collection of entries. Currently there are 4 types of ledger entries. They're specified in src/xdr/Stellar-ledger-entries.x.

Account entry

This entry represents an account. In Bantu, everything is built around accounts: transactions are performed by accounts, and accounts control the access rights to balances.

Other entries are add-ons, owned by a main account entry. With every new entry attached to the account, the minimum balance in XLM goes up for the account. For details, the docs on minimum balance.

Trustline entry

Trustlines are lines of credit the account has given a particular issuer in a specific asset.

Trustline entries define the rules around the use of this currency. Rules can be defined by the user — who can set a maximum balance limit to limit risk — or by the issuer — who can set a flag to control access to the asset.

Offer entry

Offers are entries that an account creates in the orderbook. They are a way to automate simple trading inside the Bantu network. For more on offers, refer to the distributed exchange documentation.

Data entry

Data entries are key/value pairs attached to an account. They allow account controllers to attach arbitrary data to their account, and provide a flexible extension point to add application specific data to the ledger.