hookr-sdk 0.2.0 → 0.2.1

package/README.md

@@ -99,8 +99,11 @@ const swapCall = buildExactInputSwapCall({ key, currencyIn: market.quote, amount
 A swap on a recapture pool needs more gas than an estimate reports, because the correction is
 fail-open: an estimate converges on the cheapest swap that succeeds, which is the one that skipped
 the correction. The swap builders put `gas: CORRECTION_SWAP_GAS_FLOOR` (1,100,000, the app's
-floor) on the call whenever the pool's root corrects, so pass the call to `writeContract` as it
-is; on the default root the call carries no `gas` and the wallet estimates as usual.
+floor) on the call whenever the pool's root is the current recapture root, so pass the call to
+`writeContract` as it is; on the default root the call carries no `gas` and the wallet estimates
+as usual. A pool opened on a superseded recapture root keeps its executor and keeps correcting;
+read `poolCorrects(await readPoolRules(client, poolId))` and pass it as `correcting` to the swap
+builders to put the same floor on that call (since 0.2.1).
 
 ## Roots
 
@@ -138,6 +141,9 @@ parity test in that repository keeps the package and the app in step.
 
 ## Changes
 
+- 0.2.1: the swap builders take `correcting` (default `isCorrectingRoot(key.hooks)`, the current
+  recapture root), and `poolCorrects(rules)` reads from a pool's frozen rules whether it names a
+  correction executor, so a pool on a superseded recapture root can carry the gas floor too.
 - 0.2.0: names both live roots (`ADDRESSES.recaptureRoot`, `RECAPTURE_KERNEL_ID`, `ROOTS`); the
   market builders take `root` and freeze the recapture correction fields (`RECAPTURE_CORRECTION`);
   swap calls carry `gas: CORRECTION_SWAP_GAS_FLOOR` on a correcting root; `listMarkets` scans in

package/dist/reads.d.ts

@@ -98,6 +98,15 @@ export type PoolRules = Readonly<{
  * by this package.
  */
 export declare function readPoolRules(client: PublicClient, poolId: Hex): Promise<PoolRules>;
+/**
+ * True when the pool's frozen rules name a correction executor, so the root's kernel dispatches a
+ * correction around every swap and the swap needs `CORRECTION_SWAP_GAS_FLOOR`. This is the pool's
+ * own record rather than the root's identity: a pool on a superseded recapture root keeps its
+ * executor and keeps correcting, which `isCorrectingRoot` (current root only) does not see. Pass
+ * the result as `correcting` to the swap builders. It is also true for a pool whose lane cannot
+ * run on ordinary gas (the first recapture root); the floor is then unused headroom, not a loss.
+ */
+export declare function poolCorrects(rules: PoolRules): boolean;
 /** `HookrStackRegistryV1.KernelStatus`. */
 export type RootStatus = "unset" | "active" | "retired";
 /** One registered root (kernel) as the stack registry records it. */

package/dist/reads.js

@@ -11,7 +11,7 @@
  */
 import { decodeAbiParameters, getAbiItem, toEventSelector } from "viem";
 import { hookrMarketCoordinatorV5Abi, hookrStackRegistryV2Abi } from "./abi.js";
-import { ADDRESSES, MODULE_ID } from "./chain.js";
+import { ADDRESSES, MODULE_ID, NATIVE_ADDRESS } from "./chain.js";
 function marketOrigin(value) {
     if (value === 1)
         return "new-token";
@@ -153,6 +153,18 @@ export async function readPoolRules(client, poolId) {
     }
     return Object.freeze({ configured: true, limits: core.limits, nativeConfig });
 }
+/**
+ * True when the pool's frozen rules name a correction executor, so the root's kernel dispatches a
+ * correction around every swap and the swap needs `CORRECTION_SWAP_GAS_FLOOR`. This is the pool's
+ * own record rather than the root's identity: a pool on a superseded recapture root keeps its
+ * executor and keeps correcting, which `isCorrectingRoot` (current root only) does not see. Pass
+ * the result as `correcting` to the swap builders. It is also true for a pool whose lane cannot
+ * run on ordinary gas (the first recapture root); the floor is then unused headroom, not a loss.
+ */
+export function poolCorrects(rules) {
+    const executor = rules.limits?.correctionExecutor;
+    return executor !== undefined && executor.toLowerCase() !== NATIVE_ADDRESS.toLowerCase();
+}
 function rootStatus(value) {
     if (value === 0)
         return "unset";

package/dist/swap.d.ts

@@ -12,18 +12,26 @@ import { hookrKernelRouterV3Abi } from "./abi.js";
 import type { PoolKey } from "./market.js";
 /**
  * The gas limit a swap on a correcting root must carry (the app's `CORRECTION_SWAP_GAS_FLOOR` in
- * `src/lib/gas-headroom.ts`). The recapture root runs its correction after the swap inside a bounded
- * call that fails open: a wallet's gas estimate covers the swap alone, so an estimated transaction
- * succeeds with the correction skipped and nothing recaptured. The swap builders below put this
- * floor on the call whenever `key.hooks` is a correcting root; pass it through to `writeContract`
- * (viem sends `gas` as the limit) instead of estimating.
+ * `src/lib/gas-headroom.ts`). The recapture root runs its correction in both swap phases, once in
+ * `beforeSwap` and again in `afterSwap` (`HookrSwapKernelV5Wth.sol`, `_tryCorrection` at lines 214
+ * and 250), each inside a bounded call that fails open: a wallet's gas estimate covers the swap
+ * alone, so an estimated transaction succeeds with the correction skipped and nothing recaptured.
+ * The swap builders below put this floor on the call whenever `key.hooks` is the current recapture
+ * root, or whenever the caller passes `correcting: true`; pass it through to `writeContract` (viem
+ * sends `gas` as the limit) instead of estimating.
  */
 export declare const CORRECTION_SWAP_GAS_FLOOR = 1100000n;
-/** True when `hooks` is a root that corrects after the swap: today the recapture root. */
+/**
+ * True when `hooks` is the current recapture root, which corrects in both swap phases. This is the
+ * root's identity, not the pool's: a pool opened on a superseded recapture root keeps the executor
+ * frozen into its rules and keeps correcting, and this returns false for it. Read that from the
+ * pool itself with `poolCorrects(await readPoolRules(client, poolId))` and pass the answer as
+ * `correcting` to the swap builders.
+ */
 export declare function isCorrectingRoot(hooks: Address): boolean;
-/** The gas limit to send with a swap on `key`: the floor on a correcting root, else `undefined`
- *  (let the wallet estimate). */
-export declare function swapGasLimit(key: PoolKey): bigint | undefined;
+/** The gas limit to send with a swap on `key`: the floor when the pool corrects (`correcting`,
+ *  defaulting to `isCorrectingRoot(key.hooks)`), else `undefined` (let the wallet estimate). */
+export declare function swapGasLimit(key: PoolKey, correcting?: boolean): bigint | undefined;
 /** Router / block `MIN_SQRT_PRICE_LIMIT`: the full-fill limit for a `zeroForOne` swap. */
 export declare const MIN_SQRT_PRICE_LIMIT = 4295128740n;
 /** Router / block `MAX_SQRT_PRICE_LIMIT`: the full-fill limit for a `oneForZero` swap. */
@@ -45,13 +53,14 @@ export type RouterCall<F extends "exactInput" | "exactOutput"> = Readonly<{
     functionName: F;
     args: ContractFunctionArgs<typeof hookrKernelRouterV3Abi, "payable", F>;
     value: bigint;
-    /** Set to `CORRECTION_SWAP_GAS_FLOOR` when the pool's root corrects after the swap; absent otherwise. */
+    /** Set to `CORRECTION_SWAP_GAS_FLOOR` when the pool corrects; absent otherwise. */
     gas?: bigint;
 }>;
 /**
  * `exactInput` through the Hookr router. `value` is `amountIn` when `currencyIn` is native ETH,
  * else 0 (the router pulls the ERC-20 by `transferFrom`; approve it first). `gas` carries the
- * correction floor when the pool sits on a correcting root; send it as the gas limit.
+ * correction floor when the pool corrects; send it as the gas limit. `correcting` defaults to
+ * `isCorrectingRoot(key.hooks)`; pass `poolCorrects(rules)` for a pool on a superseded root.
  */
 export declare function buildExactInputSwapCall(input: {
     key: PoolKey;
@@ -60,10 +69,12 @@ export declare function buildExactInputSwapCall(input: {
     amountOutMinimum: bigint;
     recipient: Address;
     deadline: bigint;
+    correcting?: boolean;
 }): RouterCall<"exactInput">;
 /**
  * `exactOutput` through the Hookr router. `value` is `amountInMaximum` when `currencyIn` is
- * native ETH — the router refunds what the swap does not use.
+ * native ETH — the router refunds what the swap does not use. `correcting` works as on
+ * `buildExactInputSwapCall`.
  */
 export declare function buildExactOutputSwapCall(input: {
     key: PoolKey;
@@ -72,6 +83,7 @@ export declare function buildExactOutputSwapCall(input: {
     amountInMaximum: bigint;
     recipient: Address;
     deadline: bigint;
+    correcting?: boolean;
 }): RouterCall<"exactOutput">;
 export type Quote = Readonly<{
     amountIn: bigint;

package/dist/swap.js

@@ -2,21 +2,29 @@ import { hookrKernelQuoterV1Abi, hookrKernelRouterV3Abi } from "./abi.js";
 import { ADDRESSES, NATIVE_ADDRESS } from "./chain.js";
 /**
  * The gas limit a swap on a correcting root must carry (the app's `CORRECTION_SWAP_GAS_FLOOR` in
- * `src/lib/gas-headroom.ts`). The recapture root runs its correction after the swap inside a bounded
- * call that fails open: a wallet's gas estimate covers the swap alone, so an estimated transaction
- * succeeds with the correction skipped and nothing recaptured. The swap builders below put this
- * floor on the call whenever `key.hooks` is a correcting root; pass it through to `writeContract`
- * (viem sends `gas` as the limit) instead of estimating.
+ * `src/lib/gas-headroom.ts`). The recapture root runs its correction in both swap phases, once in
+ * `beforeSwap` and again in `afterSwap` (`HookrSwapKernelV5Wth.sol`, `_tryCorrection` at lines 214
+ * and 250), each inside a bounded call that fails open: a wallet's gas estimate covers the swap
+ * alone, so an estimated transaction succeeds with the correction skipped and nothing recaptured.
+ * The swap builders below put this floor on the call whenever `key.hooks` is the current recapture
+ * root, or whenever the caller passes `correcting: true`; pass it through to `writeContract` (viem
+ * sends `gas` as the limit) instead of estimating.
  */
 export const CORRECTION_SWAP_GAS_FLOOR = 1100000n;
-/** True when `hooks` is a root that corrects after the swap: today the recapture root. */
+/**
+ * True when `hooks` is the current recapture root, which corrects in both swap phases. This is the
+ * root's identity, not the pool's: a pool opened on a superseded recapture root keeps the executor
+ * frozen into its rules and keeps correcting, and this returns false for it. Read that from the
+ * pool itself with `poolCorrects(await readPoolRules(client, poolId))` and pass the answer as
+ * `correcting` to the swap builders.
+ */
 export function isCorrectingRoot(hooks) {
     return hooks.toLowerCase() === ADDRESSES.recaptureRoot.toLowerCase();
 }
-/** The gas limit to send with a swap on `key`: the floor on a correcting root, else `undefined`
- *  (let the wallet estimate). */
-export function swapGasLimit(key) {
-    return isCorrectingRoot(key.hooks) ? CORRECTION_SWAP_GAS_FLOOR : undefined;
+/** The gas limit to send with a swap on `key`: the floor when the pool corrects (`correcting`,
+ *  defaulting to `isCorrectingRoot(key.hooks)`), else `undefined` (let the wallet estimate). */
+export function swapGasLimit(key, correcting) {
+    return (correcting ?? isCorrectingRoot(key.hooks)) ? CORRECTION_SWAP_GAS_FLOOR : undefined;
 }
 /** Router / block `MIN_SQRT_PRICE_LIMIT`: the full-fill limit for a `zeroForOne` swap. */
 export const MIN_SQRT_PRICE_LIMIT = 4295128740n;
@@ -45,12 +53,13 @@ export function swapDirection(key, currencyIn) {
 /**
  * `exactInput` through the Hookr router. `value` is `amountIn` when `currencyIn` is native ETH,
  * else 0 (the router pulls the ERC-20 by `transferFrom`; approve it first). `gas` carries the
- * correction floor when the pool sits on a correcting root; send it as the gas limit.
+ * correction floor when the pool corrects; send it as the gas limit. `correcting` defaults to
+ * `isCorrectingRoot(key.hooks)`; pass `poolCorrects(rules)` for a pool on a superseded root.
  */
 export function buildExactInputSwapCall(input) {
     const zeroForOne = swapDirection(input.key, input.currencyIn);
     const native = input.currencyIn.toLowerCase() === NATIVE_ADDRESS.toLowerCase();
-    const gas = swapGasLimit(input.key);
+    const gas = swapGasLimit(input.key, input.correcting);
     return Object.freeze({
         address: ADDRESSES.router,
         abi: hookrKernelRouterV3Abi,
@@ -73,12 +82,13 @@ export function buildExactInputSwapCall(input) {
 }
 /**
  * `exactOutput` through the Hookr router. `value` is `amountInMaximum` when `currencyIn` is
- * native ETH — the router refunds what the swap does not use.
+ * native ETH — the router refunds what the swap does not use. `correcting` works as on
+ * `buildExactInputSwapCall`.
  */
 export function buildExactOutputSwapCall(input) {
     const zeroForOne = swapDirection(input.key, input.currencyIn);
     const native = input.currencyIn.toLowerCase() === NATIVE_ADDRESS.toLowerCase();
-    const gas = swapGasLimit(input.key);
+    const gas = swapGasLimit(input.key, input.correcting);
     return Object.freeze({
         address: ADDRESSES.router,
         abi: hookrKernelRouterV3Abi,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hookr-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Build a market on Hookr's live root hooks, quote and swap through its router, read markets, and claim payouts.",
   "type": "module",
   "license": "MIT",