Lesson 1 — What a market on Uniswap v4 is
Sources: Uniswap/v4-core
v4.0.0, psyto/summon-stocksd4debb7, fabrknt/shadowbook7d07439. Every line link below points at those exact versions.About 10 minutes to read, 30 if you run everything.
A market on v4 is five values
On Uniswap v4, one contract, the PoolManager, holds every pool.
A pool is nothing more than its PoolKey. That's five values: two currencies, a fee, a tick spacing and a hooks address.
Change any of the five and you have a different market.
The hooks address is where you add your own rules.
In this lesson we read those pieces in v4-core. Then we look at two open projects that build a market this way, and run both test suites: 57 tests for one, 49 for the other.
You'll learn:
- Why v4 has one
PoolManagerfor all pools, and what that means for a new market - The five fields of a
PoolKey, and how a pool's id is derived from them - Where hooks enter: the hooks address in the key, and the checks
initializemakes on it - How two projects use this: Shadowbook (a pool quoted from an off-chain price) and Summon (a tokenized stock that arrives with a pool its backers own)
Where's the factory? There isn't one
In v4 there's no factory that deploys a contract per pool.
The PoolManager keeps all pool state in one mapping (PoolManager.sol L77-L92):
/// @title PoolManager
/// @notice Holds the state for all pools
contract PoolManager is IPoolManager, ProtocolFees, NoDelegateCall, ERC6909Claims, Extsload, Exttload {
...
mapping(PoolId id => Pool.State) internal _pools;
So "deploying a market" on v4 means calling initialize on a PoolManager that already exists.
Summon does exactly that. On Base Sepolia it uses the PoolManager at 0x05E7…3408 (Deploy.s.sol L23). It doesn't deploy its own.
A pool is its key
A pool is identified by five values (types/PoolKey.sol L11-L22):
struct PoolKey {
/// @notice The lower currency of the pool, sorted numerically
Currency currency0;
/// @notice The higher currency of the pool, sorted numerically
Currency currency1;
/// @notice The pool LP fee, capped at 1_000_000. If the highest bit is 1, the pool has a dynamic fee and must be exactly equal to 0x800000
uint24 fee;
/// @notice Ticks that involve positions must be a multiple of tick spacing
int24 tickSpacing;
/// @notice The hooks of the pool
IHooks hooks;
}
The pool's id is the hash of the whole key (types/PoolId.sol L10-L16): keccak256(abi.encode(poolKey)). It's computed in assembly over the key's five 32-byte slots.
"Same pair, same market?" Not on v4.
Two pools of the same pair with a different fee, tick spacing or hooks address are two different markets, with separate liquidity.
Two details of the key matter for a new market.
currency0 < currency1.
Otherwise initialize reverts with CurrenciesOutOfOrderOrEqual. The native currency is address(0), so it's always currency0.
fee can be a flag.
0x800000 (LPFeeLibrary.DYNAMIC_FEE_FLAG, LPFeeLibrary.sol L15) means "no fixed fee". The pool starts at a 0 fee (L51-L56), and a hook sets it.
initialize is where these rules are checked (PoolManager.sol L116-L142, trimmed):
function initialize(PoolKey memory key, uint160 sqrtPriceX96) external noDelegateCall returns (int24 tick) {
if (key.tickSpacing > MAX_TICK_SPACING) TickSpacingTooLarge.selector.revertWith(key.tickSpacing);
if (key.tickSpacing < MIN_TICK_SPACING) TickSpacingTooSmall.selector.revertWith(key.tickSpacing);
if (key.currency0 >= key.currency1) { CurrenciesOutOfOrderOrEqual ... }
if (!key.hooks.isValidHookAddress(key.fee)) Hooks.HookAddressNotValid.selector.revertWith(address(key.hooks));
uint24 lpFee = key.fee.getInitialLPFee();
key.hooks.beforeInitialize(key, sqrtPriceX96);
PoolId id = key.toId();
tick = _pools[id].initialize(sqrtPriceX96, lpFee);
// event is emitted before the afterInitialize call to ensure events are always emitted in order
// emit all details of a pool key. poolkeys are not saved in storage and must always be provided by the caller
// the key's fee may be a static fee or a sentinel to denote a dynamic fee.
emit Initialize(id, key.currency0, key.currency1, key.fee, key.tickSpacing, key.hooks, sqrtPriceX96, tick);
key.hooks.afterInitialize(key, sqrtPriceX96, tick);
}
Look at the comment above the emit. Pool keys aren't saved in storage. So every caller passes the full key, every time.
Hooks are where your rules go
The last field, hooks, is a contract address. The PoolManager calls it at fixed points: before and after initialize, add and remove liquidity, swap and donate.
You can see two of them in initialize above: beforeInitialize and afterInitialize.
Which calls actually happen is decided by the hooks address itself. That's the subject of Lesson 3.
For now, hold on to this. A market on v4 is a pool key. The hooks address in it is where a builder puts the rules that make the market theirs.
Two markets built this way
Both projects below are open source and early. Read their status lines before anything else:
- Shadowbook: "Status: early and unaudited; not yet deployed." (README L15)
- Summon: "testnet only (Base Sepolia), unaudited, not for real funds." (README L5)
Shadowbook: a pool quoted from an off-chain price
Shadowbook is "a prop AMM for Elysium (Kinetiq's Hyperliquid L2), built as a Uniswap v4 hook" (README L3).
Its hook quotes the pool from a price a keeper pushes, instead of a curve.
Why a v4 pool, and not a new venue? Its README gives the reason (README L7-L8):
Because it is an ordinary v4 pool, the aggregators and solvers already routing on Elysium reach it without a new integration.
And here's the measurement behind that (README L25-L31), quoted as the README states it:
Measured on Elysium mainnet, 2026-11-10 UTC (scripts in
measure/):
- HYPE/USDC traded about $12M across v3/v4/DLMM pools.
- Pools charging 25–30 bp still filled over $3M of it, mostly small orders arriving through aggregators and solvers (KyberSwap, 0x, OKX DEX, Relay and others). A new v4 pool was reached by ERC-4337 and Relay flow within a minute of initialization, and by KyberSwap and a solver within the hour.
Its demo deploys the pool with a native-HYPE / USDC key (script/Demo.s.sol L69-L70):
PoolKey memory key = PoolKey(Currency.wrap(address(0)), Currency.wrap(address(usdc)), 0, 60, IHooks(at));
manager.initialize(key, 2 ** 96); // the curve never runs; any valid price will do
currency0 is address(0), native HYPE.
Why is the fee 0? As the README says, "the curve never runs, so no LP fee is charged whatever the tier" (README L205-L206).
Summon: a stock arrives with a pool its backers own
Summon is "a primary-market primitive for tokenized stocks" on Base (README L14).
Backers commit USDC to a ticker. When a holder of the stock token fills the round, "Part of the round seeds a Uniswap v4 pool. The pool can only be created by the round, and the backers own the LP position together." (README L24-L25).
After the fill, the pool's hook "stops swaps while the stock is halted, around a corporate action, or while the issuer pauses it, and charges 1.00% instead of 0.30% while the US session is closed" (README L36-L38).
Each round knows its pool's key (src/SummonRound.sol L216-L221):
function poolKey() public view returns (PoolKey memory key) {
(Currency c0, Currency c1) = p.token < d.usdc
? (Currency.wrap(p.token), Currency.wrap(d.usdc))
: (Currency.wrap(d.usdc), Currency.wrap(p.token));
key = PoolKey(c0, c1, SummonPool.FEE, SummonPool.TICK_SPACING, IHooks(d.hook));
}
The constants are in src/SummonPool.sol L14-L17:
int24 internal constant TICK_SPACING = 60;
uint24 internal constant FEE = LPFeeLibrary.DYNAMIC_FEE_FLAG;
uint24 internal constant OPEN_FEE = 3000; // 0.30%, while the listing exchange is open
uint24 internal constant CLOSED_FEE = 10_000; // 1.00%, while it is closed or the guard is quiet
The token sorts against USDC exactly as initialize requires.
And because the key is the pool's identity, the factory can register "this key belongs to this round" when the round opens (src/SummonFactory.sol L154): roundForPool[keccak256(abi.encode(round.poolKey()))] = address(round);.
Later, the hook looks up the round by the same hash.
The two keys side by side
| Shadowbook (demo) | Summon | |
|---|---|---|
| currencies | native HYPE (address(0)) / USDC | stock token / USDC, sorted by address |
| fee | 0 (the curve never runs) | 0x800000, dynamic: the hook sets 0.30% or 1.00% |
| tickSpacing | 60 | 60 |
| hooks | the Shadowbook hook | SummonHook |
| who initializes | the owner, once | only the round registered for the key |
Exercise: clone both projects and run their tests
You need Foundry.
The commands come from the two READMEs. We add a git checkout of the version this lesson cites, plus the submodule update that goes with it (Summon README L180-L182, Shadowbook README L243-L244):
git clone --recursive https://github.com/psyto/summon-stocks
cd summon-stocks
git checkout d4debb7 # the version this lesson cites
git submodule update --init --recursive
forge test
cd ..
git clone https://github.com/fabrknt/shadowbook
cd shadowbook
git checkout 7d07439
forge install
forge test
Here's what we got (forge 1.7.1, macOS, 2026-11-14; per-test lines removed).
Summon builds with via_ir (README L187-L188), so its first compile is slower:
# summon-stocks
Compiling 93 files with Solc 0.8.26
Solc 0.8.26 finished in 20.50s
Compiler run successful!
Ran 6 tests for test/SummonPrice.t.sol:SummonPriceTest
Suite result: ok. 6 passed; 0 failed; 0 skipped; finished in 9.78ms (10.51ms CPU time)
Ran 51 tests for test/SummonRound.t.sol:SummonRoundTest
Suite result: ok. 51 passed; 0 failed; 0 skipped; finished in 9.75ms (36.38ms CPU time)
Ran 2 test suites in 13.61ms (19.53ms CPU time): 57 tests passed, 0 failed, 0 skipped (57 total tests)
# shadowbook
Compiling 88 files with Solc 0.8.26
Solc 0.8.26 finished in 1.18s
Compiler run successful!
Ran 21 tests for test/DirectionalFee.t.sol:DirectionalFeeTest
Suite result: ok. 21 passed; 0 failed; 0 skipped; finished in 197.52ms (559.46ms CPU time)
Ran 28 tests for test/Shadowbook.t.sol:ShadowbookTest
Suite result: ok. 28 passed; 0 failed; 0 skipped; finished in 197.48ms (206.61ms CPU time)
Ran 2 test suites in 205.43ms (394.99ms CPU time): 49 tests passed, 0 failed, 0 skipped (49 total tests)
Your timings will differ. The counts shouldn't.
- Summon: 57. As its README says, "57 tests, no keys, no network after the clone".
- Shadowbook: 49. Its README: "28 Shadowbook + 21 DirectionalFee".
Next, open each test suite's setUp. Find the line that builds the pool key and the line that initializes the pool.
- Summon: the round does both, inside
fill.setUpopens a round withfactory.openRound(test/SummonRound.t.sol L124). The helpers_startand_fillAfter(L160-L178) start the auction and fill it. - Shadowbook:
initPool(currency0, currency1, IHooks(address(hook)), 0, 60, SQRT_PRICE_1_1)(test/Shadowbook.t.sol L41), a v4 test helper.
What to check
- Both suites pass with 57 and 49 tests at the cited commits.
- You can name the five
PoolKeyfields, and say why the native currency is alwayscurrency0. - You can explain why a dynamic-fee pool whose hook never sets its fee would trade at 0 (
getInitialLPFeereturns 0 for0x800000). - In the table above, each row is a choice a market builder makes; for each project you can point to the source line that makes it.
Next, Lesson 2 opens the PoolManager's unlock and follows a real swap and a real pool seeding through it.