Home

polar-bear-rig-onchain Wiki

Polar Bear Systems · Technology Lead: Murtaza Ali Imtiaz

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, run
Architecture	System design, module map, data-flow diagram
Configuration	Environment variables and .env setup
CLI Reference	--mode flags, --wallet, --amount
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
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]
       │
┌──────┴──────────────────────────────────┐
│  onchain::signer                        │──── tokio::task_local! SignerContext
│  with_signer(signer, f)                 │     (task-scoped, not thread-scoped)
└──────┬──────────────────────────────────┘
       │
┌──────┴──────────────────────────────────┐
│  rig-core Agent (claude-sonnet-4-6)     │──── SolanaBalanceTool
│  PEV loop governance                    │     JupiterQuoteTool (dry-run)
│                                         │     SignerIsolationTool
└──────┬──────────────────────────────────┘
       │
┌──────┴──────────────────────────────────┐
│  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.
• rig-core ≥ 0.36 compatibility — Client::new(api_key)? (fallible), both CompletionClient + ProviderClient traits in scope.
• 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.

---

License

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