boing-sdk 0.3.0

package/dist/nativeAmmPool.js

@@ -0,0 +1,245 @@
+/**
+ * Native constant-product pool — `contract_call` + access list for Boing Express / JSON-RPC.
+ * Matches `Transaction::suggested_parallel_access_list` for `ContractCall` when only sender + pool touch state.
+ *
+ * Storage layout matches `boing_execution::native_amm`:
+ * reserves (`reserve_a_key` / `reserve_b_key`), total LP (`total_lp_supply_key`), per-signer LP (`lp_balance_storage_key`);
+ * **v3/v4:** `swap_fee_bps_key` (`k[31] == 0x07`).
+ * Amounts are u128 BE in the **low 16 bytes** of each 32-byte word.
+ */
+import { mergeAccessListWithSimulation } from './accessList.js';
+import { ensureHex, validateHex32 } from './hex.js';
+const HEX_RE = /^[0-9a-fA-F]+$/;
+function normalizeCalldataHex(calldataHex) {
+    const h = ensureHex(calldataHex.trim());
+    const raw = h.slice(2);
+    if (raw.length % 2 !== 0) {
+        throw new Error('calldata must be even-length hex');
+    }
+    if (!HEX_RE.test(raw)) {
+        throw new Error('calldata: invalid hex');
+    }
+    return `0x${raw.toLowerCase()}`;
+}
+/** `read` and `write` both include signer + pool (parallel-scheduling minimum for pool-only bytecode). */
+export function buildNativeConstantProductPoolAccessList(senderHex32, poolHex32, options) {
+    const s = validateHex32(senderHex32).toLowerCase();
+    const p = validateHex32(poolHex32).toLowerCase();
+    const extra = options?.additionalAccountsHex32 ?? [];
+    if (extra.length === 0) {
+        return { read: [s, p], write: [s, p] };
+    }
+    const seen = new Set([s, p]);
+    const sortedExtras = [];
+    for (const x of extra) {
+        const h = validateHex32(x).toLowerCase();
+        if (!seen.has(h)) {
+            seen.add(h);
+            sortedExtras.push(h);
+        }
+    }
+    sortedExtras.sort();
+    const combined = [s, p, ...sortedExtras];
+    return { read: combined, write: [...combined] };
+}
+/** Params for `boing_sendTransaction` / Express `contract_call` with explicit access list. */
+export function buildNativeConstantProductContractCallTx(senderHex32, poolHex32, calldataHex, options) {
+    return {
+        type: 'contract_call',
+        contract: validateHex32(poolHex32).toLowerCase(),
+        calldata: normalizeCalldataHex(calldataHex),
+        access_list: buildNativeConstantProductPoolAccessList(senderHex32, poolHex32, options),
+    };
+}
+/**
+ * Access list for **`contract_call`** into the native **multihop router**: signer, router, each pool in path order (deduped), then sorted extras (e.g. reference tokens).
+ */
+export function buildNativeDexMultihopRouterAccessList(senderHex32, routerHex32, poolHex32List, options) {
+    const s = validateHex32(senderHex32).toLowerCase();
+    const r = validateHex32(routerHex32).toLowerCase();
+    const seen = new Set([s, r]);
+    const ordered = [s, r];
+    for (const pool of poolHex32List) {
+        const p = validateHex32(pool).toLowerCase();
+        if (!seen.has(p)) {
+            seen.add(p);
+            ordered.push(p);
+        }
+    }
+    const extra = options?.additionalAccountsHex32 ?? [];
+    const sortedExtras = [];
+    for (const x of extra) {
+        const h = validateHex32(x).toLowerCase();
+        if (!seen.has(h)) {
+            seen.add(h);
+            sortedExtras.push(h);
+        }
+    }
+    sortedExtras.sort();
+    const combined = [...ordered, ...sortedExtras];
+    return { read: combined, write: [...combined] };
+}
+/** Multihop router **`contract_call`** with {@link buildNativeDexMultihopRouterAccessList}. */
+export function buildNativeDexMultihopRouterContractCallTx(senderHex32, routerHex32, calldataHex, poolHex32List, options) {
+    return {
+        type: 'contract_call',
+        contract: validateHex32(routerHex32).toLowerCase(),
+        calldata: normalizeCalldataHex(calldataHex),
+        access_list: buildNativeDexMultihopRouterAccessList(senderHex32, routerHex32, poolHex32List, options),
+    };
+}
+/**
+ * Widen multihop router access list with `sim.suggested_access_list` (e.g. after `boing_simulateTransaction`).
+ */
+export function mergeNativeDexMultihopRouterAccessListWithSimulation(senderHex32, routerHex32, poolHex32List, sim, options) {
+    const base = buildNativeDexMultihopRouterAccessList(senderHex32, routerHex32, poolHex32List, options);
+    return mergeAccessListWithSimulation(base.read, base.write, sim);
+}
+/**
+ * Widen `read`/`write` with `sim.suggested_access_list` (e.g. after `boing_simulateTransaction`).
+ */
+export function mergeNativePoolAccessListWithSimulation(senderHex32, poolHex32, sim, options) {
+    const base = buildNativeConstantProductPoolAccessList(senderHex32, poolHex32, options);
+    return mergeAccessListWithSimulation(base.read, base.write, sim);
+}
+/** `boing_getContractStorage` key for reserve A (`native_amm::reserve_a_key`). */
+export const NATIVE_CONSTANT_PRODUCT_RESERVE_A_KEY_HEX = `0x${'00'.repeat(31)}01`;
+/** `boing_getContractStorage` key for reserve B (`native_amm::reserve_b_key`). */
+export const NATIVE_CONSTANT_PRODUCT_RESERVE_B_KEY_HEX = `0x${'00'.repeat(31)}02`;
+/** Total LP supply key (`native_amm::total_lp_supply_key`, `k[31] == 0x03`). */
+export const NATIVE_CONSTANT_PRODUCT_TOTAL_LP_KEY_HEX = `0x${'00'.repeat(31)}03`;
+/** **v2:** On-chain reference-token id for reserve side A (`token_a_key`, `k[31] == 0x04`). */
+export const NATIVE_CONSTANT_PRODUCT_TOKEN_A_KEY_HEX = `0x${'00'.repeat(31)}04`;
+/** **v2:** Reference-token id for side B (`k[31] == 0x05`). */
+export const NATIVE_CONSTANT_PRODUCT_TOKEN_B_KEY_HEX = `0x${'00'.repeat(31)}05`;
+/** **v2:** Non-zero after successful `set_tokens` (`k[31] == 0x06`). */
+export const NATIVE_CONSTANT_PRODUCT_TOKENS_CONFIGURED_KEY_HEX = `0x${'00'.repeat(31)}06`;
+/** **v3/v4:** Swap fee bps on output (`swap_fee_bps_key`, `k[31] == 0x07`). **`0`** = unset until first `add_liquidity` (then defaults to **`NATIVE_CP_SWAP_FEE_BPS`** on-chain). */
+export const NATIVE_CONSTANT_PRODUCT_SWAP_FEE_BPS_KEY_HEX = `0x${'00'.repeat(31)}07`;
+const LP_BALANCE_XOR_U8 = (() => {
+    const u8 = new Uint8Array(32);
+    u8.set(new TextEncoder().encode('BOING_NATIVEAMM_LPRV1'));
+    return u8;
+})();
+/**
+ * `boing_getContractStorage` key for the caller's LP balance (`native_amm::lp_balance_storage_key`).
+ */
+export function nativeAmmLpBalanceStorageKeyHex(senderHex32) {
+    const raw = validateHex32(senderHex32).slice(2).toLowerCase();
+    let out = '';
+    for (let i = 0; i < 32; i++) {
+        const b = parseInt(raw.slice(i * 2, i * 2 + 2), 16) ^ LP_BALANCE_XOR_U8[i];
+        out += b.toString(16).padStart(2, '0');
+    }
+    return `0x${out}`;
+}
+/**
+ * Decode **u128** from a 32-byte Boing contract storage word (`value` from `boing_getContractStorage`):
+ * big-endian integer in the **low 16 bytes** (high 16 bytes ignored), matching reference-token amount words.
+ */
+export function decodeBoingStorageWordU128(valueHex) {
+    const raw = ensureHex(valueHex).slice(2).toLowerCase();
+    if (raw.length === 0)
+        return 0n;
+    if (raw.length % 2 !== 0) {
+        throw new Error('storage word: hex length must be even');
+    }
+    if (!HEX_RE.test(raw)) {
+        throw new Error('storage word: invalid hex');
+    }
+    const word64 = raw.length > 64 ? raw.slice(-64) : raw.padStart(64, '0');
+    const low16BytesHex = word64.slice(32);
+    return BigInt(`0x${low16BytesHex}`);
+}
+/**
+ * Decode successful native pool **`add_liquidity`** contract return data: **exactly 32 bytes** (64 hex
+ * chars), **u128** LP minted in the **low 16 bytes**; high 16 bytes must be zero (canonical amount word).
+ */
+export function decodeNativeAmmAddLiquidityReturnLpMinted(returnDataHex) {
+    const raw = ensureHex(returnDataHex).slice(2).toLowerCase();
+    if (raw.length % 2 !== 0) {
+        throw new Error('add_liquidity return: hex length must be even');
+    }
+    if (raw.length !== 64) {
+        throw new Error('add_liquidity return: expected exactly 32 bytes (64 hex chars)');
+    }
+    if (!HEX_RE.test(raw)) {
+        throw new Error('add_liquidity return: invalid hex');
+    }
+    if (!raw.slice(0, 32).match(/^0+$/)) {
+        throw new Error('add_liquidity return: high 16 bytes must be zero');
+    }
+    return decodeBoingStorageWordU128(`0x${raw}`);
+}
+/**
+ * Decode native AMM `Log2` **data** (96 bytes): three u128 words (low 16 bytes of each 32-byte word), per `NATIVE-AMM-CALLDATA.md` § Logs.
+ */
+export function decodeNativeAmmLogDataU128Triple(dataHex) {
+    const raw = ensureHex(dataHex).slice(2).toLowerCase();
+    if (!HEX_RE.test(raw)) {
+        throw new Error('native AMM log data: invalid hex');
+    }
+    if (raw.length < 192) {
+        throw new Error('native AMM log data: expected at least 96 bytes (192 hex chars)');
+    }
+    const w = (start) => decodeBoingStorageWordU128(`0x${raw.slice(start, start + 64)}`);
+    return [w(0), w(64), w(128)];
+}
+/**
+ * Read both in-ledger reserves for the MVP constant-product pool (`Promise.all` of two storage reads).
+ */
+export async function fetchNativeConstantProductReserves(client, poolHex32) {
+    const pool = validateHex32(poolHex32);
+    const [wa, wb] = await Promise.all([
+        client.getContractStorage(pool, NATIVE_CONSTANT_PRODUCT_RESERVE_A_KEY_HEX),
+        client.getContractStorage(pool, NATIVE_CONSTANT_PRODUCT_RESERVE_B_KEY_HEX),
+    ]);
+    return {
+        reserveA: decodeBoingStorageWordU128(wa.value),
+        reserveB: decodeBoingStorageWordU128(wb.value),
+    };
+}
+/** Single `boing_getContractStorage` read for **`total_lp_supply_key`**. */
+export async function fetchNativeConstantProductTotalLpSupply(client, poolHex32) {
+    const pool = validateHex32(poolHex32);
+    const w = await client.getContractStorage(pool, NATIVE_CONSTANT_PRODUCT_TOTAL_LP_KEY_HEX);
+    return decodeBoingStorageWordU128(w.value);
+}
+/** **v3/v4:** Raw u128 at **`swap_fee_bps_key`**. Use **`0n`** → default fee **`NATIVE_CP_SWAP_FEE_BPS`** when quoting swaps. */
+export async function fetchNativeConstantProductSwapFeeBps(client, poolHex32) {
+    const pool = validateHex32(poolHex32);
+    const w = await client.getContractStorage(pool, NATIVE_CONSTANT_PRODUCT_SWAP_FEE_BPS_KEY_HEX);
+    return decodeBoingStorageWordU128(w.value);
+}
+/** LP balance for **`signerHex32`** in **`poolHex32`** (XOR-derived storage key). */
+export async function fetchNativeAmmSignerLpBalance(client, poolHex32, signerHex32) {
+    const pool = validateHex32(poolHex32);
+    const key = nativeAmmLpBalanceStorageKeyHex(signerHex32);
+    const w = await client.getContractStorage(pool, key);
+    return decodeBoingStorageWordU128(w.value);
+}
+/**
+ * One round-trip batch: reserves + total LP, and optionally the given signer's LP balance (**3** or **4** parallel storage reads).
+ */
+export async function fetchNativeConstantProductPoolSnapshot(client, poolHex32, options) {
+    const pool = validateHex32(poolHex32);
+    const signer = options?.signerHex32?.trim();
+    const reads = [
+        client.getContractStorage(pool, NATIVE_CONSTANT_PRODUCT_RESERVE_A_KEY_HEX),
+        client.getContractStorage(pool, NATIVE_CONSTANT_PRODUCT_RESERVE_B_KEY_HEX),
+        client.getContractStorage(pool, NATIVE_CONSTANT_PRODUCT_TOTAL_LP_KEY_HEX),
+    ];
+    if (signer) {
+        reads.push(client.getContractStorage(pool, nativeAmmLpBalanceStorageKeyHex(signer)));
+    }
+    const out = await Promise.all(reads);
+    const snap = {
+        reserveA: decodeBoingStorageWordU128(out[0].value),
+        reserveB: decodeBoingStorageWordU128(out[1].value),
+        totalLpSupply: decodeBoingStorageWordU128(out[2].value),
+    };
+    if (signer && out[3]) {
+        snap.signerLpBalance = decodeBoingStorageWordU128(out[3].value);
+    }
+    return snap;
+}

