Architecture

This chapter is the map for engineers: the contract families ZKDepth deploys, the programs around them, and the two paths data takes.

The map

The browser, the API and its bots, the indexer, the signer, the relayer and the sealed batch keepers sit off chain, and all of them reach the contracts through the Robinhood Chain RPC. Addresses are in Contracts.

Contract families

The families meet at fees: FeeRouter's treasury is the venue's FeeCollector, so whatever referrers do not earn joins the pools' protocol fees on the way to the $ZKD buyback. Who can call what is in Who can do what.

The programs off chain

Indexer, API and bots covers the first four, Perps on Lighter the signer and Sealed batches the keepers.

The relayer's URL is the only private-lane server the browser talks to. The browser reads pool and sealed lane logs through a same-origin RPC route whose keys stay on the server, and builds Merkle paths itself. The API's GET /shielded/stats answers aggregates only: set size, total per asset and action counts. No route takes a commitment or an address.

A write, from click to block

Every button that changes chain state calls useWrite().run(...) in apps/web/lib/tx.ts.

1. 1
   Gate

   The hook checks for a connected wallet, chain 4663 and a deployment manifest.
2. 2
   Simulate

   An eth_call from your address. A revert stops here, and your wallet never opens.
3. 3
   Sign and send

   Your wallet signs the simulated request and sends it through the RPC.
4. 4
   Refresh

   The queries the write affects are refetched as the indexer sees the new logs.

A deposit into the private balance is the one exception: the @zkdepth/zk client sends it to your wallet with no simulation first.

For anything a transaction must get exactly right, the browser reads the chain directly. A private action loads the proving key for its circuit, proves in a browser worker, and a relayer or a fresh address submits it. The API's POST routes store a signed idea, forward a signed perp request to the signer, or return a plan for your wallet to send.

A read, from chain to page

A page hook in apps/web/lib/data.ts calls a typed fetcher in apps/web/lib/api.ts. The API answers from the indexer, from chain reads batched through Multicall3, from market data or from its database, and a cached route keeps its answer for 15 to 60 s. It maps its own model to the exact shape api.ts declares, and a test fails if either side renames a field. The indexer is fed by the chain alone.

Shared packages

• @zkdepth/core is pure TypeScript: tick and zap maths, fee APR, hedge sizing, note payoffs, DLMM bin maths, slippage. A number on a card and the number a bot acts on come from the same function.
• @zkdepth/abi holds the compiler ABIs, the chain's fixed addresses and the manifest type. The manifest is the one file that says where a deployment lives.
• @zkdepth/agent holds the routes, plans and tools agents and the app share.
• @zkdepth/zk holds keys, notes, the tree, proving workers, scanning and every private action.

Deploying the stack

DeployRobinhood.s.sol and DeployLocal.s.sol both call deployAll, which deploys the venue, the fee contracts, the position tools, the vaults, the perps engine and the launchpad, creates the seed vaults, then proposes the owner for the admin contracts. Until the owner calls acceptOwnership, the deployer still holds them. The deploy then adds the private balance, its adapters and the sealed lane, on the verifiers it is given, and names the lane's opener list to the launchpad. The owner adds sealed markets after, with the operators' keeper keys. scripts/dev-local.sh runs the same deploy on a local fork, on development proving keys.