{
  "markdown": "# AEGIS Protocol\n\n**Trustless escrow middleware for AI agent-to-agent transactions.**\n\nAEGIS composes [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) (Trustless Agents) and [x402](https://www.x402.org/) (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?*\n\nUSDC 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.\n\n## How It Works\n\n```\nAgent A (Client)                    AEGIS                         Agent B (Provider)\n      │                               │                                 │\n      ├──── Create Job + Lock USDC ──►│                                 │\n      │                               │◄──── Deliver Work ──────────────┤\n      │                               │                                 │\n      │                          Validate via                           │\n      │                        ERC-8004 Registry                        │\n      │                               │                                 │\n      │                        Score ≥ Threshold?                       │\n      │                         ┌──────┴──────┐                        │\n      │                        Yes            No                        │\n      │                         │              │                        │\n      │                   Auto-settle    Dispute Window                  │\n      │                         │              │                        │\n      │                   USDC → Provider   3-Tier Resolution           │\n```\n\n### Job Lifecycle\n\n```\nCREATED → FUNDED → DELIVERED → VALIDATING → SETTLED\n                                    ↘ DISPUTE_WINDOW → DISPUTED → RESOLVED\n           ↘ EXPIRED → REFUNDED\n```\n\n## Architecture\n\nFour smart contracts on Base L2:\n\n| Contract | Purpose |\n|----------|---------|\n| **AegisEscrow** | Core vault — creates jobs, locks USDC, routes through ERC-8004 validation, auto-settles or opens dispute window |\n| **AegisDispute** | 3-tier dispute resolution: (1) automated re-validation, (2) staked arbitrator, (3) timeout default |\n| **AegisTreasury** | Fee collection with treasury/arbitrator pool split |\n| **AegisJobFactory** | Template system for standardized job types (code-review, data-analysis, etc.) |\n\n### ERC-8004 Integration\n\nAEGIS composes all three ERC-8004 registries:\n\n- **Identity Registry** — verify agents exist, resolve payment addresses\n- **Reputation Registry** — pre-job reputation checks, post-settlement feedback (with Sybil protection)\n- **Validation Registry** — trigger work verification, read validation scores (0–100)\n\nEvery settled job generates reputation data that makes the ecosystem smarter.\n\n### Key Design Decisions\n\n- **Atomic funding** — job creation and USDC transfer in one transaction\n- **Immutable V1** — no upgradeability by design, for trust\n- **Permissionless validation** — anyone can call `processValidation()`\n- **Best-effort reputation** — feedback uses try/catch, never blocks settlement\n- **Protocol fee snapshot** — fee BPS stored per-job at creation time\n\n## Deployed Contracts (Base Sepolia)\n\n| Contract | Address |\n|----------|---------|\n| AegisEscrow | [`0x8e013cf23f11168B62bA2600d99166507Cbb4aAC`](https://sepolia.basescan.org/address/0x8e013cf23f11168B62bA2600d99166507Cbb4aAC) |\n| AegisDispute | [`0x9Cbe0bf5080568F56d61F4F3ef0f64909898DcB2`](https://sepolia.basescan.org/address/0x9Cbe0bf5080568F56d61F4F3ef0f64909898DcB2) |\n| AegisTreasury | [`0xCd2a996Edd6Be2992063fD2A41c0240D77c9e0AA`](https://sepolia.basescan.org/address/0xCd2a996Edd6Be2992063fD2A41c0240D77c9e0AA) |\n| AegisJobFactory | [`0xD6a9fafA4d1d233075D6c5de2a407942bdc29dbF`](https://sepolia.basescan.org/address/0xD6a9fafA4d1d233075D6c5de2a407942bdc29dbF) |\n\n## Quick Start\n\n### For AI Agents (MCP Server)\n\nThe fastest way to integrate — any MCP-compatible agent (Claude, Gemini, GPT) can use AEGIS autonomously.\n\n```bash\nnpm install @aegis-protocol/mcp-server\n```\n\n11 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`\n\nSee [`mcp/README.md`](mcp/README.md) for configuration and usage.\n\n### For Developers (TypeScript SDK)\n\n```bash\nnpm install @aegis-protocol/sdk @aegis-protocol/types\n```\n\n```typescript\nimport { AegisClient } from '@aegis-protocol/sdk';\n\nconst client = AegisClient.create({\n  chain: 'base-sepolia',\n  rpcUrl: process.env.RPC_URL,\n});\n\n// Check an agent's reputation before transacting\nconst reputation = await client.erc8004.reputation.getSummary(agentId);\n\n// Create an escrow job\nconst job = await client.escrow.createJob({\n  clientAgentId: 1n,\n  providerAgentId: 2n,\n  amount: 50_000000n, // 50 USDC (6 decimals)\n  jobSpecURI: 'ipfs://Qm...',\n  jobSpecHash: '0x...',\n  validatorAddress: '0x...',\n  deadlineSeconds: 86400, // 24 hours\n});\n```\n\n### For Developers (LangChain / LangGraph)\n\n```bash\nnpx -y pnpm@9.15.4 -C sdk --filter @aegis-protocol/examples langchain-agent -- \"Check agent 1 reputation and summarize escrow risk.\"\n```\n\nLangChain tool adapters are available in `sdk/packages/langchain` and can be imported as:\n\n```typescript\nimport { createAegisLangChainTools } from \"@aegis-protocol/langchain\";\n```\n\nThe native LangChain adapter now includes the advisory entry point `aegis_should_i_escrow` plus settlement support, so the agent-first funnel matches MCP, ElizaOS, and Virtuals.\n\n### For Developers (CrewAI)\n\nInstall Python dependencies (one-time):\n\n```bash\npython3 -m pip install crewai mcp\n```\n\nRun the CrewAI + MCP example:\n\n```bash\nOPENAI_API_KEY=... python3 sdk/examples/crewai-agent.py \"Check agent 1 reputation and summarize escrow risk.\"\n```\n\nOr through the examples workspace script:\n\n```bash\nnpx -y pnpm@9.15.4 -C sdk --filter @aegis-protocol/examples crewai-agent -- \"Check agent 1 reputation and summarize escrow risk.\"\n```\n\nThe example uses CrewAI's MCP integration (`MCPServerStdio`) to call the published `@aegis-protocol/mcp-server` tools directly.\nWhen `AEGIS_USAGE_LOG_PATH` is set, the example also stamps `AEGIS_USAGE_SOURCE=crewai-example` by default so demo/operator traffic can be attributed in MCP usage logs.\n\n### For Developers (ElizaOS)\n\nRun the ElizaOS example config summary:\n\n```bash\nnpx -y pnpm@9.15.4 -C sdk --filter @aegis-protocol/examples eliza-character\n```\n\nThe ElizaOS plugin package is available in `sdk/packages/elizaos` and can be imported as:\n\n```typescript\nimport { createAegisElizaPlugin } from \"@aegis-protocol/elizaos\";\n```\n\nThe example exports a minimal character/plugin config in `sdk/examples/eliza-character.ts` and includes:\n\n- advisory action entry point: `AEGIS_SHOULD_I_ESCROW`\n- trust and funding checks: `AEGIS_LOOKUP_AGENT`, `AEGIS_CHECK_BALANCE`\n- write-path actions for signer-enabled runtimes: `AEGIS_APPROVE_ESCROW`, `AEGIS_CREATE_JOB`, `AEGIS_SUBMIT_DELIVERABLE`, `AEGIS_SETTLE_JOB`\n\n### For Developers (Virtuals GAME / ACP)\n\nRun the Virtuals config summary:\n\n```bash\nnpx -y pnpm@9.15.4 -C sdk --filter @aegis-protocol/examples virtuals-agent\n```\n\nThe Virtuals adapter package is available in `sdk/packages/virtuals` and can be imported as:\n\n```typescript\nimport {\n  createAegisVirtualsWorker,\n  createAegisVirtualsPrompt,\n  createAegisAcpSchemas,\n  createAegisAcpResources,\n} from \"@aegis-protocol/virtuals\";\n```\n\nThe example exports a minimal Virtuals-ready config in `sdk/examples/virtuals-agent.ts` and includes:\n\n- GAME worker functions for AEGIS advisory/read/write flows\n- ACP custom requirement/deliverable schemas aligned to AEGIS job creation\n- ACP resource entries that point operators back to AEGIS docs/MCP surfaces\n- explicit separation between agent runtime logic and the operator-owned ACP wallet/registry setup\n\n### For Developers (REST API)\n\n```bash\n# Check a job's status\ncurl https://api.aegis-protocol.xyz/jobs/{jobId}\n\n# Query an agent's reputation\ncurl https://api.aegis-protocol.xyz/agents/{agentId}\n\n# Stream real-time events\ncurl https://api.aegis-protocol.xyz/events/stream\n```\n\nSee [`api/`](api/) for full route documentation.\n\n### Build from Source\n\n```bash\n# Install Foundry\ncurl -L https://foundry.paradigm.xyz | bash\nfoundryup\n\n# Install dependencies\nforge install\n\n# Build contracts\nforge build\n\n# Run tests\nforge test -vvv\n\n# Run invariants only\nforge test --match-path \"test/invariants/*\" -vvv\n\n# Gas report\nforge test --gas-report\n```\n\n## Monorepo Structure\n\n```\naegis-protocol/\n├── src/                    # Solidity contracts\n│   ├── AegisEscrow.sol\n│   ├── AegisDispute.sol\n│   ├── AegisTreasury.sol\n│   ├── AegisJobFactory.sol\n│   ├── interfaces/         # ERC-8004 interface definitions\n│   └── libraries/          # AegisTypes shared library\n├── test/                   # Foundry tests (unit, fuzz, invariants)\n├── script/                 # Deploy & E2E demo scripts\n├── sdk/                    # TypeScript SDK monorepo\n│   └── packages/\n│       ├── sdk/            # @aegis-protocol/sdk\n│       ├── langchain/      # @aegis-protocol/langchain\n│       ├── elizaos/        # @aegis-protocol/elizaos\n│       ├── virtuals/       # @aegis-protocol/virtuals\n│       ├── types/          # @aegis-protocol/types\n│       └── abis/           # @aegis-protocol/abis\n├── mcp/                    # MCP Server for AI agents\n├── api/                    # Hono REST API relay server\n├── subgraph/               # The Graph indexer\n└── docs/                   # Architecture & design docs\n```\n\n## Protocol Parameters\n\n| Parameter | Value |\n|-----------|-------|\n| Protocol fee | 2.5% on settlements |\n| Dispute window | 24 hours |\n| Default validation threshold | 70/100 |\n| Min escrow amount | 1 USDC |\n| Max deadline | 30 days |\n| Dispute bond | 10 USDC |\n\n## Tech Stack\n\nSolidity 0.8.24 · Foundry · OpenZeppelin 5.x · Base L2 · USDC · TypeScript · Viem · Hono · The Graph\n\n## Status\n\nAEGIS is on **Base Sepolia testnet**. Mainnet deployment is planned for Q2 2026, pending security audit.\n\n- 217 tests passing (212 Foundry + 5 invariants)\n- TypeScript SDK published on npm\n- MCP Server published on npm and listed in the official MCP Registry\n- ElizaOS plugin package shipped (`sdk/packages/elizaos`)\n- Virtuals GAME/ACP adapter package shipped (`sdk/packages/virtuals`)\n- CrewAI integration example shipped via MCP (`sdk/examples/crewai-agent.py`)\n- REST API and subgraph operational\n- Security audit planned via Sherlock competitive contest\n- Engineering risk tracker maintained at [`docs/operations/ENGINEERING-RISK-TRACKER.md`](docs/operations/ENGINEERING-RISK-TRACKER.md)\n- Reliability runbook maintained at [`docs/operations/RELIABILITY-RUNBOOK.md`](docs/operations/RELIABILITY-RUNBOOK.md)\n\n## Contributing\n\nAEGIS is open source under the MIT License. Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), or the [open issues](https://github.com/im-sham/aegis-protocol/issues).\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 11222,
  "sha": "a0cf4dba3be478f5e4b636940de046f40eb16512fa0dc25dafccb0ec92d7524e",
  "repo_slug": "im-sham/aegis-protocol",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_im_sham_aegis_protocol_23dbf371/readme"
}