hookr-sdk 0.2.0 → 1.0.0

package/dist/core/rules.d.ts

@@ -0,0 +1,675 @@
+import { type Hex } from "viem";
+import { type Address } from "./schema.js";
+/**
+ * HookrTypes.RulesConfig. Integers up to 48 bits are numbers; the uint128 amounts are bigints. Every field is set by
+ * the pool's creator at launch and frozen at bind.
+ */
+export interface RulesConfig {
+    guardEndBlock: number;
+    maxFeePips: number;
+    /** Anti-Snipe tax at launch, in pips of the pool input. */
+    snipeTaxPips: number;
+    /** Tax the decay ends at: below snipeTaxPips, or zero when snipeDecaySeconds is zero. */
+    snipeFloorPips: number;
+    /** Seconds the tax takes to fall linearly from snipeTaxPips to snipeFloorPips; zero charges snipeTaxPips flat. */
+    snipeDecaySeconds: number;
+    /** Hookr dynamic fee sensitivity, 1 to 10; zero exactly when maxFeePips equals the base fee. */
+    dynamicFeeSens: number;
+    burnBps: number;
+    lpBps: number;
+    potBps: number;
+    royaltyBps: number;
+    protocolShareBps: number;
+    potEveryNBuys: number;
+    maxBuyQuoteAmount: bigint;
+    potMinBuyQuote: bigint;
+    royaltyTo: Address;
+    /**
+     * The pool's integrator, zero for none. A nonzero integrator must be on the integrator list of the treasury the
+     * Rules pay (`HookrTreasury.feeTerms(integrator)` answers a nonzero rate) when the pool binds, or the bind reverts
+     * `UnknownIntegrator`; the pool then freezes it with that rate and pays it the rate of every Hookr share of the
+     * Snipe, dynamic fee, LP Rewards and Auto Burn (`splitProtocolShare`). Set by the app the launch goes through, not
+     * by the creator. The list is on chain: offline, `checkRulesConfig` checks it only against `RulesContext.integrators`.
+     */
+    integrator: Address;
+}
+/** HookrTypes.RecaptureConfig: a recapture pool's creator knobs, frozen at bind as the third part of its rules data. */
+export interface RecaptureConfig {
+    on: boolean;
+    traderBps: number;
+    lpBps: number;
+    period: number;
+    maxPrizeBps: number;
+    potReleaseBps: number;
+    minBuyQuote: bigint;
+    releaseBlocks: number;
+}
+/**
+ * HookrTypes.RulesKnobs (r31): a pool's Rules knobs beyond RulesConfig, frozen at bind as the second part of its rules
+ * data. `minDynamicFeeLiquidity` is a dynamic fee pool's minimum dynamic fee liquidity (1 to 2^96 - 1); the four tempo
+ * knobs are its dynamic fee reference windows (RULES_KNOB_BOUNDS); all five are zero on a pool without dynamic fees.
+ * `snipeCurve` is a decaying Snipe's shape (SNIPE_CURVE), linear unless the Snipe decays.
+ */
+export interface RulesKnobs {
+    minDynamicFeeLiquidity: bigint;
+    windowSeconds: number;
+    resetSeconds: number;
+    carryBps: number;
+    moveTicks: number;
+    snipeCurve: number;
+}
+/**
+ * HookrLauncher.MemberKnobs (r31, launchFamily only): a member's supply weight, its minimum dynamic fee liquidity
+ * divisor (zero for DYNAMIC_FEE_LIQUIDITY_DIVISOR), its lock end and its Rules knobs, which the Launcher passes to the
+ * member's Rules as given (a dynamic fee member whose four tempo knobs are all zero takes the default tempo).
+ */
+export interface MemberKnobs {
+    subjectWeightBps: number;
+    dynamicFeeLiquidityDivisor: number;
+    lockEndBlock: bigint;
+    windowSeconds: number;
+    resetSeconds: number;
+    carryBps: number;
+    moveTicks: number;
+    snipeCurve: number;
+}
+/** HookrTypes.Caps: aggregate fee ceilings. Pips use 1e6, basis points 1e4. */
+export interface Caps {
+    maxLpFeePips: number;
+    maxQuoteTakePips: number;
+    maxSubjectTakeBps: number;
+}
+/** Gas every Rules admission, and so every pool bound to HookrRules, carries: exactly 2,000,000. */
+export declare const RULES_GAS_LIMIT: 2000000;
+/** Ceiling on any LP fee, in pips. */
+export declare const MAX_LP_FEE_PIPS = 600000;
+/**
+ * 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 declare const MAX_PROTOCOL_SHARE_BPS = 5000;
+/**
+ * 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 declare const MAX_RULE_SHARE_FLOOR_BPS: number;
+export declare const MAX_INTEGRATOR_BPS: number;
+export declare const DEFAULT_INTEGRATOR_BPS: number;
+export declare const FEE_TERMS_DELAY_SECONDS: number;
+export declare const FEE_TERMS_GRACE_SECONDS: number;
+/**
+ * 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 declare const MAX_MIN_FEE_PIPS: number;
+export declare const DEFAULT_MIN_FEE_PIPS: number;
+export declare const NO_MIN_FEE_OVERRIDE: number;
+export declare const RULES_MAX_MIN_FEE_PIPS: number;
+/**
+ * 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 declare const HOOKR_TOKEN_RUNTIME_KECCAK256: Hex;
+/**
+ * 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 declare const RECAPTURE_PROTOCOL_BPS: number;
+/**
+ * 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 declare const MAX_LANE_PARTNER_BPS: number;
+/** HookrRecapture.PRIZE_SHARE_OF_FEE_BPS: a King of the Pool prize reaches at most half the protocol fee it bounds. */
+export declare const PRIZE_SHARE_OF_FEE_BPS: number;
+/**
+ * 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 declare const MAX_SNIPE_DECAY_SECONDS: number;
+/** HookrLauncher.DYNAMIC_FEE_LIQUIDITY_DIVISOR: a dynamic fee member's launch liquidity over this is its minimum. */
+export declare const DYNAMIC_FEE_LIQUIDITY_DIVISOR: bigint;
+/** Hookr dynamic fee reference windows (HookrRules.dynamicFeeParameters), in seconds, basis points and ticks. */
+export declare const DYNAMIC_FEE_PARAMETERS: {
+    readonly window: number;
+    readonly reset: number;
+    readonly carryBps: number;
+    readonly moveTicks: number;
+};
+/**
+ * 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 declare const RULES_KNOB_BOUNDS: {
+    readonly minWindowSeconds: number;
+    readonly maxWindowSeconds: number;
+    readonly minResetSeconds: number;
+    readonly maxResetSeconds: number;
+    readonly resetStepSeconds: number;
+    readonly maxCarryBps: number;
+    readonly carryStepBps: number;
+    readonly minMoveTicks: number;
+    readonly maxMoveTicks: number;
+};
+/** RulesKnobs.snipeCurve (HookrTypes.SNIPE_CURVE_*): linear (the default), front-loaded and step. */
+export declare const SNIPE_CURVE: {
+    readonly linear: number;
+    readonly frontLoaded: number;
+    readonly step: number;
+};
+/** HookrTypes.PARENT_BLOCK_SECONDS: a guard's length in parent blocks times this bounds a longer Snipe decay. */
+export declare const PARENT_BLOCK_SECONDS: number;
+/** The knobs of a pool bound without any (`abi.encode(RulesConfig)`): every field zero. */
+export declare const NO_RULES_KNOBS: RulesKnobs;
+/**
+ * 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 declare const DYNAMIC_FEE_REACH: {
+    readonly maxReach: bigint;
+    readonly maxReserve: bigint;
+    readonly reserveScale: bigint;
+};
+/** Longest launch guard, in blocks after the binding block. */
+export declare const MAX_GUARD_BLOCKS = 100000;
+/**
+ * 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 declare const RULES_CONFIG_TYPE: string;
+/**
+ * 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 declare const RULES_CONFIG_SCHEMA_HASH: Hex;
+/**
+ * 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 declare const RETIRED_RULES_CONFIG_SCHEMA_HASH: `0x${string}`;
+/**
+ * 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 declare const RULES_DATA_WORDS: {
+    readonly config: 16;
+    readonly knobs: number;
+    readonly recapture: number;
+};
+/** ABI-encodes a RulesConfig alone: `abi.encode(RulesConfig)`, the rules data of a pool without dynamic fees. */
+export declare function encodeRulesConfig(c: RulesConfig): Hex;
+/** Decodes a config-only rules data (`abi.encode(RulesConfig)`), refusing any non-canonical encoding. */
+export declare function decodeRulesConfig(data: Hex): RulesConfig;
+/**
+ * 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 declare function checkRulesKnobs(c: Pick<RulesConfig, "dynamicFeeSens" | "snipeDecaySeconds">, knobs: RulesKnobs, form: "config" | "knobs" | "recapture"): {
+    custom: boolean;
+    tempo: boolean;
+};
+/**
+ * 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 declare function encodeRulesData(c: RulesConfig, knobs?: RulesKnobs, recapture?: RecaptureConfig): Hex;
+/**
+ * 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 declare function decodeRulesData(data: Hex): {
+    config: RulesConfig;
+    knobs: RulesKnobs;
+    minLiquidity: bigint;
+    recapture?: RecaptureConfig;
+};
+/**
+ * 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 declare function dynamicFeeMinLiquidity(liquidity: bigint, divisor?: number): bigint;
+/**
+ * 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 declare function launcherRulesData(c: RulesConfig, liquidity: bigint, opts?: {
+    recapture?: RecaptureConfig;
+    knobs?: Partial<MemberKnobs>;
+}): Hex;
+/**
+ * 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 declare function maxSnipeDecaySeconds(guardEndBlock: number | bigint, blockNumber?: bigint): number;
+/** Whether a dynamic fee of `spanPips` (maxFeePips less the base fee) at `sens` and `shareBps` binds (HookrDynamicFee.withinReach). */
+export declare function withinDynamicFeeReach(spanPips: number | bigint, sens: number, shareBps: number): boolean;
+/**
+ * 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 declare function snipeTaxAt(c: RulesConfig, launchedAt: number | bigint, timestamp: number | bigint, curve?: number): number;
+/**
+ * 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 declare function guardBuyLimit(c: RulesConfig, snipePips: number): bigint | null;
+/**
+ * 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 declare function dynamicFeeAverageRate(a: bigint, b: bigint, sens: number): bigint;
+/**
+ * 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 declare function dynamicFeeDistance(sqrtRefX96: bigint, sqrtPriceX96: bigint, zeroForOne: boolean): bigint;
+/** Dynamic fee pips before clipping for a move over the distances [a, b]: the span times the average rate. */
+export declare function dynamicFeePips(c: RulesConfig, baseLpFeePips: number, a: bigint, b: bigint): number;
+/**
+ * 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 declare function protocolSharePips(bps: number | bigint, shareBps: number | bigint): bigint;
+/**
+ * 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 declare function royaltyPips(c: Pick<RulesConfig, "lpBps" | "protocolShareBps" | "royaltyBps">): number;
+/**
+ * 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 declare function lpRewardPips(c: Pick<RulesConfig, "lpBps" | "protocolShareBps" | "royaltyBps">): number;
+/**
+ * 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 declare function rulesFeeCeilings(c: RulesConfig, baseLpFeePips: number, minFeePips?: number): Caps;
+/**
+ * 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 declare function nativeLpCeiling(c: RulesConfig, baseLpFeePips: number, snipeTax?: number): number;
+/** Pool facts `checkRulesConfig` validates a configuration against. */
+export interface RulesContext {
+    baseLpFeePips: number;
+    /** HookrRules.minProtocolShareBps of the Rules the pool binds to. */
+    minProtocolShareBps: number;
+    /**
+     * The governed rule-share floor of the treasury the Rules pay (`feeTerms(..).ruleShareFloorBps`, read at the block
+     * the launch lands in, `encodeFeeTermsCall`). The pool binds at no less than the larger of it and
+     * minProtocolShareBps. Omitted: zero, the treasury's starting value.
+     */
+    ruleShareFloorBps?: number;
+    /**
+     * The treasury's integrator list as read on chain: lowercase address to its rate (`feeTerms(integrator)`). With it a
+     * nonzero `integrator` must be listed at 1 to 5,000; without it the list is not checked offline, and the Rules refuse
+     * an integrator off the list at bind (`UnknownIntegrator`).
+     */
+    integrators?: Readonly<Record<string, number>>;
+    /**
+     * Accounts HookrRules refuses as integrator whatever the treasury answers (r26, `bindRefusedIntegrators`): the Rules
+     * themselves, their trusted root, their protocol recipient, the PoolManager and their HookrRecapture module, none of
+     * which ever claims what the Rules credit it. With it such an integrator is refused offline; the bind refuses it
+     * either way (`UnknownIntegrator`).
+     */
+    refusedIntegrators?: readonly Address[];
+    /**
+     * Accounts HookrRules refuses as the royalty recipient (r31, `bindRefusedRoyaltyRecipients`): the Rules themselves,
+     * their trusted root, the PoolManager and their HookrRecapture module, none of which ever claims what settleSwap
+     * credits it. With it such a `royaltyTo` is refused offline; the bind refuses it either way (`InvalidConfig`, which a
+     * launch reports as the root's `ModuleCallReverted`).
+     */
+    refusedRoyaltyRecipients?: readonly Address[];
+    /**
+     * The Hookr minimum the pool freezes at bind, in pips (`bindMinFeePips`: the treasury's `feeTerms(..).minFeePips`
+     * for a Hookr token's pool without arb recapture whose rules earn Hookr nothing, zero for any other pool). The fee
+     * ceilings then admit royalty + minimum. Omitted: zero, a pool without a minimum.
+     */
+    minFeePips?: number;
+    /** The caps the Rules sees (`rulesBindCaps`). Omitted: the ceilings are returned without a cap check. */
+    caps?: Caps;
+    /** Current block.number; with it the launch guard window is checked. */
+    blockNumber?: bigint;
+    liquidityOwner?: Address;
+}
+/** Whether a runtime codehash is HookrToken's (`HOOKR_TOKEN_RUNTIME_KECCAK256`), the test HookrRules applies at bind. */
+export declare function isHookrTokenRuntime(codeHash: Hex): boolean;
+/** The RulesConfig fields that decide whether a pool's rules earn Hookr a share (`earnsHookr`). */
+export type EarningRules = Pick<RulesConfig, "protocolShareBps" | "lpBps" | "burnBps" | "maxFeePips" | "snipeTaxPips">;
+/** What decides a pool's Hookr minimum at bind (`bindMinFeePips`), besides its subject and the treasury's answer. */
+export interface MinimumTerms {
+    /** The pool's RulesConfig. */
+    rules: EarningRules;
+    /** The pool's base LP fee in pips. */
+    baseLpFeePips: number;
+    /** Whether the pool binds arb recapture (a RecaptureConfig with `on`, which freezes the root's lane executor). */
+    recapture: boolean;
+    /**
+     * The quote cap (`maxQuoteTakePips`) of the pool's advisory admission on its root when that advisory is Tax +
+     * Conversion (its `EXCLUSIVE_GROUP()` is keccak256("DIRECTIONAL_QUOTE_TAX")); null or omitted for any other
+     * advisory or none.
+     */
+    taxConversion?: {
+        maxQuoteTakePips: number;
+    } | null;
+}
+/**
+ * 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 declare function earnsHookr(rules: EarningRules, baseLpFeePips: number): boolean;
+/**
+ * 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 declare function bindMinFeePips(subject: "new" | Hex, treasuryMinFeePips: number, terms: MinimumTerms): number;
+/**
+ * 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 declare function treasuryMinFeePips(t: {
+    plainPips: number;
+    recapturePips: number;
+    recapture: boolean;
+    overridePips?: number;
+    approved?: boolean;
+}): number;
+/**
+ * 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 declare function effectiveShareFloor(minProtocolShareBps: number, ruleShareFloorBps?: number): number;
+/**
+ * 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 declare function listedIntegratorBps(integrator: Address, integrators?: Readonly<Record<string, number>>): number | undefined;
+/**
+ * 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 declare function splitProtocolShare(share: bigint, integratorBps: number): {
+    protocol: bigint;
+    integrator: bigint;
+};
+/** One swap's HookrRules quote (HookrTypes.FeeQuote) with the parts of its quote take. */
+export interface RulesQuote {
+    /** LP fee on top of the base fee: LP Rewards and the LPs' part of the dynamic fee and Snipe. */
+    lpFeeSurchargePips: number;
+    /** The quote take: royalty + max(ruleSharePips, minimum). */
+    quoteTakePips: number;
+    subjectBurnBps: number;
+    /** The creator's royalty in the take (buys only). */
+    royaltyPips: number;
+    /** Hookr's rule-fee share: its part of LP Rewards and Auto Burn (rounded up) and of the dynamic fee and Snipe. */
+    ruleSharePips: number;
+    /** What the Hookr minimum adds: max(0, minimum - ruleSharePips). */
+    topUpPips: number;
+}
+/**
+ * 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 declare function rulesQuote(c: RulesConfig, s: {
+    baseLpFeePips: number;
+    isBuy: boolean;
+    dynamicFeePips?: number;
+    snipePips?: number;
+    minFeePips?: number;
+}): RulesQuote;
+/**
+ * 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 declare function simulationQuote(c: RulesConfig, s: {
+    baseLpFeePips: number;
+    isBuy: boolean;
+    exactInput: boolean;
+    snipePips?: number;
+    minFeePips?: number;
+}): RulesQuote;
+/** The four swap shapes a pool quotes: buys and sells, each exact input or exact output. */
+export type SwapShape = "exactInputBuy" | "exactOutputBuy" | "exactInputSell" | "exactOutputSell";
+/**
+ * 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 declare function rulesSwapFees(s: {
+    shape: SwapShape;
+    quoteTakePips: number;
+    royaltyPips: number;
+    integratorBps?: number;
+    actualQuote: bigint;
+    requested: bigint;
+}): {
+    quoteBasis: bigint;
+    rulesFee: bigint;
+    royalty: bigint;
+    hookr: bigint;
+    protocol: bigint;
+    integrator: bigint;
+};
+/**
+ * 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 declare function recaptureProfit(pushed: bigint, partnerBps: number): bigint;
+/**
+ * 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 declare function recaptureSplit(p: {
+    amount: bigint;
+    reportedProfit: bigint;
+    traderBasis: bigint;
+    trader: Address;
+    traderBps: number;
+    potBps: number;
+    inQuote: boolean;
+}): {
+    protocol: bigint;
+    trader: bigint;
+    pot: bigint;
+    lp: bigint;
+};
+/**
+ * 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 declare function kingOfTheHillPrizeBound(lpBps: number, burnBps: number, protocolShareBps: number, integratorBps?: number): bigint;
+/**
+ * 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 declare function checkRulesConfig(c: RulesConfig, ctx: RulesContext): Caps;
+/**
+ * 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 declare function poolCapsFor(rules: Caps, baseLpFeePips: number, advisory?: Caps): 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 declare function rulesBindCaps(pool: Caps, rulesAdmission: Caps, advisoryAdmission?: Caps): Caps;
+/**
+ * `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 declare function encodeFeeTermsCall(integrator?: Address, recapture?: boolean, poolId?: Hex): Hex;
+/**
+ * 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 declare function decodeFeeTerms(data: Hex): {
+    ruleShareFloorBps: number;
+    integratorBps: number;
+    minFeePips: number;
+};
+/** `minimumFee(poolId)` calldata for a HookrRules (served by its fallback): the Hookr minimum the pool froze. */
+export declare function encodeMinimumFeeCall(poolId: Hex): Hex;
+/** Decodes a `minimumFee(poolId)` result: the pool's frozen minimum in pips, zero for a pool without one. */
+export declare function decodeMinimumFee(data: Hex): number;
+/**
+ * `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 declare function encodeApproveMinFeePoolCall(poolId: Hex, approved: boolean): Hex;
+/** `integration(poolId)` calldata: the integrator and rate a bound pool froze. */
+export declare function encodeIntegrationCall(poolId: Hex): Hex;
+/** Decodes an `integration(poolId)` result; zeros for a pool without an integrator. */
+export declare function decodeIntegration(data: Hex): {
+    integrator: Address;
+    integratorBps: number;
+};
+/** `minProtocolShareBps()` calldata: the floor a HookrRules applies to every pool's protocol share. */
+export declare function encodeMinProtocolShareCall(): Hex;
+/**
+ * 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 declare function decodeMinProtocolShareBps(data: Hex): number;
+/**
+ * `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 declare function encodeProtocolShareFloorCall(): Hex;
+/**
+ * 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 declare function decodeProtocolShareFloor(data: Hex): number;
+/**
+ * `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 declare function encodePrizeBoundForCall(lpBps: number, burnBps: number, protocolShareBps: number, integratorBps?: number): Hex;
+/** Decodes a `prizeBoundFor(...)` result: the widest maxPrizeBps, in basis points of a buy. */
+export declare function decodePrizeBoundFor(data: Hex): bigint;
+/** `configSchemaHash()` calldata for a HookrRules: its schema id, which must equal RULES_CONFIG_SCHEMA_HASH. */
+export declare function encodeConfigSchemaHashCall(): Hex;
+/**
+ * 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 declare function decodeConfigSchemaHash(data: Hex): Hex;
+/**
+ * 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 declare function bindRefusedIntegrators(a: {
+    rules: Address;
+    trustedRoot: Address;
+    protocolRecipient: Address;
+    poolManager: Address;
+    recaptureModule: Address;
+}): Address[];
+/**
+ * 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 declare function bindRefusedRoyaltyRecipients(a: {
+    rules: Address;
+    trustedRoot: Address;
+    poolManager: Address;
+    recaptureModule: Address;
+}): Address[];