subsystem-summary-of-protocol-curr

name	subsystem-summary-of-protocol-curr
description	read this skill for a token-efficient summary of the protocol-curr subsystem

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).
• : Contains and pool state .

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 ().

Stellar-ledger.x — Ledger Structure and Metadata

Defines ledger headers, upgrades, transaction sets, and close metadata:

• LedgerHeader: {ledgerVersion, previousLedgerHash, scpValue, txSetResultHash, bucketListHash, ledgerSeq, totalCoins, feePool, inflationSeq, idPool, baseFee, baseReserve, maxTxSetSize, skipList[4]}.
  • Extension V1 adds flags (LedgerHeaderFlags: liquidity pool trading/deposit/withdrawal disable flags).
• StellarValue: {txSetHash, closeTime, upgrades<6>} — the value SCP agrees on. Has BASIC or SIGNED variant (with LedgerCloseValueSignature).
• LedgerUpgrade union (7 types): VERSION, BASE_FEE, MAX_TX_SET_SIZE, BASE_RESERVE, FLAGS, CONFIG, MAX_SOROBAN_TX_SET_SIZE.
• Transaction sets:
  • TransactionSet: Legacy {previousLedgerHash, txs<>}.
  • TransactionSetV1: {previousLedgerHash, phases<>}.
  • TransactionPhase union: V0 has TxSetComponent<>, V1 has ParallelTxsComponent for parallel execution.
  • ParallelTxsComponent: {baseFee*, executionStages<>} — stages of clusters for parallel tx application.
  • GeneralizedTransactionSet union (v=1): wraps TransactionSetV1.
• Transaction metadata (multiple versions):
  • TransactionMeta union (v0-v4): Records LedgerEntryChanges (created/updated/removed/state/restored) before/after operations.
  • TransactionMetaV3: Adds SorobanTransactionMeta (events, returnValue, diagnosticEvents).
  • TransactionMetaV4: Adds OperationMetaV2 (per-operation events), TransactionEvent (fee events with stage info), SorobanTransactionMetaV2.
  • ContractEvent: {contractID*, type(SYSTEM/CONTRACT/DIAGNOSTIC), body{topics<>, data}}.
  • SorobanTransactionMetaExtV1: Fee breakdown (nonRefundable, refundable, rent).
• Ledger close metadata:

Stellar-contract-config-setting.x — Soroban Configuration

Network-wide Soroban settings stored as CONFIG_SETTING ledger entries:

• ConfigSettingID enum (17 settings): Controls max contract size, compute limits, ledger costs, historical data fees, event limits, bandwidth, cost model params, data size limits, state archival, execution lanes, eviction, parallel compute, SCP timing.
• ConfigSettingEntry union: Discriminated by ConfigSettingID.
• Key config structs:
  • ConfigSettingContractComputeV0: ledgerMaxInstructions, txMaxInstructions, feeRatePerInstructionsIncrement, txMemoryLimit.
  • ConfigSettingContractLedgerCostV0: Limits and fees for disk reads/writes, rent pricing.
  • ConfigSettingContractLedgerCostExtV0: txMaxFootprintEntries, feeWrite1KB.
  • ConfigSettingContractBandwidthV0: ledgerMaxTxsSizeBytes, txMaxSizeBytes, feeTxSize1KB.
  • ConfigSettingContractExecutionLanesV0: ledgerMaxTxCount.
  • ConfigSettingContractParallelComputeV0: ledgerMaxDependentTxClusters.
  • StateArchivalSettings: TTL bounds, rent rates, eviction parameters.
  • ConfigSettingSCPTiming: Target close time and nomination/ballot timeouts (in ms).
• ContractCostType enum (85 cost types): Covers WASM execution, memory, hashing (SHA256, Keccak256), signature verification (Ed25519, ECDSA secp256k1/r1), BLS12-381 and BN254 elliptic curve operations, WASM parsing/instantiation costs.
• ContractCostParamEntry: {constTerm, linearTerm} — piecewise linear cost model.
• EvictionIterator: {bucketListLevel, isCurrBucket, bucketFileOffset} — tracks eviction scan position.

