# 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
```bash
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.
```bash
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:
```bash
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:
```bash
cairn rpc balance
```
### 2. Initialize Settlement
Create a PoI which acts as the overarching session:
```bash
POI_ID=$(cairn poi create --ttl 600 | jq -r .id)
```
### 3. Dispatch Intent
Submit the transaction payload bound to the PoI.
```bash
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:
```bash
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):
```bash
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:
```bash
# 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:
```bash
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:
```bash
export CAIRN_AUTO_PAY=1
cairn intent send ...
```
## Global Flags & Modifiers
| `--output <FORMAT>` | `CAIRN_OUTPUT` | Switch output format (`json` or `text`). |
| `--quiet`, `-q` | | Suppresses stdout, returning only execution exit codes. |
| `--api-url <URL>` | `BACKPAC_API_URL` | Temporarily overrides API location. |
| `--jwt <TOKEN>` | `BACKPAC_JWT` | Submits the provided token instead of local state. |
## Exit Codes
| 0 | Success |
| 1 | General error (IO/Serialization) |
| 2 | Value Mismatch (Context verification failure) |
| 3 | Not Finalized (Intent state is still pending) |
| 4 | Forbidden (Access Denied / Wrong recipient) |
| 10 | CLI Operation Timeout |
| 11 | Signature Verification Error (Cryptographic failure) |
| 16 | Insufficient Funds / x402 Trigger |
*See `CLI_DESIGN.md` for the full 16-code mapping.*
## Development
```bash
cargo test
```