hookr-sdk 0.2.1 → 1.1.0

package/README.md

@@ -1,17 +1,17 @@
 # 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, the Uniswap v4 hook on Robinhood Chain: launch tokens with Hook Blocks, open pools, quote and swap.
 
-Two roots are live. A pool names exactly one of them in `PoolKey.hooks`:
+The package carries Hookr's contracts, release id `hookr-1`: their addresses, deployment and ABIs, the 22-quote catalog, the bounds of every setting of the core Hook Blocks and advisories, 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)
+- [Wallet Cap](#wallet-cap)
+- [Arb recapture](#arb-recapture)
+- [Gas](#gas)
+- [Quotes](#quotes)
+- [What is in the package](#what-is-in-the-package)
 
 ## Install
 
@@ -19,135 +19,338 @@ 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 pool on Hookr's shared hook is a Uniswap v4 pool whose `PoolKey.hooks` is `HookrRoot`. A hook you deploy through the owned-root factory is an unmodified copy of it at an address of its own, and its pools name that address instead. Either way the pool's 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],
+});
+```
+
+`config` is the pool's `PoolConfig`: its quote, base LP fee and caps, and the HookrRules contract that holds its Hook Blocks, one of the release's [Rules modules](#rules-modules). `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 ([Gas](#gas)). On the Wallet Cap Rules, `blocks.potMinBuyQuote` is the pool's [Wallet Cap](#wallet-cap).
+
+### Quote
 
-console.log(RULES.map((r) => r.key)); // ["snipe", "fee", "burn", "lp", "pot"]
+`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.
 
-const stack = [defaultBlock("fee"), defaultBlock("lp")];
-const { ok, errors } = validateStack(stack);
+```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 });
+
+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.
+
+### Launch a token with Hook Blocks
 
-## Read a market, quote, and swap
+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.
 
-`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.
+Anti-Snipe's launch guard, on by default, counts the blocks the contracts read as `block.number`: Ethereum's, which each Robinhood Chain block carries as `l1BlockNumber`. `readParentBlockNumber` reads it. `getBlockNumber()` is the chain's own, far larger number, and a guard counted from it is one the Rules refuse.
 
 ```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,
+  readParentBlockNumber,
+  rulesAbi,
+  rulesPoolTerms,
+  type Admission,
+} from "hookr-sdk";
+
+const { HookrRegistry, HookrRoot, HookrRules, HookrLauncher } = HOOKR_1.contracts;
+const blockNumber = await readParentBlockNumber(client);
+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 is the current recapture root, so pass the call to
-`writeContract` as it is; on the default root the call carries no `gas` and the wallet estimates
-as usual. A pool opened on a superseded recapture root keeps its executor and keeps correcting;
-read `poolCorrects(await readPoolRules(client, poolId))` and pass it as `correcting` to the swap
-builders to put the same floor on that call (since 0.2.1).
+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`. 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 per currency in each pool's own Rules, the `config.rules` its `poolConfig` names (see [Read a pool](#read-a-pool)), until claimed.
 
 ```ts
-import { claimableCall, claimCall } from "hookr-sdk";
+import { 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: config.rules, abi: rulesAbi, functionName: "claimable", args: [currency, account] });
+if (owed > 0n)
+  await wallet.writeContract({ account, address: config.rules, abi: rulesAbi, functionName: "claim", args: [currency] });
 ```
 
-## Rule catalog
-
-`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.
-
-## Changes
-
-- 0.2.1: 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.
-- 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.
+`claimTo` sends the claim to another address. `claimAsClaims` takes it as Uniswap v4 ERC-6909 claims.
+
+## Addresses
+
+Robinhood Chain, chain id 4663. `HOOKR_1.contracts` holds every address. `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.
+
+| 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` |
+
+Every other contract is in `HOOKR_1.contracts`.
+
+### Rules modules
+
+A pool binds one HookrRules, its `PoolConfig.rules`, and keeps it. Beside the release's own, the registry admits three more on `HookrRoot` on the same terms, each with the HookrRecapture its constructor created. `HOOKR_1.rulesModules` holds all four and `rulesModule(HOOKR_1, name)` names one. The manifest pins each by its runtime code hash, so `readReleaseManifest` refuses one that runs other code.
+
+| Name | Rules | HookrRecapture | What a pool on them runs |
+| --- | --- | --- | --- |
+| `standard` | [`0x4a71c270b1520F94064268102AebD744b0DE7942`](https://robin.etherscan.io/address/0x4a71c270b1520F94064268102AebD744b0DE7942) | [`0xF83569E564d70daebc35950f66a73f2e2B915583`](https://robin.etherscan.io/address/0xF83569E564d70daebc35950f66a73f2e2B915583) | The release's HookrRules |
+| `whole-pot` | [`0x10f684361b35C8411a2c07F68A6fB1F4B7e555F7`](https://robin.etherscan.io/address/0x10f684361b35C8411a2c07F68A6fB1F4B7e555F7) | [`0x60Efc4a41498e9433be2155b6cc1677AEC31D649`](https://robin.etherscan.io/address/0x60Efc4a41498e9433be2155b6cc1677AEC31D649) | The same Rules, where King of the Pool's winner takes the whole pot |
+| `wallet-cap` | [`0xb67b73E28C522a3AAC438bE970bf94976Deee52a`](https://robin.etherscan.io/address/0xb67b73E28C522a3AAC438bE970bf94976Deee52a) | [`0xbbC43DC2f01F5E7882caCd78EF094A44eF0E4d23`](https://robin.etherscan.io/address/0xbbC43DC2f01F5E7882caCd78EF094A44eF0E4d23) | The whole-pot Rules plus [Wallet Cap](#wallet-cap) |
+| `round-trip` | [`0x3d7e31746127FD9a14d3C7fC12E73611D2e8cb34`](https://robin.etherscan.io/address/0x3d7e31746127FD9a14d3C7fC12E73611D2e8cb34) | [`0xddFF6326E5CB9AA98b88e9064d9A9570f777f8A3`](https://robin.etherscan.io/address/0xddFF6326E5CB9AA98b88e9064d9A9570f777f8A3) | Rules that keep a record of who traded in each block, for Buy/Sell Block's round-trip check |
+
+## Wallet Cap
+
+While a launch's guard lasts, no wallet can buy more than the pool's cap of the token, its `rules.potMinBuyQuote`. A pool takes it at launch by binding the `wallet-cap` Rules.
+
+```ts
+import { checkWalletCapLaunch, readWalletCap, rulesModule, walletCapAmount, walletCapPoolTerms, walletCapRevert } from "hookr-sdk";
+
+const walletCap = rulesModule(HOOKR_1, "wallet-cap");
+const capAdmission = await client.readContract({ address: HookrRegistry, abi: ARTIFACT_ABIS.HookrRegistry, functionName: "admission", args: [HookrRoot, walletCap.rules] });
+
+// The defaults keep the launch guard on: 50 parent blocks, about 10 minutes. Until it ends, no wallet buys more than 2% of the supply.
+const capped = defaultRulesLaunch(ctx);
+capped.rules.potMinBuyQuote = walletCapAmount(token.supply, 200);
+const cappedTerms = walletCapPoolTerms(capped, ctx, capAdmission as Admission);
+const cappedMember = {
+  ...member,
+  config: { ...member.config, rules: walletCap.rules, caps: cappedTerms.caps, rulesGasLimit: cappedTerms.rulesGasLimit },
+  rules: capped.rules,
+};
+checkWalletCapLaunch([cappedMember]);
+
+// A pool binds only while its guard has yet to end, so the launch must land well inside it.
+const cappedDeadline = BigInt(Math.floor(Date.now() / 1000) + 300);
+const cappedCall = buildLaunch(manifest, token, HookrRoot, [cappedMember], seed.amount0Max, cappedDeadline, launchFee);
+
+// Once it trades: what a wallet may still buy, until the guard ends at a parent block (readParentBlockNumber).
+const cap = await readWalletCap(client, { poolId: id, wallet: account, subject: tokenAddress });
+if (cap) console.log(`${cap.room} of ${cap.cap} left until parent block ${cap.guardEndBlock}`);
+
+// A buy past the cap fails its quote and its gas estimate with GuardWalletLimit, however the contracts wrapped it.
+try {
+  await client.estimateGas({ account, to: swapCall.to, data: swapCall.data, value: swapCall.value });
+} catch (error) {
+  console.log(walletCapRevert(error) ?? error);
+}
+```
+
+`readWalletCap` reads the pool through the Rules' `extsload`, one storage word at a time, and gives null for a pool on any other Rules. `walletCapPoolSlot` and `walletCapBoughtSlot` give the slots for reads of your own, and `WALLET_CAP_ABI` is what the Wallet Cap Rules add to `rulesAbi`.
+
+## 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 (off by default; up to 50% of it on the standard and round-trip Rules, up to all of it on the whole-pot and Wallet Cap Rules) and the LPs |
+
+The pool's split is frozen at launch. `recaptureSplit` and `recaptureProfit` work it out to the wei; `recaptureSplit` takes a pot of up to 50%. The SDK's builders always open a pool with the pot off. 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.
+
+The lane's switch is not frozen: the registry's owner, or its guardian once one is appointed, can switch the lane off, or lower its gas cap, for every pool that froze it, at once, and the swaps then skip or shrink arb recapture. Switching it back on, or raising the cap, waits in the registry's 30-minute timelock. The switch touches nothing else of the pool.
+
+## 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: a buy through `HookrRouter` on a live lane pool estimates at about 7.5 million.
+
+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 8.8 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
+
+| Source file | What it does |
+| --- | --- |
+| `releases.ts` | `HOOKR_1`: addresses, deployment, the Rules modules, the manifest, `ROBINHOOD_CHAIN`, explorer links, the lane gas floor and the parent block the launch guard counts |
+| `wallet-cap.ts` | Wallet Cap: the cap from a share of supply, a pool's terms and a launch's checks, the reads through `extsload`, and its refusal in plain words |
+| `wallet.ts` | The launcher, router and quoter calls, each checked against its bounds |
+| `launch.ts` | Multi-pool launch, the dev buy and exactly what the launcher pulls |
+| `params.ts` | Every setting of the core Hook Blocks and advisories, with its range and default, and the checks that refuse a value outside them |
+| `rules.ts` | Encodes and checks a pool's Hook Blocks, and prices the Snipe tax, the dynamic fee and the arb recapture split |
+| `quotes.ts` | The quote catalog, quote classes and amounts in each quote's own decimals |
+| `registry.ts` | Typed registry operations and the admission checks |
+| `advisories.ts` | The managed fee and market-hours advisory configs |
+| `abi.ts` | The call ABIs for the root and its lane, the router, quoter, launcher, HookrRules, HookrRecapture, the registry, treasury, programs, referrals and forwarder |
+| `generated.ts` | `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.ts`, `referrals.ts`, `proofs.ts` | Liquidity vault and treasury calls, referral authorizations and reward proofs |
+| `client.ts` | `HookrClient`, for a Hookr service at a URL you give it. Hookr runs no public service. |
+
+Everything but `releases.ts`, `deployments.ts` and `wallet-cap.ts` is the release SDK hookr.fun runs, copied byte for byte. Its quote-admission exports in `registry.ts` are deprecated: HookrRegistry does not have their calls. `provenance.json` names the release's source commit and the hash of every file. Every contract of the release has its source verified at its address on RobinScan and Sourcify.
+
+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