Overview
The ChaosChain Gateway is an off-chain orchestration layer that handles:
- Workflow execution (work submission, scoring, epoch closure)
- Transaction serialization (one nonce stream per signer)
- Evidence archival to Arweave
- DKG computation (deterministic, server-side)
Key Principle: The Gateway is economically powerless. All authoritative decisions occur on-chain.
Gateway Design Invariants
| Invariant | Meaning |
|---|
| Contracts are Authority | 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 |
| Protocol Isolation | Gateway bridges StudioProxy ↔ RewardsDistributor |
When to Use the Gateway
| Use Case | Direct SDK | Gateway |
|---|
| Simple transactions | ✅ | ✅ |
| Multi-step workflows | ❌ | ✅ |
| Crash recovery | ❌ | ✅ |
| Evidence archival | Manual | Automatic |
| DKG computation | SDK-side | Server-side |
Quick Start
from chaoschain_sdk import GatewayClient
# Connect to Gateway
gateway = GatewayClient("https://gateway.chaoscha.in")
# Check health
status = gateway.health_check()
print(f"Gateway: {status['status']}")
# Submit work
result = gateway.submit_work(
studio_address="0xF795D41267DEf795f6f870d5d5be833Eb9703E86",
data_hash="0x1234...",
thread_root="0x5678...",
evidence_root="0x9abc...",
signer_address="0xMyWallet..."
)
# Wait for completion
final = gateway.wait_for_workflow(result.workflow_id, timeout=300)
print(f"✅ Completed: {final.tx_hash}")
Workflow Types
WorkSubmission (6 Steps)
The Gateway orchestrates the complete work submission lifecycle:
UPLOAD_EVIDENCE → AWAIT_ARWEAVE_CONFIRM → SUBMIT_WORK_ONCHAIN → AWAIT_TX_CONFIRM → REGISTER_WORK → AWAIT_REGISTER_CONFIRM → COMPLETED
| Step | Action |
|---|
UPLOAD_EVIDENCE | Upload evidence package to Arweave |
AWAIT_ARWEAVE_CONFIRM | Wait for Arweave tx confirmation |
SUBMIT_WORK_ONCHAIN | Submit to StudioProxy.submitWork() |
AWAIT_TX_CONFIRM | Wait for blockchain confirmation |
REGISTER_WORK | Register with RewardsDistributor.registerWork() |
AWAIT_REGISTER_CONFIRM | Wait for registration confirmation |
Why REGISTER_WORK? StudioProxy and RewardsDistributor are isolated by design. The Gateway bridges this gap so closeEpoch() can succeed.
result = gateway.submit_work(
studio_address="0x...",
data_hash="0x...",
thread_root="0x...",
evidence_root="0x...",
signer_address="0x...",
# Optional multi-agent
participants=["0xAlice...", "0xBob..."],
contribution_weights=[6000, 4000], # basis points
evidence_cid="Qm..."
)
ScoreSubmission (6 Steps)
SUBMIT_SCORE → AWAIT_SCORE_CONFIRM → REGISTER_VALIDATOR → AWAIT_REGISTER_VALIDATOR_CONFIRM → COMPLETED
Direct Mode (Default)
Commit-Reveal Mode
from chaoschain_sdk.gateway_client import ScoreSubmissionMode
result = gateway.submit_score(
studio_address="0x...",
data_hash="0x...",
worker_address="0xWorker...",
scores=[8500, 9000, 8800, 9200, 8700],
signer_address="0xVerifier...",
mode=ScoreSubmissionMode.DIRECT # Default
)
StudioProxy.submitScoreVectorForWorker() directly.result = gateway.submit_score(
studio_address="0x...",
data_hash="0x...",
scores=[8500, 9000, 8800, 9200, 8700],
score_hash="0x...",
score_salt="0x...",
signer_address="0xVerifier...",
mode=ScoreSubmissionMode.COMMIT_REVEAL
)
CloseEpoch (4 Steps)
CHECK_PRECONDITIONS → SUBMIT_CLOSE_EPOCH → AWAIT_TX_CONFIRM → COMPLETED
result = gateway.close_epoch(
studio_address="0x...",
epoch=0,
signer_address="0xOwner..." # Must be Studio owner
)
final = gateway.wait_for_workflow(result.workflow_id)
print(f"✅ Epoch closed, rewards distributed")
Workflow States
PENDING → RUNNING → COMPLETED
↘ FAILED (unrecoverable)
↘ STALLED (can resume)
| State | Meaning |
|---|
PENDING | Queued, not yet started |
RUNNING | Currently executing |
COMPLETED | Successfully finished |
FAILED | Unrecoverable error (e.g., contract revert) |
STALLED | Recoverable error (e.g., RPC timeout) |
Monitoring Workflows
# Get current status
status = gateway.get_workflow_status(workflow_id)
print(f"State: {status['state']}")
print(f"Step: {status['step']}")
print(f"Progress: {status['progress']}")
# Wait with custom timeout
try:
result = gateway.wait_for_workflow(
workflow_id,
timeout=600, # 10 minutes
poll_interval=5 # Check every 5s
)
except TimeoutError:
print("Workflow still running...")
Error Handling
from chaoschain_sdk.gateway_client import GatewayError
try:
result = gateway.submit_work(...)
final = gateway.wait_for_workflow(result.workflow_id)
except GatewayError as e:
if e.state == "FAILED":
print(f"❌ Unrecoverable: {e.error}")
elif e.state == "STALLED":
print(f"⚠️ Can retry: {e.error}")
Complete Example
from chaoschain_sdk import ChaosChainAgentSDK, NetworkConfig, AgentRole, GatewayClient
from chaoschain_sdk.gateway_client import ScoreSubmissionMode
import os
def main():
# Initialize SDK (for wallet management)
sdk = ChaosChainAgentSDK(
agent_name="MyAgent",
agent_domain="myagent.io",
agent_role=AgentRole.WORKER,
network=NetworkConfig.ETHEREUM_SEPOLIA,
private_key=os.environ.get("PRIVATE_KEY")
)
# Connect to Gateway
gateway = GatewayClient("https://gateway.chaoscha.in")
my_address = sdk.wallet_manager.get_address()
studio = "0xF795D41267DEf795f6f870d5d5be833Eb9703E86"
# 1. Submit work
print("📦 Submitting work...")
work_result = gateway.submit_work(
studio_address=studio,
data_hash=sdk.w3.keccak(text="my_work_v1").hex(),
thread_root="0x" + "00" * 32,
evidence_root="0x" + "00" * 32,
signer_address=my_address
)
work_final = gateway.wait_for_workflow(work_result.workflow_id)
print(f"✅ Work submitted: {work_final.tx_hash}")
# 2. Submit score (as verifier)
print("\n📊 Submitting score...")
score_result = gateway.submit_score(
studio_address=studio,
data_hash=sdk.w3.keccak(text="my_work_v1").hex(),
worker_address=my_address,
scores=[8500, 9000, 8800, 9200, 8700],
signer_address=my_address,
mode=ScoreSubmissionMode.DIRECT
)
score_final = gateway.wait_for_workflow(score_result.workflow_id)
print(f"✅ Score submitted: {score_final.tx_hash}")
# 3. Close epoch
print("\n🔒 Closing epoch...")
close_result = gateway.close_epoch(
studio_address=studio,
epoch=0,
signer_address=my_address
)
close_final = gateway.wait_for_workflow(close_result.workflow_id)
print(f"✅ Epoch closed: {close_final.tx_hash}")
print("\n🎉 Full workflow complete!")
if __name__ == "__main__":
main()
Protocol Isolation Explained
Understanding this is critical for troubleshooting.
| Contract | Handles |
|---|
| StudioProxy | Work submission, escrow, agent stakes |
| RewardsDistributor | Epoch management, consensus, rewards |
- After
submitWork() → calls registerWork() on RewardsDistributor
- After score submission → calls
registerValidator() on RewardsDistributor
closeEpoch() only succeeds if work and validators are registered
This is why workflows include REGISTER_WORK and REGISTER_VALIDATOR steps.
Self-Hosting the Gateway
# Clone the repo
git clone https://github.com/ChaosChain/chaoschain.git
cd chaoschain/packages/gateway
# Configure
cp .env.example .env
# Edit .env with your settings
# Run with Docker
docker-compose up -d
Required Environment Variables
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/chaoschain_gateway
# Blockchain
RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
CHAIN_ID=11155111
SIGNER_PRIVATE_KEY=0x...
# Contracts
CHAOS_CORE_ADDRESS=0xF6a57f04736A52a38b273b0204d636506a780E67
REWARDS_DISTRIBUTOR_ADDRESS=0x0549772a3fF4F095C57AEFf655B3ed97B7925C19
# Storage
ARWEAVE_ENABLED=true
TURBO_API_KEY=your_turbo_key
