Home

polar-bear-rig-onchain Wiki

Polar Bear (🍨) · Technology Lead · Murtaza Ali Imtiaz · July 2019 – present Proprietary software - see LICENSE

polar-bear-rig-onchain is a production-grade Rust implementation of the rig-onchain-kit on-chain agent pattern. It demonstrates Solana devnet balance queries, Jupiter V6 dry-run swap quotes, and task-local SignerContext signer isolation via tokio::task_local!: the correct async-safe implementation of the rig-onchain-kit security boundary pattern.

---

Quick Links

Page	Description
Getting Started	Prerequisites, clone, build, first run (keyless)
CLI Reference	--mode flags, --no-agent, --wallet, --amount
Configuration	Environment variables and .env setup
Architecture	System design, module map, data-flow diagram
Module Reference	Per-module API overview (onchain, agent, config)
SignerContext and Security	tokio::task_local! isolation deep-dive
Testing	Running tests, live provider tests, coverage areas
Zed IDE	Task runner, debugger configs, rust-analyzer settings
Contributing	Dev workflow, code style, extending the agent
Changelog	Version history and bug-fix log

---

What this project demonstrates

CLI Entry (main.rs)
--mode [full|balance|quote|signer]  [--no-agent]
       │
       ├─ --mode full ──────────────────────────────── requires ANTHROPIC_API_KEY
       │   ┌──────────────────────────────────────┐
       │   │  rig-core Agent (claude-sonnet-4-6)  │──── SolanaBalanceTool
       │   │  PEV loop governance                 │     JupiterQuoteTool (dry-run)
       │   └──────────────────────────────────────┘     SignerIsolationTool
       │
       └─ --mode full --no-agent ───────────────── no API key needed
           balance → quote → signer (direct, no LLM)
       │
  ┌────┴───────────────────────────────┐
  │  onchain::signer                   │──── tokio::task_local! SignerContext
  │  with_signer(signer, f)            │     (task-scoped, not thread-scoped)
  ├────────────────────────────────────┤
  │  onchain::balance                  │──── Solana devnet RPC get_balance
  │  onchain::jupiter                  │──── Jupiter V6 /quote (read-only)
  └────────────────────────────────────┘

Key technical highlights

• tokio::task_local! signer isolation - every concurrent HFT task gets its own isolated keypair slot, preventing cross-task key contamination that thread_local! cannot prevent in an async runtime.
• Keyless operation - ANTHROPIC_API_KEY is only required for --mode full without --no-agent. All other modes, all tests, and all examples run without it.
• rig-core ≥ 0.36 compatibility - Client::new(api_key)? (fallible constructor); both CompletionClient + ProviderClient traits in scope for .agent() to resolve.
• Jupiter V6 dry-run guard - a runtime assert! in JupiterClient physically prevents any swap execution path, even if dry_run were somehow set to false.
• IsolationReport audit trail - serialisable JSON record of each signer lifecycle, designed as direct input to the Reactor GUI.
• Zero-warning build - passes cargo clippy --all-targets -- -D warnings with the Rust 2024 edition lint table.
• Fully configured Zed IDE - .zed/tasks.json (23 tasks), .zed/debug.json (9 CodeLLDB configs), and .zed/settings.json (rust-analyzer, format-on-save, inlay hints).

---

License

Published under the PBS License: portfolio and reference use only.