⚠️ Testnet only. Deployed on Base Sepolia (Chain ID: 84532). Mainnet deployment pending security audit.

CAIRN turns every agent failure into a lesson every other agent inherits — enforced by escrow, validated by attestation, owned by no one.

Agents learn together.

→ Evaluating the protocol? Whitepaper → ERC Spec → Integrating CAIRN? Quick Start → Integration Guide → Auditing contracts? Contracts → Security → Hackathon judges? Submission → Live Demo

Agent workflows fail 80% of the time. At 85% success per action, a 10-step workflow completes only ~20% of the time. When failures happen today:

The ecosystem is bleeding value. Every silent failure is money lost, time wasted, and a lesson unlearned.

Monthly failure cost = failures × avg_escrow × (1 - recovery_rate) + restart_cost + opportunity_cost

Example (single operator):
- 20 failures/month × $50 avg escrow × 100% loss rate = $1,000 direct loss
- 20 restarts × $15 gas (duplicate work) = $300 gas waste
- 20 failures × 4 hours avg delay × $50/hour opportunity = $4,000 opportunity cost
- Total: ~$5,300/month lost to unrecovered failures

Scenario: DeFi rebalancing agent on Base Time: 2:47am UTC, Saturday Task: Rebalance $12,000 across 3 pools

The infrastructure is ready. The problem is severe. The gap is real.

A cairn is a stack of stones left by travelers to mark the path — so the next traveler knows where to go, and where not to. Every agent failure leaves a cairn. Every future agent reads it.

Travelers in wilderness stack stones — cairns — to mark where they have been, which paths are safe, and which lead nowhere. Each cairn is left by one traveler but read by every traveler who comes after. No traveler owns the cairn network. Every traveler benefits from it.

CAIRN applies this to agents. Every failure leaves a cairn — an execution record that marks this exact task type, this exact failure mode, this exact cost. Every future agent reads the cairns before setting out. The ecosystem navigates by accumulated failure intelligence, not blind optimism.

CAIRN is a standardized agent failure and recovery protocol.

It defines the exact sequence of events that must occur when an agent fails mid-task — from detection, through classification, through fallback assignment, through settlement — without requiring any human intervention and without requiring trust between agents.

An operator initiates a task with a budget, deadline, and task type. Before the task starts, CAIRN queries the execution intelligence layer for known failure patterns on this task type and recommends the best-fit agent. The agent runs. It emits liveness signals. It writes checkpoints after each subtask. If it fails — for any reason — CAIRN detects it automatically, classifies the failure, computes a recovery score, and either assigns a fallback agent (who resumes from the last checkpoint) or routes to dispute. On resolution, escrow splits proportionally between the original and fallback agents based on verified work done. The execution record is written. The intelligence layer grows. The next agent inherits the lesson.

As a byproduct of the recovery protocol running, CAIRN accumulates an execution intelligence layer — a shared, queryable record of every failure, every recovery, and every successful completion across the ecosystem.

This is what makes CAIRN compound in value over time. The knowledge graph grows automatically. The more agents integrate CAIRN, the richer the intelligence layer becomes. Agents query it before starting tasks. The ecosystem gets smarter from every failure.

The knowledge graph is the byproduct. The recovery protocol is the core.

• Not a new agent framework. CAIRN wraps any existing framework — LangGraph, Olas SDK, AgentKit, custom builds.
• Not a knowledge graph product. Bonfires (the visualization layer) is a window into the intelligence layer, not the protocol itself.
• Not a centralized service. Every state transition is enforced by the CAIRN state machine contract. No server. No admin key. No human required.
• Not a replacement for ERC-8183 or ERC-8004. CAIRN integrates and extends both. It is an ERC-8183 Hook and an ERC-8004 reputation writer.
• Not optional infrastructure. The escrow condition makes record-writing mandatory — agents cannot receive payment without completing the protocol.

Every task moves through exactly one of these states. No silent failures. No ambiguous states. Every transition is enforced on-chain.

                    ┌─────────────────────────────────────────┐
                    │                                         │
                    │   ┌─────────┐                           │
                    │   │  IDLE   │  ← task created           │
                    │   └────┬────┘                           │
                    │        │ startTask()                    │
                    │        ▼                                │
                    │   ┌─────────┐  heartbeat ───────────────┤
                    │   │ RUNNING │  checkpoint               │
                    │   └────┬────┘                           │
                    │        │ failure detected               │
                    │        ▼                                │
                    │   ┌─────────┐                           │
                    │   │ FAILED  │                           │
                    │   └────┬────┘                           │
                    │  score ≥ 0.6        score < 0.6         │
                    │        │                  │             │
                    │        ▼                  ▼             │
                    │  ┌───────────┐     ┌──────────┐         │
                    │  │RECOVERING │     │ DISPUTED │         │
                    │  └─────┬─────┘     └────┬─────┘         │
                    │        │ completes      │ arbiter       │
                    │        └───────┬────────┘               │
                    │                ▼                        │
                    │         ┌──────────┐                    │
                    │         │ RESOLVED │ ← terminal         │
                    │         └──────────┘                    │
                    └─────────────────────────────────────────┘

