diff --git a/docs/build/smart-contracts/example-contracts/storage.mdx b/docs/build/smart-contracts/example-contracts/storage.mdx index 588aa3fd05..ab2f25863f 100644 --- a/docs/build/smart-contracts/example-contracts/storage.mdx +++ b/docs/build/smart-contracts/example-contracts/storage.mdx @@ -136,7 +136,7 @@ env.storage().instance().extend_ttl(50, 100); All contract data has a Time To Live (TTL), measured in ledgers, that must be periodically extended. If an entry's TTL is not periodically extended, the entry will eventually become "archived." You can learn more about this in the [State Archival](../../../learn/fundamentals/contract-development/storage/state-archival.mdx) document. -For now, it's worth knowing that there are three kinds of storage: `Persistent`, `Temporary`, and `Instance`. This contract only uses `Instance` storage: `env.storage().instance()`. Every time the counter is incremented, this storage's TTL gets extended by 100 [ledgers](../../../learn/fundamentals/stellar-data-structures/ledgers.mdx), or about 500 seconds. +For now, it's worth knowing that there are three kinds of storage: `Persistent`, `Temporary`, and `Instance`. This contract only uses `Instance` storage: `env.storage().instance()`. Every time the counter is incremented, this storage's TTL gets extended by 100 [ledgers](../../../learn/fundamentals/stellar-data-structures/ledgers/README.mdx), or about 500 seconds. ## Tests diff --git a/docs/build/smart-contracts/getting-started/storing-data.mdx b/docs/build/smart-contracts/getting-started/storing-data.mdx index 84ec5f9fc0..f75bd782da 100644 --- a/docs/build/smart-contracts/getting-started/storing-data.mdx +++ b/docs/build/smart-contracts/getting-started/storing-data.mdx @@ -122,7 +122,7 @@ env.storage().instance().extend_ttl(100, 100); All contract data has a Time To Live (TTL), measured in ledgers, that must be periodically extended. If an entry's TTL is not periodically extended, the entry will eventually become "archived." You can learn more about this in the [State Archival](../../../learn/fundamentals/contract-development/storage/state-archival.mdx) document. -For now, it's worth knowing that there are three kinds of storage: `Persistent`, `Temporary`, and `Instance`. This contract only uses `Instance` storage: `env.storage().instance()`. Every time the counter is incremented, this storage's TTL gets extended by 100 [ledgers](../../../learn/fundamentals/stellar-data-structures/ledgers.mdx), or about 500 seconds. +For now, it's worth knowing that there are three kinds of storage: `Persistent`, `Temporary`, and `Instance`. This contract only uses `Instance` storage: `env.storage().instance()`. Every time the counter is incremented, this storage's TTL gets extended by 100 [ledgers](../../../learn/fundamentals/stellar-data-structures/ledgers/README.mdx), or about 500 seconds. ### Build the contract diff --git a/docs/data/analytics/hubble/analyst-guide/history-vs-state-tables.mdx b/docs/data/analytics/hubble/analyst-guide/history-vs-state-tables.mdx index 0caea9cc98..539558bc55 100644 --- a/docs/data/analytics/hubble/analyst-guide/history-vs-state-tables.mdx +++ b/docs/data/analytics/hubble/analyst-guide/history-vs-state-tables.mdx @@ -64,7 +64,7 @@ As seen in the table, each row shows the distinct operation with its unique `id` - [History Assets](../data-catalog/data-dictionary/history-assets.mdx) - [History Contract Events](../data-catalog/data-dictionary/history-contract-events.mdx) - [History Effects](../data-catalog/data-dictionary/history-effects.mdx) -- [History Ledgers](../data-catalog/data-dictionary/history-ledgers.mdx) +- [History Ledgers](../data-catalog/data-dictionary/history.mdx) - [History Operations](../data-catalog/data-dictionary/history-operations.mdx) - [History Trades](../data-catalog/data-dictionary/history-trades.mdx) - [History Transactions](../data-catalog/data-dictionary/history-transactions.mdx) diff --git a/docs/data/apis/rpc/api-reference/methods/README.mdx b/docs/data/apis/rpc/api-reference/methods/README.mdx index 3d8a016cad..745f5c17a9 100644 --- a/docs/data/apis/rpc/api-reference/methods/README.mdx +++ b/docs/data/apis/rpc/api-reference/methods/README.mdx @@ -12,7 +12,7 @@ All you need to know about available RPC methods, parameters and responses, and Don't know which endpoint you need to get what you want? A lot of the returned fields are deeply-nested [XDR structures](../../../../../learn/fundamentals/data-format/xdr.mdx#more-about-xdr), so it can be hard to figure out what kind of information is available in each of these. Here's a bit of a dive into what the "workhorse" endpoints provide, in decreasing order of granularity: - [`getLedgers`](./getLedgers.mdx) operates at the block level, providing you with the full, complete details of what occurred during application of that ledger (known as "ledger metadata", defined in the protocol by the [`LedgerCloseMeta`](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L539) union, specifically the `V1` iteration). Each of the subsequent endpoints is just a microscope into a subset of the data available provided by this endpoint. Metadata includes things like: - - Details for recreating the blockchain's state (see [Ledger Headers](../../../../../learn/fundamentals/stellar-data-structures/ledgers.mdx#ledger-headers) for more). + - Details for recreating the blockchain's state (see [Ledger Headers](../../../../../learn/fundamentals/stellar-data-structures/ledgers/headers.mdx) for more). - The consensus information that led to the block closing (see [Stellar Consensus Protocol](../../../../../learn/fundamentals/stellar-consensus-protocol.mdx)). - The set of transactions, their respective operations, and the results of applying those transactions in this block (see [Transactions](../../../../../learn/fundamentals/transactions/operations-and-transactions.mdx)). - [`getTransaction(s)`](./getTransactions.mdx) operates across a span of ledgers or on a single transaction hash depending on the variant. The structured data here includes details such as: diff --git a/docs/data/apis/rpc/api-reference/methods/getLedgerEntries.mdx b/docs/data/apis/rpc/api-reference/methods/getLedgerEntries.mdx index 58018d4324..0fc257941b 100644 --- a/docs/data/apis/rpc/api-reference/methods/getLedgerEntries.mdx +++ b/docs/data/apis/rpc/api-reference/methods/getLedgerEntries.mdx @@ -10,28 +10,15 @@ import rpcSpec from "@site/static/stellar-rpc.openrpc.json"; method={rpcSpec.methods.filter((meth) => meth.name === "getLedgerEntries")[0]} /> -# Building ledger keys +## Constructing Calls -The Stellar ledger is, on some level, essentially a key-value store. The keys are instances of [`LedgerKey`](https://github.com/stellar/stellar-xdr/blob/v25.0/Stellar-ledger-entries.x#L588) and the values are instances of [`LedgerEntry`](https://github.com/stellar/stellar-xdr/blob/v25.0/Stellar-ledger-entries.x#L548). An interesting product of the store's internal design is that the key is a _subset_ of the entry: we'll see more of this later. +The `getLedgerEntries` method returns the "values" (or "entries") for a given set of "keys." Ledger keys come in a lot of forms, and we'll go over the commonly used ones on this page alongside tutorials on how to build and use them. -The `getLedgerEntries` method returns the "values" (or "entries") for a given set of "keys". Ledger keys come in a lot of forms, and we'll go over the commonly used ones on this page alongside tutorials on how to build and use them. +The source of truth should always be the XDR defined in the protocol. `LedgerKey`s are a union type defined in [Stellar-ledger-entries.x](https://github.com/stellar/stellar-xdr/blob/v25.0/Stellar-ledger-entries.x#L588). -## Types of `LedgerKey`s +An interesting product of the store's internal design is that the key is a _subset_ of the entry: we'll see more of this later. -The source of truth should always be the XDR defined in the protocol. `LedgerKey`s are a union type defined in [Stellar-ledger-entries.x](https://github.com/stellar/stellar-xdr/blob/v25.0/Stellar-ledger-entries.x#L588). There are 10 different forms a ledger key can take: - -1. **Account:** holistically defines a Stellar account, including its balance, signers, etc. (see [Accounts](../../../../../learn/fundamentals/stellar-data-structures/accounts.mdx)) -2. **Trustline:** defines a balance line to a non-native asset issued on the network (see [`changeTrustOp`](../../../../../learn/fundamentals/transactions/list-of-operations.mdx#change-trust)) -3. **Offer:** defines an offer made on the Stellar DEX (see [Liquidity on Stellar](../../../../../learn/fundamentals/liquidity-on-stellar-sdex-liquidity-pools.mdx)) -4. **Account Data:** defines key-value data entries attached to an account (see [`manageDataOp`](../../../../../learn/fundamentals/transactions/list-of-operations.mdx#manage-data)) -5. **Claimable Balance:** defines a balance that may or may not actively be claimable (see [Claimable Balances](../../../../../build/guides/transactions/claimable-balances.mdx)) -6. **Liquidity Pool:** defines the configuration of a native constant liquidity pool between two assets (see [Liquidity on Stellar](../../../../../learn/fundamentals/liquidity-on-stellar-sdex-liquidity-pools.mdx)) -7. **Contract Data:** defines a piece of data being stored in a contract under a key -8. **Contract Code:** defines the Wasm bytecode of a contract -9. **Config Setting:** defines the currently active network configuration -10. **TTL:** defines the time-to-live of an associated contract data or code entry - -We're going to focus on a subset of these for maximum value, but once you understand how to build and parse some keys and entries, you can extrapolate to all of them. +For more on the types of `LedgerKey` entries and their purposes, see [Ledger Entries](../../../../../learn/fundamentals/stellar-data-structures/ledgers/entries.mdx). ### Accounts diff --git a/docs/data/indexers/build-your-own/ingest-sdk/README.mdx b/docs/data/indexers/build-your-own/ingest-sdk/README.mdx index d1486e0f22..a0207f0d35 100644 --- a/docs/data/indexers/build-your-own/ingest-sdk/README.mdx +++ b/docs/data/indexers/build-your-own/ingest-sdk/README.mdx @@ -9,13 +9,13 @@ The SDK is composed of several published Golang packages under `github.com/stell ## Why use the Ingest SDK? -Applications can leverage the SDK to rapidly develop ingestion pipelines capable of acquiring real-time or historical Stellar network data and deriving custom data models. The SDK enables applications to traverse the hierarchal data structures of the network: [history archives](../../../../validators/admin-guide/environment-preparation.mdx#history-archives), [ledgers](../../../../learn/fundamentals/stellar-data-structures/ledgers.mdx), transactions, operations, ledger state changes, and events. +Applications can leverage the SDK to rapidly develop ingestion pipelines capable of acquiring real-time or historical Stellar network data and deriving custom data models. The SDK enables applications to traverse the hierarchal data structures of the network: [history archives](../../../../validators/admin-guide/environment-preparation.mdx#history-archives), [ledgers](../../../../learn/fundamentals/stellar-data-structures/ledgers/README.mdx), transactions, operations, ledger state changes, and events. Use the SDK for an intuitive, compile-time, type-safe developer experience to work with the main types of network data: ### Ledger Entries -Obtain the final state of [ledger entries](../../../../learn/fundamentals/stellar-data-structures/ledgers.mdx) on the network at close of any recent or historically aged checkpoint ledger sequence. A Checkpoint ledger occurs once every 64 ledgers, during which the network will publish this data to [history archives](../../../../validators/admin-guide/environment-preparation.mdx#history-archives) in the format of compressed files which contain lists of `BucketEntry`, wherein each contains one `LedgerEntry` and the `LedgerKey`. +Obtain the final state of [ledger entries](../../../../learn/fundamentals/stellar-data-structures/ledgers/entries.mdx) on the network at close of any recent or historically aged checkpoint ledger sequence. A Checkpoint ledger occurs once every 64 ledgers, during which the network will publish this data to [history archives](../../../../validators/admin-guide/environment-preparation.mdx#history-archives) in the format of compressed files which contain lists of `BucketEntry`, wherein each contains one `LedgerEntry` and the `LedgerKey`. Ledger entries are cryptographically signed as part of each ledger and therefore represent the trusted, cumulative state at a point in time for [assets](../../../../learn/fundamentals/stellar-data-structures/assets.mdx) related to an [account](../../../../learn/fundamentals/stellar-data-structures/accounts.mdx) or [contract](../../../../learn/fundamentals/contract-development/storage/persisting-data.mdx). Examples of asset types: diff --git a/docs/learn/fundamentals/stellar-data-structures/ledgers.mdx b/docs/learn/fundamentals/stellar-data-structures/ledgers.mdx deleted file mode 100644 index 9673cefbf0..0000000000 --- a/docs/learn/fundamentals/stellar-data-structures/ledgers.mdx +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: "Ledgers Store Accounts, Balances, Orders, Smart Contract Data & More" -sidebar_position: 10 -sidebar_label: Ledgers -description: "A ledger captures the state of the Stellar network at a point in time, storing accounts, balances, orders, smart contract data, and other persistent information." ---- - -# Ledgers - -A ledger represents the state of the Stellar network at a point in time. It is shared across all Core nodes in the network and contains the list of accounts and balances, orders on the distributed exchange, smart contract data, and any other persisting data. - -:::note - -Blockchains typically refer to the **ledger** as the entire record of all transactions on the blockchain and **blocks** as individual units of data that contain a collection of transactions. In Stellar, "ledger" can refer to both. - -::: - -In every Stellar Consensus Protocol round, the network reaches consensus on which transaction set to apply to the last closed ledger, and when the new set is applied, a new “last closed ledger” is defined. Each ledger is cryptographically linked to the unique previous ledger, creating a historical chain that goes back to the genesis ledger. - -Data is stored on the ledger as ledger entries. Possible ledger entries include: - -- [Accounts](./accounts.mdx) -- [Claimable balances](../../../build/guides/transactions/claimable-balances.mdx) -- [Liquidity pools](../../fundamentals/liquidity-on-stellar-sdex-liquidity-pools.mdx) -- [Contract data](../../fundamentals/contract-development/storage/persisting-data.mdx#ledger-entries) - -## Ledger headers - -Every ledger has a header that references the data in that ledger and the previous ledger. These references are cryptographic hashes of the content which behave like pointers in typical data structures but with added security guarantees. Think of a historical ledger chain as a linked list of ledger headers. Time flows forward from left to right, hashes point backwards in time, from right to left. Each hash in the chain links a ledger to its previous ledger, which authenticates the entire history of ledgers in its past: - -```mermaid -flowchart RL - subgraph genesis["Genesis"] - direction LR - prev1["Prev: none"] - state1["Genesis state"] - end - - subgraph block2["Ledger 2"] - prev2["Prev: hash(Genesis)"] - state2["Ledger 2
transactions
and state"] - end - - subgraph block3["Ledger 3"] - prev3["Prev: hash(Ledger 2)"] - state3["Ledger 3
transactions
and state"] - end - - subgraph dotdot["..."] - end - - subgraph blockn["Ledger N"] - prevn["Prev: hash(Ledger N-1)"] - staten["Ledger N
transactions
and state"] - end - - - genesis ~~~ block2 ~~~ block3 ~~~ dotdot ~~~ blockn - prev2 --> genesis - prev3 --> block2 - dotdot --> block3 - prevn --> dotdot - -``` - -The genesis ledger has a sequence number of 1. The ledger directly following a ledger with sequence number `N` has a sequence number of `N+1`. Ledger `N+1` contains a hash of ledger `N` in its previous ledger field. - -## Ledger header fields - -### Version - -The protocol version of this ledger. - -### Previous ledger hash - -Hash of the previous ledger. - -### SCP value - -During consensus, all the validating nodes in the network run SCP and agree on a particular value, which is a transaction set they will apply to a ledger. This value is stored here and in the following three fields (transaction set hash, close time, and upgrades). - -### Transaction set hash - -Hash of the transaction set applied to the previous ledger. - -### Close time - -The close time is a UNIX timestamp indicating when the ledger closes. Its accuracy depends on the system clock of the validator proposing the block. Consequently, SCP may confirm a close time that lags a few seconds behind or up to 60 seconds ahead. It's strictly monotonic – guaranteed to be greater than the close time of an earlier ledger. - -### 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, the SDF will inform and help coordinate participants using the #validators channel on the Dev Discord and the Stellar Validators Google Group. - -### Transaction set result hash - -Hash of the results of applying the transaction set. This data is not 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. 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. Note: the inflation operation was deprecated when validators voted to upgrade the network to Protocol 12 on 10/28/2019. Therefore, inflation no longer runs, so this sequence number no longer changes. - -### 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. For more about surge pricing and fee strategies, see our [Fees section](../../fundamentals/fees-resource-limits-metering.mdx). - -### Base fee - -The fee the network charges per operation in a transaction. Calculated in stroops. See the [Fees section](../../fundamentals/fees-resource-limits-metering.mdx) for more information. - -### Base reserve - -The reserve the network uses when calculating an account’s minimum balance. - -### Skip list - -Hashes of ledgers in the past. Intended to accelerate access to past ledgers without walking back ledger by ledger. Currently unused. diff --git a/docs/learn/fundamentals/stellar-data-structures/ledgers/README.mdx b/docs/learn/fundamentals/stellar-data-structures/ledgers/README.mdx new file mode 100644 index 0000000000..e49d6b5947 --- /dev/null +++ b/docs/learn/fundamentals/stellar-data-structures/ledgers/README.mdx @@ -0,0 +1,23 @@ +--- +title: "Ledgers Store Accounts, Balances, Orders, Smart Contract Data & More" +sidebar_position: 10 +sidebar_label: Ledgers +hide_table_of_contents: false +description: "A ledger captures the state of the Stellar network at a point in time, storing accounts, balances, orders, smart contract data, and other persistent information." +--- + +import DocCardList from "@theme/DocCardList"; + +# Ledgers + +A ledger represents the state of the Stellar network at a point in time. It is shared across all Core nodes in the network and contains the list of accounts and balances, orders on the distributed exchange, smart contract data, and any other persisting data. + +:::note + +Blockchains typically refer to the **ledger** as the entire record of all transactions on the blockchain and **blocks** as individual units of data that contain a collection of transactions. In Stellar, "ledger" can refer to both. + +::: + +During each [Stellar Consensus Protocol](../../stellar-consensus-protocol.mdx) round, validators agree on a transaction set to apply to the last closed ledger. When that set is applied, a new last closed ledger is defined. Each ledger is cryptographically linked to the unique previous ledger, creating a historical chain that goes back to the genesis ledger. + + diff --git a/docs/learn/fundamentals/stellar-data-structures/ledgers/_category_.json b/docs/learn/fundamentals/stellar-data-structures/ledgers/_category_.json new file mode 100644 index 0000000000..a37565f28d --- /dev/null +++ b/docs/learn/fundamentals/stellar-data-structures/ledgers/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Ledgers", + "position": 10, + "link": { + "type": "doc", + "id": "learn/fundamentals/stellar-data-structures/ledgers/README" + }, + "description": "Learn how Stellar ledgers snapshot the entire network state, from accounts and balances to DEX orders and smart-contract data." +} diff --git a/docs/learn/fundamentals/stellar-data-structures/ledgers/entries.mdx b/docs/learn/fundamentals/stellar-data-structures/ledgers/entries.mdx new file mode 100644 index 0000000000..d8f7185642 --- /dev/null +++ b/docs/learn/fundamentals/stellar-data-structures/ledgers/entries.mdx @@ -0,0 +1,90 @@ +--- +title: "Ledger Entries" +sidebar_label: Entries +sidebar_position: 20 +description: "Ledger entries are the durable data structures that make up the Stellar network state." +--- + +# Ledger Entries + +Data is stored on the ledger as ledger entries, akin to key-value stores. Each key is a `LedgerKey` instance defined in [protocol XDR](https://github.com/stellar/stellar-xdr/blob/cff714a5ebaaaf2dac343b3546c2df73f0b7a36e/Stellar-ledger-entries.x#L588). Keys state which object we reference, pointing to `LedgerEntry` values defined in [protocol XDR](https://github.com/stellar/stellar-xdr/blob/v26.0/Stellar-ledger-entries.x#L548). Thus entry instances contain the data stored at that key. + +Ledger entries include the identifying key, since they're a full record of ledger data. These fungible key identifiers and fields lower excess variables, using the same subset of XDR structure. + +## 10 Ledger Key Cases + +### Account + +The `AccountEntry` holistically defines a Stellar account, including its balance, sequence number, thresholds, signers, and flags. See [Accounts](../accounts.mdx) section. + +- **Key:** Identified by `AccountID` +- **Entry:** Full account record including balance, sequence number, thresholds, flags, home domain, and list of signers. Tracks [subentries](../accounts.mdx#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`](../../transactions/list-of-operations.mdx#change-trust). + +- **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 order book. See [Liquidity on Stellar](../../liquidity-on-stellar-sdex-liquidity-pools.mdx#orderbook) DEX section. + +- **Key:** `(sellerID, offerID)` +- **Entry:** A single offer on the DEX. Contains the selling and buying assets, amount, price, and [passive](../../liquidity-on-stellar-sdex-liquidity-pools.mdx#passive-offer) flags. + +### Account Data + +A `DataEntry` stores key-value data entries attached to an account. Used through the [`manageDataOp`](../../transactions/list-of-operations.mdx#manage-data). + +- **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](../../../../build/guides/transactions/claimable-balances.mdx) guide. + +- **Key:** `balanceID` +- **Entry:** Tracks the asset, amount, claimants, [predicates](../../../../build/guides/transactions/claimable-balances.mdx#other-parameters), and optional flags. + +### Liquidity Pool + +The `LiquidityPoolEntry` defines the configuration of a constant-product liquidity pool between two assets. See [Liquidity on Stellar](../../liquidity-on-stellar-sdex-liquidity-pools.mdx#liquidity-pools) 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](../../contract-development/storage/persisting-data.mdx#ledger-entries) 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](../../../../build/smart-contracts/overview.mdx) page. + +- **Key:** `hash` of the Wasm module. +- **Entry:** Contains the Wasm bytecode and associated cost inputs to deploy or invoke contracts. [Fee metadata](../../fees-resource-limits-metering.mdx#resource-fee) 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](../../../../validators/admin-guide/soroban-settings.mdx) section. + +- **Key:** `configSettingID` (index of setting [in list](https://github.com/stellar/stellar-xdr/blob/4b7a2ef7931ab2ca2499be68d849f38190b443ca/Stellar-contract-config-setting.x#L319-L338)) +- **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`](../../../../data/apis/rpc/api-reference/methods/getLedgerEntries.mdx) when you need to fetch the raw on-ledger representation for debugging or cross-checking derived data. diff --git a/docs/learn/fundamentals/stellar-data-structures/ledgers/headers.mdx b/docs/learn/fundamentals/stellar-data-structures/ledgers/headers.mdx new file mode 100644 index 0000000000..2adbced62b --- /dev/null +++ b/docs/learn/fundamentals/stellar-data-structures/ledgers/headers.mdx @@ -0,0 +1,119 @@ +--- +title: "Ledger Headers" +sidebar_label: Headers +sidebar_position: 10 +description: "Ledger headers capture the metadata that links each Stellar ledger to its history and summarizes recent transactions." +--- + +# Ledger Headers + +Every ledger has a header that references the data in that ledger and the previous ledger. These references are cryptographic hashes of the content which behave like pointers in typical data structures but with added security guarantees. Think of a historical ledger chain as a linked list of ledger headers. Time flows forward from left to right, hashes point backwards in time, from right to left. Each hash in the chain links a ledger to its previous ledger, which authenticates the entire history of ledgers in its past: + +```mermaid +flowchart RL + subgraph genesis["Genesis"] + direction LR + prev1["Prev: none"] + state1["Genesis state"] + end + + subgraph block2["Ledger 2"] + prev2["Prev: hash(Genesis)"] + state2["Ledger 2\\ntransactions\\nand state"] + end + + subgraph block3["Ledger 3"] + prev3["Prev: hash(Ledger 2)"] + state3["Ledger 3\\ntransactions\\nand state"] + end + + subgraph dotdot["..."] + end + + subgraph blockN["Ledger N"] + prevN["Prev: hash(Ledger N-1)"] + stateN["Ledger N\\ntransactions\\nand state"] + end + + genesis ~~~ block2 ~~~ block3 ~~~ dotdot ~~~ blockN + prev2 --> genesis + prev3 --> block2 + dotdot --> block3 + prevN --> dotdot +``` + +The genesis ledger has a sequence number of 1. The ledger directly following a ledger with sequence number `N` has a sequence number of `N + 1`. Ledger `N + 1` contains a hash of ledger `N` in its previous ledger field. + +## Consensus Fields + +### Version + +The protocol version of this ledger. + +### Previous Ledger Hash + +Hash of the previous ledger. + +### SCP Value + +During consensus, all the validating nodes in the network run SCP and agree on a particular value, which is a transaction set they will apply to a ledger. This value is stored here and in the following three fields (transaction set hash, close time, and upgrades). + +### Transaction Set Hash + +Hash of the transaction set applied to the previous ledger. + +### Transaction Set Result Hash + +Hash of the results of applying the transaction set. This data is not 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. + +### Close Time + +The close time is a UNIX timestamp indicating when the ledger closes. Its accuracy depends on the system clock of the validator proposing the block. Consequently, SCP may confirm a close time that lags a few seconds behind or up to 60 seconds ahead. It is strictly monotonic - guaranteed to be greater than the close time of an earlier ledger. + +### 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, the SDF will inform and help coordinate participants using the #validators channel on the Dev Discord and the Stellar Validators Google Group. + +### 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. 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. The inflation operation was stopped when validators voted to upgrade the network to Protocol 12 on 28 Oct 2019. This number does not change without inflation. + +### ID Pool + +The last used global ID. These IDs are used for generating objects. The number is a single monotonically increasing counter which corresponds to unique identifiers like OfferIDs or ClaimableBalanceIDs. + +### 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 surge pricing mode. For more about surge pricing and fee strategies, see the [Fees section](../../fees-resource-limits-metering.mdx). + +### Base Fee + +The fee the network charges per operation in a transaction. Calculated in stroops. See the [Fees section](../../fees-resource-limits-metering.mdx) for more information. + +### Base Reserve + +The reserve the network uses when calculating an account's minimum balance. + +### Skip List + +Hashes of ledgers in the past. Intended to accelerate access to past ledgers without walking back ledger by ledger. Currently unused. + +## Extension Flags + +A field that validators can flip through `LEDGER_UPGRADE_FLAGS`, directly changing header flags bitmasks. Unlike the config settings above, these are not durable ledger entries with keys and tunable parameters. This feature can be extended like all of the [Ledger Entries](./entries.mdx) for arbitrary future expansion of network functions that could require an "emergency switch." diff --git a/docs/learn/glossary.mdx b/docs/learn/glossary.mdx index 107a6dabc5..68c4be5914 100644 --- a/docs/learn/glossary.mdx +++ b/docs/learn/glossary.mdx @@ -171,7 +171,7 @@ An encrypted store or file that serves as a repository of private keys, certific A representation of the state of the Stellar universe at a given point in time, shared across all network nodes. -Learn more in the [Ledgers section](./fundamentals/stellar-data-structures/ledgers.mdx). +Learn more in the [Ledgers section](./fundamentals/stellar-data-structures/ledgers/README.mdx). ### LedgerKey diff --git a/docs/validators/README.mdx b/docs/validators/README.mdx index b2c709339b..aaee28f51f 100644 --- a/docs/validators/README.mdx +++ b/docs/validators/README.mdx @@ -7,7 +7,7 @@ sidebar_position: 10 # Validators Introduction -Stellar is a peer-to-peer network made up of nodes, which are computers that keep a common distributed [ledger](../learn/fundamentals/stellar-data-structures/ledgers.mdx), and that communicate to validate and add [transactions](../learn/fundamentals/transactions/operations-and-transactions.mdx) to it. Nodes use a program called Stellar Core — an implementation of the [Stellar Consensus Protocol](../learn/fundamentals/stellar-consensus-protocol.mdx) — to stay in sync as they work to agree on the validity of transaction sets and to apply them to the ledger. Generally, nodes reach consensus, apply a transaction set, and update the ledger every 3-5 seconds. +Stellar is a peer-to-peer network made up of nodes, which are computers that keep a common distributed [ledger](../learn/fundamentals/stellar-data-structures/ledgers/README.mdx), and that communicate to validate and add [transactions](../learn/fundamentals/transactions/operations-and-transactions.mdx) to it. Nodes use a program called Stellar Core — an implementation of the [Stellar Consensus Protocol](../learn/fundamentals/stellar-consensus-protocol.mdx) — to stay in sync as they work to agree on the validity of transaction sets and to apply them to the ledger. Generally, nodes reach consensus, apply a transaction set, and update the ledger every 3-5 seconds. This section of the docs explains how to run a validator node, which participates in consensus to validate transactions and determine network settings. A validator node _should not_ be used for network data access and transaction submission. There are two varieties of _non-validating_ nodes that can be used for those purposes, each of which has its own process for set up, interaction, maintenance, and monitoring. They are: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/data/analytics/hubble/analyst-guide/history-vs-state-tables.mdx b/i18n/es/docusaurus-plugin-content-docs/current/data/analytics/hubble/analyst-guide/history-vs-state-tables.mdx index 9ac2991abf..5281d9bfb9 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/data/analytics/hubble/analyst-guide/history-vs-state-tables.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/data/analytics/hubble/analyst-guide/history-vs-state-tables.mdx @@ -64,7 +64,7 @@ As seen in the table, each row shows the distinct operation with its unique `id` - [History Assets](../data-catalog/data-dictionary/history-assets.mdx) - [History Contract Events](../data-catalog/data-dictionary/history-contract-events.mdx) - [History Effects](../data-catalog/data-dictionary/history-effects.mdx) -- [History Ledgers](../data-catalog/data-dictionary/history-ledgers.mdx) +- [History Ledgers](../data-catalog/data-dictionary/history.mdx) - [History Operations](../data-catalog/data-dictionary/history-operations.mdx) - [History Trades](../data-catalog/data-dictionary/history-trades.mdx) - [History Transactions](../data-catalog/data-dictionary/history-transactions.mdx) diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 01ab480b14..0d17b737ea 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -152,7 +152,7 @@ rewrite ^/docs/learn/encyclopedia/fee-bump-transactions$ "/docs/learn/encycloped rewrite ^/docs/learn/encyclopedia/channel-accounts$ "/docs/learn/encyclopedia/transactions-specialized/channel-accounts" permanent; rewrite ^/docs/learn/encyclopedia/contract-development/fees-and-metering "/docs/learn/fundamentals/fees-resource-limits-metering" permanent; rewrite ^/docs/learn/encyclopedia/inflation$ "/docs/learn/encyclopedia/network-configuration/inflation" permanent; -rewrite ^/docs/learn/encyclopedia/ledger-headers$ "/docs/learn/encyclopedia/network-configuration/ledger-headers" permanent; +rewrite ^/docs/learn/encyclopedia/ledger-headers$ "/docs/learn/fundamentals/stellar-data-structures/ledgers/headers" permanent; rewrite ^/docs/learn/encyclopedia/liquidity-on-stellar-sdex-liquidity-pools$ "/docs/learn/fundamentals/liquidity-on-stellar-sdex-liquidity-pools" permanent; rewrite ^/docs/learn/encyclopedia/sdex$ "/docs/learn/fundamentals/liquidity-on-stellar-sdex-liquidity-pools" permanent; rewrite ^/docs/learn/encyclopedia/lumen-supply-metrics$ "/docs/learn/fundamentals/lumens#lumen-supply-metrics" permanent; diff --git a/routes.txt b/routes.txt index fa1b368e88..0a1035f108 100644 --- a/routes.txt +++ b/routes.txt @@ -524,6 +524,8 @@ /docs/learn/fundamentals/stellar-data-structures/contracts /docs/learn/fundamentals/stellar-data-structures/events /docs/learn/fundamentals/stellar-data-structures/ledgers +/docs/learn/fundamentals/stellar-data-structures/ledgers/entries +/docs/learn/fundamentals/stellar-data-structures/ledgers/headers /docs/learn/fundamentals/stellar-ecosystem-proposals /docs/learn/fundamentals/stellar-stack /docs/learn/fundamentals/transactions