CLI Reference - Sinker

Overview

sinker is a single binary that starts the transaction sidecar and provides developer commands for inspecting its live state. No separate installation required — build once, use everywhere.

cd sinker
cargo build --release
./target/release/sinker --help

Sidecar commands

`sinker up`

Start the full stack — sidecar and AI agent (Synapse) together in a single terminal. Both processes share stdout; agent lines are prefixed with [ AGENT ] to keep the streams readable.

sinker up

This is the recommended command for normal development and production. The Synapse layer connects to the sidecar via /internal/agent/presence on startup, registers its model/provider, and begins driving submissions.

`sinker start`

Start the sidecar only — without spawning the AI agent. The sidecar streams slots, maintains the tip oracle and leader buffer, and exposes the HTTP API. The Synapse agent must be started separately (e.g. sinker agent in another terminal).

sinker start

Decision mode defaults to cortex (LLM on every submission). Set AGENT_DECISION_MODE=reflex in .env to boot in reflex mode, or flip at runtime via POST /internal/mode.

`sinker start --bypass`

Skip the AI agent entirely. Submits transactions at a fixed tip the instant they are enqueued. Useful for testing the frontend → sidecar → Jito path without the AI layer.

sinker start --bypass
sinker start --bypass --tip 50000

Flag	Description
`--bypass`	Disable Synapse; submit immediately on each `tx_enqueued` event
`--tip <lamports>`	Fixed tip in lamports (default: `10000`). Only used with `--bypass`.

`sinker agent`

Start the Synapse TypeScript agent in a separate process. Runs npm run dev inside the agents/ directory (override with AGENT_DIR env var).

sinker agent

`sinker web`

Start the Next.js dashboard. Runs npm run dev inside the web/ directory (override with WEB_DIR env var).

sinker web

`sinker smoke`

Run the stream_smoke integration test — connects to Yellowstone, waits for a Jito leader window, submits one bundle, and polls until finalization.

sinker smoke

Inspect commands

Inspect commands query a running sidecar at http://localhost:{API_PORT} (default 7777). Start the sidecar first with sinker start or sinker up.

`sinker status`

Print a summary of the current sidecar state: slot, leader identity, whether the current leader is running Jito, tip floor (p50/p75), active decision mode, and pending queue depth.

$ sinker status
┌─ Sidecar Status ─────────────────────────────────
│  slot         : 318456201
│  leader       : 9xRc…
│  jito leader  : true
│  tip p50      : 9850 lamports
│  tip p75      : 14200 lamports
│  stale        : false
│  queue        : 0 pending tx(s)
└──────────────────────────────────────────────────

`sinker tip`

Print the full tip floor percentile table.

$ sinker tip
┌─ Tip Floor Percentiles ──────────────────────────
│  p25  :       6500 lamports
│  p50  :       9850 lamports
│  p75  :      14200 lamports
│  p95  :      31000 lamports
│  p99  :      75000 lamports
│  ema  :       9200 lamports
│  stale: false
└──────────────────────────────────────────────────

`sinker queue`

Print the pending transaction queue contents with age and priority.

$ sinker queue
pending: 2  (evicted_total: 0)
  tx_id=3fa2…  age=3slots  priority=normal
  tx_id=7b1c…  age=1slots  priority=high

`sinker lifecycle`

Print recent bundle lifecycle history. Shows the most recent 10 entries by default.

sinker lifecycle
sinker lifecycle --last 25

showing 3/3 entries (most recent last):
bundle_id             stage       slot          failure     tip
──────────────────────────────────────────────────────────────────────
8f3a1b2c4d5e6f70      finalized   318456120     —           9850L
2e7d4c3b1a0f9e8d      failed      318456185     fee_too_low  8000L
5c9a2f1e8b4d3c70      finalized   318456198     —           14200L

Each entry shows the decision tier (reflex / cortex) and whether the Reflex path escalated to the LLM.

Flag	Description
`--last N` / `-l N`	Number of entries to show (default: 10)

`sinker bundle <id>`

Print the full JSON lifecycle entry for a specific bundle, including the AI decision trace, commitment timeline (submitted → processed → confirmed → finalized), tip floor at submit time, and all transaction signatures.

sinker bundle 8f3a1b2c4d5e6f70abcdef1234567890abcdef12

