boing-sdk 0.3.0

package/dist/nativeDexRouting.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Constant-product **routing** and **quote aggregation** over Boing native pools (pure math + optional RPC hydrate).
+ * No external chains. Execution still uses **`contract_call`** / multihop router encoders elsewhere in the SDK.
+ */
+import type { BoingClient } from './client.js';
+import type { NativeDexIntegrationOverrides } from './dexIntegration.js';
+import { type NativeDexDirectorySnapshot } from './nativeDexDirectory.js';
+/** One tradeable CP pool with oriented reserves (A/B match on-chain slot semantics). */
+export type CpPoolVenue = {
+    poolHex: `0x${string}`;
+    tokenAHex: `0x${string}`;
+    tokenBHex: `0x${string}`;
+    reserveA: bigint;
+    reserveB: bigint;
+    /** Output-side fee bps; use **`NATIVE_CP_SWAP_FEE_BPS`** when on-chain reads **`0`**. */
+    feeBps: bigint;
+};
+export type CpQuoteResult = {
+    amountOut: bigint;
+    tokenOutHex: string;
+    /** Native AMM **`swap`** direction: **`0`** = A→B, **`1`** = B→A. */
+    directionForSwapCalldata: bigint;
+};
+/**
+ * Exact output quote for **`tokenIn` → opposite side** on one venue (fails if **`tokenIn`** is not **`tokenA`** or **`tokenB`**).
+ */
+export declare function quoteCpPoolSwap(venue: CpPoolVenue, tokenInHex: string, amountIn: bigint): CpQuoteResult;
+/** Rank venues that list **`(tokenIn, tokenOut)`** by **`amountOut`** for a given **`amountIn`** (best first). */
+export declare function rankDirectCpPools(venues: readonly CpPoolVenue[], tokenInHex: string, tokenOutHex: string, amountIn: bigint): Array<{
+    venue: CpPoolVenue;
+    amountOut: bigint;
+    directionForSwapCalldata: bigint;
+}>;
+export type RouteHop = {
+    venue: CpPoolVenue;
+    tokenInHex: string;
+    tokenOutHex: string;
+    amountIn: bigint;
+    amountOut: bigint;
+    directionForSwapCalldata: bigint;
+};
+export type CpSwapRoute = {
+    hops: RouteHop[];
+    tokenInHex: string;
+    tokenOutHex: string;
+    amountIn: bigint;
+    amountOut: bigint;
+};
+/** First route with **≥ 2** hops, or **`undefined`** (skips direct single-pool rows). */
+export declare function pickFirstMultihopCpRoute(routes: readonly CpSwapRoute[]): CpSwapRoute | undefined;
+/**
+ * Unique **`tokenA`** / **`tokenB`** ids across **`route.hops`** (**sorted** hex). Pass as **`additionalAccountsHex32`** when pools **`CALL`** reference-token contracts (v2+).
+ */
+export declare function uniqueSortedTokenHex32FromCpRoute(route: CpSwapRoute): string[];
+/** Maximum sequential pool **`Call`s** supported by canonical multihop router bytecode (selectors **`0xE5`–`0xEE`**). */
+export declare const NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS = 6;
+/**
+ * Basis points denominator for {@link minOutFloorAfterSlippageBps} (**10000** = 100%).
+ * Example: **`50`** bps ⇒ allow **0.5%** worse execution vs the quoted amount.
+ */
+export declare const NATIVE_DEX_SLIPPAGE_BPS_SCALE = 10000n;
+/**
+ * Floor of **`amountOut * (SCALE - slippageBps) / SCALE`** — conservative per-hop **`minOut`** for multihop **`swap`** / **`swap_to`** inners.
+ */
+export declare function minOutFloorAfterSlippageBps(amountOut: bigint, slippageBps: bigint): bigint;
+/** One slippage floor per {@link CpSwapRoute} hop, aligned with {@link RouteHop.amountOut} order. */
+export declare function minOutPerHopFromQuotedRouteSlippageBps(route: CpSwapRoute, slippageBps: bigint): bigint[];
+/**
+ * Enumerate simple CP paths (**no** same-pool reuse) up to **`maxHops`** pools; returns routes sorted by **`amountOut`** (best first).
+ * Default **`maxHops`** matches on-chain multihop router capacity ({@link NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS}); pass a lower value for large **`venues`** sets.
+ */
+export declare function findBestCpRoutes(venues: readonly CpPoolVenue[], tokenInHex: string, tokenOutHex: string, amountIn: bigint, options?: {
+    maxHops?: number;
+    maxRoutes?: number;
+}): CpSwapRoute[];
+/** Best route or **`undefined`** when none. */
+export declare function findBestCpRoute(venues: readonly CpPoolVenue[], tokenInHex: string, tokenOutHex: string, amountIn: bigint, options?: {
+    maxHops?: number;
+    maxRoutes?: number;
+}): CpSwapRoute | undefined;
+export type EncodeNativeDexMultihopFromRouteOptions128 = {
+    /** One minimum output per hop; length must equal **`route.hops.length`**. */
+    minOutPerHop: readonly bigint[];
+};
+export type EncodeNativeDexMultihopFromRouteOptions160 = {
+    minOutPerHop: readonly bigint[];
+    /** Multihop router **`AccountId`**; intermediate **`swap_to`** deliveries use this address. */
+    routerAccountHex32: string;
+    /** Final hop **`swap_to`** recipient (typically the trader). */
+    finalRecipientHex32: string;
+};
+/**
+ * Build **128-byte** inner **`swap`** calldata for a quoted {@link CpSwapRoute} (**2–6** hops).
+ * Pair with **`contract_call`** targeting the multihop router account.
+ */
+export declare function encodeNativeDexMultihopRouterCalldata128FromRoute(route: CpSwapRoute, options: EncodeNativeDexMultihopFromRouteOptions128): Uint8Array;
+/**
+ * Build **160-byte** inner **`swap_to`** (v5 pool) calldata for a quoted {@link CpSwapRoute}.
+ * Intermediate hops send output to **`routerAccountHex32`**; the last hop sends to **`finalRecipientHex32`**.
+ */
+export declare function encodeNativeDexMultihopRouterCalldata160FromRoute(route: CpSwapRoute, options: EncodeNativeDexMultihopFromRouteOptions160): Uint8Array;
+/**
+ * Same as {@link encodeNativeDexMultihopRouterCalldata128FromRoute} with **`minOutPerHop`** from
+ * {@link minOutPerHopFromQuotedRouteSlippageBps}.
+ */
+export declare function encodeNativeDexMultihopRouterCalldata128FromRouteWithSlippage(route: CpSwapRoute, slippageBps: bigint): Uint8Array;
+/**
+ * Same as {@link encodeNativeDexMultihopRouterCalldata160FromRoute} with **`minOutPerHop`** from
+ * {@link minOutPerHopFromQuotedRouteSlippageBps}.
+ */
+export declare function encodeNativeDexMultihopRouterCalldata160FromRouteWithSlippage(route: CpSwapRoute, routerAccountHex32: string, finalRecipientHex32: string, slippageBps: bigint): Uint8Array;
+/**
+ * Even-split **aggregation heuristic**: divide **`totalAmountIn`** across the top **`poolCount`** direct pools (by full-size quote rank), sum outputs.
+ * Not an optimal CEX splitter; useful for UI estimates and incremental liquidity use.
+ */
+export declare function quoteCpEvenSplitAcrossDirectPools(venues: readonly CpPoolVenue[], tokenInHex: string, tokenOutHex: string, totalAmountIn: bigint, poolCount: number): {
+    rankedPools: Array<{
+        venue: CpPoolVenue;
+        amountOut: bigint;
+        directionForSwapCalldata: bigint;
+    }>;
+    allocations: Array<{
+        venue: CpPoolVenue;
+        amountIn: bigint;
+        amountOut: bigint;
+        directionForSwapCalldata: bigint;
+    }>;
+    totalOut: bigint;
+};
+export type PoolTokenRow = {
+    poolHex: string;
+    tokenAHex: string;
+    tokenBHex: string;
+};
+/**
+ * Hydrate **`CpPoolVenue`** rows from Boing RPC (reserves + fee bps per pool). **Boing-only.**
+ */
+export declare function hydrateCpPoolVenuesFromRpc(client: BoingClient, rows: readonly PoolTokenRow[], options?: {
+    concurrency?: number;
+}): Promise<CpPoolVenue[]>;
+export type FetchCpRoutingFromDirectoryLogsOptions = {
+    overrides?: NativeDexIntegrationOverrides;
+    registerLogs: {
+        fromBlock: number;
+        toBlock?: number;
+    };
+    maxHops?: number;
+    maxRoutes?: number;
+    hydrateConcurrency?: number;
+};
+/**
+ * **Boing-only** pipeline: directory **`register_pair`** log range → hydrate venues → best CP route(s).
+ * Pair with **`encodeNativeDexMultihopRouterCalldata128FromRoute`** / **`encodeNativeDexMultihopRouterCalldata160FromRoute`** or **`pickFirstMultihopCpRoute`** + **`buildNativeDexMultihopSwapExpressTxFromRoute128`** when executing multihop on-chain.
+ */
+export declare function fetchCpRoutingFromDirectoryLogs(client: BoingClient, tokenInHex: string, tokenOutHex: string, amountIn: bigint, options: FetchCpRoutingFromDirectoryLogsOptions): Promise<{
+    snapshot: NativeDexDirectorySnapshot;
+    venues: CpPoolVenue[];
+    routes: CpSwapRoute[];
+}>;
+//# sourceMappingURL=nativeDexRouting.d.ts.map

