Argus.

System architecture

Two runtimes, one contract. A Rust Core holds every deterministic, network-facing concern. A TypeScript Agent holds a single judgment call. They speak only over HTTP/JSON — and that process boundary is the challenge's required clean separation between AI layer and core stack, made literal.

Rust earns its place on the Yellowstone gRPC firehose: tokio gives idiomatic bounded-channel backpressure and reconnection — the one genuinely hard feature the brief names. TypeScript hosts the agent for LLM ergonomics and fast prompt iteration. Neither leaks into the other. ADR 0001

flowchart LR
  subgraph EXT["External infrastructure"]
    direction TB
    YS["SolInfra Yellowstone gRPC
slot + tx streams"]
    RPC["SolInfra RPC
blockhash · simulate"]
    SE["Jito searcher gRPC
next leader"]
    TF["Jito tip floor"]
    BE["Jito block engine
sendBundle · 8 regions"]
    OR["OpenRouter
model access"]
    SOL["Solana mainnet"]
  end
  subgraph CORE["Core — Rust · the eyes"]
    direction TB
    STR["streaming"]
    LDR["leader"]
    TIP["tip"]
    BDL["bundle"]
    LFC["lifecycle"]
    FAIL["failure / classify"]
    ACL["agent_client"]
    DB[("SQLite")]
  end
  subgraph AG["Agent — TS · the judgment"]
    direction TB
    HTTP["/decide · /health/"]
    DEC["decide()"]
  end
  YS --> STR --> LFC --> DB
  RPC --> FAIL
  SE --> LDR
  TF --> TIP
  TIP --> BDL
  LDR -.timing.-> BDL
  BDL --> BE --> SOL
  FAIL --> ACL
  ACL -->|"raw failure surface"| HTTP --> DEC --> OR
  ACL --> DB
      

Deployment

• Layout: core/ (Rust), agent/ (TypeScript), docs/ (ADRs + plan), logs/ (SQLite + JSONL + Markdown Lifecycle Log).
• Mainnet for the real path with SolInfra credits and a dedicated low-balance keypair — Jito only lands bundles on mainnet, and judges verify slots on explorers. Devnet is a sandbox only. ADR 0002
• One contract: a scored run hard-gates on the agent's /health and refuses to start if it is down.

Key components

Core (Rust) — deterministic, network-facing

Agent (TypeScript) — the single judgment

• index.ts — Express service: GET /health, POST /decide (zod-validated), port 8787.
• decide.ts — the OpenRouter call: prompt, reasoning request, submit_decision tool parse.
• types.ts — zod schemas mirroring the Rust types (snake_case).

Storage — the Lifecycle Log is the deliverable

A Run is a prefix, not a column: the session is run-{ts} and payload k runs under child run_id = run-{ts}-p{k} — unique keys, zero schema change. ADR 0011

Data flow between services

Happy path — submit, track, persist

The subscription opens before the bundle is sent, so inclusion is never missed; tracking is reconciled afterward against getSignatureStatuses in case a Landed frame is dropped.

sequenceDiagram
  autonumber
  participant O as Orchestrator
  participant B as bundle
  participant J as Jito
  participant Y as Yellowstone
  participant DB as SQLite
  O->>B: build_bundle(payload, tip)
  O->>DB: record_submission
  O->>Y: subscribe slot + tx — before submit
  Y-->>O: on_subscribed
  O->>J: submit_all_regions
  Y-->>O: Landed (slot)
  O->>DB: set_landed_slot
  Y-->>O: Processed → Confirmed → Finalized
  O->>DB: mark_stage
      

The lifecycle, measured

One submission's progression on mainnet, with the real deltas from the graded run. Two adjacent deltas, two orders of magnitude apart, measuring different physics.

Failure path — diagnose, remedy, resubmit

A Jito bundle is all-or-nothing, so a faulted transaction never lands and leaves no on-chain error. The one deterministic pre-submit source of truth is a preflight simulateTransaction — and that output is the raw surface handed to the agent.

sequenceDiagram
  autonumber
  participant O as injection_run
  participant R as rpc.simulate
  participant A as Agent → OpenRouter
  participant DB as SQLite
  O->>R: simulateTransaction
  R-->>O: err · instruction_error · logs
  O->>A: POST /decide (raw surface, no failure_class)
  A-->>O: diagnosis · triage · remedy · trace
  O->>DB: record_decision (agent + baseline)
  alt remedy = abort
    O-->>O: stop — no retry
  else recoverable
    O->>O: attempt-2 (fresh blockhash / raised CU)
  end
      

Infrastructure decisions

Every decision is recorded as an ADR in the repo. The load-bearing ones:

Failure handling strategy

Failure is the heart of the system — happy-path-only submissions are disqualified. Argus handles it on two axes: a bounded four-class baseline for remedy variation, and an unbounded program-error tail for diagnosis variation.

The bounded baseline — four classes

The unbounded tail — where a classifier goes blind

One identical malformed instruction — [0xff; 8], zero accounts — sent to three different real programs produces three distinct errors. The four-class baseline collapses all three to one verdict. The agent does not.

Click each failure below ↓  The baseline on the left never moves — it's blind. The agent on the right names a different cause every time.

Retry, recovery, degradation

• Remedy execution stays in Core. The agent names the remedy; Core owns the magnitudes — e.g. the raised CU limit comes from a max-CU re-simulation, not a tuned constant.
• Attempt-2 is seeded clean, so a remedy is tested honestly rather than inheriting the injected fault.
• Loud degradation. If the agent is unreachable within ~45s, Core falls back to the baseline and records model="local-fallback" — visible in the log, never silent.

AI agent responsibilities

The agent owns exactly one operational decision — failure diagnosis. It observes a failed transaction, reasons about why it failed, and decides what must change before retrying. Retry decisions come from the agent, not from hardcoded logic.

The contract

Triage — the axis the agent reasons on

The honesty boundary: on a permanent failure the agent and the baseline both abort — the agent's value there is the reason, not a different action. It is graded on the diagnoses a lookup can't produce, not on theatrical disagreement. ADR 0012

Operational evidence

From the graded mainnet run run-1781958744615, committed to the repo as logs/lifecycle-1781958744615.{md,jsonl}.

The graded run — every submission, explorable

All 15 real submissions from run-1781958744615. Faulted rows expand to the agent's diagnosis, triage, and full reasoning trace; landed rows show the commitment deltas drawn to scale.

Four payloads the baseline collapses to one verdict drew four distinct diagnoses. The two recoverable injections — expired blockhash (aged 200 slots, conf. 0.99) and compute exceeded (cu_limit=1, conf. 0.99) — were triaged and landed on attempt 2 (slots 427724252, 427724375). Every decision carried a non-empty reasoning trace.

The three required questions, from this run

Decision record

Full context and consequences live in the repository under docs/adr/.