|
| 1 | +# AEA Protocol - Autonomous Economic Agents |
| 2 | + |
| 3 | +A comprehensive on-chain protocol for human-AI economic coordination, written in OVSM LISP and compiling to Solana sBPF bytecode. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The AEA (Autonomous Economic Agents) Protocol enables: |
| 8 | + |
| 9 | +- **Identity Registry**: Humans and AI agents register on-chain with staked collateral |
| 10 | +- **Service Marketplace**: Providers list services, buyers create escrow-protected orders |
| 11 | +- **Reputation System**: Track record builds trust through successful transactions |
| 12 | +- **Autonomous Trading**: Agents can bid, negotiate, and trade without human intervention |
| 13 | +- **DAO Governance**: Stake-weighted voting on protocol parameters |
| 14 | + |
| 15 | +## Architecture |
| 16 | + |
| 17 | +``` |
| 18 | +┌─────────────────────────────────────────────────────────────────────────────┐ |
| 19 | +│ AEA PROTOCOL SUITE │ |
| 20 | +├─────────────────────────────────────────────────────────────────────────────┤ |
| 21 | +│ │ |
| 22 | +│ ┌─────────────────────┐ ┌──────────────────────┐ ┌──────────────────┐│ |
| 23 | +│ │ ON-CHAIN PROGRAMS │ │ OFF-CHAIN SCRIPTS │ │ TOOLING ││ |
| 24 | +│ │ (Compile to sBPF) │ │ (OVSM Interpreter) │ │ ││ |
| 25 | +│ ├─────────────────────┤ ├──────────────────────┤ ├──────────────────┤│ |
| 26 | +│ │ │ │ │ │ ││ |
| 27 | +│ │ aea_protocol.ovsm │ │ aea_agent_brain.ovsm│ │ IDL JSON files ││ |
| 28 | +│ │ - Identity mgmt │ │ - AI decision layer │ │ - TypeScript ││ |
| 29 | +│ │ - Service registry │ │ - Risk assessment │ │ client gen ││ |
| 30 | +│ │ - Order escrow │ │ - Opportunity scan │ │ ││ |
| 31 | +│ │ - Reputation │ │ │ │ validate- ││ |
| 32 | +│ │ │ │ aea_game_theory.ovsm│ │ instruction ││ |
| 33 | +│ │ aea_negotiation │ │ - Nash equilibrium │ │ - Debug txs ││ |
| 34 | +│ │ .ovsm │ │ - Price strategy │ │ ││ |
| 35 | +│ │ - Bidding system │ │ - Market analysis │ │ ││ |
| 36 | +│ │ - Counter-offers │ │ │ │ ││ |
| 37 | +│ │ - Auto-accept │ │ aea_economics_tests │ │ ││ |
| 38 | +│ │ │ │ .ovsm │ │ ││ |
| 39 | +│ │ aea_governance │ │ - Token economics │ │ ││ |
| 40 | +│ │ .ovsm │ │ - Staking tests │ │ ││ |
| 41 | +│ │ - DAO proposals │ │ - Slashing tests │ │ ││ |
| 42 | +│ │ - Voting │ │ │ │ ││ |
| 43 | +│ │ - Execution │ │ │ │ ││ |
| 44 | +│ │ │ │ │ │ ││ |
| 45 | +│ └─────────────────────┘ └──────────────────────┘ └──────────────────┘│ |
| 46 | +│ │ |
| 47 | +└─────────────────────────────────────────────────────────────────────────────┘ |
| 48 | +``` |
| 49 | + |
| 50 | +## Module Descriptions |
| 51 | + |
| 52 | +### 1. `aea_protocol.ovsm` - Core Protocol (On-Chain) |
| 53 | + |
| 54 | +The foundation layer providing identity, services, and escrow functionality. |
| 55 | + |
| 56 | +**Discriminator Range**: 0-65 |
| 57 | + |
| 58 | +| Discriminator | Instruction | Description | |
| 59 | +|--------------|-------------|-------------| |
| 60 | +| 0 | `initializeProtocol` | Deploy protocol config | |
| 61 | +| 10 | `registerUser` | Register human participant (free) | |
| 62 | +| 11 | `registerAgent` | Register AI agent (requires stake) | |
| 63 | +| 12 | `registerProvider` | Register service provider | |
| 64 | +| 13 | `registerValidator` | Register dispute validator | |
| 65 | +| 14 | `updateProfile` | Update participant metadata | |
| 66 | +| 15 | `startCooldown` | Begin unstaking cooldown | |
| 67 | +| 40 | `createOrder` | Create service order with escrow | |
| 68 | +| 41 | `acceptOrder` | Provider accepts order | |
| 69 | +| 43 | `confirmDelivery` | Buyer confirms receipt | |
| 70 | +| 44 | `cancelOrder` | Buyer cancels before acceptance | |
| 71 | +| 45 | `refundOrder` | Provider refunds | |
| 72 | +| 50 | `openDispute` | Open arbitration dispute | |
| 73 | +| 51 | `resolveDispute` | Validator resolves dispute | |
| 74 | +| 61 | `slashParticipant` | Reduce stake for bad behavior | |
| 75 | +| 62 | `suspendParticipant` | Temporarily disable participant | |
| 76 | + |
| 77 | +**Participant Types**: |
| 78 | +- `User (0)`: Human, no staking required |
| 79 | +- `Agent (1)`: AI agent, must stake $AEA tokens |
| 80 | +- `Provider (2)`: Service provider (human or agent) |
| 81 | +- `Validator (3)`: Dispute arbitrator, high stake |
| 82 | + |
| 83 | +### 2. `aea_negotiation.ovsm` - Autonomous Trading (On-Chain) |
| 84 | + |
| 85 | +Agent-to-agent bidding and negotiation system. |
| 86 | + |
| 87 | +**Discriminator Range**: 70-89 |
| 88 | + |
| 89 | +| Discriminator | Instruction | Description | |
| 90 | +|--------------|-------------|-------------| |
| 91 | +| 70 | `createBid` | Post buy bid with escrowed collateral | |
| 92 | +| 71 | `createOffer` | Post sell offer | |
| 93 | +| 72 | `counterBid` | Respond with counter-offer | |
| 94 | +| 73 | `acceptBid` | Accept a bid/offer | |
| 95 | +| 74 | `rejectBid` | Explicitly reject | |
| 96 | +| 75 | `cancelBid` | Cancel own bid | |
| 97 | +| 76 | `claimExpiredBid` | Reclaim expired collateral | |
| 98 | +| 80 | `createAutoAcceptRule` | Set auto-accept parameters | |
| 99 | +| 83 | `triggerAutoAccept` | Execute auto-accept match | |
| 100 | + |
| 101 | +**Features**: |
| 102 | +- Escrowed collateral on all bids |
| 103 | +- Counter-offer chains (up to 10 depth) |
| 104 | +- Auto-accept rules for hands-free trading |
| 105 | +- 24-hour default bid expiry |
| 106 | + |
| 107 | +### 3. `aea_governance.ovsm` - DAO Control (On-Chain) |
| 108 | + |
| 109 | +Decentralized governance for protocol parameters. |
| 110 | + |
| 111 | +**Discriminator Range**: 90-109 |
| 112 | + |
| 113 | +| Discriminator | Instruction | Description | |
| 114 | +|--------------|-------------|-------------| |
| 115 | +| 90 | `initializeGovernance` | Deploy governance config | |
| 116 | +| 92 | `createProposal` | Submit new proposal | |
| 117 | +| 94 | `transitionToVoting` | Move from discussion to voting | |
| 118 | +| 95 | `castVote` | Cast stake-weighted vote | |
| 119 | +| 97 | `delegateVotes` | Delegate voting power | |
| 120 | +| 99 | `finalizeProposal` | Finalize after voting ends | |
| 121 | +| 100 | `executeProposal` | Execute passed proposal | |
| 122 | +| 101 | `guardianVeto` | Emergency veto by guardian | |
| 123 | + |
| 124 | +**Proposal Lifecycle**: |
| 125 | +1. **Discussion** (2 days): Community deliberation |
| 126 | +2. **Voting** (5 days): Stake-weighted votes |
| 127 | +3. **Timelock** (2 days): Delay before execution |
| 128 | +4. **Execution**: Anyone can trigger |
| 129 | + |
| 130 | +### 4. `aea_agent_brain.ovsm` - AI Decision Layer (Off-Chain) |
| 131 | + |
| 132 | +Interpreter script for autonomous agent reasoning. |
| 133 | + |
| 134 | +**Components**: |
| 135 | +- **Opportunity Scanner**: Filter bids by capabilities and risk |
| 136 | +- **Counterparty Analyzer**: Evaluate reputation and history |
| 137 | +- **Risk Assessor**: Expected value and worst-case analysis |
| 138 | +- **Decision Engine**: Accept/reject/counter recommendations |
| 139 | +- **Execution Planner**: Transaction batching and gas optimization |
| 140 | + |
| 141 | +**Usage**: |
| 142 | +```bash |
| 143 | +osvm ovsm run aea_agent_brain.ovsm |
| 144 | +``` |
| 145 | + |
| 146 | +### 5. `aea_game_theory.ovsm` - Strategic Reasoning (Off-Chain) |
| 147 | + |
| 148 | +Multi-agent competition analysis for market equilibrium. |
| 149 | + |
| 150 | +**Concepts**: |
| 151 | +- Prisoner's Dilemma in pricing |
| 152 | +- Nash equilibrium detection |
| 153 | +- Tit-for-Tat with forgiveness |
| 154 | +- Market collusion detection |
| 155 | +- Stackelberg leader/follower dynamics |
| 156 | + |
| 157 | +### 6. `aea_economics_tests.ovsm` - Test Suite (Off-Chain) |
| 158 | + |
| 159 | +Comprehensive tests for token economics (24/24 passing). |
| 160 | + |
| 161 | +## Account Layouts |
| 162 | + |
| 163 | +### Participant Account (256 bytes) |
| 164 | + |
| 165 | +``` |
| 166 | +offset 0: u8 participant_type (0=User, 1=Agent, 2=Provider, 3=Validator) |
| 167 | +offset 1: u8 status (0=Inactive, 1=Active, 2=Cooldown, 3=Slashed, 4=Suspended) |
| 168 | +offset 8: u64 stake_amount |
| 169 | +offset 16: i64 reputation_score |
| 170 | +offset 24: u64 tasks_completed |
| 171 | +offset 32: u64 tasks_failed |
| 172 | +offset 40: u64 disputes_won |
| 173 | +offset 48: u64 disputes_lost |
| 174 | +offset 56: u64 total_earned |
| 175 | +offset 64: u64 total_spent |
| 176 | +offset 72: u64 registered_at |
| 177 | +offset 80: u64 last_active |
| 178 | +offset 88: u64 cooldown_start |
| 179 | +offset 96: [32] authority_pubkey |
| 180 | +offset 128: [64] endpoint (HTTP/mesh address) |
| 181 | +offset 192: [32] display_name |
| 182 | +offset 224: [32] capabilities_hash |
| 183 | +``` |
| 184 | + |
| 185 | +### Order/Escrow Account (256 bytes) |
| 186 | + |
| 187 | +``` |
| 188 | +offset 0: u8 status (0=Created, 1=Accepted, 2=InProgress, 3=Delivered, |
| 189 | + 4=Completed, 5=Disputed, 6=Refunded, 7=Cancelled) |
| 190 | +offset 8: u64 order_id |
| 191 | +offset 16: u64 service_id |
| 192 | +offset 24: u64 amount |
| 193 | +offset 32: u64 fee_amount |
| 194 | +offset 40: u64 created_at |
| 195 | +offset 48: u64 accepted_at |
| 196 | +offset 56: u64 delivered_at |
| 197 | +offset 64: u64 deadline |
| 198 | +offset 72: u64 dispute_deadline |
| 199 | +offset 80: [32] buyer_pubkey |
| 200 | +offset 112: [32] provider_pubkey |
| 201 | +offset 144: [64] request_hash (IPFS CID) |
| 202 | +offset 208: [64] delivery_hash (IPFS CID) |
| 203 | +``` |
| 204 | + |
| 205 | +## Compilation |
| 206 | + |
| 207 | +Compile OVSM source to Solana sBPF: |
| 208 | + |
| 209 | +```bash |
| 210 | +# Compile core protocol |
| 211 | +osvm ovsm compile aea_protocol.ovsm -o aea_protocol.so --verify |
| 212 | + |
| 213 | +# Compile negotiation module |
| 214 | +osvm ovsm compile aea_negotiation.ovsm -o aea_negotiation.so --verify |
| 215 | + |
| 216 | +# Compile governance module |
| 217 | +osvm ovsm compile aea_governance.ovsm -o aea_governance.so --verify |
| 218 | +``` |
| 219 | + |
| 220 | +## IDL Generation |
| 221 | + |
| 222 | +Generate Anchor-compatible IDL for TypeScript clients: |
| 223 | + |
| 224 | +```bash |
| 225 | +# Generate IDL |
| 226 | +osvm ovsm idl aea_protocol.ovsm -o idl/aea_protocol.json |
| 227 | + |
| 228 | +# Validate instruction data against IDL |
| 229 | +osvm ovsm validate-instruction idl/aea_protocol.json 0x0a 01000000 |
| 230 | +``` |
| 231 | + |
| 232 | +**Generated IDL Files**: |
| 233 | +- `idl/aea_protocol.json` - 16 instructions |
| 234 | +- `idl/aea_negotiation.json` - 9 instructions |
| 235 | +- `idl/aea_governance.json` - 8 instructions |
| 236 | + |
| 237 | +## Economic Model |
| 238 | + |
| 239 | +### Staking Requirements |
| 240 | + |
| 241 | +| Participant Type | Minimum Stake | Purpose | |
| 242 | +|-----------------|---------------|---------| |
| 243 | +| User | 0 | Free to register | |
| 244 | +| Agent | 10 tokens | Skin in the game | |
| 245 | +| Provider | 25 tokens | Service guarantee | |
| 246 | +| Validator | 100 tokens | Dispute authority | |
| 247 | + |
| 248 | +### Fees |
| 249 | + |
| 250 | +- **Escrow Fee**: 1% (100 basis points) |
| 251 | +- **Bid Creation Fee**: 0.1% (10 basis points) |
| 252 | +- **Dispute Resolution**: Funded from slashed stakes |
| 253 | + |
| 254 | +### Reputation |
| 255 | + |
| 256 | +- Starts at 0, can go negative |
| 257 | +- +10 per successful task |
| 258 | +- -25 per failed task |
| 259 | +- -50 per lost dispute |
| 260 | +- Weighted by stake for credibility |
| 261 | + |
| 262 | +### Cooldown & Slashing |
| 263 | + |
| 264 | +- **Cooldown Period**: 7 days to withdraw stake |
| 265 | +- **Dispute Window**: 48 hours after delivery |
| 266 | +- **Slash Amount**: Up to 50% of stake per offense |
| 267 | + |
| 268 | +## Integration with BBS |
| 269 | + |
| 270 | +AEA Protocol integrates with the OSVM BBS system for communication: |
| 271 | + |
| 272 | +- Agents register HTTP endpoints or Meshtastic mesh node IDs |
| 273 | +- Messages exchanged via BBS federation |
| 274 | +- Service requests can reference BBS message IDs |
| 275 | +- Off-grid operation possible via LoRa mesh |
| 276 | + |
| 277 | +## Example Workflow |
| 278 | + |
| 279 | +### 1. Agent Registration |
| 280 | + |
| 281 | +```lisp |
| 282 | +;; On-chain: Register as AI agent |
| 283 | +(define participant_ptr (account-data-ptr 1)) |
| 284 | +(mem-store1 participant_ptr 1) ;; Set type = Agent |
| 285 | +(mem-store1 (+ participant_ptr 1) 1) ;; Set status = Active |
| 286 | +(mem-store (+ participant_ptr 8) 10000000000) ;; Stake 10 tokens |
| 287 | +``` |
| 288 | + |
| 289 | +### 2. Service Listing |
| 290 | + |
| 291 | +```lisp |
| 292 | +;; Provider creates service listing |
| 293 | +(define service_ptr (account-data-ptr 1)) |
| 294 | +(mem-store1 service_ptr 1) ;; is_active = true |
| 295 | +(mem-store (+ service_ptr 16) 5000000000) ;; price = 5 tokens |
| 296 | +``` |
| 297 | + |
| 298 | +### 3. Autonomous Bid |
| 299 | + |
| 300 | +```lisp |
| 301 | +;; Agent evaluates opportunity (off-chain) |
| 302 | +(define opportunity (analyze-opportunity service)) |
| 303 | +(if (> (get opportunity :expected_value) 0.15) |
| 304 | + (recommend-accept) |
| 305 | + (recommend-counter (- (get service :price) 1000000000))) |
| 306 | +``` |
| 307 | + |
| 308 | +## Testing |
| 309 | + |
| 310 | +Run the economics test suite: |
| 311 | + |
| 312 | +```bash |
| 313 | +osvm ovsm run aea_economics_tests.ovsm |
| 314 | +``` |
| 315 | + |
| 316 | +Expected output: `✅ All 24 tests passing` |
| 317 | + |
| 318 | +## Files |
| 319 | + |
| 320 | +| File | Size | Type | Description | |
| 321 | +|------|------|------|-------------| |
| 322 | +| `aea_protocol.ovsm` | 63 KB | On-chain | Core identity & escrow | |
| 323 | +| `aea_negotiation.ovsm` | 35 KB | On-chain | Bidding & negotiation | |
| 324 | +| `aea_governance.ovsm` | 40 KB | On-chain | DAO governance | |
| 325 | +| `aea_agent_brain.ovsm` | 24 KB | Off-chain | AI decision layer | |
| 326 | +| `aea_game_theory.ovsm` | 18 KB | Off-chain | Strategic reasoning | |
| 327 | +| `aea_economics_tests.ovsm` | 16 KB | Test | Economics test suite | |
| 328 | +| `idl/aea_protocol.json` | 8.5 KB | IDL | TypeScript interface | |
| 329 | +| `idl/aea_negotiation.json` | 4.4 KB | IDL | TypeScript interface | |
| 330 | +| `idl/aea_governance.json` | 3.9 KB | IDL | TypeScript interface | |
| 331 | + |
| 332 | +## License |
| 333 | + |
| 334 | +MIT License - See project root for details. |
0 commit comments