package/dist/nativeDexRouting.d.ts.map

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

package/dist/nativeDexRouting.js

@@ -0,0 +1,345 @@
+/**
+ * Constant-product **routing** and **quote aggregation** over Boing native pools (pure math + optional RPC hydrate).
+ * No external chains. Execution still uses **`contract_call`** / multihop router encoders elsewhere in the SDK.
+ */
+import { fetchNativeDexDirectorySnapshot } from './nativeDexDirectory.js';
+import { validateHex32 } from './hex.js';
+import { mapWithConcurrencyLimit } from './indexerBatch.js';
+import { NATIVE_CP_SWAP_FEE_BPS, constantProductAmountOutWithFeeBps, encodeNativeAmmSwapCalldata, encodeNativeAmmSwapToCalldata, } from './nativeAmm.js';
+import { encodeNativeDexSwap2RouterCalldata128, encodeNativeDexSwap2RouterCalldata160, encodeNativeDexSwap3RouterCalldata128, encodeNativeDexSwap3RouterCalldata160, encodeNativeDexSwap4RouterCalldata128, encodeNativeDexSwap4RouterCalldata160, encodeNativeDexSwap5RouterCalldata128, encodeNativeDexSwap5RouterCalldata160, encodeNativeDexSwap6RouterCalldata128, encodeNativeDexSwap6RouterCalldata160, } from './nativeDexSwap2Router.js';
+import { fetchNativeConstantProductPoolSnapshot, fetchNativeConstantProductSwapFeeBps, } from './nativeAmmPool.js';
+function normHex32(h) {
+    return validateHex32(h).toLowerCase();
+}
+function effectiveFeeBps(raw) {
+    return raw === 0n ? BigInt(NATIVE_CP_SWAP_FEE_BPS) : raw;
+}
+/**
+ * Exact output quote for **`tokenIn` → opposite side** on one venue (fails if **`tokenIn`** is not **`tokenA`** or **`tokenB`**).
+ */
+export function quoteCpPoolSwap(venue, tokenInHex, amountIn) {
+    if (amountIn < 0n)
+        throw new RangeError('amountIn must be non-negative');
+    const a = normHex32(venue.tokenAHex);
+    const b = normHex32(venue.tokenBHex);
+    const tin = normHex32(tokenInHex);
+    if (tin === a) {
+        const amountOut = constantProductAmountOutWithFeeBps(venue.reserveA, venue.reserveB, amountIn, venue.feeBps);
+        return { amountOut, tokenOutHex: b, directionForSwapCalldata: 0n };
+    }
+    if (tin === b) {
+        const amountOut = constantProductAmountOutWithFeeBps(venue.reserveB, venue.reserveA, amountIn, venue.feeBps);
+        return { amountOut, tokenOutHex: a, directionForSwapCalldata: 1n };
+    }
+    throw new Error('quoteCpPoolSwap: tokenIn is not a pool token');
+}
+/** Rank venues that list **`(tokenIn, tokenOut)`** by **`amountOut`** for a given **`amountIn`** (best first). */
+export function rankDirectCpPools(venues, tokenInHex, tokenOutHex, amountIn) {
+    const tout = normHex32(tokenOutHex);
+    const out = [];
+    for (const v of venues) {
+        let q;
+        try {
+            q = quoteCpPoolSwap(v, tokenInHex, amountIn);
+        }
+        catch {
+            continue;
+        }
+        if (q.tokenOutHex === tout && q.amountOut > 0n) {
+            out.push({ venue: v, amountOut: q.amountOut, directionForSwapCalldata: q.directionForSwapCalldata });
+        }
+    }
+    out.sort((x, y) => (x.amountOut > y.amountOut ? -1 : x.amountOut < y.amountOut ? 1 : 0));
+    return out;
+}
+/** First route with **≥ 2** hops, or **`undefined`** (skips direct single-pool rows). */
+export function pickFirstMultihopCpRoute(routes) {
+    return routes.find((r) => r.hops.length >= 2);
+}
+/**
+ * Unique **`tokenA`** / **`tokenB`** ids across **`route.hops`** (**sorted** hex). Pass as **`additionalAccountsHex32`** when pools **`CALL`** reference-token contracts (v2+).
+ */
+export function uniqueSortedTokenHex32FromCpRoute(route) {
+    const seen = new Set();
+    for (const h of route.hops) {
+        seen.add(normHex32(h.venue.tokenAHex));
+        seen.add(normHex32(h.venue.tokenBHex));
+    }
+    return [...seen].sort();
+}
+/** Maximum sequential pool **`Call`s** supported by canonical multihop router bytecode (selectors **`0xE5`–`0xEE`**). */
+export const NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS = 6;
+/**
+ * Basis points denominator for {@link minOutFloorAfterSlippageBps} (**10000** = 100%).
+ * Example: **`50`** bps ⇒ allow **0.5%** worse execution vs the quoted amount.
+ */
+export const NATIVE_DEX_SLIPPAGE_BPS_SCALE = 10000n;
+/**
+ * Floor of **`amountOut * (SCALE - slippageBps) / SCALE`** — conservative per-hop **`minOut`** for multihop **`swap`** / **`swap_to`** inners.
+ */
+export function minOutFloorAfterSlippageBps(amountOut, slippageBps) {
+    if (amountOut < 0n)
+        throw new RangeError('amountOut must be non-negative');
+    if (slippageBps < 0n || slippageBps > NATIVE_DEX_SLIPPAGE_BPS_SCALE) {
+        throw new RangeError(`slippageBps must satisfy 0 <= slippageBps <= ${NATIVE_DEX_SLIPPAGE_BPS_SCALE.toString()}`);
+    }
+    return (amountOut * (NATIVE_DEX_SLIPPAGE_BPS_SCALE - slippageBps)) / NATIVE_DEX_SLIPPAGE_BPS_SCALE;
+}
+/** One slippage floor per {@link CpSwapRoute} hop, aligned with {@link RouteHop.amountOut} order. */
+export function minOutPerHopFromQuotedRouteSlippageBps(route, slippageBps) {
+    return route.hops.map((h) => minOutFloorAfterSlippageBps(h.amountOut, slippageBps));
+}
+function edgesFromToken(venues, currentToken) {
+    const t = normHex32(currentToken);
+    const hit = [];
+    for (const v of venues) {
+        const a = normHex32(v.tokenAHex);
+        const b = normHex32(v.tokenBHex);
+        if (a === t || b === t)
+            hit.push(v);
+    }
+    return hit;
+}
+/**
+ * Enumerate simple CP paths (**no** same-pool reuse) up to **`maxHops`** pools; returns routes sorted by **`amountOut`** (best first).
+ * Default **`maxHops`** matches on-chain multihop router capacity ({@link NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS}); pass a lower value for large **`venues`** sets.
+ */
+export function findBestCpRoutes(venues, tokenInHex, tokenOutHex, amountIn, options) {
+    const maxHops = options?.maxHops ?? NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS;
+    const maxRoutes = options?.maxRoutes ?? 32;
+    if (maxHops < 1)
+        throw new RangeError('maxHops must be >= 1');
+    if (maxHops > NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS) {
+        throw new RangeError(`maxHops cannot exceed ${NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS} (multihop router cap)`);
+    }
+    const tin = normHex32(tokenInHex);
+    const tout = normHex32(tokenOutHex);
+    if (tin === tout) {
+        return [{ hops: [], tokenInHex: tin, tokenOutHex: tout, amountIn, amountOut: amountIn }];
+    }
+    const routes = [];
+    function dfs(currentToken, amount, path, visitedPools) {
+        if (routes.length >= maxRoutes)
+            return;
+        for (const v of edgesFromToken(venues, currentToken)) {
+            const ph = normHex32(v.poolHex);
+            if (visitedPools.has(ph))
+                continue;
+            let q;
+            try {
+                q = quoteCpPoolSwap(v, currentToken, amount);
+            }
+            catch {
+                continue;
+            }
+            if (q.amountOut === 0n)
+                continue;
+            const hop = {
+                venue: v,
+                tokenInHex: currentToken,
+                tokenOutHex: q.tokenOutHex,
+                amountIn: amount,
+                amountOut: q.amountOut,
+                directionForSwapCalldata: q.directionForSwapCalldata,
+            };
+            if (normHex32(q.tokenOutHex) === tout) {
+                routes.push({
+                    hops: [...path, hop],
+                    tokenInHex: tin,
+                    tokenOutHex: tout,
+                    amountIn,
+                    amountOut: q.amountOut,
+                });
+                continue;
+            }
+            if (path.length + 1 >= maxHops)
+                continue;
+            visitedPools.add(ph);
+            dfs(q.tokenOutHex, q.amountOut, [...path, hop], visitedPools);
+            visitedPools.delete(ph);
+            if (routes.length >= maxRoutes)
+                return;
+        }
+    }
+    dfs(tin, amountIn, [], new Set());
+    routes.sort((a, b) => (a.amountOut > b.amountOut ? -1 : a.amountOut < b.amountOut ? 1 : 0));
+    return routes.slice(0, maxRoutes);
+}
+/** Best route or **`undefined`** when none. */
+export function findBestCpRoute(venues, tokenInHex, tokenOutHex, amountIn, options) {
+    return findBestCpRoutes(venues, tokenInHex, tokenOutHex, amountIn, options)[0];
+}
+/**
+ * Build **128-byte** inner **`swap`** calldata for a quoted {@link CpSwapRoute} (**2–6** hops).
+ * Pair with **`contract_call`** targeting the multihop router account.
+ */
+export function encodeNativeDexMultihopRouterCalldata128FromRoute(route, options) {
+    const n = route.hops.length;
+    if (n < 2 || n > NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS) {
+        throw new RangeError(`multihop router expects 2..${NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS} hops, got ${n}`);
+    }
+    if (options.minOutPerHop.length !== n) {
+        throw new RangeError('minOutPerHop length must match route.hops.length');
+    }
+    const pools = route.hops.map((h) => validateHex32(h.venue.poolHex));
+    const inners = route.hops.map((hop, i) => encodeNativeAmmSwapCalldata(hop.directionForSwapCalldata, hop.amountIn, options.minOutPerHop[i]));
+    switch (n) {
+        case 2:
+            return encodeNativeDexSwap2RouterCalldata128(pools[0], inners[0], pools[1], inners[1]);
+        case 3:
+            return encodeNativeDexSwap3RouterCalldata128(pools[0], inners[0], pools[1], inners[1], pools[2], inners[2]);
+        case 4:
+            return encodeNativeDexSwap4RouterCalldata128(pools[0], inners[0], pools[1], inners[1], pools[2], inners[2], pools[3], inners[3]);
+        case 5:
+            return encodeNativeDexSwap5RouterCalldata128(pools[0], inners[0], pools[1], inners[1], pools[2], inners[2], pools[3], inners[3], pools[4], inners[4]);
+        case 6:
+            return encodeNativeDexSwap6RouterCalldata128(pools[0], inners[0], pools[1], inners[1], pools[2], inners[2], pools[3], inners[3], pools[4], inners[4], pools[5], inners[5]);
+        default:
+            throw new RangeError(`unsupported hop count ${n}`);
+    }
+}
+/**
+ * Build **160-byte** inner **`swap_to`** (v5 pool) calldata for a quoted {@link CpSwapRoute}.
+ * Intermediate hops send output to **`routerAccountHex32`**; the last hop sends to **`finalRecipientHex32`**.
+ */
+export function encodeNativeDexMultihopRouterCalldata160FromRoute(route, options) {
+    const n = route.hops.length;
+    if (n < 2 || n > NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS) {
+        throw new RangeError(`multihop router expects 2..${NATIVE_DEX_MULTIHOP_ROUTER_MAX_POOLS} hops, got ${n}`);
+    }
+    if (options.minOutPerHop.length !== n) {
+        throw new RangeError('minOutPerHop length must match route.hops.length');
+    }
+    const router = validateHex32(options.routerAccountHex32);
+    const finalRecip = validateHex32(options.finalRecipientHex32);
+    const pools = route.hops.map((h) => validateHex32(h.venue.poolHex));
+    const inners = route.hops.map((hop, i) => {
+        const recip = i === n - 1 ? finalRecip : router;
+        return encodeNativeAmmSwapToCalldata(hop.directionForSwapCalldata, hop.amountIn, options.minOutPerHop[i], recip);
+    });
+    switch (n) {
+        case 2:
+            return encodeNativeDexSwap2RouterCalldata160(pools[0], inners[0], pools[1], inners[1]);
+        case 3:
+            return encodeNativeDexSwap3RouterCalldata160(pools[0], inners[0], pools[1], inners[1], pools[2], inners[2]);
+        case 4:
+            return encodeNativeDexSwap4RouterCalldata160(pools[0], inners[0], pools[1], inners[1], pools[2], inners[2], pools[3], inners[3]);
+        case 5:
+            return encodeNativeDexSwap5RouterCalldata160(pools[0], inners[0], pools[1], inners[1], pools[2], inners[2], pools[3], inners[3], pools[4], inners[4]);
+        case 6:
+            return encodeNativeDexSwap6RouterCalldata160(pools[0], inners[0], pools[1], inners[1], pools[2], inners[2], pools[3], inners[3], pools[4], inners[4], pools[5], inners[5]);
+        default:
+            throw new RangeError(`unsupported hop count ${n}`);
+    }
+}
+/**
+ * Same as {@link encodeNativeDexMultihopRouterCalldata128FromRoute} with **`minOutPerHop`** from
+ * {@link minOutPerHopFromQuotedRouteSlippageBps}.
+ */
+export function encodeNativeDexMultihopRouterCalldata128FromRouteWithSlippage(route, slippageBps) {
+    return encodeNativeDexMultihopRouterCalldata128FromRoute(route, {
+        minOutPerHop: minOutPerHopFromQuotedRouteSlippageBps(route, slippageBps),
+    });
+}
+/**
+ * Same as {@link encodeNativeDexMultihopRouterCalldata160FromRoute} with **`minOutPerHop`** from
+ * {@link minOutPerHopFromQuotedRouteSlippageBps}.
+ */
+export function encodeNativeDexMultihopRouterCalldata160FromRouteWithSlippage(route, routerAccountHex32, finalRecipientHex32, slippageBps) {
+    return encodeNativeDexMultihopRouterCalldata160FromRoute(route, {
+        minOutPerHop: minOutPerHopFromQuotedRouteSlippageBps(route, slippageBps),
+        routerAccountHex32,
+        finalRecipientHex32,
+    });
+}
+/**
+ * Even-split **aggregation heuristic**: divide **`totalAmountIn`** across the top **`poolCount`** direct pools (by full-size quote rank), sum outputs.
+ * Not an optimal CEX splitter; useful for UI estimates and incremental liquidity use.
+ */
+export function quoteCpEvenSplitAcrossDirectPools(venues, tokenInHex, tokenOutHex, totalAmountIn, poolCount) {
+    if (poolCount < 1)
+        throw new RangeError('poolCount must be >= 1');
+    if (totalAmountIn < 0n)
+        throw new RangeError('totalAmountIn must be non-negative');
+    const ranked = rankDirectCpPools(venues, tokenInHex, tokenOutHex, totalAmountIn);
+    const n = Math.min(poolCount, ranked.length);
+    if (n === 0 || totalAmountIn === 0n) {
+        return { rankedPools: ranked, allocations: [], totalOut: 0n };
+    }
+    const base = totalAmountIn / BigInt(n);
+    const rem = Number(totalAmountIn % BigInt(n));
+    const allocations = [];
+    let totalOut = 0n;
+    for (let i = 0; i < n; i++) {
+        const row = ranked[i];
+        const ai = base + (i < rem ? 1n : 0n);
+        if (ai === 0n)
+            continue;
+        const q = quoteCpPoolSwap(row.venue, tokenInHex, ai);
+        allocations.push({
+            venue: row.venue,
+            amountIn: ai,
+            amountOut: q.amountOut,
+            directionForSwapCalldata: q.directionForSwapCalldata,
+        });
+        totalOut += q.amountOut;
+    }
+    return { rankedPools: ranked, allocations, totalOut };
+}
+function dedupePoolRows(rows) {
+    const m = new Map();
+    for (const r of rows) {
+        const k = normHex32(r.poolHex);
+        if (!m.has(k))
+            m.set(k, r);
+    }
+    return [...m.values()];
+}
+/**
+ * Hydrate **`CpPoolVenue`** rows from Boing RPC (reserves + fee bps per pool). **Boing-only.**
+ */
+export async function hydrateCpPoolVenuesFromRpc(client, rows, options) {
+    const uniq = dedupePoolRows(rows);
+    const concurrency = options?.concurrency ?? 8;
+    return mapWithConcurrencyLimit(uniq, concurrency, async (r) => {
+        const poolHex = validateHex32(r.poolHex);
+        const tokenAHex = validateHex32(r.tokenAHex);
+        const tokenBHex = validateHex32(r.tokenBHex);
+        const [snap, feeRaw] = await Promise.all([
+            fetchNativeConstantProductPoolSnapshot(client, poolHex),
+            fetchNativeConstantProductSwapFeeBps(client, poolHex),
+        ]);
+        return {
+            poolHex,
+            tokenAHex,
+            tokenBHex,
+            reserveA: snap.reserveA,
+            reserveB: snap.reserveB,
+            feeBps: effectiveFeeBps(feeRaw),
+        };
+    });
+}
+/**
+ * **Boing-only** pipeline: directory **`register_pair`** log range → hydrate venues → best CP route(s).
+ * Pair with **`encodeNativeDexMultihopRouterCalldata128FromRoute`** / **`encodeNativeDexMultihopRouterCalldata160FromRoute`** or **`pickFirstMultihopCpRoute`** + **`buildNativeDexMultihopSwapExpressTxFromRoute128`** when executing multihop on-chain.
+ */
+export async function fetchCpRoutingFromDirectoryLogs(client, tokenInHex, tokenOutHex, amountIn, options) {
+    const snapshot = await fetchNativeDexDirectorySnapshot(client, {
+        overrides: options.overrides,
+        registerLogs: options.registerLogs,
+    });
+    const logs = snapshot.registerLogs ?? [];
+    const rows = logs.map((l) => ({
+        poolHex: l.poolHex,
+        tokenAHex: l.tokenAHex,
+        tokenBHex: l.tokenBHex,
+    }));
+    const venues = await hydrateCpPoolVenuesFromRpc(client, rows, {
+        concurrency: options.hydrateConcurrency,
+    });
+    const routes = findBestCpRoutes(venues, tokenInHex, tokenOutHex, amountIn, {
+        maxHops: options.maxHops,
+        maxRoutes: options.maxRoutes,
+    });
+    return { snapshot, venues, routes };
+}

