Architecture

This chapter is the map for engineers: every contract Levee deploys, the programs that run around them, and the two paths data takes, a write from your wallet to a contract and a read from the chain back to a page. Every other chapter zooms into one part of it. Every name in code can be found with a search of the repository.

The map

Read it from the top. The browser, the API and its bots, the indexer and the signer sit off chain, and all of them reach the contracts through the Robinhood Chain RPC. On chain, the contracts fall into two families with separate histories. The liquidity-management contracts in contracts/src work on top of Uniswap v3 and v4. The venue in contracts/src/venue is Levee's own set of pools, router and fee path. They meet at one point: FeeRouter collects the fees of the first family and names the venue's FeeCollector as its treasury, so whatever referrers do not earn joins the pools' protocol fees on the way to the $LEVEE buyback.

Nothing in contracts/src is behind a proxy, and nothing can be upgraded. The liquidity-management contracts have no owner and no admin function. In the venue, ProtocolConfig, AssetRegistry, FeeCollector and BuybackV2 are Ownable2Step. Their owner can tune parameters, steer fees and pause swaps and new liquidity. Withdrawals never check the pause. Security model lists every power that key has.

Contracts by job

Each table names who creates the contract, what it is for and what it calls. "deployAll" means the contract is deployed once by LeveeWiring.deployAll. "deployVenue" means the venue half of that same call.

Position tools

Details: One-token deposits, Limit orders, Position automation.

Vaults

Details: Vaults, Hedged vaults, Structured notes.

Launch tracking and pre-market perps

Details: Graduation and pre-market perps.

Levee pools and routing

Both hooks and every DLMM pair send the protocol share of each fee straight to FeeCollector. Details: Levee pools, Swaps and routing.

Pool vaults and launches

Details: Levee pools, Launch a token.

Fees and $LEVEE

Details: Buyback and burn, Fees and referrals.

Who holds a key

DeployRobinhood refuses to run if the owner, hedger or a funder is the deployer, if a funder is the hedger, the keeper or the owner, or if the two hedged vaults share a funder.

The programs off chain

Indexer, API and bots covers the first four in depth; Perpetuals covers the signer.

A write, from click to block

Every button that changes chain state calls useWrite().run(...) in apps/web/lib/tx.ts. There is no second path.

1. 01
   Gate

   canWrite checks for a connected wallet, chain 4663 (development builds also allow 31337) and a deployment manifest. If one is missing, the button says which.
2. 02
   Simulate

   The hook runs simulateContract, an eth_call from your address. A revert stops here: it costs nothing and your wallet never opens.
3. 03
   Sign and send

   Your wallet signs the simulated request and sends it through the RPC. A toast links the transaction on the explorer.
4. 04
   Refresh

   The query keys the write affects are refetched at 1.5 s, 4 s and 10 s, the time the indexer needs to see the new logs.

For anything a transaction must get exactly right, the browser reads the chain directly instead of asking the API: balances, allowances, vault previews, router quotes, the active DLMM bin. The API never sends a transaction for a user. Its POST routes store a signed Idea, forward a signed perp request to the signer, return a mirror plan for your wallet to send, record the contact form or, with the admin secret, recompute points.

A read, from chain to page

