Docs

How it works

Quotes

Where the prices come from: two Uniswap V3 pools on Base, read from slot0 at a recorded block.

The pools#

Forgeus reads two fixed pools on Base (chain id 8453). It never uses an off-chain price feed.

MarketPoolAddresstoken0 / token1Invert
ETH-USDCWETH/USDC 0.05%, Uniswap V30xd0b53D9277642d899DF5C87A3966A349A798F224WETH (18) / USDC (6)no
BTC-USDCUSDC/cbBTC 0.05%, Uniswap V30xfBB6Eed8e7aa03B138556eeDaF5D271A5E1e43efUSDC (6) / cbBTC (8)yes

The numbers in brackets are token decimals. Every price is stored as USDC per base asset (ETH or BTC).

How a quote is read#

Every minute the engine calls slot0() on each pool at a specific block and stores:

FieldMeaning
idQuote id, increasing
marketETH-USDC or BTC-USDC
blockBase block number the pool was read at
tsUnix seconds of that block
sqrt_pricesqrtPriceX96 from slot0, as a decimal string
priceUSDC per base asset, derived from sqrt_price

sqrt_price is the raw on-chain value. price is derived from it with a fixed formula, so anyone can recompute it. See Checking quotes on-chain.

Price formula#

text
s     = sqrtPriceX96 / 2^96
raw   = s * s                      // token1 per token0, in raw units
p     = raw * 10^(dec0 - dec1)     // token1 per token0, in whole tokens
price = invert ? 1 / p : p         // USDC per base asset
price = round(price, 6 decimals)
  • ETH-USDC: p = raw * 10^12. token1 is USDC, so p is already USDC per ETH.
  • BTC-USDC: p = raw / 10^2. That is cbBTC per USDC, so the engine inverts it to get USDC per BTC.

The engine applies the decimal shift by multiplying or dividing by 10 one step at a time. This keeps results identical in every JavaScript engine.

Backfill#

The first generations need history that existed before the engine started. That history was backfilled from the same pools at past blocks, one read every 30 blocks (about one minute on Base). Backfilled quotes are stored the same way, with their block number, so they can be checked the same way.

Quotes in a generation#

A generation uses 120 quotes per market: 60 warmup quotes for lookbacks, then 60 window quotes that are traded. The record stores a quotes_hash for all 120 per market. See Generations & the hash chain.

Paper only. No funds are traded. $FOUS is not launched. Nothing here is financial advice.