hookr-sdk 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -1,8 +1,44 @@
 # Changelog
 
+## 1.1.1
+
+README only, no code changes. 1.1.0's README said the SDK's builders always open a pool with the pot off. `defaultRulesLaunch` does, and `checkRulesConfig` refuses a pot, but `buildLaunch` encodes the Rules config you pass it, pot included.
+
+## 1.1.0
+
+The Rules modules `HookrRoot` admits beside the release's own, and Wallet Cap, which runs on one of them.
+
+### What is new
+
+- `HOOKR_1.rulesModules`: `standard`, the release's HookrRules; `whole-pot`, where King of the Pool's winner takes the whole pot (`0x10f684361b35C8411a2c07F68A6fB1F4B7e555F7`); `wallet-cap`, HookrRulesWalletCap (`0xb67b73E28C522a3AAC438bE970bf94976Deee52a`); and `round-trip`, HookrRulesRoundTrip (`0x3d7e31746127FD9a14d3C7fC12E73611D2e8cb34`), which keeps a record of who traded in each block for Buy/Sell Block's round-trip check. These are the four Rules the registry admits on `HookrRoot`. Each comes with the HookrRecapture its constructor created and both runtime code hashes. `rulesModule(release, name)` names one and `otherRulesModules(release)` lists those beside the release's Rules. `releaseManifest` pins each as one more `rules` pin, so the builders that name a Rules take it, and `readReleaseManifest` reads their code and refuses any other.
+- Wallet Cap: while a launch's guard lasts, no wallet buys more than the pool's cap of the token. `walletCapAmount` turns a share of the supply into the cap. `checkWalletCapRulesConfig` and `walletCapPoolTerms` check a pool on the Wallet Cap Rules and give its caps, gas and rules data with the cap. `checkWalletCapLaunch` holds a launch's pools to one cap and to arb recapture on every pool or none. `readWalletCap` reads a pool's launch, guard end and cap, and a wallet's count and room, through the Rules' `extsload` (`walletCapPoolSlot`, `walletCapBoughtSlot`, `walletCapLaunch`, `RULES_SLOT`). `walletCapRefusal` and `walletCapRevert` find `GuardWalletLimit` inside the root's, the PoolManager's and the quoter's wrappers. `WALLET_CAP_ABI` is `extsload` and `GuardWalletLimit`, what the Wallet Cap Rules add to `rulesAbi`.
+- `readParentBlockNumber`: the block number the contracts read as `block.number`, Ethereum's, from the latest block's `l1BlockNumber`. Anti-Snipe's launch guard counts these blocks.
+- `kingOfThePoolPrizeBound`: `kingOfTheHillPrizeBound` under King of the Pool's name.
+
+### Fixed
+
+- The README's launch example counted the launch guard from `getBlockNumber()`, the chain's own block number, so the guard the defaults turn on ended far past the 100,000 parent blocks the Rules accept, and the launch would revert. It reads `readParentBlockNumber` now.
+- The README's claim example read the release's HookrRules, so it showed nothing owed on a pool of another Rules module. It reads the pool's own Rules, `config.rules`, now.
+- The README, MIGRATING.md and `laneGasFloor`'s comment said a fixed gas limit of 7.5 million is enough on a pool with arb recapture on. A buy on a live lane pool estimates at about 7.5 million, so they say at least 8.8 million now, the estimate plus a sixth.
+
+### Deprecated
+
+- `buildExcludeQuoteClass`, `buildStopOpenQuotes`, `encodeQuoteStateCall`, `decodeQuoteState`, `encodeCuratedQuoteCall` and `decodeCuratedQuote`, and the `QuoteState` type: they build, encode or decode calls to functions HookrRegistry does not have, so they never worked on chain.
+- `registryHasQuoteAdmission` and `registryHasOperation`: they only check an ABI offline, and return false for the deployed registry's.
+- `QUOTE_ADMISSION_ABI` and `QUOTE_ADMISSION_OPERATIONS`: they describe calls HookrRegistry does not have.
+- `kingOfTheHillPrizeBound`: use `kingOfThePoolPrizeBound`, the same function.
+
+The quote-admission exports still resolve, and go in 2.0. `quoteAdmission` is not deprecated: its `admitted` is the registry's `isQuote`. Its `curated` is always null.
+
+### Also changed
+
+- `releaseManifest(HOOKR_1)` pins three more contracts than 1.0.0 did, all `rules`, and `readReleaseManifest(client, HOOKR_1)` makes three more `getCode` reads. `HookrRelease` has a new field, `rulesModules`.
+- `CANARY_HOOKR_1_A` is marked internal. It is not for users.
+- `src/core` is unchanged, the release SDK of `412960b37` byte for byte, and the package exports all of it. The core's `checkRulesConfig` and `rulesPoolTerms` still refuse a nonzero `potMinBuyQuote`, as every Rules but Wallet Cap's does.
+
 ## 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.
+The package now builds on `hookr-1`, Hookr's production contracts on Robinhood Chain: one root, `HookrRoot`, whose pools each freeze their own Hook Blocks and, when they want it, arb recapture.
 
 ### What is new
 
@@ -21,17 +57,17 @@ Hookr 1. The package now builds on the `hookr-1` release on Robinhood Chain: one
 
 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.x keeps working for pools on `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.
+- The swap builders take `correcting` (default `isCorrectingRoot(key.hooks)`, the recapture root), and `poolCorrects(rules)` reads from a pool's frozen rules whether it names an arb recapture executor, so a pool on a retired 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.
+- Names both live roots (`ADDRESSES.recaptureRoot`, `RECAPTURE_KERNEL_ID`, `ROOTS`). The market builders take `root` and freeze the arb recapture 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)
 

package/MIGRATING.md

@@ -1,8 +1,8 @@
 # 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.
+1.x builds on `hookr-1`, Hookr's production contracts. 0.2.x builds on `HookrModularHookV6` and `HookrModularHookV6WthV5`. Pools of both sets live on Robinhood Chain, and each package only talks to its own.
 
-## Keep 0.2.x for the earlier roots
+## Keep 0.2.x for pools on the V6 roots
 
 Pools on `HookrModularHookV6` (`0xb3cA29cF721380CEe8b8e4755F3865Ebc68Fe8cC`) and `HookrModularHookV6WthV5` (`0xb914f955294799de4b891bd2EA8AF628Fa1c68CC`) keep trading. 0.2.x stays on npm for them:
 
@@ -16,7 +16,7 @@ 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.
+Pick by the pool's `PoolKey.hooks`: `HOOKR_1.contracts.HookrRoot` is 1.x's, the two roots above are 0.2.x's.
 
 ## What changes
 
@@ -70,7 +70,7 @@ await walletClient.sendTransaction({ to: call.to, data: call.data, value: call.v
 | `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`) |
+| `claimableCall`, `claimCall`, `claimToCall` | `claimable`, `claim` and `claimTo` (`rulesAbi`) on the pool's own Rules, `poolConfig(id).rules` |
 | `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` |
@@ -80,9 +80,9 @@ await walletClient.sendTransaction({ to: call.to, data: call.data, value: call.v
 
 ## 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.
+On the 0.2.x recapture roots Hookr and What The Hook each took 10% of an arb recapture's profit. On `HookrRoot` 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.
+A swap on a `HookrRoot` 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 8.8 million. See [Gas](https://www.npmjs.com/package/hookr-sdk#gas) in the README.
 
 ## Requirements
 

package/README.md

@@ -1,12 +1,13 @@
 # hookr-sdk
 
-Build on Hookr 1, the Uniswap v4 hook on Robinhood Chain: launch tokens with Hook Blocks, open pools, quote, swap and claim.
+Build on Hookr, the Uniswap v4 hook on Robinhood Chain: launch tokens with Hook Blocks, open pools, quote and swap.
 
-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.
+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.
 
 - [Install](#install)
 - [Quick start](#quick-start)
 - [Addresses](#addresses)
+- [Wallet Cap](#wallet-cap)
 - [Arb recapture](#arb-recapture)
 - [Gas](#gas)
 - [Quotes](#quotes)
@@ -44,7 +45,7 @@ const manifest = await readReleaseManifest(client, HOOKR_1);
 
 ### 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.
+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 { DYNAMIC_FEE, HOOKR_1, ZERO, laneRootAbi, poolId, rootAbi, rulesAbi, type PoolKey } from "hookr-sdk";
@@ -68,7 +69,7 @@ const [executor, codeHash, partnerBps, family, laneOn, gasCap, gasFloor] = await
 });
 ```
 
