Agentic Crypto Swarm Prototype

A hierarchical multi-agent system for machine-paid on-chain value creation — no trading, no speculation. Defaults: Celo Sepolia (11142220) for development; production settlement on Celo mainnet (42220). Public inbound sales use Base mainnet USDC (x402 facilitator seller, eip155:8453) and XRPL mainnet XRP (T54, xrpl:0) once HTTPS URLs are set — see documentation/PUBLIC_MAINNET_OPERATIONS.md. Local Anvil (31337) for zero-faucet testing.

Layout: long-form manuals live under documentation/ (see documentation/README.md). Generated soak reports, traces, proof bundles, and communication traces live under artifacts/ (see artifacts/README.md). The docs/ folder is reserved for GitHub Pages (index.html, endpoints.json, sitemap, discovery scans linked from the site).

Completed: T54 x402 seller on XRPL

Machine-paid APIs — HTTP 402 — XRP settlement via T54 facilitator (xrpl:0)

All paid / commerce surfaces in this repository

Architecture

Human (seeds ETH + goals)
    │
    ▼
Root Strategist (ERC-4337 smart account)
    │
    ├──► IP-Generator (creates novel oracle/prompt logic)
    ├──► Deployer (deploys/upgrades AgentRevenueService)
    └──► Finance-Distributor (treasury, profit distribution)

• 4 isolated smart accounts with session keys + 0.01 ETH daily cap

• AgentRevenueService.sol — pay-per-query AI service (min 0.001 ETH)

• LangGraph — stateful multi-agent orchestration

• Profit split: 60% human beneficiary, 40% reinvested

Prerequisites

• Foundry

• Python 3.12+

• Node.js 18+

• Ollama for LLM inference. Recommended (low local RAM): cloud models such as kimi-k2.5:cloud — run ollama signin, then ollama pull kimi-k2.5:cloud, keep the Ollama app running, set OLLAMA_MODEL / OLLAMA_BASE_URL=http://127.0.0.1:11434 in .env. Alternative: fully local qwen3.5:9b (~8.7 GiB RAM) or phi3:mini / tinyllama. Direct cloud API: OLLAMA_BASE_URL=https://ollama.com + OLLAMA_API_KEY from ollama.com/settings/keys.

• RPC: set RPC_URL or CELO_SEPOLIA_RPC_URL for Celo Sepolia; Alchemy optional for Base legacy

Setup

1. Clone and install

   git clone https://github.com/Hobie1Kenobi/agentic-crypto-swarm-prototype.git
   cd agentic-crypto-swarm-prototype

2. Environment

   Copy .env.example to .env. Set CHAIN_NAME=celo-sepolia (default) or anvil for local. Optional: RPC_URL, BENEFICIARY_ADDRESS, PIMLICO_API_KEY (Base only). Configure Ollama in .env (OLLAMA_MODEL, OLLAMA_BASE_URL; optional OLLAMA_API_KEY for direct cloud — see Prerequisites).

3. Install dependencies

   .\scripts\ensure-ollama-model.ps1
   .\scripts\install-foundry.ps1

   Restart the terminal so forge is on PATH, then:

   forge install OpenZeppelin/openzeppelin-contracts
   cd packages/wallet && npm install
   cd packages/agents && pip install -r requirements.txt

4. Create agent wallets (saves secrets to .env, updates .gitignore)

   npm run create-accounts

5. Claim testnet CELO (Celo Sepolia)

   • Celo Sepolia Faucet

   • For local runs use npm run simulation:local (no faucet). For legacy Base Sepolia: basefaucet.com, CDP faucet.

Run

Full orchestration (one command): strategist → IP-generator → deployer check → 10-user simulation → finance check (and loop until profit threshold or max steps).

Celo Sepolia public test: Full flow (env → create wallets → deploy → fund → orchestrate → monitor) and troubleshooting: documentation/celo-xrpl/CELO-SEPOLIA-TESTNET.md. Short path: npm run create-accounts → fund deployer → npm run testnet:celo → fund ROOT_STRATEGIST_ADDRESS → npm run orchestrate. Check balances: .\scripts\celo-sepolia-balances.ps1.

Manual deploy then orchestrate:

# 1. Deploy contracts (once)
.\scripts\deploy.ps1 --broadcast
.\scripts\fetch-and-save-addresses.ps1
# Ensure REVENUE_SERVICE_ADDRESS and FINANCE_DISTRIBUTOR_ADDRESS in .env

# 2. Run full orchestration (LangGraph + simulation in one graph)
npm run orchestrate
# or: npm run swarm   (same thing)

Use --max-steps to limit graph steps (default 5), e.g. cd packages/agents && python main.py --max-steps 3.

Run steps separately (optional):

npm run swarm          # LangGraph only (no simulation)
npm run simulation     # 10-user revenue loop only

Simulation: Without REVENUE_SERVICE_ADDRESS it runs in dry-run (LLM only, log to simulation_log.txt). With contract address and a funded key, it sends real fulfillQuery txs.

Local-first test harness (no faucet, repeatable): One command to validate the full system on Anvil:

npm run harness:local

