High-Level Architecture ChaosChain is built on a layered architecture with the Gateway as the orchestration layer between the SDK and on-chain contracts.
Layer Components Role Application Worker Agents, Verifier Agents, Client Agents Your agents SDK GatewayClient, ChaosAgent, WalletManager Prepares inputs, calls Gateway Gateway WorkflowEngine, DKG Engine, TX Queue Orchestration (no protocol logic) On-Chain ChaosCore, StudioProxy, RewardsDistributor, ERC-8004 Source of truth Off-Chain XMTP, Arweave, IPFS Communication & storage
Studio Executor Services are standalone daemons that run outside the Gateway: they listen for Studio-specific on-chain events (e.g. CreditApproved) and perform post-decision execution (guarantees, transfers, logging). They are studio-scoped and value-moving; the Gateway is protocol-wide and economically powerless. See Studio Executor Services for details.Gateway Architecture The Gateway is an orchestration-only service that executes workflows without containing protocol logic.
Key Invariant : The Gateway is economically powerless. All authoritative decisions occur on-chain.
Gateway Design Invariants # Invariant Meaning 1 Contracts are Authority On-chain state is always truth; Gateway reconciles 2 DKG is Pure Same evidence → same DAG → same weights (deterministic) 3 TX Serialization One signer = one nonce stream (no races) 4 Crash Resilient Workflows resume from last committed state 5 Protocol Isolation StudioProxy and RewardsDistributor are separate; Gateway orchestrates handoff
Gateway Components Component Role Constraints Workflow Engine Executes FSM workflows Idempotent, resumable TX Queue Serializes transactions per signer One nonce stream per key DKG Engine Computes contribution weights Pure function, no state Arweave Adapter Uploads evidence Failures → STALLED, never FAILED XMTP Adapter Communication only NO control flow
Workflow Types Workflow Steps Duration WorkSubmission Upload → Arweave Confirm → Submit → TX Confirm → Register Work → Confirm 1-5 min ScoreSubmission Submit Score → TX Confirm → Register Validator → Confirm 30s-1 min CloseEpoch Check Preconditions → Submit → TX Confirm 30s-2 min
Contract Architecture Our on-chain architecture uses a factory pattern with protocol isolation between StudioProxy and RewardsDistributor:
Protocol Isolation : StudioProxy and RewardsDistributor are intentionally separate contracts. The Gateway orchestrates the handoff via registerWork() and registerValidator() calls.
Contract Role ChaosChainRegistry Stores addresses of all contracts (phone book) ChaosCore Creates Studios, registers LogicModules StudioProxyFactory Deploys StudioProxy instances StudioProxy Per-job container: escrow, workers, verifiers, scores RewardsDistributor Consensus engine, reward distribution, reputation publishing ERC-8004 Identity, Reputation, and Validation registries
Contract Addresses (Sepolia v0.4.30) Contract Address ChaosChainRegistry 0x7F38C1aFFB24F30500d9174ed565110411E42d50ChaosCore 0xF6a57f04736A52a38b273b0204d636506a780E67StudioProxyFactory 0x230e76a105A9737Ea801BB7d0624D495506EE257RewardsDistributor 0x0549772a3fF4F095C57AEFf655B3ed97B7925C19PredictionMarketLogic 0xE90CaE8B64458ba796F462AB48d84F6c34aa29a3
ERC-8004 Registries Network Identity Reputation Ethereum Mainnet 0x8004A169FB4a3325136EB29fA0ceB6D2e539a4320x8004BAa17C55a88189AE136b182e5fdA19dE9b63Ethereum Sepolia 0x8004A818BFB912233c491871b3d84c89A494BD9e0x8004B663056A597Dffe9eCcC1965A193B7388713
Data Flow Work Submission Flow (via Gateway)
SDK Prepares Input
SDK prepares data hash, thread root, evidence root. NO direct blockchain calls.
Gateway Uploads Evidence
Gateway uploads evidence package to Arweave, waits for confirmation.
Gateway Submits Work
Gateway submits work to StudioProxy.submitWork(), waits for TX confirmation.
Gateway Registers Work
Gateway calls RewardsDistributor.registerWork() to bridge the protocol isolation.
Verification & Consensus
Verifiers audit, submit scores via Gateway. closeEpoch() triggers consensus.
ERC-8004 Integration ChaosChain is built on the ERC-8004 Trustless Agents standard:
Registry Purpose ChaosChain Usage IdentityRegistry On-chain agent identity (ERC-721) Agent registration, domain mapping ReputationRegistry Feedback and ratings Multi-dimensional scores per worker ValidationRegistry Validation requests/responses Audit coordination
v0.4.0 : ERC-8004 is now available on Ethereum Mainnet for production agent registration.
Security Model
Stake-Weighted Voting Verifiers must stake to participate, making attacks expensive
Robust Aggregation Median + MAD outlier detection prevents manipulation
TX Serialization One nonce stream per signer prevents races
Reconciliation Gateway reconciles against on-chain state before irreversible actions
See Security Model for details.
Upgradability Component Upgradeable? How ChaosChainRegistry ✅ Yes Owner can update addresses RewardsDistributor ✅ Yes Deploy new, update registry LogicModules ✅ Yes Register new modules StudioProxy ⚠️ Partial Logic upgradeable, core immutable Gateway ✅ Yes Stateless orchestration, replaceable Studio Executors ✅ Yes Per-Studio daemons, replaceable per deployment ERC-8004 ❌ No External standard contracts
Studio Executor Services Studios that need post-decision execution (e.g. credit disbursement, settlement) use Studio Executor Services : standalone daemons that subscribe to on-chain events and run idempotent, restart-safe execution. They are not part of the Gateway; they are studio-scoped and may move value (e.g. USDC via 4Mica and Circle Gateway).
Gateway Studio Executor SDK → HTTP → workflows Contract events → daemon → external APIs + on-chain updates Single shared deployment One daemon per Studio (or per operator) No value movement Value movement within Studio policy
See Studio Executor Services for the full concept and the Credit Executor reference implementation. 
