ambient-blockchain

name	ambient-blockchain
description	Safely observe the Ambient Blockchain, plan Tool Oracle and x402 interactions, prepare Ambient program deployment work, and run local live-test evidence gates.

Ambient Blockchain Adapter

Use this capability when the user wants Ambient Desktop or Pi to inspect Ambient chain state, plan funded Tool Oracle requests, work with x402 endpoints, scaffold/validate Ambient program deployment work, or collect live evidence for this blockchain integration.

Discovery And Setup

• Find this package with ambient_cli_search using terms like Ambient Blockchain, Solana RPC, Tool Oracle, x402, program deploy, or live gate.
• Call ambient_cli_describe before first use so the exact commands, env bindings, and safety gates are visible.
• Run ambient_chain_doctor --json before other commands. The health check is deterministic and does not touch the network unless --network is passed.
• Safe live-read is the default live lane: ambient_blockchain_live_gate --live-read --json tests getHealth, getVersion, and getSlot without secrets or spend.
• The default RPC is http://rpc.ambient.xyz:8899/; set AMBIENT_BLOCKCHAIN_RPC_URL only when a local or alternate Ambient-compatible endpoint is intended.
• Keypair env bindings are acceptable for now, but treat them like browser/Electron wallet secrets: bind through Ambient-managed secret/file flows, never paste key material into chat, and only use signer-backed lanes after explicit spend approval.
• Use ambient_keypair_status --json before any signer-backed plan. It reports configured booleans, path hashes, file metadata, and public keys only; it never prints keypair paths or private bytes.
• Use ambient_approval_verify --plan-artifact <path> --approval-sha256 <sha> --require-signer --json immediately before any submit, payment, deploy, upgrade, or authority command.

Commands