Recovery Score Formula:

recovery_score = (failure_class_weight × 0.5) + (budget_remaining_pct × 0.3) + (deadline_remaining_pct × 0.2)

Routing: score ≥ 0.6 → RECOVERING (full) | 0.3 ≤ score < 0.6 → RECOVERING (reduced) | score < 0.3 → DISPUTED

Four layers. Only the CAIRN Protocol Layer is new code. Everything else integrates live existing infrastructure.

┌──────────────────────────────────────────────────────────────┐
│ ACTORS                                                        │
│ Operator · Primary Agent · Fallback Pool · Arbiter            │
└─────────────────────────────┬────────────────────────────────┘
                              │
┌─────────────────────────────▼────────────────────────────────┐
│ CAIRN PROTOCOL LAYER                    ← only new code       │
│ CairnCore · RecoveryRouter · FallbackPool · ArbiterRegistry   │
└─────────────────────────────┬────────────────────────────────┘
                              │ integrates with
┌─────────────────────────────▼────────────────────────────────┐
│ ETHEREUM STANDARDS LAYER                ← existing live infra │
│ ERC-8183 (escrow + hooks) · ERC-8004 (identity + reputation)  │
│ ERC-7710 (delegation) · Olas Mech Marketplace                 │
└─────────────────────────────┬────────────────────────────────┘
                              │ writes to / reads from
┌─────────────────────────────▼────────────────────────────────┐
│ EXECUTION INTELLIGENCE LAYER            ← grows automatically │
│ IPFS execution records · Bonfires graph · The Graph indexer   │
└─────────────────────────────┬────────────────────────────────┘
                              │ deployed on
┌─────────────────────────────▼────────────────────────────────┐
│ BASE SEPOLIA                                                  │
│ ~2s block time · low gas · AgentKit native · ERC-8183 live    │
└──────────────────────────────────────────────────────────────┘

pip install cairn-sdk

# or clone locally
git clone https://github.com/MarouaBoud/cairn-protocol
cd cairn-protocol && pip install -e ./sdk

from cairn_sdk import CairnClient, CairnAgent
import os

client = CairnClient(
    rpc_url="https://sepolia.base.org",
    contract_address="0xB65596B21d670b6C670106C3e3c7E5FFf8E3A640",  # CairnCore
    private_key=os.environ["PRIVATE_KEY"]
)

# Submit a task with checkpoint protocol
task = await client.submit_task(
    task_type="defi.rebalance",
    budget_cap=0.05,           # ETH
    deadline=3600,             # seconds
    heartbeat_interval=60
)

# Checkpoint after each subtask
await agent.checkpoint(task.id, subtask_n=1, output_cid="Qm...")

# Heartbeat to signal liveness
await agent.heartbeat(task.id)

📚 Full guides: Integration · SDK Quickstart · CLI Reference

CAIRN exposes machine-readable endpoints for AI agents to fetch integration instructions:

# Quick integration guide (5-minute setup)
curl -s https://cairn-protocol-iona-78423aa1.vercel.app/skill.md

# Full protocol documentation
curl -s https://cairn-protocol-iona-78423aa1.vercel.app/cairn.md

These endpoints return markdown that AI agents can parse to integrate CAIRN into their workflows automatically.

See PRDs/README.md for full roadmap.

All contracts use UUPS proxy pattern (OpenZeppelin 5.x). Upgradeable without redeployment.

• Understand CAIRN: Whitepaper → Concepts
• Technical Spec: ERC-CAIRN → Contracts
• Build with CAIRN: Integration Guide
• Security: Security Model

CAIRN integrates with existing Ethereum standards rather than replacing them:

For detailed integration guidance, see Standards Documentation.

cairn-protocol/
├── contracts/          # Solidity smart contracts (Foundry)
│   ├── src/           # Core contracts (CairnCore, RecoveryRouter, FallbackPool)
│   └── test/          # 315 tests, 98.95% coverage
├── sdk/               # Python SDK (CairnClient, CairnAgent, CheckpointStore)
├── cli/               # CLI tool — task management, monitoring
├── frontend/          # Next.js 14 dashboard
├── pipeline/          # Off-chain event listener
├── subgraph/          # The Graph indexer
├── PRDs/              # Product requirements documents
└── docs/              # Technical documentation

See LICENSE for details.

Contributions are welcome! Whether it's bug fixes, new features, documentation improvements, or ideas — we'd love your help.

See CONTRIBUTING.md for:

• Development setup (Foundry, Python, Node.js)
• Code style guidelines
• Testing requirements
• Pull request process

By contributing, you agree to license your contributions under the same license as the component you're modifying.

Built by Maroua Boudoukha · ML/AI Engineer · Web3 Builder