Skip to content

Getting Started

Jump to bottom
Murtaza Ali Imtiaz edited this page May 25, 2026 · 3 revisions

Getting Started

Prerequisites

Tool Minimum Version Install
Rust stable toolchain 1.85.0 rustup update stable
rustfmt (with toolchain) rustup component add rustfmt
clippy (with toolchain) rustup component add clippy
Anthropic API key - console.anthropic.com (only for --mode full)

ANTHROPIC_API_KEY is optional for most operations. All four individual modes, all integration tests, and all examples work without it. The key is only required when running the full rig-core agent pipeline (--mode full without --no-agent).

Solana CLI is not required. All on-chain operations use the solana-client crate directly via the devnet RPC endpoint.

Clone and build

git clone https://github.com/murtazaai/polar-bear-rig-onchain
cd polar-bear-rig-onchain

# Build - no API key needed
cargo build --release

To use the full agent pipeline, copy the env template and set your key:

cp .env.example .env
# Open .env and set ANTHROPIC_API_KEY=sk-ant-...

Recommended first run (no API key needed)

The --no-agent flag runs the complete pipeline - balance query, Jupiter quote, and SignerContext isolation - without constructing the Anthropic client:

cargo run --release -- --mode full --no-agent

Expected output:

╔══════════════════════════════════════════════════════════╗
║  FULL PIPELINE  ·  --no-agent  ·  No API key required   ║
╚══════════════════════════════════════════════════════════╝

── Step 1: Solana devnet balance ──────────────────────────
BalanceResult { address=4Nd1m..., lamports=..., sol=..., network=devnet }

── Step 2: Jupiter V6 dry-run quote ───────────────────────
JupiterQuote { in=100000000 lamports (0.100000 SOL) → out=... USDC, ..., DRY-RUN=true }

── Step 3: SignerContext isolation demo ────────────────────
INFO [SignerContext] task-local signer installed  label=demo-task-0  pubkey=<A>
INFO [SignerContext] task-local signer installed  label=demo-task-1  pubkey=<B>
INFO [SignerContext] task-local signer installed  label=demo-task-2  pubkey=<C>
INFO [SIGNER] All tasks complete. SignerContext isolation verified ✓

✓  polar-bear-rig-onchain pipeline complete (agent skipped).
   Network: devnet | Swap: DRY-RUN | Boundary: SEALED | Agent: SKIPPED

Run individual subsystems

Each subsystem can be exercised independently:

# Solana devnet balance query
cargo run --release -- --mode balance

# Jupiter V6 dry-run quote
cargo run --release -- --mode quote --amount 0.5

# SignerContext task-local isolation demo (3 concurrent tasks)
cargo run --release -- --mode signer

None of these require an Anthropic API key.

Run the full agent pipeline

Requires ANTHROPIC_API_KEY to be set in .env or the shell:

cargo run --release -- --mode full --wallet <DEVNET_ADDRESS> --amount 0.1

Replace <DEVNET_ADDRESS> with any valid Solana devnet base-58 address. If --wallet is omitted, the default devnet address from config.rs is used.

Expected output (abbreviated):

INFO  polar_bear_rig_onchain: Starting platform mode=Full wallet=... api_key_present=true
INFO  polar_bear_rig_onchain::onchain::signer: [SignerContext] task-local signer installed
INFO  polar_bear_rig_onchain::onchain::balance: [SolanaClient::query_balance] ✓ balance retrieved
INFO  polar_bear_rig_onchain::onchain::jupiter: [JupiterClient::get_quote] ✓ quote received [DRY-RUN]
INFO  polar_bear_rig_onchain::onchain::signer: [SignerContext] task-local signer evicted ✓

╔══════════════════════════════════════════════════════════╗
║  AGENT PIPELINE RESULT                                   ║
╚══════════════════════════════════════════════════════════╝

[Agent structured summary: balance, quote, isolation status]

✓  polar-bear-rig-onchain pipeline complete.
   Network: devnet | Swap: DRY-RUN | Boundary: SEALED

Run the standalone examples

These examples require no Anthropic API key and demonstrate individual subsystems:

cargo run --example balance_demo       # Solana devnet balance query
cargo run --example signer_demo        # SignerContext isolation across 3 concurrent tasks
cargo run --example jupiter_dry_run    # Jupiter V6 dry-run quote + IsolationReport

Run the tests

All integration tests are deterministic and require no API key:

# All tests
cargo test

# Per-module, with log output
cargo test --test test_balance         -- --nocapture
cargo test --test test_jupiter         -- --nocapture
cargo test --test test_signer_context  -- --nocapture

# Live provider tests (Anthropic API key required, opt-in only)
ANTHROPIC_API_KEY=sk-ant-... cargo test --test providers -- --ignored --test-threads=1 --nocapture

Format, lint, docs

cargo fmt --all                               # format in place
cargo fmt --all -- --check                   # CI-style: report drift without modifying
cargo clippy --all-targets -- -D warnings    # lint (must produce zero warnings)
cargo doc --open                             # browse generated API docs
cargo doc --open --document-private-items    # include internals

API key requirement at a glance

Invocation API key needed?
--mode full ✅ Yes - constructs the rig-core agent
--mode full --no-agent ❌ No - runs balance → quote → signer directly
--mode balance ❌ No
--mode quote ❌ No
--mode signer ❌ No
cargo test ❌ No - live provider tests are #[ignore]-gated
cargo run --example * ❌ No

Next steps

polar-bear-rig-onchain · Polar Bear (🍨) · Technology Lead: Murtaza Ali Imtiaz · PBS License

polar-bear-rig-onchain

🏠 Home

Getting Started

Design

Reference

Development

External

Clone this wiki locally