hookr-sdk 0.2.1 → 1.1.0

package/dist/core/rules.js

@@ -0,0 +1,1049 @@
+import { decodeAbiParameters, decodeFunctionResult, encodeAbiParameters, encodeFunctionData, keccak256, stringToBytes, } from "viem";
+import { recaptureAbi, rulesAbi, treasuryAbi } from "./abi.js";
+import { RELEASE_CONSTANTS, STRUCT_COMPONENTS } from "./generated.js";
+import { address, assert, uint, ZERO } from "./schema.js";
+/** Gas every Rules admission, and so every pool bound to HookrRules, carries: exactly 2,000,000. */
+export const RULES_GAS_LIMIT = RELEASE_CONSTANTS.REGISTRY_RULES_MIN_GAS_LIMIT;
+/** Ceiling on any LP fee, in pips. */
+export const MAX_LP_FEE_PIPS = 600_000;
+/**
+ * Highest protocol share a pool binds with, in basis points (HookrRules._validate), and highest minimum a HookrRules
+ * can be built with (its constructor): 50%.
+ */
+export const MAX_PROTOCOL_SHARE_BPS = 5_000;
+/**
+ * Rule-fee terms the treasury governs (HookrTreasury, r23): the highest governed floor of a pool's protocolShareBps,
+ * the highest integrator rate (in basis points of Hookr's rule-fee share; HookrRules refuses a larger one at bind too)
+ * and the rate the app pre-fills, and how long a proposed change waits and then stays acceptable, in seconds.
+ */
+export const MAX_RULE_SHARE_FLOOR_BPS = Number(RELEASE_CONSTANTS.TREASURY_MAX_RULE_SHARE_FLOOR_BPS);
+export const MAX_INTEGRATOR_BPS = Number(RELEASE_CONSTANTS.RULES_MAX_INTEGRATOR_BPS);
+export const DEFAULT_INTEGRATOR_BPS = Number(RELEASE_CONSTANTS.TREASURY_DEFAULT_INTEGRATOR_BPS);
+export const FEE_TERMS_DELAY_SECONDS = Number(RELEASE_CONSTANTS.TREASURY_TERMS_DELAY);
+export const FEE_TERMS_GRACE_SECONDS = Number(RELEASE_CONSTANTS.TREASURY_TERMS_GRACE);
+/**
+ * The Hookr minimum (r25, HookrTreasury): the least Hookr takes of every trader swap on a Hookr token's pool, in pips
+ * of the swap, frozen at bind. The treasury holds a rate for pools without arb recapture and one for pools with it,
+ * each 0 to MAX_MIN_FEE_PIPS (10,000, 1%) and DEFAULT_MIN_FEE_PIPS (1,000, 0.1%) at deployment, and a per-integrator
+ * override (0 to 10,000; NO_MIN_FEE_OVERRIDE, 65,535, reads as none) that reaches only the pool ids that integrator
+ * approved (`approveMinFeePool`). HookrRules refuses a minimum above its own MAX_MIN_FEE_PIPS at bind.
+ */
+export const MAX_MIN_FEE_PIPS = Number(RELEASE_CONSTANTS.TREASURY_MAX_MIN_FEE_PIPS);
+export const DEFAULT_MIN_FEE_PIPS = Number(RELEASE_CONSTANTS.TREASURY_DEFAULT_MIN_FEE_PIPS);
+export const NO_MIN_FEE_OVERRIDE = Number(RELEASE_CONSTANTS.TREASURY_NO_MIN_FEE_OVERRIDE);
+export const RULES_MAX_MIN_FEE_PIPS = Number(RELEASE_CONSTANTS.RULES_MAX_MIN_FEE_PIPS);
+/**
+ * The runtime keccak256 of HookrToken, the token HookrLauncher creates. It has no immutables, so every HookrToken has
+ * this codehash; HookrRules compares a pool's subject's codehash with it at bind and freezes the Hookr minimum only
+ * on a match, and then only on a pool without arb recapture whose rules earn Hookr nothing (`bindMinFeePips`). A token
+ * of any other code binds none; HookrToken bytecode deployed outside the launcher binds it.
+ */
+export const HOOKR_TOKEN_RUNTIME_KECCAK256 = RELEASE_CONSTANTS.HOOKR_TOKEN_RUNTIME_KECCAK256;
+/**
+ * Hookr's cut of every arb recapture, in basis points of the profit the root reads back from each push at the pool's
+ * frozen partner share (HookrRecapture.RECAPTURE_PROTOCOL_BPS): 25% since r31, on every pool, whatever its
+ * protocolShareBps or integrator.
+ */
+export const RECAPTURE_PROTOCOL_BPS = Number(RELEASE_CONSTANTS.RECAPTURE_PROTOCOL_BPS);
+/**
+ * HookrRegistryChecks.MAX_LANE_PARTNER_BPS: the most a lane partner keeps of each arb recapture's profit, 25% since
+ * r31, checked at every lane opening.
+ */
+export const MAX_LANE_PARTNER_BPS = Number(RELEASE_CONSTANTS.MAX_LANE_PARTNER_BPS);
+/** HookrRecapture.PRIZE_SHARE_OF_FEE_BPS: a King of the Pool prize reaches at most half the protocol fee it bounds. */
+export const PRIZE_SHARE_OF_FEE_BPS = Number(RELEASE_CONSTANTS.RECAPTURE_PRIZE_SHARE_OF_FEE_BPS);
+/**
+ * Longest Anti-Snipe decay any guard binds with, in seconds (HookrTypes.MAX_SNIPE_DECAY_SECONDS, an hour); since r31 a
+ * longer guard may decay over its whole length (`maxSnipeDecaySeconds`).
+ */
+export const MAX_SNIPE_DECAY_SECONDS = Number(RELEASE_CONSTANTS.RULES_MAX_SNIPE_DECAY_SECONDS);
+/** HookrLauncher.DYNAMIC_FEE_LIQUIDITY_DIVISOR: a dynamic fee member's launch liquidity over this is its minimum. */
+export const DYNAMIC_FEE_LIQUIDITY_DIVISOR = BigInt(RELEASE_CONSTANTS.LAUNCHER_DYNAMIC_FEE_LIQUIDITY_DIVISOR);
+/** Hookr dynamic fee reference windows (HookrRules.dynamicFeeParameters), in seconds, basis points and ticks. */
+export const DYNAMIC_FEE_PARAMETERS = {
+    window: Number(RELEASE_CONSTANTS.RULES_DYNAMIC_FEE_WINDOW),
+    reset: Number(RELEASE_CONSTANTS.RULES_DYNAMIC_FEE_RESET),
+    carryBps: Number(RELEASE_CONSTANTS.RULES_DYNAMIC_FEE_CARRY_BPS),
+    moveTicks: Number(RELEASE_CONSTANTS.RULES_DYNAMIC_FEE_MOVE_TICKS),
+};
+/**
+ * RulesKnobs bounds HookrRules enforces at bind (HookrTypes): a dynamic fee pool's window, its reset (a multiple of the
+ * reset step from the larger of twice the window and the reset floor), its carry (a multiple of the carry step) and its
+ * counted move; the Snipe curves; and the parent block length a guard's wall-clock length is counted in.
+ */
+export const RULES_KNOB_BOUNDS = {
+    minWindowSeconds: Number(RELEASE_CONSTANTS.RULES_MIN_WINDOW_SECONDS),
+    maxWindowSeconds: Number(RELEASE_CONSTANTS.RULES_MAX_WINDOW_SECONDS),
+    minResetSeconds: Number(RELEASE_CONSTANTS.RULES_MIN_RESET_SECONDS),
+    maxResetSeconds: Number(RELEASE_CONSTANTS.RULES_MAX_RESET_SECONDS),
+    resetStepSeconds: Number(RELEASE_CONSTANTS.RULES_RESET_STEP_SECONDS),
+    maxCarryBps: Number(RELEASE_CONSTANTS.RULES_MAX_CARRY_BPS),
+    carryStepBps: Number(RELEASE_CONSTANTS.RULES_CARRY_STEP_BPS),
+    minMoveTicks: Number(RELEASE_CONSTANTS.RULES_MIN_MOVE_TICKS),
+    maxMoveTicks: Number(RELEASE_CONSTANTS.RULES_MAX_MOVE_TICKS),
+};
+/** RulesKnobs.snipeCurve (HookrTypes.SNIPE_CURVE_*): linear (the default), front-loaded and step. */
+export const SNIPE_CURVE = {
+    linear: Number(RELEASE_CONSTANTS.RULES_SNIPE_CURVE_LINEAR),
+    frontLoaded: Number(RELEASE_CONSTANTS.RULES_SNIPE_CURVE_FRONT_LOADED),
+    step: Number(RELEASE_CONSTANTS.RULES_SNIPE_CURVE_STEP),
+};
+/** HookrTypes.PARENT_BLOCK_SECONDS: a guard's length in parent blocks times this bounds a longer Snipe decay. */
+export const PARENT_BLOCK_SECONDS = Number(RELEASE_CONSTANTS.RULES_PARENT_BLOCK_SECONDS);
+/** The knobs of a pool bound without any (`abi.encode(RulesConfig)`): every field zero. */
+export const NO_RULES_KNOBS = Object.freeze({
+    minDynamicFeeLiquidity: 0n,
+    windowSeconds: 0,
+    resetSeconds: 0,
+    carryBps: 0,
+    moveTicks: 0,
+    snipeCurve: 0,
+});
+/**
+ * HookrDynamicFee's reach bound (r31, N09): a dynamic fee pool binds only when its span (maxFeePips less the base fee)
+ * times its sensitivity squared is at most `maxReach`, and its span times its protocol share times (`reserveScale` less
+ * the sensitivity squared) at most `maxReserve` times `reserveScale`.
+ */
+export const DYNAMIC_FEE_REACH = {
+    maxReach: BigInt(RELEASE_CONSTANTS.DYNAMIC_FEE_MAX_REACH),
+    maxReserve: BigInt(RELEASE_CONSTANTS.DYNAMIC_FEE_MAX_RESERVE),
+    reserveScale: BigInt(RELEASE_CONSTANTS.DYNAMIC_FEE_RESERVE_SCALE),
+};
+const MAX_MIN_LIQUIDITY = (1n << 96n) - 1n;
+const WAD = 10n ** 18n;
+/** Longest launch guard, in blocks after the binding block. */
+export const MAX_GUARD_BLOCKS = 100_000;
+const PIPS = 1000000n;
+const BPS = 10000n;
+const MAX_LP = BigInt(MAX_LP_FEE_PIPS);
+const RULES_TUPLE = [{ type: "tuple", components: STRUCT_COMPONENTS.RulesConfig }];
+const KNOBS_RULES_TUPLE = [...RULES_TUPLE, { type: "tuple", components: STRUCT_COMPONENTS.RulesKnobs }];
+const RECAPTURE_RULES_TUPLE = [
+    ...KNOBS_RULES_TUPLE,
+    { type: "tuple", components: STRUCT_COMPONENTS.RecaptureConfig },
+];
+/**
+ * RulesConfig's type string, `RulesConfig(uint40 guardEndBlock,...,address integrator)`, built from the struct's ABI
+ * components in declaration order (16 fields since r23 appended `integrator`).
+ */
+export const RULES_CONFIG_TYPE = `RulesConfig(${STRUCT_COMPONENTS.RulesConfig.map((f) => `${f.type} ${f.name}`).join(",")})`;
+/**
+ * The Rules' schema id (r26): HookrRules.configSchemaHash() is the keccak256 of RULES_CONFIG_TYPE, and
+ * HookrFeeAdvisory.RULES_SCHEMA and HookrSessionAdvisory's RULES_SCHEMA read the same id. A Rules admission carries it
+ * as its `schemaHash` (the lane checks the admission against the Rules' own answer), and a reader that gates on it
+ * refuses any other layout.
+ */
+export const RULES_CONFIG_SCHEMA_HASH = RELEASE_CONSTANTS.RULES_CONFIG_SCHEMA_HASH;
+/**
+ * The retired schema id of the 15-word layout before r23's `integrator` field, keccak256("hookr.rules.config"): these
+ * Rules never answer it, so an advisory or tool still pinned to it fails closed against them.
+ */
+export const RETIRED_RULES_CONFIG_SCHEMA_HASH = keccak256(stringToBytes("hookr.rules.config"));
+/**
+ * Words of each form of rules data HookrRules binds (r31): the config alone, the config and its RulesKnobs, and both
+ * with a RecaptureConfig too (16, 22 and 30 words).
+ */
+export const RULES_DATA_WORDS = {
+    config: STRUCT_COMPONENTS.RulesConfig.length,
+    knobs: STRUCT_COMPONENTS.RulesConfig.length + STRUCT_COMPONENTS.RulesKnobs.length,
+    recapture: STRUCT_COMPONENTS.RulesConfig.length +
+        STRUCT_COMPONENTS.RulesKnobs.length +
+        STRUCT_COMPONENTS.RecaptureConfig.length,
+};
+/** The decoded config with its addresses in the lowercase form every SDK comparison uses. */
+function normalized(c) {
+    return { ...c, royaltyTo: c.royaltyTo.toLowerCase(), integrator: c.integrator.toLowerCase() };
+}
+function int(value, bits, label) {
+    assert(Number.isSafeInteger(value) && value >= 0 && value < 2 ** bits, `Invalid ${label}`);
+    return BigInt(value);
+}
+function min(a, b) {
+    return a < b ? a : b;
+}
+/** ABI-encodes a RulesConfig alone: `abi.encode(RulesConfig)`, the rules data of a pool without dynamic fees. */
+export function encodeRulesConfig(c) {
+    return encodeAbiParameters(RULES_TUPLE, [c]);
+}
+/** Decodes a config-only rules data (`abi.encode(RulesConfig)`), refusing any non-canonical encoding. */
+export function decodeRulesConfig(data) {
+    const [c] = decodeAbiParameters(RULES_TUPLE, data);
+    const decoded = normalized(c);
+    assert(encodeRulesConfig(decoded).toLowerCase() === data.toLowerCase(), "Non-canonical rules config");
+    return decoded;
+}
+/** The knobs with every integer normalized: what an ABI decode and a caller's literal compare equal on. */
+function knobsOf(k) {
+    return {
+        minDynamicFeeLiquidity: BigInt(k.minDynamicFeeLiquidity),
+        windowSeconds: Number(k.windowSeconds),
+        resetSeconds: Number(k.resetSeconds),
+        carryBps: Number(k.carryBps),
+        moveTicks: Number(k.moveTicks),
+        snipeCurve: Number(k.snipeCurve),
+    };
+}
+/** Whether `k` sets any knob: a pool whose knobs are all zero binds the config alone. */
+function anyKnob(k) {
+    return (k.minDynamicFeeLiquidity !== 0n ||
+        k.windowSeconds !== 0 ||
+        k.resetSeconds !== 0 ||
+        k.carryBps !== 0 ||
+        k.moveTicks !== 0 ||
+        k.snipeCurve !== 0);
+}
+/**
+ * Refuses knobs HookrRules._checkKnobs refuses at bind for `c` in the given form (`knobs`: abi.encode(RulesConfig,
+ * RulesKnobs); `recapture`: with a RecaptureConfig after them; `config`: the config alone, whose knobs read as zero). A
+ * pool without dynamic fees takes none of the five dynamic fee fields; a dynamic fee pool needs the knobbed form, a
+ * minimum dynamic fee liquidity of 1 to 2^96 - 1 and its tempo in bounds; a curve other than linear needs a decaying
+ * Snipe; and a knobbed pool without arb recapture or dynamic fees must set a knob off its default (the curve).
+ * Returns whether the pool stores knobs (`custom`) and whether its tempo is off the default (`tempo`).
+ */
+export function checkRulesKnobs(c, knobs, form) {
+    const k = knobsOf(knobs);
+    uint(k.minDynamicFeeLiquidity, 96);
+    int(k.windowSeconds, 16, "windowSeconds");
+    int(k.resetSeconds, 16, "resetSeconds");
+    int(k.carryBps, 16, "carryBps");
+    int(k.moveTicks, 24, "moveTicks");
+    int(k.snipeCurve, 8, "snipeCurve");
+    const knobbed = form !== "config";
+    if (!knobbed)
+        assert(!anyKnob(k), "Rules data without knobs carries no knob");
+    let tempo = false;
+    let custom = false;
+    if (c.dynamicFeeSens === 0) {
+        assert(k.minDynamicFeeLiquidity === 0n &&
+            k.windowSeconds === 0 &&
+            k.resetSeconds === 0 &&
+            k.carryBps === 0 &&
+            k.moveTicks === 0, "A pool without dynamic fees takes no dynamic fee knob");
+    }
+    else {
+        const b = RULES_KNOB_BOUNDS;
+        assert(knobbed, "A dynamic fee pool binds its RulesKnobs (abi.encode(RulesConfig, RulesKnobs))");
+        assert(k.minDynamicFeeLiquidity > 0n, "A dynamic fee pool needs a minimum dynamic fee liquidity in [1, 2^96 - 1]");
+        assert(k.windowSeconds >= b.minWindowSeconds && k.windowSeconds <= b.maxWindowSeconds, `windowSeconds ${k.windowSeconds} outside [${b.minWindowSeconds}, ${b.maxWindowSeconds}]`);
+        assert(k.resetSeconds >= 2 * k.windowSeconds &&
+            k.resetSeconds >= b.minResetSeconds &&
+            k.resetSeconds <= b.maxResetSeconds &&
+            k.resetSeconds % b.resetStepSeconds === 0, `resetSeconds ${k.resetSeconds} outside [max(2 x window, ${b.minResetSeconds}), ${b.maxResetSeconds}] in steps of ${b.resetStepSeconds}`);
+        assert(k.carryBps <= b.maxCarryBps && k.carryBps % b.carryStepBps === 0, `carryBps ${k.carryBps} above ${b.maxCarryBps} or off its ${b.carryStepBps} step`);
+        assert(k.moveTicks >= b.minMoveTicks && k.moveTicks <= b.maxMoveTicks, `moveTicks ${k.moveTicks} outside [${b.minMoveTicks}, ${b.maxMoveTicks}]`);
+        const d = DYNAMIC_FEE_PARAMETERS;
+        tempo =
+            k.windowSeconds !== d.window ||
+                k.resetSeconds !== d.reset ||
+                k.carryBps !== d.carryBps ||
+                k.moveTicks !== d.moveTicks;
+        custom = tempo;
+    }
+    assert(k.snipeCurve <= SNIPE_CURVE.step, `Unknown Snipe curve ${k.snipeCurve}`);
+    assert(k.snipeCurve === 0 || c.snipeDecaySeconds !== 0, "A Snipe curve other than linear needs a decaying Snipe");
+    if (k.snipeCurve !== 0)
+        custom = true;
+    assert(!(form === "knobs" && !custom && c.dynamicFeeSens === 0), "Knobs at their defaults on a pool without dynamic fees or arb recapture bind as the config alone");
+    return { custom, tempo };
+}
+/**
+ * The canonical rules data HookrRules.bind takes for `c` (r31, three forms told apart by length): `abi.encode(RulesConfig)`
+ * for a pool without dynamic fees, arb recapture or a knob off its default; `abi.encode(RulesConfig, RulesKnobs)` for
+ * every other pool without arb recapture; `abi.encode(RulesConfig, RulesKnobs, RecaptureConfig)` for a recapture pool
+ * (`recapture.on`). Refuses knobs bind would refuse (`checkRulesKnobs`); the RecaptureConfig's own bounds are
+ * HookrRecapture's, checked at bind.
+ */
+export function encodeRulesData(c, knobs = NO_RULES_KNOBS, recapture) {
+    const k = knobsOf(knobs);
+    if (recapture?.on) {
+        checkRulesKnobs(c, k, "recapture");
+        return encodeAbiParameters(RECAPTURE_RULES_TUPLE, [c, k, recapture]);
+    }
+    if (c.dynamicFeeSens === 0 && !anyKnob(k))
+        return encodeRulesConfig(c);
+    checkRulesKnobs(c, k, "knobs");
+    return encodeAbiParameters(KNOBS_RULES_TUPLE, [c, k]);
+}
+/**
+ * Decodes `RulesBound.config` in any form HookrRules.bind accepts (16, 22 or, for a recapture pool, 30 words) and
+ * refuses what bind refuses of its shape: a non-canonical encoding, knobs its config cannot take (`checkRulesKnobs`)
+ * and recapture data with recapture off. `knobs` is NO_RULES_KNOBS for the config-only form; `minLiquidity` is the
+ * knobs' minimum dynamic fee liquidity, zero without dynamic fees.
+ */
+export function decodeRulesData(data) {
+    const words = (data.length - 2) / 64;
+    if (words === RULES_DATA_WORDS.config)
+        return { config: decodeRulesConfig(data), knobs: { ...NO_RULES_KNOBS }, minLiquidity: 0n };
+    if (words === RULES_DATA_WORDS.recapture) {
+        const [c, k, rc] = decodeAbiParameters(RECAPTURE_RULES_TUPLE, data);
+        const config = normalized(c);
+        const knobs = knobsOf(k);
+        const recapture = { ...rc };
+        assert(encodeAbiParameters(RECAPTURE_RULES_TUPLE, [config, knobs, recapture]).toLowerCase() === data.toLowerCase(), "Non-canonical recapture rules data");
+        assert(recapture.on, "Recapture rules data with recapture off");
+        checkRulesKnobs(config, knobs, "recapture");
+        return { config, knobs, minLiquidity: knobs.minDynamicFeeLiquidity, recapture };
+    }
+    assert(words === RULES_DATA_WORDS.knobs, "Rules data is none of the forms HookrRules binds");
+    const [c, k] = decodeAbiParameters(KNOBS_RULES_TUPLE, data);
+    const config = normalized(c);
+    const knobs = knobsOf(k);
+    assert(encodeAbiParameters(KNOBS_RULES_TUPLE, [config, knobs]).toLowerCase() === data.toLowerCase(), "Non-canonical rules data");
+    checkRulesKnobs(config, knobs, "knobs");
+    return { config, knobs, minLiquidity: knobs.minDynamicFeeLiquidity };
+}
+/**
+ * HookrLauncher's minimum dynamic fee liquidity for a member launched with `liquidity`: liquidity / divisor, in
+ * [1, 2^96 - 1]. `divisor` is launchFamily's MemberKnobs.dynamicFeeLiquidityDivisor; zero (and every other launch) is
+ * DYNAMIC_FEE_LIQUIDITY_DIVISOR.
+ */
+export function dynamicFeeMinLiquidity(liquidity, divisor = 0) {
+    int(divisor, 16, "dynamicFeeLiquidityDivisor");
+    const minimum = liquidity / (divisor === 0 ? DYNAMIC_FEE_LIQUIDITY_DIVISOR : BigInt(divisor));
+    if (minimum === 0n)
+        return 1n;
+    return minimum > MAX_MIN_LIQUIDITY ? MAX_MIN_LIQUIDITY : minimum;
+}
+/**
+ * The rules data HookrLauncher binds for a member with `rules` and launch `liquidity` (HookrLauncher._rulesData, r31):
+ * launchFamily's MemberKnobs pass the member's Rules knobs as given (`knobs`; every other launch passes none); a
+ * dynamic fee member's minimum is its liquidity over the divisor, and its tempo the default when all four tempo knobs
+ * are zero. A recapture member (`recapture.on`) binds the 30-word form, a member with every knob zero the config alone,
+ * any other the 22-word form. Like the Launcher it does not check the knobs; HookrRules refuses bad ones at bind
+ * (`checkRulesKnobs`).
+ */
+export function launcherRulesData(c, liquidity, opts = {}) {
+    const m = opts.knobs ?? {};
+    const k = {
+        minDynamicFeeLiquidity: 0n,
+        windowSeconds: m.windowSeconds ?? 0,
+        resetSeconds: m.resetSeconds ?? 0,
+        carryBps: m.carryBps ?? 0,
+        moveTicks: m.moveTicks ?? 0,
+        snipeCurve: m.snipeCurve ?? 0,
+    };
+    if (c.dynamicFeeSens !== 0) {
+        k.minDynamicFeeLiquidity = dynamicFeeMinLiquidity(liquidity, m.dynamicFeeLiquidityDivisor ?? 0);
+        if (k.windowSeconds === 0 && k.resetSeconds === 0 && k.carryBps === 0 && k.moveTicks === 0) {
+            k.windowSeconds = DYNAMIC_FEE_PARAMETERS.window;
+            k.resetSeconds = DYNAMIC_FEE_PARAMETERS.reset;
+            k.carryBps = DYNAMIC_FEE_PARAMETERS.carryBps;
+            k.moveTicks = DYNAMIC_FEE_PARAMETERS.moveTicks;
+        }
+    }
+    if (opts.recapture?.on)
+        return encodeAbiParameters(RECAPTURE_RULES_TUPLE, [c, k, opts.recapture]);
+    if (!anyKnob(k))
+        return encodeRulesConfig(c);
+    return encodeAbiParameters(KNOBS_RULES_TUPLE, [c, k]);
+}
+/**
+ * The longest snipeDecaySeconds a pool binds with at `blockNumber` (HookrRules._validate, r31): MAX_SNIPE_DECAY_SECONDS,
+ * or the guard's length in seconds when that is longer, (guardEndBlock - blockNumber) x PARENT_BLOCK_SECONDS, at most
+ * 65,535. Without a block number only MAX_SNIPE_DECAY_SECONDS is certain.
+ */
+export function maxSnipeDecaySeconds(guardEndBlock, blockNumber) {
+    const guard = BigInt(guardEndBlock);
+    if (blockNumber === undefined || guard <= blockNumber)
+        return MAX_SNIPE_DECAY_SECONDS;
+    const length = (guard - blockNumber) * BigInt(PARENT_BLOCK_SECONDS);
+    const longest = length > 65535n ? 65535n : length;
+    return Number(longest) > MAX_SNIPE_DECAY_SECONDS ? Number(longest) : MAX_SNIPE_DECAY_SECONDS;
+}
+/** Whether a dynamic fee of `spanPips` (maxFeePips less the base fee) at `sens` and `shareBps` binds (HookrDynamicFee.withinReach). */
+export function withinDynamicFeeReach(spanPips, sens, shareBps) {
+    const span = BigInt(spanPips);
+    const sens2 = BigInt(sens) * BigInt(sens);
+    const r = DYNAMIC_FEE_REACH;
+    return (span * sens2 <= r.maxReach && span * BigInt(shareBps) * (r.reserveScale - sens2) <= r.maxReserve * r.reserveScale);
+}
+/**
+ * The Anti-Snipe tax, in pips before clipping, of a guarded buy at `timestamp` in a pool bound at `launchedAt`
+ * (HookrRules._snipePips and _knobbedSnipe, r31): snipeTaxPips flat without a decay, otherwise falling from snipeTaxPips
+ * at launch to snipeFloorPips at snipeDecaySeconds along the pool's Snipe curve, every division rounded down. With
+ * d = snipeDecaySeconds, e the launch age, x = snipeTaxPips - snipeFloorPips and n = 8e / d: linear (the default),
+ * floor + x(d - e)/d; step, floor + x(8 - n)/8; front-loaded, what is left halves every eighth of the decay in a
+ * straight line between the halvings (the last eighth falls the rest of the way). The launch age is taken modulo 2^32
+ * and a clock behind the launch reads as the launch. The guard itself is counted in blocks (guardEndBlock).
+ */
+export function snipeTaxAt(c, launchedAt, timestamp, curve = SNIPE_CURVE.linear) {
+    int(curve, 8, "snipeCurve");
+    assert(curve <= SNIPE_CURVE.step, `Unknown Snipe curve ${curve}`);
+    const start = BigInt(c.snipeTaxPips);
+    const duration = BigInt(c.snipeDecaySeconds);
+    if (duration === 0n)
+        return Number(start);
+    let elapsed = (BigInt(timestamp) - BigInt(launchedAt)) & 0xffffffffn;
+    if (elapsed > 0xffffffffn >> 1n)
+        elapsed = 0n;
+    const floor = BigInt(c.snipeFloorPips);
+    if (elapsed >= duration)
+        return Number(floor);
+    if (curve === SNIPE_CURVE.linear)
+        return Number(floor + ((start - floor) * (duration - elapsed)) / duration);
+    const n = (elapsed * 8n) / duration;
+    if (curve === SNIPE_CURVE.step)
+        return Number(floor + ((start - floor) * (8n - n)) / 8n);
+    const h = (start - floor) >> n;
+    const l = n === 7n ? 0n : h >> 1n;
+    return Number(floor + l + ((h - l) * (duration - (elapsed * 8n - n * duration))) / duration);
+}
+/**
+ * The guarded per-parent-block buy cap at Anti-Snipe tax `snipePips` (HookrRules.settleSwap): maxBuyQuoteAmount
+ * without a decay; with one, maxBuyQuoteAmount * snipeTaxPips / snipePips, so a block that fills the cap pays the
+ * same tax at every point of the decay. `null` when there is no cap: a zero maxBuyQuoteAmount, or a zero tax.
+ */
+export function guardBuyLimit(c, snipePips) {
+    if (c.maxBuyQuoteAmount === 0n)
+        return null;
+    if (c.snipeDecaySeconds === 0)
+        return c.maxBuyQuoteAmount;
+    if (snipePips === 0)
+        return null;
+    return (c.maxBuyQuoteAmount * BigInt(c.snipeTaxPips)) / BigInt(snipePips);
+}
+/**
+ * HookrDynamicFee.averageRate: the average of min(1, (d / knee)^2), knee = 1 / (2 * sens), over the distances [a, b]
+ * from the reference, as a fraction of the dynamic fee span in WAD. Distances are in WAD; requires b > a.
+ */
+export function dynamicFeeAverageRate(a, b, sens) {
+    assert(b > a && a >= 0n && Number.isInteger(sens) && sens >= 1 && sens <= 10, "Invalid dynamic fee interval");
+    const s = BigInt(sens);
+    const knee = WAD / (2n * s);
+    if (a >= knee)
+        return WAD;
+    if (b <= knee)
+        return (4n * s * s * (a * a + a * b + b * b)) / (3n * WAD);
+    const area = (knee - (a * a * a) / (knee * knee)) / 3n + (b - knee);
+    const ratio = (area * WAD) / (b - a);
+    return ratio > WAD ? WAD : ratio;
+}
+/**
+ * HookrDynamicFee.distance: the signed distance of `sqrtPriceX96` from the reference `sqrtRefX96` in the direction of
+ * a swap, in WAD: sqrt(ref) / sqrt(p) - 1 for zeroForOne, sqrt(p) / sqrt(ref) - 1 otherwise.
+ */
+export function dynamicFeeDistance(sqrtRefX96, sqrtPriceX96, zeroForOne) {
+    return (zeroForOne ? (sqrtRefX96 * WAD) / sqrtPriceX96 : (sqrtPriceX96 * WAD) / sqrtRefX96) - WAD;
+}
+/** Dynamic fee pips before clipping for a move over the distances [a, b]: the span times the average rate. */
+export function dynamicFeePips(c, baseLpFeePips, a, b) {
+    if (c.dynamicFeeSens === 0 || b <= a)
+        return 0;
+    const span = BigInt(c.maxFeePips) - BigInt(baseLpFeePips);
+    return Number((span * dynamicFeeAverageRate(a, b, c.dynamicFeeSens)) / WAD);
+}
+/**
+ * The protocol's share of a `bps` slice of a buy, in pips of the gross buyer spend, rounded up
+ * (HookrRules._protocolPips): ceil(bps x 100 x shareBps / 10,000). Exact whenever shareBps is a whole percent.
+ */
+export function protocolSharePips(bps, shareBps) {
+    return (BigInt(bps) * BigInt(shareBps) + 99n) / 100n;
+}
+/**
+ * LP Rewards net of the protocol share, before the royalty, in pips: lpBps x 100 less its protocol share in pips,
+ * rounded up (HookrRules._buyParts, HookrFeeAdvisory._nativeCeiling, HookrSessionAdvisory._rulesCeiling).
+ */
+function lpNetPips(c) {
+    return BigInt(c.lpBps) * 100n - protocolSharePips(c.lpBps, c.protocolShareBps);
+}
+/**
+ * LP Rewards, quote take, net subject burn and the royalty's part of the take of a buy (HookrRules._buyParts). The
+ * protocol's share of LP Rewards and of Auto Burn is taken in pips, rounded up; the burn left after it is whole basis
+ * points, rounded down.
+ */
+function buyParts(c) {
+    const lpSlice = protocolSharePips(c.lpBps, c.protocolShareBps);
+    const lpNet = BigInt(c.lpBps) * 100n - lpSlice;
+    const royaltyPips = (lpNet * BigInt(c.royaltyBps)) / BPS;
+    const burnSlice = protocolSharePips(c.burnBps, c.protocolShareBps);
+    return {
+        lpReward: lpNet - royaltyPips,
+        take: lpSlice + royaltyPips + burnSlice,
+        burnBps: (BigInt(c.burnBps) * 100n - burnSlice) / 100n,
+        royaltyPips,
+    };
+}
+/**
+ * The royalty's part of a buy's quote take, in pips of the gross buyer spend (HookrRules._buyParts): LP Rewards net of
+ * the protocol share, times royaltyBps, rounded down. It is the creator's, not Hookr's: the Hookr minimum compares
+ * Hookr's rule-fee share alone with the minimum and adds the royalty on top. Sells pay no royalty.
+ */
+export function royaltyPips(c) {
+    return Number((lpNetPips(c) * BigInt(c.royaltyBps)) / BPS);
+}
+/**
+ * LP Rewards of a buy, in pips of the pool input: lpBps x 100 less the protocol share (in pips, rounded up), less
+ * the royalty (HookrRules._buyParts). A pool binds only when base + this is at most 600,000 pips.
+ */
+export function lpRewardPips(c) {
+    return Number(buyParts({ ...c, burnBps: 0 }).lpReward);
+}
+/**
+ * The smallest caps HookrRules accepts for `c` at base fee `baseLpFeePips` on a pool that freezes the Hookr minimum
+ * `minFeePips` (zero for a pool without one, `bindMinFeePips`): the worst-case total LP fee, quote take and subject
+ * burn over every swap (HookrRules._validate). The quote take is at least royalty + minimum, so a Hookr token's pool
+ * whose caps do not admit its minimum does not bind. These are the caps the Rules sees, after the Root has reserved the
+ * advisory's admitted maximum.
+ */
+export function rulesFeeCeilings(c, baseLpFeePips, minFeePips = 0) {
+    const base = int(baseLpFeePips, 24, "base fee");
+    const minimum = BigInt(minFee(minFeePips));
+    assert(BigInt(c.maxFeePips) >= base && c.maxFeePips <= MAX_LP_FEE_PIPS, "maxFeePips outside [base, 600000]");
+    const { lpReward, take, burnBps, royaltyPips } = buyParts(c);
+    assert(base + lpReward <= MAX_LP, "Base fee plus LP Rewards above 600000 pips");
+    const share = BigInt(c.protocolShareBps);
+    const span = BigInt(c.maxFeePips) - base;
+    const snipeTax = BigInt(c.snipeTaxPips);
+    const room = MAX_LP - base - lpReward;
+    const dynamicFee = min(span, room);
+    const snipe = min(snipeTax, room - dynamicFee);
+    let slice = (dynamicFee * share) / BPS + (snipe * share) / BPS;
+    let maximumLp = base + lpReward + dynamicFee + snipe - slice;
+    if (span + snipeTax > room && share !== 0n) {
+        // A clipped dynamic fee and Snipe round their shares separately: allow one pip less protocol share.
+        slice = ((dynamicFee + snipe) * share) / BPS;
+        maximumLp = base + lpReward + dynamicFee + snipe - (slice === 0n ? 0n : slice - 1n);
+    }
+    if (maximumLp < BigInt(c.maxFeePips))
+        maximumLp = BigInt(c.maxFeePips);
+    let maximumQuote = slice + take;
+    if ((span * share) / BPS > maximumQuote)
+        maximumQuote = (span * share) / BPS;
+    // The Hookr minimum replaces a smaller rule share (r25): a buy takes at most royalty + max(rule share, minimum), a
+    // sell max(dynamic fee share, minimum), so the bound is the larger of the rules' own and royalty + minimum.
+    if (royaltyPips + minimum > maximumQuote)
+        maximumQuote = royaltyPips + minimum;
+    return {
+        maxLpFeePips: Number(maximumLp),
+        maxQuoteTakePips: Number(maximumQuote),
+        maxSubjectTakeBps: Number(burnBps),
+    };
+}
+/**
+ * Largest native LP fee (base + Rules surcharge) HookrRules can quote with Anti-Snipe at `snipeTax`
+ * (HookrFeeAdvisory._nativeCeiling). The fee advisory's room on a HookrRoot pool is the pool's LP cap minus this.
+ */
+export function nativeLpCeiling(c, baseLpFeePips, snipeTax = 0) {
+    const base = BigInt(baseLpFeePips);
+    const share = BigInt(c.protocolShareBps);
+    const lpNet = lpNetPips(c);
+    const lpReward = lpNet - (lpNet * BigInt(c.royaltyBps)) / BPS;
+    if (base + lpReward >= MAX_LP)
+        return MAX_LP_FEE_PIPS;
+    const room = MAX_LP - base - lpReward;
+    const span = BigInt(c.maxFeePips) - base;
+    const dynamicFee = min(span, room);
+    const snipe = min(BigInt(snipeTax), room - dynamicFee);
+    let slice = (dynamicFee * share) / BPS + (snipe * share) / BPS;
+    if (span + BigInt(snipeTax) > room && share !== 0n) {
+        slice = ((dynamicFee + snipe) * share) / BPS;
+        if (slice !== 0n)
+            slice -= 1n;
+    }
+    const ceiling = base + lpReward + dynamicFee + snipe - slice;
+    return Number(ceiling < BigInt(c.maxFeePips) ? BigInt(c.maxFeePips) : ceiling);
+}
+function bps(value, max, label) {
+    assert(Number.isSafeInteger(value) && value >= 0 && value <= max, `${label} ${value} outside [0, ${max}]`);
+    return value;
+}
+/** A Hookr minimum a pool can freeze: 0 to 10,000 pips (HookrRules refuses a larger one at bind, InvalidConfig). */
+function minFee(pips) {
+    return bps(pips, RULES_MAX_MIN_FEE_PIPS, "minFeePips");
+}
+/** Whether a runtime codehash is HookrToken's (`HOOKR_TOKEN_RUNTIME_KECCAK256`), the test HookrRules applies at bind. */
+export function isHookrTokenRuntime(codeHash) {
+    return codeHash.toLowerCase() === HOOKR_TOKEN_RUNTIME_KECCAK256.toLowerCase();
+}
+/**
+ * HookrRules._earnsHookr (r31): whether a rule can pay Hookr at least a pip of some swap at the pool's
+ * protocolShareBps. Nothing does at a zero share; LP Rewards and Auto Burn do at any nonzero share (the Rules round
+ * their protocol slices up); the dynamic fee does when its whole span (maxFeePips less the base fee) times the share is
+ * at least 10,000, and the Anti-Snipe tax when snipeTaxPips times the share is (the Rules round both shares down).
+ */
+export function earnsHookr(rules, baseLpFeePips) {
+    const share = BigInt(rules.protocolShareBps);
+    if (share === 0n)
+        return false;
+    if (rules.lpBps !== 0 || rules.burnBps !== 0)
+        return true;
+    const base = BigInt(baseLpFeePips);
+    const span = BigInt(rules.maxFeePips) > base ? BigInt(rules.maxFeePips) - base : 0n;
+    return span * share >= BPS || BigInt(rules.snipeTaxPips) * share >= BPS;
+}
+/**
+ * The Hookr minimum a pool freezes at bind (HookrRules.bind, r31): the treasury's `feeTerms(integrator, false, id)`
+ * minimum (`decodeFeeTerms`) only on a Hookr token's pool that binds no arb recapture, whose rules earn Hookr no share
+ * (`earnsHookr`) and whose advisory is not Tax + Conversion at a nonzero share; zero on every other pool. Whatever
+ * pays Hookr a share replaces the minimum, never adds to it. `subject` is `"new"` for a launch that creates its token
+ * (HookrLauncher deploys a HookrToken, so it always is one) or the existing subject's runtime codehash (`eth_getCode`,
+ * then keccak256; a Hookr token exactly when it equals HOOKR_TOKEN_RUNTIME_KECCAK256). A treasury answer above 10,000
+ * pips is refused whatever follows, as the Rules refuse it. A Rules paying an address without code reads no terms and
+ * binds no minimum: pass 0 as `treasuryMinFeePips` for it.
+ */
+export function bindMinFeePips(subject, treasuryMinFeePips, terms) {
+    minFee(treasuryMinFeePips);
+    if (subject !== "new" && !isHookrTokenRuntime(subject))
+        return 0;
+    int(terms.baseLpFeePips, 24, "base fee");
+    if (terms.recapture || earnsHookr(terms.rules, terms.baseLpFeePips))
+        return 0;
+    const tax = terms.taxConversion;
+    if (tax && terms.rules.protocolShareBps !== 0 && tax.maxQuoteTakePips !== 0)
+        return 0;
+    return treasuryMinFeePips;
+}
+/**
+ * The minimum HookrTreasury.feeTerms answers for a pool (r25): the integrator's override when it has one
+ * (`overridePips` other than NO_MIN_FEE_OVERRIDE) and approved the pool's id, else the rate for its kind of pool (with
+ * arb recapture on, `recapturePips`; without, `plainPips`). An override never reaches a pool its integrator did not
+ * approve, so naming the integrator alone does not bind it. Offline mirror; read `feeTerms` on chain before signing.
+ */
+export function treasuryMinFeePips(t) {
+    const rate = minFee(t.recapture ? t.recapturePips : t.plainPips);
+    const override = t.overridePips ?? NO_MIN_FEE_OVERRIDE;
+    if (override === NO_MIN_FEE_OVERRIDE || !t.approved)
+        return rate;
+    return minFee(override);
+}
+/**
+ * The effective protocolShareBps floor HookrRules binds a pool at (HookrRules._feeTerms): the larger of its immutable
+ * minProtocolShareBps and the treasury's governed floor, both 0 to 5,000.
+ */
+export function effectiveShareFloor(minProtocolShareBps, ruleShareFloorBps = 0) {
+    return Math.max(bps(minProtocolShareBps, MAX_PROTOCOL_SHARE_BPS, "minProtocolShareBps"), bps(ruleShareFloorBps, MAX_RULE_SHARE_FLOOR_BPS, "ruleShareFloorBps"));
+}
+/**
+ * The rate a pool naming `integrator` freezes, from the treasury's list as read (`RulesContext.integrators`): zero for
+ * no integrator; refused when the integrator is not listed at 1 to 5,000. Undefined when the list was not given.
+ */
+export function listedIntegratorBps(integrator, integrators) {
+    const account = address(integrator, true);
+    if (account === ZERO)
+        return 0;
+    if (integrators === undefined)
+        return undefined;
+    const rate = integrators[account] ?? 0;
+    assert(Number.isSafeInteger(rate) && rate >= 1 && rate <= MAX_INTEGRATOR_BPS, `Integrator ${account} is not on the treasury's integrator list (HookrRules UnknownIntegrator)`);
+    return rate;
+}
+/**
+ * Splits Hookr's share of one swap's rule fees (the Snipe, dynamic fee, LP Rewards and Auto Burn, royalty already
+ * out) on a pool with an integrator frozen at `integratorBps` (HookrRules.settleSwap): the integrator gets
+ * share x rate / 10,000 rounded down as a Rules claim (`IntegratorPaid`), the protocol recipient the rest, the odd
+ * unit included (`FeesAllocated.protocol`). A pool without an integrator (rate 0) pays the protocol all of it.
+ */
+export function splitProtocolShare(share, integratorBps) {
+    uint(share);
+    const cut = (share * BigInt(bps(integratorBps, MAX_INTEGRATOR_BPS, "integratorBps"))) / BPS;
+    return { protocol: share - cut, integrator: cut };
+}
+/**
+ * A swap's HookrRules quote (HookrRules._quote, r25) on a pool bound with `c` at `baseLpFeePips` that froze the Hookr
+ * minimum `minFeePips`. `dynamicFeePips` is the dynamic fee before clipping (zero without one) and `snipePips` the
+ * Anti-Snipe tax (`snipeTaxAt`, only on a buy while the guard lasts). The dynamic fee is clipped to the room base and
+ * LP Rewards leave under 600,000 pips, the Snipe to what remains. Hookr's rule-fee share is its part of LP Rewards and
+ * Auto Burn (buys) and of the dynamic fee and the Snipe; the royalty is the creator's. The minimum is a top-up to the
+ * quote take only: `quoteTakePips` = royalty + max(ruleSharePips, minFeePips) and the LP fee surcharge is unchanged, so
+ * a pool without rules takes exactly the minimum and a pool whose rules give Hookr at least the minimum pays nothing
+ * more. Sells pay no LP Rewards, Auto Burn, royalty or Snipe, so a sell's share is its dynamic fee share alone. Since
+ * r31 only a pool whose rules earn Hookr nothing binds a minimum (`bindMinFeePips`), so there the top-up is the whole
+ * minimum, and no arb recapture pool binds one.
+ */
+export function rulesQuote(c, s) {
+    const base = int(s.baseLpFeePips, 24, "base fee");
+    const minimum = BigInt(minFee(s.minFeePips ?? 0));
+    let lpReward = 0n;
+    let take = 0n;
+    let burnBps = 0n;
+    let royalty = 0n;
+    if (s.isBuy)
+        ({ lpReward, take, burnBps, royaltyPips: royalty } = buyParts(c));
+    assert(base + lpReward <= MAX_LP, "Base fee plus LP Rewards above 600000 pips");
+    const room = MAX_LP - base - lpReward;
+    let dynamicFee = BigInt(int(s.dynamicFeePips ?? 0, 24, "dynamic fee"));
+    let snipe = s.isBuy ? BigInt(int(s.snipePips ?? 0, 24, "Snipe")) : 0n;
+    if (dynamicFee > room)
+        dynamicFee = room;
+    if (snipe > room - dynamicFee)
+        snipe = room - dynamicFee;
+    const share = BigInt(c.protocolShareBps);
+    const protocolPips = (dynamicFee * share) / BPS + (snipe * share) / BPS;
+    take += protocolPips;
+    const ruleShare = take - royalty;
+    const topUp = ruleShare < minimum ? minimum - ruleShare : 0n;
+    return {
+        lpFeeSurchargePips: Number(lpReward + dynamicFee + snipe - protocolPips),
+        quoteTakePips: Number(take + topUp),
+        subjectBurnBps: Number(burnBps),
+        royaltyPips: Number(royalty),
+        ruleSharePips: Number(ruleShare),
+        topUpPips: Number(topUp),
+    };
+}
+/**
+ * The quote HookrRules.simulationQuote gives the root for its simulated swap on a dynamic fee pool (r26): the swap's
+ * quote (`rulesQuote`) without a dynamic fee, and on an exact-output sell a quote take of the larger of the largest
+ * dynamic fee share the sell can pay (the span, clipped to 600,000 pips less the base fee, times protocolShareBps) and
+ * that quote's take, which on a sell is the pool's Hookr minimum (zero without one). The real take of such a sell is
+ * max(its dynamic fee share, the minimum), so the simulation reaches at least as far as the real swap and no further
+ * than that bound; before r26 it reserved their sum and simulated a longer move. Every other shape is quoted without
+ * the dynamic fee.
+ */
+export function simulationQuote(c, s) {
+    const q = rulesQuote(c, {
+        baseLpFeePips: s.baseLpFeePips,
+        isBuy: s.isBuy,
+        snipePips: s.snipePips,
+        minFeePips: s.minFeePips,
+    });
+    if (s.isBuy || s.exactInput)
+        return q;
+    const base = BigInt(s.baseLpFeePips);
+    const span = BigInt(c.maxFeePips) - base;
+    const room = MAX_LP - base;
+    const largest = ((span > room ? room : span) * BigInt(c.protocolShareBps)) / BPS;
+    if (largest <= BigInt(q.quoteTakePips))
+        return q;
+    return { ...q, quoteTakePips: Number(largest) };
+}
+/**
+ * What one swap without an advisory pays the Rules, in the pool's quote (HookrRoot's settlement, then
+ * HookrRules.settleSwap): `rulesFee`, the royalty inside it (buys: quoteBasis x royalty pips / 1e6, at most the fee),
+ * Hookr's part (`hookr`, the rest: its rule-fee share with the minimum's top-up) and Hookr's part split with the
+ * pool's integrator (`splitProtocolShare`: the integrator's frozen rate rounded down, the protocol recipient the rest).
+ * `actualQuote` is the quote the pool swap took in (buys) or paid out (sells), `requested` the swap's specified
+ * amount. Buys are priced on the gross buyer spend, quoteBasis = actualQuote x 1e6 / (1e6 - take) (at most the
+ * specified input of an exact-input buy); an exact-input sell on the quote out; an exact-output sell reserves
+ * ceil(requested x take / (1e6 - take)) on top of the requested output, all of it the Rules' fee without an advisory.
+ */
+export function rulesSwapFees(s) {
+    const rate = BigInt(int(s.quoteTakePips, 24, "quote take"));
+    assert(rate < PIPS, "Quote take at or above 1000000 pips");
+    const actual = uint(s.actualQuote);
+    const requested = uint(s.requested);
+    let quoteBasis;
+    let rulesFee;
+    let royalty = 0n;
+    if (s.shape === "exactInputBuy" || s.shape === "exactOutputBuy") {
+        quoteBasis = (actual * PIPS) / (PIPS - rate);
+        if (s.shape === "exactInputBuy" && quoteBasis > requested)
+            quoteBasis = requested;
+        rulesFee = (quoteBasis * rate) / PIPS;
+        royalty = (quoteBasis * BigInt(int(s.royaltyPips, 24, "royalty"))) / PIPS;
+        if (royalty > rulesFee)
+            royalty = rulesFee;
+    }
+    else if (s.shape === "exactInputSell") {
+        quoteBasis = actual;
+        rulesFee = (quoteBasis * rate) / PIPS;
+    }
+    else {
+        quoteBasis = actual;
+        rulesFee = rate === 0n ? 0n : (requested * rate + (PIPS - rate) - 1n) / (PIPS - rate);
+    }
+    const hookr = rulesFee - royalty;
+    const split = splitProtocolShare(hookr, s.integratorBps ?? 0);
+    return { quoteBasis, rulesFee, royalty, hookr, ...split };
+}
+/**
+ * The profit one currency's push stands for (HookrLane._run, r28): the root reads it back from the push at the pool's
+ * frozen partner share, pushed x 10,000 / (10,000 - partnerBps) rounded down, and emits it as CorrectionSucceeded's
+ * `reportedProfit`. What the executor's call returns is not read. An executor that keeps floor(P x partnerBps /
+ * 10,000) of a profit P and pushes the rest is read back as P or P + 1.
+ */
+export function recaptureProfit(pushed, partnerBps) {
+    return (uint(pushed) * BPS) / (BPS - BigInt(bps(partnerBps, MAX_LANE_PARTNER_BPS, "partnerBps")));
+}
+/**
+ * One arb recapture's split of `amount` pushed in `currency` (HookrRecapture.settleRecapture): the protocol takes
+ * RECAPTURE_PROTOCOL_BPS (25% since r31) of the profit the push stands for (`reportedProfit`: the root's read-back,
+ * recaptureProfit(amount, partnerBps)), at most the push, on every pool alike and never split with an integrator; on
+ * a push in the pool's quote (`inQuote`) the King of the Pool pot takes potBps of the rest and the trader named on the
+ * after-phase traderBps of the rest's part its own move accounts for (min(amount, traderBasis) x rest / amount); the
+ * LPs take what is left, rounding dust included. A push in any other currency pays no trader or pot; a frame that
+ * pushed in several currencies splits each on its own. With WTH keeping 2,500 bps and the default traderBps of 2,500,
+ * a profit P splits 25% to the partner, 25% to the protocol, 12.5% to the trader and 37.5% to the LPs.
+ */
+export function recaptureSplit(p) {
+    assert(uint(p.amount) > 0n, "An arb recapture settles a nonzero push (HookrRecapture InvalidSettlement)");
+    const cut = (uint(p.reportedProfit) * BigInt(RECAPTURE_PROTOCOL_BPS)) / BPS;
+    const protocol = cut < p.amount ? cut : p.amount;
+    const rest = p.amount - protocol;
+    let trader = 0n;
+    let pot = 0n;
+    if (p.inQuote) {
+        if (address(p.trader, true) !== ZERO && uint(p.traderBasis) !== 0n) {
+            const part = p.traderBasis < p.amount ? p.traderBasis : p.amount;
+            trader = (((part * rest) / p.amount) * BigInt(bps(p.traderBps, 5_000, "traderBps"))) / BPS;
+        }
+        pot = (rest * BigInt(bps(p.potBps, 5_000, "potBps"))) / BPS;
+    }
+    return { protocol, trader, pot, lp: rest - trader - pot };
+}
+/**
+ * The largest King of the Pool maxPrizeBps a recapture pool binds with (HookrRecapture._validate): half of what the
+ * protocol keeps of LP Rewards and Auto Burn in basis points of a buy, each rounded down, where the kept share is
+ * protocolShareBps x (10,000 - integratorBps) / 10,000 rounded down. It is HookrRecapture.prizeBoundFor(lpBps, burnBps,
+ * protocolShareBps, integratorBps) (r26), read on chain with `encodePrizeBoundForCall`; for a pool naming an integrator,
+ * take the rate from `integration(id)` or `feeTerms`, never `prizeBound` on the pool's whole share.
+ */
+export function kingOfTheHillPrizeBound(lpBps, burnBps, protocolShareBps, integratorBps = 0) {
+    const kept = (BigInt(bps(protocolShareBps, MAX_PROTOCOL_SHARE_BPS, "protocolShareBps")) *
+        (BPS - BigInt(bps(integratorBps, MAX_INTEGRATOR_BPS, "integratorBps")))) /
+        BPS;
+    return (((BigInt(lpBps) * kept) / BPS + (BigInt(burnBps) * kept) / BPS) * BigInt(PRIZE_SHARE_OF_FEE_BPS)) / BPS;
+}
+/**
+ * Refuses a RulesConfig that HookrRules.bind would refuse, and returns its fee ceilings (`rulesFeeCeilings`).
+ * Mirrors HookrRules._validate, including the effective protocol share floor (`effectiveShareFloor`), the integrator
+ * list when the context carries it (`listedIntegratorBps`), the Anti-Snipe decay bounds and, on a pool that freezes the
+ * Hookr minimum (`RulesContext.minFeePips`), caps that admit royalty + minimum. A dynamic fee pool binds at any tick
+ * spacing. An integrator changes no fee ceiling: it is paid from Hookr's share after the take.
+ */
+export function checkRulesConfig(c, ctx) {
+    int(c.guardEndBlock, 40, "guardEndBlock");
+    for (const [k, bits] of [
+        ["maxFeePips", 24],
+        ["snipeTaxPips", 24],
+        ["snipeFloorPips", 24],
+        ["snipeDecaySeconds", 16],
+        ["dynamicFeeSens", 16],
+        ["burnBps", 16],
+        ["lpBps", 16],
+        ["potBps", 16],
+        ["royaltyBps", 16],
+        ["protocolShareBps", 16],
+        ["potEveryNBuys", 32],
+    ])
+        int(c[k], bits, k);
+    uint(c.maxBuyQuoteAmount, 128);
+    uint(c.potMinBuyQuote, 128);
+    const royaltyTo = address(c.royaltyTo, true);
+    listedIntegratorBps(c.integrator, ctx.integrators);
+    const integrator = address(c.integrator, true);
+    assert(integrator === ZERO || !(ctx.refusedIntegrators ?? []).some((a) => address(a, true) === integrator), `Integrator ${integrator} is an account of the Rules' own release that never claims (HookrRules UnknownIntegrator)`);
+    assert(c.potBps === 0 && c.potEveryNBuys === 0 && c.potMinBuyQuote === 0n, "Pot unavailable in this release");
+    assert(c.protocolShareBps >= effectiveShareFloor(ctx.minProtocolShareBps, ctx.ruleShareFloorBps), "Protocol share below the Rules minimum (the larger of minProtocolShareBps and the treasury's governed floor)");
+    assert(c.protocolShareBps <= MAX_PROTOCOL_SHARE_BPS, "Protocol share above 5000 bps");
+    assert(c.dynamicFeeSens <= 10, "Dynamic fee sensitivity above 10");
+    assert((c.dynamicFeeSens === 0) === (c.maxFeePips === ctx.baseLpFeePips), "Dynamic fees must be on exactly when maxFeePips is above base");
+    // r31: a decay may run past MAX_SNIPE_DECAY_SECONDS up to the guard's own length at bind (maxSnipeDecaySeconds).
+    assert(c.snipeDecaySeconds <= maxSnipeDecaySeconds(c.guardEndBlock, ctx.blockNumber), "Anti-Snipe decay above the longest the Rules accept: an hour, or the guard's length when it is longer");
+    // r31 (N09): a dynamic fee binds only within HookrDynamicFee's reach bound.
+    assert(withinDynamicFeeReach(c.maxFeePips - ctx.baseLpFeePips, c.dynamicFeeSens, c.protocolShareBps), "Dynamic fee past the reach bound: lower maxFeePips, the sensitivity or the protocol share");
+    assert(c.snipeDecaySeconds === 0 ? c.snipeFloorPips === 0 : c.snipeFloorPips < c.snipeTaxPips, "Anti-Snipe floor must be below the launch tax with a decay, and zero without one");
+    assert(ctx.baseLpFeePips + c.snipeTaxPips <= MAX_LP_FEE_PIPS, "Base fee plus Snipe above 600000 pips");
+    assert(c.burnBps + c.lpBps <= 1_000, "Burn plus LP Rewards above 1000 bps");
+    assert(c.royaltyBps <= 1_000, "Royalty above 1000 bps");
+    assert((c.royaltyBps === 0) === (royaltyTo === ZERO), "Royalty needs exactly one of rate and recipient");
+    assert(royaltyTo === ZERO || !(ctx.refusedRoyaltyRecipients ?? []).some((a) => address(a, true) === royaltyTo), `Royalty recipient ${royaltyTo} is an account of the Rules' own release that never claims (HookrRules InvalidConfig)`);
+    assert(c.royaltyBps === 0 || c.lpBps !== 0, "Royalty needs LP Rewards");
+    if (c.guardEndBlock === 0) {
+        assert(c.snipeTaxPips === 0 && c.maxBuyQuoteAmount === 0n && c.snipeDecaySeconds === 0, "Snipe, its decay and the buy limit need a launch guard");
+    }
+    else {
+        assert(ctx.liquidityOwner !== undefined && address(ctx.liquidityOwner) !== ZERO, "Launch guard needs a liquidity owner");
+        if (ctx.blockNumber !== undefined)
+            assert(BigInt(c.guardEndBlock) > ctx.blockNumber &&
+                BigInt(c.guardEndBlock) <= ctx.blockNumber + BigInt(MAX_GUARD_BLOCKS), "Launch guard outside the next 100000 blocks");
+    }
+    const ceilings = rulesFeeCeilings(c, ctx.baseLpFeePips, ctx.minFeePips ?? 0);
+    if (ctx.caps)
+        assert(ceilings.maxLpFeePips <= ctx.caps.maxLpFeePips &&
+            ceilings.maxQuoteTakePips <= ctx.caps.maxQuoteTakePips &&
+            ceilings.maxSubjectTakeBps <= ctx.caps.maxSubjectTakeBps, "Rules fee ceilings exceed the caps");
+    return ceilings;
+}
+function checkCaps(caps) {
+    int(caps.maxLpFeePips, 24, "maxLpFeePips");
+    int(caps.maxQuoteTakePips, 24, "maxQuoteTakePips");
+    int(caps.maxSubjectTakeBps, 16, "maxSubjectTakeBps");
+    assert(caps.maxLpFeePips <= MAX_LP_FEE_PIPS, "LP cap above 600000 pips");
+    assert(BigInt(caps.maxQuoteTakePips) < PIPS, "Quote take cap at or above 1000000 pips");
+    assert(caps.maxSubjectTakeBps <= 1_000, "Subject cap above 1000 bps");
+}
+/**
+ * The pool caps (PoolConfig.caps) of a pool whose Rules needs `rules` and whose advisory is admitted with
+ * `advisory` caps: the Rules ceilings plus the advisory's admitted maximum, so the Root's reservation leaves the
+ * Rules its full ceilings. Pass the result of `rulesFeeCeilings` (or `checkRulesConfig`) as `rules`.
+ */
+export function poolCapsFor(rules, baseLpFeePips, advisory) {
+    const caps = {
+        maxLpFeePips: rules.maxLpFeePips + (advisory?.maxLpFeePips ?? 0),
+        maxQuoteTakePips: rules.maxQuoteTakePips + (advisory?.maxQuoteTakePips ?? 0),
+        maxSubjectTakeBps: rules.maxSubjectTakeBps,
+    };
+    checkCaps(caps);
+    assert(baseLpFeePips <= caps.maxLpFeePips, "Base fee above the LP cap");
+    return caps;
+}
+/**
+ * The caps HookrRoot.initializePool hands the Rules: min(pool, Rules admission) per field, less the advisory's
+ * admitted maximum. Refuses what the Root refuses: pool caps out of range, or an advisory maximum above the room.
+ */
+export function rulesBindCaps(pool, rulesAdmission, advisoryAdmission) {
+    checkCaps(pool);
+    const limits = {
+        maxLpFeePips: Math.min(pool.maxLpFeePips, rulesAdmission.maxLpFeePips),
+        maxQuoteTakePips: Math.min(pool.maxQuoteTakePips, rulesAdmission.maxQuoteTakePips),
+        maxSubjectTakeBps: Math.min(pool.maxSubjectTakeBps, rulesAdmission.maxSubjectTakeBps),
+    };
+    if (!advisoryAdmission)
+        return limits;
+    assert(advisoryAdmission.maxLpFeePips <= limits.maxLpFeePips &&
+        advisoryAdmission.maxQuoteTakePips <= limits.maxQuoteTakePips, "Advisory admitted maximum above the pool room");
+    return {
+        maxLpFeePips: limits.maxLpFeePips - advisoryAdmission.maxLpFeePips,
+        maxQuoteTakePips: limits.maxQuoteTakePips - advisoryAdmission.maxQuoteTakePips,
+        maxSubjectTakeBps: limits.maxSubjectTakeBps,
+    };
+}
+const ZERO_ID = `0x${"0".repeat(64)}`;
+/**
+ * `feeTerms(integrator, recapture, id)` calldata for the treasury a Rules pays (r25): its governed floor, `integrator`'s
+ * listed rate and the Hookr minimum of pool `id` (with arb recapture on when `recapture`; `integrator`'s override only
+ * when it approved `id`). It is exactly the read HookrRules makes at bind, with the pool's own id.
+ */
+export function encodeFeeTermsCall(integrator = ZERO, recapture = false, poolId = ZERO_ID) {
+    assert(/^0x[0-9a-fA-F]{64}$/.test(poolId), "Invalid pool id");
+    return encodeFunctionData({
+        abi: treasuryAbi,
+        functionName: "feeTerms",
+        args: [address(integrator, true), recapture, poolId],
+    });
+}
+/**
+ * Decodes a `feeTerms(integrator, recapture, id)` result: `ruleShareFloorBps` for `RulesContext.ruleShareFloorBps`,
+ * the integrator's rate (zero when it is not listed) for `RulesContext.integrators`, and the minimum the treasury
+ * gives the pool (`bindMinFeePips` applies the r31 rule for `RulesContext.minFeePips`). Refuses values no
+ * HookrTreasury holds, and a minimum above the 10,000 pips the Rules accept.
+ */
+export function decodeFeeTerms(data) {
+    const [floor, rate, minimum] = decodeFunctionResult({ abi: treasuryAbi, functionName: "feeTerms", data });
+    return {
+        ruleShareFloorBps: bps(Number(floor), MAX_RULE_SHARE_FLOOR_BPS, "ruleShareFloorBps"),
+        integratorBps: bps(Number(rate), MAX_INTEGRATOR_BPS, "integratorBps"),
+        minFeePips: minFee(Number(minimum)),
+    };
+}
+/** `minimumFee(poolId)` calldata for a HookrRules (served by its fallback): the Hookr minimum the pool froze. */
+export function encodeMinimumFeeCall(poolId) {
+    return encodeFunctionData({ abi: recaptureAbi, functionName: "minimumFee", args: [poolId] });
+}
+/** Decodes a `minimumFee(poolId)` result: the pool's frozen minimum in pips, zero for a pool without one. */
+export function decodeMinimumFee(data) {
+    return minFee(Number(decodeFunctionResult({ abi: recaptureAbi, functionName: "minimumFee", data })));
+}
+/**
+ * `approveMinFeePool(id, approved)` calldata for the treasury, sent by an integrator account itself: it approves (or
+ * withdraws) pool `id` binding that account's Hookr minimum override when the pool names it. Only the sender's own
+ * approvals change; an approval does nothing while the sender has no override, and it is read once, at bind. How Hookr
+ * runs chosen pools at a lower minimum: list an account it controls as an integrator, set that account's override
+ * through the treasury timelock, then have the account approve each chosen pool id before its launch (for a new
+ * token the id follows from `HookrLauncher.predictToken`, and nobody can initialize it first).
+ */
+export function encodeApproveMinFeePoolCall(poolId, approved) {
+    assert(/^0x[0-9a-fA-F]{64}$/.test(poolId), "Invalid pool id");
+    return encodeFunctionData({ abi: treasuryAbi, functionName: "approveMinFeePool", args: [poolId, approved] });
+}
+/** `integration(poolId)` calldata: the integrator and rate a bound pool froze. */
+export function encodeIntegrationCall(poolId) {
+    return encodeFunctionData({ abi: rulesAbi, functionName: "integration", args: [poolId] });
+}
+/** Decodes an `integration(poolId)` result; zeros for a pool without an integrator. */
+export function decodeIntegration(data) {
+    const [integrator, rate] = decodeFunctionResult({ abi: rulesAbi, functionName: "integration", data });
+    return {
+        integrator: integrator.toLowerCase(),
+        integratorBps: bps(Number(rate), MAX_INTEGRATOR_BPS, "integratorBps"),
+    };
+}
+/** `minProtocolShareBps()` calldata: the floor a HookrRules applies to every pool's protocol share. */
+export function encodeMinProtocolShareCall() {
+    return encodeFunctionData({ abi: rulesAbi, functionName: "minProtocolShareBps" });
+}
+/**
+ * Decodes a `minProtocolShareBps()` result, the `ParamContext.minProtocolShareBps` of pools that bind to that Rules.
+ * Refuses a value no HookrRules can hold (its constructor caps it at 5,000 bps).
+ */
+export function decodeMinProtocolShareBps(data) {
+    const v = Number(decodeFunctionResult({ abi: rulesAbi, functionName: "minProtocolShareBps", data }));
+    assert(v <= MAX_PROTOCOL_SHARE_BPS, `minProtocolShareBps ${v} above ${MAX_PROTOCOL_SHARE_BPS}`);
+    return v;
+}
+/**
+ * `protocolShareFloor()` calldata for a HookrRules (r26, served by its HookrRecapture module through the fallback): the
+ * effective floor a pool binding now must meet, the larger of the Rules' minProtocolShareBps and the governed floor of
+ * the treasury they pay (zero governed floor for a recipient without code). One read in place of
+ * `encodeMinProtocolShareCall` plus `encodeFeeTermsCall`; it moves when the treasury's floor changes.
+ */
+export function encodeProtocolShareFloorCall() {
+    return encodeFunctionData({ abi: recaptureAbi, functionName: "protocolShareFloor" });
+}
+/**
+ * Decodes a `protocolShareFloor()` result: the least protocolShareBps a pool binds with now, for
+ * `ParamContext.minProtocolShareBps` (with `ruleShareFloorBps` left at zero, since it already includes the governed
+ * floor). Refuses a value above 5,000 bps, which neither floor can hold.
+ */
+export function decodeProtocolShareFloor(data) {
+    const v = Number(decodeFunctionResult({ abi: recaptureAbi, functionName: "protocolShareFloor", data }));
+    assert(v <= MAX_PROTOCOL_SHARE_BPS, `protocolShareFloor ${v} above ${MAX_PROTOCOL_SHARE_BPS}`);
+    return v;
+}
+/**
+ * `prizeBoundFor(lpBps, burnBps, protocolShareBps, integratorBps)` calldata for a HookrRules (r26, served by its
+ * HookrRecapture module): the widest King of the Pool maxPrizeBps the bind admits for a pool naming an integrator at
+ * that rate (0 for none). `kingOfTheHillPrizeBound` computes the same offline.
+ */
+export function encodePrizeBoundForCall(lpBps, burnBps, protocolShareBps, integratorBps = 0) {
+    return encodeFunctionData({
+        abi: recaptureAbi,
+        functionName: "prizeBoundFor",
+        args: [
+            bps(lpBps, 65_535, "lpBps"),
+            bps(burnBps, 65_535, "burnBps"),
+            bps(protocolShareBps, 65_535, "protocolShareBps"),
+            bps(integratorBps, MAX_INTEGRATOR_BPS, "integratorBps"),
+        ],
+    });
+}
+/** Decodes a `prizeBoundFor(...)` result: the widest maxPrizeBps, in basis points of a buy. */
+export function decodePrizeBoundFor(data) {
+    return decodeFunctionResult({ abi: recaptureAbi, functionName: "prizeBoundFor", data });
+}
+/** `configSchemaHash()` calldata for a HookrRules: its schema id, which must equal RULES_CONFIG_SCHEMA_HASH. */
+export function encodeConfigSchemaHashCall() {
+    return encodeFunctionData({ abi: rulesAbi, functionName: "configSchemaHash" });
+}
+/**
+ * Decodes a `configSchemaHash()` result and refuses any id but RULES_CONFIG_SCHEMA_HASH: a Rules of another layout
+ * (the retired keccak256("hookr.rules.config") among them) is not the Rules this SDK encodes for.
+ */
+export function decodeConfigSchemaHash(data) {
+    const id = decodeFunctionResult({ abi: rulesAbi, functionName: "configSchemaHash", data });
+    assert(id.toLowerCase() === RULES_CONFIG_SCHEMA_HASH.toLowerCase(), `Rules schema id ${id} is not RULES_CONFIG_SCHEMA_HASH (the keccak256 of ${RULES_CONFIG_TYPE})` +
+        (id.toLowerCase() === RETIRED_RULES_CONFIG_SCHEMA_HASH.toLowerCase()
+            ? "; it is the retired 15-word layout's"
+            : ""));
+    return id;
+}
+/**
+ * The accounts HookrRules refuses as a pool's integrator whatever its treasury answers (r26, HookrRules._feeTerms),
+ * lowercase, for `RulesContext.refusedIntegrators` / `ParamContext.refusedIntegrators`: the Rules, their trusted root,
+ * their protocol recipient (the treasury), the PoolManager and their HookrRecapture module (`recaptureModule()`).
+ * None of them ever claims what the Rules would credit it. The treasury also refuses, at proposal and acceptance, the
+ * zero address, itself, the PoolManager and every admitted source.
+ */
+export function bindRefusedIntegrators(a) {
+    return [a.rules, a.trustedRoot, a.protocolRecipient, a.poolManager, a.recaptureModule].map((x) => address(x));
+}
+/**
+ * The accounts HookrRules refuses as a pool's royalty recipient (r31, HookrRules._validate), lowercase, for
+ * `RulesContext.refusedRoyaltyRecipients` / `ParamContext.refusedRoyaltyRecipients`: the Rules, their trusted root, the
+ * PoolManager and their HookrRecapture module (`recaptureModule()`), the integrator refusals less the protocol
+ * recipient. None of them ever claims what settleSwap credits it.
+ */
+export function bindRefusedRoyaltyRecipients(a) {
+    return [a.rules, a.trustedRoot, a.poolManager, a.recaptureModule].map((x) => address(x));
+}