package/dist/nativeContractSubmit.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Thin ergonomic wrapper around `submitContractCallWithSimulationRetry` for a fixed contract + signer.
+ */
+import type { BoingClient } from './client.js';
+import { type SubmitContractCallWithSimulationOptions, type SubmitFlowResult } from './submitFlow.js';
+import type { Ed25519SecretKey32 } from './transactionBuilder.js';
+export interface NativeContractSubmitterConfig {
+    client: BoingClient;
+    secretKey32: Ed25519SecretKey32;
+    senderHex: string;
+    contractHex: string;
+    /** Default access list for calls (signer + contract is typical). */
+    accessList?: {
+        read: string[];
+        write: string[];
+    };
+    maxSimulationRetries?: number;
+}
+/**
+ * Factory for repeated `ContractCall` submits to one contract with shared signer/client options.
+ */
+export declare function createNativeContractSubmitter(config: NativeContractSubmitterConfig): {
+    /** Submit arbitrary calldata with simulate → access-list retry → submit. */
+    submitCalldata(calldata: Uint8Array, overrides?: Pick<SubmitContractCallWithSimulationOptions, "accessList" | "maxSimulationRetries">): Promise<SubmitFlowResult>;
+};
+//# sourceMappingURL=nativeContractSubmit.d.ts.map

