SlotPilot

SlotPilot is an AI-assisted Solana transaction control tower.

Most Solana apps stop at sendTransaction. SlotPilot treats submission as an operational lifecycle:

observe network state
submit through Jito bundles
verify commitment progression
classify failures
retry from observed context
prove every attempt with lifecycle logs

Capability	What it does
Yellowstone live stream	Reads live slot and transaction updates
Jito bundle submission	Submits signed transactions through the block engine
Dynamic tip oracle	Selects tip account and tip size per attempt
AI retry agent	Returns structured retry, hold, or abort decisions
Lifecycle logs	Stores append-only proof for every attempt

1. Problem Statement

Sending a Solana transaction is only one part of the process.

Before a transaction lands, it passes through leader scheduling, TPU ingestion, block production, shred propagation, and commitment progression. Production systems need to understand these stages instead of only relying on RPC polling.

The key challenge is simple:

A Jito bundle id does not prove the transaction landed.

SlotPilot tracks the transaction through processed, confirmed, and finalized states before treating the attempt as proven.

2. Architecture Overview

SlotPilot is a modular monolith with an external AI decision agent.

The transaction engine observes, builds, signs, submits, and tracks. The AI agent only receives observed context and returns an operational decision. It does not hold private keys and does not sign transactions.

Yellowstone gRPC Streamslot and transaction updates

Slot + Leader Trackercurrent slot and leader windows

Submission Plannersubmit, wait, or avoid

Blockhash Managerfresh blockhash and expiry risk

Transaction Builderinstruction, fee payer, signature

Tip Oracletip account and tip size

Jito Bundle Builderuser transaction plus tip transaction

Jito Block Enginebundle submission

Lifecycle Trackersubmitted, processed, confirmed, finalized

Failure Classifiernormalized failure class

AI Retry Agentretry, hold, or abort JSON

Retry Executorsafe resubmission path

The AI agent sits outside the core transaction engine. It never signs transactions and never holds private keys. It only receives observed context and returns structured operational decisions.

3. Data Flow

Subscribe to Yellowstone gRPC slot and transaction streams.

Track current slot and upcoming leader windows.

Fetch a fresh blockhash using processed or confirmed commitment.

Build and sign a simple Solana transfer transaction.

Select a Jito tip account and calculate a dynamic tip.

Wrap the signed transaction and tip transaction into a Jito bundle.

Submit the bundle to the Jito Block Engine.

Record submitted_at timestamp and submitted_slot.

Watch Yellowstone transaction updates for processed, confirmed, and finalized.

Calculate latency deltas between lifecycle stages.

If failure occurs, classify the reason.

Send failure context to the AI agent.

Agent decides whether to retry, hold, or abort.

Retry executor follows the agent decision.

4. Component Breakdown

A. Yellowstone Stream Service Maintains live subscriptions to Solana network data.

Stream slot updates
Stream transaction updates
Reconnect on disconnect
Handle backpressure
Emit normalized internal events

B. Slot + Leader Tracker Understands where the network currently is.

Track current slot
Track skipped or delayed slots
Detect upcoming leader windows
Provide submission timing context

C. Submission Planner Decides if the current network moment is good for submission.

Check current slot
Check leader proximity
Avoid poor timing windows
Pass submission context to the bundle builder

D. Blockhash Manager Keeps transactions fresh.

Fetch latest blockhash
Track lastValidBlockHeight
Detect blockhash expiry risk
Refresh blockhash during retries
Avoid finalized commitment for time-sensitive blockhash fetching

E. Transaction Builder Creates the actual Solana transaction.

Build transfer instruction
Attach fresh blockhash
Add a unique per-attempt memo
Set fee payer
Sign transaction
Support fault injection with stale blockhash for demo failure

F. Tip Oracle Chooses the Jito bundle tip dynamically.

Fetch available Jito tip accounts
Analyze recent tip/network data
Avoid hardcoded fixed tips
Balance cost and landing probability
Return selected tip amount and explanation

G. Jito Bundle Builder Packages transactions for Jito.

Add user transaction
Add tip transaction
Serialize signed transactions
Submit bundle to Jito Block Engine
Capture bundle id and transaction signatures

H. Lifecycle Tracker Proves what happened after submission.

Mark submitted
Detect processed
Detect confirmed
Detect finalized
Store timestamps
Store slot numbers
Calculate latency deltas

I. Failure Classifier Normalizes raw failures into useful operational categories.

expired_blockhash
fee_or_tip_too_low
compute_exceeded
bundle_not_landed
skipped_leader
unknown

J. AI Retry Agent Owns one real operational decision.

Receive failure context
Reason about likely cause
Decide retry, hold, or abort
Decide whether to refresh blockhash
Decide whether to increase or recalculate tip
Decide whether to delay submission by some slots

