hookr-sdk 0.1.0

package/dist/market.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Pool key/id, the native block's config encoding, stack limits, and the two coordinator calls
+ * that open a market.
+ *
+ * `poolKeyFor`, `poolIdFor`, the config encoder and `stackLimitsFor` are pure, faithful copies
+ * of `src/lib/v2-encode.ts` in the Hookr app (`v2PoolKey`, `v2PoolId`, `encodeV2Config`,
+ * `v2StackLimits`) — nothing here reads a chain, so `src/test/hookr-sdk-parity.test.ts` proves
+ * them by calling both on the same fixed inputs and asserting byte-for-byte agreement.
+ *
+ * `buildNewTokenMarketCall` and `buildExistingTokenMarketCall` assemble the exact
+ * `openNewTokenMarket` / `openExistingTokenMarket` calldata `src/lib/v2-launch-execute.ts`
+ * produces from a reviewed plan (`v2ExecuteTransactions`), field for field with
+ * `src/lib/v2-launch-plan.ts`'s `buildV2LaunchPlan`. Parity reached, with one deliberate scope
+ * cut, stated here rather than left implicit:
+ *
+ *   - `caps` (the native block's `validateStack` answer — its surcharge and take-bps ceilings)
+ *     and `protocolShareBps` / `protocolRecipient` (the coordinator's and block's own reads for
+ *     this creator) are NOT re-derived here: they are live chain reads in the app
+ *     (`buildV2LaunchPlan` calls `validateStack`, `protocolShareBps`, and reads the block's
+ *     `protocolRecipient()`), and this package does not carry a client of its own. Pass them in
+ *     — read with viem's `readContract` against `abi.ts`'s ABIs — exactly as the app's plan
+ *     builder does before it ever encodes a call.
+ *   - The opening `sqrtPriceX96` (and, on the new-token lane, the founding band) is a caller
+ *     input too. The app derives it from a chosen price via tick math
+ *     (`v2SqrtPriceForOpeningPrice`, `v2FoundingBand`) that depends on Uniswap's `TickMath`
+ *     library; reimplementing and re-verifying that library was out of this pass's time box, so
+ *     it is not duplicated here. Compute it with the app's own `v2-encode.ts` (or an equivalent),
+ *     or read it back from an already-opened pool with `reads.ts`.
+ *   - The dev buy (`initialBuy`) is accepted as an already-priced input, not computed: sizing one
+ *     against the founding band (`src/lib/v2-dev-buy.ts`) is a further, separate pricing
+ *     concern this pass did not reach. Omit it for a plain launch with no creator buy.
+ *
+ * Everything downstream of those three reads — the pool id, the config bytes, the stack limits,
+ * and the final struct-for-struct call — is exact, proven, and the parity test's fixed-input
+ * cases exercise the full assembly with a representative `caps`/`sqrtPriceX96` pair.
+ */
+import { type Address, type Hex } from "viem";
+import { hookrMarketCoordinatorV5Abi } from "./abi.js";
+import { type RuleBlock } from "./rules.js";
+/** `HookrMarketCoordinatorV5.DYNAMIC_FEE_FLAG`: the Uniswap v4 dynamic-fee sentinel in every V2 PoolKey. */
+export declare const DYNAMIC_FEE = 8388608;
+export type PoolKey = Readonly<{
+    currency0: Address;
+    currency1: Address;
+    fee: number;
+    tickSpacing: number;
+    hooks: Address;
+}>;
+/** `subject < quote` by numeric value; ETH (the zero address) is therefore never `currency1`. */
+export declare function subjectIsCurrency0(subject: Address, quote: Address): boolean;
+/**
+ * `HookrMarketCoordinatorV5._poolKey`: currencies sorted numerically, `fee = DYNAMIC_FEE`,
+ * `hooks` the root hook (defaults to `ADDRESSES.root`, the one live root).
+ */
+export declare function poolKeyFor(input: {
+    subject: Address;
+    quote: Address;
+    tickSpacing: number;
+    hooks?: Address;
+}): PoolKey;
+/** `PoolId = keccak256(abi.encode(key))`. */
+export declare function poolIdFor(key: PoolKey): Hex;
+export type NativeConfig = Readonly<{
+    poolId: Hex;
+    kernel: Address;
+    subject: Address;
+    quote: Address;
+    lockedLiquidityProvider: Address;
+    guardEndBlock: bigint;
+    baseFeePips: number;
+    maxFeePips: number;
+    snipeTaxPips: number;
+    surgeSens: number;
+    burnBps: number;
+    lpBps: number;
+    potBps: number;
+    royaltyBps: number;
+    potEveryNBuys: number;
+    maxBuyQuoteAmount: bigint;
+    potMinBuyWei: bigint;
+    royaltyTo: Address;
+    protocolRecipient: Address;
+    protocolShareBps: number;
+}>;
+/** `abi.encode(Config)`: one static tuple, exactly 640 bytes. */
+export declare function encodeNativeBlockConfig(config: NativeConfig): Hex;
+/** `HookrNativeMechanicsBlockV2.MAX_GUARD_BLOCKS`. */
+export declare const MAX_GUARD_BLOCKS = 100000;
+/** `guardEndBlock` for a guard of `guardBlocks` blocks from `contractBlock`; `0n` (off) at or below zero. */
+export declare function guardEndBlockFor(contractBlock: bigint, guardBlocks: number): bigint;
+/** The native block's registered callback gas; `limits.maxTotalModuleGas` in every fixture. */
+export declare const MODULE_GAS = 2000000;
+export declare const ZERO_BYTES32: Hex;
+/** What `HookrNativeMechanicsBlockV2.validateStack` returns for a config: the surcharge and
+ *  take-bps ceilings this creator's stack is admitted at. A live chain read; see the module doc. */
+export type StackCaps = Readonly<{
+    configHash: Hex;
+    maxLpFeeSurchargePips: number;
+    maxSpecifiedQuoteTakeBps: number;
+    maxUnspecifiedQuoteTakeBps: number;
+    maxSubjectTakeBps: number;
+}>;
+export type StackLimits = Readonly<{
+    baseLpFeePips: number;
+    maxLpFeePips: number;
+    maxSpecifiedQuoteTakeBps: number;
+    maxUnspecifiedQuoteTakeBps: number;
+    maxSubjectTakeBps: number;
+    maxTotalModuleGas: number;
+    trustedRouter: Address;
+    trustedQuoter: Address;
+    correctionExecutor: Address;
+    correctionCreator: Address;
+    correctionMaxVolumeBps: number;
+    correctionMinProfitQuote: bigint;
+    correctionFeePolicyId: Hex;
+}>;
+/**
+ * The tightest `StackLimits` the registry admits: equal to the block's own caps, exactly as the
+ * app's `v2StackLimits` sets them. `trustedRouter`/`trustedQuoter` are always `ADDRESSES.router`
+ * / `ADDRESSES.quoter` today — the app's own equivalent takes them as a parameter only so its
+ * tests can fake them; a real launch always wires the same two addresses this package does.
+ */
+export declare function stackLimitsFor(config: NativeConfig, caps: StackCaps): StackLimits;
+export type ModuleSelection = Readonly<{
+    moduleId: Hex;
+    config: Hex;
+}>;
+export type MarketParams = Readonly<{
+    quote: Address;
+    subjectAmount: bigint;
+    quoteAmount: bigint;
+    lpFeeRecipient: Address;
+    tickSpacing: number;
+    sqrtPriceX96: bigint;
+    kernelId: Hex;
+    modules: readonly ModuleSelection[];
+    limits: StackLimits;
+}>;
+export type InitialBuyParams = Readonly<{
+    quoteAmountIn: bigint;
+    subjectAmountOutMinimum: bigint;
+    deadline: bigint;
+    moduleData: Hex;
+}>;
+export type NewTokenArgs = Readonly<{
+    name: string;
+    symbol: string;
+    tagline: string;
+    logoURI: string;
+    expectedCreator: Address;
+    totalSupply: bigint;
+    deploymentSalt: Hex;
+    market: MarketParams;
+    initialBuy: InitialBuyParams;
+}>;
+export type ExistingTokenArgs = Readonly<{
+    subject: Address;
+    market: MarketParams;
+}>;
+/** The rule numbers a market's stack carries, as the builders take them. */
+export type MarketRulesInput = Readonly<{
+    /** The stack's Base LP fee, in pips. */
+    baseFeePips: number;
+    blocks: readonly RuleBlock[];
+    /** Guard length in contract blocks; 0 (default) turns the guard off. New-token lane only. */
+    guardBlocks?: number;
+    /** Per-block max buy in quote raw units while the guard is up. New-token lane only. */
+    maxBuyQuoteAmount?: bigint;
+    royaltyBps?: number;
+    /** Required exactly when `royaltyBps` is nonzero. */
+    royaltyTo?: Address | null;
+}>;
+export type CoordinatorCall<Args extends readonly unknown[]> = Readonly<{
+    address: Address;
+    abi: typeof hookrMarketCoordinatorV5Abi;
+    functionName: "openNewTokenMarket" | "openExistingTokenMarket";
+    args: Args;
+    value: bigint;
+}>;
+/**
+ * Build the exact `openNewTokenMarket` call: pool key/id from `subject` (the previewed token
+ * address — `marketCoordinator.previewNewTokenAddress`) and `quote`, the native config from
+ * `rules`, the one native-mechanics module, and the stack limits from `caps`. `value` is the
+ * dev buy's quote amount for a native-ETH quote, else 0 (the router pulls an ERC-20 dev buy from
+ * an allowance, exactly like the app).
+ */
+export declare function buildNewTokenMarketCall(input: {
+    creator: Address;
+    name: string;
+    symbol: string;
+    tagline: string;
+    logoURI: string;
+    totalSupply: bigint;
+    deploymentSalt: Hex;
+    intentId: Hex;
+    /** The coordinator's previewed token address for this intent; also the market's `subject`. */
+    expectedToken: Address;
+    quote: Address;
+    tickSpacing: number;
+    sqrtPriceX96: bigint;
+    /** Founding-position fee recipient; defaults to `creator`. */
+    lpFeeRecipient?: Address;
+    rules: MarketRulesInput;
+    /** The contract clock's block at build time (`context.contractBlock` in the app); anchors the guard. */
+    contractBlock: bigint;
+    protocolRecipient: Address;
+    protocolShareBps: number;
+    caps: StackCaps;
+    initialBuy?: Readonly<{
+        quoteAmountIn: bigint;
+        subjectAmountOutMinimum: bigint;
+        deadline: bigint;
+        moduleData?: Hex;
+    }>;
+}): CoordinatorCall<readonly [NewTokenArgs, Hex, Address]>;
+/**
+ * Build the exact `openExistingTokenMarket` call. The existing-asset lane carries no guard, no
+ * founding position and no dev buy: `value` is always 0, `lpFeeRecipient` is always the zero
+ * address, and any guard field in `rules` is ignored (zeroed), exactly as the app's plan builder
+ * refuses a guard on this lane rather than silently applying it.
+ */
+export declare function buildExistingTokenMarketCall(input: {
+    subject: Address;
+    quote: Address;
+    tickSpacing: number;
+    sqrtPriceX96: bigint;
+    rules: MarketRulesInput;
+    protocolRecipient: Address;
+    protocolShareBps: number;
+    caps: StackCaps;
+}): CoordinatorCall<readonly [ExistingTokenArgs]>;
+/** The calldata `encodeFunctionData` would produce for a built call, for sending with viem directly. */
+export declare function encodeMarketCall(call: CoordinatorCall<readonly unknown[]>): Hex;

package/dist/market.js

@@ -0,0 +1,289 @@
+/**
+ * Pool key/id, the native block's config encoding, stack limits, and the two coordinator calls
+ * that open a market.
+ *
+ * `poolKeyFor`, `poolIdFor`, the config encoder and `stackLimitsFor` are pure, faithful copies
+ * of `src/lib/v2-encode.ts` in the Hookr app (`v2PoolKey`, `v2PoolId`, `encodeV2Config`,
+ * `v2StackLimits`) — nothing here reads a chain, so `src/test/hookr-sdk-parity.test.ts` proves
+ * them by calling both on the same fixed inputs and asserting byte-for-byte agreement.
+ *
+ * `buildNewTokenMarketCall` and `buildExistingTokenMarketCall` assemble the exact
+ * `openNewTokenMarket` / `openExistingTokenMarket` calldata `src/lib/v2-launch-execute.ts`
+ * produces from a reviewed plan (`v2ExecuteTransactions`), field for field with
+ * `src/lib/v2-launch-plan.ts`'s `buildV2LaunchPlan`. Parity reached, with one deliberate scope
+ * cut, stated here rather than left implicit:
+ *
+ *   - `caps` (the native block's `validateStack` answer — its surcharge and take-bps ceilings)
+ *     and `protocolShareBps` / `protocolRecipient` (the coordinator's and block's own reads for
+ *     this creator) are NOT re-derived here: they are live chain reads in the app
+ *     (`buildV2LaunchPlan` calls `validateStack`, `protocolShareBps`, and reads the block's
+ *     `protocolRecipient()`), and this package does not carry a client of its own. Pass them in
+ *     — read with viem's `readContract` against `abi.ts`'s ABIs — exactly as the app's plan
+ *     builder does before it ever encodes a call.
+ *   - The opening `sqrtPriceX96` (and, on the new-token lane, the founding band) is a caller
+ *     input too. The app derives it from a chosen price via tick math
+ *     (`v2SqrtPriceForOpeningPrice`, `v2FoundingBand`) that depends on Uniswap's `TickMath`
+ *     library; reimplementing and re-verifying that library was out of this pass's time box, so
+ *     it is not duplicated here. Compute it with the app's own `v2-encode.ts` (or an equivalent),
+ *     or read it back from an already-opened pool with `reads.ts`.
+ *   - The dev buy (`initialBuy`) is accepted as an already-priced input, not computed: sizing one
+ *     against the founding band (`src/lib/v2-dev-buy.ts`) is a further, separate pricing
+ *     concern this pass did not reach. Omit it for a plain launch with no creator buy.
+ *
+ * Everything downstream of those three reads — the pool id, the config bytes, the stack limits,
+ * and the final struct-for-struct call — is exact, proven, and the parity test's fixed-input
+ * cases exercise the full assembly with a representative `caps`/`sqrtPriceX96` pair.
+ */
+import { encodeAbiParameters, encodeFunctionData, keccak256 } from "viem";
+import { hookrMarketCoordinatorV5Abi } from "./abi.js";
+import { ADDRESSES, KERNEL_ID, MODULE_ID, NATIVE_ADDRESS } from "./chain.js";
+import { compileRuleBlocks } from "./rules.js";
+// -----------------------------------------------------------------------------------------------
+// Pool key and pool id
+// -----------------------------------------------------------------------------------------------
+/** `HookrMarketCoordinatorV5.DYNAMIC_FEE_FLAG`: the Uniswap v4 dynamic-fee sentinel in every V2 PoolKey. */
+export const DYNAMIC_FEE = 0x800000;
+const POOL_KEY_COMPONENTS = [
+    { name: "currency0", type: "address" },
+    { name: "currency1", type: "address" },
+    { name: "fee", type: "uint24" },
+    { name: "tickSpacing", type: "int24" },
+    { name: "hooks", type: "address" },
+];
+const POOL_KEY_ABI = [{ type: "tuple", components: POOL_KEY_COMPONENTS }];
+/** `subject < quote` by numeric value; ETH (the zero address) is therefore never `currency1`. */
+export function subjectIsCurrency0(subject, quote) {
+    const s = BigInt(subject);
+    const q = BigInt(quote);
+    if (s === q)
+        throw new Error("The subject and the quote are the same currency.");
+    return s < q;
+}
+/**
+ * `HookrMarketCoordinatorV5._poolKey`: currencies sorted numerically, `fee = DYNAMIC_FEE`,
+ * `hooks` the root hook (defaults to `ADDRESSES.root`, the one live root).
+ */
+export function poolKeyFor(input) {
+    const subjectFirst = subjectIsCurrency0(input.subject, input.quote);
+    return Object.freeze({
+        currency0: subjectFirst ? input.subject : input.quote,
+        currency1: subjectFirst ? input.quote : input.subject,
+        fee: DYNAMIC_FEE,
+        tickSpacing: input.tickSpacing,
+        hooks: input.hooks ?? ADDRESSES.root,
+    });
+}
+/** `PoolId = keccak256(abi.encode(key))`. */
+export function poolIdFor(key) {
+    return keccak256(encodeAbiParameters(POOL_KEY_ABI, [key]));
+}
+// -----------------------------------------------------------------------------------------------
+// HookrNativeMechanicsBlockV2.Config
+// -----------------------------------------------------------------------------------------------
+/** The 20 fields of `HookrNativeMechanicsBlockV2.Config`, in the struct's own order. */
+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 }];
+/** `abi.encode(Config)`: one static tuple, exactly 640 bytes. */
+export function encodeNativeBlockConfig(config) {
+    return encodeAbiParameters(CONFIG_ABI, [{ ...config, guardEndBlock: Number(config.guardEndBlock) }]);
+}
+/** `HookrNativeMechanicsBlockV2.MAX_GUARD_BLOCKS`. */
+export const MAX_GUARD_BLOCKS = 100_000;
+/** `guardEndBlock` for a guard of `guardBlocks` blocks from `contractBlock`; `0n` (off) at or below zero. */
+export function guardEndBlockFor(contractBlock, guardBlocks) {
+    if (guardBlocks <= 0)
+        return 0n;
+    return contractBlock + BigInt(Math.min(Math.round(guardBlocks), MAX_GUARD_BLOCKS));
+}
+// -----------------------------------------------------------------------------------------------
+// Stack limits
+// -----------------------------------------------------------------------------------------------
+/** The native block's registered callback gas; `limits.maxTotalModuleGas` in every fixture. */
+export const MODULE_GAS = 2_000_000;
+export const ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * The tightest `StackLimits` the registry admits: equal to the block's own caps, exactly as the
+ * app's `v2StackLimits` sets them. `trustedRouter`/`trustedQuoter` are always `ADDRESSES.router`
+ * / `ADDRESSES.quoter` today — the app's own equivalent takes them as a parameter only so its
+ * tests can fake them; a real launch always wires the same two addresses this package does.
+ */
+export function stackLimitsFor(config, caps) {
+    return Object.freeze({
+        baseLpFeePips: config.baseFeePips,
+        maxLpFeePips: config.baseFeePips + caps.maxLpFeeSurchargePips,
+        maxSpecifiedQuoteTakeBps: caps.maxSpecifiedQuoteTakeBps,
+        maxUnspecifiedQuoteTakeBps: caps.maxUnspecifiedQuoteTakeBps,
+        maxSubjectTakeBps: caps.maxSubjectTakeBps,
+        maxTotalModuleGas: MODULE_GAS,
+        trustedRouter: ADDRESSES.router,
+        trustedQuoter: ADDRESSES.quoter,
+        correctionExecutor: NATIVE_ADDRESS,
+        correctionCreator: NATIVE_ADDRESS,
+        correctionMaxVolumeBps: 0,
+        correctionMinProfitQuote: 0n,
+        correctionFeePolicyId: ZERO_BYTES32,
+    });
+}
+const NO_INITIAL_BUY = Object.freeze({
+    quoteAmountIn: 0n,
+    subjectAmountOutMinimum: 0n,
+    deadline: 0n,
+    moduleData: "0x",
+});
+function buildNativeConfig(input) {
+    const { lane, rules } = input;
+    const compiled = compileRuleBlocks(rules.blocks, rules.baseFeePips);
+    const guardOn = lane === "new" && (rules.guardBlocks ?? 0) > 0;
+    return Object.freeze({
+        poolId: input.poolId,
+        kernel: ADDRESSES.root,
+        subject: input.subject,
+        quote: input.quote,
+        lockedLiquidityProvider: guardOn ? ADDRESSES.coordinator : NATIVE_ADDRESS,
+        guardEndBlock: guardOn ? guardEndBlockFor(input.contractBlock, compiled.guardBlocks) : 0n,
+        baseFeePips: compiled.baseFeePips,
+        maxFeePips: compiled.maxFeePips,
+        snipeTaxPips: lane === "new" ? compiled.snipeTaxPips : 0,
+        surgeSens: compiled.surgeSens,
+        burnBps: compiled.burnBps,
+        lpBps: compiled.lpBps,
+        potBps: compiled.potBps,
+        royaltyBps: rules.royaltyBps ?? 0,
+        potEveryNBuys: compiled.potEveryNBuys,
+        maxBuyQuoteAmount: lane === "new" ? rules.maxBuyQuoteAmount ?? 0n : 0n,
+        potMinBuyWei: compiled.potMinBuyWei,
+        royaltyTo: rules.royaltyTo ?? NATIVE_ADDRESS,
+        protocolRecipient: input.protocolRecipient,
+        protocolShareBps: input.protocolShareBps,
+    });
+}
+/**
+ * Build the exact `openNewTokenMarket` call: pool key/id from `subject` (the previewed token
+ * address — `marketCoordinator.previewNewTokenAddress`) and `quote`, the native config from
+ * `rules`, the one native-mechanics module, and the stack limits from `caps`. `value` is the
+ * dev buy's quote amount for a native-ETH quote, else 0 (the router pulls an ERC-20 dev buy from
+ * an allowance, exactly like the app).
+ */
+export function buildNewTokenMarketCall(input) {
+    const subject = input.expectedToken;
+    const poolId = poolIdFor(poolKeyFor({ subject, quote: input.quote, tickSpacing: input.tickSpacing }));
+    const config = buildNativeConfig({
+        lane: "new",
+        rules: input.rules,
+        poolId,
+        subject,
+        quote: input.quote,
+        contractBlock: input.contractBlock,
+        protocolRecipient: input.protocolRecipient,
+        protocolShareBps: input.protocolShareBps,
+    });
+    const encodedConfig = encodeNativeBlockConfig(config);
+    const limits = stackLimitsFor(config, input.caps);
+    const market = {
+        quote: input.quote,
+        subjectAmount: input.totalSupply,
+        quoteAmount: 0n,
+        lpFeeRecipient: input.lpFeeRecipient ?? input.creator,
+        tickSpacing: input.tickSpacing,
+        sqrtPriceX96: input.sqrtPriceX96,
+        kernelId: KERNEL_ID,
+        modules: [{ moduleId: MODULE_ID, config: encodedConfig }],
+        limits,
+    };
+    const initialBuy = input.initialBuy
+        ? {
+            quoteAmountIn: input.initialBuy.quoteAmountIn,
+            subjectAmountOutMinimum: input.initialBuy.subjectAmountOutMinimum,
+            deadline: input.initialBuy.deadline,
+            moduleData: input.initialBuy.moduleData ?? "0x",
+        }
+        : NO_INITIAL_BUY;
+    const args = {
+        name: input.name,
+        symbol: input.symbol,
+        tagline: input.tagline,
+        logoURI: input.logoURI,
+        expectedCreator: input.creator,
+        totalSupply: input.totalSupply,
+        deploymentSalt: input.deploymentSalt,
+        market,
+        initialBuy,
+    };
+    const value = input.quote === NATIVE_ADDRESS ? initialBuy.quoteAmountIn : 0n;
+    return Object.freeze({
+        address: ADDRESSES.coordinator,
+        abi: hookrMarketCoordinatorV5Abi,
+        functionName: "openNewTokenMarket",
+        args: [args, input.intentId, input.expectedToken],
+        value,
+    });
+}
+/**
+ * Build the exact `openExistingTokenMarket` call. The existing-asset lane carries no guard, no
+ * founding position and no dev buy: `value` is always 0, `lpFeeRecipient` is always the zero
+ * address, and any guard field in `rules` is ignored (zeroed), exactly as the app's plan builder
+ * refuses a guard on this lane rather than silently applying it.
+ */
+export function buildExistingTokenMarketCall(input) {
+    const poolId = poolIdFor(poolKeyFor({ subject: input.subject, quote: input.quote, tickSpacing: input.tickSpacing }));
+    const config = buildNativeConfig({
+        lane: "existing",
+        rules: input.rules,
+        poolId,
+        subject: input.subject,
+        quote: input.quote,
+        contractBlock: 0n,
+        protocolRecipient: input.protocolRecipient,
+        protocolShareBps: input.protocolShareBps,
+    });
+    const encodedConfig = encodeNativeBlockConfig(config);
+    const limits = stackLimitsFor(config, input.caps);
+    const market = {
+        quote: input.quote,
+        subjectAmount: 0n,
+        quoteAmount: 0n,
+        lpFeeRecipient: NATIVE_ADDRESS,
+        tickSpacing: input.tickSpacing,
+        sqrtPriceX96: input.sqrtPriceX96,
+        kernelId: KERNEL_ID,
+        modules: [{ moduleId: MODULE_ID, config: encodedConfig }],
+        limits,
+    };
+    const args = { subject: input.subject, market };
+    return Object.freeze({
+        address: ADDRESSES.coordinator,
+        abi: hookrMarketCoordinatorV5Abi,
+        functionName: "openExistingTokenMarket",
+        args: [args],
+        value: 0n,
+    });
+}
+/** The calldata `encodeFunctionData` would produce for a built call, for sending with viem directly. */
+export function encodeMarketCall(call) {
+    return encodeFunctionData({
+        abi: call.abi,
+        functionName: call.functionName,
+        args: call.args,
+    });
+}

package/dist/reads.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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;
+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.
+ *
+ * `root`, when given, is checked against every row's `kernel` rather than passed to the log
+ * filter: `kernel` is not an indexed topic, and there is exactly one live root today
+ * (`ADDRESSES.root`), so every row already carries it. A future second root would need a
+ * client-side filter here, which is exactly what this parameter is for.
+ */
+export declare function listMarkets(client: PublicClient, options?: Readonly<{
+    root?: Address;
+    fromBlock?: bigint;
+    toBlock?: 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>;