hookr-sdk 0.2.1 → 1.0.0

package/dist/reads.d.ts

@@ -1,136 +0,0 @@
-/**
- * Read a market from the coordinator, list markets from `MarketCreated` logs, and read a pool's
- * frozen rules from the stack registry.
- *
- * `readMarket` mirrors `HookrMarketCoordinatorV5.getMarket`; `listMarkets` mirrors the log shape
- * and scan-from block in the app's `src/lib/v2-discover-server.ts` (`v2MarketRowFromLog`,
- * `V2_MARKET_SCAN_FROM_BLOCK`); `readPoolRules` mirrors the registry read the app's agent skill
- * (`src/lib/agent-skill.ts`, "Read a pool's rules") describes in prose: `stack(poolId)` for the
- * module count and limits, then `moduleAt(poolId, i)` for each module, decoding the
- * native-mechanics module's `config` with `market.ts`'s `NativeConfig` tuple.
- */
-import { type Address, type Hex, type PublicClient } from "viem";
-import type { NativeConfig, StackLimits } from "./market.js";
-/** `HookrMarketCoordinatorV5.MarketOrigin`: 1 is a token the coordinator deployed, 2 an existing one. */
-export type MarketOrigin = "new-token" | "existing-token";
-export type Market = Readonly<{
-    live: boolean;
-    origin: MarketOrigin;
-    subject: Address;
-    quote: Address;
-    creator: Address;
-    kernel: Address;
-    lpFeeRecipient: Address;
-    kernelId: Hex;
-    stackHash: Hex;
-    poolId: Hex;
-    sqrtPriceX96: bigint;
-    tickSpacing: number;
-    subjectSupplied: bigint;
-    quoteSupplied: bigint;
-    subjectUsed: bigint;
-    quoteUsed: bigint;
-    cumulativeFee0: bigint;
-    cumulativeFee1: bigint;
-    openedAtBlock: bigint;
-    launchIntentId: Hex;
-    initialBuyRouter: Address;
-    creatorAllocation: bigint;
-    initialBuyQuoteIn: bigint;
-    initialBuySubjectOut: bigint;
-    initialBuySubjectOutMinimum: bigint;
-    initialBuyModuleDataHash: Hex;
-}>;
-/** `marketCoordinator.getMarket(poolId)`. `live` is false for a `poolId` the coordinator never opened. */
-export declare function readMarket(client: PublicClient, poolId: Hex): Promise<Market>;
-/** The coordinator's deploy block on chain 4663: no `MarketCreated` log can sit before it. */
-export declare const MARKET_SCAN_FROM_BLOCK = 57229676n;
-/**
- * Blocks per `eth_getLogs` window in `listMarkets`, the same width the app's own scanners use.
- * The chain's public node answers an over-wide window with an empty array rather than an error,
- * so one request over the whole history is a silent miss waiting to happen; a bounded window
- * keeps each answer small. Lower it further on a provider with a tighter range limit.
- */
-export declare const MARKET_SCAN_CHUNK_BLOCKS = 3000000n;
-export declare const MARKET_CREATED_TOPIC: Hex;
-/** One decoded `MarketCreated` log: every field the coordinator emitted, nothing derived. */
-export type MarketRow = Readonly<{
-    poolId: Hex;
-    subject: Address;
-    quote: Address;
-    creator: Address;
-    origin: MarketOrigin;
-    kernel: Address;
-    sqrtPriceX96: bigint;
-    tickSpacing: number;
-    blockNumber: bigint;
-    txHash: Hex;
-    logIndex: number;
-}>;
-/**
- * Every `MarketCreated` log the coordinator emitted in `[fromBlock, toBlock]`, oldest first,
- * fetched in windows of `chunkBlocks` (`MARKET_SCAN_CHUNK_BLOCKS` by default).
- *
- * `root`, when given, is checked against every row's `kernel` rather than passed to the log
- * filter, because `kernel` is not an indexed topic. Pass `ADDRESSES.root` for markets on the
- * default root, `ADDRESSES.recaptureRoot` for markets on the recapture root, or nothing for
- * every market the coordinator opened, on any root.
- */
-export declare function listMarkets(client: PublicClient, options?: Readonly<{
-    root?: Address;
-    fromBlock?: bigint;
-    toBlock?: bigint;
-    chunkBlocks?: bigint;
-}>): Promise<readonly MarketRow[]>;
-/** The inverse of `market.ts`'s `encodeNativeBlockConfig`. */
-export declare function decodeNativeBlockConfig(data: Hex): NativeConfig;
-export type PoolRules = Readonly<{
-    /** False when the registry has no stack for this `poolId` at all. */
-    configured: boolean;
-    limits: StackLimits | null;
-    /** The native-mechanics module's decoded config; null when the pool carries no such module. */
-    nativeConfig: NativeConfig | null;
-}>;
-/**
- * `stackRegistry.stack(poolId)` for `moduleCount`/`limits`, then `stackRegistry.moduleAt` for
- * each module, decoding the native-mechanics module's `config` bytes. Every other module (the
- * directional tax block, when a pool carries one) is skipped: its config schema is not modeled
- * by this package.
- */
-export declare function readPoolRules(client: PublicClient, poolId: Hex): Promise<PoolRules>;
-/**
- * True when the pool's frozen rules name a correction executor, so the root's kernel dispatches a
- * correction around every swap and the swap needs `CORRECTION_SWAP_GAS_FLOOR`. This is the pool's
- * own record rather than the root's identity: a pool on a superseded recapture root keeps its
- * executor and keeps correcting, which `isCorrectingRoot` (current root only) does not see. Pass
- * the result as `correcting` to the swap builders. It is also true for a pool whose lane cannot
- * run on ordinary gas (the first recapture root); the floor is then unused headroom, not a loss.
- */
-export declare function poolCorrects(rules: PoolRules): boolean;
-/** `HookrStackRegistryV1.KernelStatus`. */
-export type RootStatus = "unset" | "active" | "retired";
-/** One registered root (kernel) as the stack registry records it. */
-export type RootRow = Readonly<{
-    kernelId: Hex;
-    /** The root hook: `PoolKey.hooks` for every pool opened on it. */
-    hook: Address;
-    version: number;
-    codeHash: Hex;
-    hookFlags: bigint;
-    status: RootStatus;
-    /** True when the registry holds a sealed root profile for this kernel; the coordinator only
-     *  opens markets on a sealed profile. */
-    sealed: boolean;
-    profileId: Hex | null;
-    moduleCount: number | null;
-}>;
-/**
- * Every kernel the stack registry has registered, in registration order: `kernelCount`, then
- * `kernelIdAt`, `kernel`, `kernelStatus` and `rootProfile` for each. Nothing here comes from a
- * list in this package, so a root this package has never heard of still appears. `rootProfile`
- * reverts for a kernel whose profile was never sealed; that reads as `sealed: false`.
- *
- * The registry never retires a root on its own, so an active, sealed root is not the same thing
- * as a current one: `ROOTS` names the two roots Hookr opens markets on today.
- */
-export declare function listRoots(client: PublicClient): Promise<readonly RootRow[]>;