K. Retry Executor Executes the AI decision safely.

Refresh blockhash if requested
Recalculate tip if requested
Rebuild and resign transaction
Wait delay slots if requested
Resubmit bundle
Append retry attempt to lifecycle logs

Blockhash Commitment Rule

Finalized blockhashes are older and reduce the usable lifetime of a transaction. For time-sensitive submissions, the system should use processed or confirmed commitment.

AI Agent Response

{
  "decision": "retry",
  "reason": "The transaction failed because the blockhash expired before landing.",
  "refreshBlockhash": true,
  "tipMultiplier": 1.2,
  "delaySlots": 0
}

5. Transaction Lifecycle Timeline

Submitted The bundle was sent to the Jito Block Engine. This only proves submission, not landing.

Processed A validator processed the transaction in a block. This is the fastest signal but lowest confidence.

Confirmed The cluster has voted enough on the block. This gives stronger confidence that the transaction landed on the main fork.

Finalized The block has become rooted and is very unlikely to be reverted.

submitted_to_processed_ms

processed_to_confirmed_ms

confirmed_to_finalized_ms

total_lifecycle_ms

6. Failure Recovery Loop

The system does not blindly retry. It retries based on observed context and AI-generated structured decisions.

Failure Detected

Failure Classifier

AI Agent Reasoning

Retry Decision

Refresh / Tip / Delay

Resubmit Bundle

Lifecycle Tracker

7. Fault Injection Demo

The required demo intentionally submits one transaction with a stale or expired blockhash.

Step	Expected flow
1	Build transaction with expired blockhash.
2	Submit bundle.
3	Transaction fails with blockhash expiry.
4	Failure classifier marks it as `expired_blockhash`.
5	AI agent receives failure context.
6	Agent decides to refresh blockhash, recalculate tip, and retry.
7	Retry executor rebuilds and resubmits.
8	Lifecycle tracker records the successful retry.

8. Lifecycle Log Format

Successful attempt:

{
  "runId": "run_001",
  "attempt": 1,
  "bundleId": "bundle_xxx",
  "signature": "tx_sig_xxx",
  "submittedAt": "2026-06-23T10:00:01.120Z",
  "submittedSlot": 344100001,
  "processedAt": "2026-06-23T10:00:01.530Z",
  "processedSlot": 344100002,
  "confirmedAt": "2026-06-23T10:00:02.410Z",
  "confirmedSlot": 344100003,
  "finalizedAt": "2026-06-23T10:00:14.900Z",
  "finalizedSlot": 344100035,
  "tipLamports": 12000,
  "submittedToProcessedMs": 410,
  "processedToConfirmedMs": 880,
  "confirmedToFinalizedMs": 12490,
  "failureClass": null,
  "agentDecision": null
}

Failed and retried attempt:

{
  "runId": "run_008",
  "attempt": 1,
  "failureClass": "expired_blockhash",
  "agentDecision": {
    "decision": "retry",
    "reason": "The blockhash expired before landing. Refresh blockhash and resubmit.",
    "refreshBlockhash": true,
    "tipMultiplier": 1.2,
    "delaySlots": 0
  }
}

9. README Questions

What does the delta between `processed_at` and `confirmed_at` tell you about network health at the time of submission?

The delta between processed_at and confirmed_at shows how quickly the network moved from local block processing to broader vote confirmation. A small delta suggests healthy propagation and voting. A large delta can indicate congestion, slow propagation, fork uncertainty, skipped slots, or validator voting delays.

Why should you never use finalized commitment when fetching a blockhash for a time-sensitive transaction?

Finalized commitment gives an older blockhash because it waits for the block to become rooted. For time-sensitive transactions, an older blockhash reduces the remaining lifetime before expiry. Processed or confirmed commitment gives a fresher blockhash and more time for the transaction to land.

What happens to your bundle if the Jito leader skips their slot?

If the Jito leader skips their slot, the bundle may not land in that slot. The system must detect that the transaction did not progress, refresh the blockhash if expiry risk increases, recalculate the tip, and resubmit during another valid leader window.

10. Infrastructure Decisions

Modular monolithUsed instead of microservices because this is a 7-day infra prototype.

JSONL logsUsed instead of a database because append-only logs are easy to verify and submit.

Yellowstone streamingUsed instead of RPC-only polling because the bounty requires stream-based confirmation.

Separated AI agentKept outside signing logic for safety and clean architecture.

CLI-first demoUsed because it is easier to reproduce and judge.

11. Limitations and Future Improvements

Add optional external analytics export while retaining JSONL as the proof source.
Add dashboard for live lifecycle visualization.
Add more advanced tip percentile modeling.
Add support for more transaction types.
Add validator/leader performance scoring.
Add alerting for abnormal confirmation latency.

SlotPilot

On this page