package/dist/nativeContractSubmit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeContractSubmit.d.ts","sourceRoot":"","sources":["../src/nativeContractSubmit.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAEL,KAAK,uCAAuC,EAC5C,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,kBAAkB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACjD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,6BAA6B;IAE/E,4EAA4E;6BAEhE,UAAU,cACR,IAAI,CACd,uCAAuC,EACvC,YAAY,GAAG,sBAAsB,CACtC,GACA,OAAO,CAAC,gBAAgB,CAAC;EAY/B"}

package/dist/nativeContractSubmit.js

@@ -0,0 +1,23 @@
+/**
+ * Thin ergonomic wrapper around `submitContractCallWithSimulationRetry` for a fixed contract + signer.
+ */
+import { submitContractCallWithSimulationRetry, } from './submitFlow.js';
+/**
+ * Factory for repeated `ContractCall` submits to one contract with shared signer/client options.
+ */
+export function createNativeContractSubmitter(config) {
+    return {
+        /** Submit arbitrary calldata with simulate → access-list retry → submit. */
+        async submitCalldata(calldata, overrides) {
+            return submitContractCallWithSimulationRetry({
+                client: config.client,
+                secretKey32: config.secretKey32,
+                senderHex: config.senderHex,
+                contractHex: config.contractHex,
+                calldata,
+                accessList: overrides?.accessList ?? config.accessList,
+                maxSimulationRetries: overrides?.maxSimulationRetries ?? config.maxSimulationRetries,
+            });
+        },
+    };
+}

