Kova

Overview

A tokenized share on Robinhood Chain rarely trades in one place. The same stock sits in Uniswap v2, v3 and v4 pools, in Algebra pools and in several v3 forks, against USDG, WETH, native ether and other stocks, and every pool keeps its own price. Kova reads all of them and sets them side by side: what a share costs, how far apart the pools are and what a real order would get in each one.

What Kova is not

• Not a venue. It routes no orders, matches nothing and takes no fee. Trades happen in the pools, wherever you choose.
• Not a wallet. It never asks for a signature, a network switch or a transaction.
• Not an oracle. The book price is a reading aid, a liquidity-weighted median of live pools, not a reference rate to settle anything against.

How it works

The same modules run on the server and in the browser. The API builds the book once for everyone looking; the terminal can skip the API and rebuild the whole book in the page, straight from the chain.

Flow

DexScreener: which pools list NVDA, SPY, AAPL ...?
      |
      v
classify each pool on chain ---> v2 | v3 | algebra | v4 | unknown
      |
      v
read state: slot0, globalState, reserves, v4 slots      KovaLens.peek, 250 reads per eth_call
      |
      v
price: USDG pools set the dollar; ETH and equity legs convert through their own pools
      |
      v
book: price, low, high, spread and every pool row, per asset
      |
      +--> /api/v1/book, the terminal, the landing page
      +--> quotes: every pool swaps inside eth_call             KovaLens.quote
      +--> tape: Swap events from the busiest pools

A cold build, discovery included, takes a few seconds against the public node; a warm one, with discovery cached, takes one or two. The server keeps a finished book for 15 seconds and serves it for up to three minutes while a fresh one is built behind it.

Quickstart

Run the site

# from a checkout of this repository
npm install
npm run dev          # http://localhost:4720, pages and /api like on Vercel

Check the engine

npm test                          # unit tests
node scripts/time-book.mjs        # two builds against the node, with timings

Ask the API

curl -s "localhost:4720/api/v1/book?rows=0" | jq .stats
curl -s "localhost:4720/api/v1/quote?symbol=NVDA&side=buy&amount=1000" | jq .best

Discovery

The book starts from a list of canonical tokens and asks DexScreener which pools list each one, through /token-pairs/v1/robinhood/{token}, six tokens at a time. Lists are cached for five minutes. WETH is looked up as well, because its USDG pools set the dollar price of ether.

A listing only names a pool. Its labels and prices are not trusted: every pool worth reading is measured on chain in the next steps. Pools with less than $5,000 of reported liquidity stay in the book as dust and are never read.

Canonical tokens

Every tokenized equity Robinhood issues is a beacon proxy pointing at the same beacon. A token enters the registry only when its EIP-1967 beacon slot holds that beacon. A matching name or ticker is not enough, so a look-alike token never reaches the book.

npm run build:registry writes the list to js/registry.js, together with the settled facts of every pool it could classify, so a cold start does not rediscover what never changes. A token issued after the last build is missing until the registry is rebuilt.

Pool kinds

A pool's kind decides how its price is read, so it is measured rather than taken from a label. Every pool not yet classified gets seven calls: globalState, slot0, getReserves, token0, token1, fee and tickSpacing. Whatever answers decides.

A pool that stays silent three rounds in a row is marked unknown. Token order, fee and tick spacing are kept with the kind, and the registry build stores them for next time.

Reading state

Every read for the book goes through KovaLens.peek, a multicall that exists only inside the call: its bytecode travels with each eth_call as a state override at 0x4b4f564100000000000000000000000000000000, an address whose bytes spell KOVA. One call carries 250 reads, each with its own 300,000 gas, and the calls share one HTTP batch. Around 840 pools cost a handful of requests instead of hundreds.

Uniswap v4

v4 pools have no contract of their own. Their state lives in the PoolManager at 0x8366a39cc670b4001a1121b8f6a443a643e40951, in mapping slot 6: the pool's state slot is keccak256(poolId, 6), slot0 is packed into it and liquidity sits three slots further on. Both are read with extsload.