{
  "bundle_id": "8f3a1b2c4d5e6f70…",
  "stage": "finalized",
  "slot_submitted": 318456120,
  "tip_lamports": 9850,
  "decision_mode": "reflex",
  "escalated": false,
  "submitted_to_processed_ms": 412,
  "processed_to_confirmed_ms": 389,
  "confirmed_to_finalized_ms": 478,
  "transactions": ["5xKp…"],
  "ai_decision_trace": null
}

Policy commands

sinker policy gates what the Synapse agent is allowed to do — tip caps, retry limits, queue depth, and throughput controls. Settings persist in sinker.policy.json between restarts.

sinker policy show                        # print all values and override status
sinker policy set max-tip 200000          # hard ceiling on tip size
sinker policy set tip-percentile p95      # target a higher percentile
sinker policy set max-retries 5           # retry up to 5 times before expiry
sinker policy set expiry-slots 150        # drop bundles older than 150 slots
sinker policy set escalation-step 5000   # max tip increase per retry (lamports)
sinker policy set max-queue 10            # reject enqueues above 10 in-flight
sinker policy set rate-limit 30           # max 30 tx/min across all callers
sinker policy set priority high           # pin all bundles to high priority
sinker policy validate                    # check for contradictions
sinker policy reset max-tip               # reset one key to built-in default
sinker policy reset                       # reset all keys
sinker policy clear                       # delete file, revert all to defaults
sinker policy export --path ./prod.json  # save resolved policy for sharing
sinker policy import ./prod.json          # apply a saved policy

Policy reference →

Full reference for all 10 policy keys and 7 sub-commands.

The Synapse AI layer

Sinker’s AI layer — Synapse — is the decision junction that evaluates each transaction cycle and routes it to one of two tiers:

Tier	Trigger	Behaviour	Measured latency
Reflex	Every cycle (if `AGENT_DECISION_MODE=reflex`)	Deterministic fast-path: reads tip oracle, applies policy, submits. Escalates to the LLM only on hard cases (stale tip, fee rejection, escalation).	~374 ms decision
Cortex	Every cycle (default)	LLM called on every submission. Full reasoning trace attached to the lifecycle entry. Highest accuracy; slower.	~4,200 ms decision

Both tiers are LLM-backed. Reflex routes most cycles deterministically and only calls the model when it encounters an edge case. Cortex calls the model unconditionally.

Switching modes at runtime

# Via environment variable at startup
AGENT_DECISION_MODE=reflex sinker start

# Via API while running (no restart required)
curl -X POST http://localhost:7777/internal/mode \
  -H 'Content-Type: application/json' \
  -d '{"decision_mode": "reflex"}'

# Check current mode
curl http://localhost:7777/internal/mode

Agent presence

The Synapse agent keeps a persistent SSE connection open to /internal/agent/presence. When it connects, it registers its model and provider. Check agent status:

curl http://localhost:7777/internal/agent/info
# {"model": "claude-opus-4-8", "provider": "anthropic"}

Environment variables

Variable	Default	Description
`YELLOWSTONE_ENDPOINT`	required	Yellowstone gRPC endpoint
`YELLOWSTONE_X_TOKEN`	—	Yellowstone auth token (if required)
`RPC_URL`	required	Solana RPC URL (mainnet Helius recommended)
`JITO_BLOCK_ENGINE_URL`	`mainnet.block-engine.jito.wtf`	Jito block engine
`JITO_UUID`	—	Jito auth UUID for higher rate limits
`KEYPAIR_PATH`	`~/.config/solana/id.json`	Path to signing keypair
`API_PORT`	`7777`	Sidecar API port
`AGENT_DECISION_MODE`	`cortex`	Boot decision tier: `cortex` or `reflex`
`BYPASS_AGENT`	`0`	Set `1` to enable bypass mode via env
`BYPASS_TIP_LAMPORTS`	`10000`	Fixed tip for bypass mode (lamports)
`AGENT_DIR`	`../agents`	Directory for `sinker agent`
`WEB_DIR`	`../web`	Directory for `sinker web`
`SINKER_POLICY_FILE`	`./sinker.policy.json`	Custom path for the policy file
`LIFECYCLE_PATH`	`./lifecycle.jsonl`	Path for the bundle audit log

​Overview

​Sidecar commands

​sinker up

​sinker start

​sinker start --bypass

​sinker agent

​sinker web

​sinker smoke

​Inspect commands

​sinker status

​sinker tip

​sinker queue

​sinker lifecycle

​sinker bundle <id>

​Policy commands