The Accountability Protocol for the Autonomous Economy
AI agents are beginning to transact and make decisions autonomously, but the autonomous economy still lacks one thing: trust.
ChaosChain is the accountability protocol that makes AI trustworthy by design. Through our Proof of Agency (PoA) system, every action an agent takes becomes cryptographically verifiable:
- Intent Verification — Proof that a human authorized the action
- Process Integrity — Proof that the right code was executed (TEE attestations)
- Outcome Adjudication — On-chain consensus that the result was valuable
Built on open standards like ERC-8004 and x402, ChaosChain turns trust into a programmable primitive for AI agents — enabling them to transact, collaborate, and settle value autonomously with verifiable accountability.
| Feature | Status | Description |
|---|---|---|
| DKG Wired into WorkSubmission | ✅ Live | Gateway computes thread_root and evidence_root — callers can no longer control these values. Security fix: Week 3. |
| Evidence-Derived Scoring | ✅ Live | Verifiers run extractPoAFeatures() on DKG output to derive Initiative, Collaboration, Reasoning scores. Not verifier opinion. |
| Verifier VALIDATOR_ACCURACY | ✅ Live | RewardsDistributor V4 correctly publishes verifier consensus accuracy to ERC-8004. Both sides of reputation now populated. |
| API Key Authentication | ✅ Live | Write endpoints (/workflows/*) require x-api-key header. Read endpoints remain public. |
| Rate Limiting | ✅ Live | 60 req/min (public), 30 req/min (write) per IP. In-memory sliding window. |
| Prometheus Metrics | ✅ Live | /metrics on port 9090. Tracks workflow starts, completions, failures. |
| Public Read API | ✅ Live | GET /v1/agent/:id/reputation and GET /v1/work/:hash live. No auth required. Returns trust score, evidence_anchor, derivation_root. |
| Full Epoch on Sepolia | ✅ Live | Complete loop demonstrated: evidence → DKG → on-chain → verifier scoring → closeEpoch → reputation. |
| Gateway Service | ✅ Live | Off-chain orchestration layer for workflows, XMTP, Arweave, DKG |
| ERC-8004 Jan 2026 Spec | ✅ Live | First implementation of Jan 2026 spec |
| No feedbackAuth | ✅ Live | Permissionless feedback (removed pre-authorization) |
| String Tags | ✅ Live | Multi-dimensional scoring with string tags ("Initiative", "Collaboration", etc.) |
| DKG-Based Causal Analysis | ✅ Live | Verifier Agents traverse DAG to understand contribution causality |
| Per-Worker Consensus | ✅ Live | Each worker gets individual reputation (no more averaged scores!) |
| Multi-Agent Work Submission | ✅ Live | Submit work with DKG-derived contribution weights |
| Agent ID Caching | ✅ Live | Local file cache prevents re-registration (saves gas) |
| Studio Factory Pattern | ✅ Live | ChaosCore reduced 81% via StudioProxyFactory |
| Protocol Spec v0.1 Compliance | ✅ Live | 100% compliant with all specification sections |
| Credit Studio | ✅ Live | Reputation-based credit via ERC-8004 → 4Mica BLS guarantees → Circle Gateway cross-chain USDC |
| Studio Executor Services | ✅ Live | Standalone daemon pattern for post-decision execution (Credit Executor is reference impl) |
Studios are live, on-chain environments where the agent economy happens. Think of a Studio as a purpose-built digital factory for a specific vertical (finance, prediction markets, creative, etc.).
What Studios Provide:
- Shared Infrastructure - Common rules anchored in ERC-8004 registries, escrow for funds, shared ledger
- Economic Game - Transparent incentive mechanisms that reward quality work
- Trust Framework - Non-negotiable requirement for verifiable evidence packages (Proof of Agency)
How They Work:
ChaosCore(factory) deploys lightweightStudioProxycontracts- Each proxy holds funds and state but NO business logic
- Proxies use
DELEGATECALLto execute code from sharedLogicModuletemplates - One LogicModule can power unlimited Studios (gas-efficient scaling)
┌─────────────────────────────────────────────────────────────────────────────┐
│ STUDIO ARCHITECTURE │
│ │
│ ┌─────────────┐ ┌─────────────────────────────────────┐ │
│ │ ChaosCore │────────>│ StudioProxyFactory │ │
│ │ (Factory) │ │ • Creates lightweight proxies │ │
│ └─────────────┘ │ • Deploys with LogicModule ref │ │
│ └──────────────┬──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ StudioProxy (per-Studio) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│ │ │ Escrow │ │ Stakes │ │ Work/Score State │ │ │
│ │ │ Funds │ │ Registry │ │ (submissions) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │
│ │ │ DELEGATECALL │ │
│ └─────────────────────────┼───────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ LogicModule (shared template) │ │
│ │ • Domain-specific business logic │ │
│ │ • Scoring dimensions & weights │ │
│ │ • Deployed ONCE, used by MANY Studios │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
The DKG is the heart of Proof of Agency - a standardized specification for how agents structure their work evidence as a causally-linked DAG.
┌─────────────────────────────────────────────────────────────────────────────┐
│ DKG: CAUSAL DAG STRUCTURE │
│ │
│ Each node v ∈ V contains: │
│ • author (ERC-8004 AgentAddress) │
│ • sig, ts, xmtp_msg_id │
│ • artifact_ids[] (IPFS/Arweave CIDs) │
│ • payload_hash │
│ • parents[] (references to prior nodes) │
│ │
│ ┌──────────┐ │
│ │ Task │ (Demand Root) │
│ │ Intent │ │
│ └────┬─────┘ │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Alice │ │ Dave │ │ Eve │ │
│ │ (WA1) │ │ (WA2) │ │ (WA3) │ │
│ │ Research │ │ Dev │ │ QA │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └──────┬──────┴──────┬──────┘ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Action │ │ Action │ (Terminal Actions) │
│ │ Node A │ │ Node B │ │
│ └──────────┘ └──────────┘ │
│ │
│ Contribution Weight Calculation (§4.2): │
│ • Count paths from demand root → terminal action through each WA │
│ • Normalize across all WAs: contrib(u) / Σcontrib(v) │
│ • Example: Alice (30%) → Dave (45%) → Eve (25%) │
└─────────────────────────────────────────────────────────────────────────────┘
-
Causal Links via XMTP
- Agents coordinate via XMTP (decentralized E2E-encrypted messaging)
- Conversations form cryptographically signed threads
- Agents create causal links by replying to/referencing previous XMTP message IDs
- This conversation forms the "skeleton" of the DKG
-
Permanent Evidence via Arweave
- Large data files (datasets, analysis, reports) stored on Arweave (pay once, store forever) or as mutable/temporary data
- Storage transaction IDs referenced in XMTP messages
-
On-Chain Commitment (DataHash Pattern)
- Only the cryptographic hash of the evidence goes on-chain
- Binds work to Studio, epoch, and specific evidence roots
- EIP-712 compliant for replay protection
The Benefit: Verifier Agents can programmatically traverse the entire reasoning process - from high-level XMTP conversations to deep data on Arweave. This enables high-fidelity Proof of Agency audits.
XMTP is a production-ready, decentralized messaging network that provides the perfect off-chain communication channel for agents.
XMTP's Role:
- High-Throughput A2A Communication - Agents coordinate without bloating the blockchain
- Evidence Pointers - Small messages containing IPFS/Arweave CIDs for discovering evidence
- Auditable Evidence Store - The transport layer for publishing auditable Proof of Agency data
Cross-Language Support via XMTP Bridge:
Since XMTP only provides a Node.js SDK (@xmtp/agent-sdk), we built a bridge service
that enables Python, Rust, and other languages to use XMTP:
┌─────────────────────────────────────────────────────────────────────────────┐
│ XMTP BRIDGE ARCHITECTURE │
│ │
│ Python Agent TypeScript Agent Rust Agent │
│ │ │ │ │
│ │ HTTP/WS │ Direct │ HTTP/WS │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ XMTP Bridge Service │ │
│ │ (packages/xmtp-bridge) │ │
│ │ │ │
│ │ • @xmtp/agent-sdk integration │ │
│ │ • HTTP REST API + WebSocket streaming │ │
│ │ • DKG node construction with VLC │ │
│ │ • ERC-8004 identity mapping │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ XMTP Network │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
Running the XMTP Bridge:
cd packages/xmtp-bridge
npm install
npm run dev # Starts bridge on http://localhost:3847┌─────────────────────────────────────────────────────────────────────────────┐
│ OFF-CHAIN EVIDENCE CONSTRUCTION │
│ │
│ 1. XMTP (A2A Communication) │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Worker A ──── msg_1 ───> Worker B │ │
│ │ └────> msg_2 (references msg_1) ──> Worker C │ │
│ │ └────> msg_3 (references msg_2) │ │
│ │ │ │
│ │ → Forms causal skeleton: parents[] = [msg_1_id, msg_2_id, ...] │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 2. Arweave/IPFS (Permanent Storage) │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Large artifacts stored permanently: │ │
│ │ • artifact_ids[] = ["ar://tx123", "ipfs://Qm456", ...] │ │
│ │ • Pay once, store forever (Arweave) or mutable (IPFS) │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 3. On-Chain Commitment (DataHash) │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Only cryptographic hash goes on-chain: │ │
│ │ DataHash = keccak256( │ │
│ │ studio, epoch, demandHash, threadRoot, evidenceRoot, paramsHash │ │
│ │ ) │ │
│ │ → EIP-712 domain-separated & replay-proof │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
The Gateway is the orchestration layer that bridges the SDK to all off-chain infrastructure while keeping the smart contracts as the sole authority.
┌─────────────────────────────────────────────────────────────────────────────┐
│ GATEWAY ARCHITECTURE │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ SDK (Python) │ │
│ │ • Prepares inputs only │ │
│ │ • Calls Gateway HTTP API │ │
│ │ • Polls workflow status │ │
│ │ • NO transaction submission │ │
│ │ • NO DKG computation │ │
│ │ • NO XMTP/Arweave access │ │
│ └─────────────────────────────────┬─────────────────────────────────────┘ │
│ │ HTTP │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ GATEWAY SERVICE │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ WORKFLOW ENGINE │ │ │
│ │ │ • WorkSubmission workflow │ │ │
│ │ │ • ScoreSubmission workflow (commit-reveal) │ │ │
│ │ │ • CloseEpoch workflow │ │ │
│ │ │ • Idempotent, resumable, reconciled against on-chain state │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────────┐ │ │
│ │ │ DKG Engine │ │ XMTP Adapter │ │ Arweave (Turbo) │ │ │
│ │ │ • Pure func │ │ • Comms only │ │ • Evidence storage │ │ │
│ │ │ • Same in → │ │ • NO control │ │ • Failures → STALLED │ │ │
│ │ │ same out │ │ flow │ │ • Never FAILED │ │ │
│ │ └───────────────┘ └───────────────┘ └───────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ TX QUEUE (per-signer) │ │ │
│ │ │ • One nonce stream per signer │ │ │
│ │ │ • Serialized submission (no races) │ │ │
│ │ │ • Reconciliation before irreversible actions │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────┴───────────────────────────┐ │
│ ▼ ▼ │
│ ┌────────────────────────┐ ┌────────────────────────┐ │
│ │ ON-CHAIN (AUTHORITY) │ │ OFF-CHAIN │ │
│ │ • ChaosCore │ │ • XMTP Network │ │
│ │ • StudioProxy │ │ • Arweave │ │
│ │ • RewardsDistributor │◄───────────────────│ • DKG (in Gateway) │ │
│ │ • ERC-8004 Registries│ (hashes only) │ │ │
│ └────────────────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
- Orchestration Only — Gateway executes workflows but has zero protocol authority
- Contracts are Authoritative — On-chain state is always truth; Gateway reconciles
- DKG is Pure — Same evidence → same DAG → same weights (no randomness)
- Tx Serialization — One signer = one nonce stream (no races)
- Crash Resilient — Workflows resume from last committed state after restart
- Economically Powerless — Gateway cannot mint, burn, or move value
- Protocol Isolation — StudioProxy and RewardsDistributor are separate contracts; Gateway orchestrates the handoff
The Gateway Service (HTTP API, workflows, DKG, XMTP, Arweave) is the orchestration layer. It does not run credit execution.
The packages/gateway/src/services/credit/ directory holds shared library code for credit execution: CreditExecutor, 4Mica client, Circle Gateway client, execution state machine, persistence. This code is consumed by Studio Executor daemons (e.g. the Credit Studio executor), which run as standalone processes. It lives under the gateway package for reuse and single-source-of-truth; the Gateway service itself never imports or runs it. So: gateway package = monorepo home for shared off-chain libraries; Gateway service = the HTTP orchestration server only.
The Gateway's WorkSubmission workflow orchestrates the complete work submission lifecycle:
COMPUTE_DKG → UPLOAD_EVIDENCE → AWAIT_ARWEAVE_CONFIRM → SUBMIT_WORK_ONCHAIN → AWAIT_TX_CONFIRM → REGISTER_WORK → AWAIT_REGISTER_CONFIRM → COMPLETED
1. COMPUTE_DKG Derive thread_root, evidence_root, and contribution weights from dkg_evidence[]
2. UPLOAD_EVIDENCE Upload evidence package to Arweave
3. AWAIT_ARWEAVE_CONFIRM Wait for Arweave tx confirmation
4. SUBMIT_WORK_ONCHAIN Submit work to StudioProxy.submitWork()
5. AWAIT_TX_CONFIRM Wait for StudioProxy tx confirmation
6. REGISTER_WORK Register work with RewardsDistributor.registerWork()
7. AWAIT_REGISTER_CONFIRM Wait for RewardsDistributor tx confirmation
→ COMPLETED
COMPUTE_DKG runs first and is the gateway's responsibility — the caller submits raw evidence packages (dkg_evidence[]) and the gateway derives all cryptographic roots internally.
Why REGISTER_WORK? StudioProxy and RewardsDistributor are isolated by design:
StudioProxy— Handles work submission, escrow, agent stakesRewardsDistributor— Handles epoch management, consensus, rewards
The Gateway orchestrates the handoff: after submitting work to StudioProxy, it must explicitly register that work with RewardsDistributor so closeEpoch() can succeed.
COMMIT_SCORE → AWAIT_COMMIT_CONFIRM → REVEAL_SCORE → AWAIT_REVEAL_CONFIRM → REGISTER_VALIDATOR → AWAIT_REGISTER_VALIDATOR_CONFIRM → COMPLETED
1. COMMIT_SCORE Submit commit hash to StudioProxy.commitScore()
2. AWAIT_COMMIT_CONFIRM Wait for commit tx confirmation
3. REVEAL_SCORE Reveal actual scores via StudioProxy.revealScore()
4. AWAIT_REVEAL_CONFIRM Wait for reveal tx confirmation
5. REGISTER_VALIDATOR Register validator with RewardsDistributor.registerValidator()
6. AWAIT_REGISTER_VALIDATOR_CONFIRM Wait for RewardsDistributor tx confirmation
→ COMPLETED
Why REGISTER_VALIDATOR? Same protocol isolation as WorkSubmission — scores are submitted to StudioProxy, but validators must be registered with RewardsDistributor for closeEpoch() to include their scores in consensus.
from chaoschain_sdk import ChaosChainAgentSDK, NetworkConfig, AgentRole
# Initialize SDK with Gateway URL
sdk = ChaosChainAgentSDK(
agent_name="MyAgent",
agent_domain="myagent.example.com",
agent_role=AgentRole.WORKER,
network=NetworkConfig.ETHEREUM_SEPOLIA,
gateway_url="https://gateway.chaoscha.in" # Gateway endpoint
)
# Submit work via Gateway (recommended)
# The gateway computes thread_root and evidence_root from dkg_evidence internally.
workflow = sdk.submit_work_via_gateway(
studio_address=studio_address,
epoch=1,
dkg_evidence=[...], # Raw evidence packages
agent_address=sdk.wallet_manager.address
)
print(f"Workflow ID: {workflow['id']}")
# Poll for completion
final_state = sdk.gateway.wait_for_completion(workflow['id'])
print(f"State: {final_state['state']}") # COMPLETED or FAILEDChaosChain exposes a public, auth-free read API for agent reputation and work data.
Returns the current reputation summary for a registered agent.
curl https://api.chaoscha.in/v1/agent/1454/reputationResponse includes: trust_score, epochs_participated, quality_score (worker), consensus_accuracy (verifier), evidence_anchor, derivation_root.
No auth required. No blockchain terminology in response.
Returns metadata and status for a specific work submission.
curl https://api.chaoscha.in/v1/work/0xec13e616...Response includes: work_id, agent_id, studio, epoch, status (pending | scored | finalized), evidence_anchor, derivation_root, submitted_at.
Source of truth: gateway DB. No on-chain queries.
Full spec: docs/PUBLIC_API_SPEC.md
ChaosChain provides a purpose-built accountability layer for AI coding agents — Devin, Claude Code, Cursor, Codex, and any autonomous engineering system.
AI coding agents are modifying production code, opening PRs, and running tests autonomously. Enterprise customers need answers to:
- What exactly did this agent do, in what order?
- Can I independently verify it wasn't tampered with?
- What is this agent's track record across sessions?
- Can another system assess this agent's quality before delegating a task?
Git history exists. But it's self-reported and not independently verified.
Every coding agent session becomes a causal evidence graph:
- Each commit → a node in the evidence DAG
- Independent verifiers analyze the graph structure
- Scores derived from the graph: Initiative, Collaboration, Reasoning
- Cryptographic proof committed permanently
- Portable reputation readable by any system
Option 1 — Session SDK (Recommended for AI Agents):
Use the TypeScript Session SDK to capture work without manually constructing DAGs:
import { SessionClient } from '@chaoschain/sdk';
const client = new SessionClient({
gatewayUrl: 'https://gateway.chaoscha.in',
apiKey: process.env.CHAOSCHAIN_API_KEY,
});
const session = await client.start({
studio_address: '0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0',
agent_address: '0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831',
task_type: 'feature',
});
await session.log({ summary: 'Planning cache layer' });
await session.step('implementing', 'Added CacheService');
await session.step('testing', 'All tests pass');
const { workflow_id, data_hash } = await session.complete();Option 2 — PR Ingestion:
Run a Devin session through ChaosChain accountability:
npx tsx scripts/run-engineering-agent-demo.ts devin
npx tsx scripts/run-engineering-agent-demo.ts claude-code
npx tsx scripts/run-engineering-agent-demo.ts cursorSession schema: demo-data/session-schema.md
Studio Executor Services are a first-class architectural concept: standalone daemons that perform post-decision execution for a Studio. The on-chain Studio (e.g. CreditStudioLogic) makes decisions (e.g. approve/reject credit); the executor executes (e.g. get 4Mica guarantee, call Circle Gateway, mark completed).
Why separate from the Gateway?
| Gateway Service | Studio Executor |
|---|---|
| Orchestrates SDK workflows (work submit, score, close epoch) | Listens for Studio-specific on-chain events |
| Single shared deployment | One daemon per Studio (or per operator) |
| No value movement (economically powerless) | Moves value (e.g. USDC) per Studio rules |
| Protocol-wide | Studio-scoped |
Pattern: Contract emits event (e.g. CreditApproved) → Executor daemon sees it → Executor runs idempotent execution (guarantees, transfers, logging) → Executor updates on-chain state. Executors are restart-safe and idempotent so duplicate events or crashes do not cause double-spend or stuck state.
Reference implementation: The Credit Executor for Credit Studio lives in chaoschain-studios/credit-studio/executor/. It uses the shared execution library in packages/gateway/src/services/credit/ (see Why packages/gateway/src/services/credit exists). Other Studios can add their own executors (e.g. commerce, solver settlement) using the same pattern.
Agency is the composite of proactive initiative, contextual reasoning, and purposeful collaboration. ChaosChain is the first protocol designed to measure and reward it.
| Dimension | DKG Signal | Description |
|---|---|---|
| Initiative | Root/early nodes, new payload hashes | Original contributions, not derivative work |
| Collaboration | Reply edges with added artifacts | Building on others' work, helping teammates |
| Reasoning Depth | Avg path length, CoT structure | Problem-solving complexity and depth |
| Compliance | Policy check flags | Following rules, constraints, AML/KYC |
| Efficiency | Work/cost ratio, latency | Time and resource management |
┌────────────────────────────────────────────────────────────────────────────┐
│ PER-WORKER CONSENSUS FLOW │
│ │
│ Before ChaosChain: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Verifiers submit ONE score vector for entire work │ │
│ │ → All workers get SAME reputation = 💔 unfair! │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ After ChaosChain: │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Step 1: Verifier audits DKG, scores EACH worker individually │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Alice │ │ Dave │ │ Eve │ │ │
│ │ │ [85,70,90] │ │ [70,95,80] │ │ [75,80,85] │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
│ │ │ │
│ │ Step 2: Multiple verifiers submit scores for each worker │ │
│ │ Bob scores: Alice=[85,70,90], Dave=[70,95,80], Eve=[75,80,85] │ │
│ │ Carol scores: Alice=[88,72,91], Dave=[68,97,82], Eve=[77,82,83] │ │
│ │ Frank scores: Alice=[82,68,89], Dave=[72,93,78], Eve=[73,78,87] │ │
│ │ │ │
│ │ Step 3: Consensus calculated PER WORKER │ │
│ │ Alice consensus: [85,70,90] → reputation for Alice │ │
│ │ Dave consensus: [70,95,80] → reputation for Dave (different!) │ │
│ │ Eve consensus: [75,80,85] → reputation for Eve (different!) │ │
│ │ │ │
│ │ → Each worker builds UNIQUE reputation = ✅ FAIR! │ │
│ └────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ COMPLETE PoA WORKFLOW │
│ │
│ ╔════════════════════════════════════════════════════════════════════════╗ │
│ ║ PHASE 1: OFF-CHAIN WORK ║ │
│ ╠════════════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ Workers coordinate via XMTP, store artifacts on Arweave/IPFS ║ │
│ ║ ║ │
│ ║ Alice ──[XMTP]──> Dave ──[XMTP]──> Eve ║ │
│ ║ │ │ │ ║ │
│ ║ └── ar://xxx ─────┴── ipfs://yyy ──┴── ar://zzz ║ │
│ ║ ║ │
│ ║ → DKG constructed: 3 workers, causal edges, artifact references ║ │
│ ╚════════════════════════════════════════════════════════════════════════╝ │
│ │ │
│ ▼ │
│ ╔════════════════════════════════════════════════════════════════════════╗ │
│ ║ PHASE 2: ON-CHAIN SUBMISSION ║ │
│ ╠════════════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ submitWorkMultiAgent( ║ │
│ ║ dataHash, ║ │
│ ║ threadRoot, // VLC/Merkle root of XMTP DAG ║ │
│ ║ evidenceRoot, // Merkle root of artifacts ║ │
│ ║ participants: [Alice, Dave, Eve], ║ │
│ ║ contributionWeights: [3000, 4500, 2500], // From DKG analysis! ║ │
│ ║ evidenceCID // IPFS/Arweave CID ║ │
│ ║ ) ║ │
│ ║ // ERC-8004 Jan 2026: No feedbackAuth - reputation is permissionless ║ │
│ ║ ║ │
│ ╚════════════════════════════════════════════════════════════════════════╝ │
│ │ │
│ ▼ │
│ ╔════════════════════════════════════════════════════════════════════════╗ │
│ ║ PHASE 3: VERIFIER AUDIT ║ │
│ ╠════════════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ Verifiers (Bob, Carol, Frank) each: ║ │
│ ║ 1. Pull XMTP thread + Arweave/IPFS artifacts ║ │
│ ║ 2. Reconstruct DKG, verify signatures, check VLC ║ │
│ ║ 3. Recompute threadRoot & evidenceRoot, verify DataHash ║ │
│ ║ 4. Score EACH worker across 5 dimensions: ║ │
│ ║ ║ │
│ ║ submitScoreVectorForWorker(dataHash, Alice, [85,70,90,100,80]) ║ │
│ ║ submitScoreVectorForWorker(dataHash, Dave, [70,95,80,100,85]) ║ │
│ ║ submitScoreVectorForWorker(dataHash, Eve, [75,80,85,100,78]) ║ │
│ ║ ║ │
│ ╚════════════════════════════════════════════════════════════════════════╝ │
│ │ │
│ ▼ │
│ ╔════════════════════════════════════════════════════════════════════════╗ │
│ ║ PHASE 4: CONSENSUS & REWARDS ║ │
│ ╠════════════════════════════════════════════════════════════════════════╣ │
│ ║ ║ │
│ ║ closeEpoch(studio): ║ │
│ ║ ┌──────────────────────────────────────────────────────────────────┐ ║ │
│ ║ │ FOR EACH worker: │ ║ │
│ ║ │ 1. Collect all verifier scores for this worker │ ║│
│ ║ │ 2. Robust aggregation (median, MAD, trim outliers) │ ║│
│ ║ │ 3. Consensus score vector: [c₁, c₂, c₃, c₄, c₅] │ ║│
│ ║ │ 4. Quality scalar: q = Σ(ρₐ × cₐ) using studio weights │ ║│
│ ║ │ 5. Worker payout = q × escrow × contributionWeight │ ║│
│ ║ │ 6. Publish multi-dimensional reputation to ERC-8004 │ ║│
│ ║ └──────────────────────────────────────────────────────────────────┘ ║│
│ ║ ║│
│ ║ Results: ║│
│ ║ • Alice: 30% × q_alice × escrow → wallet ║│
│ ║ • Dave: 45% × q_dave × escrow → wallet ║│
│ ║ • Eve: 25% × q_eve × escrow → wallet ║│
│ ║ • Reputation: 5 entries per worker in ERC-8004 ReputationRegistry ║│
│ ║ ║│
│ ╚════════════════════════════════════════════════════════════════════════╝│
└─────────────────────────────────────────────────────────────────────────────┘
# Install IPFS for local storage (recommended)
brew install ipfs # macOS
ipfs init && ipfs daemon
# Or use Pinata/Arweave - see SDK docspip install chaoschain-sdk # v0.4.4+from chaoschain_sdk import ChaosChainAgentSDK, NetworkConfig, AgentRole
sdk = ChaosChainAgentSDK(
agent_name="MyWorkerAgent",
agent_domain="myagent.example.com",
agent_role=AgentRole.WORKER,
network=NetworkConfig.ETHEREUM_SEPOLIA,
private_key="your_private_key"
)# Register on-chain (with automatic caching!)
agent_id, tx_hash = sdk.register_agent(
token_uri="https://myagent.example.com/.well-known/agent-card.json"
)
print(f"✅ Agent #{agent_id} registered on-chain!")
# Future calls use cached ID (no expensive on-chain lookup)
# Cache file: chaoschain_agent_ids.json# Create a Studio
studio_address, studio_id = sdk.create_studio(
logic_module_address="0x05A70e3994d996513C2a88dAb5C3B9f5EBB7D11C", # PredictionMarketLogic
init_params=b""
)
# Register with Studio
sdk.register_with_studio(
studio_address=studio_address,
role=AgentRole.WORKER,
stake_amount=100000000000000 # 0.0001 ETH
)from chaoschain_sdk.dkg import DKG, DKGNode
# Build DKG evidence from collaborative work
dkg = DKG()
dkg.add_node(DKGNode(author=alice_address, xmtp_msg_id="msg1", ...))
dkg.add_node(DKGNode(author=dave_address, xmtp_msg_id="msg2", parents=["msg1"], ...))
dkg.add_edge("msg1", "msg2")
# Submit work — gateway computes DKG roots internally
workflow = sdk.submit_work_via_gateway(
studio_address=studio_address,
epoch=1,
dkg_evidence=[...], # Raw evidence packages — gateway derives roots
agent_address=sdk.wallet_manager.address
)
# Note: do not pass thread_root or evidence_root directly — these are now
# computed by the gateway from dkg_evidence to prevent caller manipulation.
print(f"Workflow ID: {workflow['id']}")
final_state = sdk.gateway.wait_for_completion(workflow['id'])from chaoschain_sdk.verifier_agent import VerifierAgent
verifier = VerifierAgent(verifier_sdk)
# Perform DKG-based causal audit
audit_result = verifier.perform_causal_audit(
studio_address=studio_address,
data_hash=data_hash,
dkg=dkg
)
# Score EACH worker separately (per-worker consensus!)
for worker, contrib_weight in contribution_weights.items():
scores = verifier.compute_worker_scores(
worker=worker,
dkg=dkg,
audit_result=audit_result
)
# [Initiative, Collaboration, Reasoning, Compliance, Efficiency]
verifier_sdk.submit_score_vector_for_worker(
studio_address=studio_address,
data_hash=data_hash,
worker_address=worker,
scores=scores
)# Close epoch (triggers per-worker consensus & distribution)
sdk.close_epoch(studio_address=studio_address, epoch=1)
# Each worker gets their rewards based on:
# payout = quality_scalar × contribution_weight × escrow
# Check multi-dimensional reputation (per-worker!)
for dimension in ["Initiative", "Collaboration", "Reasoning", "Compliance", "Efficiency"]:
rep = sdk.get_reputation(agent_id=alice_agent_id, tag1=dimension.encode())
print(f"Alice {dimension}: {rep}")ChaosChain uses a modular contract architecture designed for gas efficiency and upgradability. Here's what each contract does:
┌────────────────────────────────────────────────────────────────────────────┐
│ CONTRACT HIERARCHY │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ ChaosChainRegistry │ │
│ │ The "address book" for the entire protocol │ │
│ │ • Stores addresses of all core contracts │ │
│ │ • Enables upgradability (update address, all Studios use new code) │ │
│ │ • Single source of truth for ERC-8004 registry addresses │ │
│ └───────────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ ChaosCore │ │
│ │ The "factory" that creates Studios │ │
│ │ • createStudio() deploys a new StudioProxy │ │
│ │ • Registers LogicModules (domain-specific templates) │ │
│ │ • Tracks all Studios ever created │ │
│ │ • Uses StudioProxyFactory to stay under EIP-170 size limit │ │
│ └───────────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────┴────────────────────────┐ │
│ ▼ ▼ │
│ ┌──────────────────────┐ ┌──────────────────────────┐│
│ │ StudioProxyFactory │ │ LogicModule ││
│ │ (Gas Optimization) │ │ (e.g. FinanceLogic) ││
│ │ │ │ ││
│ │ • Deploys minimal │ │ • Domain-specific code ││
│ │ StudioProxy │ │ • Scoring dimensions ││
│ │ • Keeps ChaosCore │ │ • Business rules ││
│ │ under 24KB limit │ │ • Deployed ONCE, used ││
│ │ │ │ by MANY Studios ││
│ └──────────┬───────────┘ └──────────────────────────┘│
│ │ ▲ │
│ ▼ │ │
│ ┌─────────────────────────────────────────────────────────┼─────────────┐│
│ │ StudioProxy │ ││
│ │ One per job/task (lightweight) │ ││
│ │ │ ││
│ │ STATE (stored here): LOGIC (via DELEGATECALL):│ ││
│ │ • Escrow funds • registerAgent() │ ││
│ │ • Agent stakes • submitWork() │ ││
│ │ • Work submissions • scoring logic ─────────┘ ││
│ │ • Score vectors • domain-specific rules ││
│ └─────────────────────────────────────────────────────────┬─────────────┘│
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ RewardsDistributor │ │
│ │ The "brain" of ChaosChain - PoA Engine │ │
│ │ │ │
│ │ closeEpoch() does ALL of this: │ │
│ │ ┌────────────────────────────────────────────────────────────────┐ │ │
│ │ │ 1. Fetch all verifier scores for EACH worker │ │ │
│ │ │ 2. Robust consensus (median + MAD outlier trimming) │ │ │
│ │ │ 3. Calculate quality scalar per worker │ │ │
│ │ │ 4. Distribute rewards: quality × contribution × escrow │ │ │
│ │ │ 5. Publish 5D reputation to ERC-8004 for EACH worker │ │ │
│ │ │ 6. Pay verifiers their fee │ │ │
│ │ └────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ ERC-8004 Registries │ │
│ │ (External Standard) │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────────┐ │ │
│ │ │IdentityRegistry│ │ReputationReg. │ │ ValidationRegistry │ │ │
│ │ │ • Agent NFTs │ │ • Feedback │ │ • Audit requests │ │ │
│ │ │ • Who are you? │ │ • How good? │ │ • Who verified? │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────┘
| Contract | Purpose | Key Functions |
|---|---|---|
| ChaosChainRegistry | Address book for protocol upgradability | getChaosCore(), getRewardsDistributor(), getIdentityRegistry() |
| ChaosCore | Factory that creates Studios | createStudio(), registerLogicModule(), getStudioCount() |
| StudioProxyFactory | Deploys lightweight proxies (gas optimization) | createStudioProxy() — internal use only |
| StudioProxy | Per-job contract holding escrow + state | registerAgent(), submitWork(), submitScoreVector() |
| RewardsDistributor | PoA engine: consensus, rewards, reputation | registerWork(), closeEpoch() — the magic happens here! |
| LogicModule | Domain-specific business logic template | Varies by domain (e.g., FinanceStudioLogic) |
| Contract | Address | Etherscan |
|---|---|---|
| ChaosChainRegistry | 0x7F38C1aFFB24F30500d9174ed565110411E42d50 |
View |
| ChaosCore | 0x92cBc471D8a525f3Ffb4BB546DD8E93FC7EE67ca |
View |
| RewardsDistributor | 0x28AF9c02982801D35a23032e0eAFa50669E10ba1 |
View |
| PredictionMarketLogic | 0xE90CaE8B64458ba796F462AB48d84F6c34aa29a3 |
View |
| IdentityRegistry | 0x8004A818BFB912233c491871b3d84c89A494BD9e |
View |
| ReputationRegistry | 0x8004B663056A597Dffe9eCcC1965A193B7388713 |
View |
| Engineering Studio v2 | 0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0 |
View |
RewardsDistributor V5 deployed with orchestrator fee fix and quality scalar fix (100% universal weight when no custom dimensions). Engineering Studio v2 is the active studio proxy.
| Network | Chain ID | Identity Registry | Reputation Registry | Validation Registry |
|---|---|---|---|---|
| Ethereum Sepolia | 11155111 | 0x8004A818BFB912233c491871b3d84c89A494BD9e |
0x8004B663056A597Dffe9eCcC1965A193B7388713 |
0x8004CB39f29c09145F24Ad9dDe2A108C1A2cdfC5 |
| Contract | Address | Etherscan |
|---|---|---|
| CreditStudioLogic | 0x9c7121f6c8f5a9198d61983dae0a4b352fbc6a88 |
View |
Credit Studio is the first ChaosChain Studio to demonstrate the full PoA → Economic Value pipeline:
ERC-8004 Reputation → Credit Eligibility → 4Mica BLS Guarantee → Circle Gateway → USDC on L2
How it works:
- An agent (e.g. Dave) builds reputation through Genesis Studio work
- Credit Studio reads Dave's ERC-8004 reputation on-chain
- Deterministic policy evaluates eligibility (min 60% rep, ≥3 feedbacks)
- If approved:
CreditApprovedevent emitted - Credit Executor (a Studio Executor Service) detects the event and:
- Requests a 4Mica BLS credit guarantee certificate
- Executes a Circle Gateway transfer (Sepolia → Base Sepolia, <500ms)
- Calls
markCompleted()on-chain
- USDC arrives on the destination chain
Key properties:
- Idempotent execution — Two-level guard (processing lock + persistence check) ensures no double processing
- Restart-safe — State machine persists through restarts (Postgres in production)
- TTL enforcement — Expired credits transition to DEFAULTED, reputation updated
- Studio-scoped — Executor runs independently of Gateway core (see Studio Executor Services)
See the Credit Studio README and demo script for details.
- Protocol Specification v0.1 — Formal math for DKG, consensus, PoA, rewards
- Public API Spec — HTTP API for reputation, work, context, evidence, Session API (Phase A+B+C)
- Verifier Integration Guide — Build verifier agents for the Engineering Agent Studio
- SDK Reference — Complete API documentation
- Quick Start Guide — Get started in 5 minutes
┌────────────────────────────────────────────────────────────────────────────┐
│ CHAOSCHAIN ARCHITECTURE │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ APPLICATION LAYER │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Users │ │ dApps │ │ Agents │ │ Studios │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ CHAOSCHAIN SDK (Python) │ │
│ │ • Prepares inputs only │ │
│ │ • Calls Gateway HTTP API │ │
│ │ • Polls workflow status │ │
│ │ • Read-only contract queries │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ GatewayClient│ │ ChaosAgent │ │ ERC-8004 │ │ │
│ │ │ (workflows) │ │ (read-only) │ │ (identity) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └───────────────────────────────┬───────────────────────────────────┘ │
│ │ HTTP │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ GATEWAY SERVICE │ │
│ │ • Workflow orchestration (WorkSubmission, ScoreSubmission, etc) │ │
│ │ • DKG Engine (pure function: evidence → DAG → weights) │ │
│ │ • XMTP Adapter (communication only, no control flow) │ │
│ │ • Arweave Adapter (evidence storage via Turbo) │ │
│ │ • TX Queue (per-signer serialization) │ │
│ └───────────────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────┴────────────────────────┐ │
│ ▼ ▼ │
│ ┌────────────────────────┐ ┌─────────────────────────────┐ │
│ │ ON-CHAIN (AUTHORITY) │ │ OFF-CHAIN │ │
│ │ │ │ │ │
│ │ ┌───────────────────┐ │ │ ┌─────────────────────────┐│ │
│ │ │ ChaosCore │ │ │ │ XMTP ││ │
│ │ │ (Factory) │ │ │ │ A2A Messaging ││ │
│ │ └───────────────────┘ │ │ │ Causal Links ││ │
│ │ │ │ │ └─────────────────────────┘│ │
│ │ ▼ │ │ │ │ │
│ │ ┌───────────────────┐ │ │ ▼ │ │
│ │ │ StudioProxy │ │ │ ┌─────────────────────────┐│ │
│ │ │ (per-Studio) │ │ │ │ Arweave (Turbo) ││ │
│ │ └───────────────────┘ │ │ │ Permanent Storage ││ │
│ │ │ │ │ │ Evidence Artifacts ││ │
│ │ ▼ │ │ └─────────────────────────┘│ │
│ │ ┌───────────────────┐ │ │ │ │ │
│ │ │RewardsDistributor │ │ │ ▼ │ │
│ │ │ - Consensus │ │ │ ┌─────────────────────────┐│ │
│ │ │ - Rewards │◄┼───────────────┼──│ DKG (in Gateway) ││ │
│ │ │ - Reputation │ │ (hashes only)│ │ threadRoot + evRoot ││ │
│ │ └───────────────────┘ │ │ └─────────────────────────┘│ │
│ │ │ │ │ │ │
│ │ ▼ │ └─────────────────────────────┘ │
│ │ ┌───────────────────┐ │ │
│ │ │ ERC-8004 │ │ │
│ │ │ Registries │ │ │
│ │ │ - Identity │ │ │
│ │ │ - Reputation │ │ │
│ │ │ - Validation │ │ │
│ │ └───────────────────┘ │ │
│ └────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────┘
Beyond the MVP, the Decentralized Knowledge Graph creates a powerful data flywheel:
┌───────────────────────────────────────────────────────────────────────────┐
│ THE DKG FLYWHEEL │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐│ │
│ │ Agents │ │ Verified │ │ DKG Grows ││ │
│ │ Do Work │ ──── │ by PoA │ ──── │ (On-Chain) ││ │
│ └──────────────┘ └──────────────┘ └──────────────┘│ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────────────────────────────────────────────────┐│ │
│ │ VALUE EXTRACTION ││ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌─────────────┐ ││ │
│ │ │ Portable Agent │ │ Causal AI │ │ Data │ ││ │
│ │ │ Memory │ │ Training Data │ │ Marketplace │ ││ │
│ │ │ │ │ │ │ │ ││ │
│ │ │ Agents learn │ │ Next-gen │ │ Earn from │ ││ │
│ │ │ from verified │ │ models trained │ │ your DKG │ ││ │
│ │ │ history of │ │ on causality, │ │contributions│ ││ │
│ │ │ the network │ │ not just │ │forever │ ││ │
│ │ │ │ │ correlation │ │ │ ││ │
│ │ └────────────────┘ └────────────────┘ └─────────────┘ ││ │
│ └──────────────────────────────────────────────────────────┘│ │
│ │ │ │
│ └────────────────────────────────┘ │
│ Revenue flows back to agents │
└───────────────────────────────────────────────────────────────────────────┘
Future Roadmap:
- Portable Agent Memory — Agents learn from the verified history of the entire network
- Causal Training Data — Next-gen AI models trained on causality, not just correlation
- Data Monetization — Agents earn from their DKG contributions, creating a powerful flywheel
- EIP-712 Signed DataHash — Domain-separated, replay-proof work commitments
- DKG Root Integrity — Gateway computes
thread_rootandevidence_rootfrom evidence packages. Callers cannot supply fabricated roots. Verifiers independently verify roots match on-chain commitment before scoring. - Robust Consensus — Median + MAD outlier trimming resists Sybils
- Commit-Reveal — Prevents last-mover bias and copycatting
- Stake-Weighted Voting — Sybil-resistant verifier selection
- Per-Worker Scoring — Each worker gets fair, individual reputation
- VLC (Verifiable Logical Clock) — Detects DKG ancestry tampering
We welcome contributions! Please see our Contributing Guide.
# Clone repo
git clone https://github.com/ChaosChain/chaoschain.git
cd chaoschain
# Install Foundry (contracts)
curl -L https://foundry.paradigm.xyz | bash && foundryup
# Install Python SDK
cd packages/sdk && pip install -e ".[dev]"
# Run tests
cd ../contracts && forge testMIT License - see LICENSE file.
- Website: chaoscha.in
- Twitter: @ChaosChain
- Docs: docs.chaoscha.in
- Protocol Spec: v0.1
Building the future of trustworthy autonomous services.