Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
read this skill for a token-efficient summary of the transactions subsystem
Transactions Subsystem — Technical Summary
Overview
The transactions subsystem implements the core transaction processing pipeline in stellar-core: parsing transaction envelopes from XDR, validating them, applying them to the ledger, and producing results and metadata. It encompasses the transaction frame hierarchy, all operation types (classic and Soroban), signature verification, offer exchange logic, sponsorship utilities, parallel apply infrastructure, and event/meta generation.
Key Files
TransactionFrameBase.h/.cpp — Abstract base class for all transaction types.
TransactionFrame.h/.cpp — Concrete implementation for regular (non-fee-bump) transactions. ~2500 lines; contains the main apply, checkValid, commonValid, processFeeSeqNum, parallelApply, and applyOperations logic.
FeeBumpTransactionFrame.h/.cpp — Wraps a TransactionFrame (inner tx) for fee bump support. Delegates most operations to the inner tx.
OperationFrame.h/.cpp — Abstract base for all operations. Factory method makeHelper creates concrete subclasses from XDR Operation. Contains apply, checkValid, parallelApply dispatch.
MutableTransactionResult.h/.cpp — Mutable result objects (MutableTransactionResult, FeeBumpMutableTransactionResult) that track transaction outcomes and fee refunds via RefundableFeeTracker.
TransactionMeta.h/.cpp — and for building XDR (ledger changes, events, return values).
TransactionMetaBuilder
OperationMetaBuilder
TransactionMeta
EventManager.h/.cpp — DiagnosticEventManager, OpEventManager, TxEventManager for emitting contract/diagnostic/fee events during tx processing.
SignatureChecker.h/.cpp — Validates decorated signatures against signers with weight thresholds, caching verification results.
SignatureUtils.h/.cpp — Low-level signature creation/verification helpers (Ed25519, hash-x, signed payloads).
TransactionUtils.h/.cpp — ~400 lines of helpers: ledger entry loading, balance/liability math, key construction, asset utilities, Soroban contract data helpers.
insertKeysForFeeProcessing() / insertKeysForTxApply() — declare keys needed for prefetching
withInnerTx() — visitor for fee bump inner tx access
Type aliases: TransactionFrameBasePtr = shared_ptr<TransactionFrameBase const>, MutableTxResultPtr = unique_ptr<MutableTransactionResultBase>
TransactionFrame — The main transaction implementation.
Members: mEnvelope (TransactionEnvelope), mNetworkID (Hash ref), mContentsHash/mFullHash (lazily computed), mOperations (vector of shared_ptr<OperationFrame const>, built in constructor via OperationFrame::makeHelper), mCachedAccountPreProtocol8
ValidationType enum: kInvalid, kInvalidUpdateSeqNum, kInvalidPostAuth, kMaybeValid — used by commonValid to decide how to handle failures (e.g., whether to still update seq nums or remove one-time signers)
Key methods (see Flows section below)
FeeBumpTransactionFrame — Holds an outer mEnvelope plus mInnerTx (TransactionFramePtr). Delegates most operations to the inner tx. Has its own commonValid/commonValidPreSeqNum for validating the fee bump wrapper's signatures and fee source. ValidationType: kInvalid, kInvalidPostAuth, kFullyValid.
getThresholdLevel() — returns LOW, MEDIUM, or HIGH; most ops default to MEDIUM, but MergeOpFrame, SetOptionsOpFrame, InflationOpFrame, BumpSequenceOpFrame, ClaimClaimableBalanceOpFrame, ExtendFootprintTTLOpFrame, RestoreFootprintOpFrame override.
isOpSupported(header) — gates ops by protocol version.
isDexOperation() — true for offer ops and path payments.
isSoroban() — true for Soroban ops.
insertLedgerKeysToPrefetch(keys) — allows ops to declare keys for bulk loading.
ManageOfferOpFrameBase — Shared base for sell/buy offer management. Contains the complete offer matching logic: validates offers, computes exchange parameters, calls convertWithOffersAndPools, manages offer creation/modification/deletion in the DEX. Uses sheep/wheat terminology.
PathPaymentOpFrameBase — Shared base for path payments. Provides convert() (calls convertWithOffersAndPools for each path hop), updateSourceBalance, updateDestBalance, checkIssuer.
TrustFlagsOpFrameBase — Shared base for AllowTrustOpFrame and SetTrustLineFlagsOpFrame. Contains common doApply logic for flag validation, authorization changes, and offer removal on deauthorization.
Result Types
MutableTransactionResultBase — Abstract base for mutable results during tx processing.
RefundableFeeTracker — Tracks consumed Soroban refundable resources (contract events size, rent fees) to compute fee refunds. consumeRefundableSorobanResources() returns false if the tx exceeds its refundable fee budget. getFeeRefund() returns unused portion.
Meta and Events
TransactionMetaBuilder — Builds TransactionMeta XDR for a transaction. Creates OperationMetaBuilder instances for each operation. Methods: pushTxChangesBefore(), pushTxChangesAfter(), setNonRefundableResourceFee(), finalize(success).
OperationMetaBuilder — Per-operation meta builder. setLedgerChanges() captures LedgerEntryChanges from operation's LedgerTxn. setSorobanReturnValue(), getEventManager(), getDiagnosticEventManager().
DiagnosticEventManager — Buffers DiagnosticEvent entries. Created as enabled/disabled depending on context (apply vs. validation, meta enabled or not). pushEvent(), pushError().
SignatureChecker — Constructed with (protocolVersion, contentsHash, signatures). checkSignature(signers, neededWeight) iterates decorated signatures, verifies each against provided signers, accumulates weight. Tracks which signatures have been used; checkAllSignaturesUsed() enforces no extra signatures. Maintains static counters for cache hit metrics.
Offer Exchange
ExchangeResultV10 — Result of a single offer crossing: numWheatReceived, numSheepSend, wheatStays.
convertWithOffersAndPools(...) — Buys wheat with sheep by crossing offers from the order book and/or using liquidity pools. Returns ConvertResult (eOK, ePartial, eFilterStopBadPrice, etc.). Takes a filter callback for price bounds and self-crossing prevention.
Parallel Apply Infrastructure
TxEffects — Container holding TransactionMetaBuilder and LedgerTxnDelta for a single transaction during parallel apply.
TxBundle — Groups a transaction pointer, its result payload reference, tx number, and TxEffects.
Cluster — vector<TxBundle> — a group of transactions that must be applied sequentially (they share footprint overlap).
ApplyStage — vector<Cluster> with iteration support. Contains non-overlapping clusters that can be applied in parallel.
Parallel Ledger State Hierarchy (scoped entry ownership for safety):
GlobalParallelApplyLedgerState — Owns the global entry map, hot archive snapshot, live snapshot, in-memory Soroban state, and restored entries. Splits state into per-thread maps before parallel execution, merges back after.
ThreadParallelApplyLedgerState — Per-thread state copied from global. Owns mThreadEntryMap, mThreadRestoredEntries, RO TTL bumps buffer. Commits changes from successful txs.
TxParallelApplyLedgerState — Per-transaction state within a thread. Owns mTxEntryMap (modified entries) and mTxRestoredEntries. Provides takeSuccess()/takeFailure() to produce ParallelTxReturnVal.
LedgerAccessHelper — Abstract interface (getLedgerEntryOpt, upsertLedgerEntry, eraseLedgerEntryIfExists) with two implementations:
PreV23LedgerAccessHelper — wraps AbstractLedgerTxn for sequential apply
ParallelLedgerAccessHelper — wraps TxParallelApplyLedgerState for parallel apply
ParallelTxReturnVal — Returned by each parallel tx: contains success flag, TxModifiedEntryMap, and RestoredEntries.
Key Data Flows
Transaction Lifecycle: Submission to Application
Deserialization: TransactionFrameBase::makeTransactionFromWire(networkID, envelope) constructs either a TransactionFrame or FeeBumpTransactionFrame based on envelope type. TransactionFrame constructor invokes OperationFrame::makeHelper for each operation.
Validation (checkValid): Called during flood/herder acceptance.
Calls commonPreApply(): builds SignatureChecker, calls commonValid(applying=true), processes sequence number (processSeqNum), processes signatures (processSignatures — removes one-time signers, validates op signatures). Returns the checker on success, nullptr on failure.
Calls applyOperations(): iterates operations, for each op calls op->apply() which does checkValid(forApply=true) then doApply() or doApplyForSoroban(). Commits or rolls back per-op LedgerTxn based on success.
preParallelApply() — runs in sequential phase: validates signatures, processes seq num, builds signature checker. Called per-tx before parallel execution begins.
parallelApply() — runs in parallel threads: asserts single-op Soroban tx, calls op->parallelApply() which dispatches to doParallelApply(). Uses TxParallelApplyLedgerState for ledger access. On success, ThreadParallelApplyLedgerState::setEffectsDeltaFromSuccessfulTx() records changes. Returns ParallelTxReturnVal.
Parallel Apply Architecture
Soroban transactions are organized into stages of non-overlapping clusters:
GlobalParallelApplyLedgerState is constructed, collecting modified classic entries and setting up snapshots.
For each ApplyStage: clusters are distributed across threads.
Each thread gets a ThreadParallelApplyLedgerState (split from global state for the cluster's footprint).
Within a thread, txs in a cluster are applied sequentially. Each tx gets a TxParallelApplyLedgerState.
Successful tx changes are committed from tx state → thread state.
After all threads complete, thread states are merged back → global state via commitChangesFromThreads().
After all stages, commitChangesToLedgerTxn() writes final state to the main LedgerTxn.
Offer Exchange Flow
For DEX operations (ManageSell/BuyOffer, PathPayment):
ManageOfferOpFrameBase::doApply() validates the offer, computes exchange parameters.
Calls convertWithOffersAndPools() which iterates matching offers in the order book.
For each crossed offer: crossOfferV10() → exchangeV10() computes exact amounts.
Liquidity pools are checked for each asset pair (if available) and can be crossed atomically.
Results accumulated in offerTrail (vector of ClaimAtom).
Residual offer amount (if any) is written into the order book or deleted.
Path payments chain multiple conversions through intermediate assets.
Key Utility Modules
TransactionUtils
Provides an extensive set of helpers used throughout the subsystem:
Sequential apply (classic transactions and pre-v23 Soroban): All transactions applied on the main thread using AbstractLedgerTxn for atomic state management. Each operation runs in a nested LedgerTxn that can be committed or rolled back.
Parallel apply (Soroban transactions, v23+): Transactions are grouped into ApplyStages containing Clusters. Non-overlapping clusters run on separate threads. Within each cluster, transactions are applied sequentially. The LedgerEntryScope template system enforces ownership discipline across global/thread/tx scopes, preventing accidental cross-scope reads via compile-time scope tagging (GlobalParApply, ThreadParApply, TxParApply).