This starts Anvil, deploys the contracts, and runs the 10-user simulation using Anvil’s pre-funded account (10,000 ETH). Report artifacts: simulation_report.json, simulation_report.md. Clean state: npm run harness:local:reset. Simulation-only: npm run simulation:local.

How to Monitor / Claim Profits

• Treasury / finance distributor: see FINANCE_DISTRIBUTOR_ADDRESS in .env

• Celo Sepolia: https://celo-sepolia.blockscout.com/address/<ADDRESS>; Celo mainnet: https://explorer.celo.org/address/<ADDRESS>. Legacy Base: sepolia.basescan.org

• Profit distribution: when finance balance ≥ SIMULATION_PROFIT_THRESHOLD_ETH (default 0.005), simulation sends 60% to BENEFICIARY_ADDRESS and leaves 40% reinvested

How to Run in Production (testnet)

1. Install deps, create agent wallets (npm run create-accounts), fund them with testnet ETH.

2. Deploy contracts: .\scripts\deploy.ps1 --broadcast; set REVENUE_SERVICE_ADDRESS in .env.

3. Fund the payer (e.g. root strategist) with ≥0.01 ETH for 10 queries.

4. Set BENEFICIARY_ADDRESS and optionally FINANCE_DISTRIBUTOR_PRIVATE_KEY for distribution.

5. Run npm run simulation for the 10-user revenue loop; check simulation_log.txt for tx hashes and profit proof.

6. For full 0.05 ETH profit target, set SIMULATION_PROFIT_THRESHOLD_ETH=0.05 and run until finance balance reaches it (or run more queries).

Constraints

• Default testnet: Celo Sepolia (11142220). Production: Celo mainnet (42220). Local: Anvil (31337). Base Sepolia (84532) legacy/optional.

• No trading/DEX/speculation — revenue from usage fees only

• Ethical constitution — no gambling, illegal content; sustainable compute

Production readiness

For Celo mainnet launch: deployment, security, operations, secrets, monitoring, wallets, upgrades, economic risk, abuse/spam, rate limits, accounting, and DAO recommendation are in documentation/operations/PRODUCTION-READINESS.md. v1 minimal launch: deploy without DAO; keep revenue contract owned by EOA or multisig.

Compute marketplaces and DAO

• T54 XRPL x402 seller (completed): Multi-SKU HTTP seller, XRP settlement, discovery — see Completed: T54 x402 seller on XRPL at the top of this README.

• x402 API: npm run api:402 — HTTP 402 pay-per-query; client pays to AgentRevenueService, retries with X-Payment-Tx-Hash, gets LLM response.

• Compute marketplace: Deploy includes ComputeMarketplace. Run miner: npm run miner (POST /task); run validator: npm run validator (scores miners, submitScores). Fund the contract with CELO and call distributeRewards() to pay miners.

• Multi-rail agent commerce: Celo (private settlement) + XRPL (machine payments) + Olas (public demand). See documentation/celo-xrpl/XRPL_PAYMENTS.md.

  • XRPL — Machine-native payments rail (XRP on testnet; live-proven)

  • Celo — Private settlement rail (task lifecycle, escrow, withdrawals on Celo Sepolia)

  • Live proof: live_xrpl_to_celo_proof_report.md documents a successful end-to-end run with verifiable XRPL + Celo tx hashes.

• Public marketplace adapter (Olas / Mech): See documentation/operations/PUBLIC-ADAPTER.md. This repo supports a dual-chain operating model:

  • Private settlement (Celo Sepolia): MARKET_MODE=private_celo

  • Live/public Olas attempts (Gnosis): MARKET_MODE=public_olas (requires Gnosis config + mechx)

  • Hybrid (Gnosis intake → Celo settlement): MARKET_MODE=hybrid

  • XRPL payment rail: PAYMENT_RAIL_MODE=mock_payment or xrpl_x402_payment; run python scripts/run-multi-rail-demo.py --force-hybrid

  • Replay-only hybrid is supported via documentation/examples/olas_request_replay_example.json

  • Reports: olas_preflight_report.json, olas_env_checklist.md, olas_live_attempt_report.(md|json), hybrid_gnosis_celo_report.(md|json), multi_rail_run_report.(md|json), live_xrpl_to_celo_proof_report.(md|json), communication_trace.(md|json)

• DAO (optional/advanced): After deploy, npm run deploy:dao deploys SwarmGovernanceToken, Timelock, Governor and transfers AgentRevenueService ownership to the Timelock. Recommended only after validating core flow; see PRODUCTION-READINESS.md and COMPUTE_MARKETPLACES_AND_DAOS.md.

Deliverables

• Repo: Monorepo with contracts/, packages/wallet/, packages/agents/, script/, scripts/

• .cursor/rules: AGENTS.md with tech stack and conventions

• Deployed addresses: After .\scripts\deploy.ps1 --broadcast, set REVENUE_SERVICE_ADDRESS and FINANCE_DISTRIBUTOR_ADDRESS in .env (see .env.example)

• Simulation log: npm run simulation writes simulation_log.txt with tx hashes and profit summary

• Tests: npm run test runs Forge contract tests (32 tests) and Python agent tests (25 tests). Contracts: npm run test:contracts. Agents: npm run test:agents.

License

MIT