Stellar-overlay.x — Peer-to-Peer Network Messages

Types for node communication:

• MessageType enum (24 message types): Covers error, auth handshake, peer exchange, transaction/tx-set relay, SCP messages, flow control (SEND_MORE/SEND_MORE_EXTENDED), pull-mode flooding (FLOOD_ADVERT/FLOOD_DEMAND), and time-sliced surveys.
• StellarMessage union: Discriminated by MessageType, carrying the appropriate payload for each message.
• AuthenticatedMessage union: Wraps {sequence, StellarMessage, HmacSha256Mac}.
• Handshake: Hello (version info, networkID, peer info, auth cert, nonce), Auth (flow control flags).
• Survey types: TimeSlicedSurveyRequestMessage, TopologyResponseBodyV2, PeerStats, TimeSlicedNodeData — for network topology discovery.
• Flow control: SendMore {numMessages}, SendMoreExtended {numMessages, numBytes}.
• Flooding: FloodAdvert {txHashes<1000>}, FloodDemand {txHashes<1000>}.

Stellar-contract-env-meta.x — Contract Environment Metadata

Minimal: defines SCEnvMetaEntry union with a single variant SC_ENV_META_KIND_INTERFACE_VERSION carrying {protocol: uint32, preRelease: uint32}.

Stellar-contract-meta.x — Contract Metadata

Minimal: defines SCMetaEntry union with SC_META_V0 variant carrying SCMetaV0 {key: string, val: string} — arbitrary key-value metadata for contracts.

Stellar-contract-spec.x — Contract Specification (ABI)

Defines the Soroban contract ABI (Application Binary Interface):

• SCSpecType enum: All Soroban types including primitives, parameterized types (OPTION, RESULT, VEC, MAP, TUPLE, BYTES_N), and user-defined types (UDT).
• SCSpecTypeDef union: Recursive type definition supporting all SCSpecType variants.
• SCSpecEntry union (6 kinds): FUNCTION_V0, UDT_STRUCT_V0, UDT_UNION_V0, UDT_ENUM_V0, UDT_ERROR_ENUM_V0, EVENT_V0.
• Each entry includes documentation strings, names, and type information for contract interface description.
• SCSpecFunctionV0: {doc, name, inputs<>, outputs<1>}.
• SCSpecEventV0: {doc, lib, name, prefixTopics<2>, params<>, dataFormat}.

Stellar-internal.x — Internal Persistence Types

Types used only within a single core instance (not cross-node):

• StoredTransactionSet union: Legacy or Generalized tx set.
• StoredDebugTransactionSet: {txSet, ledgerSeq, scpValue} — for debugging.
• PersistedSCPState union (v0, v1): Saved SCP state including envelopes, quorum sets, and optionally tx sets.

Stellar-exporter.x — Ledger Export Types

• LedgerCloseMetaBatch: {startSequence, endSequence, ledgerCloseMetas<>} — batch of consecutive ledger close metadata for export to downstream systems.

Key Design Patterns

1. Union versioning: Most types use union switch (int v) { case 0: void; } extensions for forward compatibility. New fields are added via new case arms.
2. Envelope pattern: Data (Transaction, SCP statement) is wrapped in an envelope with signatures for authentication.
3. Result codes: Every operation has a *ResultCode enum (success = 0, failures < 0) and a *Result union.
4. Fee bump structure: FeeBumpTransaction wraps TransactionV1Envelope as innerTx, enabling fee sponsorship. TransactionResult has special codes txFEE_BUMP_INNER_SUCCESS/FAILED that carry InnerTransactionResultPair.
5. Soroban integration: Soroban operations (INVOKE_HOST_FUNCTION, EXTEND_FOOTPRINT_TTL, RESTORE_FOOTPRINT) use SorobanTransactionData for resource declarations and SorobanAuthorizationEntry for per-address authorization trees.
6. Parallel execution support: ParallelTxsComponent and ParallelTxExecutionStage organize transactions into dependency-aware clusters for parallel application.