Nerve — AI-Native Solana Transaction Stack

Nerve is an autonomous pipeline that watches Solana devnet in real time via a GeyserBridge gRPC stream, builds and submits Jito bundles with dynamic tips, tracks every bundle through its lifecycle, and uses an LLM agent (OpenRouter, free model) to make retry and tip decisions on failure.

Built for the Superteam Nigeria Advanced Infrastructure Challenge — $2,500 USDC bounty.

Architecture

GeyserBridge (gRPC) → Stream Client → Leader Tracker → Bundle Builder → Submission Manager → Jito Block Engine
                          ↓                                                    ↓
                    SQLite DB ← Lifecycle Tracker                    AI Agent (OpenRouter)
                          ↓                                                    ↓
                    Fastify API ← → Dashboard (HTML)               Fault Injector

See the Architecture Documentation for the full diagram and component breakdown.

Quick Start

# Prerequisites: Node 20+, a Solana wallet with devnet SOL, OpenRouter API key
# GeyserBridge running at localhost:10000 (or set YELLOWSTONE_GRPC_URL)

cp .env.example .env
# Fill in: SOLANA_RPC_URL, WALLET_PRIVATE_KEY, OPENROUTER_API_KEY

npm install
npx tsx src/index.ts

Open http://localhost:3000/dashboard for the real-time dashboard.

Features

Feature	Description
GeyserBridge Streaming	Real-time slot data via Yellowstone gRPC (raw @grpc/grpc-js + proto-loader)
Jito Bundle Submission	Builds + submits bundles via jito-ts, fetches tip accounts from block-engine
Dynamic Tip Calculator	Rule-based: adjusts tip based on landing ratio, congestion, and failure count
Lifecycle Tracking	submitted → processed → confirmed → finalized, stored in SQLite
AI Retry Agent	On failure, calls OpenRouter (free model) to reason about the error and recommend action
AI Tip Agent	Optional LLM-based tip optimization above the rule-based calculator
Fault Injection	/inject/enable to insert synthetic errors (blockhash expiry, low fee, compute exceeded, bundle rejection)
Real-time Dashboard	Self-contained HTML at /dashboard, auto-refresh 3s, no build step
Bundle Comparison	Dynamic vs fixed tip results in docs/comparison.md

API Endpoints

• GET /dashboard — Real-time HTML dashboard
• GET /status — Pipeline status (slots, bundles, AI actions)
• GET /bundles — Bundle logs
• GET /lifecycle — Judge-ready lifecycle log (slot numbers, commitment progression, timestamps, tip amounts, failure classifications)
• GET /ai/actions — AI agent reasoning traces
• POST /inject/enable — Enable fault injection
• POST /inject/disable — Disable fault injection
• POST /inject/scenario — Set fault scenario
• POST /inject/fire — Enable fault + trigger immediate submission

Bounty Deliverables

• Architecture Documentation — Full system architecture on Notion
• Bounty Questions Answered — 3 questions answered with real observations
• Lifecycle Log — JSON endpoint with 190+ bundles, real devnet slot numbers, commitment progression, timestamps, tip amounts, and failure classifications. Slots cross-referenceable on Solana devnet explorer.
• AI Agent Reasoning Traces — 11 AI agent reasoning traces from fault-injection runs
• Bundle Comparison — Dynamic vs fixed tip comparison (16 bundles each)
• Deployment Guide — Infrastructure requirements, cost breakdown, and deployment checklist
• Video Demo — Link TBD (ongoing)

Tests

npm test        # 20 tests (classifier + tip-calculator)
npx tsc --noEmit  # type check

Configuration

Env Var	Description
YELLOWSTONE_GRPC_URL	GeyserBridge gRPC endpoint (default: http://localhost:10000)
SOLANA_RPC_URL	Solana RPC (default: https://api.devnet.solana.com)
JITO_BLOCK_ENGINE_URL	Jito block engine (default: dallas.testnet.block-engine.jito.wtf:443)
WALLET_PRIVATE_KEY	Base58-encoded private key
OPENROUTER_API_KEY	OpenRouter API key
ADMIN_KEY	GeyserBridge auth token

License

MIT