hookr-sdk 0.2.1 → 1.1.0

package/CHANGELOG.md

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

package/LICENSE

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

package/MIGRATING.md

@@ -0,0 +1,89 @@
+# Moving from 0.2.x to 1.0
+
+1.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 pools on the V6 roots
+
+Pools on `HookrModularHookV6` (`0xb3cA29cF721380CEe8b8e4755F3865Ebc68Fe8cC`) and `HookrModularHookV6WthV5` (`0xb914f955294799de4b891bd2EA8AF628Fa1c68CC`) keep trading. 0.2.x stays on npm for them:
+
+```
+npm install hookr-sdk@0.2
+```
+
+An app that serves both sets of pools can install both under two names:
+
+```
+npm install hookr-sdk hookr-sdk-v0@npm:hookr-sdk@0.2
+```
+
+Pick by the pool's `PoolKey.hooks`: `HOOKR_1.contracts.HookrRoot` is 1.x's, the two roots above are 0.2.x's.
+
+## What changes
+
+One root instead of two. Arb recapture is no longer a separate root: each pool turns it on or off at launch in its `RecaptureConfig`, on the same `HookrRoot`.
+
+The builders return a call, `{ chainId, to, data, value }`, and take the release's manifest:
+
+```ts
+// 0.2.x
+const call = buildExactInputSwapCall({ key, currencyIn, amountIn, amountOutMinimum, recipient, deadline });
+await walletClient.writeContract(call);
+
+// 1.0
+const manifest = await readReleaseManifest(client, HOOKR_1);
+const call = buildSwap(manifest, { key, zeroForOne, amountSpecified: -amountIn, amountBound: amountOutMinimum, sqrtPriceLimitX96, recipient, deadline });
+await walletClient.sendTransaction({ to: call.to, data: call.data, value: call.value });
+```
+
+## Export by export
+
+| 0.2.x | 1.0 |
+| --- | --- |
+| `ADDRESSES.root`, `ADDRESSES.recaptureRoot`, `ROOTS` | `HOOKR_1.contracts.HookrRoot` |
+| `ADDRESSES.router` | `HOOKR_1.contracts.HookrRouter` |
+| `ADDRESSES.quoter` | `HOOKR_1.contracts.HookrQuoter` |
+| `ADDRESSES.coordinator` | `HOOKR_1.contracts.HookrLauncher` |
+| `ADDRESSES.nativeBlock` | `HOOKR_1.contracts.HookrRules` |
+| `ADDRESSES.registry` | `HOOKR_1.contracts.HookrRegistry` |
+| `KERNEL_ID`, `RECAPTURE_KERNEL_ID`, `MODULE_ID`, `RECAPTURE_CORRECTION`, `isRecaptureRoot` | none: one root, and arb recapture is each pool's `RecaptureConfig`. Pass `RECAPTURE_OFF`, or `recaptureDefaults()` read with `recaptureAbi` at the HookrRules address |
+| `NATIVE_ADDRESS` | `ZERO` |
+| `EXPLORER_URL`, `explorerAddressUrl`, `explorerTxUrl` | the same names, on RobinScan (`https://robin.etherscan.io`) |
+| `DYNAMIC_FEE`, `MIN_SQRT_PRICE_LIMIT`, `MAX_SQRT_PRICE_LIMIT` | the same names and values |
+| `fullFillLimit(zeroForOne)` | `MIN_SQRT_PRICE_LIMIT` for `zeroForOne`, `MAX_SQRT_PRICE_LIMIT` the other way |
+| `swapDirection(key, currencyIn)` | `zeroForOne` is `currencyIn === key.currency0` |
+| `subjectIsCurrency0(subject, quote)` | the lower address is `currency0`, as in every v4 `PoolKey` |
+| `INT128_MAX`, `QUOTE_MIN_OUT_BOUND`, `EMPTY_MODULE_DATA` | none: `amountBound: 1n` on an exact-input quote, and a swap carries no module data |
+| `MAX_TOTAL_FEE_PIPS`, `MIN_BASE_FEE_PIPS`, `baseFeeBounds` | `MAX_LP_FEE_PIPS` (600,000), and `baseLpFeePips` in `RULE_PARAMS.pool`, with its range |
+| `RULES`, `PARAMS`, `RULE_ORDER`, `ruleFor`, `MAX_STACK_RULES`, `defaultBlock`, `defaultStack`, `validateStack`, `compileRuleBlocks` | `RULE_PARAMS`, `defaultRulesLaunch`, `defaultRuleParams`, `checkRuleParams`, `rulesPoolTerms` |
+| `encodeNativeBlockConfig`, `decodeNativeBlockConfig` | `encodeRulesConfig`, `decodeRulesConfig` |
+| `guardEndBlockFor` | `defaultRulesLaunch` sets `guardEndBlock` from the block number. `MAX_GUARD_BLOCKS` keeps its value |
+| `MODULE_GAS`, `stackLimitsFor`, `correctionFor` | `rulesPoolTerms`, which returns the pool's caps and gas |
+| `ZERO_BYTES32` | `zeroHash` from viem |
+| `feeModel` | `rulesQuote`, `rulesSwapFees`, `recaptureSplit` |
+| `poolKeyFor`, `poolIdFor` | a `PoolKey` with `fee: DYNAMIC_FEE` and `hooks: HOOKR_1.contracts.HookrRoot`, and `poolId(key)` |
+| `buildNewTokenMarketCall` | `buildLaunch` with `token.existing` zero |
+| `buildExistingTokenMarketCall` | `buildLaunch` with `token.existing` the token |
+| `encodeMarketCall` | the `data` of the call `buildLaunch` returns |
+| `buildExactInputSwapCall`, `buildExactOutputSwapCall` | `buildSwap`: a negative `amountSpecified` is exact input, a positive one exact output |
+| `quoteExactInput` | `buildQuote`, sent as an `eth_call` from the payer |
+| `CORRECTION_SWAP_GAS_FLOOR`, `swapGasLimit`, `isCorrectingRoot`, `poolCorrects` | `gasFloor` from `laneOf(id)` on `HookrRoot` (`laneRootAbi`), `laneGasFloor(gasCap)` |
+| `readMarket`, `readPoolRules` | `poolConfig(id)` on `HookrRoot` (`rootAbi`), `config(id)` on the pool's HookrRules (`rulesAbi`), `laneOf(id)` (`laneRootAbi`) |
+| `listMarkets`, `listRoots`, `MARKET_CREATED_TOPIC`, `MARKET_SCAN_FROM_BLOCK`, `MARKET_SCAN_CHUNK_BLOCKS`, `MARKET_SCAN_CONCURRENCY` | none: read `PoolOpened` (`rootAbi`) and `MemberLaunched` (`launcherAbi`) with your own log reader |
+| `MAX_LOG_BLOCK_RANGE`, `logBlockRange`, `logBlockRanges`, `capLogSpan` | none: ask for at most 5,000 blocks a request |
+| `claimableCall`, `claimCall`, `claimToCall` | `claimable`, `claim` and `claimTo` (`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` |
+| every other 0.2.x export | removed |
+
+`CHAIN_ID`, `RPC_URL`, `PoolKey`, `DYNAMIC_FEE`, `MIN_SQRT_PRICE_LIMIT`, `MAX_SQRT_PRICE_LIMIT`, `DEFAULT_PROTOCOL_SHARE_BPS`, `MAX_PROTOCOL_SHARE_BPS` and `MAX_GUARD_BLOCKS` keep their names and values. `EXPLORER_URL`, `explorerAddressUrl` and `explorerTxUrl` keep their names and open RobinScan, where 0.2.x opened Blockscout. `RootStatus` keeps its name with a new shape.
+
+## Fees and arb recapture
+
+On the 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 `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
+
+Node 18.16 or newer, viem 2, ESM. `ROBINHOOD_CHAIN` works on any viem 2. viem's own `robinhood` chain needs viem 2.55 or newer.