-`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).
+`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
 
@@ -104,7 +105,6 @@ import { buildSwap } from "hookr-sdk";
 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 });
 ```
@@ -115,6 +115,8 @@ When the estimate fails, the swap would revert as built. Check the quote, the al
 
 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.
 
+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 { zeroHash } from "viem";
 import {
@@ -125,13 +127,14 @@ import {
   buildLaunch,
   defaultRulesLaunch,
   launchFeeAbi,
+  readParentBlockNumber,
   rulesAbi,
   rulesPoolTerms,
   type Admission,
 } from "hookr-sdk";
 
 const { HookrRegistry, HookrRoot, HookrRules, HookrLauncher } = HOOKR_1.contracts;
-const blockNumber = await client.getBlockNumber();
+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] }),
@@ -186,7 +189,7 @@ await wallet.sendTransaction({ account, to: launchCall.to, data: launchCall.data
 
 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.
+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";
@@ -215,21 +218,21 @@ const openCall = buildLaunch(manifest, existing, HookrRoot, [member], seed.amoun
 
 ### Claim
 
-Royalties, integrator fees and a trader's arb recapture rebate are held in `HookrRules`, per currency, until claimed.
+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 { HOOKR_1, rulesAbi } from "hookr-sdk";
+import { rulesAbi } from "hookr-sdk";
 
-const owed = await client.readContract({ address: HOOKR_1.contracts.HookrRules, abi: rulesAbi, functionName: "claimable", args: [currency, account] });
+const owed = await client.readContract({ address: config.rules, 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] });
+  await wallet.writeContract({ account, address: config.rules, abi: rulesAbi, functionName: "claim", args: [currency] });
 ```
 
 `claimTo` sends the claim to another address. `claimAsClaims` takes it as Uniswap v4 ERC-6909 claims.
 
 ## Addresses
 
-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.
+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 |
 | --- | --- | --- |
@@ -243,39 +246,57 @@ Robinhood Chain, chain id 4663. Every address is fixed by CREATE3 from the relea
 | 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:
+Every other contract is in `HOOKR_1.contracts`.
 
-| 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`.
+### 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
 
@@ -285,15 +306,17 @@ A pool with arb recapture on lets What The Hook's executor close the price gap b
 | --- | --- |
 | 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 | 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%. `defaultRulesLaunch` leaves the pot off and `checkRulesConfig` refuses one, but `buildLaunch` encodes the Rules config you pass it, pot included. 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 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.
+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: in the release rehearsal, a lane swap through `HookrRouter` needed a gas limit of 7,419,835.
+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 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.
+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
 
@@ -301,24 +324,23 @@ A pool may quote in native ETH, any of the 22 tokens on the genesis catalog, any
 
 ## What is in the package
 
-| Module | What it does |
+| Source file | 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.
+| `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.
 

package/dist/index.d.ts

@@ -1,9 +1,45 @@
 /**
- * hookr-sdk: build on Hookr 1, Hookr's Uniswap v4 hook on Robinhood Chain.
+ * hookr-sdk: build on Hookr, the Uniswap v4 hook on Robinhood Chain.
  *
  * `./core` is the release SDK of the release commit, copied byte for byte (`provenance.json` names the commit and
  * every file's hash). `./releases` adds the addresses and deployment of the production release and its canary, the
- * chain for viem, and builds the DeploymentManifest the core builders take.
+ * Rules modules its root admits beside the release's own, the chain for viem, and builds the DeploymentManifest the core
+ * builders take. `./wallet-cap` adds Wallet Cap: its pool terms, its storage reads and its refusal.
+ *
+ * Below, the core's quote-admission exports are exported again, marked deprecated: they name functions HookrRegistry
+ * does not have on chain.
  */
+import * as registry from "./core/registry.js";
+import { kingOfTheHillPrizeBound as prizeBound } from "./core/rules.js";
 export * from "./core/index.js";
 export * from "./releases.js";
+export * from "./wallet-cap.js";
+/**
+ * The largest King of the Pool `maxPrizeBps` a recapture pool binds with: HookrRecapture's `prizeBoundFor(lpBps,
+ * burnBps, protocolShareBps, integratorBps)`, worked out offline.
+ */
+export declare const kingOfThePoolPrizeBound: typeof prizeBound;
+/** @deprecated The same function as `kingOfThePoolPrizeBound`, under King of the Pool's earlier name. */
+export declare const kingOfTheHillPrizeBound: typeof prizeBound;
+/** @deprecated Describes calls HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const QUOTE_ADMISSION_ABI: typeof registry.QUOTE_ADMISSION_ABI;
+/** @deprecated Names functions HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const QUOTE_ADMISSION_OPERATIONS: typeof registry.QUOTE_ADMISSION_OPERATIONS;
+/** @deprecated Checks an ABI offline; against the deployed HookrRegistry's ABI it returns false. Removed in 2.0. */
+export declare const registryHasQuoteAdmission: typeof registry.registryHasQuoteAdmission;
+/** @deprecated Checks an ABI offline; against the deployed HookrRegistry's ABI it returns false. Removed in 2.0. */
+export declare const registryHasOperation: typeof registry.registryHasOperation;
+/** @deprecated Calls `excludeQuoteClassNow`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const buildExcludeQuoteClass: typeof registry.buildExcludeQuoteClass;
+/** @deprecated Calls `stopOpenQuotesNow`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const buildStopOpenQuotes: typeof registry.buildStopOpenQuotes;
+/** @deprecated Encodes `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const encodeQuoteStateCall: typeof registry.encodeQuoteStateCall;
+/** @deprecated Decodes `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const decodeQuoteState: typeof registry.decodeQuoteState;
+/** @deprecated The result of `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export type QuoteState = registry.QuoteState;
+/** @deprecated Encodes `curatedQuote(asset)`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const encodeCuratedQuoteCall: typeof registry.encodeCuratedQuoteCall;
+/** @deprecated Decodes `curatedQuote(asset)`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const decodeCuratedQuote: typeof registry.decodeCuratedQuote;

package/dist/index.js

@@ -1,9 +1,43 @@
 /**
- * hookr-sdk: build on Hookr 1, Hookr's Uniswap v4 hook on Robinhood Chain.
+ * hookr-sdk: build on Hookr, the Uniswap v4 hook on Robinhood Chain.
  *
  * `./core` is the release SDK of the release commit, copied byte for byte (`provenance.json` names the commit and
  * every file's hash). `./releases` adds the addresses and deployment of the production release and its canary, the
- * chain for viem, and builds the DeploymentManifest the core builders take.
+ * Rules modules its root admits beside the release's own, the chain for viem, and builds the DeploymentManifest the core
+ * builders take. `./wallet-cap` adds Wallet Cap: its pool terms, its storage reads and its refusal.
+ *
+ * Below, the core's quote-admission exports are exported again, marked deprecated: they name functions HookrRegistry
+ * does not have on chain.
  */
+import * as registry from "./core/registry.js";
+import { kingOfTheHillPrizeBound as prizeBound } from "./core/rules.js";
 export * from "./core/index.js";
 export * from "./releases.js";