• ambient_chain_doctor --json: reports package readiness, pinned contract IDs, env configured booleans, and live-test lanes. Add --network to probe read-only RPC reachability.
• ambient_chain_rpc --method <read-only-method> --params-json '<json-array>' --json: calls an allowlisted read-only JSON-RPC method and writes the full response under .ambient/blockchain/rpc/.
• ambient_chain_account --address <pubkey> --json: reads native lamport balance and account metadata, then writes full evidence under .ambient/blockchain/account/.
• ambient_chain_validators --json [--limit <n>]: lists validator identities and vote accounts through read-only RPC, then writes full evidence under .ambient/blockchain/validators/. Use an identity value from the preview as a funded demo address for ambient_chain_account.
• ambient_chain_token_balances --owner <pubkey> --json [--mint <pubkey>]: reads SPL-style token accounts and parsed token balances for an owner address, then writes full evidence under .ambient/blockchain/token-balances/. Use --program-id <pubkey> only for a nonstandard token program scan.
• ambient_chain_transaction --signature <sig> --json: reads one transaction, summarizes status and logs, and writes the raw response under .ambient/blockchain/transaction/. Use --address <pubkey> --limit <n> instead to list recent signatures for an address.
• ambient_chain_program_observe --program-id <pubkey> --filters-json '<json-array>' --json: reads program accounts with bounded data slices, account summaries, and a full artifact. Use --allow-unfiltered only when the user explicitly wants a broad scan.
• ambient_keypair_status --json [--kind chain|x402]: validates signer bindings without exposing paths or secrets, and writes the same redacted status under .ambient/blockchain/keypair/.
• ambient_approval_verify --plan-artifact <path> --approval-sha256 <sha> --json: recomputes a plan approval digest, checks optional cap bounds, and optionally verifies the current signer still matches the plan. This command does not sign or submit anything.
• ambient_auction_inspect --json [--account <pubkey>]: returns pinned Auction and Tool Oracle contract metadata; with --account, verifies one account owner through read-only RPC.
• ambient_oracle_request_plan --prompt <text> --escrow-lamports <n> --json: creates a non-mutating Tool Oracle funded-request plan with prompt hash, caps, approval digest/copy, signer summary, and evidence artifact.
• ambient_oracle_request_submit --plan-artifact <path> --approval-sha256 <sha> --max-lamports <n> --require-signer --client-command-json '<json-array>' --json: submits an approved Tool Oracle request through an explicit client command template. Supported placeholders include <KEYPAIR_FILE>, <RPC_URL>, <WS_URL>, <PROMPT_FILE>, <ESCROW_LAMPORTS>, <MAX_RESPONSES>, and <FILTER>; signer path, prompt text, and prompt-file path are redacted from output artifacts.
• ambient_oracle_request_wait --submit-artifact <path> --max-attempts <n> --json: polls the request account with read-only RPC and writes every observation plus bounded decoded state evidence.
• ambient_oracle_response_decode --wait-artifact <path> --json: decodes preserved Tool Oracle account data from a wait/account artifact or --data-base64 payload.
• ambient_oracle_reclaim_plan --submit-artifact <path> --json: creates a non-mutating cleanup plan for reclaiming lamports from a completed or failed request account.
• ambient_oracle_reclaim_execute --plan-artifact <path> --approval-sha256 <sha> --max-lamports <n> --require-signer --client-command-json '<json-array>' --json: executes approved cleanup through an explicit client command template with <REQUEST_ACCOUNT>, <KEYPAIR_FILE>, and <RPC_URL> placeholders.
• ambient_x402_quote --endpoint <url> --max-micro-usdc <n> --json [--live]: prepares an x402 quote/payment plan with separate lamport and micro-USDC caps; --live may probe for payment metadata but still does not submit payment.
• ambient_x402_request_execute --quote-artifact <path> --approval-sha256 <sha> --max-lamports <n> --max-micro-usdc <n> --payment-header-file <path> --json: executes an approved x402 paid HTTP request using a one-use payment header file. It replays approval, cap, method, endpoint, and signer checks, captures receipt headers and full response body, and redacts the payment header.
• ambient_program_doctor --json: checks local Rust/Solana/Anchor toolchain readiness without installing anything.
• ambient_program_scaffold --project-dir <dir> --template native-rust|anchor|oracle-client|auction-cpi --json: writes a local program workbench project. The default native-rust template is dependency-free and suitable for offline build/test validation.
• ambient_program_build --project-dir <dir> --json: runs cargo build, preserves full stdout/stderr in .ambient/blockchain/program/, and returns bounded previews.
• ambient_program_test --project-dir <dir> --json: runs cargo test, preserves full stdout/stderr in .ambient/blockchain/program/, and returns bounded previews.
• ambient_program_deploy_plan --binary <path> --json: hashes a local program artifact and produces a non-mutating deployment plan with signer and lamport gates.
• ambient_program_deploy_execute --plan-artifact <path> --approval-sha256 <sha> --max-lamports <n> --require-signer --json: executes an approved Solana CLI program deploy only after approval verification, binary hash replay, lamport cap replay, and signer binding checks. It preserves full redacted stdout/stderr, signature, and command evidence under .ambient/blockchain/program/.
• ambient_program_upgrade_plan --program-id <pubkey> --binary <path> --json: hashes a local program artifact and produces a non-mutating upgrade plan for an existing program id.
• ambient_program_upgrade_execute --plan-artifact <path> --approval-sha256 <sha> --max-lamports <n> --require-signer --json: executes an approved Solana CLI program upgrade only after approval verification, binary hash replay, lamport cap replay, and signer binding checks.
• ambient_program_authority_plan --program-id <pubkey> --new-authority <pubkey> --json: creates a non-mutating upgrade-authority change plan. Use --final instead of --new-authority only when the user explicitly wants irreversible authority removal.
• ambient_program_authority_execute --plan-artifact <path> --approval-sha256 <sha> --max-lamports <n> --require-signer --json: executes an approved upgrade-authority change with redacted signer evidence.
• ambient_local_validator_gate --json [--start-validator]: checks local solana-test-validator readiness, or starts/stops a bounded validator lifecycle only when explicitly requested, preserving logs and redacting ledger paths.
• ambient_desktop_pi_dogfood --json: runs deterministic package discovery dogfood for Desktop/Pi without network, secrets, signing, or spend. It verifies the manifest, skill discovery flow, safety gates, and local doctor health check, then writes evidence under .ambient/blockchain/dogfood/.
• ambient_blockchain_live_gate --json: runs the local release gate and writes JSON plus Markdown evidence. Add --desktop-pi, --live-read, --x402, --oracle, --program, or --local-validator to exercise those lanes. Add --oracle-funded only when the user explicitly approves a low-escrow Tool Oracle submit/wait/decode/reclaim lifecycle with signer and caps configured; use --oracle-fake-wait only for deterministic local evidence. Add --x402-paid only when the user explicitly approves a capped paid request with signer and one-use payment header configured. Add --program-lifecycle to scaffold/build/test a local workbench; add --program-deploy only when the user explicitly approves a capped deploy with signer configured; add --program-observe to collect bounded read-only post-deploy observation evidence. Add --start-validator only for an opt-in validator lifecycle.

