# Open a Uniswap v4 pool that knows its stock's market

Bring a tokenized stock onto Base the way Summon does. Backers pledge. A holder fills at the live price, but only while the market is open. The stock arrives with a Uniswap v4 pool whose hook stops swaps during halts and splits, and charges more after the close.

## What you end up with

Here's where you end up: the Summon page running on your machine, reading live rounds from Base Sepolia. One round is still filling with pledges. A summoned stock is trading in its backers' v4 pool, quoted through the pool and its hook. The screens below are our own run.

- An open round: $50 of $300 pledged. A round only fills at the live price while the market is open. (AMC has no testnet price yet, so this one waits.) (https://fabrknt.com/recipes/stock-aware-pool/round.jpg)
- A summoned stock in its backers' pool: "Pool fee now 1.00%: the US session is closed: 1.00% instead of 0.30%". The quote goes through the hook. (https://fabrknt.com/recipes/stock-aware-pool/pool.jpg)

## Run it (~11 min)

### 1. Check the hook's rules (~5 min)

```bash
git clone --recursive https://github.com/psyto/summon-stocks
cd summon-stocks
forge test
```

You will see:

```
[PASS] test_hookRefusesAnAddressWithoutItsPermissionBits()
[PASS] test_onlyTheRoundInitializesItsPool()
[PASS] test_onlyTheRoundAddsLiquidity()
[PASS] test_swapStopsWhileHalted()
[PASS] test_swapFeeRisesWhileClosed()
[PASS] test_swapStopsWhileTheRegistryDisagrees()
…
59 tests passed, 0 failed
```

The hook uses three permissions: beforeInitialize, beforeAddLiquidity and beforeSwap. Only the round can create the pool or add liquidity, so the position belongs to the backers alone. The hook refuses to deploy at an address whose bits don't match these permissions. Swaps stop while the stock is halted, while the issuer has paused the token, during a corporate action window, or on a stale split multiplier. The fee is 0.30% in session, and 1.00% after the close or while the guard has gone quiet. You need Foundry. No keys, and no network after the clone (the first run may download the compiler).

### 2. Read the price a fill would use (~1 min)

```bash
npm install
npm run guard -- --quote GME SOFI   # read-only: prints, writes nothing
```

You will see:

```
GME 25.605 ±0.05630000000000024 Hyperliquid HIP-3 xyz:GME oracle
SOFI 15.2801 ±1.2156500000000001 Hyperliquid HIP-3 para:SOFI oracle
```

On testnet, the guard posts this reference price for a fill (for a stock listed on Pyth, the round reads Pyth instead). A fill can be at most 1% over it, and only happens while the US market is open. The round checks that onchain, in market-state's registry, which the guard writes to on testnet.

### 3. Open the page on live Base Sepolia rounds (~3 min)

```bash
cd web && npm install
printf 'GEO_BLOCK=off\n' > .dev.vars   # locally; the site is closed to US visitors
npm run build && npx wrangler dev   # open the URL it prints
```

You will see:

```
LIVE NOW · 2 ROUNDS   sAMC Open   sSOFI Filled
Pool fee now 1.00%: the US session is closed: 1.00% instead of 0.30%
```

Every number on the page is read from the chain. Pledges and fills use the round's own math, and swap quotes go through the pool and its hook (Uniswap's V4Quoter). Connecting a wallet and pledging test USDC is optional.

### 4. See a halt stop the pool, on chain (~2 min)

```bash
# no command: open the recorded transactions on Base Sepolia (README, "The full flow", step 7)
# a manual halt → a swap refused → restored → swaps again
```

You will see:

```
halt (manual)  →  swap refused: MarketHalted(5)  →  restored  →  swap succeeds
```

This halt is a simulation. On testnet the guard key writes the registry, and a manual halt (reason 5) stands in for the listing exchange's. The hook read it and refused swaps until it was lifted. A separate recorded run (step 8) shows a 2:1 split. Swaps stop in the window and on the stale multiplier. Then anyone can call realign, so the first trader can't take the difference.