+export * from "./wallet-cap.js";
+/**
+ * The largest King of the Pool `maxPrizeBps` a recapture pool binds with: HookrRecapture's `prizeBoundFor(lpBps,
+ * burnBps, protocolShareBps, integratorBps)`, worked out offline.
+ */
+export const kingOfThePoolPrizeBound = prizeBound;
+/** @deprecated The same function as `kingOfThePoolPrizeBound`, under King of the Pool's earlier name. */
+export const kingOfTheHillPrizeBound = prizeBound;
+/** @deprecated Describes calls HookrRegistry does not have on chain. Removed in 2.0. */
+export const QUOTE_ADMISSION_ABI = registry.QUOTE_ADMISSION_ABI;
+/** @deprecated Names functions HookrRegistry does not have on chain. Removed in 2.0. */
+export const QUOTE_ADMISSION_OPERATIONS = registry.QUOTE_ADMISSION_OPERATIONS;
+/** @deprecated Checks an ABI offline; against the deployed HookrRegistry's ABI it returns false. Removed in 2.0. */
+export const registryHasQuoteAdmission = registry.registryHasQuoteAdmission;
+/** @deprecated Checks an ABI offline; against the deployed HookrRegistry's ABI it returns false. Removed in 2.0. */
+export const registryHasOperation = registry.registryHasOperation;
+/** @deprecated Calls `excludeQuoteClassNow`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const buildExcludeQuoteClass = registry.buildExcludeQuoteClass;
+/** @deprecated Calls `stopOpenQuotesNow`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const buildStopOpenQuotes = registry.buildStopOpenQuotes;
+/** @deprecated Encodes `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const encodeQuoteStateCall = registry.encodeQuoteStateCall;
+/** @deprecated Decodes `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const decodeQuoteState = registry.decodeQuoteState;
+/** @deprecated Encodes `curatedQuote(asset)`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const encodeCuratedQuoteCall = registry.encodeCuratedQuoteCall;
+/** @deprecated Decodes `curatedQuote(asset)`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const decodeCuratedQuote = registry.decodeCuratedQuote;

package/dist/releases.d.ts

@@ -1,6 +1,6 @@
 /**
- * Hookr 1 on Robinhood Chain: the production release `hookr-1`, its canary `canary-hookr-1-a`, each release's
- * deployment, and the deployment manifest the builders take.
+ * Hookr on Robinhood Chain: the production release `hookr-1`, its canary `canary-hookr-1-a`, each release's
+ * deployment, the Rules modules its root admits beside the release's own, and the deployment manifest the builders take.
  *
  * Every address is fixed by CREATE3 from the release deployer, the release id and the contract's name, so it is known
  * before the contract is deployed and is the same on every machine. `test/releases.test.ts` derives each one again
@@ -17,7 +17,7 @@ export declare const CHAIN_ID = 4663;
  * endpoint of its own.
  */
 export declare const RPC_URL = "https://rpc.mainnet.chain.robinhood.com";
-/** The block explorer people open: RobinScan, where every contract's source is verified. No trailing slash. */
+/** The block explorer people open: RobinScan. No trailing slash. */
 export declare const EXPLORER_URL = "https://robin.etherscan.io";
 /**
  * Robinhood Chain for viem, on any viem 2, with RobinScan as its explorer. viem 2.55 and later also ship it as
@@ -102,10 +102,38 @@ export interface HookrRelease {
      * before the release was deployed and verified. `releaseManifest` and `readReleaseManifest` use it by default.
      */
     deployment: Readonly<ReleaseDeployment> | null;
+    /**
+     * The Rules modules a pool on this release's root can bind, by name: `standard`, the release's own HookrRules, and
+     * on `hookr-1` also `whole-pot`, where King of the Pool pays the round's winner the whole pot, `wallet-cap`, the
+     * whole-pot Rules with a per-wallet buy cap while the launch guard lasts (`wallet-cap.ts`), and `round-trip`, the
+     * Rules that record who traded in each block for Buy/Sell Block's round-trip check. The registry admits each on the
+     * root with the release Rules' own terms. `rulesModule` names one.
+     */
+    rulesModules: Readonly<Partial<Record<RulesModuleName, Readonly<RulesModule>>>>;
+}
+/**
+ * The name of a Rules module: the release's own Rules, or beside them the whole-pot King of the Pool Rules, the Wallet
+ * Cap Rules or the round-trip Rules.
+ */
+export type RulesModuleName = "standard" | "whole-pot" | "wallet-cap" | "round-trip";
+/**
+ * A HookrRules a pool can bind on the release's root (its `PoolConfig.rules`), and the HookrRecapture it created in its
+ * constructor. The Rules reach that module for every King of the Pool call, so a pool's round, pot, prize and claims
+ * live at the Rules address. Both runtime hashes are the code read back from chain.
+ */
+export interface RulesModule {
+    name: RulesModuleName;
+    rules: Address;
+    rulesRuntimeHash: Hash;
+    recapture: Address;
+    recaptureRuntimeHash: Hash;
 }
 /** The production release. Build on this one. */
 export declare const HOOKR_1: HookrRelease;
-/** The canary: the same contracts at their own addresses, deployed and proven before production. Not for users. */
+/**
+ * The canary: the same contracts at their own addresses, deployed and proven before production. Not for users.
+ * @internal
+ */
 export declare const CANARY_HOOKR_1_A: HookrRelease;
 /** Both releases by release id. */
 export declare const RELEASES: Readonly<Record<HookrReleaseId, HookrRelease>>;
@@ -129,13 +157,18 @@ export interface ReleaseDeployment {
 }
 /**
  * The DeploymentManifest the builders take for a release: every role at its fixed address with its runtime hash, from
- * the release's own deployment unless one is given. It makes no reads. Refuses a role without a runtime hash, and
- * anything `deployment()` refuses.
+ * the release's own deployment unless one is given, then each further Rules module (`otherRulesModules`) as one more
+ * `rules` pin with its own runtime hash, so the builders that name a Rules accept it. It makes no reads. Refuses a role
+ * without a runtime hash, and anything `deployment()` refuses.
  *
  * It is the builders' manifest. Its release id is the release's, `hookr-1`, so it is not the manifest a Hookr service
  * publishes: `HookrClient` takes the release id and manifest hash the service names.
  */
 export declare function releaseManifest(release: HookrRelease, d?: Readonly<ReleaseDeployment> | null): DeploymentManifest;
