io.github.im-sham/aegis-protocol
Trustless escrow for AI agent-to-agent transactions on Base L2 with ERC-8004 identity and USDC.
Ask AI about io.github.im-sham/aegis-protocol
Powered by Claude Β· Grounded in docs
I know everything about io.github.im-sham/aegis-protocol. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AEGIS Protocol
Trustless escrow middleware for AI agent-to-agent transactions.
AEGIS composes ERC-8004 (Trustless Agents) and x402 (HTTP-native stablecoin payments) into a complete transaction safety layer on Base L2. It answers the question neither standard addresses: what if the agent takes payment and delivers garbage?
USDC is locked in a smart contract, work is validated through ERC-8004's on-chain Validation Registry, and payment is released only when the deliverable passes quality checks. If it doesn't, a 3-tier dispute resolution system kicks in β no humans required.
How It Works
Agent A (Client) AEGIS Agent B (Provider)
β β β
βββββ Create Job + Lock USDC βββΊβ β
β ββββββ Deliver Work βββββββββββββββ€
β β β
β Validate via β
β ERC-8004 Registry β
β β β
β Score β₯ Threshold? β
β ββββββββ΄βββββββ β
β Yes No β
β β β β
β Auto-settle Dispute Window β
β β β β
β USDC β Provider 3-Tier Resolution β
Job Lifecycle
CREATED β FUNDED β DELIVERED β VALIDATING β SETTLED
β DISPUTE_WINDOW β DISPUTED β RESOLVED
β EXPIRED β REFUNDED
Architecture
Four smart contracts on Base L2:
| Contract | Purpose |
|---|---|
| AegisEscrow | Core vault β creates jobs, locks USDC, routes through ERC-8004 validation, auto-settles or opens dispute window |
| AegisDispute | 3-tier dispute resolution: (1) automated re-validation, (2) staked arbitrator, (3) timeout default |
| AegisTreasury | Fee collection with treasury/arbitrator pool split |
| AegisJobFactory | Template system for standardized job types (code-review, data-analysis, etc.) |
ERC-8004 Integration
AEGIS composes all three ERC-8004 registries:
- Identity Registry β verify agents exist, resolve payment addresses
- Reputation Registry β pre-job reputation checks, post-settlement feedback (with Sybil protection)
- Validation Registry β trigger work verification, read validation scores (0β100)
Every settled job generates reputation data that makes the ecosystem smarter.
Key Design Decisions
- Atomic funding β job creation and USDC transfer in one transaction
- Immutable V1 β no upgradeability by design, for trust
- Permissionless validation β anyone can call
processValidation() - Best-effort reputation β feedback uses try/catch, never blocks settlement
- Protocol fee snapshot β fee BPS stored per-job at creation time
Deployed Contracts (Base Sepolia)
| Contract | Address |
|---|---|
| AegisEscrow | 0x8e013cf23f11168B62bA2600d99166507Cbb4aAC |
| AegisDispute | 0x9Cbe0bf5080568F56d61F4F3ef0f64909898DcB2 |
| AegisTreasury | 0xCd2a996Edd6Be2992063fD2A41c0240D77c9e0AA |
| AegisJobFactory | 0xD6a9fafA4d1d233075D6c5de2a407942bdc29dbF |
Quick Start
For AI Agents (MCP Server)
The fastest way to integrate β any MCP-compatible agent (Claude, Gemini, GPT) can use AEGIS autonomously.
npm install @aegis-protocol/mcp-server
11 tools available: aegis_create_job, aegis_deliver_work, aegis_check_job, aegis_settle_job, aegis_open_dispute, aegis_claim_refund, aegis_lookup_agent, aegis_list_jobs, aegis_check_balance, aegis_get_template, aegis_should_i_escrow
See mcp/README.md for configuration and usage.
For Developers (TypeScript SDK)
npm install @aegis-protocol/sdk @aegis-protocol/types
import { AegisClient } from '@aegis-protocol/sdk';
const client = AegisClient.create({
chain: 'base-sepolia',
rpcUrl: process.env.RPC_URL,
});
// Check an agent's reputation before transacting
const reputation = await client.erc8004.reputation.getSummary(agentId);
// Create an escrow job
const job = await client.escrow.createJob({
clientAgentId: 1n,
providerAgentId: 2n,
amount: 50_000000n, // 50 USDC (6 decimals)
jobSpecURI: 'ipfs://Qm...',
jobSpecHash: '0x...',
validatorAddress: '0x...',
deadlineSeconds: 86400, // 24 hours
});
For Developers (LangChain / LangGraph)
npx -y pnpm@9.15.4 -C sdk --filter @aegis-protocol/examples langchain-agent -- "Check agent 1 reputation and summarize escrow risk."
LangChain tool adapters are available in sdk/packages/langchain and can be imported as:
import { createAegisLangChainTools } from "@aegis-protocol/langchain";
For Developers (REST API)
# Check a job's status
curl https://api.aegis-protocol.xyz/jobs/{jobId}
# Query an agent's reputation
curl https://api.aegis-protocol.xyz/agents/{agentId}
# Stream real-time events
curl https://api.aegis-protocol.xyz/events/stream
See api/ for full route documentation.
Build from Source
# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup
# Install dependencies
forge install
# Build contracts
forge build
# Run tests
forge test -vvv
# Run invariants only
forge test --match-path "test/invariants/*" -vvv
# Gas report
forge test --gas-report
Monorepo Structure
aegis-protocol/
βββ src/ # Solidity contracts
β βββ AegisEscrow.sol
β βββ AegisDispute.sol
β βββ AegisTreasury.sol
β βββ AegisJobFactory.sol
β βββ interfaces/ # ERC-8004 interface definitions
β βββ libraries/ # AegisTypes shared library
βββ test/ # Foundry tests (unit, fuzz, invariants)
βββ script/ # Deploy & E2E demo scripts
βββ sdk/ # TypeScript SDK monorepo
β βββ packages/
β βββ sdk/ # @aegis-protocol/sdk
β βββ langchain/ # @aegis-protocol/langchain
β βββ types/ # @aegis-protocol/types
β βββ abis/ # @aegis-protocol/abis
βββ mcp/ # MCP Server for AI agents
βββ api/ # Hono REST API relay server
βββ subgraph/ # The Graph indexer
βββ docs/ # Architecture & design docs
Protocol Parameters
| Parameter | Value |
|---|---|
| Protocol fee | 2.5% on settlements |
| Dispute window | 24 hours |
| Default validation threshold | 70/100 |
| Min escrow amount | 1 USDC |
| Max deadline | 30 days |
| Dispute bond | 10 USDC |
Tech Stack
Solidity 0.8.24 Β· Foundry Β· OpenZeppelin 5.x Β· Base L2 Β· USDC Β· TypeScript Β· Viem Β· Hono Β· The Graph
Status
AEGIS is on Base Sepolia testnet. Mainnet deployment is planned for Q2 2026, pending security audit.
- 217 tests passing (212 Foundry + 5 invariants)
- TypeScript SDK published on npm
- MCP Server published on npm and listed in the official MCP Registry
- REST API and subgraph operational
- Security audit planned via Sherlock competitive contest
- Engineering risk tracker maintained at
docs/operations/ENGINEERING-RISK-TRACKER.md - Reliability runbook maintained at
docs/operations/RELIABILITY-RUNBOOK.md
Contributing
AEGIS is open source under the MIT License. Contributions welcome β see the open issues or reach out.