## Why: what went wrong (measured)

- 2026-11-07: Coinbase had registered 298 tokenized stocks (B20) on Base. 227 had never been minted. Some that were minted (DJT, AMC, GME) had no pool to trade in. On 2026-11-14 the counting script read 358 registered and 286 never minted. (https://github.com/psyto/summon-stocks#readme)
- 2026-11-11: While we built it, a stale market-state install read the session as always open, so swaps after the close paid 0.30% instead of 1.00%. The fix went into the part itself: an unknown session name now reads as closed (market-state v0.4.0). (https://github.com/fabrknt/market-state/issues/1)

## Put together: the parts

### 1. The round, the factory and the stock-aware pool hook: Summon

https://github.com/psyto/summon-stocks

SummonRound (pledges, a capped auction, refunds, the LP), SummonFactory, SummonHook (beforeInitialize, beforeAddLiquidity, beforeSwap) and SummonSwap, with 59 Foundry tests. A TypeScript guard and keeper. A Cloudflare Worker page. Apache-2.0, Base Sepolia only.

```bash
git clone --recursive https://github.com/psyto/summon-stocks
```

### 2. Fail closed when the market is closed or halted: market-state

https://github.com/fabrknt/market-state

MarketStateCheck.requireOpen on every auction start and fill, NYSE holidays and early closes, the core-hours session, and a Nasdaq Trader halts guard; the registry fails closed when its updater goes quiet.

```bash
forge install fabrknt/market-state@v0.4.1
```

### 3. Read the reference price safely: HL Price Guard

https://github.com/fabrknt/hl-price-guard

PythRef for the Pyth read and confidence bound, and JumpLatch. Summon needed two more, so we added them to the part instead of working around it: readFresh (v0.3.2), a Pyth-only staleness check, and readFirstAfter (v0.4.0), so a filler can't pick among fresh prints.

```bash
forge install fabrknt/hl-price-guard@v0.4.0
```

## Go deeper, in order

1. [Uniswap v4: hooks](https://docs.uniswap.org/contracts/v4/concepts/hooks): Hook permissions, address flags, and what each callback can do.
2. [Summon's spec (r5) and its review rounds](https://github.com/psyto/summon-stocks/blob/main/docs/specs/001-summon.md): The round, the price math and the stock-aware pool, as reviewed over eight rounds.
3. [market-state](https://github.com/fabrknt/market-state): Halt and session state for tokenized stocks, and why a registry should fail closed.

## Before real money

- Remove any of the 8 fill checks or any of the hook's 6 rules, and a test fails. Keep it that way when you change the hook.
- Run the guard before the open, and confirm the installed market-state reads a weekend and the first 15 minutes as closed. (If it doesn't, the guard won't start.)
- Summon runs on Base Sepolia only. The tokens are test tokens with no value, it isn't audited, the page isn't hosted, and it isn't offered to US persons.
- Every testnet fill was priced from the guard's feed: a Hyperliquid HIP-3 oracle price set by that market's deployer. It's demo data only. The Pyth path is covered by unit tests only.
- It's an entry to Base's Stocks Maxxing quest. It isn't affiliated with or endorsed by Base or Coinbase.
- Who fills on mainnet is still an open question. The keeper is a reference any holder can run, not a committed market maker.

## Run end to end

2026-11-14: We followed it from the public repository. A fresh clone and forge test (57 passed; 58 after b1dd190, which made the hook validate its permission bits; 59 at 8a8b464, 2026-11-14). npm ci without SSH keys. The read-only guard quote shown above. The web page built and served locally, reading live Base Sepolia rounds (the screens above). The halt, split and fee steps are the project's recorded Base Sepolia transactions from 2026-11-11 and 11-12.

Fabrknt is independent and not affiliated with Hyperliquid. The parts are unaudited.