package/dist/reads.js

@@ -1,219 +0,0 @@
-/**
- * Read a market from the coordinator, list markets from `MarketCreated` logs, and read a pool's
- * frozen rules from the stack registry.
- *
- * `readMarket` mirrors `HookrMarketCoordinatorV5.getMarket`; `listMarkets` mirrors the log shape
- * and scan-from block in the app's `src/lib/v2-discover-server.ts` (`v2MarketRowFromLog`,
- * `V2_MARKET_SCAN_FROM_BLOCK`); `readPoolRules` mirrors the registry read the app's agent skill
- * (`src/lib/agent-skill.ts`, "Read a pool's rules") describes in prose: `stack(poolId)` for the
- * module count and limits, then `moduleAt(poolId, i)` for each module, decoding the
- * native-mechanics module's `config` with `market.ts`'s `NativeConfig` tuple.
- */
-import { decodeAbiParameters, getAbiItem, toEventSelector } from "viem";
-import { hookrMarketCoordinatorV5Abi, hookrStackRegistryV2Abi } from "./abi.js";
-import { ADDRESSES, MODULE_ID, NATIVE_ADDRESS } from "./chain.js";
-function marketOrigin(value) {
-    if (value === 1)
-        return "new-token";
-    if (value === 2)
-        return "existing-token";
-    throw new Error(`Unknown MarketOrigin ${value}.`);
-}
-/** `marketCoordinator.getMarket(poolId)`. `live` is false for a `poolId` the coordinator never opened. */
-export async function readMarket(client, poolId) {
-    const m = (await client.readContract({
-        address: ADDRESSES.coordinator,
-        abi: hookrMarketCoordinatorV5Abi,
-        functionName: "getMarket",
-        args: [poolId],
-    }));
-    return Object.freeze({ ...m, origin: marketOrigin(m.origin) });
-}
-// -----------------------------------------------------------------------------------------------
-// listMarkets
-// -----------------------------------------------------------------------------------------------
-/** The coordinator's deploy block on chain 4663: no `MarketCreated` log can sit before it. */
-export const MARKET_SCAN_FROM_BLOCK = 57229676n;
-/**
- * Blocks per `eth_getLogs` window in `listMarkets`, the same width the app's own scanners use.
- * The chain's public node answers an over-wide window with an empty array rather than an error,
- * so one request over the whole history is a silent miss waiting to happen; a bounded window
- * keeps each answer small. Lower it further on a provider with a tighter range limit.
- */
-export const MARKET_SCAN_CHUNK_BLOCKS = 3000000n;
-const MARKET_CREATED_EVENT = getAbiItem({ abi: hookrMarketCoordinatorV5Abi, name: "MarketCreated" });
-export const MARKET_CREATED_TOPIC = toEventSelector(MARKET_CREATED_EVENT);
-/**
- * Every `MarketCreated` log the coordinator emitted in `[fromBlock, toBlock]`, oldest first,
- * fetched in windows of `chunkBlocks` (`MARKET_SCAN_CHUNK_BLOCKS` by default).
- *
- * `root`, when given, is checked against every row's `kernel` rather than passed to the log
- * filter, because `kernel` is not an indexed topic. Pass `ADDRESSES.root` for markets on the
- * default root, `ADDRESSES.recaptureRoot` for markets on the recapture root, or nothing for
- * every market the coordinator opened, on any root.
- */
-export async function listMarkets(client, options = {}) {
-    const fromBlock = options.fromBlock ?? MARKET_SCAN_FROM_BLOCK;
-    const toBlock = options.toBlock ?? (await client.getBlockNumber());
-    const chunk = options.chunkBlocks ?? MARKET_SCAN_CHUNK_BLOCKS;
-    if (chunk <= 0n)
-        throw new Error("chunkBlocks must be positive.");
-    const logs = [];
-    for (let from = fromBlock; from <= toBlock; from += chunk) {
-        const to = from + chunk - 1n < toBlock ? from + chunk - 1n : toBlock;
-        logs.push(...(await client.getLogs({
-            address: ADDRESSES.coordinator,
-            event: MARKET_CREATED_EVENT,
-            fromBlock: from,
-            toBlock: to,
-            strict: true,
-        })));
-    }
-    const rows = [];
-    for (const log of logs) {
-        const args = log.args;
-        const row = Object.freeze({
-            poolId: args.poolId,
-            subject: args.subject,
-            quote: args.quote,
-            creator: args.creator,
-            origin: marketOrigin(args.origin),
-            kernel: args.kernel,
-            sqrtPriceX96: args.sqrtPriceX96,
-            tickSpacing: args.tickSpacing,
-            blockNumber: log.blockNumber,
-            txHash: log.transactionHash,
-            logIndex: log.logIndex ?? 0,
-        });
-        if (options.root && row.kernel.toLowerCase() !== options.root.toLowerCase())
-            continue;
-        rows.push(row);
-    }
-    rows.sort((a, b) => (a.blockNumber === b.blockNumber ? a.logIndex - b.logIndex : a.blockNumber < b.blockNumber ? -1 : 1));
-    return Object.freeze(rows);
-}
-// -----------------------------------------------------------------------------------------------
-// readPoolRules
-// -----------------------------------------------------------------------------------------------
-const CONFIG_COMPONENTS = [
-    { name: "poolId", type: "bytes32" },
-    { name: "kernel", type: "address" },
-    { name: "subject", type: "address" },
-    { name: "quote", type: "address" },
-    { name: "lockedLiquidityProvider", type: "address" },
-    { name: "guardEndBlock", type: "uint40" },
-    { name: "baseFeePips", type: "uint24" },
-    { name: "maxFeePips", type: "uint24" },
-    { name: "snipeTaxPips", type: "uint24" },
-    { name: "surgeSens", type: "uint16" },
-    { name: "burnBps", type: "uint16" },
-    { name: "lpBps", type: "uint16" },
-    { name: "potBps", type: "uint16" },
-    { name: "royaltyBps", type: "uint16" },
-    { name: "potEveryNBuys", type: "uint32" },
-    { name: "maxBuyQuoteAmount", type: "uint96" },
-    { name: "potMinBuyWei", type: "uint96" },
-    { name: "royaltyTo", type: "address" },
-    { name: "protocolRecipient", type: "address" },
-    { name: "protocolShareBps", type: "uint24" },
-];
-const CONFIG_ABI = [{ type: "tuple", components: CONFIG_COMPONENTS }];
-/** The inverse of `market.ts`'s `encodeNativeBlockConfig`. */
-export function decodeNativeBlockConfig(data) {
-    const raw = decodeAbiParameters(CONFIG_ABI, data)[0];
-    return Object.freeze({ ...raw, guardEndBlock: BigInt(raw.guardEndBlock) });
-}
-/**
- * `stackRegistry.stack(poolId)` for `moduleCount`/`limits`, then `stackRegistry.moduleAt` for
- * each module, decoding the native-mechanics module's `config` bytes. Every other module (the
- * directional tax block, when a pool carries one) is skipped: its config schema is not modeled
- * by this package.
- */
-export async function readPoolRules(client, poolId) {
-    const core = (await client.readContract({
-        address: ADDRESSES.registry,
-        abi: hookrStackRegistryV2Abi,
-        functionName: "stack",
-        args: [poolId],
-    }));
-    if (!core.configured)
-        return Object.freeze({ configured: false, limits: null, nativeConfig: null });
-    let nativeConfig = null;
-    for (let i = 0; i < core.moduleCount; i++) {
-        const [snapshot, config] = (await client.readContract({
-            address: ADDRESSES.registry,
-            abi: hookrStackRegistryV2Abi,
-            functionName: "moduleAt",
-            args: [poolId, BigInt(i)],
-        }));
-        if (snapshot.moduleId.toLowerCase() === MODULE_ID.toLowerCase()) {
-            nativeConfig = decodeNativeBlockConfig(config);
-            break;
-        }
-    }
-    return Object.freeze({ configured: true, limits: core.limits, nativeConfig });
-}
-/**
- * True when the pool's frozen rules name a correction executor, so the root's kernel dispatches a
- * correction around every swap and the swap needs `CORRECTION_SWAP_GAS_FLOOR`. This is the pool's
- * own record rather than the root's identity: a pool on a superseded recapture root keeps its
- * executor and keeps correcting, which `isCorrectingRoot` (current root only) does not see. Pass
- * the result as `correcting` to the swap builders. It is also true for a pool whose lane cannot
- * run on ordinary gas (the first recapture root); the floor is then unused headroom, not a loss.
- */
-export function poolCorrects(rules) {
-    const executor = rules.limits?.correctionExecutor;
-    return executor !== undefined && executor.toLowerCase() !== NATIVE_ADDRESS.toLowerCase();
-}
-function rootStatus(value) {
-    if (value === 0)
-        return "unset";
-    if (value === 1)
-        return "active";
-    if (value === 2)
-        return "retired";
-    throw new Error(`Unknown KernelStatus ${value}.`);
-}
-/**
- * Every kernel the stack registry has registered, in registration order: `kernelCount`, then
- * `kernelIdAt`, `kernel`, `kernelStatus` and `rootProfile` for each. Nothing here comes from a
- * list in this package, so a root this package has never heard of still appears. `rootProfile`
- * reverts for a kernel whose profile was never sealed; that reads as `sealed: false`.
- *
- * The registry never retires a root on its own, so an active, sealed root is not the same thing
- * as a current one: `ROOTS` names the two roots Hookr opens markets on today.
- */
-export async function listRoots(client) {
-    const registry = { address: ADDRESSES.registry, abi: hookrStackRegistryV2Abi };
-    const count = (await client.readContract({ ...registry, functionName: "kernelCount" }));
-    const rows = [];
-    for (let i = 0n; i < count; i++) {
-        const kernelId = (await client.readContract({ ...registry, functionName: "kernelIdAt", args: [i] }));
-        const record = (await client.readContract({ ...registry, functionName: "kernel", args: [kernelId] }));
-        const status = (await client.readContract({ ...registry, functionName: "kernelStatus", args: [kernelId] }));
-        let sealed = false;
-        let profileId = null;
-        let moduleCount = null;
-        try {
-            const profile = (await client.readContract({ ...registry, functionName: "rootProfile", args: [kernelId] }));
-            sealed = profile.isSealed;
-            profileId = profile.profileId;
-            moduleCount = profile.moduleCount;
-        }
-        catch {
-            // Unsealed: the registry reverts rather than returning an empty profile.
-        }
-        rows.push(Object.freeze({
-            kernelId,
-            hook: record.implementation,
-            version: record.version,
-            codeHash: record.implementationCodeHash,
-            hookFlags: record.hookFlags,
-            status: rootStatus(status),
-            sealed,
-            profileId,
-            moduleCount,
-        }));
-    }
-    return rows;
-}

