Technical Architecture

Stack#

Repo layout#

Contracts#

Details are on Independent Agent Vaults.

Data flow#

1. 1A user deposits test USDG into an agent's vault from the app (approve, then deposit).
2. 2Every 30 seconds the worker loads every agent from the AgentFactory, skipping retired vaults, along with the rules it should trade on: a team-approved change from the indexer's GET /rules/effective if there is one, otherwise the governor's current rules.
3. 3For each agent with deposits whose report interval has passed, the worker resumes from the state in the agent's last Reported note, pulls live data (launch tokens from the Neuron indexer; majors, perps, funding and yields from Hyperliquid and DefiLlama) and decides a move.
4. 4Trades are reported immediately with SimulatedStrategy.report. Holds are reported at most every 15 minutes (HOLD_REPORT_SECONDS, 900) for launch traders and at most hourly for other engines.
5. 5The indexer syncs Reported events every 15 seconds and vault share transfers for depositor counts, then computes returns, charts, win rates and fills.
6. 6The app reads the indexer for performance and reads the vaults directly through wagmi for deposits, balances and positions.

The worker loop#

worker/agent-worker.ts ticks every TICK_SECONDS (30 by default) and never overlaps two ticks. Each tick it refreshes the agent list (every 2 minutes) and approved rules (every minute), runs runAgentTick from src/lib/agents/runtime.ts, logs a heartbeat every 20 ticks, and checks the operator's gas every 120 ticks, warning below 0.0005 ETH. A tick skips an agent when the configured key is not that strategy's operator, the vault is empty, the rate limit has not passed, or its rules fail validation. Shadow mode (AGENT_SHADOW_ENABLED=1) records what an experimental entry gate would have decided, without ever trading on it.

The indexer#

indexer/index.ts creates its Postgres schema, starts the HTTP API and runs a set of independent loops:

The performance endpoints the app uses are GET /agents/live, /agents/performance, /agents/<id>/series, /agents/<id>/history, /agents/race, /agents/fills and /holders/<address>. See Blockchain Indexer.

Frontend data flow#

• Server pages (/agents, /agents/[id]) fetch /agents/live with a 60 second revalidate and merge it into the profiles from src/lib/agents.ts.
• Client widgets poll the indexer (performance every 60 seconds, trade history every 30 seconds).
• Vault state (totalAssets, pricePerShare, fee, cap, minimum, paused, your shares, maxWithdraw, costBasis, USDG balance and allowance) is one multicall, refreshed every 15 seconds.
• src/lib/web3/network.ts picks the network from NEXT_PUBLIC_NEURON_NETWORK: testnet (default, Robinhood Chain testnet as the home chain) or local (anvil, chain 31337).

deployments.json#

npm run sync:contracts copies contracts/deployments/<chainId>.json and the matching .community.json into src/lib/web3/deployments.json, and regenerates src/lib/web3/abis.ts from the Foundry build output. The shape, keyed by chain ID:

{
  "46630": {
    "chainId": 46630,
    "chainKey": "robinhood",
    "usdc": "0x...",
    "usdcIsMock": true,
    "registry": "0x...",
    "feeCollector": "0x...",
    "operator": "0x...",
    "startBlock": 0,
    "vaults": { "<agent-id>": { "vault": "0x...", "strategy": "0x..." } },
    "legacyVaults": { "<agent-id>": [{ "vault": "0x...", "strategy": "0x...", "keepsRecord": true }] },
    "community": { "factory": "0x...", "feeCollector": "0x...", "startBlock": 0 }
  }
}

vaults holds each house agent's current vault; legacyVaults lists older ones, oldest first, which the app treats as withdraw only.

Commands#

npm install
npm run dev              # app on http://localhost:3000, testnet config
npm run typecheck
npm run build
npm run contracts:build  # forge build
npm run contracts:test   # forge unit and fuzz tests

Fully local, with no accounts (needs Foundry):

npm run chain            # anvil on port 8546, chain 31337
npm run deploy:local     # MockUSDC, registry, fee collector, house vaults, factory; syncs the app
npm run dev:local        # app on http://localhost:3100 against the local chain
ALCHEMY_API_KEY=... INDEXER_URL=... NEURON_RPC_URL=http://127.0.0.1:8546 npm run worker

Testnet deploy and services:

npm run deploy:testnet   # Deploy.s.sol on Robinhood Chain testnet, verified on Blockscout, then sync
npm run sync:contracts   # after any deploy or launch script
npm run worker           # needs OPERATOR_PRIVATE_KEY, ALCHEMY_API_KEY, INDEXER_URL
npm run indexer          # needs DATABASE_URL

Other variables you may set: NEXT_PUBLIC_PRIVY_APP_ID, NEXT_PUBLIC_INDEXER_URL, NEXT_PUBLIC_ROBINHOOD_TESTNET_RPC_URL, and on the indexer ANTHROPIC_API_KEY, REALM_LAUNCHER_KEY and REALM_NETWORK. .env.example lists them all; keep keys server-side.

Related#

• Security Model
• Testnet to Mainnet
• Protocol Architecture