package/dist/nativeDexDirectory.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Native DEX pair directory — single Boing RPC surface (no external chains).
+ *
+ * Composes {@link fetchNativeDexIntegrationDefaults}, factory storage reads, and optional
+ * **`register_pair`** log backfill into one snapshot; helpers resolve **`(tokenA, tokenB)` → pool**.
+ */
+import type { BoingClient } from './client.js';
+import { type NativeDexIntegrationDefaults, type NativeDexIntegrationOverrides } from './dexIntegration.js';
+import { type FindNativeDexFactoryPoolOptions } from './nativeDexFactoryPool.js';
+import type { NativeDexFactoryRegisterRpcParsed } from './nativeDexFactoryLogs.js';
+/** Snapshot of operator hints + on-chain directory state (Boing RPC only). */
+export type NativeDexDirectorySnapshot = {
+    chainId: number | null;
+    headHeight: number;
+    defaults: NativeDexIntegrationDefaults;
+    /** Factory storage **`pairs_count`** when factory address is known; otherwise **`null`**. */
+    pairsCount: bigint | null;
+    /**
+     * Parsed **`register_pair`** logs when {@link FetchNativeDexDirectorySnapshotOptions.registerLogs} was set
+     * and a factory address was resolved; otherwise **`null`** (not fetched).
+     */
+    registerLogs: NativeDexFactoryRegisterRpcParsed[] | null;
+};
+export type FetchNativeDexDirectorySnapshotOptions = {
+    overrides?: NativeDexIntegrationOverrides;
+    /**
+     * Inclusive block range for **`boing_getLogs`** (**`register_pair`** on the factory).
+     * **`toBlock`** defaults to the chain head from the same **`getNetworkInfo`** snapshot.
+     */
+    registerLogs?: {
+        fromBlock: number;
+        toBlock?: number;
+    };
+};
+/**
+ * Plan the next inclusive **`register_pair`** log scan for an indexer (Boing RPC only).
+ * Returns **`null`** when already caught up (**`lastScannedBlockInclusive` ≥ `headHeight`**).
+ */
+export declare function suggestNativeDexRegisterLogCatchUpRange(opts: {
+    headHeight: number;
+    lastScannedBlockInclusive: number | null;
+}): {
+    fromBlock: number;
+    toBlock: number;
+} | null;
+/** Canonical map key for an unordered token pair (lowercased **32-byte** hex ids). */
+export declare function nativeDexPairKey(tokenAHex32: string, tokenBHex32: string): string;
+/**
+ * Build **`pairKey → poolHex`** from register logs. Later log entries win (on-chain re-register / ordering).
+ */
+export declare function buildNativeDexRegisterLogPoolIndex(logs: readonly NativeDexFactoryRegisterRpcParsed[]): ReadonlyMap<string, `0x${string}`>;
+/** Resolve pool for **`(tokenA, tokenB)`** in either order using a register-log index. */
+export declare function pickNativeDexPoolFromRegisterLogs(logs: readonly NativeDexFactoryRegisterRpcParsed[], tokenAHex32: string, tokenBHex32: string): `0x${string}` | null;
+/**
+ * Fetch network hints, optional factory pair count, and optional **`register_pair`** logs — **Boing RPC only**.
+ */
+export declare function fetchNativeDexDirectorySnapshot(client: BoingClient, options?: FetchNativeDexDirectorySnapshotOptions): Promise<NativeDexDirectorySnapshot>;
+export type ResolveNativeDexPoolForTokensResult = {
+    poolHex: `0x${string}` | null;
+    factoryHex: `0x${string}` | null;
+    via: 'logs' | 'simulate' | 'none';
+};
+export type ResolveNativeDexPoolForTokensOptions = {
+    kind: 'logs';
+    overrides?: NativeDexIntegrationOverrides;
+    fromBlock: number;
+    toBlock?: number;
+} | {
+    kind: 'simulate';
+    overrides?: NativeDexIntegrationOverrides;
+    find: FindNativeDexFactoryPoolOptions;
+} | {
+    kind: 'auto';
+    overrides?: NativeDexIntegrationOverrides;
+    fromBlock: number;
+    toBlock?: number;
+    find: FindNativeDexFactoryPoolOptions;
+};
+/**
+ * Resolve **`tokenA` / `tokenB` → pool** using logs and/or directory simulation (**Boing-only**).
+ */
+export declare function resolveNativeDexPoolForTokens(client: BoingClient, tokenAHex32: string, tokenBHex32: string, options: ResolveNativeDexPoolForTokensOptions): Promise<ResolveNativeDexPoolForTokensResult>;
+//# sourceMappingURL=nativeDexDirectory.d.ts.map