1. A page hook in apps/web/lib/data.ts calls a typed fetcher in apps/web/lib/api.ts against NEXT_PUBLIC_API_URL (http://127.0.0.1:8792 by default), with a 15 s stale time and no retry.
2. The API route answers from the indexer (GraphQL documents in src/indexer/queries.ts), from chain reads batched through Multicall3, from market data (Lighter first, then Hyperliquid or Yahoo) or from its database. A cached route keeps its answer for 15 to 60 s.
3. The route maps its own model to the exact shape api.ts declares (routes/wire.ts), and a test fails if either side renames a field.
4. If the API does not answer, a development or staging build shows a fixture with a "Sample data" tag. A production build never does: it shows the empty state and a status notice instead.

The indexer is fed by the chain alone. It subscribes to the Uniswap factory, position manager and PoolManager, to every Levee contract in the manifest, and to the Pons factory, and folds their logs into tables.

Shared packages

@levee/core

Pure TypeScript with no I/O, imported by the web, the API and the indexer. It holds tick maths and range shapes, zap maths, impermanent loss, fee APR, the Seasoned screen (isEstablished), Carry (basis.ts), LP delta and hedge sizing (hedge.ts), keeper policy predictions (policy.ts), note payoffs, DLMM bin maths, the perp request message (perpAuth.ts), slippage, market hours, position sizing and backtests. A number on a card and the number a bot acts on come from the same function.

Two Foundry tests write fixtures when run with WRITE_FIXTURES=true: contracts/fixtures/zap.json, which packages/core/src/zapMath.test.ts asserts the TypeScript port against, and contracts/fixtures/payoff.json, eight points of each StructuredVault.payoffCurve mode that payoff.ts mirrors.

@levee/abi and the manifest

• src/generated/ holds the compiler ABIs of every contract with an off-chain caller. contracts/export-abis.sh writes them, and they are committed, so no package needs Foundry to build.
• src/addresses.ts holds the fixed facts: chain 4663, the public RPC, the Uniswap contracts, tokens, Chainlink feeds, Lighter, Multicall3, Pons and the stock list.
• src/manifest.ts types the deployment manifest and validates it with loadManifest, which names the bad key when it throws.

The manifest is the one file that says where a deployment lives: chainId, deployBlock, the owner, treasury, hedger and funder, each hedged vault's funder (funders), the three vault implementations, addresses (with seed vaults by name) and venue. The API reads it from MANIFEST_PATH, the indexer from PONDER_MANIFEST, the web from apps/web/deployments/manifest.json or NEXT_PUBLIC_MANIFEST_URL. Without one, writes are disabled, the bots stay off, the manifest routes answer empty and the indexer sees only Uniswap.

Deployed addresses

Read from the manifest this site loaded, so the table is always the deployment you are using:

Chain 4663, deployed from block 82,431,214. Each address opens on the explorer.

Deploying the stack

DeployRobinhood.s.sol and DeployLocal.s.sol both call deployAll in contracts/script/LeveeWiring.sol. It never starts a broadcast and never reads the environment, so the same sequence runs under a broadcast, a dry run and a fork test.

1. 01
   The venue

   VenueWiring.deployVenue deploys AssetRegistry, BuybackV2, Router, FeeCollector and ProtocolConfig, then both hooks at CREATE2 addresses whose low bits are their permission flags, then the DLMM, launch and stock-vault contracts. It sets the quotes, lists every stock with default risk parameters and names the hedger as keeper of both vault factories.
2. 02
   Fees

   ReferralRegistry, then FeeRouter with the venue's FeeCollector as its treasury.
3. 03
   Position tools

   Both zaps, RangeOrders and PositionKeeper.
4. 04
   Vaults and launches

   The three vault implementations, then VaultFactory, which takes them as constructor arguments because their combined creation code is over the initcode limit. Then LaunchPipeline and PreMarketPerp.
5. 05
   Seed vaults

   Best effort: the ETH and USDG vaults on WETH/USDG 0.05 %, NVDA and SPY Hedged on each token's deepest WETH pool, Income NVDA and Protected SPY. A missing pool logs a line and skips that vault.
6. 06
   Hand over

   handOver proposes the owner for the four venue admin contracts. Until the owner calls acceptOwnership, the deployer still holds them.

writeManifest then records the result. DeployLocal also runs VenueSeed, which seeds pools, a deposit, a resting DLMM limit order and a launch on a local fork. Canary.s.sol is the post-deploy smoke test: a tiny zap, a range order placed and cancelled, and a harvest on the ETH vault's pool.

Reference

Deploy values

Ports and environment