Trenchbird

Trenchbird is a local-first execution evidence recorder for Solana swaps.

It acts like a flight recorder around the swap lifecycle: preserving what was requested, what the provider claimed, what transaction was produced, what was externally signed, what happened on-chain, and how the result differed from expectations.

Trenchbird does not sign, submit, approve, reject, authorize, or decide whether a transaction should happen.

Signing and submission occur outside Trenchbird. Credentials granting execution authority never cross the Trenchbird boundary. Unknown, partial, incomplete, and not_evaluated outcomes remain valid evidence results where defined.

Who it is for: agents and programmatic Solana/Jupiter execution systems that need durable, inspectable lifecycle evidence—plus developers inspecting recorded evidence. Trenchbird is not a consumer-wallet companion, trading agent, or policy gate.

v1 scope: Solana swaps through Jupiter.
Package: @trenchbird/cli · CLI: tb · License: MIT
Repository: TrenchBird/trenchbird-cli

Why this exists

Provider responses, explorers, and wallets each show part of a swap. Relating intent → claims → prepared bytes → signatures → on-chain outcome usually requires manual glue and memory. Trenchbird records those relationships as durable, inspectable artifacts for humans and agents—without becoming a wallet, router, trading agent, or policy gate.

Lifecycle

The CLI lifecycle is intentionally segmented because signing and submission occur outside Trenchbird. Trenchbird records and links each handoff; it does not collapse those steps into a single “execute for me” command.

Intent
→ Provider Claims
→ Unsigned Transaction
→ Available Inspection
→ External Signing          ← outside Trenchbird
→ Signed-Message Verification
→ External Execution Evidence  ← outside Trenchbird (submit/confirm)
→ Expected vs Actual

What Trenchbird records

Stage	Evidence role
Intent	What was requested (amounts, mints, IDs)
Provider claims	What Jupiter asserted (including route claims)
Unsigned transaction	Exact prepared wire preserved for handoff
Inspection	What could be observed from those bytes
External signing	Caller supplies signed bytes; Trenchbird does not sign
Signed-message verification	Message continuity and observable signature completeness
Execution evidence	Externally supplied confirmation / failure evidence
Expected vs actual	Difference-only comparisons where axes can be evaluated

Trenchbird persists a documented projection of provider claims while separately digest-binding the full supported non-secret captured request and response. Projection completeness and capture integrity are distinct. Provenance integrity does not prove Jupiter origin, authenticated transport, one HTTP session, or that provider claims were true.

What Trenchbird does not do

• Load private keys, seed phrases, mnemonics, or keypair files
• Sign transactions or call wallet APIs
• Submit transactions (sendRawTransaction, Jupiter /execute, etc.)
• Accept API/Jupiter credentials, bearer tokens, RPC credentials, or cookies as supported inputs
• Approve, reject, authorize, score, rank providers, or enforce policy

Synthetic evidence sketch

Illustrative (not live operator data)—values show the kind of fields you get:

requested input:     1000000 (lamports)
provider expected:   142500000 (USDC base units claim)
actual output:       142480000 (derived from confirmed balances)
difference:          -20000 (actual − expected)
signed-message:      messageUnchanged + fullySigned where observable
route comparison:    partially_evaluated (completeness only —
                     not venue / “executed through” proof)

Account presence, instruction-account reference, and invoked-program identity are separate relationships. Do not read them as venue proof.

Quick start

Requires Node.js 20+ and npm.

npm install -g @trenchbird/cli
tb --version
tb --help

For source development (clone, npm ci, typecheck/build/test), see CONTRIBUTING.md.

Offline lifecycle (CLI)

Primary audience: agents and programmatic Solana execution systems that need durable execution evidence. Secondary: developers inspecting recorded evidence.

tb import-order                         # /order JSON → tb.prepare-request.v1
tb prepare --request … --out …          # → tb.prepared-operation.v2
→ external signing (outside Trenchbird)
tb verify-signed … --out …              # → tb.signed-operation.v1
→ external submission / confirmation (outside Trenchbird)
tb normalize-confirmed-transaction …    # optional: flatten RPC → fixture
tb import-confirmed-execution … --out …
tb link-lifecycle … --out …             # → tb.lifecycle-linkage-artifact.v2

Live prepare may optionally emit lifecycle peers in one acquisition (--intent-out + --provider-order-out, both-or-neither). Default remains prepared-only. Jupiter orders are short-lived; re-prepare if expired — Trenchbird does not refresh or requote. --minimum-output is a local intent/comparison floor, not Jupiter slippage.

Confirmed-execution import binding modes (exactly one):

• Path A: --signed-operation — identity from signed-operation (identityDigestProvenance: from_signed_operation)
• Path B: --prepared + --confirmed-wire (Base64) — identity from confirmed wire (identityDigestProvenance: from_confirmed_wire)

Equal digests do not collapse Path B into Path A.

Lifecycle linkage (tb link-lifecycle) emits tb.lifecycle-linkage-artifact.v2:

• Path A: supply --signed-operation (or --signed-verification); completeness still follows the four primary edges only
• Path B: omit signed-operation only when CE has identityDigestProvenance: from_confirmed_wire and a messageDigest; records additive preparedToConfirmed.messageIdentity; emits PRE_SUBMIT_SIGNED_TRANSACTION_NOT_OBSERVED; recordingCompleteness stays partial; sources.signedVerification is structurally absent

Optional: tb import-submission-evidence records failed external submission/preflight (not a lifecycle peer).

See examples/ for synthetic handoff files (including metadata.json) and docs/offline-lifecycle-workflow.md.

Machine contract (Model B)

Artifact-producing commands require --out. Ordering: construct → write durable body → emit success.

With --json, stdout is a summary envelope only (status, digests, absolute outputPath, …)—not a nested full artifact. Agents must read outputPath, load the file, and chain paths.

Why not just an explorer / Jupiter response / wallet history / simulator?

Source	What it shows	What it usually does not bind
Explorer	Confirmed on-chain facts	Original intent, provider claim package, prepared unsigned identity
Jupiter /order response	Provider claims + optional transaction	Independent confirmation, signed-message continuity, expected-vs-actual
Wallet history	User-facing activity	Provider claim digests, prepare↔sign continuity, structured comparisons
Transaction simulator / preflight	Likely execution / error hints	Intent↔provider↔prepared↔signed↔confirmed package linkage

Trenchbird preserves relationships across those layers as versioned evidence—not a substitute for any one of them.

Evidence limitations / non-claims

• Incomplete inspection and routeTransparency: unknown are successful recordings with limits—not rejections.
• Digests of captured non-secret components are not proof of authenticated transport or claim truth.
• Economic and route comparison axes may remain not_evaluated or partially_evaluated while other facts verify.
• Partial inspection / linkage outcomes remain valid success recordings where integrity verifies.

Governing docs: PROJECT_PRINCIPLES.md, docs/evidence-engine.md, SECURITY.md.

Documentation

Start at docs/README.md.

Contributing / security / license

• Contributing: CONTRIBUTING.md · agent rules: AGENTS.md
• Security: SECURITY.md (GitHub private vulnerability reporting / Security Advisories when available)
• License: LICENSE (MIT)