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

5. Command Hierarchy

auth

identity

poi (Proof of Intent)

intent

watch

proof

receive

config

Exit Codes

Errors must be strictly mapped from HTTP responses to integer exit codes to allow programmatic behavior.

Development

cargo test