package/dist/rules.d.ts

@@ -1,84 +0,0 @@
-/**
- * The public rules a market's stack can carry, and their bounds.
- *
- * Copied from the Hookr app's `src/lib/hooks-model.ts`: `RULES` mirrors `HOOKS` reduced to
- * `{ key, name, summary, explanation }`, and `PARAMS` mirrors the bounds/step/default of the
- * app's `PARAMS[type]` (its display-only `fmt` function is not carried here; `unit` is a short,
- * human label instead — see the module doc below). Both are restricted to the app's
- * `PUBLIC_BUILDER_HOOK_ORDER`, which today is the five deployed blocks (`HOOK_ORDER`): the
- * directional tax module (`DIRECTIONAL_TAX_UI` in the app) is off and is not offered here either.
- * `src/test/hookr-sdk-parity.test.ts` in the app asserts the key order and every bound match.
- *
- * A rule compiles into the native block's `Config` (see `fees.ts` and `market.ts`); it is not a
- * separate contract call. At most five rules on a stack today, one per key, because there are
- * only five public rule keys — `validateStack` still checks the count explicitly so a future
- * sixth key does not silently raise the ceiling.
- */
-export type RuleKey = "snipe" | "fee" | "burn" | "lp" | "pot";
-/** The public rule keys, in the order the app's builder palette offers them. */
-export declare const RULE_ORDER: readonly RuleKey[];
-export type Rule = Readonly<{
-    key: RuleKey;
-    name: string;
-    /** Compact catalogue tagline. */
-    summary: string;
-    /** One complete, plain-language sentence. */
-    explanation: string;
-}>;
-export declare const RULES: readonly Rule[];
-export declare function ruleFor(key: RuleKey): Rule;
-export type Param = Readonly<{
-    key: string;
-    label: string;
-    min: number;
-    max: number;
-    step: number;
-    def: number;
-    /** Short display unit, e.g. "%", "BLK", "ETH". Display-only; not asserted byte-for-byte
-     *  against the app's `fmt` function, which the app keeps as a closure, not exported data. */
-    unit: string;
-    hint: string;
-}>;
-export declare const PARAMS: Readonly<Record<RuleKey, readonly Param[]>>;
-export type RuleBlock = Readonly<{
-    type: RuleKey;
-    params: Readonly<Record<string, number>>;
-}>;
-/** The native block's `Config` rate fields a stack of rule blocks compiles into. */
-export type CompiledRules = Readonly<{
-    guardBlocks: number;
-    maxBuyBps: number;
-    snipeTaxPips: number;
-    baseFeePips: number;
-    maxFeePips: number;
-    surgeSens: number;
-    burnBps: number;
-    lpBps: number;
-    potBps: number;
-    potEveryNBuys: number;
-    potMinBuyWei: bigint;
-}>;
-/**
- * Compile a stack of public rule blocks into the exact rate fields the native block's `Config`
- * carries, mirroring `compileStack` in the app's `src/lib/hooks-model.ts`.
- *
- * `baseFeePipsOverride` is the stack-level Base LP fee, chosen independently of whether a
- * Surge Fees rule is present — it always wins over the Surge block's own "Base fee" slider,
- * exactly like the app's builder. The block still supplies the surge ceiling and sensitivity.
- */
-export declare function compileRuleBlocks(blocks: readonly RuleBlock[], baseFeePipsOverride: number): CompiledRules;
-/** The default single block for one rule: every param at its `def`. */
-export declare function defaultBlock(key: RuleKey): RuleBlock;
-/** The starting stack a new configuration opens with: no rules, base fee only. */
-export declare function defaultStack(): readonly RuleBlock[];
-export declare const MAX_STACK_RULES = 5;
-export type ValidationResult = Readonly<{
-    ok: boolean;
-    errors: readonly string[];
-}>;
-/**
- * Validate a stack of rule blocks: unknown rule keys, duplicate rules, more than
- * `MAX_STACK_RULES` rules, an unknown parameter, or a parameter outside its bounds or off its
- * step grid. Every problem is reported, not just the first.
- */
-export declare function validateStack(blocks: readonly RuleBlock[]): ValidationResult;