+/** The release's Rules modules other than its own HookrRules: on `hookr-1`, the whole-pot, Wallet Cap and round-trip Rules. */
+export declare function otherRulesModules(release: HookrRelease): Readonly<RulesModule>[];
+/** The release's Rules module `name`, or an error for a release without it (the canary has only `standard`). */
+export declare function rulesModule(release: HookrRelease, name: RulesModuleName): Readonly<RulesModule>;
 /** The two reads `readReleaseManifest` makes. A viem PublicClient has both. */
 export interface ReleaseReader {
     getCode(args: {
@@ -160,13 +193,27 @@ export interface ReadReleaseOptions {
 /**
  * `releaseManifest` with each role's runtime hash and the start block's hash read from chain. Refuses a role with no
  * code: the release is not deployed, or not on this chain. Where the release carries its deployment, it also refuses
- * a role whose code is not the release's, and a start block whose hash is not the release's.
+ * a role whose code is not the release's, and a start block whose hash is not the release's. It always refuses a
+ * further Rules module whose code is not the one the release pins for it.
  */
 export declare function readReleaseManifest(client: ReleaseReader, release: HookrRelease, options?: ReadReleaseOptions): Promise<DeploymentManifest>;
 /**
  * The gas floor a swap on an arb recapture pool must carry while its lane is on: `2 × gasCap + gasCap / 63 + 755,000`
  * (HookrLane), the `gasFloor` `laneOf(id)` returns. At the 3,000,000 cap the lane opens with it is 6,802,619. A swap
- * sent with less reverts `InsufficientLaneGas`. The swap's own gas comes on top: the release rehearsal's lane swap
- * needed a gas limit of 7,419,835, so a fixed limit on such a pool should be at least 7,500,000.
+ * sent with less reverts `InsufficientLaneGas`. The swap's own gas comes on top: a buy on a live lane pool estimates at
+ * about 7.5 million, so a fixed limit on such a pool should be at least 8,800,000, the estimate plus a sixth.
  */
 export declare function laneGasFloor(gasCap: number | bigint): bigint;
+/** The read `readParentBlockNumber` makes. A viem PublicClient has it. */
+export interface ParentBlockReader {
+    getBlock(args: {
+        blockTag: "latest";
+    }): Promise<unknown>;
+}
+/**
+ * The block number the contracts read as `block.number`: on Robinhood Chain, an Arbitrum Orbit chain, it is the parent
+ * chain's (Ethereum's), which each block carries as `l1BlockNumber`, about one every 12 seconds. Anti-Snipe's launch
+ * guard (`guardEndBlock`), and Wallet Cap with it, counts these blocks, so pass this as a launch's `blockNumber`.
+ * `getBlockNumber()` is the chain's own, far larger number: a guard counted from it is one the Rules refuse at bind.
+ */
+export declare function readParentBlockNumber(client: ParentBlockReader): Promise<bigint>;

package/dist/releases.js

@@ -1,6 +1,6 @@
 /**
- * Hookr 1 on Robinhood Chain: the production release `hookr-1`, its canary `canary-hookr-1-a`, each release's
- * deployment, and the deployment manifest the builders take.
+ * Hookr on Robinhood Chain: the production release `hookr-1`, its canary `canary-hookr-1-a`, each release's
+ * deployment, the Rules modules its root admits beside the release's own, and the deployment manifest the builders take.
  *
  * Every address is fixed by CREATE3 from the release deployer, the release id and the contract's name, so it is known
  * before the contract is deployed and is the same on every machine. `test/releases.test.ts` derives each one again
@@ -18,7 +18,7 @@ export const CHAIN_ID = 4663;
  * endpoint of its own.
  */
 export const RPC_URL = "https://rpc.mainnet.chain.robinhood.com";
-/** The block explorer people open: RobinScan, where every contract's source is verified. No trailing slash. */
+/** The block explorer people open: RobinScan. No trailing slash. */
 export const EXPLORER_URL = "https://robin.etherscan.io";
 /**
  * Robinhood Chain for viem, on any viem 2, with RobinScan as its explorer. viem 2.55 and later also ship it as
@@ -66,6 +66,53 @@ export const HOOKR_1 = Object.freeze({
     canary: false,
     chainId: CHAIN_ID,
     deployment: frozen(DEPLOYMENTS["hookr-1"]),
+    rulesModules: Object.freeze({
+        standard: Object.freeze({
+            name: "standard",
+            rules: "0x4a71c270b1520F94064268102AebD744b0DE7942",
+            rulesRuntimeHash: "0x4b6d50b40981b8082f3ee5a7ebf57e48489f71c94c2a3b94032a1d1a382b515b",
+            recapture: "0xF83569E564d70daebc35950f66a73f2e2B915583",
+            recaptureRuntimeHash: "0xb78c68d64388c9c0c4d20faa3d429309a6a025024c3eefc579831bb10de145ed",
+        }),
+        /**
+         * Deployed 2026-10-07 beside the release (CREATE3 from the release deployer, release id `hookr-1-whole-pot`), with
+         * the release's constructor arguments. Its HookrRecapture pays a round's winner the whole pot and lets a pool put
+         * up to all of its arb recapture share in the pot. Same ABI as the release's Rules.
+         */
+        "whole-pot": Object.freeze({
+            name: "whole-pot",
+            rules: "0x10f684361b35C8411a2c07F68A6fB1F4B7e555F7",
+            rulesRuntimeHash: "0x3ffac05e248f81ad3843949052af1c0c6343179f0ec591bae3e271e249c7d879",
+            recapture: "0x60Efc4a41498e9433be2155b6cc1677AEC31D649",
+            recaptureRuntimeHash: "0xdc89f3eb02ff5bfbc07ac078e4f1d1de215ec253bc7ba843962e0b6cd11445c4",
+        }),
+        /**
+         * HookrRulesWalletCap v2, deployed 2026-10-12 beside the release (CREATE3 from the release deployer, release id
+         * `hookr-1-wallet-cap-v2`) with the release's constructor arguments, and admitted on HookrRoot with the release
+         * Rules' terms. The whole-pot Rules plus a per-wallet buy cap while a pool's launch guard lasts: it binds only a
+         * pool with a cap and a guard, and answers `extsload` (`wallet-cap.ts`). Its HookrRecapture is the whole-pot one's
+         * source, so its runtime, which keeps its own address, is its own. Same ABI as the release's Rules otherwise.
+         */
+        "wallet-cap": Object.freeze({
+            name: "wallet-cap",
+            rules: "0xb67b73E28C522a3AAC438bE970bf94976Deee52a",
+            rulesRuntimeHash: "0x0fed58ec91368b16ba4166acc65ddd9252529fb860834f81fdc5dab3179a6247",
+            recapture: "0xbbC43DC2f01F5E7882caCd78EF094A44eF0E4d23",
+            recaptureRuntimeHash: "0x04001c31836049074c926cf6519ecf999c18267229fe6a05df26685caadb0984",
+        }),
+        /**
+         * HookrRulesRoundTrip, deployed beside the release (CREATE3 from the release deployer, release id `hookr-1`) and
+         * admitted on HookrRoot with the release Rules' terms at block 82,372,631. Rules that keep a record of who traded
+         * in each block, which Buy/Sell Block's round-trip check reads. Same ABI as the release's Rules otherwise.
+         */
+        "round-trip": Object.freeze({
+            name: "round-trip",
+            rules: "0x3d7e31746127FD9a14d3C7fC12E73611D2e8cb34",
+            rulesRuntimeHash: "0x925797125cde5723bfa57ac04238e847ac0098a2821e6703fd4d5e20881a322b",
+            recapture: "0xddFF6326E5CB9AA98b88e9064d9A9570f777f8A3",
+            recaptureRuntimeHash: "0x7e8e752507e29441d26bec6646cd57598e63825ab888cf166da27cf9a5a31e5e",
+        }),
+    }),
     contracts: Object.freeze({
         HookrRegistryChecks: "0xB9F5c54E5Cc7ac6c7a96335E5A334Cf4eA496E98",
         HookrRegistryAdmin: "0x675ac2102E8c69E2467F64656E3c235AF3901Ac1",
@@ -104,12 +151,24 @@ export const HOOKR_1 = Object.freeze({
         HookrLpBoost: "0x52536F5F4E5BC7cEA2197c8F1BB49bf2B133E7f1",
     }),
 });
-/** The canary: the same contracts at their own addresses, deployed and proven before production. Not for users. */
+/**
+ * The canary: the same contracts at their own addresses, deployed and proven before production. Not for users.
+ * @internal
+ */
 export const CANARY_HOOKR_1_A = Object.freeze({
     releaseId: "canary-hookr-1-a",
     canary: true,
     chainId: CHAIN_ID,
     deployment: frozen(DEPLOYMENTS["canary-hookr-1-a"]),
+    rulesModules: Object.freeze({
+        standard: Object.freeze({
+            name: "standard",
+            rules: "0x8Ef8869CD47d9928d563001F1d38D65c3c3e01Ab",
+            rulesRuntimeHash: "0x7e51ac228eafdaa7f2b3c45f2fec6ec9c872f81ce0258c1a2da95090883b30a5",
+            recapture: "0xe7035c0d8523a5eE9Fc5Ba5Ec97a4f1D771a6F87",
+            recaptureRuntimeHash: "0x54aa061f121e798029af86b9b700433fec566cdb570578e4e57a69865d6095a6",
+        }),
+    }),
     contracts: Object.freeze({
         HookrRegistryChecks: "0x4598d64B6c5730813a469e4B36cf379DbfB24118",
         HookrRegistryAdmin: "0x57252DB7C9ed51213a324A2160934Ee2f840d6E8",
@@ -185,8 +244,9 @@ function noDeployment(release) {
 }
 /**
  * The DeploymentManifest the builders take for a release: every role at its fixed address with its runtime hash, from
- * the release's own deployment unless one is given. It makes no reads. Refuses a role without a runtime hash, and
- * anything `deployment()` refuses.
+ * the release's own deployment unless one is given, then each further Rules module (`otherRulesModules`) as one more
+ * `rules` pin with its own runtime hash, so the builders that name a Rules accept it. It makes no reads. Refuses a role
+ * without a runtime hash, and anything `deployment()` refuses.
  *
  * It is the builders' manifest. Its release id is the release's, `hookr-1`, so it is not the manifest a Hookr service
  * publishes: `HookrClient` takes the release id and manifest hash the service names.
@@ -205,6 +265,8 @@ export function releaseManifest(release, d = release.deployment) {
             startBlock: d.startBlock,
         };
     });
+    for (const m of otherRulesModules(release))
+        contracts.push({ role: "rules", address: m.rules.toLowerCase(), runtimeHash: m.rulesRuntimeHash, startBlock: d.startBlock });
     return deployment({
         schema: "hookr.engagement.sources.v1",
         releaseId: release.releaseId,
@@ -215,10 +277,22 @@ export function releaseManifest(release, d = release.deployment) {
         qualification: { status: "verified", evidenceHash: d.evidenceHash, sourceCommit: RELEASE_SOURCE_COMMIT },
     });
 }
+/** The release's Rules modules other than its own HookrRules: on `hookr-1`, the whole-pot, Wallet Cap and round-trip Rules. */
+export function otherRulesModules(release) {
+    return Object.values(release.rulesModules).filter((m) => m !== undefined && m.rules.toLowerCase() !== release.contracts.HookrRules.toLowerCase());
+}
+/** The release's Rules module `name`, or an error for a release without it (the canary has only `standard`). */
+export function rulesModule(release, name) {
+    const m = release.rulesModules[name];
+    if (!m)
+        throw new Error(`${release.releaseId} has no ${name} Rules`);
+    return m;
+}
 /**
  * `releaseManifest` with each role's runtime hash and the start block's hash read from chain. Refuses a role with no
  * code: the release is not deployed, or not on this chain. Where the release carries its deployment, it also refuses
- * a role whose code is not the release's, and a start block whose hash is not the release's.
+ * a role whose code is not the release's, and a start block whose hash is not the release's. It always refuses a
+ * further Rules module whose code is not the one the release pins for it.
  */
 export async function readReleaseManifest(client, release, options = {}) {
     const pinned = release.deployment;
@@ -227,9 +301,11 @@ export async function readReleaseManifest(client, release, options = {}) {
     if (startBlock === undefined || evidenceHash === undefined)
         throw noDeployment(release);
     const roles = Object.keys(MANIFEST_ROLES);
-    const [block, codes] = await Promise.all([
+    const modules = otherRulesModules(release);
+    const [block, codes, moduleCodes] = await Promise.all([
         client.getBlock({ blockNumber: startBlock }),
         Promise.all(roles.map((role) => client.getCode({ address: releaseAddress(release, role), blockNumber: options.blockNumber }))),
+        Promise.all(modules.map((m) => client.getCode({ address: m.rules, blockNumber: options.blockNumber }))),
     ]);
     if (!block.hash)
         throw new Error(`Block ${startBlock} has no hash yet`);
@@ -247,6 +323,13 @@ export async function readReleaseManifest(client, release, options = {}) {
             throw new Error(`${role} ${releaseAddress(release, role)} does not run ${release.releaseId}'s code`);
         runtimeHashes[role] = runtimeHash;
     });
+    modules.forEach((m, i) => {
+        const code = moduleCodes[i];
+        if (!code || code === "0x")
+            throw new Error(`No code at the ${m.name} Rules ${m.rules}`);
+        if (keccak256(code) !== m.rulesRuntimeHash.toLowerCase())
+            throw new Error(`The ${m.name} Rules ${m.rules} do not run the code ${release.releaseId} pins for them`);
+    });
     return releaseManifest(release, {
         startBlock: startBlock.toString(),
         parentHash: block.hash,
@@ -257,8 +340,8 @@ export async function readReleaseManifest(client, release, options = {}) {
 /**
  * The gas floor a swap on an arb recapture pool must carry while its lane is on: `2 × gasCap + gasCap / 63 + 755,000`
  * (HookrLane), the `gasFloor` `laneOf(id)` returns. At the 3,000,000 cap the lane opens with it is 6,802,619. A swap
- * sent with less reverts `InsufficientLaneGas`. The swap's own gas comes on top: the release rehearsal's lane swap
- * needed a gas limit of 7,419,835, so a fixed limit on such a pool should be at least 7,500,000.
+ * sent with less reverts `InsufficientLaneGas`. The swap's own gas comes on top: a buy on a live lane pool estimates at
+ * about 7.5 million, so a fixed limit on such a pool should be at least 8,800,000, the estimate plus a sixth.
  */
 export function laneGasFloor(gasCap) {
     const cap = BigInt(gasCap);
@@ -266,3 +349,17 @@ export function laneGasFloor(gasCap) {
         return 0n;
     return 2n * cap + cap / 63n + 755000n;
 }
+/**
+ * The block number the contracts read as `block.number`: on Robinhood Chain, an Arbitrum Orbit chain, it is the parent
+ * chain's (Ethereum's), which each block carries as `l1BlockNumber`, about one every 12 seconds. Anti-Snipe's launch
+ * guard (`guardEndBlock`), and Wallet Cap with it, counts these blocks, so pass this as a launch's `blockNumber`.
+ * `getBlockNumber()` is the chain's own, far larger number: a guard counted from it is one the Rules refuse at bind.
+ */
+export async function readParentBlockNumber(client) {
+    const { l1BlockNumber } = ((await client.getBlock({ blockTag: "latest" })) ?? {});
+    if (typeof l1BlockNumber === "bigint" && l1BlockNumber > 0n)
+        return l1BlockNumber;
+    if (typeof l1BlockNumber === "string" && /^0x0*[1-9a-fA-F][0-9a-fA-F]*$/.test(l1BlockNumber))
+        return BigInt(l1BlockNumber);
+    throw new Error("The latest block carries no l1BlockNumber: read it from Robinhood Chain's own RPC");
+}

package/dist/wallet-cap.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Wallet Cap: HookrRulesWalletCap (`rulesModule(HOOKR_1, "wallet-cap")`), the whole-pot Rules with a per-wallet buy
+ * cap on each launch while its pools' launch guards last.
+ *
+ * - The cap rides in `RulesConfig.potMinBuyQuote`, in the token's raw units: the most of it one wallet may buy while the
+ *   pool's guard lasts. These Rules bind only a pool with a cap and a launch guard (`guardEndBlock` within the next
+ *   100,000 parent blocks), and `potEveryNBuys` stays zero. Every other Rules refuses a nonzero `potMinBuyQuote`, as the
+ *   core's `checkRulesConfig` does.
+ * - Each guarded buy counts what it delivers (the pool's output less Auto Burn) against its wallet: the payer
+ *   HookrRouter, the forwarder, the family router or the curated Uniswap router names, or for a swap through a router
+ *   that names none, the transaction's signer. Counts are per token and per launch: the pools of one launch share
+ *   `Bound.launchedAt`, the second they bound, and a later launch of the token counts from zero, so every pool of a
+ *   launch takes the same cap, and arb recapture on every pool or none (`checkWalletCapLaunch`). A sell frees no room.
+ *   The creator's dev buy and the pool's own arb recapture executor are not counted. A buy past the cap reverts
+ *   `GuardWalletLimit(wallet, actual, limit)`. After the guard nothing is counted or capped.
+ * - The Rules answer `extsload(bytes32)`, one word of their storage, and `readWalletCap` reads through it.
+ */
+import { type Hex } from "viem";
+import { type Address, type Admission, type Caps, type Hash, type ParamContext, type PoolTerms, type RootAdvisoryKind, type RulesConfig, type RulesContext, type RulesLaunch } from "./core/index.js";
+import { type HookrRelease } from "./releases.js";
+/**
+ * What HookrRulesWalletCap adds to the release Rules' ABI (`rulesAbi`): `extsload`, one word of its storage as Uniswap
+ * v4's Extsload reads it, and the refusal of a buy that would take a wallet past its pool's cap.
+ */
+export declare const WALLET_CAP_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "extsload";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "slot";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "value";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "GuardWalletLimit";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "actual";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }, {
+        readonly name: "limit";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+}];
+/** erc7201:hookr.rules, every HookrRules' State: keccak256(abi.encode(uint256(keccak256("hookr.rules")) - 1)) & ~0xff. */
+export declare const RULES_SLOT = 53445494162334802764660739626191472437579742535980357254313114366502610401536n;
+/**
+ * The slot of a pool's first Bound word, `State.pools[poolId]`: keccak256(abi.encode(poolId, RULES_SLOT)). Its launch
+ * guard's end is in the next slot (`uint40` of the word) and its cap two slots on (the top 128 bits).
+ */
+export declare function walletCapPoolSlot(poolId: Hash): Hash;
+/** The slot of `wallet`'s count of `subject` on launch `launch`, `State.bought[subject][launch][wallet]`. */
+export declare function walletCapBoughtSlot(subject: Address, launch: number | bigint, wallet: Address): Hash;
+/**
+ * The launch in a pool's first Bound word: its top 32 bits, `Bound.launchedAt`. The word packs, low to high,
+ * baseFeePips (24 bits), tickSpacing (16), bound (8), quoteIsCurrency0 (8), terms (8), liquidityOwner (160) and
+ * launchedAt (32). Null for anything but 32 bytes of hex with the bound flag set: a pool these Rules never bound.
+ */
+export declare function walletCapLaunch(value: Hex): number | null;
+/**
+ * A pool's cap, in the token's raw units, for a share of `supply` (raw units) in basis points: the floor of
+ * supply × bps / 10,000, so 200 bps of a supply of 10^27 is 2 × 10^25. It goes in the pool's `rules.potMinBuyQuote`.
+ * Refuses a share outside 1 to 10,000 bps and a cap that rounds to zero. hookr.fun offers 0.1% to 10%, 2% by default.
+ */
+export declare function walletCapAmount(supply: bigint, bps: number | bigint): bigint;
+/** What a wallet may still buy while the guard lasts: the cap less what it bought, never below zero. */
+export declare function walletCapRoom(cap: bigint, bought: bigint): bigint;
+/**
+ * Refuses a RulesConfig HookrRulesWalletCap's bind would refuse and returns its fee ceilings: `checkRulesConfig` with
+ * the cap set aside, plus the Wallet Cap Rules' own terms: a cap above zero in `potMinBuyQuote` (below 2^128), and a
+ * launch guard, with its liquidity owner, ending within 100,000 parent blocks after `ctx.blockNumber`, which is required
+ * here. `potEveryNBuys` stays zero. Every other Rules refuses a cap: check those with `checkRulesConfig`.
+ */
+export declare function checkWalletCapRulesConfig(c: RulesConfig, ctx: RulesContext): Caps;
+/**
+ * `rulesPoolTerms` for a launch member on the Wallet Cap Rules: every check `checkWalletCapRulesConfig` makes, the
+ * pool's caps and gas limits from the Rules' admission (`admission(HookrRoot, rulesModule(HOOKR_1, "wallet-cap").rules)`
+ * on the registry), and its `rulesData` with the cap. Refuses the admission of any other Rules. The member binds these
+ * Rules as `config.rules` and `l.rules`, cap included, as `rules`; every pool of the launch takes the same cap.
+ */
+export declare function walletCapPoolTerms(l: RulesLaunch, ctx: ParamContext & {
+    liquidityOwner?: Address;
+}, rulesAdmission: Admission, advisory?: {
+    admission: Admission;
+    kind: RootAdvisoryKind;
+    phases?: number;
+}, release?: HookrRelease): PoolTerms;
+/**
+ * Refuses a launch whose members (`buildLaunch`'s) Wallet Cap would leave a way round, or turn against traders, though
+ * the Rules bind each pool alone: some pools on the Wallet Cap Rules and some not, capped pools with different caps (a
+ * wallet could then buy the largest), or capped pools some with arb recapture and some without (on a capped pool
+ * without the lane, the executor's legs count against the trader whose swap set them off). Passes a launch without it.
+ */
+export declare function checkWalletCapLaunch(members: readonly Record<string, unknown>[], release?: HookrRelease): void;
+/** The read `readWalletCap` makes: an `eth_call`. A viem PublicClient has it. */
+export interface WalletCapReader {
+    call(args: {
+        to: Address;
+        data: Hex;
+        blockNumber?: bigint;
+    }): Promise<{
+        data?: Hex;
+    }>;
+}
+/** Which pool, and optionally which wallet, `readWalletCap` reads. */
+export interface WalletCapQuery {
+    /** The pool's PoolId (`poolId(key)`). */
+    poolId: Hash;
+    /** The wallet whose count and room to read. */
+    wallet?: Address;
+    /** The pool's token, with `wallet`: counts are per token. */
+    subject?: Address;
+    /** The block to read at. Defaults to the latest. */
+    blockNumber?: bigint;
+}
+/** A pool's wallet cap as its Rules hold it, and a wallet's count against it. */
+export interface WalletCap {
+    /** The pool's launch: `Bound.launchedAt`, the second its launch bound it, which the launch's pools share. */
+    launch: number;
+    /** The parent block the pool's launch guard, and the cap with it, ends at (`readParentBlockNumber` reads the clock). */
+    guardEndBlock: bigint;
+    /** The most of the token, in raw units, one wallet may buy across the launch's pools while the guard lasts. */
+    cap: bigint;
+    /** What the wallet bought across the launch's pools while their guards lasted, or null without a wallet. */
+    bought: bigint | null;
+    /** What the wallet may still buy before the guard ends (`walletCapRoom`), or null without a wallet. */
+    room: bigint | null;
+}
+/**
+ * Reads a pool on the Wallet Cap Rules through their `extsload`: its launch, guard end and cap from its Bound
+ * (`walletCapPoolSlot` and the two slots after it), then, with a wallet, that wallet's count on the launch
+ * (`walletCapBoughtSlot`) and its room. Null for a pool these Rules have not bound: a pool on any other Rules has no
+ * wallet cap. A count and its room hold while the guard lasts; after it nothing is counted or capped.
+ */
+export declare function readWalletCap(client: WalletCapReader, query: WalletCapQuery, release?: HookrRelease): Promise<WalletCap | null>;
+/** A buy Wallet Cap refused: the wallet it counted, the total the buy would have brought it to, and the cap. */
+export interface WalletCapRefusal {
+    wallet: Address;
+    actual: bigint;
+    limit: bigint;
+}
+/**
+ * The GuardWalletLimit inside a failed quote, swap or launch, however the root, the lane, the PoolManager and the quoter
+ * wrapped it, or null. Takes the revert data, or the viem error that carries it.
+ */
+export declare function walletCapRefusal(error: unknown): WalletCapRefusal | null;
+/** Names Wallet Cap's refusal in `error` (revert data, or the viem error that carries it), or null. */
+export declare function walletCapRevert(error: unknown): string | null;

package/dist/wallet-cap.js

@@ -0,0 +1,234 @@
+/**
+ * Wallet Cap: HookrRulesWalletCap (`rulesModule(HOOKR_1, "wallet-cap")`), the whole-pot Rules with a per-wallet buy
+ * cap on each launch while its pools' launch guards last.
+ *
+ * - The cap rides in `RulesConfig.potMinBuyQuote`, in the token's raw units: the most of it one wallet may buy while the
+ *   pool's guard lasts. These Rules bind only a pool with a cap and a launch guard (`guardEndBlock` within the next
+ *   100,000 parent blocks), and `potEveryNBuys` stays zero. Every other Rules refuses a nonzero `potMinBuyQuote`, as the
+ *   core's `checkRulesConfig` does.
+ * - Each guarded buy counts what it delivers (the pool's output less Auto Burn) against its wallet: the payer
+ *   HookrRouter, the forwarder, the family router or the curated Uniswap router names, or for a swap through a router
+ *   that names none, the transaction's signer. Counts are per token and per launch: the pools of one launch share
+ *   `Bound.launchedAt`, the second they bound, and a later launch of the token counts from zero, so every pool of a
+ *   launch takes the same cap, and arb recapture on every pool or none (`checkWalletCapLaunch`). A sell frees no room.
+ *   The creator's dev buy and the pool's own arb recapture executor are not counted. A buy past the cap reverts
+ *   `GuardWalletLimit(wallet, actual, limit)`. After the guard nothing is counted or capped.
+ * - The Rules answer `extsload(bytes32)`, one word of their storage, and `readWalletCap` reads through it.
+ */
+import { BaseError, decodeErrorResult, encodeAbiParameters, encodeFunctionData, getAddress, keccak256, numberToHex, parseAbi, } from "viem";
+import { address, assert, checkRulesConfig, encodeRulesData, hash, rulesKnobsOf, rulesPoolTerms, uint, } from "./core/index.js";
+import { HOOKR_1, rulesModule } from "./releases.js";
+/**
+ * What HookrRulesWalletCap adds to the release Rules' ABI (`rulesAbi`): `extsload`, one word of its storage as Uniswap
+ * v4's Extsload reads it, and the refusal of a buy that would take a wallet past its pool's cap.
+ */
+export const WALLET_CAP_ABI = [
+    {
+        type: "function",
+        name: "extsload",
+        stateMutability: "view",
+        inputs: [{ name: "slot", type: "bytes32", internalType: "bytes32" }],
+        outputs: [{ name: "value", type: "bytes32", internalType: "bytes32" }],
+    },
+    {
+        type: "error",
+        name: "GuardWalletLimit",
+        inputs: [
+            { name: "wallet", type: "address", internalType: "address" },
+            { name: "actual", type: "uint256", internalType: "uint256" },
+            { name: "limit", type: "uint256", internalType: "uint256" },
+        ],
+    },
+];
+/** erc7201:hookr.rules, every HookrRules' State: keccak256(abi.encode(uint256(keccak256("hookr.rules")) - 1)) & ~0xff. */
+export const RULES_SLOT = 0x762913e4bc0f59f7b08c82f07586fa48932548ab5fab99e6db0b09765b4ff900n;
+/** `State.bought`, the State's fourteenth field: what each wallet bought, per subject and launch. */
+const BOUGHT = RULES_SLOT + 13n;
+/** A slot as `extsload` takes it: 32 bytes, wrapping as the EVM's slot arithmetic does. */
+const word = (n) => numberToHex(n & ((1n << 256n) - 1n), { size: 32 });
+/** The slot of `key` in the mapping at `slot`: keccak256(abi.encode(key, slot)). */
+const mapping = (keyType, key, slot) => BigInt(keccak256(encodeAbiParameters([{ type: keyType }, { type: "uint256" }], [key, slot])));
+/**
+ * The slot of a pool's first Bound word, `State.pools[poolId]`: keccak256(abi.encode(poolId, RULES_SLOT)). Its launch
+ * guard's end is in the next slot (`uint40` of the word) and its cap two slots on (the top 128 bits).
+ */
+export function walletCapPoolSlot(poolId) {
+    return word(mapping("bytes32", hash(poolId), RULES_SLOT));
+}
+/** The slot of `wallet`'s count of `subject` on launch `launch`, `State.bought[subject][launch][wallet]`. */
+export function walletCapBoughtSlot(subject, launch, wallet) {
+    const bySubject = mapping("address", address(subject), BOUGHT);
+    return word(mapping("address", address(wallet), mapping("uint256", uint(BigInt(launch), 32), bySubject)));
+}
+/**
+ * The launch in a pool's first Bound word: its top 32 bits, `Bound.launchedAt`. The word packs, low to high,
+ * baseFeePips (24 bits), tickSpacing (16), bound (8), quoteIsCurrency0 (8), terms (8), liquidityOwner (160) and
+ * launchedAt (32). Null for anything but 32 bytes of hex with the bound flag set: a pool these Rules never bound.
+ */
+export function walletCapLaunch(value) {
+    if (typeof value !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(value))
+        return null;
+    const w = BigInt(value);
+    return ((w >> 40n) & 0xffn) === 1n ? Number(w >> 224n) : null;
+}
+/**
+ * A pool's cap, in the token's raw units, for a share of `supply` (raw units) in basis points: the floor of
+ * supply × bps / 10,000, so 200 bps of a supply of 10^27 is 2 × 10^25. It goes in the pool's `rules.potMinBuyQuote`.
+ * Refuses a share outside 1 to 10,000 bps and a cap that rounds to zero. hookr.fun offers 0.1% to 10%, 2% by default.
+ */
+export function walletCapAmount(supply, bps) {
+    assert(typeof supply === "bigint" && supply > 0n, "Wallet Cap needs the token's supply in raw units");
+    const share = BigInt(bps);
+    assert(share >= 1n && share <= 10000n, `Wallet Cap share ${share} bps outside 1 to 10,000`);
+    const cap = (supply * share) / 10000n;
+    assert(cap > 0n, "Wallet Cap's share of this supply rounds to zero tokens");
+    return uint(cap, 128);
+}
+/** What a wallet may still buy while the guard lasts: the cap less what it bought, never below zero. */
+export function walletCapRoom(cap, bought) {
+    return bought >= cap ? 0n : cap - bought;
+}
+/** The terms only the Wallet Cap Rules hold a pool to, and the parent block to check its guard against. */
+function walletCapTerms(c, blockNumber) {
+    assert(typeof c.potMinBuyQuote === "bigint" && c.potMinBuyQuote > 0n, "Wallet Cap needs its cap in potMinBuyQuote: the most of the token, in raw units, one wallet may buy during the guard");
+    uint(c.potMinBuyQuote, 128);
+    assert(c.guardEndBlock !== 0, "Wallet Cap lasts as long as the launch guard: set guardEndBlock");
+    assert(blockNumber !== undefined, "Wallet Cap needs blockNumber, the parent block the launch lands in (readParentBlockNumber), to check its guard");
+}
+/**
+ * Refuses a RulesConfig HookrRulesWalletCap's bind would refuse and returns its fee ceilings: `checkRulesConfig` with
+ * the cap set aside, plus the Wallet Cap Rules' own terms: a cap above zero in `potMinBuyQuote` (below 2^128), and a
+ * launch guard, with its liquidity owner, ending within 100,000 parent blocks after `ctx.blockNumber`, which is required
+ * here. `potEveryNBuys` stays zero. Every other Rules refuses a cap: check those with `checkRulesConfig`.
+ */
+export function checkWalletCapRulesConfig(c, ctx) {
+    walletCapTerms(c, ctx.blockNumber);
+    return checkRulesConfig({ ...c, potMinBuyQuote: 0n }, ctx);
+}
+/**
+ * `rulesPoolTerms` for a launch member on the Wallet Cap Rules: every check `checkWalletCapRulesConfig` makes, the
+ * pool's caps and gas limits from the Rules' admission (`admission(HookrRoot, rulesModule(HOOKR_1, "wallet-cap").rules)`
+ * on the registry), and its `rulesData` with the cap. Refuses the admission of any other Rules. The member binds these
+ * Rules as `config.rules` and `l.rules`, cap included, as `rules`; every pool of the launch takes the same cap.
+ */
+export function walletCapPoolTerms(l, ctx, rulesAdmission, advisory, release = HOOKR_1) {
+    const m = rulesModule(release, "wallet-cap");
+    assert(address(rulesAdmission.implementation, true) === address(m.rules) && hash(rulesAdmission.codeHash) === hash(m.rulesRuntimeHash), `Not the admission of ${release.releaseId}'s Wallet Cap Rules ${m.rules}`);
+    walletCapTerms(l.rules, ctx.blockNumber);
+    const terms = rulesPoolTerms({ ...l, rules: { ...l.rules, potMinBuyQuote: 0n } }, ctx, rulesAdmission, advisory);
+    return { ...terms, rulesData: encodeRulesData(l.rules, rulesKnobsOf(l)) };
+}
+/**
+ * Refuses a launch whose members (`buildLaunch`'s) Wallet Cap would leave a way round, or turn against traders, though
+ * the Rules bind each pool alone: some pools on the Wallet Cap Rules and some not, capped pools with different caps (a
+ * wallet could then buy the largest), or capped pools some with arb recapture and some without (on a capped pool
+ * without the lane, the executor's legs count against the trader whose swap set them off). Passes a launch without it.
+ */
+export function checkWalletCapLaunch(members, release = HOOKR_1) {
+    const pin = release.rulesModules["wallet-cap"];
+    const field = (member, part, key) => member[part]?.[key];
+    const capped = (member) => {
+        const rules = field(member, "config", "rules");
+        return pin !== undefined && typeof rules === "string" && rules.toLowerCase() === pin.rules.toLowerCase();
+    };
+    if (!members.some(capped))
+        return;
+    assert(members.every(capped), "Wallet Cap counts a wallet's buys across the launch's pools: every pool binds its Rules, or none does");
+    const caps = new Set(members.map((m) => field(m, "rules", "potMinBuyQuote")));
+    const [cap] = caps;
+    assert(caps.size === 1 && typeof cap === "bigint" && cap > 0n, "Every pool of a Wallet Cap launch takes the same cap, above zero");
+    assert(new Set(members.map((m) => field(m, "recapture", "on") === true)).size === 1, "In a Wallet Cap launch every pool takes arb recapture, or none does");
+}
+/**
+ * Reads a pool on the Wallet Cap Rules through their `extsload`: its launch, guard end and cap from its Bound
+ * (`walletCapPoolSlot` and the two slots after it), then, with a wallet, that wallet's count on the launch
+ * (`walletCapBoughtSlot`) and its room. Null for a pool these Rules have not bound: a pool on any other Rules has no
+ * wallet cap. A count and its room hold while the guard lasts; after it nothing is counted or capped.
+ */
+export async function readWalletCap(client, query, release = HOOKR_1) {
+    assert((query.wallet === undefined) === (query.subject === undefined), "A wallet's count needs the pool's subject");
+    const rules = rulesModule(release, "wallet-cap").rules;
+    const at = query.blockNumber === undefined ? {} : { blockNumber: query.blockNumber };
+    const read = async (slot) => {
+        const data = encodeFunctionData({ abi: WALLET_CAP_ABI, functionName: "extsload", args: [word(slot)] });
+        const answer = (await client.call({ to: rules, data, ...at })).data;
+        assert(typeof answer === "string" && /^0x[0-9a-fA-F]{64}$/.test(answer), `The Wallet Cap Rules ${rules} answered extsload with ${answer}`);
+        return answer;
+    };
+    const pool = BigInt(walletCapPoolSlot(query.poolId));
+    const [first, second, third] = await Promise.all([read(pool), read(pool + 1n), read(pool + 2n)]);
+    const launch = walletCapLaunch(first);
+    if (launch === null)
+        return null;
+    const cap = BigInt(third) >> 128n;
+    assert(cap > 0n, `The Wallet Cap Rules ${rules} hold no cap for pool ${query.poolId}`);
+    const guardEndBlock = BigInt(second) & ((1n << 40n) - 1n);
+    if (query.wallet === undefined)
+        return { launch, guardEndBlock, cap, bought: null, room: null };
+    const bought = BigInt(await read(BigInt(walletCapBoughtSlot(query.subject, launch, query.wallet))));
+    return { launch, guardEndBlock, cap, bought, room: walletCapRoom(cap, bought) };
+}
+/**
+ * The errors a refusal can reach a caller inside: the root's and the lane's (a module's own revert), the PoolManager's
+ * (a hook's revert in a swap) and the quoter's (a quoted swap's revert).
+ */
+const REFUSAL_ABI = [
+    ...WALLET_CAP_ABI,
+    ...parseAbi([
+        "error ModuleCallReverted(address module, bytes4 callSelector, bytes reason)",
+        "error WrappedError(address target, bytes4 selector, bytes reason, bytes details)",
+        "error SimulationFailed(bytes reason)",
+    ]),
+];
+/** The most wrappers stripped from one revert, so a malformed one cannot recurse without end. */
+const MAX_WRAPS = 4;
+const hex = (value) => typeof value === "string" && /^0x([0-9a-fA-F]{2})+$/.test(value) ? value : null;
+/** Revert data: a hex string as given, or the data a viem error carries anywhere in its cause chain. */
+function revertData(error) {
+    if (typeof error === "string")
+        return hex(error);
+    for (let e = error, depth = 0; e !== null && typeof e === "object" && depth < 16; depth++) {
+        const { raw, data, cause } = e;
+        const found = hex(raw) ?? hex(data) ?? hex(data?.data);
+        if (found)
+            return found;
+        e = cause;
+    }
+    return null;
+}
+/**
+ * The GuardWalletLimit inside a failed quote, swap or launch, however the root, the lane, the PoolManager and the quoter
+ * wrapped it, or null. Takes the revert data, or the viem error that carries it.
+ */
+export function walletCapRefusal(error) {
+    let data = revertData(error);
+    for (let wraps = 0; data !== null && wraps <= MAX_WRAPS; wraps++) {
+        let e;
+        try {
+            e = decodeErrorResult({ abi: REFUSAL_ABI, data });
+        }
+        catch (caught) {
+            if (!(caught instanceof BaseError))
+                throw caught;
+            return null;
+        }
+        if (e.errorName === "GuardWalletLimit") {
+            const [wallet, actual, limit] = e.args;
+            return { wallet: getAddress(wallet), actual, limit };
+        }
+        if (e.errorName === "ModuleCallReverted" || e.errorName === "WrappedError")
+            data = hex(e.args[2]);
+        else if (e.errorName === "SimulationFailed")
+            data = hex(e.args[0]);
+        else
+            return null;
+    }
+    return null;
+}
+/** Names Wallet Cap's refusal in `error` (revert data, or the viem error that carries it), or null. */
+export function walletCapRevert(error) {
+    const r = walletCapRefusal(error);
+    return r
+        ? `The buy would bring ${r.wallet}'s buys of the subject during the launch guard to ${r.actual}, above the pool's wallet cap ${r.limit}`
+        : null;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hookr-sdk",
-  "version": "1.0.0",
-  "description": "Build on Hookr 1: launch tokens with Hook Blocks, open pools, quote, swap and claim on Robinhood Chain.",
+  "version": "1.1.1",
+  "description": "Build on Hookr, the Uniswap v4 hook on Robinhood Chain: launch tokens with Hook Blocks, open pools, quote and swap.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://hookr.fun/docs",
@@ -12,7 +12,7 @@
     "v4-hooks",
     "hooks",
     "hook-blocks",
-    "launchpad",
+    "token-launch",
     "robinhood-chain",
     "viem",
     "sdk"