package/dist/nativeDexDirectory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeDexDirectory.d.ts","sourceRoot":"","sources":["../src/nativeDexDirectory.ts"],"names":[],"mappings":"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"}

package/dist/nativeDexDirectory.js

@@ -0,0 +1,147 @@
+/**
+ * Native DEX pair directory — single Boing RPC surface (no external chains).
+ *
+ * Composes {@link fetchNativeDexIntegrationDefaults}, factory storage reads, and optional
+ * **`register_pair`** log backfill into one snapshot; helpers resolve **`(tokenA, tokenB)` → pool**.
+ */
+import { fetchNativeDexFactoryRegisterLogs, fetchNativeDexIntegrationDefaults, mergeNativeDexIntegrationDefaults, } from './dexIntegration.js';
+import { validateHex32 } from './hex.js';
+import { fetchNativeDexFactoryPairsCount, findNativeDexFactoryPoolByTokens, } from './nativeDexFactoryPool.js';
+function clampBlock(n, lo, hi) {
+    if (n < lo)
+        return lo;
+    if (n > hi)
+        return hi;
+    return n;
+}
+/**
+ * Plan the next inclusive **`register_pair`** log scan for an indexer (Boing RPC only).
+ * Returns **`null`** when already caught up (**`lastScannedBlockInclusive` ≥ `headHeight`**).
+ */
+export function suggestNativeDexRegisterLogCatchUpRange(opts) {
+    if (!Number.isInteger(opts.headHeight) || opts.headHeight < 0) {
+        throw new RangeError('headHeight must be a non-negative integer');
+    }
+    if (opts.lastScannedBlockInclusive != null) {
+        if (!Number.isInteger(opts.lastScannedBlockInclusive) || opts.lastScannedBlockInclusive < -1) {
+            throw new RangeError('lastScannedBlockInclusive must be null or an integer >= -1');
+        }
+    }
+    if (opts.lastScannedBlockInclusive == null || opts.lastScannedBlockInclusive < 0) {
+        return { fromBlock: 0, toBlock: opts.headHeight };
+    }
+    const next = opts.lastScannedBlockInclusive + 1;
+    if (next > opts.headHeight)
+        return null;
+    return { fromBlock: next, toBlock: opts.headHeight };
+}
+/** Canonical map key for an unordered token pair (lowercased **32-byte** hex ids). */
+export function nativeDexPairKey(tokenAHex32, tokenBHex32) {
+    const a = validateHex32(tokenAHex32).toLowerCase();
+    const b = validateHex32(tokenBHex32).toLowerCase();
+    return a < b ? `${a}:${b}` : `${b}:${a}`;
+}
+/**
+ * Build **`pairKey → poolHex`** from register logs. Later log entries win (on-chain re-register / ordering).
+ */
+export function buildNativeDexRegisterLogPoolIndex(logs) {
+    const m = new Map();
+    for (const row of logs) {
+        const k = nativeDexPairKey(row.tokenAHex, row.tokenBHex);
+        m.set(k, validateHex32(row.poolHex));
+    }
+    return m;
+}
+/** Resolve pool for **`(tokenA, tokenB)`** in either order using a register-log index. */
+export function pickNativeDexPoolFromRegisterLogs(logs, tokenAHex32, tokenBHex32) {
+    const idx = buildNativeDexRegisterLogPoolIndex(logs);
+    return idx.get(nativeDexPairKey(tokenAHex32, tokenBHex32)) ?? null;
+}
+/**
+ * Fetch network hints, optional factory pair count, and optional **`register_pair`** logs — **Boing RPC only**.
+ */
+export async function fetchNativeDexDirectorySnapshot(client, options) {
+    const info = await client.getNetworkInfo();
+    const headHeight = info.head_height;
+    const defaults = mergeNativeDexIntegrationDefaults(info, options?.overrides);
+    const factoryHex = defaults.nativeDexFactoryAccountHex;
+    let pairsCount = null;
+    if (factoryHex != null) {
+        pairsCount = await fetchNativeDexFactoryPairsCount(client, factoryHex);
+    }
+    let registerLogs = null;
+    const rl = options?.registerLogs;
+    if (rl != null && factoryHex != null) {
+        const fromBlock = rl.fromBlock;
+        const toBlock = clampBlock(rl.toBlock ?? headHeight, 0, headHeight);
+        if (fromBlock <= toBlock) {
+            registerLogs = await fetchNativeDexFactoryRegisterLogs(client, {
+                factoryAccountHex: factoryHex,
+                fromBlock,
+                toBlock,
+            });
+        }
+        else {
+            registerLogs = [];
+        }
+    }
+    return {
+        chainId: info.chain_id ?? null,
+        headHeight,
+        defaults,
+        pairsCount,
+        registerLogs,
+    };
+}
+/**
+ * Resolve **`tokenA` / `tokenB` → pool** using logs and/or directory simulation (**Boing-only**).
+ */
+export async function resolveNativeDexPoolForTokens(client, tokenAHex32, tokenBHex32, options) {
+    switch (options.kind) {
+        case 'logs': {
+            const snap = await fetchNativeDexDirectorySnapshot(client, {
+                overrides: options.overrides,
+                registerLogs: { fromBlock: options.fromBlock, toBlock: options.toBlock },
+            });
+            const fac = snap.defaults.nativeDexFactoryAccountHex;
+            if (fac == null || snap.registerLogs == null) {
+                return { poolHex: null, factoryHex: fac, via: 'none' };
+            }
+            const poolHex = pickNativeDexPoolFromRegisterLogs(snap.registerLogs, tokenAHex32, tokenBHex32);
+            return { poolHex, factoryHex: fac, via: poolHex != null ? 'logs' : 'none' };
+        }
+        case 'simulate': {
+            const d = await fetchNativeDexIntegrationDefaults(client, options.overrides);
+            const fac = d.nativeDexFactoryAccountHex;
+            if (fac == null) {
+                return { poolHex: null, factoryHex: null, via: 'none' };
+            }
+            const poolHexRaw = await findNativeDexFactoryPoolByTokens(client, fac, tokenAHex32, tokenBHex32, options.find);
+            const poolHex = poolHexRaw != null ? validateHex32(poolHexRaw) : null;
+            return { poolHex, factoryHex: fac, via: poolHex != null ? 'simulate' : 'none' };
+        }
+        case 'auto': {
+            const snap = await fetchNativeDexDirectorySnapshot(client, {
+                overrides: options.overrides,
+                registerLogs: { fromBlock: options.fromBlock, toBlock: options.toBlock },
+            });
+            const fac = snap.defaults.nativeDexFactoryAccountHex;
+            if (fac == null) {
+                return { poolHex: null, factoryHex: null, via: 'none' };
+            }
+            if (snap.registerLogs != null) {
+                const fromLogs = pickNativeDexPoolFromRegisterLogs(snap.registerLogs, tokenAHex32, tokenBHex32);
+                if (fromLogs != null) {
+                    return { poolHex: fromLogs, factoryHex: fac, via: 'logs' };
+                }
+            }
+            const poolHexRaw = await findNativeDexFactoryPoolByTokens(client, fac, tokenAHex32, tokenBHex32, options.find);
+            const poolHex = poolHexRaw != null ? validateHex32(poolHexRaw) : null;
+            return { poolHex, factoryHex: fac, via: poolHex != null ? 'simulate' : 'none' };
+        }
+        default: {
+            const _exhaustive = options;
+            return _exhaustive;
+        }
+    }
+}