A quote needs the pool's full key, not just its id. Kova recovers the key by hashing candidates: the two currencies, the LP fee or the dynamic-fee flag, and each common tick spacing, with no hooks, until one matches the id. A pool whose key does not turn up, a pool with hooks for example, is priced but never quoted.

Pricing

A pool price starts as a ratio of its two tokens, from sqrtPriceX96 for v3, Algebra and v4 pools or from reserves for v2, corrected for decimals. Turning it into dollars takes one more step, and the book never borrows that step from an indexer:

1. USDG is one dollar. A pool against USDG is priced directly.
2. Ether is priced from WETH's own USDG pools, as a liquidity-weighted median of the lively ones. If none answered, the indexer's figure stands in and every ETH-priced row says so with ethPriceReported.
3. Pools against WETH or native ether convert through that price.
4. Each stock gets a dollar mid from those pools, and pools quoted in another stock convert through that stock's mid.

An asset's price is the liquidity-weighted median of its active pools: the price with half the active liquidity on either side. A thin pool can print any number; it cannot drag this one far.

Row statuses

A pool is lively when it holds at least $10,000 and traded at least five times in the last 24 hours. Only active pools feed an asset's price, low, high and spread.

Spreads and drift

spreadPct is how far the richest active pool sits above the cheapest, (high / low - 1) × 100, given once an asset has two active pools. The book's medianSpreadPct is the median of those spreads across assets, and every row carries deltaPct, its distance from the asset's price.

driftPct sets a pool's on-chain dollar price against the price the indexer reports for the same pool, on rows where that price refers to the stock. The terminal and the landing page flag anything past 2%. A large drift usually means one of the two numbers is stale, and the row shows both so you can tell which.

Quotes

A quote asks every pool the same question at once: what would this order get here, right now? A buy spends USDG on a stock; a sell turns shares into USDG.

The candidates are an asset's active and thin pools that are quotable. A pool against USDG is quoted directly. A pool against WETH is quoted through the deepest quotable WETH/USDG pool, so a buy there crosses two pools: USDG to WETH, then WETH to the stock. Outliers and unpriced pools are never quoted.

KovaLens

Quotes run in KovaLens, a contract that is never deployed. Its runtime code, about 5 KB, travels with each eth_call as a state override, so a quote needs no deployment, approval or signature and describes the pool at the current block.

Each revert is caught and decoded, so the pool's own arithmetic, fees, tick crossings and running out of depth included, becomes the answer while the swap itself unwinds. A leg that fails zeroes only its own path. Each leg gets 2,500,000 gas, six paths travel per call, and the calls share one HTTP batch.

function quote(Leg[] calldata legs, uint256[] calldata lengths, uint256 amountIn)
    external returns (uint256[] memory amountsOut, uint256[] memory amountsInUsed);

function peek(Read[] calldata reads) external view returns (bytes[] memory results);

The source is contracts/KovaLens.sol. npm run build:lens compiles it with solc 0.8.26 into js/lens-code.js, and /api/v1/health reports the fingerprint of the code in use.

Reading a quote

Tape

The tape lists trades as they printed. It reads Swap events from the busiest active pools, up to 40 ranked by 24-hour volume, over the last 9,000 blocks: about fifteen minutes at a tenth of a second per block, and inside the ten thousand blocks the node allows per log query.

A trade is a buy when the pool paid the stock out. Its value comes from the pool's own quote amount at the row's dollar rate, and each trade links to its transaction on Blockscout. The tape has no API endpoint; pages read it through the RPC proxy.

Holdings

The terminal can show what an address holds: every canonical stock token, USDG, WETH and ether, valued at book prices. Paste an address or connect a browser wallet. Connecting only asks the wallet which account is selected.

Balances are read in one pass through KovaLens.peek, via this site's RPC proxy, which stores nothing. The address is remembered in your browser under kova.watch until you clear it.