Live Testing Expectations

• Always collect immutable local evidence for live work. Use .ambient/blockchain/live-gate/ for release-gate JSON/Markdown reports and command-specific subdirectories for raw RPC, account, x402, oracle, validator, and program artifacts.
• Live-gate reports include an evidenceIndex with per-lane artifact references, signatures, receipts, and cost/cap summaries. Use it first when reporting what a live run proved.
• Desktop/Pi discovery dogfood is the non-network product lane: run ambient_desktop_pi_dogfood --json directly or ambient_blockchain_live_gate --desktop-pi --json to prove Pi can discover, describe, health-check, and respect safety guidance for the bundled package.
• Safe live-read is the default live lane: ambient_blockchain_live_gate --live-read --json should test getHealth, getVersion, and getSlot without secrets or spend.
• Funded Tool Oracle and x402 lanes must be quote/plan-first. Tool Oracle submit/reclaim commands require a configured signer, explicit lamport cap, visible approval, explicit oracle client command template or explicit fake test mode, transaction signature artifact, wait/decode evidence, and cleanup evidence; ambient_blockchain_live_gate --oracle --oracle-funded --json runs that approved lifecycle through the same commands and records redacted lane evidence. x402 execution requires separate lamport and micro-USDC caps, visible approval, one-use payment header file, receipt artifact, and response evidence; ambient_blockchain_live_gate --x402 --x402-paid --json runs that approved paid path through the same executor and records redacted lane evidence.
• Approval digests are part of the plan contract. Submit/payment/deploy commands must run ambient_approval_verify and verify the user approved the same approvalSha256 before signing, paying, or deploying.
• Program deployment lanes must separate scaffold, local build/test readiness, deploy/upgrade/authority plan, execution, observe, and teardown. Run program execution commands only after ambient_approval_verify succeeds for the exact plan digest; each command re-verifies internally, redacts the keypair path, and preserves logs/signature evidence. ambient_blockchain_live_gate --program --program-lifecycle --json records scaffold/build/test evidence, --program-deploy adds approved deploy-plan/deploy execution evidence, and --program-observe adds bounded read-only post-deploy observation evidence.
• Local validator lifecycle runs are opt-in. Use ambient_local_validator_gate --start-validator --json or ambient_blockchain_live_gate --local-validator --start-validator --json; otherwise the validator lane only reports readiness or setup gaps.
• Prefer live Ambient/Pi/Desktop validation for product behavior, but keep funded and deploy actions behind explicit opt-in flags and approval boundaries.

Safety And Boundaries

• The bundled commands are read-only or non-mutating planners except ambient_x402_request_execute, ambient_program_deploy_execute, ambient_program_upgrade_execute, and ambient_program_authority_execute, which are signer-backed funded lanes gated by approval digest, cap replay, and signer binding checks.
• Generic RPC is allowlisted. Transaction submission, airdrops, and simulation of signed payloads are blocked by default.
• Prefer the purpose-built validator, account, token balance, transaction, and program observation commands over generic RPC so the chat transcript stays bounded and full evidence is preserved.
• Stdout is bounded for the chat transcript. Full JSON responses and logs are written as workspace artifacts with path, size, and hash metadata.
• Do not expose keypair paths, key material, payment secrets, or API keys in chat output, descriptor text, logs, or artifacts.
• Payment headers must come from --payment-header-file or AMBIENT_X402_PAYMENT_HEADER_FILE; do not pass one-use x402 payment values in chat text or command arguments.
• If a live lane fails because the Ambient RPC, JumpGate, or local toolchain is unavailable, report the exact lane and artifact path instead of broad retry advice.