package/dist/nativeDexDirectoryApi.d.ts

@@ -0,0 +1,121 @@
+/**
+ * HTTP JSON for the Cloudflare Worker `workers/native-dex-indexer` D1 directory
+ * (`GET /v1/directory/meta`, `GET /v1/directory/pools`). Not Boing JSON-RPC.
+ */
+import type { NativeDexIndexerPoolRow } from './nativeDexIndexerStats.js';
+import type { NativeDexMaterializedPoolEvent } from './nativeDexPoolHistory.js';
+/** `api` field value on successful directory responses. */
+export declare const NATIVE_DEX_DIRECTORY_API_ID: "boing-native-dex-directory/v1";
+/** Bumped when D1 schema or meta semantics change in a breaking way for clients. */
+export declare const NATIVE_DEX_DIRECTORY_SCHEMA_VERSION: 2;
+export type NativeDexDirectoryMetaResponse = {
+    api: string;
+    schemaVersion?: number;
+    poolCount: number;
+    /** Row count in `directory_pool_events` when the Worker migration is applied. */
+    eventCount?: number;
+    latestSyncBatch: string | null;
+    /** Chain height used for the last event snapshot (migration `0003+`). */
+    indexedTipHeight?: number | null;
+    /** Block hash at `indexedTipHeight` when the node returned it — for skew checks only; not a reorg rewind signal. */
+    indexedTipBlockHash?: string | null;
+    /** `header.parent_hash` at the indexed tip block when available. */
+    indexedParentBlockHash?: string | null;
+    nftOwnerRowCount?: number;
+    /** Rows in `directory_receipt_log` when migration `0006` is applied and receipt archiving is enabled. */
+    receiptLogCount?: number;
+};
+export type NativeDexDirectoryPoolsPageResponse = {
+    api: string;
+    limit: number;
+    cursor: string | null;
+    nextCursor: string | null;
+    hasMore: boolean;
+    pools: NativeDexIndexerPoolRow[];
+};
+export type NativeDexDirectoryPoolEventsPageResponse = {
+    api: string;
+    poolHex: string;
+    limit: number;
+    cursor: string | null;
+    nextCursor: string | null;
+    hasMore: boolean;
+    events: NativeDexMaterializedPoolEvent[];
+};
+export type NativeDexDirectoryUserEventsPageResponse = {
+    api: string;
+    callerHex: string;
+    limit: number;
+    cursor: string | null;
+    nextCursor: string | null;
+    hasMore: boolean;
+    events: NativeDexMaterializedPoolEvent[];
+};
+export declare class NativeDexDirectoryHttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly bodySnippet?: string | undefined;
+    constructor(message: string, status: number, url: string, bodySnippet?: string | undefined);
+}
+/** Trim and strip a trailing slash (no path segment — base is worker origin). */
+export declare function normalizeNativeDexDirectoryWorkerBaseUrl(raw: string): string;
+/**
+ * Parse `GET /v1/directory/meta` JSON. Returns `null` if shape is invalid.
+ */
+export declare function parseNativeDexDirectoryMetaResponse(data: unknown): NativeDexDirectoryMetaResponse | null;
+/**
+ * Parse `GET /v1/directory/pools` JSON. Drops pool objects that fail minimal hex validation.
+ */
+export declare function parseNativeDexDirectoryPoolsPageResponse(data: unknown): NativeDexDirectoryPoolsPageResponse | null;
+/**
+ * Parse `GET /v1/history/pool/{pool}/events` JSON. Drops malformed event objects.
+ */
+export declare function parseNativeDexDirectoryPoolEventsPageResponse(data: unknown): NativeDexDirectoryPoolEventsPageResponse | null;
+/**
+ * Parse `GET /v1/history/user/{caller}/events` JSON. Drops malformed event objects.
+ */
+export declare function parseNativeDexDirectoryUserEventsPageResponse(data: unknown): NativeDexDirectoryUserEventsPageResponse | null;
+/**
+ * `GET {baseUrl}/v1/directory/meta`
+ */
+export declare function fetchNativeDexDirectoryMeta(baseUrl: string, init?: RequestInit): Promise<NativeDexDirectoryMetaResponse>;
+export type FetchNativeDexDirectoryPoolsPageQuery = {
+    /** 1–100; default 20 on server if omitted — we pass explicit default 20 when unset. */
+    limit?: number;
+    cursor?: string | null;
+};
+/**
+ * `GET {baseUrl}/v1/directory/pools?limit=&cursor=`
+ */
+export declare function fetchNativeDexDirectoryPoolsPage(baseUrl: string, query?: FetchNativeDexDirectoryPoolsPageQuery, init?: RequestInit): Promise<NativeDexDirectoryPoolsPageResponse>;
+export type FetchNativeDexDirectoryPoolEventsPageQuery = {
+    limit?: number;
+    /** Row `id` cursor from prior `nextCursor` (newest-first pages). */
+    cursor?: string | null;
+};
+/**
+ * `GET {baseUrl}/v1/history/pool/{poolHex}/events?limit=&cursor=`
+ */
+export declare function fetchNativeDexDirectoryPoolEventsPage(baseUrl: string, poolHex32: string, query?: FetchNativeDexDirectoryPoolEventsPageQuery, init?: RequestInit): Promise<NativeDexDirectoryPoolEventsPageResponse>;
+export type FetchNativeDexDirectoryUserEventsPageQuery = {
+    limit?: number;
+    cursor?: string | null;
+};
+/**
+ * `GET {baseUrl}/v1/history/user/{callerHex}/events?limit=&cursor=`
+ */
+export declare function fetchNativeDexDirectoryUserEventsPage(baseUrl: string, callerHex32: string, query?: FetchNativeDexDirectoryUserEventsPageQuery, init?: RequestInit): Promise<NativeDexDirectoryUserEventsPageResponse>;
+export type CollectNativeDexDirectoryPoolsOptions = {
+    /** Per request `limit` (1–100). Default 100. */
+    pageLimit?: number;
+    /** Stop after this many pools (truncates last page). Default unlimited. */
+    maxPools?: number;
+    /** Safety cap on HTTP pages. Default 10_000. */
+    maxPages?: number;
+    init?: RequestInit;
+};
+/**
+ * Walk cursor pages until `hasMore` is false or limits hit.
+ */
+export declare function collectAllNativeDexDirectoryPools(baseUrl: string, opts?: CollectNativeDexDirectoryPoolsOptions): Promise<NativeDexIndexerPoolRow[]>;
+//# sourceMappingURL=nativeDexDirectoryApi.d.ts.map

package/dist/nativeDexDirectoryApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeDexDirectoryApi.d.ts","sourceRoot":"","sources":["../src/nativeDexDirectoryApi.ts"],"names":[],"mappings":"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"}