FACTA

master.pools

Version
0.1.0

The Uniswap pools of issuer-listed tokens, and the liquidity each one reports.

Changelog

Changelog
VersionDateChange
0.1.0
2026-11-11
First version.

What it measures

Which Uniswap v3 and v4 pools hold a listed token against USDG, WETH or its sibling (the other issuer's token for the same stock), and each pool's price and in-range liquidity (pool_liquidity). It does not measure volume, and it does not say whether a pool's volume is real: that is Tape, in Phase 2.

Inputs

Found by computing each pool's address or ID, never by reading a long range of logs (master.pools-sync, daily):

  1. Uniswap v3: getPool(token, quote, fee) on the v3 factory (0x1f7d7550b1b028f7571e69a784071f0205fd2efa) for every listed token against USDG, WETH and its sibling, at the four standard fee tiers (0.01%, 0.05%, 0.3%, 1%). A non-zero answer is a pool.
  2. Uniswap v4: the ID of each of the same pairs with no hook, at the four standard tiers and their tick spacings, read through StateView (getSlot0). A pool with a price is initialised.
  3. StablePair pools: for each pair of sibling tokens, the ID of the pool with fee 0x800000 (dynamic), tick spacing 1 and the StablePair hook (0xd061f665d1c4816787fceaa168fa66c59d3abcc0). A pool with a price and a stored reference rate is one; see master.parity.
  4. State of every known pool, daily: price and in-range liquidity (slot0() and liquidity() on a v3 pool, getSlot0 and getLiquidity through StateView for a v4 pool).

A pool ID is computed once for a token's list of pairs. Each ID is a keccak hash, and a step computes at most 30, for whole tokens. A token's IDs, and those of its StablePair pair, are kept in the job's state row master.pool-ids with the list of pairs they were computed for: its quote assets and fee tiers, by version, and its siblings. A later run reads them back and computes none, so its steps read up to 200 candidate pools each. An entry made for another list of pairs, as when a token gains a sibling, is not used: the token's IDs are computed again.

The first run over the 218 tokens listed on 2026-11-10 is 4 steps for Uniswap v3, 73 for Uniswap v4, one for the StablePair pools and one for each 80 known pools: 79 steps and 159 outside requests when few pools are known. A later run, with the IDs stored, takes 9 steps for Uniswap v4: 15 steps and 31 outside requests. Every step reads the head block once and then:

Inputs
StepReadsRequests for them
Uniswap v3
getPool for whole tokens, at most 800 calls a step, 400 a request
at most 2
Uniswap v4
getSlot0 for at most 200 candidate IDs, of which at most 30 are computed in the step
1
StablePair
getSlot0 and feeConfig for at most 30 sibling pairs
1
State of known pools
2 or 3 calls for each of at most 80 pools
1, or 2 when the page holds pools of both venues

A step writes at most 120 new pools. A new pool writes four rows, its own and three index entries, and a step may write 500 rows, of which it keeps 20 for its other writes. When a page of reads finds more new pools than that, the step writes the first of them and moves on past those only: the pools of its first whole tokens after a page of Uniswap v3 reads, and the first pools in the order read after a page of Uniswap v4 reads. The next step reads the rest again.

What an answer shows is ranked in the job's state row master.token-pools: for each listed token, how many of its pools are on file, and which of them an answer shows, in order (below). The ranking follows the pools on file, batch by batch. A step that stores new pools ranks the pools of their tokens again in the same batch, after its inserts, so a pool counts from the step that stores it, not from the end of the run. A step that reads known pools again and writes one ranks the pools of that pool's tokens again in the same batch, so its order follows the liquidity just read. A step of master.registry-sync that stores a token the registry had left out ranks its pools still on file the same way. The last step of a run ranks every listed token's pools again. Before the row exists, as before the first pool is stored, the step that stores the first new pools ranks every listed token's. The row is written only when the ranking changed.

The calls of one request travel as one call to Multicall3, pinned to the step's block. A v3 pool is a contract of its own, and it never shares such a call with StateView or the hook. When an endpoint refuses and the read falls back, it costs more than one of the step's 40 requests. A step whose budget cannot cover its page reads a smaller one, and moves on by what it read. When not even one token's or one pool's reads fit, the step fails with that reason and is retried.

The rule

A pool is stored once found and refreshed daily. A pool's row is written only when its price, liquidity or reference changed.

Liquidity, per venue: the figure is the in-range liquidity L exactly as the pool reports it, a raw integer. For a v3 pool it is liquidity() on the pool; for a v4 pool it is getLiquidity(poolId) through StateView. It is not a dollar value and not the total value locked: the tokens deposited outside the current price range are not in it.

The pools an answer shows

A check shows at most 10 pools of its token, and an instrument page at most 20 for all its tokens together, whatever the number on file. Anyone can create a pool for a listed token at every key this method looks for, for gas only: 25 for a token with a sibling, 41 for their instrument. Each pool shown is a row a request reads, and rows read are a daily budget every caller shares.

The pools shown are the token's first in this order, from the pools on file and the liquidity last read for each:

  1. its StablePair pools, which carry the parity record (master.parity);
  2. its pools whose in-range liquidity is above zero, the largest first;
  3. its pools whose in-range liquidity is zero or has not been read yet.

Ties are broken by pool ID. The order compares the raw in-range liquidity each pool reports. Two pools against quote assets with different decimals report different figures for the same depth, so the order is not a ranking by dollar depth.

What it costs to put a pool first. Little: this order does not resist it. Anyone can create a pool at a key this method looks for, for the gas of the transactions, and the raw in-range liquidity the order compares is cheap to make large:

  • A position one tick spacing wide, centred on the price, reports about 40,000 times the in-range liquidity of a full-range position holding the same tokens at the 0.01% tier, whose tick spacing is 1; about 4,000 times at 0.05% (spacing 10), about 670 times at 0.3% (spacing 60) and about 200 times at 1% (spacing 200). For a spacing of s ticks the factor is 1 ÷ (1 − 1.0001^(−s/4)).
  • In-range liquidity is counted in each token's smallest units. For the same depth in dollars, a pool against WETH, which has 18 decimals, reports 10^6 ÷ √P times the liquidity of a pool against USDG, which has 6, where P is the price of one ether in dollars.

So a new pool against WETH with a position one tick spacing wide can rank above a token's deep pools against USDG while it holds a tiny fraction of their tokens, and a stranger who creates enough such pools fills the places an answer shows. The answer still says how many pools are on file (poolsTotal), and the order is the one this page names. Whether a stranger can hold the small amount of a listed token such a position may need depends on that token's transfer rules, which this method does not check. An order by what each pool holds would need each pool's positions or balances, which this version does not read.

Every answer says how many pools of its token are on file, in the field poolsTotal: of a check, and of each token of an instrument page. It counts every pool of the token on file, those shown and those not, from the step that stored each one. A pool of two listed tokens counts for each of them. When poolsTotal is more than the pools listed, each page and the MCP text say how many are shown, out of how many on file, and in this order, for example: "This token has 25 pools on file, and 10 are shown: its StablePair pools first, then its pools with the largest in-range liquidity as each pool reports it." The answer's notes carry no sentence of their own about it, so no surface says it twice. An address no issuer lists has no pools in its answer and poolsTotal 0: no pool is looked for or filed under it.

An instrument page takes each token's pools in turn: the first of each token, then the second of each, and so on, until it holds 20. A pool two tokens share is taken once. Each token shows the first pools of its own order and no others, so a token shows on the instrument page what its own check shows, or the first part of it.

Until a run has completed, an answer says that the token's pools are being found, and shows those found so far. An answer says that none is on file only for a token the last completed run looked for: a run walks every token stored before its first step, and its state records when that step ran (startedAt). A token an issuer lists after the run began has not been looked for: its answer gives no poolsTotal, says that its pools are being found, and the next run looks for them. Its instrument page says the same. Before the ranking row exists, as on a database whose pools were stored before the row existed, no pool is shown, the answer says that the token's pools are being found, and it gives no poolsTotal: no count has been made, and 0 could be untrue.

Thresholds

Thresholds
ThresholdDefaultWhere
Quote assets
USDG, WETH, the sibling token
pools-sync.ts
Fee tiers
100, 500, 3,000 and 10,000 hundredths of a basis point
STANDARD_FEE_TIERS
Pool IDs a step computes
30
POOLS_SYNC.v4CandidatesPerStep
Candidate v4 pools a step reads
200
POOLS_SYNC.v4ReadsPerStep
Tokens a v4 step looks at
26
POOLS_SYNC.v4TokensPerStep
New pools a step writes
120: four rows each, in a budget of 500 rows of which 20 are kept
MAX_NEW_POOLS, POOLS_SYNC.rowsPerNewPool, POOLS_SYNC.rowsReserve
Pools a check shows for its token
10
POOL_LIST.perToken
Pools an instrument page shows for all its tokens
20
POOL_LIST.perInstrument
Pools are stale after
259,200 seconds (3 days)
FRESHNESS.poolSeconds

Terms

None. The term about a pool's volume, the Pool Check, belongs to Tape and is not in Phase 1.

Evidence

  • pool_liquidity, keyed by the pool's ID (v3:<pool address> or v4:<pool id>): the call liquidity() on the v3 pool, or getLiquidity(bytes32) on StateView with the pool ID, at its block.

Recomputation

pnpm tool packages/master/recompute.ts --envelope answer.json --rpc <endpoint> reads each pool's liquidity again and compares. No free endpoint serves past state, so without an archive endpoint the script re-reads at the head block and says so; liquidity moves with every deposit and withdrawal, so a mismatch at the head shows that it moved.

Ways to game it, and what the method does

Ways to game it, and what the method does
WayWhat the method does
A pool with a hook or a fee tier not looked for
It is not found, and this page says so: the answer lists only what was looked for.
Liquidity placed just around the price to look deep
The figure is in-range liquidity as reported, not a depth or a dollar value. Tape measures turnover against it.
Pools created for a listed token at every fee tier and quote, so that a step finds hundreds at once
A step writes what its budget of rows holds, 120 new pools, and moves on past those only; no number of pools makes the job fail or a step write more than its budget.
Pools created for a listed token at every key, so that each check of it reads many rows of the day's shared budget
A check shows at most 10 pools of a token and an instrument page 20, read by their keys, one row each, whatever the number on file. The answer says how many are on file (poolsTotal). The ranking is made in the job's batches: a step that stores new pools reads the pools of their tokens only, not every pool on file.
Empty pools created to push a token's real pools off its answer
Pools whose in-range liquidity is zero rank after every pool with some, and the StablePair pool always comes first.
Liquidity placed in a new pool to rank it above a token's established pools
Nothing in this version prevents it, and it costs little: see "What it costs to put a pool first". The order is the raw in-range liquidity each pool reports, which this page names; it is not a dollar depth. The answer says how many pools are on file, so a reader knows when some are not shown.
Pools created while a run is under way, to be on file and not counted until the run completes
A pool counts in poolsTotal, and takes its place in the order, from the step that stores it.

Limits

  • Only standard keys are looked for. A pool with a non-standard fee, another hook, or another quote asset is missed. In particular, v4 pools against native ETH are not looked for: the method pairs v4 pools with WETH as it does v3 pools. Finding pools from Initialize events, which finds every pool, is the first Phase 2 task.
  • Pools are listed for issuer-listed tokens only. An address no issuer lists has no pools in its answer, and the answer says so.
  • An answer shows at most 10 pools of a token. No list of all of a token's pools is served in Phase 1; the answer says how many are on file.
  • A stranger can choose which pools an answer shows, for little ("What it costs to put a pool first"). The order is raw in-range liquidity, which a position one tick spacing wide or a pool against an 18-decimal asset makes large. An order by what each pool holds needs each pool's positions or balances, which this version does not read.
  • A pool newly stored has no liquidity read until the same run reads the known pools again: until then it ranks among the pools with none, and its liquidity counts in the order from the step that reads it.
  • Only Uniswap v3 and v4 pools are read. RFQ desks, proprietary market makers and order books are out of scope.

What overlaps elsewhere

Uniswap's interface and explorers list pools. This method reads the pools of listed tokens by their computed keys, so each figure points to the call that produced it.