package/dist/nativeDexSeamless.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Copy, preflight, and one-shot tx helpers for native Boing DEX integration.
+ * Reinforces that Boing is **not** a drop-in Uniswap/EVM router and keeps flows **Boing-RPC-only**.
+ */
+import type { BoingClient } from './client.js';
+import type { NativeDexIntegrationDefaults } from './dexIntegration.js';
+import { buildNativeConstantProductContractCallTx, buildNativeDexMultihopRouterContractCallTx, type NativePoolAccessListOptions } from './nativeAmmPool.js';
+import type { CpSwapRoute } from './nativeDexRouting.js';
+import { type BoingRpcPreflightError } from './preflightGate.js';
+import type { SimulateResult } from './types.js';
+/** Short line for tooltips / footers. */
+export declare const BOING_NATIVE_DEX_NOT_EVM_TAGLINE = "Boing native DEX uses 32-byte account ids, explicit access lists, and VM-specific calldata\u2014not a paste-any-Uniswap-address router.";
+/** Bullet list for onboarding modals or docs snippets. */
+export declare const BOING_NATIVE_DEX_NOT_EVM_BULLETS: readonly ["Accounts are 32-byte Boing AccountIds (64 hex chars), not 20-byte Ethereum contract addresses.", "Each `contract_call` needs calldata per NATIVE-AMM / NATIVE-DEX specs plus explicit `access_list` read/write sets.", "Pool, factory, multihop router, ledger forwarders, and LP vault/share ids resolve via RPC `end_user` hints, `fetchNativeDexIntegrationDefaults`, env overrides, or CREATE2 prediction—there is no universal router ABI."];
+export declare function formatBoingNativeDexNotEvmDisclaimer(): string;
+/**
+ * Surfaces missing operator hints so UIs can link to ops runbooks instead of failing silently.
+ */
+export declare function describeNativeDexDefaultGaps(defaults: NativeDexIntegrationDefaults): readonly string[];
+/** RPC methods a typical native DEX dApp (read + simulate + logs) expects from **boing-node**. */
+export declare const BOING_NATIVE_DEX_TOOLKIT_RPC_METHODS: readonly ["boing_getNetworkInfo", "boing_simulateTransaction", "boing_getLogs", "boing_getContractStorage"];
+/**
+ * {@link assertBoingRpcEnvironment} with {@link BOING_NATIVE_DEX_TOOLKIT_RPC_METHODS}.
+ * Throws {@link BoingRpcPreflightError} when the endpoint is missing methods or failing discovery.
+ */
+export declare function assertBoingNativeDexToolkitRpc(client: BoingClient): Promise<import("./rpcDoctor.js").BoingRpcDoctorResult>;
+/** User-facing text when {@link assertBoingNativeDexToolkitRpc} fails (QA / pruned / old node). */
+export declare function formatNativeDexToolkitPreflightForUi(err: BoingRpcPreflightError): string;
+/**
+ * One-shot **`contract_call`** object for **`boing_sendTransaction`** / Boing Express: native CP **`swap`** calldata + pool access list.
+ */
+export declare function buildNativeCpPoolSwapExpressTx(input: {
+    senderHex32: string;
+    poolHex32: string;
+    direction: bigint;
+    amountIn: bigint;
+    minOut: bigint;
+    poolAccessListOptions?: NativePoolAccessListOptions;
+}): ReturnType<typeof buildNativeConstantProductContractCallTx>;
+/** Multihop router **`contract_call`** from a quoted {@link CpSwapRoute} (**128-byte** pool inners). Pass **`minOutPerHop`** or **`slippageBps`** (explicit **`minOutPerHop`** wins when set). */
+export type BuildNativeDexMultihopSwapExpressTxFromRoute128Input = {
+    senderHex32: string;
+    routerHex32: string;
+    route: CpSwapRoute;
+    minOutPerHop?: readonly bigint[];
+    slippageBps?: bigint;
+    /**
+     * When **`true`**, append {@link uniqueSortedTokenHex32FromCpRoute} to **`additionalAccountsHex32`**
+     * (reference-token pools that **`CALL`** token contracts during **`swap`**).
+     */
+    includeVenueTokenAccounts?: boolean;
+    poolAccessListOptions?: NativePoolAccessListOptions;
+};
+/** Multihop router **`contract_call`** with **160-byte** **`swap_to`** inners (v5 pools). */
+export type BuildNativeDexMultihopSwapExpressTxFromRoute160Input = BuildNativeDexMultihopSwapExpressTxFromRoute128Input & {
+    finalRecipientHex32: string;
+};
+/**
+ * Recompute **`access_list`** after **`boing_simulateTransaction`** using {@link mergeNativeDexMultihopRouterAccessListWithSimulation}.
+ * **`poolHex32List`** and **`poolAccessListOptions`** should match the pools / extras used to build **`tx`**.
+ */
+export declare function applyNativeDexMultihopSimulationToContractCallTx(tx: {
+    type: 'contract_call';
+    contract: string;
+    calldata: string;
+    access_list: {
+        read: string[];
+        write: string[];
+    };
+}, input: {
+    senderHex32: string;
+    poolHex32List: readonly string[];
+    sim: SimulateResult;
+    poolAccessListOptions?: NativePoolAccessListOptions;
+}): {
+    type: 'contract_call';
+    contract: string;
+    calldata: string;
+    access_list: {
+        read: string[];
+        write: string[];
+    };
+};
+export declare function buildNativeDexMultihopSwapExpressTxFromRoute128(input: BuildNativeDexMultihopSwapExpressTxFromRoute128Input): ReturnType<typeof buildNativeDexMultihopRouterContractCallTx>;
+export declare function buildNativeDexMultihopSwapExpressTxFromRoute160(input: BuildNativeDexMultihopSwapExpressTxFromRoute160Input): ReturnType<typeof buildNativeDexMultihopRouterContractCallTx>;
+//# sourceMappingURL=nativeDexSeamless.d.ts.map

package/dist/nativeDexSeamless.d.ts.map

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