subsystem-summary-of-protocol-curr

# Subsystem: protocol-curr (Current-Protocol XDR Type Definitions) ## Overview The `src/protocol-curr/xdr/` directory contains the canonical XDR (External Data Representation) type definitions for the current protocol version of stellar-core. These `.x` files define all on-wire and on-disk data structures used by the Stellar network. Corresponding `.h` files are auto-generated C++ headers from these XDR definitions via the xdrpp code generator. **Never edit `.h` files directly; always modify the `.x` source files.** The directory is a git submodule pointing to the official Stellar XDR repository. ## File Organization and Dependency Graph The XDR files form a dependency DAG via `%#include` directives: ``` Stellar-types.x (base types, no dependencies) ├── Stellar-SCP.x (consensus protocol types) ├── Stellar-contract.x (smart contract value types) │ └── Stellar-contract-config-setting.x (Soroban config settings) ├── Stellar-contract-env-meta.x (contract environment metadata) ├── Stellar-contract-meta.x (contract metadata) ├── Stellar-contract-spec.x (contract specification/ABI) ├── Stellar-ledger-entries.x (ledger state entries; depends on contract.x, contract-config-setting.x) │ └── Stellar-transaction.x (transaction types; depends on ledger-entries.x, contract.x) │ └── Stellar-ledger.x (ledger structure, meta; depends on transaction.x, SCP.x) │ ├── Stellar-overlay.x (peer-to-peer network messages) │ ├── Stellar-internal.x (internal-only persistence types) │ └── Stellar-exporter.x (ledger export batch types) ``` ## Module Summaries ### Stellar-types.x — Foundational Types Defines primitive and shared types used throughout all other XDR files: - **Primitive typedefs**: `Hash` (32-byte opaque), `uint256` (32-byte opaque), `uint32`, `int32`, `uint64`, `int64`, `TimePoint` (uint64), `Duration` (uint64) - **`ExtensionPoint`**: A union (always case 0/void) used as a placeholder in structs for future extensibility. - **Cryptographic key types**: - `CryptoKeyType` enum: `KEY_TYPE_ED25519 (0)`, `KEY_TYPE_PRE_AUTH_TX (1)`, `KEY_TYPE_HASH_X (2)`, `KEY_TYPE_ED25519_SIGNED_PAYLOAD (3)`, `KEY_TYPE_MUXED_ED25519 (0x100)`. - `PublicKey` union (discriminant `PublicKeyType`): wraps ed25519 key. - `SignerKey` union (discriminant `SignerKeyType`): supports ed25519, pre-auth tx hash, hash-x, ed25519+signed-payload. - **Identity typedefs**: `NodeID = PublicKey`, `AccountID = PublicKey`, `ContractID = Hash`, `PoolID = Hash`. - **Signature types**: `Signature` (opaque<64>), `SignatureHint` (opaque[4]). - **Crypto primitives**: `Curve25519Secret`, `Curve25519Public`, `HmacSha256Key`, `HmacSha256Mac`, `ShortHashSeed`. - **`SerializedBinaryFuseFilter`**: Probabilistic filter with configurable bit-width (8/16/32-bit), used by bucket list. - **`ClaimableBalanceID`**: Union keyed by `ClaimableBalanceIDType`, currently only `V0` wrapping a `Hash`. ### Stellar-SCP.x — Stellar Consensus Protocol Types for the SCP (Federated Byzantine Agreement) consensus mechanism: - **`SCPBallot`**: `{counter, value}` — a ballot in the SCP protocol. - **`SCPStatementType`** enum: `PREPARE (0)`, `CONFIRM (1)`, `EXTERNALIZE (2)`, `NOMINATE (3)`. - **`SCPStatement`**: Contains `nodeID`, `slotIndex`, and a `pledges` union discriminated by `SCPStatementType`: - `PREPARE`: `{quorumSetHash, ballot, prepared*, preparedPrime*, nC, nH}` - `CONFIRM`: `{ballot, nPrepared, nCommit, nH, quorumSetHash}` - `EXTERNALIZE`: `{commit, nH, commitQuorumSetHash}` - `NOMINATE`: `SCPNomination {quorumSetHash, votes<>, accepted<>}` - **`SCPEnvelope`**: `{statement, signature}` — signed SCP message. - **`SCPQuorumSet`**: `{threshold, validators<>, innerSets<>}` — recursive quorum slice definition (max 4 nesting levels). ### Stellar-contract.x — Smart Contract (Soroban) Value Types Core types for the Soroban smart contract system: - **`SCValType`** enum (22 variants): `BOOL, VOID, ERROR, U32, I32, U64, I64, TIMEPOINT, DURATION, U128, I128, U256, I256, BYTES, STRING, SYMBOL, VEC, MAP, ADDRESS, CONTRACT_INSTANCE, LEDGER_KEY_CONTRACT_INSTANCE, LEDGER_KEY_NONCE`. - **`SCVal`** union: The universal polymorphic value type for Soroban, discriminated by `SCValType`. - **`SCError`** union: Discriminated by `SCErrorType` (10 types: `CONTRACT, WASM_VM, CONTEXT, STORAGE, OBJECT, CRYPTO, EVENTS, BUDGET, VALUE, AUTH`). Contract errors carry a `uint32` code; all others carry an `SCErrorCode` enum. - **`SCErrorCode`** enum: `ARITH_DOMAIN, INDEX_BOUNDS, INVALID_INPUT, MISSING_VALUE, EXISTING_VALUE, EXCEEDED_LIMIT, INVALID_ACTION, INTERNAL_ERROR, UNEXPECTED_TYPE, UNEXPECTED_SIZE`. - **Large integer structs**: `UInt128Parts {hi, lo}`, `Int128Parts {hi(signed), lo}`, `UInt256Parts {hi_hi, hi_lo, lo_hi, lo_lo}`, `Int256Parts`. - **`ContractExecutable`** union: `WASM` (carries `wasm_hash`) or `STELLAR_ASSET` (void). - **`SCAddress`** union (discriminant `SCAddressType`): `ACCOUNT(AccountID)`, `CONTRACT(ContractID)`, `MUXED_ACCOUNT`, `CLAIMABLE_BALANCE`, `LIQUIDITY_POOL`. - **Collection types**: `SCVec = SCVal<>`, `SCMap = SCMapEntry<>`, `SCMapEntry = {key: SCVal, val: SCVal}`. - **String types**: `SCBytes = opaque<>`, `SCString = string<>`, `SCSymbol = string<32>`. - **`SCContractInstance`**: `{executable: ContractExecutable, storage: SCMap*}`. ### Stellar-ledger-entries.x — Ledger State Entries Defines all persistent ledger entry types: - **`LedgerEntryType`** enum (10 types): `ACCOUNT(0), TRUSTLINE(1), OFFER(2), DATA(3), CLAIMABLE_BALANCE(4), LIQUIDITY_POOL(5), CONTRACT_DATA(6), CONTRACT_CODE(7), CONFIG_SETTING(8), TTL(9)`. - **Asset types**: - `AssetType` enum: `NATIVE(0), CREDIT_ALPHANUM4(1), CREDIT_ALPHANUM12(2), POOL_SHARE(3)`. - `Asset` union: void for native, `AlphaNum4/12` for credits (each has `assetCode + issuer`). - `TrustLineAsset`: extends Asset with `POOL_SHARE` variant carrying `PoolID`. - `ChangeTrustAsset`: extends Asset with `POOL_SHARE` variant carrying `LiquidityPoolParameters`. - `Price`: fractional `{n: int32, d: int32}`. - **`AccountEntry`**: `{accountID, balance, seqNum, numSubEntries, inflationDest*, flags, homeDomain, thresholds, signers<20>}` with extension versions V1 (adds `Liabilities`), V2 (adds sponsorship tracking), V3 (adds `seqLedger`, `seqTime`). - `AccountFlags`: `AUTH_REQUIRED(0x1), AUTH_REVOCABLE(0x2), AUTH_IMMUTABLE(0x4), AUTH_CLAWBACK_ENABLED(0x8)`. - **`TrustLineEntry`**: `{accountID, asset, balance, limit, flags}` with extensions for liabilities and `liquidityPoolUseCount`. - `TrustLineFlags`: `AUTHORIZED(1), AUTHORIZED_TO_MAINTAIN_LIABILITIES(2), TRUSTLINE_CLAWBACK_ENABLED(4)`. - **`OfferEntry`**: `{sellerID, offerID, selling, buying, amount, price, flags}`. - **`DataEntry`**: `{accountID, dataName, dataValue}` — arbitrary key-value data on accounts. - **`ClaimableBalanceEntry`**: `{balanceID, claimants<10>, asset, amount}` with `ClaimPredicate` union (recursive: `UNCONDITIONAL, AND, OR, NOT, BEFORE_ABSOLUTE_TIME, BEFORE_RELATIVE_TIME`). - **`LiquidityPoolEntry`**: Contains `LiquidityPoolConstantProductParameters {assetA, assetB, fee}` and pool state `{reserveA, reserveB, totalPoolShares, poolSharesTrustLineCount}`. - **Soroban entries**: - `ContractDataEntry`: `{contract: SCAddress, key: SCVal, durability: ContractDataDurability, val: SCVal}`. Durability is `TEMPORARY(0)` or `PERSISTENT(1)`. - `ContractCodeEntry`: `{hash, code<>}` with optional `ContractCodeCostInputs` in V1 extension. - `TTLEntry`: `{keyHash, liveUntilLedgerSeq}` — tracks expiration of Soroban entries. - `ConfigSettingEntry`: see contract-config-setting.x below. - **`LedgerEntry`** union: Wraps all entry types with `lastModifiedLedgerSeq` and optional `LedgerEntryExtensionV1` (carries `sponsoringID`). - **`LedgerKey`** union: Discriminated by `LedgerEntryType`, carries lookup keys for each entry type. - **`EnvelopeType`** enum: `TX_V0(0), SCP(1), TX(2), AUTH(3), SCPVALUE(4), TX_FEE_BUMP(5), OP_ID(6), POOL_REVOKE_OP_ID(7), CONTRACT_ID(8), SOROBAN_AUTHORIZATION(9)`. - **Bucket types**: - `BucketListType`: `LIVE(0), HOT_ARCHIVE(1)`. - `BucketEntryType`: `METAENTRY(-1), LIVEENTRY(0), DEADENTRY(1), INITENTRY(2)`. - `BucketEntry` union and `HotArchiveBucketEntry` union for live and hot-archive bucket lists. - `BucketMetadata`: `{ledgerVersion}` with optional `BucketListType` extension. ### Stellar-transaction.x — Transactions and Operations The largest XDR file (~2100 lines). Defines transaction structure, all 27 operation types, and all result types. - **`OperationType`** enum (27 operations): `CREATE_ACCOUNT(0)`, `PAYMENT(1)`, `PATH_PAYMENT_STRICT_RECEIVE(2)`, `MANAGE_SELL_OFFER(3)`, `CREATE_PASSIVE_SELL_OFFER(4)`, `SET_OPTIONS(5)`, `CHANGE_TRUST(6)`, `ALLOW_TRUST(7)`, `ACCOUNT_MERGE(8)`, `INFLATION(9)`, `MANAGE_DATA(10)`, `BUMP_SEQUENCE(11)`, `MANAGE_BUY_OFFER(12)`, `PATH_PAYMENT_STRICT_SEND(13)`, `CREATE_CLAIMABLE_BALANCE(14)`, `CLAIM_CLAIMABLE_BALANCE(15)`, `BEGIN_SPONSORING_FUTURE_RESERVES(16)`, `END_SPONSORING_FUTURE_RESERVES(17)`, `REVOKE_SPONSORSHIP(18)`, `CLAWBACK(19)`, `CLAWBACK_CLAIMABLE_BALANCE(20)`, `SET_TRUST_LINE_FLAGS(21)`, `LIQUIDITY_POOL_DEPOSIT(22)`, `LIQUIDITY_POOL_WITHDRAW(23)`, `INVOKE_HOST_FUNCTION(24)`, `EXTEND_FOOTPRINT_TTL(25)`, `RESTORE_FOOTPRINT(26)`. - **`Operation`** struct: `{sourceAccount*: MuxedAccount, body: union(OperationType)}`. - **`MuxedAccount`** union: `ed25519` or `{id, ed25519}` for multiplexed accounts. - **Transaction envelope hierarchy**: - `TransactionV0` / `TransactionV0Envelope`: Legacy format (raw ed25519 source key). - `Transaction` / `TransactionV1Envelope`: Current format with `MuxedAccount` source, `Preconditions`, `Memo`, `operations<100>`, optional `SorobanTransactionData`. - `FeeBumpTransaction` / `FeeBumpTransactionEnvelope`: Wraps an inner `TransactionV1Envelope` with `feeSource` and increased `fee`. - `TransactionEnvelope` union: Discriminated by `EnvelopeType` (`TX_V0, TX, TX_FEE_BUMP`). - **Preconditions**: `Preconditions` union (`NONE, TIME, V2`). `PreconditionsV2` adds `timeBounds*, ledgerBounds*, minSeqNum*, minSeqAge, minSeqLedgerGap, extraSigners<2>`. - **Memo**: `MemoType` enum (`NONE, TEXT, ID, HASH, RETURN`). - **Soroban-specific types**: - `SorobanResources`: `{footprint: LedgerFootprint, instructions, diskReadBytes, writeBytes}`. - `SorobanTransactionData`: `{resources, resourceFee}` with optional `SorobanResourcesExtV0` for archived entries. - `HostFunction` union: `INVOKE_CONTRACT, CREATE_CONTRACT, UPLOAD_CONTRACT_WASM, CREATE_CONTRACT_V2`. - `SorobanAuthorizationEntry`: `{credentials, rootInvocation}` — authorization tree for Soroban calls. - `SorobanCredentials` union: `SOURCE_ACCOUNT(void)` or `ADDRESS(SorobanAddressCredentials)`. - `InvokeContractArgs`: `{contractAddress, functionName, args<>}`. - **`HashIDPreimage`** union: Used for deterministic ID generation, discriminated by `EnvelopeType` (`OP_ID, POOL_REVOKE_OP_ID, CONTRACT_ID, SOROBAN_AUTHORIZATION`). - **`TransactionSignaturePayload`**: `{networkId, taggedTransaction}` — the structure that is SHA-256 hashed and signed. - **Result types**: Each operation has a corresponding `*ResultCode` enum and `*Result` union. The top-level chain is: - `TransactionResult`: `{feeCharged, result union by TransactionResultCode}`. For fee bumps, wraps `InnerTransactionResultPair`. - `TransactionResultCode` enum (18 codes): `txFEE_BUMP_INNER_SUCCESS(1), txSUCCESS(0), txFAILED(-1)`, ..., `txSOROBAN_INVALID(-17)`.