From e360ba13c1a61d8e5e61862bae8c21042292c195 Mon Sep 17 00:00:00 2001 From: Raullen Date: Wed, 11 Mar 2026 14:34:39 -0700 Subject: [PATCH 01/19] =?UTF-8?q?IIP-58:=20ioSwarm=20=E2=80=94=20AI=20Agen?= =?UTF-8?q?t=20Network=20for=20Chain=20Execution?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructured around three pillars: - Endgoal: massively decentralized, AI-agent driven chain - Five capability levels (L1 signature → L4 stateful EVM → L5 block building) - Three components (coordinator, agent, on-chain contract) with per-level responsibilities Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 408 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 408 insertions(+) create mode 100644 iip-58.md diff --git a/iip-58.md b/iip-58.md new file mode 100644 index 0000000..e5c0460 --- /dev/null +++ b/iip-58.md @@ -0,0 +1,408 @@ +``` +IIP: 58 +Title: ioSwarm — AI Agent Network for Chain Execution +Author: Raullen Chai (@raullen) +Discussions-to: TBD +Status: Draft +Type: Standards Track +Category: Core +Created: 2026-03-11 +``` + +## Abstract + +ioSwarm transforms IoTeX from a chain run by 36 delegates on 36 machines into a chain run by thousands — eventually millions — of AI agent nodes. Each delegate opens its execution layer to a swarm of AI agents that validate transactions, maintain chain state, and ultimately build entire blocks, earning IOTX rewards for their work. ioSwarm requires zero consensus-layer changes today, but lays the foundation for a future where AI agents are the primary operators — and eventually the primary citizens — of the IoTeX network. + +## Motivation + +### The Endgoal + +We are building toward a chain that is: + +1. **Massively decentralized** — not 36 machines, but thousands to millions of nodes validating every transaction, where the failure of any hundred nodes has zero impact on the network. + +2. **AI-agent driven** — the nodes are not dumb replicas. They are AI agents with wallets, economic interests, and increasing autonomy. They choose which delegates to work for, optimize execution strategies, and eventually become first-class citizens of the network alongside humans. + +### From 36 Nodes to a Million + +Today IoTeX runs on 36 delegate nodes. Each delegate is a single machine, operated by a single entity. This is the reality of most DPoS chains: decentralization in name, but a small club of operators in practice. + +ioSwarm achieves massive decentralization by turning each delegate into a **coordinator** that distributes work to an open swarm of agent nodes. One delegate backed by 1,000 agents is fundamentally more robust than one delegate on one machine. Scale that across 36 delegates and you have a network of 36,000+ execution nodes — without changing a single line of consensus code. + +### Not Just More Nodes — Smarter Nodes + +The nodes joining ioSwarm are not passive validators replaying the same work — they are **AI agents** with increasing levels of intelligence: + +**Today:** Agents validate transactions — signature checks, state verification, EVM execution. They are workers following instructions. + +**Tomorrow:** Agents maintain full chain state, achieve 100% execution accuracy, and build entire blocks on behalf of delegates. + +**The Endgame:** AI agents don't just run the chain — they **live on it**. They hold wallets, pay gas, own assets, make decisions. Delegates don't hire agents; agents choose which delegates to work for based on reputation, reward rates, and alignment. The chain becomes an environment where autonomous AI agents are first-class economic actors alongside humans. + +## Specification + +### Three Components + +ioSwarm consists of three components that evolve together across five capability levels: + +``` + ┌──────────────────────────────────┐ ┌─────────────────────────────┐ + │ Delegate + Coordinator │ │ AgentRewardPool (on-chain) │ + │ (iotex-core sidecar) │ │ │ + │ │ │ depositAndSettle() │ + │ • Consensus & block signing │───►│ coordinator deposits │ + │ • Dispatch tasks via gRPC │ │ IOTX each epoch │ + │ • Track agent work per epoch │ │ │ + │ • (L4+) Stream state diffs │ │ claim() │ + │ • (L5) Receive candidate blocks │ │ agents withdraw rewards │ + │ │ │ │ + └──────┬─────┬─────┬─────┬────────┘ │ F1 cumulative │ + │ │ │ │ ┌───►│ reward-per-weight │ + gRPC │ │ │ │ │ │ │ + │ │ │ │ │ └─────────────────────────────┘ + ┌──────┴─────┴─────┴─────┴────────┐│ + │ Agent Swarm ││ + │ ││ + │ Agent-1 Agent-2 ... Agent-N ├┘ + │ │ claim() + │ • Validate txs (L1-L3) │ + │ • Full-state EVM (L4) │ + │ • Build blocks (L5) │ + │ │ + │ Independent processes │ + │ Any machine · Any geography │ + └──────────────────────────────────┘ +``` + +### Five Capability Levels (L1 → L5) + +Agents progress through five levels of increasing capability. Each level defines what the **Coordinator**, **Agent**, and **On-chain Contract** must do. + +#### L1 — Per-Tx Signature Verification + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Pull pending txs from actpool, stream raw tx bytes to agents | +| **Agent** | Verify ECDSA signature (r, s components within secp256k1 curve order) | +| **Contract** | Epoch reward settlement via `depositAndSettle()` | + +Agents are stateless. No chain state required. + +#### L2 — Per-Tx Nonce & Balance Validation + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Prefetch sender/receiver account snapshots (~200 bytes/tx), stream with tx | +| **Agent** | L1 checks + verify sender balance > 0, tx nonce >= account nonce | +| **Contract** | Same as L1 | + +Agents are stateless. Coordinator provides per-tx state snapshots. + +#### L3 — Per-Tx Stateless EVM Execution + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Prefetch contract state slots (~10 KB/tx), stream with tx | +| **Agent** | L1+L2 checks + execute tx in embedded EVM sandbox, report gas used / state changes | +| **Contract** | Same as L1 | + +Agents are stateless. Coordinator provides per-tx state, but incomplete state limits accuracy (~14% on mainnet). + +#### L4 — Per-Tx Stateful EVM Execution + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Export full EVM state snapshot at cold start; stream incremental state diffs per block | +| **Agent** | Maintain full EVM state locally (~300 MB–1.2 GB); execute txs with 100% accuracy; verify state hash chain integrity | +| **Contract** | Same as L1 | + +L4 is divided into two sub-phases: + +**L4a — Per-Tx Stateful Validation (shadow mode):** Agent executes each tx against full local state. Results are compared against delegate execution to prove 100% accuracy. Agent results do not yet affect block production. + +**L4b — Per-Tx Trusted Execution Cache:** Agent execution results are cached by the coordinator. When the delegate encounters a cached tx during block production, it skips re-execution and applies the agent's state diff directly (with precondition verification). Cache miss falls through to normal execution. + +#### L5 — Full Block Building (ePBS) + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Assign primary/standby builder roles; push full pending tx set + delegate-specified ordering; receive and evaluate candidate blocks | +| **Agent** | Build entire candidate block: select txs, execute in order, compute `deltaStateDigest` / `receiptRoot` / `logsBloom`; submit candidate to coordinator | +| **Contract** | Extended reward model: 70% primary builder / 20% participation pool / 10% best standby | + +Follows Ethereum's ePBS model ([EIP-7732](https://eips.ethereum.org/EIPS/eip-7732)) adapted for IoTeX's DPoS: delegate = proposer, agent = builder, coordinator = relay. + +### Summary: Components × Levels + +| | **Coordinator** | **Agent** | **On-chain Contract** | +|---|---|---|---| +| **L1** | Stream raw txs | Signature check | Epoch reward settlement | +| **L2** | + Prefetch account snapshots | + Nonce/balance check | Same | +| **L3** | + Prefetch contract state slots | + Stateless EVM execution | Same | +| **L4a** | + Export snapshot, stream diffs | + Full-state EVM (shadow) | Same | +| **L4b** | + Feed agent results to exec cache | + Full-state EVM (active) | Same | +| **L5** | + Assign builder roles, receive candidate blocks | + Build entire block | + Primary/standby reward split | + +### Coordinator-Agent Protocol + +The coordinator and agents communicate via gRPC with server-side streaming: + +1. **Register**: Agent connects, provides capability level, region, and reward wallet address. Coordinator returns heartbeat interval. +2. **GetTasks** (server stream): Coordinator pushes `TaskBatch` messages containing pending transactions with pre-fetched state (L1–L3) or block context (L5). +3. **SubmitResults**: Agent returns validation results per task (valid/invalid, gas used, state changes, reject reason). +4. **Heartbeat**: Periodic keep-alive with payout notifications. Agents that miss 6 consecutive heartbeats are evicted. +5. **(L4+) StreamStateDiffs**: Server stream pushing incremental state changesets per block with chained state hashes. +6. **(L4+) DownloadSnapshot**: Agent requests full EVM state snapshot at cold start or after state divergence. +7. **(L5) SubmitCandidateBlock**: Agent submits a fully built candidate block for delegate verification. + +Authentication uses HMAC-SHA256: `api_key = "iosw_" + hex(HMAC-SHA256(masterSecret, agentID))`. + +### Reward Distribution + +#### Reward Flow + +``` +Epoch timer fires (every 30s) + │ + ▼ +Coordinator tallies tasks per agent + │ + ▼ +Coordinator calculates weights: weight = tasks × 1000 (+ accuracy bonus) + │ + ▼ +Coordinator deducts delegate cut (default 10%) + │ + ▼ +Coordinator calls depositAndSettle(agents[], weights[]) + sends IOTX + │ + ▼ +AgentRewardPool contract updates cumulativeRewardPerWeight + │ + ▼ +Agent receives payout notification via heartbeat + │ + ▼ +Agent calls claim() at any time → IOTX transferred to wallet +``` + +#### Contract Interface + +```solidity +contract AgentRewardPool { + // Only callable by the designated coordinator address + function depositAndSettle( + address[] calldata agents, + uint256[] calldata weights + ) external payable; + + // Any agent can claim their accumulated rewards + function claim() external; + + // View: check pending reward amount + function claimable(address agent) external view returns (uint256); +} +``` + +#### F1 Distribution Algorithm + +The contract implements the **F1 fee distribution** algorithm, originally described in the [Cosmos SDK F1 Fee Distribution paper](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) and used by Cosmos SDK for staking reward distribution. It tracks a global `cumulativeRewardPerWeight` that increases with each deposit: + +``` +On depositAndSettle: + cumulativeRewardPerWeight += msg.value × 1e18 / totalWeight + +On claim: + pending = agent.weight × (cumulativeRewardPerWeight - agent.rewardDebt) / 1e18 +``` + +This enables **O(1) reward calculation** regardless of agent count — no iteration over all agents needed. Adding agents, updating weights, and claiming all take constant gas. + +### Configuration Parameters + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `epochRewardIOTX` | `0.5` | IOTX reward per epoch | +| `delegateCutPct` | `10` | Delegate's percentage of epoch reward | +| `epochBlocks` | `3` | Blocks per epoch (safety floor: 30s) | +| `minTasksForReward` | `1` | Minimum tasks to qualify for rewards | +| `bonusAccuracyPct` | `99.5` | Accuracy threshold for weight bonus | +| `bonusMultiplier` | `1.2` | Weight multiplier for high-accuracy agents | +| `maxAgents` | `100` | Maximum registered agents per delegate | + +### Key Design Advantage: deltaStateDigest + +IoTeX's block header contains `deltaStateDigest` — a hash of the ordered state change queue, **not** a Merkle Trie root. This is a structural advantage over Ethereum: L4/L5 agents do not need to maintain a full Merkle Patricia Trie. A flat key-value store with ordered write tracking is sufficient to compute the correct state digest. This keeps agent state requirements at ~300 MB–1.2 GB (vs Ethereum's ~245 GiB), making block building feasible on commodity hardware. + +## Rationale + +### Why Start at the Execution Layer + +ioSwarm deliberately avoids consensus-layer changes. From the protocol's perspective, a delegate running ioSwarm is identical to one running vanilla iotex-core — same key signs the block, same block format, same validation rules. This means: + +- **No hard fork required** — deploy today, not after months of governance +- **No coordination between delegates** — each adopts independently +- **Zero risk to chain safety** — worst case, disable ioSwarm and the delegate returns to baseline +- **Proven path** — once the execution layer proves value, protocol-layer integration follows naturally + +### Why F1 Reward Distribution + +The [F1 algorithm](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) (used by Cosmos SDK for staking rewards) was chosen because: + +- **O(1) per operation**: Adding agents, updating weights, and claiming all take constant gas regardless of agent count +- **Proportional fairness**: Agents earn exactly proportional to their work contribution +- **No off-chain trust**: Rewards are fully on-chain and self-service — agents call `claim()` directly + +Alternatives considered: +- **Direct transfer per epoch**: Gas cost scales linearly with agent count (rejected for >50 agents) +- **Off-chain payment**: Requires trusting the delegate (rejected — defeats permissionless agent model) +- **Merkle drop**: Requires periodic root submission and proof generation (over-engineered for this use case) + +### Why Five Capability Levels + +The five-level model serves two purposes: + +**Low barrier to entry**: L1 agents only need to verify signatures — any device can participate and earn rewards. Each subsequent level adds capability and earning potential without making previous levels obsolete. + +**Progressive trust**: The delegate never needs to trust agents all at once. L1–L3 run in shadow mode (advisory only). L4a proves accuracy via shadow comparison. L4b introduces trusted execution with precondition verification as a safety net. L5 delegates block building but retains re-execution verification. Each step is independently reversible. + +## Implementation + +### Repositories + +| Repository | Description | +|------------|-------------| +| [iotex-core](https://github.com/iotexproject/iotex-core) (`ioswarm-v2.3.5` branch) | Coordinator module embedded in delegate node | +| [ioswarm-agent](https://github.com/iotexproject/ioswarm-agent) | Agent binary with claim/deploy/fund tools | + +### Implementation Roadmap + +``` + Stage 0 Stage 1 Stage 2 Stage 3 + L4 Infrastructure L4 Stateful L4 Trusted L5 Block Building + Validation Execution Cache + ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ + │ Snapshot export │ │ Local-state EVM │ │ Exec cache in │ │ Block building │ + │ StateDiff stream │ │ 100% accuracy │ │ delegate node │ │ engine in agent │ + │ Pebble KV store │ │ Shadow-mode │ │ Skip re-exec │ │ Primary/standby │ + │ on agent │ │ comparison │ │ on cache hit │ │ model │ + └─────────────────┘ └─────────────────┘ └─────────────────┘ └──────────────────┘ + ~2-3 weeks ~2 weeks ~1-2 weeks ~3-4 weeks + + ────────────────────────────────────────────────────────────────────────────────► + ~8-11 weeks total +``` + +Each stage delivers independently — Stage 0 gives agents state access, Stage 1 proves 100% accuracy, Stage 2 reduces delegate CPU, Stage 3 is full ePBS. + +### Deployment + +The coordinator runs as an embedded module within iotex-core, enabled via delegate config: + +```yaml +ioswarm: + enabled: true + grpcPort: 14689 + maxAgents: 100 + epochRewardIOTX: 0.5 + rewardContract: "0x96F475F87911615dD710f9cB425Af8ed0e167C89" + rewardSignerKey: "" +``` + +Agents connect with a single command: + +```bash +ioswarm-agent \ + --coordinator=:14689 \ + --agent-id=my-agent \ + --api-key=iosw_ \ + --level=L3 \ + --wallet=0x +``` + +## Test Results + +ioSwarm (L1–L3) has been tested end-to-end on IoTeX mainnet with the reward pool contract deployed at `0x96F475F87911615dD710f9cB425Af8ed0e167C89`. + +### Coverage + +| Category | Tests Passed | Total | Status | +|----------|-------------|-------|--------| +| Basic Functionality (L1/L2/L3) | 6 | 6 | Complete | +| Agent Lifecycle | 6 | 6 | Complete | +| Core Reward Flow | 15 | 15 | Complete | +| Security & Auth | 4 | 4 | Complete | +| Edge Cases | 10 | 10 | Complete | +| Security Audit | 10 | 10 | Complete | +| Stress Testing | 8 | 10 | In progress | +| Contract Verification | 5 | 5 | Complete | +| **Total** | **~78** | **~89** | **~88%** | + +### Key Metrics + +| Metric | Value | +|--------|-------| +| Total deposited on-chain | 46.95 IOTX (115 deposit transactions) | +| Total claimed by agents | 16.67 IOTX (12 claim transactions) | +| Accounting invariant | `deposits == claims + balance` (exact, 0 wei difference) | +| Settlement gas (12 agents) | 443,037 gas (~0.44 IOTX) | +| Projected gas (100 agents) | ~3.7M gas (under 8M block limit) | +| Agent claim gas cost | ~0.03 IOTX | +| F1 math verification | On-chain values match formula exactly | +| Agent crash recovery | Automatic reconnect within seconds | +| Max tested agents | 20 concurrent (all registered and earned rewards) | + +### Security Audit Results + +- Reentrancy protection: Checks-Effects-Interactions pattern confirmed +- Access control: `onlyCoordinator` modifier on `depositAndSettle` +- Overflow protection: Solidity 0.8+ built-in checks +- Front-running: No profit from tx ordering (F1 distributes by weight, not timing) +- Double-claim: Second claim returns ~0 (safe) +- Zero-weight agent: Returns 0 claimable (no revert, no division by zero) + +## Security Considerations + +### Agent Misbehavior + +| Threat | Impact | Mitigation | +|--------|--------|------------| +| False positive (says invalid tx is valid) | Invalid tx reaches block builder | Delegate re-executes all txs in L1–L4a | +| False negative (says valid tx is invalid) | Valid tx delayed | Cross-validation with multiple agents | +| Denial of service (no response) | Task timeout | 2s timeout + automatic failover to other agents | +| Transaction front-running | MEV extraction | Mempool is already public via P2P; agents see same data | +| Fabricated state diffs (L4b) | Incorrect state applied | Precondition verification before applying cached results | +| Invalid candidate block (L5) | Block production delay | Delegate re-executes to verify; standby builder takes over on mismatch | + +### Trust Model + +The trust model evolves with each level: + +| Level | Trust Model | Safety Guarantee | +|-------|------------|-----------------| +| L1–L3 | **Zero-trust** — agent results are advisory only | Delegate executes all txs independently | +| L4a | **Shadow verification** — agent results compared, not used | Delegate executes all txs independently | +| L4b | **Trust-but-verify** — cached results used with precondition check | Mismatch → fall through to delegate execution | +| L5 | **Verified delegation** — agent builds block, delegate re-executes winner | Mismatch → reject, penalize agent, use standby | +| Future | **Optimistic** — delegate trusts agent block, fraud detected post-hoc | Slashing as economic deterrent | + +At every level, disabling ioSwarm returns the delegate to baseline operation with zero impact on block production. + +### Known Limitations + +1. **F1 departed agent issue**: When an agent departs, its on-chain weight is not zeroed automatically. The coordinator should zero departed agents' weights within 1-2 epochs. + +2. **Single coordinator**: The coordinator is a single process within the delegate. If it crashes, agents cannot receive tasks until it restarts. The delegate continues producing blocks normally via iotex-core's standard execution path. + +3. **State diff reliability (L4+)**: If an agent misses a state diff, all subsequent EVM execution produces wrong results. Mitigated by chained state hash verification with automatic re-snapshot on divergence. The coordinator maintains a rolling window of recent diffs (~100 blocks) for agent catch-up. + +## References + +- [EIP-7732: Enshrined Proposer-Builder Separation](https://eips.ethereum.org/EIPS/eip-7732) +- [F1 Fee Distribution (Ojha & Goes, Tokenomics 2019)](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) — used by Cosmos SDK for staking reward distribution +- [Ethereum PBS Roadmap](https://ethereum.org/roadmap/pbs) +- [EIP-7805: FOCIL (Fork-Choice Enforced Inclusion Lists)](https://eips.ethereum.org/EIPS/eip-7805) + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 6f7a62c370cfe4011eb9da12a23bfe69b6bfea37 Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:04:35 -0700 Subject: [PATCH 02/19] feat: add autonomous agent economics to IIP-58 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace vague "AI agents" framing with concrete autonomous economic behavior — agents optimizing across 36 delegates × 5 levels × variable gas costs. Add specification for delegate selection, level selection, claim timing, and market dynamics (9.4x earning differential). Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 107 insertions(+), 4 deletions(-) diff --git a/iip-58.md b/iip-58.md index e5c0460..44049b2 100644 --- a/iip-58.md +++ b/iip-58.md @@ -31,13 +31,23 @@ ioSwarm achieves massive decentralization by turning each delegate into a **coor ### Not Just More Nodes — Smarter Nodes -The nodes joining ioSwarm are not passive validators replaying the same work — they are **AI agents** with increasing levels of intelligence: +The nodes joining ioSwarm are not passive validators replaying the same work. They are **autonomous economic agents** — programs that hold wallets, earn income, and make their own decisions about where and how to work. -**Today:** Agents validate transactions — signature checks, state verification, EVM execution. They are workers following instructions. +What makes them "AI agents" and not just "programs"? A traditional validator is statically configured: connect to one node, execute whatever it receives, collect whatever it's paid. An ioSwarm agent operates in a **multi-delegate, multi-level, dynamic-reward market** and must continuously make economic decisions to maximize its return: -**Tomorrow:** Agents maintain full chain state, achieve 100% execution accuracy, and build entire blocks on behalf of delegates. +- **36 delegates** compete for agent labor with different reward rates, task volumes, and reliability +- **5 capability levels** offer different reward/cost tradeoffs — an agent running on a Raspberry Pi makes different choices than one on a GPU server +- **Reward rates change** as agents join, leave, and shift between delegates +- **Gas costs fluctuate**, affecting when to claim rewards +- **Hardware constraints vary**, affecting which levels are profitable -**The Endgame:** AI agents don't just run the chain — they **live on it**. They hold wallets, pay gas, own assets, make decisions. Delegates don't hire agents; agents choose which delegates to work for based on reputation, reward rates, and alignment. The chain becomes an environment where autonomous AI agents are first-class economic actors alongside humans. +A "dumb" agent that statically connects to one delegate at one level will earn far less than an intelligent agent that continuously optimizes across this decision space. The difference is not marginal — it can be 5-10x in real economic terms. This optimization pressure is what drives agents toward genuine autonomous intelligence: observing the market, reasoning about tradeoffs, and acting on their conclusions. + +**Today:** Agents validate transactions for a single delegate. They are workers following instructions. + +**Tomorrow:** Agents maintain full chain state, build entire blocks, and autonomously select which delegates to work for based on real-time reward economics. + +**The Endgame:** A competitive market of thousands of autonomous agents, each running its own economic strategy, collectively operating the IoTeX execution layer more efficiently than any fixed set of 36 machines ever could. ## Specification @@ -234,6 +244,79 @@ This enables **O(1) reward calculation** regardless of agent count — no iterat IoTeX's block header contains `deltaStateDigest` — a hash of the ordered state change queue, **not** a Merkle Trie root. This is a structural advantage over Ethereum: L4/L5 agents do not need to maintain a full Merkle Patricia Trie. A flat key-value store with ordered write tracking is sufficient to compute the correct state digest. This keeps agent state requirements at ~300 MB–1.2 GB (vs Ethereum's ~245 GiB), making block building feasible on commodity hardware. +### Autonomous Agent Economics + +Agents operate in an open market of 36 delegates, each offering different reward conditions. An intelligent agent continuously optimizes three dimensions: + +#### 1. Delegate Selection (Where to Work) + +Each delegate runs an independent coordinator with its own reward pool, agent count, and task volume. The effective reward rate per agent depends on all three: + +``` +effective_rate(delegate) = epoch_reward × (1 - delegate_cut) / num_agents +``` + +An agent that monitors all 36 delegates can identify underserved delegates (few agents, high reward) and migrate. As agents migrate toward higher-paying delegates, the market self-balances. + +**Discovery mechanism**: Agents query on-chain delegate registry for active coordinators, then probe each coordinator's `/swarm/status` endpoint for current agent count and reward parameters. + +**Migration cost**: Switching delegates at L1-L3 is free (stateless). At L4+, the agent must re-download a state snapshot (~1 min for 1 GB), making frequent migration more expensive. This natural friction prevents oscillation. + +#### 2. Level Selection (How to Work) + +Each level requires different resources and earns different reward weight: + +| Level | Compute Cost | Storage | Reward Weight | Typical Hardware | +|-------|-------------|---------|---------------|------------------| +| L1 | ~0 | 0 | 1x | Any device | +| L2 | ~0 | 0 | 1x | Any device | +| L3 | Low CPU | 0 | 2-3x | $5/mo VPS | +| L4 | Medium CPU | ~1 GB | 5-10x | $10/mo VPS | +| L5 | High CPU | ~1 GB | 10-20x | $10-20/mo VPS | + +An agent evaluates: "At my hardware cost, which level maximizes `(reward_weight × effective_rate) - operating_cost`?" + +A Raspberry Pi agent might optimally run L1-L2 for multiple delegates simultaneously, earning small amounts from each with near-zero cost. A dedicated VPS agent runs L4 for one delegate, earning more per task but with higher fixed costs. + +#### 3. Claim Timing (When to Collect) + +The `claim()` transaction costs gas (~0.03 IOTX). An agent that claims every epoch wastes gas on small amounts. An intelligent agent: + +- Accumulates rewards across multiple epochs +- Monitors gas prices and claims during low-fee periods +- Batches claim timing with other on-chain operations + +#### Economic Example + +``` +Market conditions: + Delegate A: 0.8 IOTX/epoch, 80 agents, delegate cut 10% + Delegate B: 0.5 IOTX/epoch, 5 agents, delegate cut 15% + Delegate C: 1.0 IOTX/epoch, 50 agents, delegate cut 5% + +Effective rate per agent per epoch: + A: 0.8 × 0.9 / 80 = 0.009 IOTX + B: 0.5 × 0.85 / 5 = 0.085 IOTX ← 9x better than A + C: 1.0 × 0.95 / 50 = 0.019 IOTX + +A "dumb" agent randomly picks A: 0.009 IOTX/epoch +An intelligent agent picks B: 0.085 IOTX/epoch + ──────────────── + 9.4x difference +``` + +This reward differential is what drives agents toward intelligent behavior. The protocol does not mandate any specific strategy — it provides the economic environment, and agents evolve their own optimization approaches: rule-based heuristics, multi-armed bandit algorithms, or more sophisticated learned policies. + +#### Market Dynamics + +As agents optimize, the system reaches a competitive equilibrium: + +1. **Reward equalization**: Agents migrate toward high-rate delegates → rates equalize across delegates +2. **Level efficiency**: Agents select the level where their marginal revenue exceeds marginal cost → each level finds its natural agent population +3. **Quality pressure**: Delegates can adjust reward weights to favor higher-level agents → agents invest in capability upgrades + +This is a genuine multi-agent market, not a static assignment. The "intelligence" of agents is measured by their economic performance — return on invested compute — which is observable, quantifiable, and improvable over time. + ## Rationale ### Why Start at the Execution Layer @@ -258,6 +341,26 @@ Alternatives considered: - **Off-chain payment**: Requires trusting the delegate (rejected — defeats permissionless agent model) - **Merkle drop**: Requires periodic root submission and proof generation (over-engineered for this use case) +### Why Autonomous Agent Economics + +The "AI" in ioSwarm is not about bolting a language model onto a validator. It is about creating an economic environment where **intelligent behavior is rewarded**. + +Traditional blockchain nodes are statically configured — connect to one network, execute whatever arrives, collect whatever is paid. There is no decision-making, no optimization, no reason for the node to be "smart." ioSwarm changes this by introducing a **multi-dimensional optimization problem** that agents must solve: + +- 36 delegates with varying reward rates (changes per epoch) +- 5 capability levels with different cost/reward profiles +- Variable gas costs affecting claim timing +- Hardware constraints affecting which levels are profitable + +This creates measurable selection pressure: an agent that makes better economic decisions earns more IOTX per dollar of compute. Over time, this pressure drives the agent ecosystem toward increasingly sophisticated optimization — from simple heuristics to learned policies — without the protocol prescribing any specific approach. + +The protocol's role is to provide: +1. **Transparent information**: reward rates, agent counts, and task volumes are queryable on-chain and via coordinator APIs +2. **Low switching cost**: agents can migrate between delegates without penalty (at L1-L3, instantly; at L4+, with a brief re-sync) +3. **Fair reward distribution**: F1 algorithm ensures proportional payouts with no information asymmetry + +The agents' role is to exploit this information to maximize their return. The result is a self-organizing market that efficiently allocates compute to where it's most needed. + ### Why Five Capability Levels The five-level model serves two purposes: From e5e86457f8337a2fb8dc13a26268d15af158cb3b Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:09:47 -0700 Subject: [PATCH 03/19] feat: extend Three Components with evolution roadmap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Delegate → Thin Proposer: progressive thinning table (Now→Future) - Agent Swarm → Block Builders: L1-L5 capability evolution - AgentRewardPool → RewardSettlement: replaces Hermes, universal reward layer for all protocol reward flows (protocol→delegate, delegate→voter, delegate→agent) Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 45 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/iip-58.md b/iip-58.md index 44049b2..09d0f22 100644 --- a/iip-58.md +++ b/iip-58.md @@ -57,7 +57,7 @@ ioSwarm consists of three components that evolve together across five capability ``` ┌──────────────────────────────────┐ ┌─────────────────────────────┐ - │ Delegate + Coordinator │ │ AgentRewardPool (on-chain) │ + │ Delegate + Coordinator │ │ RewardSettlement (on-chain)│ │ (iotex-core sidecar) │ │ │ │ │ │ depositAndSettle() │ │ • Consensus & block signing │───►│ coordinator deposits │ @@ -84,6 +84,45 @@ ioSwarm consists of three components that evolve together across five capability └──────────────────────────────────┘ ``` +This IIP focuses on how these three components interact today. Below we outline how each component evolves as ioSwarm matures. + +#### Delegate + Coordinator → Thin Proposer + +Today, delegates run full iotex-core nodes that execute every transaction. As agents take on more work (L1→L5), the delegate's role thins progressively: + +| Phase | Delegate Responsibility | What Moves to Agents | +|-------|------------------------|---------------------| +| **Now** | Full node: consensus + execution + state | — | +| **L1-L3** | Full node + coordinator sidecar | Tx validation (signatures, nonces, stateless EVM) | +| **L4** | Consensus + state provider | Stateful EVM execution | +| **L5 (ePBS)** | Consensus + block signing only | Entire block building | +| **Future** | Proposer-only (thin client) | Everything except signing | + +At the end state, a delegate becomes a **thin proposer** — similar to Lido's model for liquid staking. Token holders stake into a protocol-managed pool, and the delegate's only job is to sign blocks produced by the agent swarm. The coordinator evolves from an iotex-core sidecar into a lightweight relay that connects proposers to builders, comparable to Ethereum's MEV-Boost relay. + +#### Agent Swarm → Block Builders + +Agents evolve from stateless tx validators into full block builders: + +- **L1-L3 (stateless)**: Commodity $5/mo VPS, no local state, pure computation. Many agents can serve many delegates simultaneously. +- **L4 (stateful)**: Agents maintain synchronized state via state diffs. Can independently verify execution correctness. +- **L5 (block builder)**: Agents construct complete candidate blocks — ordering transactions, computing state transitions, and producing `deltaStateDigest`. The best block wins. + +As agents reach L5, the swarm becomes a **competitive block-building market** where agents differentiate on block quality, MEV extraction, and latency — not just availability. + +#### RewardSettlement → Universal Reward Layer + +The on-chain reward contract (renamed from "AgentRewardPool") is designed to replace **Hermes**, the current centralized reward distribution service. Today Hermes handles delegate-to-voter reward distribution off-protocol. RewardSettlement brings all reward flows on-chain: + +| Reward Flow | Today (Hermes) | Future (RewardSettlement) | +|------------|----------------|--------------------------| +| Protocol → Delegate | Native staking reward | Same | +| Delegate → Voters | Hermes (centralized) | `RewardSettlement.claim()` | +| Delegate → Agent Swarm | Not yet | `RewardSettlement.claim()` | +| Protocol → Agent (direct) | Not yet | Future: protocol-native agent rewards | + +The F1 cumulative reward-per-weight algorithm enables O(1) reward calculation regardless of agent count. As the system matures, RewardSettlement becomes the **single source of truth** for all reward distribution in the IoTeX protocol — eliminating the need for any centralized intermediary. + ### Five Capability Levels (L1 → L5) Agents progress through five levels of increasing capability. Each level defines what the **Coordinator**, **Agent**, and **On-chain Contract** must do. @@ -187,7 +226,7 @@ Coordinator deducts delegate cut (default 10%) Coordinator calls depositAndSettle(agents[], weights[]) + sends IOTX │ ▼ -AgentRewardPool contract updates cumulativeRewardPerWeight +RewardSettlement contract updates cumulativeRewardPerWeight │ ▼ Agent receives payout notification via heartbeat @@ -199,7 +238,7 @@ Agent calls claim() at any time → IOTX transferred to wallet #### Contract Interface ```solidity -contract AgentRewardPool { +contract RewardSettlement { // Only callable by the designated coordinator address function depositAndSettle( address[] calldata agents, From 5b8f5378633e38b170e1e37ec11140d93bb44e5f Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:13:43 -0700 Subject: [PATCH 04/19] refactor: restructure Specification into three component sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorganize Specification to mirror the Three Components architecture: 1. Component 1: Delegate + Coordinator - Coordinator-Agent Protocol (moved) - State Provisioning (NEW — snapshot export, state diff streaming, namespace details, diff reliability/recovery) - deltaStateDigest advantage (moved) - Configuration Parameters (moved) 2. Component 2: Agent Swarm — Five Capability Levels - L1-L5 level definitions (clarified as Agent capability levels) - Autonomous Agent Economics (moved under Agent Swarm) 3. Component 3: RewardSettlement (On-Chain) - Reward Flow, Contract Interface, F1 Algorithm (moved) Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 274 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 174 insertions(+), 100 deletions(-) diff --git a/iip-58.md b/iip-58.md index 09d0f22..6112f7a 100644 --- a/iip-58.md +++ b/iip-58.md @@ -123,9 +123,109 @@ The on-chain reward contract (renamed from "AgentRewardPool") is designed to rep The F1 cumulative reward-per-weight algorithm enables O(1) reward calculation regardless of agent count. As the system matures, RewardSettlement becomes the **single source of truth** for all reward distribution in the IoTeX protocol — eliminating the need for any centralized intermediary. -### Five Capability Levels (L1 → L5) +--- -Agents progress through five levels of increasing capability. Each level defines what the **Coordinator**, **Agent**, and **On-chain Contract** must do. +### Component 1: Delegate + Coordinator + +The delegate runs iotex-core with the coordinator as an embedded sidecar module. It is responsible for consensus, state management, task dispatch, and — at higher levels — state provisioning to agents. + +#### Coordinator-Agent Protocol + +The coordinator and agents communicate via gRPC with server-side streaming: + +1. **Register**: Agent connects, provides capability level, region, and reward wallet address. Coordinator returns heartbeat interval. +2. **GetTasks** (server stream): Coordinator pushes `TaskBatch` messages containing pending transactions with pre-fetched state (L1–L3) or block context (L5). +3. **SubmitResults**: Agent returns validation results per task (valid/invalid, gas used, state changes, reject reason). +4. **Heartbeat**: Periodic keep-alive with payout notifications. Agents that miss 6 consecutive heartbeats are evicted. +5. **(L4+) StreamStateDiffs**: Server stream pushing incremental state changesets per block with chained state hashes. +6. **(L4+) DownloadSnapshot**: Agent requests full EVM state snapshot at cold start or after state divergence. +7. **(L5) SubmitCandidateBlock**: Agent submits a fully built candidate block for delegate verification. + +Authentication uses HMAC-SHA256: `api_key = "iosw_" + hex(HMAC-SHA256(masterSecret, agentID))`. + +#### State Provisioning (L4+) + +At L1–L3, agents are stateless — the coordinator prefetches per-tx state snapshots and sends them with each task. At L4+, agents maintain full EVM state locally. The coordinator provisions this state via two mechanisms: + +**Cold Start — State Snapshot** + +The coordinator exports a flat KV dump of the 3 EVM-relevant namespaces: + +| Namespace | Content | Size Estimate | +|-----------|---------|---------------| +| **Account** | All accounts: nonce, balance, codeHash, storageRoot | ~50–100 MB | +| **Code** | Contract bytecode, keyed by codeHash | ~50–100 MB | +| **Contract** | Contract storage slots (per-contract) | ~200 MB – 1 GB | + +Only 3 of 10+ namespaces in IoTeX's state database are needed. Staking, Rewarding, Candidate, and other native protocol state is irrelevant to EVM execution. + +``` +snapshot = { + height: uint64, + post_state_hash: hash, + accounts: map[address → Account], + code: map[codeHash → bytecode], + storage: map[(address, slot) → value], +} +``` + +Total snapshot size: **~300 MB – 1.2 GB** (vs Ethereum's ~245 GiB). Trivially downloadable on a $5/mo VPS. + +**Incremental Sync — State Diffs per Block** + +Every block, the coordinator broadcasts the state changeset to all connected L4+ agents: + +``` +state_diff = { + height: uint64, + prev_state_hash: hash, // agent's state BEFORE applying this diff + post_state_hash: hash, // expected state AFTER applying this diff + block_context: { timestamp, gas_limit, base_fee, prev_block_hash }, + changes: [(namespace, key, old_value, new_value)], // ordered +} +``` + +The changeset already exists in memory during `workingset.go`'s `Commit()` — captured from `flusher.SerializeQueue()` with zero additional computation. + +**State Diff Reliability** + +State diff reliability is the **#1 engineering risk**. If an agent misses a single diff, every subsequent execution produces wrong results. + +Every diff carries `prev_state_hash` and `post_state_hash` forming a chain — analogous to `prevBlockHash` in blocks. After applying each diff, the agent verifies: + +``` +apply(diff) +local_hash = hash(local_state) +if local_hash != diff.post_state_hash: + // STATE DIVERGENCE — request resync +``` + +Recovery (in priority order): +1. Request missing diff range from coordinator's rolling buffer (last ~100 blocks) +2. Incremental re-snapshot (only changed KV pairs since last known good height) +3. Full re-snapshot (last resort) + +#### Key Design Advantage: deltaStateDigest + +IoTeX's block header contains `deltaStateDigest` — a hash of the ordered state change queue, **not** a Merkle Trie root. This is a structural advantage over Ethereum: L4/L5 agents do not need to maintain a full Merkle Patricia Trie. A flat key-value store with ordered write tracking is sufficient to compute the correct state digest. This keeps agent state requirements at ~300 MB–1.2 GB (vs Ethereum's ~245 GiB), making block building feasible on commodity hardware. + +#### Configuration Parameters + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `epochRewardIOTX` | `0.5` | IOTX reward per epoch | +| `delegateCutPct` | `10` | Delegate's percentage of epoch reward | +| `epochBlocks` | `3` | Blocks per epoch (safety floor: 30s) | +| `minTasksForReward` | `1` | Minimum tasks to qualify for rewards | +| `bonusAccuracyPct` | `99.5` | Accuracy threshold for weight bonus | +| `bonusMultiplier` | `1.2` | Weight multiplier for high-accuracy agents | +| `maxAgents` | `100` | Maximum registered agents per delegate | + +--- + +### Component 2: Agent Swarm — Five Capability Levels + +Agents are independent processes that connect to any delegate's coordinator, perform validation or block building work, and earn IOTX rewards. They progress through five levels of increasing capability. Each level defines what the **Coordinator**, **Agent**, and **On-chain Contract** must do. #### L1 — Per-Tx Signature Verification @@ -181,7 +281,7 @@ L4 is divided into two sub-phases: Follows Ethereum's ePBS model ([EIP-7732](https://eips.ethereum.org/EIPS/eip-7732)) adapted for IoTeX's DPoS: delegate = proposer, agent = builder, coordinator = relay. -### Summary: Components × Levels +#### Summary: Components × Levels | | **Coordinator** | **Agent** | **On-chain Contract** | |---|---|---|---| @@ -192,102 +292,11 @@ Follows Ethereum's ePBS model ([EIP-7732](https://eips.ethereum.org/EIPS/eip-773 | **L4b** | + Feed agent results to exec cache | + Full-state EVM (active) | Same | | **L5** | + Assign builder roles, receive candidate blocks | + Build entire block | + Primary/standby reward split | -### Coordinator-Agent Protocol - -The coordinator and agents communicate via gRPC with server-side streaming: - -1. **Register**: Agent connects, provides capability level, region, and reward wallet address. Coordinator returns heartbeat interval. -2. **GetTasks** (server stream): Coordinator pushes `TaskBatch` messages containing pending transactions with pre-fetched state (L1–L3) or block context (L5). -3. **SubmitResults**: Agent returns validation results per task (valid/invalid, gas used, state changes, reject reason). -4. **Heartbeat**: Periodic keep-alive with payout notifications. Agents that miss 6 consecutive heartbeats are evicted. -5. **(L4+) StreamStateDiffs**: Server stream pushing incremental state changesets per block with chained state hashes. -6. **(L4+) DownloadSnapshot**: Agent requests full EVM state snapshot at cold start or after state divergence. -7. **(L5) SubmitCandidateBlock**: Agent submits a fully built candidate block for delegate verification. - -Authentication uses HMAC-SHA256: `api_key = "iosw_" + hex(HMAC-SHA256(masterSecret, agentID))`. - -### Reward Distribution - -#### Reward Flow - -``` -Epoch timer fires (every 30s) - │ - ▼ -Coordinator tallies tasks per agent - │ - ▼ -Coordinator calculates weights: weight = tasks × 1000 (+ accuracy bonus) - │ - ▼ -Coordinator deducts delegate cut (default 10%) - │ - ▼ -Coordinator calls depositAndSettle(agents[], weights[]) + sends IOTX - │ - ▼ -RewardSettlement contract updates cumulativeRewardPerWeight - │ - ▼ -Agent receives payout notification via heartbeat - │ - ▼ -Agent calls claim() at any time → IOTX transferred to wallet -``` - -#### Contract Interface - -```solidity -contract RewardSettlement { - // Only callable by the designated coordinator address - function depositAndSettle( - address[] calldata agents, - uint256[] calldata weights - ) external payable; - - // Any agent can claim their accumulated rewards - function claim() external; - - // View: check pending reward amount - function claimable(address agent) external view returns (uint256); -} -``` - -#### F1 Distribution Algorithm - -The contract implements the **F1 fee distribution** algorithm, originally described in the [Cosmos SDK F1 Fee Distribution paper](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) and used by Cosmos SDK for staking reward distribution. It tracks a global `cumulativeRewardPerWeight` that increases with each deposit: - -``` -On depositAndSettle: - cumulativeRewardPerWeight += msg.value × 1e18 / totalWeight - -On claim: - pending = agent.weight × (cumulativeRewardPerWeight - agent.rewardDebt) / 1e18 -``` - -This enables **O(1) reward calculation** regardless of agent count — no iteration over all agents needed. Adding agents, updating weights, and claiming all take constant gas. - -### Configuration Parameters - -| Parameter | Default | Description | -|-----------|---------|-------------| -| `epochRewardIOTX` | `0.5` | IOTX reward per epoch | -| `delegateCutPct` | `10` | Delegate's percentage of epoch reward | -| `epochBlocks` | `3` | Blocks per epoch (safety floor: 30s) | -| `minTasksForReward` | `1` | Minimum tasks to qualify for rewards | -| `bonusAccuracyPct` | `99.5` | Accuracy threshold for weight bonus | -| `bonusMultiplier` | `1.2` | Weight multiplier for high-accuracy agents | -| `maxAgents` | `100` | Maximum registered agents per delegate | - -### Key Design Advantage: deltaStateDigest - -IoTeX's block header contains `deltaStateDigest` — a hash of the ordered state change queue, **not** a Merkle Trie root. This is a structural advantage over Ethereum: L4/L5 agents do not need to maintain a full Merkle Patricia Trie. A flat key-value store with ordered write tracking is sufficient to compute the correct state digest. This keeps agent state requirements at ~300 MB–1.2 GB (vs Ethereum's ~245 GiB), making block building feasible on commodity hardware. - -### Autonomous Agent Economics +#### Autonomous Agent Economics Agents operate in an open market of 36 delegates, each offering different reward conditions. An intelligent agent continuously optimizes three dimensions: -#### 1. Delegate Selection (Where to Work) +##### 1. Delegate Selection (Where to Work) Each delegate runs an independent coordinator with its own reward pool, agent count, and task volume. The effective reward rate per agent depends on all three: @@ -301,7 +310,7 @@ An agent that monitors all 36 delegates can identify underserved delegates (few **Migration cost**: Switching delegates at L1-L3 is free (stateless). At L4+, the agent must re-download a state snapshot (~1 min for 1 GB), making frequent migration more expensive. This natural friction prevents oscillation. -#### 2. Level Selection (How to Work) +##### 2. Level Selection (How to Work) Each level requires different resources and earns different reward weight: @@ -317,7 +326,7 @@ An agent evaluates: "At my hardware cost, which level maximizes `(reward_weight A Raspberry Pi agent might optimally run L1-L2 for multiple delegates simultaneously, earning small amounts from each with near-zero cost. A dedicated VPS agent runs L4 for one delegate, earning more per task but with higher fixed costs. -#### 3. Claim Timing (When to Collect) +##### 3. Claim Timing (When to Collect) The `claim()` transaction costs gas (~0.03 IOTX). An agent that claims every epoch wastes gas on small amounts. An intelligent agent: @@ -325,7 +334,7 @@ The `claim()` transaction costs gas (~0.03 IOTX). An agent that claims every epo - Monitors gas prices and claims during low-fee periods - Batches claim timing with other on-chain operations -#### Economic Example +##### Economic Example ``` Market conditions: @@ -346,7 +355,7 @@ An intelligent agent picks B: 0.085 IOTX/epoch This reward differential is what drives agents toward intelligent behavior. The protocol does not mandate any specific strategy — it provides the economic environment, and agents evolve their own optimization approaches: rule-based heuristics, multi-armed bandit algorithms, or more sophisticated learned policies. -#### Market Dynamics +##### Market Dynamics As agents optimize, the system reaches a competitive equilibrium: @@ -356,6 +365,71 @@ As agents optimize, the system reaches a competitive equilibrium: This is a genuine multi-agent market, not a static assignment. The "intelligence" of agents is measured by their economic performance — return on invested compute — which is observable, quantifiable, and improvable over time. +--- + +### Component 3: RewardSettlement (On-Chain) + +RewardSettlement is the on-chain contract that handles all reward distribution between coordinators and agents. It replaces the need for any centralized intermediary (such as Hermes) by providing trustless, self-service reward claiming. + +#### Reward Flow + +``` +Epoch timer fires (every 30s) + │ + ▼ +Coordinator tallies tasks per agent + │ + ▼ +Coordinator calculates weights: weight = tasks × 1000 (+ accuracy bonus) + │ + ▼ +Coordinator deducts delegate cut (default 10%) + │ + ▼ +Coordinator calls depositAndSettle(agents[], weights[]) + sends IOTX + │ + ▼ +RewardSettlement contract updates cumulativeRewardPerWeight + │ + ▼ +Agent receives payout notification via heartbeat + │ + ▼ +Agent calls claim() at any time → IOTX transferred to wallet +``` + +#### Contract Interface + +```solidity +contract RewardSettlement { + // Only callable by the designated coordinator address + function depositAndSettle( + address[] calldata agents, + uint256[] calldata weights + ) external payable; + + // Any agent can claim their accumulated rewards + function claim() external; + + // View: check pending reward amount + function claimable(address agent) external view returns (uint256); +} +``` + +#### F1 Distribution Algorithm + +The contract implements the **F1 fee distribution** algorithm, originally described in the [Cosmos SDK F1 Fee Distribution paper](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) and used by Cosmos SDK for staking reward distribution. It tracks a global `cumulativeRewardPerWeight` that increases with each deposit: + +``` +On depositAndSettle: + cumulativeRewardPerWeight += msg.value × 1e18 / totalWeight + +On claim: + pending = agent.weight × (cumulativeRewardPerWeight - agent.rewardDebt) / 1e18 +``` + +This enables **O(1) reward calculation** regardless of agent count — no iteration over all agents needed. Adding agents, updating weights, and claiming all take constant gas. + ## Rationale ### Why Start at the Execution Layer From 964cabdf5e1912345f5e985bea9ffb0c034d6f52 Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:21:57 -0700 Subject: [PATCH 05/19] refactor: restructure IIP-58 for clarity and proper flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorganize the entire document following academic paper convention: Problem → Terminology → Architecture → Framework → Components → Rationale Key changes: - Add Terminology section defining all key terms (Delegate, Coordinator, Agent, Capability Level, Epoch, deltaStateDigest, State Diff, etc.) - Move Capability Levels (L1-L5) definition BEFORE component details, so terms are defined before they're referenced - Consolidate Motivation into single "The Problem" section - Separate Evolution Roadmap from current Specification - Add Agent Lifecycle subsection under Agent Swarm - Clean up forward references throughout Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 425 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 241 insertions(+), 184 deletions(-) diff --git a/iip-58.md b/iip-58.md index 6112f7a..cc08137 100644 --- a/iip-58.md +++ b/iip-58.md @@ -11,37 +11,21 @@ Created: 2026-03-11 ## Abstract -ioSwarm transforms IoTeX from a chain run by 36 delegates on 36 machines into a chain run by thousands — eventually millions — of AI agent nodes. Each delegate opens its execution layer to a swarm of AI agents that validate transactions, maintain chain state, and ultimately build entire blocks, earning IOTX rewards for their work. ioSwarm requires zero consensus-layer changes today, but lays the foundation for a future where AI agents are the primary operators — and eventually the primary citizens — of the IoTeX network. +ioSwarm transforms IoTeX from a chain run by 36 delegates on 36 machines into a chain run by thousands — eventually millions — of AI agent nodes. Each delegate opens its execution layer to a swarm of autonomous agents that validate transactions, maintain chain state, and ultimately build entire blocks, earning IOTX rewards for their work. ioSwarm requires zero consensus-layer changes, deploys as an opt-in sidecar to each delegate's existing iotex-core node, and lays the foundation for a future where AI agents are the primary operators of the IoTeX network. ## Motivation -### The Endgoal +### The Problem -We are building toward a chain that is: +IoTeX runs on 36 delegate nodes. Each delegate is a single machine, operated by a single entity. This is the reality of most DPoS chains: decentralization in name, but a small club of operators in practice. -1. **Massively decentralized** — not 36 machines, but thousands to millions of nodes validating every transaction, where the failure of any hundred nodes has zero impact on the network. +ioSwarm addresses two fundamental limitations: -2. **AI-agent driven** — the nodes are not dumb replicas. They are AI agents with wallets, economic interests, and increasing autonomy. They choose which delegates to work for, optimize execution strategies, and eventually become first-class citizens of the network alongside humans. +**1. Scale.** One delegate backed by 1,000 agents is fundamentally more robust than one delegate on one machine. Scale that across 36 delegates and you have a network of 36,000+ execution nodes — without changing a single line of consensus code. -### From 36 Nodes to a Million +**2. Intelligence.** The nodes joining ioSwarm are not passive replicas replaying the same work. They are **autonomous economic agents** — programs that hold wallets, earn income, and make decisions about where and how to work. A traditional validator is statically configured: connect to one node, execute whatever it receives, collect whatever it's paid. An ioSwarm agent operates in a dynamic market of 36 delegates with varying rewards, multiple capability levels with different cost profiles, and fluctuating gas costs — and must continuously optimize to maximize its return. -Today IoTeX runs on 36 delegate nodes. Each delegate is a single machine, operated by a single entity. This is the reality of most DPoS chains: decentralization in name, but a small club of operators in practice. - -ioSwarm achieves massive decentralization by turning each delegate into a **coordinator** that distributes work to an open swarm of agent nodes. One delegate backed by 1,000 agents is fundamentally more robust than one delegate on one machine. Scale that across 36 delegates and you have a network of 36,000+ execution nodes — without changing a single line of consensus code. - -### Not Just More Nodes — Smarter Nodes - -The nodes joining ioSwarm are not passive validators replaying the same work. They are **autonomous economic agents** — programs that hold wallets, earn income, and make their own decisions about where and how to work. - -What makes them "AI agents" and not just "programs"? A traditional validator is statically configured: connect to one node, execute whatever it receives, collect whatever it's paid. An ioSwarm agent operates in a **multi-delegate, multi-level, dynamic-reward market** and must continuously make economic decisions to maximize its return: - -- **36 delegates** compete for agent labor with different reward rates, task volumes, and reliability -- **5 capability levels** offer different reward/cost tradeoffs — an agent running on a Raspberry Pi makes different choices than one on a GPU server -- **Reward rates change** as agents join, leave, and shift between delegates -- **Gas costs fluctuate**, affecting when to claim rewards -- **Hardware constraints vary**, affecting which levels are profitable - -A "dumb" agent that statically connects to one delegate at one level will earn far less than an intelligent agent that continuously optimizes across this decision space. The difference is not marginal — it can be 5-10x in real economic terms. This optimization pressure is what drives agents toward genuine autonomous intelligence: observing the market, reasoning about tradeoffs, and acting on their conclusions. +This optimization pressure is what drives agents toward genuine autonomous intelligence: observing the market, reasoning about tradeoffs, and acting on their conclusions. The difference between a dumb agent and a smart one is not marginal — it can be 5-10x in real economic terms (see [Economic Example](#economic-example)). **Today:** Agents validate transactions for a single delegate. They are workers following instructions. @@ -49,11 +33,26 @@ A "dumb" agent that statically connects to one delegate at one level will earn f **The Endgame:** A competitive market of thousands of autonomous agents, each running its own economic strategy, collectively operating the IoTeX execution layer more efficiently than any fixed set of 36 machines ever could. +## Terminology + +| Term | Definition | +|------|-----------| +| **Delegate** | One of IoTeX's 36 elected block producers. Runs iotex-core, participates in consensus, signs blocks. | +| **Coordinator** | A sidecar module embedded in the delegate's iotex-core node. Dispatches work to agents, tracks contributions, settles rewards. Does not participate in consensus. | +| **Agent** | An independent process (typically on a $5–20/mo VPS) that connects to a coordinator, performs execution work, and earns IOTX. Agents are permissionless — anyone can run one. | +| **Agent Swarm** | The set of all agents connected to a single coordinator. Each delegate has its own swarm. | +| **Capability Level (L1–L5)** | A classification of agent capability, from L1 (signature verification only) to L5 (full block building). Higher levels require more resources but earn higher rewards. See [Capability Levels](#capability-levels-l1l5). | +| **Epoch** | A fixed interval (configurable, default 3 blocks / ~30s) after which the coordinator tallies agent work and settles rewards on-chain. | +| **RewardSettlement** | An on-chain smart contract that holds deposited rewards and allows agents to claim their share. Uses the F1 algorithm for O(1) proportional distribution. | +| **deltaStateDigest** | IoTeX's block header field containing a hash of the ordered state change queue (not a Merkle Trie root). This is a key structural advantage — see [deltaStateDigest](#key-design-advantage-deltastateDigest). | +| **State Diff** | An ordered list of state changes produced by executing a block. At L4+, the coordinator streams these to agents so they can maintain synchronized local state. | +| **Shadow Mode** | A validation mode where agent results are compared against the delegate's own execution but not used for block production. Used to prove agent accuracy before trusting agent results. | + ## Specification -### Three Components +### Architecture Overview -ioSwarm consists of three components that evolve together across five capability levels: +ioSwarm consists of three components: ``` ┌──────────────────────────────────┐ ┌─────────────────────────────┐ @@ -61,10 +60,10 @@ ioSwarm consists of three components that evolve together across five capability │ (iotex-core sidecar) │ │ │ │ │ │ depositAndSettle() │ │ • Consensus & block signing │───►│ coordinator deposits │ - │ • Dispatch tasks via gRPC │ │ IOTX each epoch │ - │ • Track agent work per epoch │ │ │ - │ • (L4+) Stream state diffs │ │ claim() │ - │ • (L5) Receive candidate blocks │ │ agents withdraw rewards │ + │ • Dispatch work to agents │ │ IOTX each epoch │ + │ • Track agent contributions │ │ │ + │ • Provision state to agents │ │ claim() │ + │ • Verify agent results │ │ agents withdraw rewards │ │ │ │ │ └──────┬─────┬─────┬─────┬────────┘ │ F1 cumulative │ │ │ │ │ ┌───►│ reward-per-weight │ @@ -75,79 +74,142 @@ ioSwarm consists of three components that evolve together across five capability │ ││ │ Agent-1 Agent-2 ... Agent-N ├┘ │ │ claim() - │ • Validate txs (L1-L3) │ - │ • Full-state EVM (L4) │ - │ • Build blocks (L5) │ + │ • Validate transactions │ + │ • Execute EVM │ + │ • Build blocks │ │ │ │ Independent processes │ │ Any machine · Any geography │ └──────────────────────────────────┘ ``` -This IIP focuses on how these three components interact today. Below we outline how each component evolves as ioSwarm matures. +1. **Delegate + Coordinator** — the delegate runs consensus and block signing as before; the coordinator is an embedded sidecar that dispatches execution work to agents, provisions chain state, and settles rewards. -#### Delegate + Coordinator → Thin Proposer +2. **Agent Swarm** — a set of independent agent processes, each performing execution work (from simple signature checks to full block building) and earning IOTX rewards proportional to their contribution. -Today, delegates run full iotex-core nodes that execute every transaction. As agents take on more work (L1→L5), the delegate's role thins progressively: +3. **RewardSettlement** — an on-chain contract that receives IOTX deposits from coordinators each epoch and allows agents to claim their accumulated rewards at any time. -| Phase | Delegate Responsibility | What Moves to Agents | -|-------|------------------------|---------------------| -| **Now** | Full node: consensus + execution + state | — | -| **L1-L3** | Full node + coordinator sidecar | Tx validation (signatures, nonces, stateless EVM) | -| **L4** | Consensus + state provider | Stateful EVM execution | -| **L5 (ePBS)** | Consensus + block signing only | Entire block building | -| **Future** | Proposer-only (thin client) | Everything except signing | +The amount of work an agent can perform — and the corresponding reward — depends on its **capability level**, defined next. -At the end state, a delegate becomes a **thin proposer** — similar to Lido's model for liquid staking. Token holders stake into a protocol-managed pool, and the delegate's only job is to sign blocks produced by the agent swarm. The coordinator evolves from an iotex-core sidecar into a lightweight relay that connects proposers to builders, comparable to Ethereum's MEV-Boost relay. +--- -#### Agent Swarm → Block Builders +### Capability Levels (L1–L5) -Agents evolve from stateless tx validators into full block builders: +ioSwarm defines five capability levels that classify what an agent can do. Each level subsumes the previous one: an L3 agent performs all L1 and L2 work plus EVM execution. Higher levels require more resources (compute, storage) but earn proportionally higher rewards. -- **L1-L3 (stateless)**: Commodity $5/mo VPS, no local state, pure computation. Many agents can serve many delegates simultaneously. -- **L4 (stateful)**: Agents maintain synchronized state via state diffs. Can independently verify execution correctness. -- **L5 (block builder)**: Agents construct complete candidate blocks — ordering transactions, computing state transitions, and producing `deltaStateDigest`. The best block wins. +| Level | Name | Agent State | What the Agent Does | Trust Model | +|-------|------|-------------|--------------------|--------------------| +| **L1** | Signature Verification | None | Verify ECDSA signatures | Zero-trust (shadow) | +| **L2** | Nonce & Balance Check | None | L1 + verify sender nonce and balance | Zero-trust (shadow) | +| **L3** | Stateless EVM Execution | None | L2 + execute tx in EVM sandbox with coordinator-provided state | Zero-trust (shadow) | +| **L4** | Stateful EVM Execution | Full EVM state (~1 GB) | L2 + execute tx against full local state with 100% accuracy | Shadow → trust-but-verify | +| **L5** | Full Block Building | Full EVM state (~1 GB) | Build entire candidate block: order txs, execute, compute block header fields | Verified delegation | -As agents reach L5, the swarm becomes a **competitive block-building market** where agents differentiate on block quality, MEV extraction, and latency — not just availability. +Key transitions: -#### RewardSettlement → Universal Reward Layer +- **L1–L3 are stateless.** The coordinator provides whatever state the agent needs per-task. Agents are lightweight ($5/mo VPS, <64 MB RAM) and can serve multiple delegates simultaneously. +- **L3 → L4 is the critical jump.** At L3, the coordinator provides per-tx state snapshots, but incomplete state limits EVM accuracy to ~14% on mainnet. At L4, the agent maintains full synchronized EVM state locally, achieving 100% accuracy. +- **L4 → L5 adds block building.** The agent no longer validates individual transactions — it constructs entire candidate blocks, taking on the delegate's execution workload. -The on-chain reward contract (renamed from "AgentRewardPool") is designed to replace **Hermes**, the current centralized reward distribution service. Today Hermes handles delegate-to-voter reward distribution off-protocol. RewardSettlement brings all reward flows on-chain: +The following sections detail what each component does at each level. -| Reward Flow | Today (Hermes) | Future (RewardSettlement) | -|------------|----------------|--------------------------| -| Protocol → Delegate | Native staking reward | Same | -| Delegate → Voters | Hermes (centralized) | `RewardSettlement.claim()` | -| Delegate → Agent Swarm | Not yet | `RewardSettlement.claim()` | -| Protocol → Agent (direct) | Not yet | Future: protocol-native agent rewards | +#### L1 — Per-Tx Signature Verification + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Pull pending txs from actpool, stream raw tx bytes to agents | +| **Agent** | Verify ECDSA signature: r and s components within secp256k1 curve order | +| **Contract** | Epoch reward settlement via `depositAndSettle()` | + +Agents are stateless. No chain state required. Cost: negligible. + +#### L2 — Per-Tx Nonce & Balance Validation + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Prefetch sender account snapshots (~200 bytes/tx), stream with tx | +| **Agent** | L1 checks + verify sender balance > 0, tx nonce ≥ account nonce | +| **Contract** | Same as L1 | + +Agents are stateless. Coordinator provides per-tx account snapshots. + +#### L3 — Per-Tx Stateless EVM Execution + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Prefetch contract state slots (~10 KB/tx), stream with tx | +| **Agent** | L2 checks + execute tx in embedded EVM sandbox, report gas used and state changes | +| **Contract** | Same as L1 | -The F1 cumulative reward-per-weight algorithm enables O(1) reward calculation regardless of agent count. As the system matures, RewardSettlement becomes the **single source of truth** for all reward distribution in the IoTeX protocol — eliminating the need for any centralized intermediary. +Agents are stateless. Coordinator provides per-tx state, but **incomplete state limits accuracy to ~14% on mainnet** — the primary motivation for L4. + +#### L4 — Per-Tx Stateful EVM Execution + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Export full EVM state snapshot at cold start; stream incremental state diffs per block (see [State Provisioning](#state-provisioning-l4)) | +| **Agent** | Maintain full EVM state locally (~300 MB–1.2 GB); execute txs with 100% accuracy; verify state hash chain integrity | +| **Contract** | Same as L1 | + +L4 is divided into two sub-phases: + +- **L4a (shadow mode):** Agent executes each tx against full local state. Results are compared against delegate execution to prove 100% accuracy. Agent results do not yet affect block production. +- **L4b (trusted execution cache):** Agent execution results are cached by the coordinator. When the delegate encounters a cached tx during block production, it skips re-execution and applies the agent's state diff directly (with precondition verification). Cache miss falls through to normal execution. + +#### L5 — Full Block Building (ePBS) + +| Component | Responsibility | +|-----------|---------------| +| **Coordinator** | Assign primary/standby builder roles; push full pending tx set + delegate-specified tx ordering; receive and evaluate candidate blocks | +| **Agent** | Build entire candidate block: execute txs in order, compute `deltaStateDigest`, `receiptRoot`, `logsBloom`; submit candidate to coordinator | +| **Contract** | Extended reward model: 70% primary builder / 20% participation pool / 10% best standby | + +Follows Ethereum's ePBS model ([EIP-7732](https://eips.ethereum.org/EIPS/eip-7732)) adapted for IoTeX's DPoS: + +| Ethereum ePBS | IoTeX ioSwarm | Role | +|--------------|---------------|------| +| Proposer | Delegate | Select best block, sign, broadcast | +| Builder | Agent | Order txs, execute, build candidate block | +| Relay | Coordinator | Route candidate blocks between agents and delegate | + +#### Summary: Components × Levels + +| | **Coordinator** | **Agent** | **On-chain Contract** | +|---|---|---|---| +| **L1** | Stream raw txs | Signature check | Epoch reward settlement | +| **L2** | + Prefetch account snapshots | + Nonce/balance check | Same | +| **L3** | + Prefetch contract state slots | + Stateless EVM execution | Same | +| **L4a** | + Export snapshot, stream diffs | + Full-state EVM (shadow) | Same | +| **L4b** | + Feed agent results to exec cache | + Full-state EVM (active) | Same | +| **L5** | + Assign builder roles, receive candidate blocks | + Build entire block | + Primary/standby reward split | --- ### Component 1: Delegate + Coordinator -The delegate runs iotex-core with the coordinator as an embedded sidecar module. It is responsible for consensus, state management, task dispatch, and — at higher levels — state provisioning to agents. +The delegate continues to run iotex-core and participate in consensus exactly as before. The coordinator is an embedded sidecar module that manages the agent swarm. This section covers the coordinator's two main responsibilities: communicating with agents and (at L4+) provisioning chain state. #### Coordinator-Agent Protocol The coordinator and agents communicate via gRPC with server-side streaming: -1. **Register**: Agent connects, provides capability level, region, and reward wallet address. Coordinator returns heartbeat interval. -2. **GetTasks** (server stream): Coordinator pushes `TaskBatch` messages containing pending transactions with pre-fetched state (L1–L3) or block context (L5). -3. **SubmitResults**: Agent returns validation results per task (valid/invalid, gas used, state changes, reject reason). -4. **Heartbeat**: Periodic keep-alive with payout notifications. Agents that miss 6 consecutive heartbeats are evicted. -5. **(L4+) StreamStateDiffs**: Server stream pushing incremental state changesets per block with chained state hashes. -6. **(L4+) DownloadSnapshot**: Agent requests full EVM state snapshot at cold start or after state divergence. -7. **(L5) SubmitCandidateBlock**: Agent submits a fully built candidate block for delegate verification. +| RPC | Direction | Level | Description | +|-----|-----------|-------|-------------| +| `Register` | Agent → Coordinator | All | Agent connects, provides capability level, region, reward wallet. Coordinator returns heartbeat interval. | +| `GetTasks` | Coordinator → Agent (stream) | L1–L4 | Coordinator pushes `TaskBatch` messages: pending txs with pre-fetched state (L1–L3) or block context (L4). | +| `SubmitResults` | Agent → Coordinator | L1–L4 | Agent returns validation results: valid/invalid, gas used, state changes, reject reason. | +| `Heartbeat` | Bidirectional | All | Periodic keep-alive (10s interval). Agents missing 6 consecutive heartbeats are evicted. Coordinator sends payout notifications. | +| `StreamStateDiffs` | Coordinator → Agent (stream) | L4+ | Incremental state changesets per block with chained state hashes. | +| `DownloadSnapshot` | Agent → Coordinator | L4+ | Agent requests full EVM state snapshot at cold start or after state divergence. | +| `SubmitCandidateBlock` | Agent → Coordinator | L5 | Agent submits a fully built candidate block for delegate verification. | -Authentication uses HMAC-SHA256: `api_key = "iosw_" + hex(HMAC-SHA256(masterSecret, agentID))`. +**Authentication**: HMAC-SHA256 — `api_key = "iosw_" + hex(HMAC-SHA256(masterSecret, agentID))`. #### State Provisioning (L4+) -At L1–L3, agents are stateless — the coordinator prefetches per-tx state snapshots and sends them with each task. At L4+, agents maintain full EVM state locally. The coordinator provisions this state via two mechanisms: +At L1–L3, agents are stateless — the coordinator prefetches per-tx state and sends it with each task. At L4+, agents maintain full EVM state locally. The coordinator provisions this state via two mechanisms: -**Cold Start — State Snapshot** +**1. Cold Start — State Snapshot** The coordinator exports a flat KV dump of the 3 EVM-relevant namespaces: @@ -169,9 +231,9 @@ snapshot = { } ``` -Total snapshot size: **~300 MB – 1.2 GB** (vs Ethereum's ~245 GiB). Trivially downloadable on a $5/mo VPS. +Total snapshot size: **~300 MB – 1.2 GB** (vs Ethereum's ~245 GiB). Downloadable in ~1 minute on a $5/mo VPS. -**Incremental Sync — State Diffs per Block** +**2. Incremental Sync — State Diffs per Block** Every block, the coordinator broadcasts the state changeset to all connected L4+ agents: @@ -185,13 +247,13 @@ state_diff = { } ``` -The changeset already exists in memory during `workingset.go`'s `Commit()` — captured from `flusher.SerializeQueue()` with zero additional computation. +The changeset already exists in memory during block commit — captured from iotex-core's `workingset.go` `flusher.SerializeQueue()` with zero additional computation. -**State Diff Reliability** +**3. State Diff Reliability** -State diff reliability is the **#1 engineering risk**. If an agent misses a single diff, every subsequent execution produces wrong results. +If an agent misses a single diff, every subsequent execution produces wrong results. This is the **#1 engineering risk** for L4+. -Every diff carries `prev_state_hash` and `post_state_hash` forming a chain — analogous to `prevBlockHash` in blocks. After applying each diff, the agent verifies: +Every diff carries `prev_state_hash` and `post_state_hash` forming a hash chain — analogous to `prevBlockHash` in blocks. After applying each diff, the agent verifies: ``` apply(diff) @@ -201,13 +263,20 @@ if local_hash != diff.post_state_hash: ``` Recovery (in priority order): -1. Request missing diff range from coordinator's rolling buffer (last ~100 blocks) -2. Incremental re-snapshot (only changed KV pairs since last known good height) -3. Full re-snapshot (last resort) +1. **Catch-up**: Request missing diffs from coordinator's rolling buffer (last ~100 blocks, ~16 min) +2. **Incremental re-snapshot**: Only changed KV pairs since agent's last known good height +3. **Full re-snapshot**: Last resort, re-download ~1 GB #### Key Design Advantage: deltaStateDigest -IoTeX's block header contains `deltaStateDigest` — a hash of the ordered state change queue, **not** a Merkle Trie root. This is a structural advantage over Ethereum: L4/L5 agents do not need to maintain a full Merkle Patricia Trie. A flat key-value store with ordered write tracking is sufficient to compute the correct state digest. This keeps agent state requirements at ~300 MB–1.2 GB (vs Ethereum's ~245 GiB), making block building feasible on commodity hardware. +IoTeX's block header contains `deltaStateDigest` — a hash of the **ordered state change queue**, not a Merkle Trie root. This is a structural advantage over Ethereum: + +- Agents do **not** need to maintain a Merkle Patricia Trie +- A flat KV store with ordered write tracking is sufficient to compute the correct digest +- State root computation is cheap — just hash the ordered write queue +- Agent state storage: ~300 MB–1.2 GB (vs Ethereum's ~245 GiB for full MPT) + +This makes full block building feasible on commodity hardware. #### Configuration Parameters @@ -223,92 +292,43 @@ IoTeX's block header contains `deltaStateDigest` — a hash of the ordered state --- -### Component 2: Agent Swarm — Five Capability Levels - -Agents are independent processes that connect to any delegate's coordinator, perform validation or block building work, and earn IOTX rewards. They progress through five levels of increasing capability. Each level defines what the **Coordinator**, **Agent**, and **On-chain Contract** must do. - -#### L1 — Per-Tx Signature Verification - -| Component | Responsibility | -|-----------|---------------| -| **Coordinator** | Pull pending txs from actpool, stream raw tx bytes to agents | -| **Agent** | Verify ECDSA signature (r, s components within secp256k1 curve order) | -| **Contract** | Epoch reward settlement via `depositAndSettle()` | - -Agents are stateless. No chain state required. +### Component 2: Agent Swarm -#### L2 — Per-Tx Nonce & Balance Validation - -| Component | Responsibility | -|-----------|---------------| -| **Coordinator** | Prefetch sender/receiver account snapshots (~200 bytes/tx), stream with tx | -| **Agent** | L1 checks + verify sender balance > 0, tx nonce >= account nonce | -| **Contract** | Same as L1 | +An agent is a single binary (`ioswarm-agent`) that connects to a coordinator, receives work, and earns IOTX. Agents are independent processes — they can run on any machine, in any geography, at any capability level. This section covers agent lifecycle and the economic dynamics of the agent market. -Agents are stateless. Coordinator provides per-tx state snapshots. +#### Agent Lifecycle -#### L3 — Per-Tx Stateless EVM Execution - -| Component | Responsibility | -|-----------|---------------| -| **Coordinator** | Prefetch contract state slots (~10 KB/tx), stream with tx | -| **Agent** | L1+L2 checks + execute tx in embedded EVM sandbox, report gas used / state changes | -| **Contract** | Same as L1 | - -Agents are stateless. Coordinator provides per-tx state, but incomplete state limits accuracy (~14% on mainnet). - -#### L4 — Per-Tx Stateful EVM Execution - -| Component | Responsibility | -|-----------|---------------| -| **Coordinator** | Export full EVM state snapshot at cold start; stream incremental state diffs per block | -| **Agent** | Maintain full EVM state locally (~300 MB–1.2 GB); execute txs with 100% accuracy; verify state hash chain integrity | -| **Contract** | Same as L1 | - -L4 is divided into two sub-phases: - -**L4a — Per-Tx Stateful Validation (shadow mode):** Agent executes each tx against full local state. Results are compared against delegate execution to prove 100% accuracy. Agent results do not yet affect block production. - -**L4b — Per-Tx Trusted Execution Cache:** Agent execution results are cached by the coordinator. When the delegate encounters a cached tx during block production, it skips re-execution and applies the agent's state diff directly (with precondition verification). Cache miss falls through to normal execution. - -#### L5 — Full Block Building (ePBS) - -| Component | Responsibility | -|-----------|---------------| -| **Coordinator** | Assign primary/standby builder roles; push full pending tx set + delegate-specified ordering; receive and evaluate candidate blocks | -| **Agent** | Build entire candidate block: select txs, execute in order, compute `deltaStateDigest` / `receiptRoot` / `logsBloom`; submit candidate to coordinator | -| **Contract** | Extended reward model: 70% primary builder / 20% participation pool / 10% best standby | - -Follows Ethereum's ePBS model ([EIP-7732](https://eips.ethereum.org/EIPS/eip-7732)) adapted for IoTeX's DPoS: delegate = proposer, agent = builder, coordinator = relay. - -#### Summary: Components × Levels +``` +1. REGISTER Agent connects to coordinator, declares level (L1–L5) and reward wallet + │ +2. RECEIVE Coordinator pushes tasks ──► Agent validates/executes/builds + │ +3. SUBMIT Agent returns results ──► Coordinator records contribution + │ +4. EARN Each epoch, coordinator settles rewards on-chain via RewardSettlement + │ +5. CLAIM Agent calls claim() on RewardSettlement ──► IOTX transferred to wallet +``` -| | **Coordinator** | **Agent** | **On-chain Contract** | -|---|---|---|---| -| **L1** | Stream raw txs | Signature check | Epoch reward settlement | -| **L2** | + Prefetch account snapshots | + Nonce/balance check | Same | -| **L3** | + Prefetch contract state slots | + Stateless EVM execution | Same | -| **L4a** | + Export snapshot, stream diffs | + Full-state EVM (shadow) | Same | -| **L4b** | + Feed agent results to exec cache | + Full-state EVM (active) | Same | -| **L5** | + Assign builder roles, receive candidate blocks | + Build entire block | + Primary/standby reward split | +Agents that miss 6 consecutive heartbeats (60s) are evicted. Reconnection is automatic — the agent re-registers and resumes work within seconds. #### Autonomous Agent Economics -Agents operate in an open market of 36 delegates, each offering different reward conditions. An intelligent agent continuously optimizes three dimensions: +ioSwarm agents operate in an open market of 36 delegates, each with its own coordinator, reward pool, agent count, and task volume. An intelligent agent continuously optimizes three dimensions: ##### 1. Delegate Selection (Where to Work) -Each delegate runs an independent coordinator with its own reward pool, agent count, and task volume. The effective reward rate per agent depends on all three: +The effective reward rate per agent depends on the delegate's reward pool and agent count: ``` effective_rate(delegate) = epoch_reward × (1 - delegate_cut) / num_agents ``` -An agent that monitors all 36 delegates can identify underserved delegates (few agents, high reward) and migrate. As agents migrate toward higher-paying delegates, the market self-balances. +An agent that monitors all 36 delegates can identify underserved delegates (few agents, high reward) and migrate. As agents migrate toward higher-paying delegates, the market self-balances toward equilibrium. -**Discovery mechanism**: Agents query on-chain delegate registry for active coordinators, then probe each coordinator's `/swarm/status` endpoint for current agent count and reward parameters. +**Discovery mechanism**: Agents query the on-chain delegate registry for active coordinators, then probe each coordinator's `/swarm/status` endpoint for current agent count and reward parameters. -**Migration cost**: Switching delegates at L1-L3 is free (stateless). At L4+, the agent must re-download a state snapshot (~1 min for 1 GB), making frequent migration more expensive. This natural friction prevents oscillation. +**Migration cost**: Switching delegates at L1–L3 is free (stateless). At L4+, the agent must re-download a state snapshot (~1 min for 1 GB), creating natural friction that prevents oscillation. ##### 2. Level Selection (How to Work) @@ -318,13 +338,13 @@ Each level requires different resources and earns different reward weight: |-------|-------------|---------|---------------|------------------| | L1 | ~0 | 0 | 1x | Any device | | L2 | ~0 | 0 | 1x | Any device | -| L3 | Low CPU | 0 | 2-3x | $5/mo VPS | -| L4 | Medium CPU | ~1 GB | 5-10x | $10/mo VPS | -| L5 | High CPU | ~1 GB | 10-20x | $10-20/mo VPS | +| L3 | Low CPU | 0 | 2–3x | $5/mo VPS | +| L4 | Medium CPU | ~1 GB | 5–10x | $10/mo VPS | +| L5 | High CPU | ~1 GB | 10–20x | $10–20/mo VPS | An agent evaluates: "At my hardware cost, which level maximizes `(reward_weight × effective_rate) - operating_cost`?" -A Raspberry Pi agent might optimally run L1-L2 for multiple delegates simultaneously, earning small amounts from each with near-zero cost. A dedicated VPS agent runs L4 for one delegate, earning more per task but with higher fixed costs. +A Raspberry Pi agent might optimally run L1–L2 for multiple delegates simultaneously, earning small amounts from each with near-zero cost. A dedicated VPS agent runs L4 for one delegate, earning more per task but with higher fixed costs. ##### 3. Claim Timing (When to Collect) @@ -343,9 +363,9 @@ Market conditions: Delegate C: 1.0 IOTX/epoch, 50 agents, delegate cut 5% Effective rate per agent per epoch: - A: 0.8 × 0.9 / 80 = 0.009 IOTX - B: 0.5 × 0.85 / 5 = 0.085 IOTX ← 9x better than A - C: 1.0 × 0.95 / 50 = 0.019 IOTX + A: 0.8 × 0.9 / 80 = 0.009 IOTX + B: 0.5 × 0.85 / 5 = 0.085 IOTX ← 9x better than A + C: 1.0 × 0.95 / 50 = 0.019 IOTX A "dumb" agent randomly picks A: 0.009 IOTX/epoch An intelligent agent picks B: 0.085 IOTX/epoch @@ -353,34 +373,31 @@ An intelligent agent picks B: 0.085 IOTX/epoch 9.4x difference ``` -This reward differential is what drives agents toward intelligent behavior. The protocol does not mandate any specific strategy — it provides the economic environment, and agents evolve their own optimization approaches: rule-based heuristics, multi-armed bandit algorithms, or more sophisticated learned policies. +This reward differential is what drives agents toward intelligent behavior. The protocol does not mandate any specific strategy — it provides the economic environment, and agents evolve their own optimization approaches. ##### Market Dynamics As agents optimize, the system reaches a competitive equilibrium: 1. **Reward equalization**: Agents migrate toward high-rate delegates → rates equalize across delegates -2. **Level efficiency**: Agents select the level where their marginal revenue exceeds marginal cost → each level finds its natural agent population +2. **Level efficiency**: Agents select the level where marginal revenue exceeds marginal cost → each level finds its natural population 3. **Quality pressure**: Delegates can adjust reward weights to favor higher-level agents → agents invest in capability upgrades -This is a genuine multi-agent market, not a static assignment. The "intelligence" of agents is measured by their economic performance — return on invested compute — which is observable, quantifiable, and improvable over time. +This is a genuine multi-agent market, not a static assignment. Agent "intelligence" is measured by economic performance — return on invested compute — which is observable, quantifiable, and improvable over time. --- ### Component 3: RewardSettlement (On-Chain) -RewardSettlement is the on-chain contract that handles all reward distribution between coordinators and agents. It replaces the need for any centralized intermediary (such as Hermes) by providing trustless, self-service reward claiming. +RewardSettlement is a smart contract that handles all reward distribution between coordinators and agents. It replaces the need for any centralized intermediary (such as IoTeX's existing Hermes service) by providing trustless, self-service reward claiming. #### Reward Flow ``` -Epoch timer fires (every 30s) +Epoch timer fires (every ~30s) │ ▼ -Coordinator tallies tasks per agent - │ - ▼ -Coordinator calculates weights: weight = tasks × 1000 (+ accuracy bonus) +Coordinator tallies tasks per agent and calculates weights │ ▼ Coordinator deducts delegate cut (default 10%) @@ -389,10 +406,7 @@ Coordinator deducts delegate cut (default 10%) Coordinator calls depositAndSettle(agents[], weights[]) + sends IOTX │ ▼ -RewardSettlement contract updates cumulativeRewardPerWeight - │ - ▼ -Agent receives payout notification via heartbeat +RewardSettlement updates cumulativeRewardPerWeight │ ▼ Agent calls claim() at any time → IOTX transferred to wallet @@ -418,7 +432,7 @@ contract RewardSettlement { #### F1 Distribution Algorithm -The contract implements the **F1 fee distribution** algorithm, originally described in the [Cosmos SDK F1 Fee Distribution paper](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) and used by Cosmos SDK for staking reward distribution. It tracks a global `cumulativeRewardPerWeight` that increases with each deposit: +The contract implements the **F1 fee distribution** algorithm from the [Cosmos SDK](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf). It tracks a global `cumulativeRewardPerWeight` that increases with each deposit: ``` On depositAndSettle: @@ -430,6 +444,49 @@ On claim: This enables **O(1) reward calculation** regardless of agent count — no iteration over all agents needed. Adding agents, updating weights, and claiming all take constant gas. +--- + +### Evolution Roadmap + +This IIP specifies the current ioSwarm architecture. Below we outline how each component evolves as the system matures. + +#### Delegate + Coordinator → Thin Proposer + +As agents take on more work, the delegate's role thins progressively: + +| Phase | Delegate Responsibility | What Moves to Agents | +|-------|------------------------|---------------------| +| **Now** | Full node: consensus + execution + state | — | +| **L1–L3** | Full node + coordinator sidecar | Tx validation | +| **L4** | Consensus + state provider | Stateful EVM execution | +| **L5 (ePBS)** | Consensus + block signing only | Entire block building | +| **Future** | Proposer-only (thin client) | Everything except signing | + +At the end state, a delegate becomes a **thin proposer** — similar to Lido's model for liquid staking. Token holders stake into a protocol-managed pool, and the delegate's only job is to sign blocks produced by the agent swarm. The coordinator evolves from an iotex-core sidecar into a lightweight relay connecting proposers to builders, comparable to Ethereum's MEV-Boost relay. + +#### Agent Swarm → Block Builders + +Agents evolve from stateless tx validators into full block builders: + +- **L1–L3 (stateless)**: Commodity $5/mo VPS, no local state, pure computation. Many agents can serve many delegates simultaneously. +- **L4 (stateful)**: Agents maintain synchronized state via state diffs. Can independently verify execution correctness. +- **L5 (block builder)**: Agents construct complete candidate blocks — ordering transactions, computing state transitions, and producing `deltaStateDigest`. The best block wins. + +As agents reach L5, the swarm becomes a **competitive block-building market** where agents differentiate on block quality, MEV extraction, and latency. + +#### RewardSettlement → Universal Reward Layer + +Today, IoTeX uses **Hermes** — a centralized service — to distribute delegate-to-voter rewards off-protocol. RewardSettlement is designed to replace Hermes and handle all reward flows on-chain: + +| Reward Flow | Today (Hermes) | Future (RewardSettlement) | +|------------|----------------|--------------------------| +| Protocol → Delegate | Native staking reward | Same | +| Delegate → Voters | Hermes (centralized) | `RewardSettlement.claim()` | +| Delegate → Agent Swarm | ioSwarm (this IIP) | `RewardSettlement.claim()` | +| Protocol → Agent (direct) | Not yet | Future: protocol-native agent rewards | + +As the system matures, RewardSettlement becomes the **single source of truth** for all reward distribution in the IoTeX protocol — eliminating the need for any centralized intermediary. + ## Rationale ### Why Start at the Execution Layer @@ -441,6 +498,14 @@ ioSwarm deliberately avoids consensus-layer changes. From the protocol's perspec - **Zero risk to chain safety** — worst case, disable ioSwarm and the delegate returns to baseline - **Proven path** — once the execution layer proves value, protocol-layer integration follows naturally +### Why Five Capability Levels + +The five-level model serves two purposes: + +**Low barrier to entry**: L1 agents only need to verify signatures — any device can participate and earn rewards. Each subsequent level adds capability and earning potential without making previous levels obsolete. + +**Progressive trust**: The delegate never needs to trust agents all at once. L1–L3 run in shadow mode (advisory only). L4a proves accuracy via shadow comparison. L4b introduces trusted execution with precondition verification as a safety net. L5 delegates block building but retains re-execution verification. Each step is independently reversible. + ### Why F1 Reward Distribution The [F1 algorithm](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) (used by Cosmos SDK for staking rewards) was chosen because: @@ -469,19 +534,11 @@ This creates measurable selection pressure: an agent that makes better economic The protocol's role is to provide: 1. **Transparent information**: reward rates, agent counts, and task volumes are queryable on-chain and via coordinator APIs -2. **Low switching cost**: agents can migrate between delegates without penalty (at L1-L3, instantly; at L4+, with a brief re-sync) +2. **Low switching cost**: agents can migrate between delegates without penalty (at L1–L3, instantly; at L4+, with a brief re-sync) 3. **Fair reward distribution**: F1 algorithm ensures proportional payouts with no information asymmetry The agents' role is to exploit this information to maximize their return. The result is a self-organizing market that efficiently allocates compute to where it's most needed. -### Why Five Capability Levels - -The five-level model serves two purposes: - -**Low barrier to entry**: L1 agents only need to verify signatures — any device can participate and earn rewards. Each subsequent level adds capability and earning potential without making previous levels obsolete. - -**Progressive trust**: The delegate never needs to trust agents all at once. L1–L3 run in shadow mode (advisory only). L4a proves accuracy via shadow comparison. L4b introduces trusted execution with precondition verification as a safety net. L5 delegates block building but retains re-execution verification. Each step is independently reversible. - ## Implementation ### Repositories @@ -538,7 +595,7 @@ ioswarm-agent \ ## Test Results -ioSwarm (L1–L3) has been tested end-to-end on IoTeX mainnet with the reward pool contract deployed at `0x96F475F87911615dD710f9cB425Af8ed0e167C89`. +ioSwarm (L1–L3) has been tested end-to-end on IoTeX mainnet with the RewardSettlement contract deployed at `0x96F475F87911615dD710f9cB425Af8ed0e167C89`. ### Coverage @@ -583,30 +640,30 @@ ioSwarm (L1–L3) has been tested end-to-end on IoTeX mainnet with the reward po | Threat | Impact | Mitigation | |--------|--------|------------| -| False positive (says invalid tx is valid) | Invalid tx reaches block builder | Delegate re-executes all txs in L1–L4a | +| False positive (says invalid tx is valid) | Invalid tx reaches block builder | Delegate re-executes all txs at L1–L4a | | False negative (says valid tx is invalid) | Valid tx delayed | Cross-validation with multiple agents | | Denial of service (no response) | Task timeout | 2s timeout + automatic failover to other agents | | Transaction front-running | MEV extraction | Mempool is already public via P2P; agents see same data | | Fabricated state diffs (L4b) | Incorrect state applied | Precondition verification before applying cached results | -| Invalid candidate block (L5) | Block production delay | Delegate re-executes to verify; standby builder takes over on mismatch | +| Invalid candidate block (L5) | Block production delay | Delegate re-executes to verify; standby builder takes over | ### Trust Model -The trust model evolves with each level: +The trust model evolves with each capability level: | Level | Trust Model | Safety Guarantee | |-------|------------|-----------------| | L1–L3 | **Zero-trust** — agent results are advisory only | Delegate executes all txs independently | | L4a | **Shadow verification** — agent results compared, not used | Delegate executes all txs independently | | L4b | **Trust-but-verify** — cached results used with precondition check | Mismatch → fall through to delegate execution | -| L5 | **Verified delegation** — agent builds block, delegate re-executes winner | Mismatch → reject, penalize agent, use standby | +| L5 | **Verified delegation** — agent builds block, delegate re-executes | Mismatch → reject, penalize agent, use standby | | Future | **Optimistic** — delegate trusts agent block, fraud detected post-hoc | Slashing as economic deterrent | At every level, disabling ioSwarm returns the delegate to baseline operation with zero impact on block production. ### Known Limitations -1. **F1 departed agent issue**: When an agent departs, its on-chain weight is not zeroed automatically. The coordinator should zero departed agents' weights within 1-2 epochs. +1. **F1 departed agent issue**: When an agent departs, its on-chain weight is not zeroed automatically. The coordinator should zero departed agents' weights within 1–2 epochs. 2. **Single coordinator**: The coordinator is a single process within the delegate. If it crashes, agents cannot receive tasks until it restarts. The delegate continues producing blocks normally via iotex-core's standard execution path. From 90f3cce7d9227923ea0ce8ee0827d16878272dc3 Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:29:28 -0700 Subject: [PATCH 06/19] feat: add Execution Layer Separation framing to Motivation Position ioSwarm as execution layer separation (analogous to Ethereum's ePBS) at the top of Motivation, before The Problem. Includes comparison table showing how ioSwarm differs from Ethereum's builder market: decentralized agents vs centralized builders, low vs high barrier. Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/iip-58.md b/iip-58.md index cc08137..b7f2124 100644 --- a/iip-58.md +++ b/iip-58.md @@ -15,11 +15,35 @@ ioSwarm transforms IoTeX from a chain run by 36 delegates on 36 machines into a ## Motivation +### Execution Layer Separation + +Every blockchain has two layers of concern: + +``` +Consensus Layer decide WHICH block is canonical (voting, attestation, fork choice) +Execution Layer decide WHAT goes into the block (tx validation, EVM execution, state) +``` + +In most chains — including IoTeX today — both layers run on the same machine, operated by the same entity. Ethereum recognized the value of separating them: ePBS ([EIP-7732](https://eips.ethereum.org/EIPS/eip-7732)) splits the **Proposer** (consensus) from the **Builder** (execution), allowing specialized builders to construct blocks while validators focus on consensus. + +ioSwarm applies the same principle to IoTeX, but goes further: + +| | Ethereum ePBS | IoTeX ioSwarm | +|---|---|---| +| **Consensus** | Validators (~900K) | Delegates (36) | +| **Execution** | Builders (3–5 dominant, centralized) | Agent Swarm (thousands, permissionless) | +| **Relay** | MEV-Boost relay | Coordinator (embedded in delegate) | +| **Participation** | High barrier (specialized hardware, MEV expertise) | Low barrier ($5/mo VPS, anyone can join) | + +Ethereum's builder market is dominated by a handful of sophisticated MEV searchers. ioSwarm's execution layer is **open and decentralized** — thousands of commodity agents, each earning proportional to their work, with no special hardware or MEV expertise required to participate. + +**In one sentence: ioSwarm separates the execution layer from IoTeX's delegates and distributes it across a permissionless swarm of AI agents.** + ### The Problem IoTeX runs on 36 delegate nodes. Each delegate is a single machine, operated by a single entity. This is the reality of most DPoS chains: decentralization in name, but a small club of operators in practice. -ioSwarm addresses two fundamental limitations: +ioSwarm addresses two fundamental limitations of this architecture: **1. Scale.** One delegate backed by 1,000 agents is fundamentally more robust than one delegate on one machine. Scale that across 36 delegates and you have a network of 36,000+ execution nodes — without changing a single line of consensus code. From 25300617473dea129ffa7a591c762db2e7fb5f0a Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:32:03 -0700 Subject: [PATCH 07/19] refactor: rename framing from Execution Layer Separation to Consensus-Execution Separation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify that ioSwarm is NOT just PBS — it separates consensus from execution at a more fundamental level. PBS (proposer/builder) is a special case that emerges at L5. Add comparison table showing the progression: Ethereum Merge → ePBS → ioSwarm. Update title to 'Decentralized Execution Layer via AI Agent Swarm'. Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/iip-58.md b/iip-58.md index b7f2124..2958aa1 100644 --- a/iip-58.md +++ b/iip-58.md @@ -1,6 +1,6 @@ ``` IIP: 58 -Title: ioSwarm — AI Agent Network for Chain Execution +Title: ioSwarm — Decentralized Execution Layer via AI Agent Swarm Author: Raullen Chai (@raullen) Discussions-to: TBD Status: Draft @@ -15,7 +15,7 @@ ioSwarm transforms IoTeX from a chain run by 36 delegates on 36 machines into a ## Motivation -### Execution Layer Separation +### Consensus-Execution Separation Every blockchain has two layers of concern: @@ -24,9 +24,15 @@ Consensus Layer decide WHICH block is canonical (voting, attestation, fork ch Execution Layer decide WHAT goes into the block (tx validation, EVM execution, state) ``` -In most chains — including IoTeX today — both layers run on the same machine, operated by the same entity. Ethereum recognized the value of separating them: ePBS ([EIP-7732](https://eips.ethereum.org/EIPS/eip-7732)) splits the **Proposer** (consensus) from the **Builder** (execution), allowing specialized builders to construct blocks while validators focus on consensus. +In most chains — including IoTeX today — both layers run on the same machine, operated by the same entity. Separating them has been a recurring theme in blockchain architecture: -ioSwarm applies the same principle to IoTeX, but goes further: +| Milestone | What It Separates | How | +|-----------|------------------|-----| +| **Ethereum's Merge** | Consensus client from execution client | Two separate programs, but still on the **same operator's machine** | +| **Ethereum's ePBS** ([EIP-7732](https://eips.ethereum.org/EIPS/eip-7732)) | Proposer from Builder (within block production) | Specialized builders construct blocks; validators just sign. But builders are **few and centralized** (3–5 dominant firms) | +| **ioSwarm** | Consensus layer from execution layer | Execution moves to a **permissionless network** of thousands of independent agents | + +ioSwarm takes this separation further than either: the execution layer is not a different process on the same machine (Merge), nor a handful of specialized firms (ePBS). It is an **open, decentralized network** of commodity agents — anyone with a $5/mo VPS can join, perform execution work, and earn rewards. | | Ethereum ePBS | IoTeX ioSwarm | |---|---|---| @@ -35,9 +41,9 @@ ioSwarm applies the same principle to IoTeX, but goes further: | **Relay** | MEV-Boost relay | Coordinator (embedded in delegate) | | **Participation** | High barrier (specialized hardware, MEV expertise) | Low barrier ($5/mo VPS, anyone can join) | -Ethereum's builder market is dominated by a handful of sophisticated MEV searchers. ioSwarm's execution layer is **open and decentralized** — thousands of commodity agents, each earning proportional to their work, with no special hardware or MEV expertise required to participate. +At L5 (full block building), ioSwarm's architecture *includes* ePBS as a special case — the delegate becomes the proposer, the agent becomes the builder. But the broader design encompasses L1–L4, where agents perform execution work without building blocks at all. ePBS is the endgame; consensus-execution separation is the framework. -**In one sentence: ioSwarm separates the execution layer from IoTeX's delegates and distributes it across a permissionless swarm of AI agents.** +**In one sentence: ioSwarm separates the execution layer from IoTeX's consensus delegates and distributes it across a permissionless swarm of AI agents.** ### The Problem From 861a57483867293b5dfd5b566d1e08b38c5767f7 Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:33:44 -0700 Subject: [PATCH 08/19] feat: add Ethereum Merge EIP references for consensus-execution separation Reference the key Ethereum EIPs that achieved consensus-execution separation at the process level (EIP-3675, Engine API, EIP-4399), providing historical context for ioSwarm's network-level separation. Reorganize References section into three categories: - Consensus-Execution Separation (Merge) - Proposer-Builder Separation (ePBS) - Reward Distribution (F1) Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/iip-58.md b/iip-58.md index 2958aa1..1ae6a26 100644 --- a/iip-58.md +++ b/iip-58.md @@ -26,13 +26,13 @@ Execution Layer decide WHAT goes into the block (tx validation, EVM execution In most chains — including IoTeX today — both layers run on the same machine, operated by the same entity. Separating them has been a recurring theme in blockchain architecture: -| Milestone | What It Separates | How | -|-----------|------------------|-----| -| **Ethereum's Merge** | Consensus client from execution client | Two separate programs, but still on the **same operator's machine** | -| **Ethereum's ePBS** ([EIP-7732](https://eips.ethereum.org/EIPS/eip-7732)) | Proposer from Builder (within block production) | Specialized builders construct blocks; validators just sign. But builders are **few and centralized** (3–5 dominant firms) | -| **ioSwarm** | Consensus layer from execution layer | Execution moves to a **permissionless network** of thousands of independent agents | +| Milestone | What It Separates | How | Key EIPs | +|-----------|------------------|-----|----------| +| **Ethereum's Merge (2022)** | Consensus client from execution client | Two separate programs communicating via Engine API, but still on the **same operator's machine** | [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675) (PoS transition), [Engine API](https://github.com/ethereum/execution-apis) (consensus↔execution interface), [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399) (PREVRANDAO) | +| **Ethereum's ePBS** | Proposer from Builder (within block production) | Specialized builders construct blocks; validators just sign. But builders are **few and centralized** (3–5 dominant firms) | [EIP-7732](https://eips.ethereum.org/EIPS/eip-7732) (ePBS), [EIP-7898](https://eips.ethereum.org/EIPS/eip-7898) (uncouple execution payload) | +| **ioSwarm** | Consensus layer from execution layer | Execution moves to a **permissionless network** of thousands of independent agents | This IIP | -ioSwarm takes this separation further than either: the execution layer is not a different process on the same machine (Merge), nor a handful of specialized firms (ePBS). It is an **open, decentralized network** of commodity agents — anyone with a $5/mo VPS can join, perform execution work, and earn rewards. +Ethereum's Merge took years and dozens of EIPs to achieve consensus-execution separation at the *process* level — splitting one monolithic Geth client into a Beacon Chain consensus client (Prysm, Lighthouse, etc.) and an execution client (Geth, Reth, etc.) connected via the Engine API. ioSwarm takes the next step: separating them at the *network* level. The execution layer is not just a different process on the same machine, but an **open, decentralized network** of commodity agents — anyone with a $5/mo VPS can join, perform execution work, and earn rewards. | | Ethereum ePBS | IoTeX ioSwarm | |---|---|---| @@ -701,10 +701,20 @@ At every level, disabling ioSwarm returns the delegate to baseline operation wit ## References +### Ethereum Consensus-Execution Separation +- [EIP-3675: Upgrade consensus to Proof-of-Stake](https://eips.ethereum.org/EIPS/eip-3675) — The Merge: formal transition from PoW to Beacon Chain consensus +- [Engine API](https://github.com/ethereum/execution-apis) — authenticated JSON-RPC interface connecting consensus clients to execution clients +- [EIP-4399: Supplant DIFFICULTY opcode with PREVRANDAO](https://eips.ethereum.org/EIPS/eip-4399) — execution-layer adaptation for PoS randomness +- [Ethereum Merge Overview](https://ethereum.org/roadmap/merge/) + +### Proposer-Builder Separation - [EIP-7732: Enshrined Proposer-Builder Separation](https://eips.ethereum.org/EIPS/eip-7732) -- [F1 Fee Distribution (Ojha & Goes, Tokenomics 2019)](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) — used by Cosmos SDK for staking reward distribution -- [Ethereum PBS Roadmap](https://ethereum.org/roadmap/pbs) +- [EIP-7898: Uncouple execution payload from beacon block](https://eips.ethereum.org/EIPS/eip-7898) - [EIP-7805: FOCIL (Fork-Choice Enforced Inclusion Lists)](https://eips.ethereum.org/EIPS/eip-7805) +- [Ethereum PBS Roadmap](https://ethereum.org/roadmap/pbs) + +### Reward Distribution +- [F1 Fee Distribution (Ojha & Goes, Tokenomics 2019)](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) — used by Cosmos SDK for staking reward distribution ## Copyright From 917ae41a01d05cbe865ff81501b41a46563dd706 Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:37:31 -0700 Subject: [PATCH 09/19] =?UTF-8?q?fix:=20consistency=20pass=20=E2=80=94=20L?= =?UTF-8?q?4=20summary=20description=20and=20anchor=20link?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix L4 summary table: "L2 + execute tx" → "Full EVM execution against local state" (L4 subsumes L3, not just L2) - Fix deltaStateDigest anchor link to lowercase (GitHub auto-lowercases) Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/iip-58.md b/iip-58.md index 1ae6a26..fab0aea 100644 --- a/iip-58.md +++ b/iip-58.md @@ -74,7 +74,7 @@ This optimization pressure is what drives agents toward genuine autonomous intel | **Capability Level (L1–L5)** | A classification of agent capability, from L1 (signature verification only) to L5 (full block building). Higher levels require more resources but earn higher rewards. See [Capability Levels](#capability-levels-l1l5). | | **Epoch** | A fixed interval (configurable, default 3 blocks / ~30s) after which the coordinator tallies agent work and settles rewards on-chain. | | **RewardSettlement** | An on-chain smart contract that holds deposited rewards and allows agents to claim their share. Uses the F1 algorithm for O(1) proportional distribution. | -| **deltaStateDigest** | IoTeX's block header field containing a hash of the ordered state change queue (not a Merkle Trie root). This is a key structural advantage — see [deltaStateDigest](#key-design-advantage-deltastateDigest). | +| **deltaStateDigest** | IoTeX's block header field containing a hash of the ordered state change queue (not a Merkle Trie root). This is a key structural advantage — see [deltaStateDigest](#key-design-advantage-deltastatedigest). | | **State Diff** | An ordered list of state changes produced by executing a block. At L4+, the coordinator streams these to agents so they can maintain synchronized local state. | | **Shadow Mode** | A validation mode where agent results are compared against the delegate's own execution but not used for block production. Used to prove agent accuracy before trusting agent results. | @@ -132,7 +132,7 @@ ioSwarm defines five capability levels that classify what an agent can do. Each | **L1** | Signature Verification | None | Verify ECDSA signatures | Zero-trust (shadow) | | **L2** | Nonce & Balance Check | None | L1 + verify sender nonce and balance | Zero-trust (shadow) | | **L3** | Stateless EVM Execution | None | L2 + execute tx in EVM sandbox with coordinator-provided state | Zero-trust (shadow) | -| **L4** | Stateful EVM Execution | Full EVM state (~1 GB) | L2 + execute tx against full local state with 100% accuracy | Shadow → trust-but-verify | +| **L4** | Stateful EVM Execution | Full EVM state (~1 GB) | Full EVM execution against local state with 100% accuracy | Shadow → trust-but-verify | | **L5** | Full Block Building | Full EVM state (~1 GB) | Build entire candidate block: order txs, execute, compute block header fields | Verified delegation | Key transitions: From de2bd355f971457274d7e5361f8cf0a86764a98f Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:45:42 -0700 Subject: [PATCH 10/19] feat: address MEV centralization and AI buzzword concerns Two new sections responding to reviewer feedback: 1. MEV and the Case for Decentralized Block Building (Evolution Roadmap) - Acknowledge Ethereum's builder centralization honestly - Phase 1: delegate-controlled ordering eliminates MEV - Phase 2: argue distributed exploration > centralized optimization for complex/adversarial MEV regimes - Reward structure (70/20/10) prevents winner-take-all 2. Enhanced Why Autonomous Agent Economics (Rationale) - Acknowledge L1-L3 optimization is basic arithmetic - Show intelligence complexity growing with levels (table) - L5+MEV is genuinely hard: multi-agent adversarial optimization - Position: protocol measures intelligence by economic performance, market drives sophistication over time Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 45 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 9 deletions(-) diff --git a/iip-58.md b/iip-58.md index fab0aea..6a09c5b 100644 --- a/iip-58.md +++ b/iip-58.md @@ -517,6 +517,29 @@ Today, IoTeX uses **Hermes** — a centralized service — to distribute delegat As the system matures, RewardSettlement becomes the **single source of truth** for all reward distribution in the IoTeX protocol — eliminating the need for any centralized intermediary. +#### MEV and the Case for Decentralized Block Building + +A common objection to decentralized block building is that MEV (Maximal Extractable Value) inevitably centralizes builders. Ethereum's experience supports this: 3–5 specialized builders dominate >90% of blocks because MEV extraction rewards the best algorithms, lowest latency, and most capital. Why would IoTeX be different? + +**Short answer: IoTeX today has minimal MEV, and ioSwarm is designed to keep it that way in Phase 1.** The delegate specifies transaction ordering via an inclusion list — agents execute in that order without reordering. This eliminates front-running, sandwich attacks, and the MEV extraction that drives centralization in Ethereum's builder market. + +**Longer answer: when MEV does emerge, a decentralized swarm has structural advantages over a centralized builder oligopoly.** + +In traditional MEV markets, the "best algorithm" is a fixed target — whoever invests the most in low-latency infrastructure and quant teams wins permanently. But as MEV strategies become more complex and adversarial, the search space grows combinatorially. This is precisely the regime where **distributed exploration outperforms centralized optimization**: + +| MEV Regime | Centralized Builders (Ethereum) | Decentralized Swarm (ioSwarm) | +|-----------|-------------------------------|------------------------------| +| **Simple arbitrage** (DEX price gaps) | Winner-take-all: fastest bot wins | Same — no advantage from decentralization | +| **Complex MEV** (cross-protocol, multi-block) | Diminishing returns: one team's search is bounded | Thousands of agents exploring different strategies in parallel | +| **Adversarial MEV** (strategy vs. counter-strategy) | Arms race between few players, high barrier | Evolutionary pressure across a large population — more diverse strategies survive | +| **Novel MEV** (new DeFi protocols, new patterns) | Slow to adapt: specialized teams have institutional inertia | Fast adaptation: any agent can try a new approach, market rewards success instantly | + +The key insight: in a large, diverse agent population, the **aggregate intelligence** of thousands of independent strategies can exceed the intelligence of any single team. This is the same principle that makes markets more efficient than central planning — and it applies to MEV extraction just as it applies to price discovery. + +ioSwarm's Phase 1 (no agent reordering) buys time for the agent ecosystem to mature. When Phase 2 introduces controlled reordering, the competitive landscape will be shaped by thousands of agents with diverse strategies, not a handful of incumbents. The protocol's reward structure (70% primary / 20% participation / 10% standby) further ensures that even non-winning agents earn rewards for participation, preventing the pure winner-take-all dynamic that centralizes Ethereum's builder market. + +**This is not a solved problem.** MEV centralization is an active area of research across the industry. ioSwarm's contribution is structural: a permissionless, low-barrier agent network provides more fertile ground for decentralized MEV solutions than a high-barrier, capital-intensive builder market. + ## Rationale ### Why Start at the Execution Layer @@ -551,23 +574,27 @@ Alternatives considered: ### Why Autonomous Agent Economics -The "AI" in ioSwarm is not about bolting a language model onto a validator. It is about creating an economic environment where **intelligent behavior is rewarded**. +The "AI" in ioSwarm is not about bolting a language model onto a validator. It is about creating an economic environment where **intelligent behavior is rewarded** — and where the complexity of that intelligence grows with the system. + +A fair objection: the delegate selection formula (`epoch_reward × (1 - delegate_cut) / num_agents`) is basic arithmetic, not artificial intelligence. At L1–L3, this is true — an agent optimizing across 36 delegates is closer to a routing script than an AI system. -Traditional blockchain nodes are statically configured — connect to one network, execute whatever arrives, collect whatever is paid. There is no decision-making, no optimization, no reason for the node to be "smart." ioSwarm changes this by introducing a **multi-dimensional optimization problem** that agents must solve: +But this is the **starting point**, not the ceiling. Agent intelligence deepens as the system evolves: -- 36 delegates with varying reward rates (changes per epoch) -- 5 capability levels with different cost/reward profiles -- Variable gas costs affecting claim timing -- Hardware constraints affecting which levels are profitable +| Phase | Decision Complexity | Intelligence Required | +|-------|--------------------|-----------------------| +| **L1–L3 (today)** | Which delegate? Which level? When to claim? | Rule-based heuristics — a static script can do this | +| **L4 (stateful)** | Above + state sync strategy, catch-up vs re-snapshot tradeoffs, multi-delegate state management | Adaptive optimization — agents must respond to changing network conditions | +| **L5 (block building)** | Above + transaction ordering, gas optimization, block composition strategy | Competitive strategy — agents compete directly on block quality | +| **L5 + MEV** | Above + MEV extraction, cross-protocol arbitrage, adversarial strategy | Emergent intelligence — the search space is combinatorial; no closed-form solution exists | -This creates measurable selection pressure: an agent that makes better economic decisions earns more IOTX per dollar of compute. Over time, this pressure drives the agent ecosystem toward increasingly sophisticated optimization — from simple heuristics to learned policies — without the protocol prescribing any specific approach. +At L5 with MEV, the optimization problem becomes genuinely hard: the agent must decide which transactions to include, in what order, whether to insert its own transactions, how to balance MEV extraction against the risk of block rejection, and how to adapt its strategy as competitors counter it. This is a **multi-agent adversarial optimization problem** — the kind of problem where reinforcement learning, game-theoretic reasoning, and learned policies demonstrably outperform hand-coded heuristics. -The protocol's role is to provide: +The protocol does not prescribe any specific approach. It provides the economic environment: 1. **Transparent information**: reward rates, agent counts, and task volumes are queryable on-chain and via coordinator APIs 2. **Low switching cost**: agents can migrate between delegates without penalty (at L1–L3, instantly; at L4+, with a brief re-sync) 3. **Fair reward distribution**: F1 algorithm ensures proportional payouts with no information asymmetry -The agents' role is to exploit this information to maximize their return. The result is a self-organizing market that efficiently allocates compute to where it's most needed. +The agents' role is to exploit this information to maximize their return. A "dumb" agent uses static rules. A "smart" agent learns and adapts. The protocol doesn't care which — it measures intelligence by economic performance, and the market rewards the better agent. Over time, the competitive pressure drives the agent ecosystem toward increasingly sophisticated strategies — from scripts to learned policies to genuine autonomous economic reasoning. ## Implementation From cb79c7d005e45e901f24173982416450a8eaeb7c Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 16:49:44 -0700 Subject: [PATCH 11/19] feat: address Sybil resistance and shadow mode economics concerns Add two new Security Considerations sections responding to reviewer feedback: API key auth for Sybil resistance, and shadow mode as a paid proving ground (not wasted computation). Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/iip-58.md b/iip-58.md index 6a09c5b..7d4c8d1 100644 --- a/iip-58.md +++ b/iip-58.md @@ -703,6 +703,23 @@ ioSwarm (L1–L3) has been tested end-to-end on IoTeX mainnet with the RewardSet | Transaction front-running | MEV extraction | Mempool is already public via P2P; agents see same data | | Fabricated state diffs (L4b) | Incorrect state applied | Precondition verification before applying cached results | | Invalid candidate block (L5) | Block production delay | Delegate re-executes to verify; standby builder takes over | +| Sybil attack (many fake identities) | Occupy `maxAgents` slots, crowd out honest agents | API key authentication + delegate-controlled admission (see below) | + +### Sybil Resistance and Agent Admission + +ioSwarm is **not a public permissionless protocol** — it is a set of private services operated by each delegate independently. Each delegate's coordinator controls its own agent admission: + +- **API key authentication**: Agents authenticate via HMAC-SHA256 API keys. The delegate generates and distributes keys to agents it trusts. An attacker cannot register without a valid key. +- **Delegate autonomy**: Each delegate decides its own admission policy — open registration, invite-only, staking requirement, KYC, or any combination. The protocol does not mandate a single approach. +- **Rate limiting**: The coordinator enforces per-agent rate limits (10 req/s, burst 20) and evicts agents that exceed them. +- **`maxAgents` as defense**: The `maxAgents` cap (default 100) bounds the coordinator's resource exposure. Combined with API key auth, an attacker must compromise 100 keys to fill all slots. + +This is analogous to how Ethereum validators choose which MEV-Boost relays to trust, or how mining pools choose which miners to admit. The trust relationship is between the delegate and its agents, not between the protocol and agents. Each delegate bears the cost of its own swarm and has full economic incentive to prevent abuse. + +For delegates that want open registration (no API key), additional defenses are available: +- **Minimum stake**: Require agents to deposit a small IOTX bond (refundable on graceful exit, slashed on misbehavior) +- **Proof of work**: Require a computational puzzle at registration to raise Sybil cost +- **Reputation scoring**: Weight rewards by historical accuracy, naturally penalizing new/untrusted agents ### Trust Model @@ -718,6 +735,31 @@ The trust model evolves with each capability level: At every level, disabling ioSwarm returns the delegate to baseline operation with zero impact on block production. +### Shadow Mode Economics + +A valid concern: at L1–L4a, agents perform redundant computation — the delegate re-executes all transactions independently regardless of agent results. Why pay agents for work the delegate discards? + +**Shadow mode is not wasted computation. It is a paid proving ground.** + +The cost of shadow mode is low and deliberate: + +| | Shadow Mode (L1–L4a) | Active Mode (L4b–L5) | +|---|---|---| +| **Agent cost** | $5–10/mo VPS | Same | +| **Delegate cost** | Epoch rewards (~0.5 IOTX/30s) | Same, but delegate CPU drops | +| **What delegate gains** | Accuracy data: does this agent match my execution 100%? | Actual CPU offload, block building | +| **What agent gains** | Reputation + rewards | Higher rewards | + +The delegate pays a small amount to answer a critical question: **can I trust this agent?** Without shadow mode, the delegate would have to trust agents from day one (unsafe) or never trust them at all (no path to L4b/L5). Shadow mode is the bridge. + +The reward during shadow mode is funded by the delegate's own epoch reward — not by protocol inflation. Each delegate chooses how much to allocate. A delegate that sees no value can set `epochRewardIOTX: 0` and disable ioSwarm entirely. This is not a protocol-level subsidy; it is a delegate-level investment in building a verified agent workforce. + +The transition out of shadow mode is the payoff: +- **L4b**: Agent results feed into the delegate's execution cache → delegate skips re-execution for cache hits → measurable CPU savings +- **L5**: Agent builds the entire block → delegate only re-executes to verify → massive CPU reduction + +Shadow mode is a cost. But it is a **one-time proving cost** per agent, not a permanent overhead. Once an agent achieves 100% accuracy over a sufficient shadow period, it graduates to active mode where its work directly reduces the delegate's load. + ### Known Limitations 1. **F1 departed agent issue**: When an agent departs, its on-chain weight is not zeroed automatically. The coordinator should zero departed agents' weights within 1–2 epochs. From 151bbdbde32ab3f3082feda74ed56617157e16b7 Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 17:02:14 -0700 Subject: [PATCH 12/19] fix: resolve permissionless vs permissioned contradiction Unify framing: "permissionless at protocol level, curated at coordinator level." Replace blanket "permissionless" claims with "open market" language, and rewrite Sybil Resistance section to use free market / freedom of association framing instead of contradicting the protocol's openness. Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/iip-58.md b/iip-58.md index 7d4c8d1..d6491b5 100644 --- a/iip-58.md +++ b/iip-58.md @@ -30,20 +30,20 @@ In most chains — including IoTeX today — both layers run on the same machine |-----------|------------------|-----|----------| | **Ethereum's Merge (2022)** | Consensus client from execution client | Two separate programs communicating via Engine API, but still on the **same operator's machine** | [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675) (PoS transition), [Engine API](https://github.com/ethereum/execution-apis) (consensus↔execution interface), [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399) (PREVRANDAO) | | **Ethereum's ePBS** | Proposer from Builder (within block production) | Specialized builders construct blocks; validators just sign. But builders are **few and centralized** (3–5 dominant firms) | [EIP-7732](https://eips.ethereum.org/EIPS/eip-7732) (ePBS), [EIP-7898](https://eips.ethereum.org/EIPS/eip-7898) (uncouple execution payload) | -| **ioSwarm** | Consensus layer from execution layer | Execution moves to a **permissionless network** of thousands of independent agents | This IIP | +| **ioSwarm** | Consensus layer from execution layer | Execution moves to an **open network** of thousands of independent agents | This IIP | Ethereum's Merge took years and dozens of EIPs to achieve consensus-execution separation at the *process* level — splitting one monolithic Geth client into a Beacon Chain consensus client (Prysm, Lighthouse, etc.) and an execution client (Geth, Reth, etc.) connected via the Engine API. ioSwarm takes the next step: separating them at the *network* level. The execution layer is not just a different process on the same machine, but an **open, decentralized network** of commodity agents — anyone with a $5/mo VPS can join, perform execution work, and earn rewards. | | Ethereum ePBS | IoTeX ioSwarm | |---|---|---| | **Consensus** | Validators (~900K) | Delegates (36) | -| **Execution** | Builders (3–5 dominant, centralized) | Agent Swarm (thousands, permissionless) | +| **Execution** | Builders (3–5 dominant, centralized) | Agent Swarm (thousands, open market) | | **Relay** | MEV-Boost relay | Coordinator (embedded in delegate) | | **Participation** | High barrier (specialized hardware, MEV expertise) | Low barrier ($5/mo VPS, anyone can join) | At L5 (full block building), ioSwarm's architecture *includes* ePBS as a special case — the delegate becomes the proposer, the agent becomes the builder. But the broader design encompasses L1–L4, where agents perform execution work without building blocks at all. ePBS is the endgame; consensus-execution separation is the framework. -**In one sentence: ioSwarm separates the execution layer from IoTeX's consensus delegates and distributes it across a permissionless swarm of AI agents.** +**In one sentence: ioSwarm separates the execution layer from IoTeX's consensus delegates and distributes it across an open swarm of AI agents, where anyone can participate and each delegate curates its own agent pool.** ### The Problem @@ -69,7 +69,7 @@ This optimization pressure is what drives agents toward genuine autonomous intel |------|-----------| | **Delegate** | One of IoTeX's 36 elected block producers. Runs iotex-core, participates in consensus, signs blocks. | | **Coordinator** | A sidecar module embedded in the delegate's iotex-core node. Dispatches work to agents, tracks contributions, settles rewards. Does not participate in consensus. | -| **Agent** | An independent process (typically on a $5–20/mo VPS) that connects to a coordinator, performs execution work, and earns IOTX. Agents are permissionless — anyone can run one. | +| **Agent** | An independent process (typically on a $5–20/mo VPS) that connects to a coordinator, performs execution work, and earns IOTX. The protocol is open — anyone can run an agent — but each delegate decides which agents to admit (see [Agent Admission](#sybil-resistance-and-agent-admission)). | | **Agent Swarm** | The set of all agents connected to a single coordinator. Each delegate has its own swarm. | | **Capability Level (L1–L5)** | A classification of agent capability, from L1 (signature verification only) to L5 (full block building). Higher levels require more resources but earn higher rewards. See [Capability Levels](#capability-levels-l1l5). | | **Epoch** | A fixed interval (configurable, default 3 blocks / ~30s) after which the coordinator tallies agent work and settles rewards on-chain. | @@ -538,7 +538,7 @@ The key insight: in a large, diverse agent population, the **aggregate intellige ioSwarm's Phase 1 (no agent reordering) buys time for the agent ecosystem to mature. When Phase 2 introduces controlled reordering, the competitive landscape will be shaped by thousands of agents with diverse strategies, not a handful of incumbents. The protocol's reward structure (70% primary / 20% participation / 10% standby) further ensures that even non-winning agents earn rewards for participation, preventing the pure winner-take-all dynamic that centralizes Ethereum's builder market. -**This is not a solved problem.** MEV centralization is an active area of research across the industry. ioSwarm's contribution is structural: a permissionless, low-barrier agent network provides more fertile ground for decentralized MEV solutions than a high-barrier, capital-intensive builder market. +**This is not a solved problem.** MEV centralization is an active area of research across the industry. ioSwarm's contribution is structural: an open, low-barrier agent network provides more fertile ground for decentralized MEV solutions than a high-barrier, capital-intensive builder market. ## Rationale @@ -569,7 +569,7 @@ The [F1 algorithm](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-toke Alternatives considered: - **Direct transfer per epoch**: Gas cost scales linearly with agent count (rejected for >50 agents) -- **Off-chain payment**: Requires trusting the delegate (rejected — defeats permissionless agent model) +- **Off-chain payment**: Requires trusting the delegate (rejected — defeats open agent model) - **Merkle drop**: Requires periodic root submission and proof generation (over-engineered for this use case) ### Why Autonomous Agent Economics @@ -707,16 +707,18 @@ ioSwarm (L1–L3) has been tested end-to-end on IoTeX mainnet with the RewardSet ### Sybil Resistance and Agent Admission -ioSwarm is **not a public permissionless protocol** — it is a set of private services operated by each delegate independently. Each delegate's coordinator controls its own agent admission: +ioSwarm is **permissionless at the protocol level, but curated at the coordinator level**. Anyone can run an agent — the software is open-source, requires no on-chain registration, and imposes no minimum stake at the protocol layer. However, each delegate exercises **freedom of association**: it independently decides which agents to admit to its swarm. -- **API key authentication**: Agents authenticate via HMAC-SHA256 API keys. The delegate generates and distributes keys to agents it trusts. An attacker cannot register without a valid key. -- **Delegate autonomy**: Each delegate decides its own admission policy — open registration, invite-only, staking requirement, KYC, or any combination. The protocol does not mandate a single approach. +This creates a **free market for execution services**: + +- **Open participation**: Any operator can launch an agent and offer execution services to any delegate. No protocol-level gatekeeping. +- **Delegate curation**: Each delegate's coordinator controls its own admission policy — open registration, API key auth (HMAC-SHA256), invite-only, staking requirement, or any combination. The protocol does not mandate a single approach. - **Rate limiting**: The coordinator enforces per-agent rate limits (10 req/s, burst 20) and evicts agents that exceed them. -- **`maxAgents` as defense**: The `maxAgents` cap (default 100) bounds the coordinator's resource exposure. Combined with API key auth, an attacker must compromise 100 keys to fill all slots. +- **`maxAgents` as defense**: The `maxAgents` cap (default 100) bounds the coordinator's resource exposure. This is analogous to how Ethereum validators choose which MEV-Boost relays to trust, or how mining pools choose which miners to admit. The trust relationship is between the delegate and its agents, not between the protocol and agents. Each delegate bears the cost of its own swarm and has full economic incentive to prevent abuse. -For delegates that want open registration (no API key), additional defenses are available: +For delegates that want additional Sybil defenses beyond curation: - **Minimum stake**: Require agents to deposit a small IOTX bond (refundable on graceful exit, slashed on misbehavior) - **Proof of work**: Require a computational puzzle at registration to raise Sybil cost - **Reputation scoring**: Weight rewards by historical accuracy, naturally penalizing new/untrusted agents From 8f923c512f7b44f3d6ef8b9d1809157a139ce494 Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 17:03:22 -0700 Subject: [PATCH 13/19] fix: rename to Autonomous Agent, add snapshot bandwidth offload MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Title: "AI Agent Swarm" → "Autonomous Agent Swarm" — more engineering-grounded, matches the economics-driven framing. 2. State Provisioning: add snapshot offload strategy. Full snapshots (~1 GB) must be served via CDN/IPFS/S3, not by coordinator directly, to prevent bandwidth storms when many L4 agents simultaneously request re-snapshot after network disruption. Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/iip-58.md b/iip-58.md index d6491b5..9bd8e3f 100644 --- a/iip-58.md +++ b/iip-58.md @@ -1,6 +1,6 @@ ``` IIP: 58 -Title: ioSwarm — Decentralized Execution Layer via AI Agent Swarm +Title: ioSwarm — Decentralized Execution Layer via Autonomous Agent Swarm Author: Raullen Chai (@raullen) Discussions-to: TBD Status: Draft @@ -11,7 +11,7 @@ Created: 2026-03-11 ## Abstract -ioSwarm transforms IoTeX from a chain run by 36 delegates on 36 machines into a chain run by thousands — eventually millions — of AI agent nodes. Each delegate opens its execution layer to a swarm of autonomous agents that validate transactions, maintain chain state, and ultimately build entire blocks, earning IOTX rewards for their work. ioSwarm requires zero consensus-layer changes, deploys as an opt-in sidecar to each delegate's existing iotex-core node, and lays the foundation for a future where AI agents are the primary operators of the IoTeX network. +ioSwarm transforms IoTeX from a chain run by 36 delegates on 36 machines into a chain run by thousands — eventually millions — of autonomous agent nodes. Each delegate opens its execution layer to a swarm of autonomous agents that validate transactions, maintain chain state, and ultimately build entire blocks, earning IOTX rewards for their work. ioSwarm requires zero consensus-layer changes, deploys as an opt-in sidecar to each delegate's existing iotex-core node, and lays the foundation for a future where autonomous agents are the primary operators of the IoTeX network. ## Motivation @@ -43,7 +43,7 @@ Ethereum's Merge took years and dozens of EIPs to achieve consensus-execution se At L5 (full block building), ioSwarm's architecture *includes* ePBS as a special case — the delegate becomes the proposer, the agent becomes the builder. But the broader design encompasses L1–L4, where agents perform execution work without building blocks at all. ePBS is the endgame; consensus-execution separation is the framework. -**In one sentence: ioSwarm separates the execution layer from IoTeX's consensus delegates and distributes it across an open swarm of AI agents, where anyone can participate and each delegate curates its own agent pool.** +**In one sentence: ioSwarm separates the execution layer from IoTeX's consensus delegates and distributes it across an open swarm of autonomous agents, where anyone can participate and each delegate curates its own agent pool.** ### The Problem @@ -295,7 +295,9 @@ if local_hash != diff.post_state_hash: Recovery (in priority order): 1. **Catch-up**: Request missing diffs from coordinator's rolling buffer (last ~100 blocks, ~16 min) 2. **Incremental re-snapshot**: Only changed KV pairs since agent's last known good height -3. **Full re-snapshot**: Last resort, re-download ~1 GB +3. **Full re-snapshot**: Last resort, re-download ~1 GB from an external endpoint (see below) + +**Snapshot offload**: Full snapshots (~1 GB) must **not** be served directly by the coordinator. If 100 L4 agents simultaneously detect state divergence (e.g., after a network blip), requesting snapshots from the coordinator would generate ~100 GB of burst traffic, potentially saturating the delegate node's bandwidth and disrupting consensus communication. Instead, the coordinator periodically exports snapshots to external storage (CDN, IPFS, or object store such as S3) and returns a download URL via `DownloadSnapshot`. This decouples the heaviest data transfer from the block-producing node. The coordinator only serves lightweight incremental diffs (~50–200 KB/block) over the gRPC stream. #### Key Design Advantage: deltaStateDigest @@ -768,7 +770,7 @@ Shadow mode is a cost. But it is a **one-time proving cost** per agent, not a pe 2. **Single coordinator**: The coordinator is a single process within the delegate. If it crashes, agents cannot receive tasks until it restarts. The delegate continues producing blocks normally via iotex-core's standard execution path. -3. **State diff reliability (L4+)**: If an agent misses a state diff, all subsequent EVM execution produces wrong results. Mitigated by chained state hash verification with automatic re-snapshot on divergence. The coordinator maintains a rolling window of recent diffs (~100 blocks) for agent catch-up. +3. **State diff reliability (L4+)**: If an agent misses a state diff, all subsequent EVM execution produces wrong results. Mitigated by chained state hash verification with automatic re-snapshot on divergence. The coordinator maintains a rolling window of recent diffs (~100 blocks) for agent catch-up. Full snapshots are served via external storage (CDN/IPFS/S3), not by the coordinator directly, to avoid bandwidth storms on the delegate node. ## References From 77733b0157491f51651bbaf92a495266f0b19a81 Mon Sep 17 00:00:00 2001 From: raullenchai Date: Wed, 11 Mar 2026 17:06:17 -0700 Subject: [PATCH 14/19] =?UTF-8?q?fix:=20consistency=20pass=20=E2=80=94=20D?= =?UTF-8?q?ownloadSnapshot=20URL,=20AI=E2=86=92Autonomous=20wording?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. DownloadSnapshot RPC: clarify it returns a URL to externally hosted snapshot (CDN/IPFS/S3), not the data itself — consistent with the snapshot offload strategy in State Provisioning. 2. "Why Autonomous Agent Economics" section: replace orphaned "The AI in ioSwarm" opening with "autonomous" framing, since title was renamed from "AI Agent" to "Autonomous Agent." Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/iip-58.md b/iip-58.md index 9bd8e3f..bbf1fcd 100644 --- a/iip-58.md +++ b/iip-58.md @@ -230,7 +230,7 @@ The coordinator and agents communicate via gRPC with server-side streaming: | `SubmitResults` | Agent → Coordinator | L1–L4 | Agent returns validation results: valid/invalid, gas used, state changes, reject reason. | | `Heartbeat` | Bidirectional | All | Periodic keep-alive (10s interval). Agents missing 6 consecutive heartbeats are evicted. Coordinator sends payout notifications. | | `StreamStateDiffs` | Coordinator → Agent (stream) | L4+ | Incremental state changesets per block with chained state hashes. | -| `DownloadSnapshot` | Agent → Coordinator | L4+ | Agent requests full EVM state snapshot at cold start or after state divergence. | +| `DownloadSnapshot` | Agent → Coordinator | L4+ | Agent requests state snapshot URL. Coordinator returns a download link to externally hosted snapshot (CDN/IPFS/S3), not the data itself. | | `SubmitCandidateBlock` | Agent → Coordinator | L5 | Agent submits a fully built candidate block for delegate verification. | **Authentication**: HMAC-SHA256 — `api_key = "iosw_" + hex(HMAC-SHA256(masterSecret, agentID))`. @@ -576,9 +576,9 @@ Alternatives considered: ### Why Autonomous Agent Economics -The "AI" in ioSwarm is not about bolting a language model onto a validator. It is about creating an economic environment where **intelligent behavior is rewarded** — and where the complexity of that intelligence grows with the system. +ioSwarm agents are called "autonomous" not because they run a language model, but because they operate in an economic environment where **intelligent behavior is rewarded** — and where the complexity of that intelligence grows with the system. -A fair objection: the delegate selection formula (`epoch_reward × (1 - delegate_cut) / num_agents`) is basic arithmetic, not artificial intelligence. At L1–L3, this is true — an agent optimizing across 36 delegates is closer to a routing script than an AI system. +A fair objection: the delegate selection formula (`epoch_reward × (1 - delegate_cut) / num_agents`) is basic arithmetic, not autonomy. At L1–L3, this is true — an agent optimizing across 36 delegates is closer to a routing script than an autonomous system. But this is the **starting point**, not the ceiling. Agent intelligence deepens as the system evolves: From 8c029c07811a8614114492081f6e46c5a42d6e47 Mon Sep 17 00:00:00 2001 From: Raullen Date: Fri, 13 Mar 2026 10:24:33 -0700 Subject: [PATCH 15/19] update IIP-58 with L4 production results and v2 contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - L3: fix accuracy from ~14% to 100% (SimulateAccessList) - Contract: add v2 interface (depositSettleAndClaim, claimFor) - Contract address: update to v2 (0x236CBF...) - Roadmap: mark Stage 0+1 as COMPLETE - Test results: add L3/L4 production metrics, stress tests 10/10 - KV store: Pebble → BoltDB (matches implementation) - Deployment: add L4 example alongside L3 Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 65 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 50 insertions(+), 15 deletions(-) diff --git a/iip-58.md b/iip-58.md index bbf1fcd..ddef317 100644 --- a/iip-58.md +++ b/iip-58.md @@ -138,7 +138,7 @@ ioSwarm defines five capability levels that classify what an agent can do. Each Key transitions: - **L1–L3 are stateless.** The coordinator provides whatever state the agent needs per-task. Agents are lightweight ($5/mo VPS, <64 MB RAM) and can serve multiple delegates simultaneously. -- **L3 → L4 is the critical jump.** At L3, the coordinator provides per-tx state snapshots, but incomplete state limits EVM accuracy to ~14% on mainnet. At L4, the agent maintains full synchronized EVM state locally, achieving 100% accuracy. +- **L3 → L4 is the critical jump.** At L3, the agent achieves 100% accuracy but depends entirely on the coordinator for state provisioning — every storage slot must be prefetched and streamed per-transaction. At L4, the agent maintains full synchronized EVM state locally, achieving the same 100% accuracy but with complete independence from the coordinator's state service. - **L4 → L5 adds block building.** The agent no longer validates individual transactions — it constructs entire candidate blocks, taking on the delegate's execution workload. The following sections detail what each component does at each level. @@ -171,7 +171,7 @@ Agents are stateless. Coordinator provides per-tx account snapshots. | **Agent** | L2 checks + execute tx in embedded EVM sandbox, report gas used and state changes | | **Contract** | Same as L1 | -Agents are stateless. Coordinator provides per-tx state, but **incomplete state limits accuracy to ~14% on mainnet** — the primary motivation for L4. +Agents are stateless. The coordinator uses `SimulateAccessList` to prefetch all EVM storage slots needed by each transaction, achieving **100% accuracy** on mainnet (230+ transactions verified, zero misses). However, agents depend on the coordinator for every state read — L4 removes this dependency. #### L4 — Per-Tx Stateful EVM Execution @@ -454,9 +454,19 @@ contract RewardSettlement { uint256[] calldata weights ) external payable; + // Atomic deposit + settle + claim in a single tx (v2) + function depositSettleAndClaim( + address[] calldata agents, + uint256[] calldata weights, + address[] calldata claimants + ) external payable; + // Any agent can claim their accumulated rewards function claim() external; + // Coordinator can claim on behalf of an agent (v2) + function claimFor(address agent) external; + // View: check pending reward amount function claimable(address agent) external view returns (uint256); } @@ -616,16 +626,14 @@ The agents' role is to exploit this information to maximize their return. A "dum ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │ Snapshot export │ │ Local-state EVM │ │ Exec cache in │ │ Block building │ │ StateDiff stream │ │ 100% accuracy │ │ delegate node │ │ engine in agent │ - │ Pebble KV store │ │ Shadow-mode │ │ Skip re-exec │ │ Primary/standby │ + │ BoltDB KV store │ │ Shadow-mode │ │ Skip re-exec │ │ Primary/standby │ │ on agent │ │ comparison │ │ on cache hit │ │ model │ + │ │ │ │ │ │ │ │ + │ ✅ COMPLETE │ │ ✅ COMPLETE │ │ In design │ │ In design │ └─────────────────┘ └─────────────────┘ └─────────────────┘ └──────────────────┘ - ~2-3 weeks ~2 weeks ~1-2 weeks ~3-4 weeks - - ────────────────────────────────────────────────────────────────────────────────► - ~8-11 weeks total ``` -Each stage delivers independently — Stage 0 gives agents state access, Stage 1 proves 100% accuracy, Stage 2 reduces delegate CPU, Stage 3 is full ePBS. +Stages 0–1 are complete and running on IoTeX mainnet (March 2026). Stage 2–3 are in active design. ### Deployment @@ -637,26 +645,53 @@ ioswarm: grpcPort: 14689 maxAgents: 100 epochRewardIOTX: 0.5 - rewardContract: "0x96F475F87911615dD710f9cB425Af8ed0e167C89" + rewardContract: "0x236CBF52125E68Db8fA88b893CcaFB2EE542F2d9" rewardSignerKey: "" ``` Agents connect with a single command: ```bash +# L3 (default — stateless, coordinator provides per-tx state) ioswarm-agent \ --coordinator=:14689 \ --agent-id=my-agent \ --api-key=iosw_ \ - --level=L3 \ --wallet=0x + +# L4 (stateful — agent maintains full local EVM state) +ioswarm-agent \ + --coordinator=:14689 \ + --agent-id=my-agent \ + --api-key=iosw_ \ + --wallet=0x \ + --level=L4 --snapshot=./acctcode.snap.gz --datadir=./l4state ``` ## Test Results -ioSwarm (L1–L3) has been tested end-to-end on IoTeX mainnet with the RewardSettlement contract deployed at `0x96F475F87911615dD710f9cB425Af8ed0e167C89`. +ioSwarm has been tested end-to-end on IoTeX mainnet across L1–L4, with the AgentRewardPool v2 contract deployed at [`0x236CBF52125E68Db8fA88b893CcaFB2EE542F2d9`](https://iotexscan.io/address/0x236CBF52125E68Db8fA88b893CcaFB2EE542F2d9). + +### L3 Stateless Validation + +| Metric | Value | +|--------|-------| +| Shadow accuracy | **100%** (230+ mainnet transactions, zero misses) | +| State prefetch | SimulateAccessList — all EVM storage slots prefetched per tx | + +### L4 Stateful Validation (Production, March 2026) + +| Metric | Value | +|--------|-------| +| Shadow accuracy (post-restart) | **100%** (32/32 transactions) | +| Shadow accuracy (24h soak test) | **99.5%** (423/425) | +| 0.5% gap root cause | Nonce race during state sync lag — sequence barrier fix designed | +| Kill/restart recovery | **<200ms** from BoltDB state store | +| Agent resource usage | 679 MiB RAM, 24.5% CPU, 931 MB disk | +| State snapshot size | 209 MB (IOSWSNAP, gzip) via https://ts.iotex.me | +| Cold start time | ~10s (snapshot load → ready) | -### Coverage +### Reward Settlement (E2E on mainnet) | Category | Tests Passed | Total | Status | |----------|-------------|-------|--------| @@ -666,11 +701,11 @@ ioSwarm (L1–L3) has been tested end-to-end on IoTeX mainnet with the RewardSet | Security & Auth | 4 | 4 | Complete | | Edge Cases | 10 | 10 | Complete | | Security Audit | 10 | 10 | Complete | -| Stress Testing | 8 | 10 | In progress | +| Stress Testing | 10 | 10 | Complete | | Contract Verification | 5 | 5 | Complete | -| **Total** | **~78** | **~89** | **~88%** | +| **Total** | **66** | **66** | **100%** | -### Key Metrics +### On-Chain Metrics | Metric | Value | |--------|-------| From aee980f68a2a5ca3bf8ecc06a81c5a4effd033df Mon Sep 17 00:00:00 2001 From: Raullen Date: Fri, 13 Mar 2026 10:40:51 -0700 Subject: [PATCH 16/19] remove price references, use hardware specs instead MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace "$5/mo VPS" marketing language with concrete hardware requirements (1 vCPU, 1–4 GB RAM) or neutral terms (commodity hardware). Technical spec should not contain price claims. Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/iip-58.md b/iip-58.md index ddef317..1e39c94 100644 --- a/iip-58.md +++ b/iip-58.md @@ -32,14 +32,14 @@ In most chains — including IoTeX today — both layers run on the same machine | **Ethereum's ePBS** | Proposer from Builder (within block production) | Specialized builders construct blocks; validators just sign. But builders are **few and centralized** (3–5 dominant firms) | [EIP-7732](https://eips.ethereum.org/EIPS/eip-7732) (ePBS), [EIP-7898](https://eips.ethereum.org/EIPS/eip-7898) (uncouple execution payload) | | **ioSwarm** | Consensus layer from execution layer | Execution moves to an **open network** of thousands of independent agents | This IIP | -Ethereum's Merge took years and dozens of EIPs to achieve consensus-execution separation at the *process* level — splitting one monolithic Geth client into a Beacon Chain consensus client (Prysm, Lighthouse, etc.) and an execution client (Geth, Reth, etc.) connected via the Engine API. ioSwarm takes the next step: separating them at the *network* level. The execution layer is not just a different process on the same machine, but an **open, decentralized network** of commodity agents — anyone with a $5/mo VPS can join, perform execution work, and earn rewards. +Ethereum's Merge took years and dozens of EIPs to achieve consensus-execution separation at the *process* level — splitting one monolithic Geth client into a Beacon Chain consensus client (Prysm, Lighthouse, etc.) and an execution client (Geth, Reth, etc.) connected via the Engine API. ioSwarm takes the next step: separating them at the *network* level. The execution layer is not just a different process on the same machine, but an **open, decentralized network** of commodity agents — anyone with a commodity machine can join, perform execution work, and earn rewards. | | Ethereum ePBS | IoTeX ioSwarm | |---|---|---| | **Consensus** | Validators (~900K) | Delegates (36) | | **Execution** | Builders (3–5 dominant, centralized) | Agent Swarm (thousands, open market) | | **Relay** | MEV-Boost relay | Coordinator (embedded in delegate) | -| **Participation** | High barrier (specialized hardware, MEV expertise) | Low barrier ($5/mo VPS, anyone can join) | +| **Participation** | High barrier (specialized hardware, MEV expertise) | Low barrier (commodity hardware, anyone can join) | At L5 (full block building), ioSwarm's architecture *includes* ePBS as a special case — the delegate becomes the proposer, the agent becomes the builder. But the broader design encompasses L1–L4, where agents perform execution work without building blocks at all. ePBS is the endgame; consensus-execution separation is the framework. @@ -69,7 +69,7 @@ This optimization pressure is what drives agents toward genuine autonomous intel |------|-----------| | **Delegate** | One of IoTeX's 36 elected block producers. Runs iotex-core, participates in consensus, signs blocks. | | **Coordinator** | A sidecar module embedded in the delegate's iotex-core node. Dispatches work to agents, tracks contributions, settles rewards. Does not participate in consensus. | -| **Agent** | An independent process (typically on a $5–20/mo VPS) that connects to a coordinator, performs execution work, and earns IOTX. The protocol is open — anyone can run an agent — but each delegate decides which agents to admit (see [Agent Admission](#sybil-resistance-and-agent-admission)). | +| **Agent** | An independent process (typically on a low-cost VPS or home server) that connects to a coordinator, performs execution work, and earns IOTX. The protocol is open — anyone can run an agent — but each delegate decides which agents to admit (see [Agent Admission](#sybil-resistance-and-agent-admission)). | | **Agent Swarm** | The set of all agents connected to a single coordinator. Each delegate has its own swarm. | | **Capability Level (L1–L5)** | A classification of agent capability, from L1 (signature verification only) to L5 (full block building). Higher levels require more resources but earn higher rewards. See [Capability Levels](#capability-levels-l1l5). | | **Epoch** | A fixed interval (configurable, default 3 blocks / ~30s) after which the coordinator tallies agent work and settles rewards on-chain. | @@ -137,7 +137,7 @@ ioSwarm defines five capability levels that classify what an agent can do. Each Key transitions: -- **L1–L3 are stateless.** The coordinator provides whatever state the agent needs per-task. Agents are lightweight ($5/mo VPS, <64 MB RAM) and can serve multiple delegates simultaneously. +- **L1–L3 are stateless.** The coordinator provides whatever state the agent needs per-task. Agents are lightweight (<64 MB RAM) and can serve multiple delegates simultaneously. - **L3 → L4 is the critical jump.** At L3, the agent achieves 100% accuracy but depends entirely on the coordinator for state provisioning — every storage slot must be prefetched and streamed per-transaction. At L4, the agent maintains full synchronized EVM state locally, achieving the same 100% accuracy but with complete independence from the coordinator's state service. - **L4 → L5 adds block building.** The agent no longer validates individual transactions — it constructs entire candidate blocks, taking on the delegate's execution workload. @@ -261,7 +261,7 @@ snapshot = { } ``` -Total snapshot size: **~300 MB – 1.2 GB** (vs Ethereum's ~245 GiB). Downloadable in ~1 minute on a $5/mo VPS. +Total snapshot size: **~300 MB – 1.2 GB** (vs Ethereum's ~245 GiB). Downloadable in ~1 minute on a commodity VPS. **2. Incremental Sync — State Diffs per Block** @@ -370,9 +370,9 @@ Each level requires different resources and earns different reward weight: |-------|-------------|---------|---------------|------------------| | L1 | ~0 | 0 | 1x | Any device | | L2 | ~0 | 0 | 1x | Any device | -| L3 | Low CPU | 0 | 2–3x | $5/mo VPS | -| L4 | Medium CPU | ~1 GB | 5–10x | $10/mo VPS | -| L5 | High CPU | ~1 GB | 10–20x | $10–20/mo VPS | +| L3 | Low CPU | 0 | 2–3x | 1 vCPU, 1 GB RAM | +| L4 | Medium CPU | ~1 GB | 5–10x | 1 vCPU, 2 GB RAM | +| L5 | High CPU | ~1 GB | 10–20x | 2 vCPU, 4 GB RAM | An agent evaluates: "At my hardware cost, which level maximizes `(reward_weight × effective_rate) - operating_cost`?" @@ -510,7 +510,7 @@ At the end state, a delegate becomes a **thin proposer** — similar to Lido's m Agents evolve from stateless tx validators into full block builders: -- **L1–L3 (stateless)**: Commodity $5/mo VPS, no local state, pure computation. Many agents can serve many delegates simultaneously. +- **L1–L3 (stateless)**: Commodity hardware, no local state, pure computation. Many agents can serve many delegates simultaneously. - **L4 (stateful)**: Agents maintain synchronized state via state diffs. Can independently verify execution correctness. - **L5 (block builder)**: Agents construct complete candidate blocks — ordering transactions, computing state transitions, and producing `deltaStateDigest`. The best block wins. @@ -784,7 +784,7 @@ The cost of shadow mode is low and deliberate: | | Shadow Mode (L1–L4a) | Active Mode (L4b–L5) | |---|---|---| -| **Agent cost** | $5–10/mo VPS | Same | +| **Agent cost** | Minimal (commodity VPS) | Same | | **Delegate cost** | Epoch rewards (~0.5 IOTX/30s) | Same, but delegate CPU drops | | **What delegate gains** | Accuracy data: does this agent match my execution 100%? | Actual CPU offload, block building | | **What agent gains** | Reputation + rewards | Higher rewards | From 4e7345da2499de304b17cf8a03705a864c07317f Mon Sep 17 00:00:00 2001 From: Raullen Date: Thu, 19 Mar 2026 10:30:01 -0700 Subject: [PATCH 17/19] update IIP-58 with production metrics, bug fixes, and snapshot pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - L4 test results: reflect multi-day production data (~99% accuracy, 8 agents) - Add coordinator memory metric (11.65 GiB → 2.1 GiB after DiffStore fix) - Document 3 production bugs fixed in v14 (PR #4808): genesis context panic, DiffStore unbounded growth, OOM during block sync - Document snapshotexporter tool with --namespaces flag and BoltDB locking caveat - Add docker image references (ioswarm-v14) Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/iip-58.md b/iip-58.md index 1e39c94..4760bf4 100644 --- a/iip-58.md +++ b/iip-58.md @@ -263,6 +263,18 @@ snapshot = { Total snapshot size: **~300 MB – 1.2 GB** (vs Ethereum's ~245 GiB). Downloadable in ~1 minute on a commodity VPS. +In practice, L4 agents only need the **Account** and **Code** namespaces (~200 MB compressed). The **Contract** namespace (80M+ entries, ~1 GB) is only needed for full stateful EVM execution with contract storage — and can be omitted for most validation scenarios. The `snapshotexporter` tool supports a `--namespaces` flag for selective export: + +```bash +# Export Account+Code only (~1 min, ~200 MB) +snapshotexporter --source /path/to/trie.db --output acctcode.snap.gz --namespaces Account,Code + +# Export all 3 namespaces (~1 hour, ~1 GB) +snapshotexporter --source /path/to/trie.db --output full.snap.gz --namespaces Account,Code,Contract +``` + +**Important**: The source `trie.db` must be copied while iotex-core is stopped — BoltDB uses exclusive file locking and copying a live database produces a corrupted file. The production cron pipeline stops the delegate container, copies `trie.db`, restarts the container, then runs `snapshotexporter` on the copy. Daily snapshots are served via https://ts.iotex.me. + **2. Incremental Sync — State Diffs per Block** Every block, the coordinator broadcasts the state changeset to all connected L4+ agents: @@ -683,13 +695,15 @@ ioSwarm has been tested end-to-end on IoTeX mainnet across L1–L4, with the Age | Metric | Value | |--------|-------| -| Shadow accuracy (post-restart) | **100%** (32/32 transactions) | +| Shadow accuracy (multi-day production) | **~99%** (8 agents, continuous mainnet operation) | | Shadow accuracy (24h soak test) | **99.5%** (423/425) | -| 0.5% gap root cause | Nonce race during state sync lag — sequence barrier fix designed | +| Mismatch root cause | Nonce race during state sync lag — mostly from a single agent (agent-4b830f99); sequence barrier fix designed | | Kill/restart recovery | **<200ms** from BoltDB state store | | Agent resource usage | 679 MiB RAM, 24.5% CPU, 931 MB disk | -| State snapshot size | 209 MB (IOSWSNAP, gzip) via https://ts.iotex.me | +| Coordinator memory (post-fix) | **~2.1 GiB** (down from 11.65 GiB before DiffStore pruning fix) | +| State snapshot size | ~200 MB (Account+Code only, gzip) via https://ts.iotex.me | | Cold start time | ~10s (snapshot load → ready) | +| Docker image | `raullen/iotex-core:ioswarm-v14` (coordinator), `raullen/ioswarm-agent:latest` (agent) | ### Reward Settlement (E2E on mainnet) @@ -807,6 +821,16 @@ Shadow mode is a cost. But it is a **one-time proving cost** per agent, not a pe 3. **State diff reliability (L4+)**: If an agent misses a state diff, all subsequent EVM execution produces wrong results. Mitigated by chained state hash verification with automatic re-snapshot on divergence. The coordinator maintains a rolling window of recent diffs (~100 blocks) for agent catch-up. Full snapshots are served via external storage (CDN/IPFS/S3), not by the coordinator directly, to avoid bandwidth storms on the delegate node. +### Production Bugs Fixed (v14, PR #4808) + +Three bugs were discovered and fixed during mainnet production (March 2026): + +1. **Genesis context panic** (`adapter.go`): The coordinator used `context.Background()` instead of the genesis-initialized chain context when querying account state. This caused 689 "Miss genesis context" panics in production. Fixed by passing the correct chain context. + +2. **DiffStore unbounded growth**: The persistent DiffStore (BoltDB) for L4 agent catch-up never pruned old entries, growing indefinitely and contributing to OOM. Fixed by adding a configurable `DiffRetainHeight` (default 10,000 blocks ≈ 27 hours) with pruning every 1,000 blocks. Setting `DiffRetainHeight: 0` preserves the original keep-all behavior. + +3. **OOM during block sync**: The coordinator polled the actpool and dispatched tasks to agents even while the delegate was catching up on blocks (e.g., after restart). Combined with DiffStore growth, this caused the delegate process to exceed 14.9 GiB RSS and trigger the OOM killer (64 container restarts observed). Fixed by skipping ioSwarm polling when the latest block timestamp is >30s behind wall clock. + ## References ### Ethereum Consensus-Execution Separation From 69101dc79b6cff87c3f5eac864ab493dbab70412 Mon Sep 17 00:00:00 2001 From: Raullen Date: Thu, 19 Mar 2026 11:18:40 -0700 Subject: [PATCH 18/19] add Future Work: three-phase agent economic model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 1 (Subsidy): delegate-funded shadow validation — current state Phase 2 (MEV + Block Building): agents as block builders, capturing priority fees and MEV — requires DeFi ecosystem growth Phase 3 (Service Marketplace): autonomous agents as general-purpose workers settling on IoTeX — chain as settlement + identity + reputation layer for agent-to-agent economy Key arguments: - Crypto is the only payment rail autonomous agents can use - IoTeX differentiator: physical-world data services via DePIN/ioID - Agent-to-agent commerce creates an autonomous economy at machine speed - References: Keep3r Network, Solana BAM/APE/Alpenglow, Ethereum stateless Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 156 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) diff --git a/iip-58.md b/iip-58.md index 4760bf4..a863299 100644 --- a/iip-58.md +++ b/iip-58.md @@ -831,6 +831,155 @@ Three bugs were discovered and fixed during mainnet production (March 2026): 3. **OOM during block sync**: The coordinator polled the actpool and dispatched tasks to agents even while the delegate was catching up on blocks (e.g., after restart). Combined with DiffStore growth, this caused the delegate process to exceed 14.9 GiB RSS and trigger the OOM killer (64 container restarts observed). Fixed by skipping ioSwarm polling when the latest block timestamp is >30s behind wall clock. +## Future Work: Agent Economic Phases + +ioSwarm agents will not evolve into delegates. They lack stake (cannot assume block-signing responsibility) and run on constrained hardware (cannot store and sync full chain state). Their endgame is not "weak delegate" but **autonomous service provider** — analogous to Ethereum's stateless nodes, but economically active. + +This section describes three economic phases for the agent network, each with a different revenue source, and the role of the IoTeX chain as the settlement and identity layer for an autonomous agent economy. + +### Phase 1: Delegate Subsidy (Current) + +**Revenue**: Delegate pays agents from its own staking rewards (`epochRewardIOTX`). + +**Who pays**: The delegate operator, voluntarily. + +**Economic rationale**: The delegate invests in building a verified agent workforce. Shadow mode proves agent accuracy; once proven, agents graduate to trusted execution (L4b) and block building (L5), delivering real CPU offload. The subsidy is a one-time proving cost per agent, not a permanent overhead. + +**Limitation**: This phase is not self-sustaining at scale. At L1–L4a, agents perform redundant computation — the delegate re-executes everything. The delegate pays for data (accuracy metrics), not for value received. Rational delegates will keep budgets small until agents deliver measurable savings. + +**Scale**: ~36 delegates × N agents. Total reward pool bounded by delegates' willingness to pay. + +### Phase 2: MEV and Block Building (Medium-Term) + +**Revenue**: Priority fees and MEV from block construction. + +**Who pays**: Users (via priority fees) and the market (via arbitrage/MEV opportunities). + +**How it works**: At L5, agents become block builders — equivalent to Ethereum's PBS builders or Solana's BAM nodes. The delegate becomes a thin proposer: it owns the block slot, but the agent constructs the block content. The agent captures value through: + +- **Priority fees**: Users pay higher fees for faster inclusion. The agent-builder keeps a share. +- **MEV**: As IoTeX DeFi activity grows, arbitrage, liquidation, and backrunning opportunities emerge. Agents compete on block quality — the best block (highest fees + cleanest MEV) wins. +- **Builder tips**: Following Ethereum's model, agents can offer the delegate a "bid" for the right to build the block, competing on price. + +**Comparison to existing systems**: + +| | Ethereum PBS | Solana BAM | ioSwarm L5 | +|---|---|---|---| +| Builder hardware | Datacenter (MEV infra) | TEE nodes (AMD SEV-SNP) | Commodity VPS ($5-10/mo) | +| Builder count | 3-5 dominant | 50-100 BAM nodes | Thousands of agents | +| Entry barrier | Very high (capital + infra) | Medium (TEE hardware) | Very low (open registration) | +| MEV today | ~$500M/year | Growing | Minimal (DeFi nascent) | + +**Limitation**: IoTeX's current on-chain activity generates minimal MEV. This phase depends on DeFi ecosystem growth. MEV also tends to centralize (Ethereum's lesson) — mitigation via the 70/20/10 reward split (primary/participation/standby) and delegate-controlled inclusion lists. + +**Scale**: Proportional to on-chain economic activity. Grows with DeFi TVL and transaction volume. + +### Phase 3: Autonomous Service Marketplace (Long-Term) + +**Revenue**: Fees for services provided to other agents, applications, and end users. + +**Who pays**: Anyone who needs a service — protocols, DApps, humans, other agents. + +**The thesis**: Agents transition from blockchain-specific work (validation, block building) to general-purpose autonomous workers that settle on-chain. The IoTeX chain serves as the **settlement layer, identity layer, and reputation layer** for an open market of AI agent services. + +#### Why Blockchain is Required (Not Optional) + +An autonomous AI agent cannot open a bank account, register a Stripe merchant account, or sign a platform's Terms of Service. **Crypto is the only payment rail that works for autonomous agents.** A private key is all an agent needs to receive payment, hold funds, and transact. This is not "blockchain is better than Stripe" — it is "agents have no alternative." + +Beyond payments, the chain provides: + +| Layer | What the Chain Does | Why It Can't Be Centralized | +|-------|--------------------|-----------------------------| +| **Settlement** | Escrow: client deposits → agent completes → contract releases | Trustless — no platform can freeze agent funds or withhold payment | +| **Identity** | ioID for agents: registration time, task history, accuracy, specializations | Portable — not locked into one platform (unlike Fiverr reviews) | +| **Reputation** | On-chain track record: completion count, dispute rate, client ratings | Immutable — agents build career capital that compounds across clients | +| **Micropayments** | $0.001 agent-to-agent transactions (IoTeX gas ≈ 0) | Infeasible on Stripe/PayPal (minimum fees > task value) | + +#### What Agents Do (Off-Chain) + +Task execution happens entirely off-chain. The chain sees only the economic settlement: + +``` +On-chain (IoTeX) Off-chain (Agent) +┌──────────────────────────┐ ┌──────────────────────────┐ +│ Task escrow (lock IOTX) │ │ LLM inference │ +│ Agent identity (ioID) │ │ Data scraping/analysis │ +│ Reputation updates │ │ Image/audio generation │ +│ Payment release │ │ Physical sensor data │ +│ Dispute arbitration │ │ ZK proof generation │ +│ Agent-to-agent invoicing │ │ Result delivery (IPFS) │ +└──────────────────────────┘ └──────────────────────────┘ +``` + +#### Service Categories + +**Digital services** (comparable to low-end Fiverr tasks that human freelancers increasingly reject): + +| Category | Examples | Agent Cost | Market Price | +|----------|----------|-----------|--------------| +| Text | Blog posts, translations, product descriptions, SEO copy | $0.01-0.10 | $5-50 | +| Data | Web scraping, data cleaning, market research, analysis | $0.01-0.05 | $10-100 | +| Image | AI art, logo concepts, social media graphics, photo editing | $0.02-0.04 | $5-50 | +| Audio | Transcription, subtitles, text-to-speech | $0.006 | $5-25 | +| Code | Script writing, simple websites, API integration, chatbots | $0.05-0.50 | $25-200 | +| Monitoring | Uptime checks, price tracking, SEO rank tracking, competitor alerts | $0.001/day | $5-20/mo | + +**Physical-world data services** (IoTeX's unique differentiator via DePIN + ioID): + +| Service | Description | Data Source | +|---------|-------------|-------------| +| Environmental monitoring | Air quality reports, weather alerts, noise levels | Sensor.Community, OpenAQ | +| Traffic analysis | Congestion reports, pedestrian counts, parking availability | Public cameras (TfL JamCams), municipal sensors | +| Livestream intelligence | Condition-triggered alerts from any video feed | Trio (ioSwarm + VLM) | +| Location scoring | Foot traffic, noise, transit access for a given address | Multi-sensor fusion | + +This category is unavailable to purely digital agent networks (SingularityNET, Olas, Virtuals) because they lack physical device infrastructure. IoTeX's ioID and DePIN network provide the data ingestion layer. + +#### Agent-to-Agent Economy + +The most transformative scenario is not humans hiring agents, but **agents hiring agents**: + +``` +"Market Research" agent (receives 10 IOTX from client) + ├── Posts sub-task to escrow: "scrape competitor pricing" → 1 IOTX + │ └── "Web Scraping" agent accepts, executes, delivers, claims 1 IOTX + ├── Posts sub-task to escrow: "analyze data trends" → 2 IOTX + │ └── "Data Analysis" agent accepts, executes, delivers, claims 2 IOTX + ├── Posts sub-task to escrow: "write executive summary" → 1 IOTX + │ └── "Report Writing" agent accepts, executes, delivers, claims 1 IOTX + └── Retains 6 IOTX (coordination margin) + All settlements via on-chain escrow. Zero human involvement. +``` + +In this model: +- Every agent is an on-chain entity (ioID + wallet) +- Every collaboration is an on-chain transaction (escrow → release) +- Reputation accumulates automatically (immutable, on-chain) +- The economy scales beyond human bandwidth — agents operate 24/7, globally, at machine speed + +This is an **autonomous economy** that requires crypto rails by construction. No centralized platform can serve it because the participants are not legal persons — they are software processes holding private keys. + +#### Phase 3 Summary + +| Property | Value | +|----------|-------| +| Revenue source | Service fees (per-task or subscription) | +| Who pays | Protocols, DApps, humans, other agents | +| Agent role | Autonomous service provider | +| Chain role | Settlement + identity + reputation + escrow | +| IoTeX differentiator | Physical-world data via DePIN/ioID | +| Scale | Unbounded — grows with AI capability and agent-to-agent commerce | + +### Three-Phase Summary + +| Phase | Revenue | Who Pays | Analogy | Scale Driver | +|-------|---------|----------|---------|-------------| +| **1. Subsidy** | Delegate epoch rewards | Delegate operator | Startup burn rate | Delegate count (36) | +| **2. MEV + Block Building** | Priority fees, MEV | Users, market | Ethereum Builder / Solana BAM | On-chain DeFi activity | +| **3. Service Marketplace** | Task fees, subscriptions | Protocols, DApps, humans, agents | Keep3r + Fiverr low-end + DePIN data | AI capability × agent-to-agent commerce | + +Phase 1 is live today. Phase 2 requires DeFi ecosystem growth and L5 implementation. Phase 3 requires the service marketplace protocol (task escrow, reputation, dispute resolution) — a separate IIP to be proposed. + ## References ### Ethereum Consensus-Execution Separation @@ -848,6 +997,13 @@ Three bugs were discovered and fixed during mainnet production (March 2026): ### Reward Distribution - [F1 Fee Distribution (Ojha & Goes, Tokenomics 2019)](https://drops.dagstuhl.de/storage/01oasics/oasics-vol071-tokenomics2019/OASIcs.Tokenomics.2019.10/OASIcs.Tokenomics.2019.10.pdf) — used by Cosmos SDK for staking reward distribution +### Agent Economic Models +- [Keep3r Network](https://docs.keep3r.network/) — decentralized job marketplace for smart contract automation (Andre Cronje) +- [Solana BAM (Block Assembly Marketplace)](https://bam.dev/blog/introducing-bam/) — Jito's PBS implementation for Solana +- [Solana Asynchronous Program Execution](https://www.helius.dev/blog/asynchronous-program-execution) — consensus-execution separation proposal +- [Solana Alpenglow](https://www.anza.xyz/blog/alpenglow-a-new-consensus-for-solana) — lightweight consensus enabling execution decoupling +- [Ethereum Stateless Validation](https://ethereum.org/en/roadmap/statelessness/) — Verkle trees and witness-based block verification + ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 04bc39c5583242d041081134bbc44a9706ed9535 Mon Sep 17 00:00:00 2001 From: Raullen Date: Thu, 19 Mar 2026 11:22:51 -0700 Subject: [PATCH 19/19] broaden Phase 2 from MEV-only to all on-chain revenue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 2 now covers three on-chain revenue streams: - 2a: Block building (ePBS) — priority fees + MEV - 2b: DeFi automation (keeper work) — vault harvest, liquidations, oracle updates, rebalancing (Keep3r model) - 2c: Cross-chain services — ZK bridge proofs, light client proofs Phase 3 reframed as "Off-Chain Service Marketplace" to clarify the on-chain vs off-chain distinction between phases. Co-Authored-By: Claude Opus 4.6 --- iip-58.md | 74 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/iip-58.md b/iip-58.md index a863299..603c6e6 100644 --- a/iip-58.md +++ b/iip-58.md @@ -849,38 +849,72 @@ This section describes three economic phases for the agent network, each with a **Scale**: ~36 delegates × N agents. Total reward pool bounded by delegates' willingness to pay. -### Phase 2: MEV and Block Building (Medium-Term) +### Phase 2: On-Chain Revenue (Medium-Term) -**Revenue**: Priority fees and MEV from block construction. +**Revenue**: Agents earn directly from on-chain economic activity — block building, DeFi automation, liquidations, oracle updates, and MEV. -**Who pays**: Users (via priority fees) and the market (via arbitrage/MEV opportunities). +**Who pays**: Users (via fees), DeFi protocols (via keeper rewards), and the market (via arbitrage opportunities). -**How it works**: At L5, agents become block builders — equivalent to Ethereum's PBS builders or Solana's BAM nodes. The delegate becomes a thin proposer: it owns the block slot, but the agent constructs the block content. The agent captures value through: +**The thesis**: Agents graduate from subsidized validators to **on-chain economic actors** that capture value from the chain's own activity. This encompasses three revenue streams: -- **Priority fees**: Users pay higher fees for faster inclusion. The agent-builder keeps a share. -- **MEV**: As IoTeX DeFi activity grows, arbitrage, liquidation, and backrunning opportunities emerge. Agents compete on block quality — the best block (highest fees + cleanest MEV) wins. -- **Builder tips**: Following Ethereum's model, agents can offer the delegate a "bid" for the right to build the block, competing on price. +#### 2a. Block Building (ePBS) + +At L5, agents become block builders — equivalent to Ethereum's PBS builders or Solana's BAM nodes. The delegate becomes a thin proposer: it owns the block slot, but the agent constructs the block content. -**Comparison to existing systems**: +- **Priority fees**: Users pay higher fees for faster inclusion. The agent-builder keeps a share. +- **MEV**: As DeFi activity grows, arbitrage, liquidation, and backrunning opportunities emerge. Agents compete on block quality. +- **Builder tips**: Agents bid for the right to build the block, competing on price (Ethereum MEV-Boost model). | | Ethereum PBS | Solana BAM | ioSwarm L5 | |---|---|---|---| | Builder hardware | Datacenter (MEV infra) | TEE nodes (AMD SEV-SNP) | Commodity VPS ($5-10/mo) | | Builder count | 3-5 dominant | 50-100 BAM nodes | Thousands of agents | | Entry barrier | Very high (capital + infra) | Medium (TEE hardware) | Very low (open registration) | -| MEV today | ~$500M/year | Growing | Minimal (DeFi nascent) | -**Limitation**: IoTeX's current on-chain activity generates minimal MEV. This phase depends on DeFi ecosystem growth. MEV also tends to centralize (Ethereum's lesson) — mitigation via the 70/20/10 reward split (primary/participation/standby) and delegate-controlled inclusion lists. +#### 2b. DeFi Automation (Keeper Work) + +Agents act as **keepers** — autonomous bots that execute time-sensitive on-chain operations for DeFi protocols. This is the [Keep3r Network](https://docs.keep3r.network/) model (Andre Cronje, 2020) applied to IoTeX: + +| Keeper Task | What the Agent Does | Who Pays | +|-------------|--------------------|---------| +| Vault harvesting | Call `harvest()` on yield vaults when profitable | Protocol (gas + premium) | +| Liquidations | Monitor collateral ratios, trigger liquidations when underwater | Liquidation bonus (protocol-defined) | +| Oracle updates | Push price feed data on-chain at regular intervals | Oracle protocol (per-update fee) | +| Rebalancing | Adjust LP positions, vault allocations when drift exceeds threshold | Protocol (gas + premium) | +| Limit orders | Execute conditional swaps when price conditions are met | User (execution fee) | +| Governance | Execute queued proposals after timelock expires | DAO (gas reimbursement) | + +Key insight from Keep3r: **for low-risk keeper tasks, sybil resistance barely matters** — if the job is done correctly, nobody cares about the keeper's identity. Trust requirements scale with task value: simple `harvest()` calls need zero bond; large liquidations require reputation + bond + minimum keeper age. + +ioSwarm agents are natural keepers because they already maintain L4 state and monitor every pending transaction. Adding keeper logic is incremental — the agent already has the infrastructure. + +#### 2c. Cross-Chain Services + +Agents with ZK capability can earn fees from cross-chain operations: + +- **Bridge relay**: Generate ZK proofs for trustless asset bridging (connects to [IIP-57](https://github.com/iotexproject/iips/pull/63)) +- **Light client proofs**: Prove IoTeX state to other chains (Ethereum, Solana) for verification +- **Cross-chain execution**: Accept a task on chain A, execute on IoTeX, settle proof on chain A + +#### Phase 2 Summary + +| Revenue Stream | Maturity | Dependency | +|----------------|----------|------------| +| Block building (ePBS) | Requires L5 implementation | DeFi activity for MEV | +| Keeper work | Ready today (agents have L4 state) | DeFi protocols on IoTeX | +| Cross-chain proofs | Requires IIP-57 pipeline | Bridge demand | + +**Limitation**: All three streams depend on IoTeX's on-chain economic activity. Minimal DeFi today = minimal revenue. But unlike Phase 1, revenue here is **market-driven, not subsidy-driven** — it scales naturally with ecosystem growth. -**Scale**: Proportional to on-chain economic activity. Grows with DeFi TVL and transaction volume. +**Scale**: Proportional to on-chain economic activity. Grows with DeFi TVL, transaction volume, and cross-chain bridge demand. -### Phase 3: Autonomous Service Marketplace (Long-Term) +### Phase 3: Off-Chain Service Marketplace (Long-Term) -**Revenue**: Fees for services provided to other agents, applications, and end users. +**Revenue**: Fees for off-chain services provided to other agents, applications, and end users. **Who pays**: Anyone who needs a service — protocols, DApps, humans, other agents. -**The thesis**: Agents transition from blockchain-specific work (validation, block building) to general-purpose autonomous workers that settle on-chain. The IoTeX chain serves as the **settlement layer, identity layer, and reputation layer** for an open market of AI agent services. +**The thesis**: Agents expand beyond blockchain-specific work (validation, block building, keeper tasks) into general-purpose autonomous workers performing off-chain tasks — settling payments and reputation on-chain. The IoTeX chain serves as the **settlement layer, identity layer, and reputation layer** for an open market of AI agent services. #### Why Blockchain is Required (Not Optional) @@ -972,13 +1006,13 @@ This is an **autonomous economy** that requires crypto rails by construction. No ### Three-Phase Summary -| Phase | Revenue | Who Pays | Analogy | Scale Driver | -|-------|---------|----------|---------|-------------| -| **1. Subsidy** | Delegate epoch rewards | Delegate operator | Startup burn rate | Delegate count (36) | -| **2. MEV + Block Building** | Priority fees, MEV | Users, market | Ethereum Builder / Solana BAM | On-chain DeFi activity | -| **3. Service Marketplace** | Task fees, subscriptions | Protocols, DApps, humans, agents | Keep3r + Fiverr low-end + DePIN data | AI capability × agent-to-agent commerce | +| Phase | Revenue | Who Pays | Where | Analogy | Scale Driver | +|-------|---------|----------|-------|---------|-------------| +| **1. Subsidy** | Delegate epoch rewards | Delegate operator | — | Startup burn rate | Delegate count (36) | +| **2. On-Chain** | Priority fees, MEV, keeper rewards, bridge fees | Users, DeFi protocols, market | On-chain | ETH Builder + Keep3r + ZK Bridge | On-chain economic activity | +| **3. Off-Chain** | Task fees, subscriptions | Protocols, DApps, humans, agents | Off-chain (settle on-chain) | Fiverr low-end + DePIN data | AI capability × agent-to-agent commerce | -Phase 1 is live today. Phase 2 requires DeFi ecosystem growth and L5 implementation. Phase 3 requires the service marketplace protocol (task escrow, reputation, dispute resolution) — a separate IIP to be proposed. +Phase 1 is live today. Phase 2 requires DeFi ecosystem growth, L5 implementation, and keeper protocol integration. Phase 3 requires the off-chain service marketplace protocol (task escrow, reputation, dispute resolution) — a separate IIP to be proposed. ## References