Transaction Lifecycle

How a Solana transaction moves from enqueue to finalized, and what Sinker tracks at each stage.

The seven stages

A transaction submitted through Sinker passes through seven distinct stages. Each stage transition is detected from the live Yellowstone gRPC stream and written to the lifecycle log.

[enqueued]
    ↓  TPU ingestion at leader (via Jito block engine)
[submitted]
    ↓  Leader includes tx in block; shreds propagate via Turbine
[landed / processed]
    ↓  ≥ 2/3 stake weight votes confirm the block
[confirmed]
    ↓  31+ subsequent blocks are finalized on top of this one
[finalized]

A bundle can receive HTTP 200 from the Jito block engine and still never land. This happens when no jito-solana validator is scheduled as leader in the next ~20 slots. Sinker’s background status tracker detects this by polling getInflightBundleStatuses and stamps the entry invalid.

---

Lifecycle entry

Every bundle submission produces a LifecycleEntry written to lifecycle.jsonl. You can read all entries with sinker.getLifecycle() or filter to a single transaction with tx.lifecycle().

const entries = await handle.lifecycle();

for (const entry of entries) {
  console.log(entry.bundle_id);
  console.log(entry.stage);            // 'finalized' | 'failed' | ...
  console.log(entry.tip_lamports);
  console.log(entry.confirmed_to_finalized_ms);  // latency delta
  console.log(entry.ai_decision_trace);           // agent's reasoning
}

LifecycleEntry fields

bundle_id · string

Unique identifier assigned by the Jito block engine (or a synthetic ID for faulted/errored submissions).

slot_submitted · number

The slot at which the bundle was submitted.

leader · string | null

The validator identity pubkey scheduled to lead slot_submitted.

tip_lamports · number

The tip amount included in this bundle attempt, in lamports.

tip_floor · TipSnapshot | null

The live Jito floor snapshot captured at submit time (p50 / p75 / p95 / ema / stale).

landed_slot · number | null

The slot the tip transaction was processed in — may drift from slot_submitted.

attempt · number

Submission attempt number for this bundle (1-based; increments on retry).

mode · string

Strategy that produced this bundle: agent | bypass | naive.

decision_mode · 'reflex' | 'cortex' | ''

The decision tier the agent submitted under. Empty for script / bypass / naive submissions. See AI Agent → Two-tier router.

escalated · boolean | null

Reflex-only: whether this submission was escalated to the LLM (Cortex). null when not in reflex mode.

submitted_at · string

ISO 8601 timestamp of submission.

stage · BundleStage

Current lifecycle stage: submitted | landed | processed | confirmed | finalized | failed | invalid | unknown

failure · FailureClass | null

Structured failure class when stage is failed. See Fault Injection for the full taxonomy.

confirmed_to_finalized_ms · number | null

Wall-clock milliseconds from confirmed to finalized. Observed values on mainnet: ~11,700–13,000 ms (~29–32 slots) — the protocol’s finalization depth. (An earlier revision reported ~2.3 s here; that was an instrumentation artifact, since fixed — see the lifecycle log notes.)

ai_decision_trace · string | null

The AI agent’s chain-of-thought for this bundle: tip selection rationale, failure pattern analysis, and escalation decisions.

queued_tx_ids · string[]

The tx_id values from /tx/enqueue that were included in this bundle.

---

Commitment levels

Level	Slots from tip	Description
processed	0	Included in a block. Can reorg.
confirmed	~2	Supermajority vote. Reorg rate <0.1% on mainnet.
finalized	~32	Irreversible under BFT assumption.

Sinker uses confirmed commitment when fetching blockhashes, giving 148 valid slots (~59s) vs 118 slots (~47s) for finalized. This is meaningful when targeting a specific 4-slot Jito leader window.

---

Observed latencies (mainnet-beta)

From real bundle submissions during development:

Bundle	submitted → confirmed	confirmed → finalized
160974fe	11,875ms	2,480ms
b9e8b294	13,354ms	2,355ms
4359b58d	13,053ms	—

Variance in submitted → confirmed is primarily driven by leader window alignment at submission time.