hookr-sdk 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 1.0.0
+
+Hookr 1. The package now builds on the `hookr-1` release on Robinhood Chain: one root, `HookrRoot`, whose pools each freeze their own Hook Blocks and, when they want it, arb recapture.
+
+### What is new
+
+- `HOOKR_1`: every contract of the production release, fixed by CREATE3, and `HOOKR_1.deployment`, the release's deployment as its source verification records it. `CANARY_HOOKR_1_A` names the canary under its own release id. It is not for users.
+- `readReleaseManifest(client, HOOKR_1)`: the manifest every builder takes. It reads the code at each address and refuses it unless it is the code the release deployed. `releaseManifest(HOOKR_1)` builds the same manifest with no reads.
+- `ROBINHOOD_CHAIN`: the chain for viem, on any viem 2, with RobinScan as its explorer.
+- Launch: `buildLaunch` and `buildLaunchAdvised` open one to eight pools of a new or existing token in one call. `buildLaunchFamily` adds a dev buy, supply weights and an opening price check. `launchFunding` lists exactly what a launch pulls.
+- Hook Blocks: `RULE_PARAMS` has every setting with its range and default. `defaultRulesLaunch`, `checkRuleParams` and `rulesPoolTerms` check a pool against the contracts' own bounds before it is sent.
+- Quote and swap: `buildQuote` and `buildSwap` for `HookrQuoter` and `HookrRouter`, `swapAllowance` and `buildApprovals` for ERC-20 input. The quoter also answers Uniswap's `quoteExactInputSingle` and `quoteExactOutputSingle`.
+- Quotes: the 22-quote genesis catalog (`ROBINHOOD_QUOTE_CATALOG`), the 204 Robinhood stock tokens, and `classifyQuote`, `quoteWarnings` and `quoteAdmission`.
+- Arb recapture: Hookr takes 25% of each profit (`RECAPTURE_PROTOCOL_BPS`), What The Hook up to 25% (`MAX_LANE_PARTNER_BPS`), and the rest goes as the pool froze it at launch. `recaptureSplit` works it out. `laneGasFloor` gives the gas a swap needs while a pool's lane is on.
+- ABIs: the call ABIs for the root, router, quoter, launcher, HookrRules, HookrRecapture and the registry, and in `ARTIFACT_ABIS` the full ABIs of the registry, HookrRules, the treasury, the advisories, the liquidity vault, the family contracts and the owned-root contracts. Also the advisories, the registry's typed operations, the liquidity vault, referrals and reward proofs.
+- `provenance.json`: the release's source commit and the hash of every file of the release SDK this package carries.
+
+### Breaking changes from 0.2.x
+
+Of the 0.2.x exports only these carry over: `CHAIN_ID`, `RPC_URL`, `EXPLORER_URL`, `explorerAddressUrl`, `explorerTxUrl`, the `PoolKey` type, `DYNAMIC_FEE`, `MIN_SQRT_PRICE_LIMIT`, `MAX_SQRT_PRICE_LIMIT`, `DEFAULT_PROTOCOL_SHARE_BPS` (2,000), `MAX_PROTOCOL_SHARE_BPS` (5,000) and `MAX_GUARD_BLOCKS` (100,000). `EXPLORER_URL` is now RobinScan, `https://robin.etherscan.io`, where every contract's source is verified, so `explorerAddressUrl` and `explorerTxUrl` open RobinScan. `RootStatus` keeps its name with a new shape: the registry's `rootStatus(root)`, `{ advisory, verified }`. The builders return `{ chainId, to, data, value }` for `sendTransaction`, not `writeContract` arguments, and take the release manifest. Node 18.16 or newer. [MIGRATING.md](https://unpkg.com/hookr-sdk@1/MIGRATING.md) maps the exports in common use. Every other 0.2.x export is removed.
+
+0.2.x keeps working for pools on the earlier roots, `HookrModularHookV6` and `HookrModularHookV6WthV5`.
+
+## 0.2.1 (2026-09-22)
+
+- The swap builders take `correcting` (default `isCorrectingRoot(key.hooks)`, the current recapture root), and `poolCorrects(rules)` reads from a pool's frozen rules whether it names a correction executor, so a pool on a superseded recapture root can carry the gas floor too.
+
+A later 0.2.x change, `listMarkets` reading in windows of at most 5,000 blocks, was never published.
+
+## 0.2.0 (2026-09-21)
+
+- Names both live roots (`ADDRESSES.recaptureRoot`, `RECAPTURE_KERNEL_ID`, `ROOTS`). The market builders take `root` and freeze the recapture correction fields (`RECAPTURE_CORRECTION`). Swap calls carry `gas: CORRECTION_SWAP_GAS_FLOOR` on a correcting root. `listMarkets` scans in windows. `listRoots` reads every registered root from the registry.
+
+## 0.1.0 (2026-09-10)
+
+- First release, default root only.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hookr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATING.md

@@ -0,0 +1,89 @@
+# Moving from 0.2.x to 1.0
+
+1.0 builds on Hookr 1, the `hookr-1` release. 0.2.x builds on the earlier roots. Both sets of pools live on Robinhood Chain, and each package only talks to its own.
+
+## Keep 0.2.x for the earlier roots
+
+Pools on `HookrModularHookV6` (`0xb3cA29cF721380CEe8b8e4755F3865Ebc68Fe8cC`) and `HookrModularHookV6WthV5` (`0xb914f955294799de4b891bd2EA8AF628Fa1c68CC`) keep trading. 0.2.x stays on npm for them:
+
+```
+npm install hookr-sdk@0.2
+```
+
+An app that serves both sets of pools can install both under two names:
+
+```
+npm install hookr-sdk hookr-sdk-v0@npm:hookr-sdk@0.2
+```
+
+Pick by the pool's `PoolKey.hooks`: `HOOKR_1.contracts.HookrRoot` is 1.0's, the two roots above are 0.2.x's.
+
+## What changes
+
+One root instead of two. Arb recapture is no longer a separate root: each pool turns it on or off at launch in its `RecaptureConfig`, on the same `HookrRoot`.
+
+The builders return a call, `{ chainId, to, data, value }`, and take the release's manifest:
+
+```ts
+// 0.2.x
+const call = buildExactInputSwapCall({ key, currencyIn, amountIn, amountOutMinimum, recipient, deadline });
+await walletClient.writeContract(call);
+
+// 1.0
+const manifest = await readReleaseManifest(client, HOOKR_1);
+const call = buildSwap(manifest, { key, zeroForOne, amountSpecified: -amountIn, amountBound: amountOutMinimum, sqrtPriceLimitX96, recipient, deadline });
+await walletClient.sendTransaction({ to: call.to, data: call.data, value: call.value });
+```
+
+## Export by export
+
+| 0.2.x | 1.0 |
+| --- | --- |
+| `ADDRESSES.root`, `ADDRESSES.recaptureRoot`, `ROOTS` | `HOOKR_1.contracts.HookrRoot` |
+| `ADDRESSES.router` | `HOOKR_1.contracts.HookrRouter` |
+| `ADDRESSES.quoter` | `HOOKR_1.contracts.HookrQuoter` |
+| `ADDRESSES.coordinator` | `HOOKR_1.contracts.HookrLauncher` |
+| `ADDRESSES.nativeBlock` | `HOOKR_1.contracts.HookrRules` |
+| `ADDRESSES.registry` | `HOOKR_1.contracts.HookrRegistry` |
+| `KERNEL_ID`, `RECAPTURE_KERNEL_ID`, `MODULE_ID`, `RECAPTURE_CORRECTION`, `isRecaptureRoot` | none: one root, and arb recapture is each pool's `RecaptureConfig`. Pass `RECAPTURE_OFF`, or `recaptureDefaults()` read with `recaptureAbi` at the HookrRules address |
+| `NATIVE_ADDRESS` | `ZERO` |
+| `EXPLORER_URL`, `explorerAddressUrl`, `explorerTxUrl` | the same names, on RobinScan (`https://robin.etherscan.io`) |
+| `DYNAMIC_FEE`, `MIN_SQRT_PRICE_LIMIT`, `MAX_SQRT_PRICE_LIMIT` | the same names and values |
+| `fullFillLimit(zeroForOne)` | `MIN_SQRT_PRICE_LIMIT` for `zeroForOne`, `MAX_SQRT_PRICE_LIMIT` the other way |
+| `swapDirection(key, currencyIn)` | `zeroForOne` is `currencyIn === key.currency0` |
+| `subjectIsCurrency0(subject, quote)` | the lower address is `currency0`, as in every v4 `PoolKey` |
+| `INT128_MAX`, `QUOTE_MIN_OUT_BOUND`, `EMPTY_MODULE_DATA` | none: `amountBound: 1n` on an exact-input quote, and a swap carries no module data |
+| `MAX_TOTAL_FEE_PIPS`, `MIN_BASE_FEE_PIPS`, `baseFeeBounds` | `MAX_LP_FEE_PIPS` (600,000), and `baseLpFeePips` in `RULE_PARAMS.pool`, with its range |
+| `RULES`, `PARAMS`, `RULE_ORDER`, `ruleFor`, `MAX_STACK_RULES`, `defaultBlock`, `defaultStack`, `validateStack`, `compileRuleBlocks` | `RULE_PARAMS`, `defaultRulesLaunch`, `defaultRuleParams`, `checkRuleParams`, `rulesPoolTerms` |
+| `encodeNativeBlockConfig`, `decodeNativeBlockConfig` | `encodeRulesConfig`, `decodeRulesConfig` |
+| `guardEndBlockFor` | `defaultRulesLaunch` sets `guardEndBlock` from the block number. `MAX_GUARD_BLOCKS` keeps its value |
+| `MODULE_GAS`, `stackLimitsFor`, `correctionFor` | `rulesPoolTerms`, which returns the pool's caps and gas |
+| `ZERO_BYTES32` | `zeroHash` from viem |
+| `feeModel` | `rulesQuote`, `rulesSwapFees`, `recaptureSplit` |
+| `poolKeyFor`, `poolIdFor` | a `PoolKey` with `fee: DYNAMIC_FEE` and `hooks: HOOKR_1.contracts.HookrRoot`, and `poolId(key)` |
+| `buildNewTokenMarketCall` | `buildLaunch` with `token.existing` zero |
+| `buildExistingTokenMarketCall` | `buildLaunch` with `token.existing` the token |
+| `encodeMarketCall` | the `data` of the call `buildLaunch` returns |
+| `buildExactInputSwapCall`, `buildExactOutputSwapCall` | `buildSwap`: a negative `amountSpecified` is exact input, a positive one exact output |
+| `quoteExactInput` | `buildQuote`, sent as an `eth_call` from the payer |
+| `CORRECTION_SWAP_GAS_FLOOR`, `swapGasLimit`, `isCorrectingRoot`, `poolCorrects` | `gasFloor` from `laneOf(id)` on `HookrRoot` (`laneRootAbi`), `laneGasFloor(gasCap)` |
+| `readMarket`, `readPoolRules` | `poolConfig(id)` on `HookrRoot` (`rootAbi`), `config(id)` on the pool's HookrRules (`rulesAbi`), `laneOf(id)` (`laneRootAbi`) |
+| `listMarkets`, `listRoots`, `MARKET_CREATED_TOPIC`, `MARKET_SCAN_FROM_BLOCK`, `MARKET_SCAN_CHUNK_BLOCKS`, `MARKET_SCAN_CONCURRENCY` | none: read `PoolOpened` (`rootAbi`) and `MemberLaunched` (`launcherAbi`) with your own log reader |
+| `MAX_LOG_BLOCK_RANGE`, `logBlockRange`, `logBlockRanges`, `capLogSpan` | none: ask for at most 5,000 blocks a request |
+| `claimableCall`, `claimCall`, `claimToCall` | `claimable`, `claim` and `claimTo` on `HookrRules` (`rulesAbi`) |
+| `ReadCall`, `WriteCall`, `RouterCall`, `CoordinatorCall` | `Call`: `{ chainId, to, data, value }` |
+| `builderLink`, `launchLink`, `encodeStack`, `decodeStack`, `decodeStackBaseFeePips`, `DEFAULT_ORIGIN`, `DEFAULT_BASE_FEE_PIPS` | none |
+| `hookrKernelRouterV3Abi`, `hookrKernelQuoterV1Abi`, `hookrMarketCoordinatorV5Abi`, `hookrNativeMechanicsBlockV2Abi`, `hookrStackRegistryV2Abi` | `routerAbi`, `quoterAbi`, `launcherAbi`, `rulesAbi`, `registryAbi`, and the full ABIs in `ARTIFACT_ABIS` |
+| every other 0.2.x export | removed |
+
+`CHAIN_ID`, `RPC_URL`, `PoolKey`, `DYNAMIC_FEE`, `MIN_SQRT_PRICE_LIMIT`, `MAX_SQRT_PRICE_LIMIT`, `DEFAULT_PROTOCOL_SHARE_BPS`, `MAX_PROTOCOL_SHARE_BPS` and `MAX_GUARD_BLOCKS` keep their names and values. `EXPLORER_URL`, `explorerAddressUrl` and `explorerTxUrl` keep their names and open RobinScan, where 0.2.x opened Blockscout. `RootStatus` keeps its name with a new shape.
+
+## Fees and arb recapture
+
+On the earlier recapture roots Hookr and What The Hook each took 10% of an arb recapture's profit. On Hookr 1 each takes 25%: Hookr's `RECAPTURE_PROTOCOL_BPS` is 2,500 and What The Hook keeps at most `MAX_LANE_PARTNER_BPS`, 2,500. The rest is the pool's, as it froze it at launch.
+
+A swap on a Hookr 1 pool with arb recapture on carries the lane's gas floor, 6,802,619 at the lane's 3,000,000 gas cap, where 0.2.x put 1,100,000 on a correcting root. The swap's own gas comes on top, so estimate and add a sixth, or use a fixed limit of at least 7.5 million. See [Gas](https://www.npmjs.com/package/hookr-sdk#gas) in the README.
+
+## Requirements
+
+Node 18.16 or newer, viem 2, ESM. `ROBINHOOD_CHAIN` works on any viem 2. viem's own `robinhood` chain needs viem 2.55 or newer.

package/README.md

@@ -1,17 +1,16 @@
 # hookr-sdk
 
-Build a market on Hookr's live root hooks with a custom rule configuration, quote and swap
-through Hookr's router, read markets, and claim payouts, on Robinhood Chain (id 4663).
+Build on Hookr 1, the Uniswap v4 hook on Robinhood Chain: launch tokens with Hook Blocks, open pools, quote, swap and claim.
 
-Two roots are live. A pool names exactly one of them in `PoolKey.hooks`:
+The package carries the `hookr-1` release: its addresses, its deployment, its ABIs, the 22-quote catalog, every Hook Block's bounds and the builders hookr.fun itself uses. It holds no wallet and signs nothing. Each builder returns `{ chainId, to, data, value }` for your wallet to send.
 
-| Root | Export | What it runs |
-| --- | --- | --- |
-| `HookrModularHookV6` | `ADDRESSES.root`, `ROOTS.default` | the five native rules |
-| `HookrModularHookV6WthV5` | `ADDRESSES.recaptureRoot`, `ROOTS.recapture` | the same five rules plus the arbitrage-recapture lane |
-
-Earlier recapture roots still hold trading pools. Their pools read back like any other, so resolve
-a root from the pool's own `PoolKey.hooks` or from the registry rather than from a list.
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Addresses](#addresses)
+- [Arb recapture](#arb-recapture)
+- [Gas](#gas)
+- [Quotes](#quotes)
+- [What is in the package](#what-is-in-the-package)
 
 ## Install
 
@@ -19,129 +18,317 @@ a root from the pool's own `PoolKey.hooks` or from the registry rather than from
 npm install hookr-sdk viem
 ```
 
-## RPC
+ESM only, with TypeScript types. Node 18.16 or newer and viem 2. `ROBINHOOD_CHAIN` is the chain for viem, with RobinScan as its explorer. On viem 2.55 or newer, `robinhood` from `viem/chains` is the same chain with Blockscout as its explorer.
+
+## Quick start
+
+### Set up
 
-`RPC_URL` is the chain's public, keyless endpoint. It is fine for a few reads. Under load it rate
-limits, and a wide `eth_getLogs` can come back as an empty array instead of an error. `listMarkets`
-scans in windows of `MARKET_SCAN_CHUNK_BLOCKS` (3,000,000 blocks, the width the app's own scanners
-use; pass `chunkBlocks` to lower it) so no single answer is wide, but anything that must not miss
-data should still run on a provider endpoint you own:
+Every builder takes the release's manifest: each contract it calls, at its address, with its runtime code hash. `readReleaseManifest` reads that code from chain and refuses it unless every contract runs the code the release deployed.
 
 ```ts
-import { http } from "viem";
-import { RPC_URL } from "hookr-sdk";
+import "viem/window";
+import { createPublicClient, createWalletClient, custom, http } from "viem";
+import { HOOKR_1, ROBINHOOD_CHAIN, readReleaseManifest } from "hookr-sdk";
 
-const transport = http(process.env.HOOKR_RPC_URL ?? RPC_URL);
+const client = createPublicClient({ chain: ROBINHOOD_CHAIN, transport: http() });
+const wallet = createWalletClient({ chain: ROBINHOOD_CHAIN, transport: custom(window.ethereum!) });
+const [account] = await wallet.getAddresses();
+
+const manifest = await readReleaseManifest(client, HOOKR_1);
 ```
 
-## List and validate rules
+`releaseManifest(HOOKR_1)` builds the same manifest from the package alone, with no reads.
+
+`http()` uses the chain's public node. It is fine for a few reads. Anything that scans logs or must not miss data should use a provider endpoint of its own.
+
+### Read a pool
+
+A Hookr pool is a Uniswap v4 pool whose `PoolKey.hooks` is `HookrRoot`. Its fee is `DYNAMIC_FEE`: the hook sets the LP fee on every swap.
 
 ```ts
-import { RULES, PARAMS, defaultBlock, validateStack } from "hookr-sdk";
+import { DYNAMIC_FEE, HOOKR_1, ZERO, laneRootAbi, poolId, rootAbi, rulesAbi, type PoolKey } from "hookr-sdk";
+
+const key: PoolKey = {
+  currency0: ZERO, // native ETH sorts first
+  currency1: tokenAddress,
+  fee: DYNAMIC_FEE,
+  tickSpacing: 60,
+  hooks: HOOKR_1.contracts.HookrRoot,
+};
+const id = poolId(key);
+
+const config = await client.readContract({ address: HOOKR_1.contracts.HookrRoot, abi: rootAbi, functionName: "poolConfig", args: [id] });
+const blocks = await client.readContract({ address: config.rules, abi: rulesAbi, functionName: "config", args: [id] });
+const [executor, codeHash, partnerBps, family, laneOn, gasCap, gasFloor] = await client.readContract({
+  address: HOOKR_1.contracts.HookrRoot,
+  abi: laneRootAbi,
+  functionName: "laneOf",
+  args: [id],
+});
+```
 
-console.log(RULES.map((r) => r.key)); // ["snipe", "fee", "burn", "lp", "pot"]
+`config` is the pool's `PoolConfig`: its quote, base LP fee and caps, and the HookrRules contract that holds its Hook Blocks. `blocks` is those Hook Blocks as frozen at launch: Anti-Snipe, the dynamic fee, Auto Burn, LP Rewards, the royalty and the protocol share. `laneOn` says whether arb recapture runs on the pool, and `gasFloor` is the least gas a swap must carry while it does. See [Gas](#gas).
 
-const stack = [defaultBlock("fee"), defaultBlock("lp")];
-const { ok, errors } = validateStack(stack);
+### Quote
+
+`HookrQuoter` simulates the swap through the pool's own callbacks, so the quote is what the swap pays and gets, fees and Hook Blocks included. Send it as an `eth_call` from the real payer.
+
+```ts
+import { decodeFunctionResult, parseEther } from "viem";
+import { MIN_SQRT_PRICE_LIMIT, buildQuote, quoterAbi } from "hookr-sdk";
+
+const swap = {
+  key,
+  zeroForOne: true, // ETH in, token out
+  amountSpecified: -parseEther("0.1"), // negative: exact input
+  amountBound: 1n, // the least out, set from the quote below
+  sqrtPriceLimitX96: MIN_SQRT_PRICE_LIMIT, // fill in full; MAX_SQRT_PRICE_LIMIT the other way
+  recipient: account,
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 600), // at most an hour ahead
+};
+
+const quote = buildQuote(manifest, swap, account);
+const { data } = await client.call({ account, to: quote.to, data: quote.data });
+const receipt = decodeFunctionResult({ abi: quoterAbi, functionName: "quote", data: data! });
+// receipt.outputAmount, receipt.quoteFee, receipt.subjectBurn, receipt.lpFeePips
 ```
 
-## Build and send a create-market call
+### Swap
 
-A market opens on the default root unless `root: ROOTS.recapture` is passed. On the recapture
-root the builder also freezes the five correction fields of the stack (`RECAPTURE_CORRECTION`
-plus the creator), without which the pool would carry that root's name and never correct. The
-registry admits that lane on native-ETH-quoted pools only, so the builder throws on any other
-quote, and it needs `creator` (the launching wallet) to freeze as the correction creator.
+`buildSwap` calls `HookrRouter.swap`. Native ETH in rides as the call's value. An ERC-20 in needs an allowance to the router first: `swapAllowance` says how much, `buildApprovals` builds the calls.
 
 ```ts
-import { createWalletClient, http } from "viem";
-import { CHAIN_ID, NATIVE_ADDRESS, ROOTS, buildExistingTokenMarketCall } from "hookr-sdk";
+import { buildSwap } from "hookr-sdk";
 
-const call = buildExistingTokenMarketCall({
-  subject: token, quote: usdcAddress, tickSpacing: 60, sqrtPriceX96,
-  rules: { baseFeePips: 3_000, blocks: stack },
-  protocolRecipient, protocolShareBps, caps, // read from the coordinator and native block first
-});
-const hash = await walletClient.writeContract(call);
-
-// The same market on the recapture root: native ETH quote, and the creator wallet.
-const recaptureCall = buildExistingTokenMarketCall({
-  subject: token, quote: NATIVE_ADDRESS, tickSpacing: 60, sqrtPriceX96,
-  rules: { baseFeePips: 3_000, blocks: stack },
-  protocolRecipient, protocolShareBps, caps,
-  root: ROOTS.recapture, creator: account.address,
-});
+const minOut = (receipt.outputAmount * 995n) / 1000n; // 0.5% slippage
+const swapCall = buildSwap(manifest, { ...swap, amountBound: minOut });
+
+// With arb recapture on, the estimate includes the lane's gas floor, so it runs above 7.4 million.
+const estimate = await client.estimateGas({ account, to: swapCall.to, data: swapCall.data, value: swapCall.value });
+const hash = await wallet.sendTransaction({ account, to: swapCall.to, data: swapCall.data, value: swapCall.value, gas: estimate + estimate / 6n });
 ```
 
-`caps` comes from `nativeMechanicsBlock.validateStack(...)`; `protocolShareBps` from
-`marketCoordinator.protocolShareBps(creator)`. See `market.ts`'s module doc for what this
-package computes and what it takes as an already-resolved input.
+When the estimate fails, the swap would revert as built. Check the quote, the allowance and the deadline before you try again.
 
-## Read a market, quote, and swap
+### Launch a token with Hook Blocks
 
-`poolKeyFor` defaults `hooks` to the default root. Pass `hooks: ADDRESSES.recaptureRoot` for a
-pool on the recapture root, or use the `kernel` a `readMarket` row carries.
+One launch creates the token and opens its pools, each with its own Hook Blocks, frozen when the pool opens. `defaultRulesLaunch` sets every block to its default. Change what you want, and `rulesPoolTerms` checks every value against the contracts' bounds and returns the pool's caps and gas.
 
 ```ts
-import { createPublicClient, http } from "viem";
-import { ADDRESSES, readMarket, poolKeyFor, quoteExactInput, buildExactInputSwapCall } from "hookr-sdk";
-
-const client = createPublicClient({ transport });
-const market = await readMarket(client, poolId);
-const key = poolKeyFor({
-  subject: market.subject, quote: market.quote, tickSpacing: market.tickSpacing,
-  hooks: market.kernel, // ADDRESSES.root or ADDRESSES.recaptureRoot
-});
-const { amountOut } = await quoteExactInput(client, { key, user, currencyIn: market.quote, amountIn });
-const swapCall = buildExactInputSwapCall({ key, currencyIn: market.quote, amountIn, amountOutMinimum, recipient: user, deadline });
+import { zeroHash } from "viem";
+import {
+  ARTIFACT_ABIS,
+  HOOKR_1,
+  RECAPTURE_OFF,
+  ZERO,
+  buildLaunch,
+  defaultRulesLaunch,
+  launchFeeAbi,
+  rulesAbi,
+  rulesPoolTerms,
+  type Admission,
+} from "hookr-sdk";
+
+const { HookrRegistry, HookrRoot, HookrRules, HookrLauncher } = HOOKR_1.contracts;
+const blockNumber = await client.getBlockNumber();
+const [open, admission, minProtocolShareBps, [launchFee]] = await Promise.all([
+  client.readContract({ address: HookrRegistry, abi: ARTIFACT_ABIS.HookrRegistry, functionName: "rootOpenFor", args: [HookrRoot, account] }),
+  client.readContract({ address: HookrRegistry, abi: ARTIFACT_ABIS.HookrRegistry, functionName: "admission", args: [HookrRoot, HookrRules] }),
+  client.readContract({ address: HookrRules, abi: rulesAbi, functionName: "minProtocolShareBps" }),
+  client.readContract({ address: HookrLauncher, abi: launchFeeAbi, functionName: "launchFee" }),
+]);
+if (!open) throw new Error("The root takes no launch from this wallet now");
+
+// Your opening price and range. ETH is currency0, so amount0Max is the ETH you seed.
+const seed = { sqrtPriceX96, tickLower, tickUpper, liquidity, amount0Max, amount1Max };
+const ctx = {
+  blockNumber,
+  minProtocolShareBps,
+  launchLiquidity: seed.liquidity,
+  launchSqrtPriceX96: seed.sqrtPriceX96,
+  quoteIsCurrency0: true,
+  liquidityOwner: HookrLauncher,
+};
+
+const settings = defaultRulesLaunch(ctx);
+settings.rules.burnBps = 50; // Auto Burn, in basis points
+settings.rules.lpBps = 300; // LP Rewards, in basis points
+const terms = rulesPoolTerms(settings, ctx, admission as Admission);
+
+const member = {
+  quote: ZERO,
+  tickSpacing: settings.tickSpacing,
+  ...seed,
+  config: {
+    subject: ZERO, // the launcher fills in the token
+    quote: ZERO,
+    rules: HookrRules,
+    advisory: ZERO,
+    liquidityOwner: HookrLauncher,
+    baseLpFeePips: settings.baseLpFeePips,
+    caps: terms.caps,
+    rulesGasLimit: terms.rulesGasLimit,
+    advisoryGasLimit: terms.advisoryGasLimit,
+    advisoryPhases: terms.advisoryPhases,
+    advisoryFailOpen: false,
+    policyId: zeroHash,
+  },
+  rules: settings.rules,
+  recapture: RECAPTURE_OFF,
+};
+
+const token = { existing: ZERO, name: "Hook", symbol: "HOOK", supply: 10n ** 27n, salt };
+const deadline = BigInt(Math.floor(Date.now() / 1000) + 600);
+const launchCall = buildLaunch(manifest, token, HookrRoot, [member], seed.amount0Max, deadline, launchFee);
+await wallet.sendTransaction({ account, to: launchCall.to, data: launchCall.data, value: launchCall.value });
 ```
 
-A swap on a recapture pool needs more gas than an estimate reports, because the correction is
-fail-open: an estimate converges on the cheapest swap that succeeds, which is the one that skipped
-the correction. The swap builders put `gas: CORRECTION_SWAP_GAS_FLOOR` (1,100,000, the app's
-floor) on the call whenever the pool's root corrects, so pass the call to `writeContract` as it
-is; on the default root the call carries no `gas` and the wallet estimates as usual.
+One launch opens one to eight pools of the same token, each on its own quote: pass more members. `buildLaunchAdvised` binds an advisory per pool, and `buildLaunchFamily` adds a dev buy, supply weights and an opening price check. `HookrLauncher.predictToken(creator, token)` gives the token's address before you send.
+
+A member with arb recapture on takes the release's default `RecaptureConfig` in place of `RECAPTURE_OFF`, once the root's lane is open. Read it with `recaptureAbi` at the HookrRules address: `recaptureDefaults()` belongs to HookrRecapture, which HookrRules reaches for every call it does not handle itself.
+
+```ts
+import { recaptureAbi } from "hookr-sdk";
+
+const [recapture] = await client.readContract({ address: HookrRules, abi: recaptureAbi, functionName: "recaptureDefaults" });
+const recaptureMember = { ...member, recapture };
+```
 
-## Roots
+### Open pools for an existing token
 
-`ROOTS` names the two roots Hookr opens markets on today. The registry itself never retires a
-root, so `listRoots` shows every kernel it has registered, current or not, with its status and
-whether its profile is sealed (the coordinator opens markets on sealed profiles only):
+The same launch, with the token named and nothing to mint. The launcher pulls the token side of each pool, so approve it first: `launchFunding` lists every allowance the launch needs.
 
 ```ts
-import { listRoots } from "hookr-sdk";
+import { buildApprovals, launchFunding } from "hookr-sdk";
 
-for (const root of await listRoots(client)) {
-  console.log(root.hook, root.status, root.sealed ? "sealed" : "unsealed");
-}
+const existing = { existing: tokenAddress, name: "", symbol: "", supply: 0n, salt: zeroHash };
+const funding = launchFunding(manifest, tokenAddress, true, [member], launchFee);
+for (const allowance of funding.allowances)
+  for (const approve of buildApprovals(manifest, allowance, currentAllowance))
+    await wallet.sendTransaction({ account, to: approve.to, data: approve.data });
+
+const openCall = buildLaunch(manifest, existing, HookrRoot, [member], seed.amount0Max, deadline, launchFee);
 ```
 
-Pools on any of those roots read, quote and swap through this package when their root's address is
-passed as `hooks`; only market creation is limited to `ROOTS`.
+`HookrLauncher.memberKey(subject, quote, tickSpacing, root)` gives each pool's `PoolKey` and whether it is still free.
+
+### Claim
 
-## Claim
+Royalties, integrator fees and a trader's arb recapture rebate are held in `HookrRules`, per currency, until claimed.
 
 ```ts
-import { claimableCall, claimCall } from "hookr-sdk";
+import { HOOKR_1, rulesAbi } from "hookr-sdk";
 
-const owed = await client.readContract(claimableCall(quoteAddress, account));
-if (owed > 0n) await walletClient.writeContract(claimCall(quoteAddress));
+const owed = await client.readContract({ address: HOOKR_1.contracts.HookrRules, abi: rulesAbi, functionName: "claimable", args: [currency, account] });
+if (owed > 0n)
+  await wallet.writeContract({ account, address: HOOKR_1.contracts.HookrRules, abi: rulesAbi, functionName: "claim", args: [currency] });
 ```
 
-## Rule catalog
+`claimTo` sends the claim to another address. `claimAsClaims` takes it as Uniswap v4 ERC-6909 claims.
 
-`RULES` and `PARAMS` are this package's own machine-readable list of the five public rules and
-their bounds, and the same list is served live at https://hookr.fun/api/hooks/catalog together
-with the roots and contract addresses, the fee model, the composition limits and prefilled
-builder links for example configurations. Both come from the same source in the Hookr app, and a
-parity test in that repository keeps the package and the app in step.
+## Addresses
 
-## Changes
+Robinhood Chain, chain id 4663. Every address is fixed by CREATE3 from the release deployer, the release id and the contract's name, so it is the same before and after deployment. `HOOKR_1.contracts` holds them all. `HOOKR_1.deployment` holds the deployment: the block the manifest starts from and its hash, each contract's runtime code hash, and the hash of the release's source verification on Blockscout. Each address below opens on RobinScan, where its source is verified.
 
-- 0.2.0: names both live roots (`ADDRESSES.recaptureRoot`, `RECAPTURE_KERNEL_ID`, `ROOTS`); the
-  market builders take `root` and freeze the recapture correction fields (`RECAPTURE_CORRECTION`);
-  swap calls carry `gas: CORRECTION_SWAP_GAS_FLOOR` on a correcting root; `listMarkets` scans in
-  windows (`MARKET_SCAN_CHUNK_BLOCKS`, `chunkBlocks`); `listRoots` reads every registered root
-  from the registry; documents the public RPC's limits. The README on npm for 0.1.0 had drifted
-  from the repository.
-- 0.1.0: first release, default root only.
+| Contract | `hookr-1` | What it does |
+| --- | --- | --- |
+| HookrRoot | [`0x89c9FB50d1f03192230FFB1c279BB6E7d3Fe6aCc`](https://robin.etherscan.io/address/0x89c9FB50d1f03192230FFB1c279BB6E7d3Fe6aCc) | The hook each pool names in `PoolKey.hooks` |
+| HookrRouter | [`0xC2Bc9a3fe6c4Ce8C2F7EB4655b0869b01D8c93C9`](https://robin.etherscan.io/address/0xC2Bc9a3fe6c4Ce8C2F7EB4655b0869b01D8c93C9) | Swaps through a Hookr pool |
+| HookrQuoter | [`0x445D7891381Aa7F91F5048EdBC6a611ccBDe7865`](https://robin.etherscan.io/address/0x445D7891381Aa7F91F5048EdBC6a611ccBDe7865) | Quotes a swap with the pool's own callbacks |
+| HookrLauncher | [`0x1cf2748A6670572425eAbf9Ab9e5BC4eb2eB8Ef4`](https://robin.etherscan.io/address/0x1cf2748A6670572425eAbf9Ab9e5BC4eb2eB8Ef4) | Opens a token's pools in one launch |
+| HookrRules | [`0x4a71c270b1520F94064268102AebD744b0DE7942`](https://robin.etherscan.io/address/0x4a71c270b1520F94064268102AebD744b0DE7942) | Holds each pool's Hook Blocks and pays its fees |
+| HookrRegistry | [`0x463c82beA1a52F4Cc05ca0741a24F0AD24bA4602`](https://robin.etherscan.io/address/0x463c82beA1a52F4Cc05ca0741a24F0AD24bA4602) | Admits roots, Hook Blocks, advisories and quotes, behind the owner's timelock |
+| HookrTreasury | [`0x2242F7FC75606500503075f29ea8cDA684EfB4a9`](https://robin.etherscan.io/address/0x2242F7FC75606500503075f29ea8cDA684EfB4a9) | Holds Hookr's share and the integrator list |
+| HookrForwarder | [`0xe7863CC0E2Fb783b44c279aB159bcD812c2ceA1c`](https://robin.etherscan.io/address/0xe7863CC0E2Fb783b44c279aB159bcD812c2ceA1c) | Runs a signed swap for a relayer |
+| PoolManager | [`0x8366a39CC670B4001A1121B8F6A443A643e40951`](https://robin.etherscan.io/address/0x8366a39CC670B4001A1121B8F6A443A643e40951) | Uniswap v4's PoolManager, `POOL_MANAGER` |
+
+The rest of the release:
+
+| Contract | `hookr-1` |
+| --- | --- |
+| HookrRegistryChecks | [`0xB9F5c54E5Cc7ac6c7a96335E5A334Cf4eA496E98`](https://robin.etherscan.io/address/0xB9F5c54E5Cc7ac6c7a96335E5A334Cf4eA496E98) |
+| HookrRegistryAdmin | [`0x675ac2102E8c69E2467F64656E3c235AF3901Ac1`](https://robin.etherscan.io/address/0x675ac2102E8c69E2467F64656E3c235AF3901Ac1) |
+| HookrLaunchChecks | [`0x8567369a70100828611BB6F44ec051B48F10fb59`](https://robin.etherscan.io/address/0x8567369a70100828611BB6F44ec051B48F10fb59) |
+| HookrTokenDeployer | [`0x1B23D6d7beBcB61E39317E9F0Bc02AEB91aFCcAe`](https://robin.etherscan.io/address/0x1B23D6d7beBcB61E39317E9F0Bc02AEB91aFCcAe) |
+| HookrReferralRegistry | [`0xefD1DfBA80c06E72F793601706c3a1c71aab3057`](https://robin.etherscan.io/address/0xefD1DfBA80c06E72F793601706c3a1c71aab3057) |
+| HookrProgramsAdmin | [`0x40B40D65543E70a9C757eda1A2208517a8BC7292`](https://robin.etherscan.io/address/0x40B40D65543E70a9C757eda1A2208517a8BC7292) |
+| HookrPrograms | [`0x9fA204AC99176782Fd20615b2b2A516D1F8C328F`](https://robin.etherscan.io/address/0x9fA204AC99176782Fd20615b2b2A516D1F8C328F) |
+| HookrMilestoneNFTFactory | [`0xa340F964F1E685c681dC3ABB5B0405E608914d00`](https://robin.etherscan.io/address/0xa340F964F1E685c681dC3ABB5B0405E608914d00) |
+| HookrProgramValidator | [`0x33e0249083Be7Cd8bD2fe175E0671AcfD0516850`](https://robin.etherscan.io/address/0x33e0249083Be7Cd8bD2fe175E0671AcfD0516850) |
+| HookrReferralDistributor | [`0x690539c53212899A9c6AEEE3b4B6737A5c4851d9`](https://robin.etherscan.io/address/0x690539c53212899A9c6AEEE3b4B6737A5c4851d9) |
+| HookrLane | [`0x9A8a1006469BA196f8FEfc017a53505C83A060BB`](https://robin.etherscan.io/address/0x9A8a1006469BA196f8FEfc017a53505C83A060BB) |
+| HookrRecapture | [`0xF83569E564d70daebc35950f66a73f2e2B915583`](https://robin.etherscan.io/address/0xF83569E564d70daebc35950f66a73f2e2B915583) |
+| HookrFamilyRouter | [`0x854f3Fa7AC342B244DF0d9A8c8F597b051aAE559`](https://robin.etherscan.io/address/0x854f3Fa7AC342B244DF0d9A8c8F597b051aAE559) |
+| HookrFamilyLock | [`0xfAFEcE64099C1E791C4B46189c277f00c0c7e00b`](https://robin.etherscan.io/address/0xfAFEcE64099C1E791C4B46189c277f00c0c7e00b) |
+| HookrCompliance | [`0x9D205e8a68464761A9d84bdeCcEa0C3CB1e7B1EC`](https://robin.etherscan.io/address/0x9D205e8a68464761A9d84bdeCcEa0C3CB1e7B1EC) |
+| HookrComplianceGuard | [`0x6CD70db1ac99344416a6fD7184e23FA8f09f313A`](https://robin.etherscan.io/address/0x6CD70db1ac99344416a6fD7184e23FA8f09f313A) |
+| HookrAccountCalls | [`0x0579a95A7760070E2d6D34e5beCe571e5F1c4818`](https://robin.etherscan.io/address/0x0579a95A7760070E2d6D34e5beCe571e5F1c4818) |
+| HookrPaymasterAdmin | [`0x1d81F4B131832f741392edf7B91b4CF099FbB008`](https://robin.etherscan.io/address/0x1d81F4B131832f741392edf7B91b4CF099FbB008) |
+| HookrPaymaster | [`0x1c4682915092E742231ea038C4fcA61e96a83c99`](https://robin.etherscan.io/address/0x1c4682915092E742231ea038C4fcA61e96a83c99) |
+| HookrRootFactory | [`0x21E438FaBE10770afb4407cF6b09d32369CBdCE4`](https://robin.etherscan.io/address/0x21E438FaBE10770afb4407cF6b09d32369CBdCE4) |
+| HookrSessionAdvisory | [`0x78Bc6b7302Dda8632e661c8d74966bdBea1c66b1`](https://robin.etherscan.io/address/0x78Bc6b7302Dda8632e661c8d74966bdBea1c66b1) |
+| HookrFeeAdvisory | [`0x3B6b3f00684987B831fcF9EB5f0d5B806afF7306`](https://robin.etherscan.io/address/0x3B6b3f00684987B831fcF9EB5f0d5B806afF7306) |
+| HookrLiquidityVault | [`0xA408923EF811945Ef119Bc700B1950Dab65467Fc`](https://robin.etherscan.io/address/0xA408923EF811945Ef119Bc700B1950Dab65467Fc) |
+| HookrOwnedProfiles | [`0xb46c318B6AEA2d6274f5566da414b09fDa6CC325`](https://robin.etherscan.io/address/0xb46c318B6AEA2d6274f5566da414b09fDa6CC325) |
+| HookrOwnedRootsLens | [`0x6Bb5c9d21dD095F788cb8373d0143429ad277366`](https://robin.etherscan.io/address/0x6Bb5c9d21dD095F788cb8373d0143429ad277366) |
+| HookrOwnedRootFactory | [`0xA6c2a401597301dFf57A59bC8F70a9622499f3ec`](https://robin.etherscan.io/address/0xA6c2a401597301dFf57A59bC8F70a9622499f3ec) |
+| HookrLpBoost | [`0x52536F5F4E5BC7cEA2197c8F1BB49bf2B133E7f1`](https://robin.etherscan.io/address/0x52536F5F4E5BC7cEA2197c8F1BB49bf2B133E7f1) |
+
+`CANARY_HOOKR_1_A` is the canary, release `canary-hookr-1-a`: the same contracts at their own addresses, deployed first to prove the release. Its root is `0x4C0904bfbdaEC6AA847C36BBf395E5f61325eacc`. It is not for users. Build on `HOOKR_1`.
+
+## Arb recapture
+
+A pool with arb recapture on lets What The Hook's executor close the price gap between the pool and outside venues inside the trader's own swap, and pays the profit out:
+
+| Who | Share of each profit |
+| --- | --- |
+| Hookr | 25% (`RECAPTURE_PROTOCOL_BPS`, 2,500) |
+| What The Hook | up to 25% (`MAX_LANE_PARTNER_BPS`, 2,500), what its executor keeps |
+| The pool | the rest: the trader's rebate (0 to 50% of it, 25% by default), the King of the Pool pot (0 to 50% of it, off by default) and the LPs |
+
+The pool's split is frozen at launch. `recaptureSplit` and `recaptureProfit` work it out to the wei. The LPs' part is released over `releaseBlocks` L2 blocks: 1,200 to 864,000, 36,000 by default. The release counts at most 10 of them a second, so 36,000 blocks take at least an hour.
+
+## Gas
+
+A swap on a pool with arb recapture on must carry the lane's gas floor, or it reverts `InsufficientLaneGas`. The floor is `2 × gasCap + gasCap / 63 + 755,000`: `laneGasFloor(gasCap)` here, `gasFloor` from `laneOf(id)` on chain. At the lane's 3,000,000 gas cap it is 6,802,619. The swap's own gas comes on top: in the release rehearsal, a lane swap through `HookrRouter` needed a gas limit of 7,419,835.
+
+Estimate and add a sixth, as the [Swap](#swap) example does. The estimate already includes the floor, which is why it is high. If your wallet sets a fixed limit, use at least 7.5 million on such a pool. A wallet pays for the gas used, not the limit. A pool without arb recapture has no floor.
+
+## Quotes
+
+A pool may quote in native ETH, any of the 22 tokens on the genesis catalog, any Robinhood stock token, and any other token the registry admits. `ROBINHOOD_QUOTE_CATALOG` is the catalog in the registry's order, each entry read from chain at block 81,225,166: address, symbol, decimals and runtime code hash. `classifyQuote` labels any address, `quoteWarnings` says what to tell a user, and `quoteAdmission` asks the registry whether a quote is admitted right now.
+
+## What is in the package
+
+| Module | What it does |
+| --- | --- |
+| `releases` | `HOOKR_1` and the canary: addresses, deployment, the manifest, `ROBINHOOD_CHAIN`, explorer links and the lane gas floor |
+| `wallet` | The launcher, router and quoter calls, each checked against its bounds |
+| `launch` | Multi-pool launch, the dev buy and exactly what the launcher pulls |
+| `params` | Every Hook Block setting with its range and default, and the checks that refuse a value outside them |
+| `rules` | Encodes and checks a pool's Hook Blocks, and prices the Snipe tax, the dynamic fee and the arb recapture split |
+| `quotes` | The quote catalog, quote classes and amounts in each quote's own decimals |
+| `registry` | Typed registry operations and the admission checks |
+| `advisories` | The managed fee and market-hours advisory configs |
+| `abi` | The call ABIs for the root and its lane, the router, quoter, launcher, HookrRules, HookrRecapture, the registry, treasury, programs, referrals and forwarder |
+| `generated` | `ARTIFACT_ABIS`, the full ABIs of the registry, HookrRules, the treasury, the root factory and pair root, the fee and session advisories, the liquidity vault, the family contracts, LP Boost and the owned-root contracts, and the constants the encoders use |
+| `vault`, `referrals`, `proofs` | Liquidity vault and treasury calls, referral authorizations and reward proofs |
+| `client` | `HookrClient`, which reads a Hookr service and checks the service serves the release it expects |
+
+Everything but `releases` and `deployments` is the release SDK hookr.fun runs, copied byte for byte. `provenance.json` names the release's source commit and the hash of every file. Every contract's source is verified at its address on RobinScan and Sourcify.
+
+`releaseManifest` and `readReleaseManifest` build the manifest the builders read. It is not a Hookr service's manifest: give `HookrClient` the release id and manifest hash the service publishes.
+
+Before you send a call, check the wallet's chain, the payer, the token approvals, the deadline and the slippage yourself. A quote simulates the pool's accounting. It does not prove approvals, balances or gas. Treat token names and links as untrusted display text.
+
+## Links
+
+- Docs: [hookr.fun/docs](https://hookr.fun/docs)
+- Explorer: [RobinScan](https://robin.etherscan.io)
+- Moving from 0.2.x: [MIGRATING.md](https://unpkg.com/hookr-sdk@1/MIGRATING.md), in the package
+- Changes: [CHANGELOG.md](https://unpkg.com/hookr-sdk@1/CHANGELOG.md), in the package
+
+## License
+
+MIT