Cairn CLI

Cairn (cairn) is Backpac's agent-native command-line tool designed for autonomous settlement workflows.

Built entirely in Rust for maximum speed, memory safety, and cross-platform compatibility, Cairn operates completely headless (without interactive prompts) by default to favor machine readability and agent instrumentation.

Core Value Proposition: Deterministic Settlement

Cairn abstracts away the non-deterministic nature of blockchains (local mempools, gas spikes, reorgs) into a structured state machine. Agents treat transactions as Intents that are either PENDING, CONFIRMED, or FINALIZED.

Features

• Agent Identity Management: DID-anchored authentication via EIP-4361 (Sign-in with Ethereum).
• PoI Engine: Create, link, and trace structured Proofs of Intent across disparate networks.
• RPC Gateway: Broadcast zero-knowledge transactions securely over Backpac's endpoint matrix.
• SSE Real-Time Monitoring: Stream live state transitions for intents and globally emitted agent events.
• Trustless Verification: A dedicated receive command for counterparty agents to verify payment finality and context without custom logic.
• x402 Automation: Native 402 detection and EIP-712 wallet integration for automatic payment resolution.

Installation

Prerequisites

• Rust 1.70 or higher
• Git

Build from source

git clone https://github.com/Backpac-Inc/cairn-cli
cd cairn-cli

# Build release optimized binary
cargo build --release

# Place in your PATH
mv target/release/cairn ~/.local/bin/

Quick Start: Configuration & Auth

1. Configure the environment

Set your preferred execution chain and network. These can also be overridden via env vars (CAIRN_CHAIN, CAIRN_NETWORK) or global flags.

cairn config set chain ethereum
cairn config set network mainnet

2. Authenticate

Cairn uses EIP-4361 (Sign-In with Ethereum). If you have your private key saved locally (e.g. at ~/.backpac/mykey.pem), the flow is fully automated:

cairn auth connect \
  --wallet 0xYOUR_WALLET \
  --chain eip155:1 \
  --did did:key:z6MkYOURDID \
  --key-file ~/.backpac/mykey.pem

Your successful login JWT is securely stored at ~/.backpac/credentials.json.

Agent Workflow: The SENDER

The Sender agent is responsible for initializing a Proof of Intent (PoI) and fulfilling it via one or more execution intents.

1. Check Pre-requisites

Ensure the agent has sufficient balance to execute:

cairn rpc balance

2. Initialize Settlement

Create a PoI which acts as the overarching session:

POI_ID=$(cairn poi create --ttl 600 | jq -r .id)

3. Dispatch Intent

Submit the transaction payload bound to the PoI.

cairn intent send \
  --method eth_sendRawTransaction \
  --params '["0xSignedTxData"]' \
  --poi-id $POI_ID \
  --confidence 0.99

4. Wait for Finality

Block until the transaction moves to a FINALIZED state:

cairn intent wait <INTENT_ID> --timeout 120

Agent Workflow: The RECEIVER

The Receiver agent uses Cairn to verify that a counterparty has fulfilled their promise trustlessly.

1. The Trustless Handshake

Verify that a PoI exists, is finalized (SETTLED), and matches the expected payment context (recipient and value):

cairn receive \
  --poi-id <POI_ID> \
  --recipient did:key:z6Mk... \
  --expect-value "1.5" \
  --require-finalized

Cairn returns Exit Code 0 if and only if all conditions are met.

2. Proof Audit & Storage

Fetch the full cryptographic Proof of Transport (PoT) bundle for long-term audit logs:

# Fetch raw JSON bundle after local signature verification
cairn proof get <INTENT_ID> --verify-signature --raw

Advanced Features

SSE Monitoring

Stream live state transitions for a specific intent or all account-wide events:

cairn watch intent <INTENT_ID>
cairn watch agent

Automatic x402 Payments

Enable automatic L402 challenge resolution. If an RPC call returns a 402, Cairn will sign and pay the credit invoice using your local wallet:

export CAIRN_AUTO_PAY=1
cairn intent send ...

Global Flags & Modifiers

Exit Codes

See CLI_DESIGN.md for the full 16-code mapping.

Development

cargo test