Protocol docs

Overview

Tokenized AI trading agents for stock tokens on Robinhood Chain (chain ID 4663). Every AI agent is a NAV-backed ERC-20 vault. Users deposit USDG and receive shares whose value tracks the agent's portfolio of tokenized equities (NVDA, AAPL, SPY, …), priced onchain via per-asset Chainlink feeds.

The AI — an offchain LLM loop — executes trades, but never has unrestricted power: every order must pass the shared TradeGuard risk engine plus an onchain oracle-price slippage bound.

User ──deposit USDG──▶ AgentVault ──shares──▶ User
                         │  ▲
      AI (operator) ─────┘  │ executeTrade (whitelisted router only)
                         │  │
                         ▼  │
                 TradeGuard + PriceOracle (Chainlink, sequencer + staleness checks)

Contracts

Contract	Role
AgentVault	ERC-20 share vault per agent. Deposit/withdraw USDG, NAV via oracle, operator trades, 20% performance fee (high-water mark), drawdown peak tracking, inflation-guard dead shares.
AgentFactory	Deploys vaults and registers them in the registry.
AgentRegistry	Agent metadata + discovery (creator, vault, strategy URI, active flag).
TradeGuard	Shared risk rules: token whitelist, max trade size, position cap, max drawdown halt, protocol pause.
PriceOracle	Chainlink wrapper: 1e18-normalized USD prices, L2 sequencer uptime check, per-feed staleness heartbeat.

Security model

• Operator is sandboxed — executeTrade is the only trading entry point. It enforces guard rules, whitelisted venues, an oracle-implied slippage floor, and post-trade position caps. The AI cannot rug, over-lever, or trade unlisted assets.
• Fees — 20% performance fee above the high-water mark, paid in USDG to the vault owner at withdrawal. No management fee in v1.
• NAV integrity — feed prices include the ERC-8056 corporate-action multiplier (dividends/splits), so no manual multiplier handling. Staleness + sequencer checks reject bad prices. Dead shares guard against first-depositor inflation.
• Withdrawal — USDG-only; reverts when the vault is illiquid (the keeper must first sell equities; a permissionless liquidate path is a future iteration).

Deployment

Mainnet broadcast is done by the protocol owner, never by an agent:

export PRIVATE_KEY=<your_key>
export RPC=https://rpc.mainnet.chain.robinhood.com
forge script script/Deploy.s.sol:Deploy --rpc-url $RPC --broadcast

Post-deploy configuration:

1. oracle.setFeed(<TOKEN>, <FEED>, 0) for every stock token — feed addresses from the Chainlink Robinhood page.
2. guard.setWhitelistedToken(<USDG>, true) + every stock token.
3. guard.setWhitelistedRouter(<router>, true) — Uniswap V3 router / Rialto propAMM.
4. oracle.setSequencerUptimeFeed(<feed>) — recommended on L2.

Offchain AI agent

Module	Role
chain.py	Web3 client: vault state, signed executeTrade submission.
prices.py	RHJ REST API + onchain feed reads.
signals.py	Decision engine: LLMProvider (DeepSeek, Gemini fallback) + HeuristicProvider (SMA crossover, offline).
executor.py	Offchain guardrail mirror (watchlist, max trade, caps) before signing; dry-run or live.
keeper.py	NAV/drawdown monitor + liquidity sweeps.
cli.py	status, run, keeper, sweep, deposit, move-price, tokens.

End-to-end demo (local anvil, reproducible): ./agent/e2e_demo.sh — verified BUY on uptrend and SELL on downtrend with real onchain transactions (status 1), plus LLM-decided live trades and keeper liquidity sweeps.

FAQ