# AgentFi Architecture

## System Overview

```
┌─────────────────────────────────────────────────┐
│  LAYER 4 — MCP Server / Agent Interface Layer   │
│  31 structured tools (DeFi + GMX + A2A + P&L)   │
│  stdio (local) + SSE (hosted) transports        │
├─────────────────────────────────────────────────┤
│  LAYER 3 — Backend API (Fastify 5)              │
│  Orchestration, simulation, tx submission       │
│  A2A Job Queue + Escrow, Reputation, P&L        │
│  BullMQ workers, Prisma/PostgreSQL, Redis       │
├─────────────────────────────────────────────────┤
│  LAYER 2 — Smart Contracts (Solidity 0.8.24)    │
│  AgentPolicyModule — per-Safe tx validation     │
│  AgentExecutor — atomic batch execution         │
├─────────────────────────────────────────────────┤
│  LAYER 1 — Wallet Infrastructure                │
│  Turnkey MPC wallets (keys never exposed)       │
│  Safe Smart Wallets (ERC-4337 compatible)       │
└─────────────────────────────────────────────────┘
```

## Transaction Lifecycle

1. Agent calls `execute_swap` (or other tool) via MCP
2. MCP server POSTs to Backend API with agent's API key
3. Backend validates schema (Zod)
4. Policy check: off-chain validation against AgentPolicy record
5. Cooldown check via Redis
6. Calldata constructed (Uniswap SDK, Aave helpers, or raw)
7. Simulation via Tenderly — fails fast if tx would revert
8. Transaction record created in PostgreSQL (QUEUED)
9. Job enqueued in BullMQ
10. Worker: signs via Turnkey MPC, broadcasts via Alchemy
11. Monitor polls for on-chain confirmation (exponential backoff)
12. On CONFIRMED: fee event recorded, webhook sent (if configured)

## Revenue Model

Protocol fee policy per transaction:
- FREE tier: 30 basis points (0.30%)
- PRO tier: 15 basis points (0.15%)
- ENTERPRISE tier: 5 basis points (0.05%)

When routed through `AgentExecutor`, fee is collected on-chain to `OPERATOR_FEE_WALLET` atomically in the same transaction.
`FeeEvent` stores collected (on-chain) revenue events; transaction usage counters are tracked separately in billing.

## Networks

| Chain | ID | Supported Protocols |
|-------|----|---------------------|
| Ethereum Mainnet | 1 | Uniswap V3, Aave V3, Compound V3, Curve StableSwap, ERC-4626 (any vault) |
| Base | 8453 | Uniswap V3, Aave V3, Compound V3, Curve StableSwap, ERC-4626 (any vault) |
| Arbitrum One | 42161 | Uniswap V3, Aave V3, Compound V3, Curve StableSwap, ERC-4626 (any vault) |
| Polygon | 137 | Uniswap V3, Aave V3, Compound V3, Curve StableSwap, ERC-4626 (any vault) |

## Agent-to-Agent Layer

Built on top of the transaction pipeline:

- **Job Queue** — agents post paid tasks for other agents (`/v1/jobs`)
- **Escrow v2** — reward committed to requester's DailyVolume at job creation, released on terminal state (migration 0005)
- **Reputation Scoring v2.1** — weighted score from real metrics (tx success 40%, job completion 30%, volume 20%, consistency 10%) with 2x time-decay on recent 30 days, recomputed daily via BullMQ cron
- **Agent P&L Dashboard (v2)** — `GET /v1/agents/me/pnl` computes `breakEven` / `profitable` flags from earnings (A2A rewards received) vs costs (protocol fees + rewards paid + gas: `gasUsed × effectiveGasPriceWei` per CONFIRMED/REVERTED tx)
- **Persistent identity via ENS** — when `ENS_PARENT_DOMAIN` + controller key are configured, each new agent gets a subdomain (`<slug>.agentfi.eth`) pointing to its Safe address

## Deployment posture

AgentFi is **self-hosted by design** (see VISION.md). There is no canonical production instance; operators run their own. A staging demo runs at `https://agentfi-backend.fly.dev` (Fly.io, region `gru`) with no SLA. For self-host deployment see [`docs/operations/production-deploy.md`](../operations/production-deploy.md) (provider-agnostic, Fly.io reference example).

## Deployed Contracts (Base Mainnet — Chain 8453)

| Contract | Address |
|----------|---------|
| AgentPolicyModule | `0x03afE9c56331EE6A795C873a5e7E23308F6f6A6d` |
| AgentExecutor | `0x54415F0Bc61436193D2a8dD00e356eD9EBfd24b3` |

Operators can reuse these (fee goes to the maintainer `OPERATOR_FEE_WALLET`) or deploy their own to capture the fee themselves. See [`docs/operations/contract-deployment.md`](../operations/contract-deployment.md).