Architecture
SlotPilot system architecture, data flow, trust boundaries, and failure recovery
SlotPilot Architecture
SlotPilot is a modular monolith for observing, submitting, proving, and recovering Solana transactions. The transaction engine owns keys and execution. The AI agent is an external decision boundary that receives operational context but cannot sign or submit transactions.
System Flow
Yellowstone gRPCnormalized, reconnecting slot and replayable signature streams
Jito Leader Plannernext connected leader and wait window
Blockhash Managerconfirmed blockhash and expiry context
Transaction Buildertransfer, unique memo, compute budget, payer signature
Tip OracleJito tip floor, Solana pressure, retry multiplier
Jito Bundlesingle signed transfer transaction with embedded Jito tip
Block Enginebase64 sendBundle submission
Lifecycle Storeappend-only JSONL proof
Failure Classifiernormalized operational cause
AI Retry Agentstrict retry, hold, or abort decision
Retry Executorrefresh, reprice, delay, rebuild, resubmit
Submission Sequence
Open the Yellowstone background slot subscription and record the current slot.
Query the next connected Jito leader and wait until the configured submission window.
Fetch a confirmed blockhash and its last valid block height.
Read the Jito landed-tip median and recent Solana prioritization-fee pressure.
Select a rotating Jito tip account and calculate a bounded tip.
Build and sign one transaction containing the user transfer, unique memo, Jito tip memo, and Jito tip transfer.
Submit the transaction through
sendBundle using base64 encoding.Record the bundle id as submission evidence only.
Subscribe to Yellowstone transaction status with replay from the recorded submission slot.
Use slot commitment updates to prove processed, confirmed, and finalized progression.
Use RPC status only for reconciliation after a Yellowstone timeout.
Append timestamps, slots, sources, tip reasoning, and latency deltas to JSONL.
Trust Boundaries
| Boundary | Holds private keys | Signs | Submits | Makes retry decision |
|---|---|---|---|---|
| Transaction engine | Yes | Yes | Yes | No |
| Jito adapter | No | No | Yes | No |
| Yellowstone adapter | No | No | No | No |
| AI agent | No | No | No | Yes |
| JSONL store | No | No | No | No |
The AI prompt contains failure class, slots, blockhash age, tip amount, lifecycle timings, and previous failures. It never contains payer secret material or serialized signing authority.
Tip Intelligence
The tip baseline is the larger of:
- configured minimum tip
- Jito's latest median or EMA landed-tip floor
That baseline is adjusted by:
- a bounded multiplier derived from Solana prioritization fees
- a failure multiplier for low-tip or non-landed attempts
- the AI agent's retry multiplier
The final amount is capped by the configured maximum. The selected tip account, source, amount, and explanation are written to lifecycle logs.
Lifecycle Proof
Yellowstone is the primary source:
- Transaction status replay starts at
submittedSlot, closing the race between a fast landing and subscription attachment. - Slot commitment updates prove that same slot reached confirmed and finalized.
- Transient signature-stream disconnects reconnect with replay while preserving partial lifecycle state.
- RPC polling is used only if the stream times out.
- Jito inflight and landed status endpoints are consulted when neither source proves landing.
Every finalized record identifies its lifecycleSource, allowing the evidence verifier to reject an RPC-only submission package.
Failure Recovery
| Failure class | Evidence | Typical agent action |
|---|---|---|
expired_blockhash | stale blockhash, simulation output, block height | refresh blockhash and retry |
fee_or_tip_too_low | Jito response or auction/tip error | increase tip multiplier |
compute_exceeded | simulation logs | abort or rebuild with new compute settings |
bundle_not_landed | stream/RPC timeout plus Jito status | refresh, reprice, and retry |
skipped_leader | unavailable leader window or skipped-slot context | delay until another leader |
simulation_failed | simulation error/logs | abort or rebuild |
stream_timeout | no stream progression and no reconciliation result | hold or retry from fresh context |
Operational Decisions
- Modular monolith: reduces deployment and coordination overhead while preserving provider boundaries.
- JSONL logs: create portable, append-only evidence without database migrations.
- Confirmed blockhashes: provide freshness without relying on the least stable processed view.
- Separate AI boundary: keeps probabilistic reasoning outside signing and submission.
- CLI-first demos: make live runs reproducible for judges.
- Rate limiting: serializes Jito JSON-RPC calls and applies a minimum live retry delay.
Evidence Gate
The final live verifier requires:
- at least 10 unique finalized runs
- a unique transaction signature and bundle id for every finalized run
- failures in at least 2 distinct runs
- an expired-blockhash failure linked to an OpenAI refresh decision and later finalization
- no mock bundle ids or mock submission plans
- complete, monotonic signatures, slots, timestamps, and exact latency deltas
- JSONL failure and agent files consistent with the lifecycle file
- at least 7 Yellowstone-proven finalized runs
Run:
pnpm run demo:verify-logs -- --require-live