API

Everything the site shows is available as read-only JSON under /api/v1. There is no key and no sign-up. Responses allow any origin and carry cache headers, so a CDN in front of the functions answers most requests without touching the engine.

Errors come back as { "error": "..." } with a matching status: 400 for a bad parameter, 404 for an asset that is not in the book, 405 for anything but GET, and 502 when the chain or the indexer did not answer in time.

GET /api/v1/book

curl -s "https://your-host/api/v1/book?rows=0&include=NVDA"

{
  "at": 1789300000000, "block": 61502221, "phase": "closed", "ethUsd": 2523.08,
  "stats": { "assets": 44, "tokens": 54, "pools": 1196, "activePools": 304, "venues": 8,
             "volume24h": ..., "liquidityUsd": ..., "medianSpreadPct": 0.96, "widestSpreadPct": ... },
  "venues": [ { "name": "Uniswap", "pools": ..., "activePools": ..., "kinds": ["v3", "v4", "v2"] } ],
  "assets": [
    { "symbol": "NVDA", "name": "NVIDIA", "price": ..., "low": ..., "high": ..., "spreadPct": ...,
      "activePools": 27, "quotablePools": ..., "cheapest": { ... }, "richest": { ... },
      "rows": [ { "id": "0x...", "venue": "Uniswap", "kind": "v3", "quote": "USDG", "status": "active", ... } ] }
  ]
}

GET /api/v1/quote

curl -s "https://your-host/api/v1/quote?symbol=NVDA&side=buy&amount=10000"
curl -s "https://your-host/api/v1/quote?tokenIn=NVDA&tokenOut=USDG&amountIn=5"

The answer holds best, the pool that fills the whole order for the most, and results for every pool quoted, with the fields described in Reading a quote. block is the block of the book the pools came from; the swaps themselves run against the latest block.

Tokens, venues, health

/api/v1/tokens lists every canonical token with its address and decimals, the beacon check that admitted it and the currencies prices are built from. /api/v1/venues lists venues with pool counts and the kinds measured behind each label. /api/v1/health says whether the node answers as chain 4663, with the head block and latency, the market phase, the registry's size and date, and the lens fingerprint with deployed: false.

RPC proxy

/api/rpc relays JSON-RPC from this site's own pages to the node. It exists because the public node, under load, sends Access-Control-Allow-Origin twice, and browsers discard such answers. It is not a public relay.

Pages try the proxy first and the node directly second. A throttled batch is retried with backoff, and a batch that fails is split in half and tried again, so a node with an unknown limit costs more requests rather than an error.

Self-hosting

Kova is a static site plus a few Node functions. On Vercel it deploys as it is: pages and assets are served statically, and every file under api/ becomes a function that imports the shared modules from js/ and lib/.

vercel deploy            # a preview
vercel deploy --prod     # production

Elsewhere, any Node server that hands the handlers a plain request and response will do. dev-server.mjs is a complete example in about a hundred lines. Functions keep the book in memory per instance, so a warm instance answers from cache; allow them up to 60 seconds, although a cold build usually takes a few.

Environment

Development

The chain code has no dependencies. Keccak-256, ABI encoding, sqrtPriceX96 prices and the v4 storage layout live in js/keccak.js and js/evm.js, and the same files run in Node and in the browser.

Numbers

Limits

Knowing where the edges are is cheaper than finding them.

• KovaLens is unaudited. It is never deployed and can move nothing, but a wrong quote would still be wrong.
• Discovery depends on DexScreener. A pool it does not list is not in the book.
• Pools with hooks, or with a tick spacing outside the common set, can be priced but not quoted.
• Prices are read at one block from a public node. They are not a signed feed and can trail a busy block.
• The market phase follows the regular US session in New York time and knows nothing about holidays.
• The tape covers fifteen minutes and has no reorg handling: a range is read once, as it stood.
• A newly issued token appears only after the registry is rebuilt.