boing-sdk 0.3.0

package/dist/nativeAmmLogs.js

@@ -0,0 +1,114 @@
+/**
+ * Parse native constant-product pool **`Log2`** rows (`topic0` + caller `topic1` + 96-byte `data`).
+ * Matches `native_amm` emission and `docs/NATIVE-AMM-CALLDATA.md` § Logs.
+ */
+import { NATIVE_AMM_TOPIC_ADD_LIQUIDITY_HEX, NATIVE_AMM_TOPIC_REMOVE_LIQUIDITY_HEX, NATIVE_AMM_TOPIC_SWAP_HEX, } from './nativeAmm.js';
+import { decodeNativeAmmLogDataU128Triple } from './nativeAmmPool.js';
+import { iterReceiptLogs, normalizeTopicWord } from './receiptLogs.js';
+const T0_SWAP = normalizeTopicWord(NATIVE_AMM_TOPIC_SWAP_HEX);
+const T0_ADD = normalizeTopicWord(NATIVE_AMM_TOPIC_ADD_LIQUIDITY_HEX);
+const T0_REMOVE = normalizeTopicWord(NATIVE_AMM_TOPIC_REMOVE_LIQUIDITY_HEX);
+function kindFromNormalizedTopic0(t0) {
+    if (t0 === T0_SWAP)
+        return 'swap';
+    if (t0 === T0_ADD)
+        return 'addLiquidity';
+    if (t0 === T0_REMOVE)
+        return 'removeLiquidity';
+    return null;
+}
+/** True if `topic` (any casing / optional `0x`) is one of the three native AMM `Log2` topic0 values. */
+export function isNativeAmmLog2Topic0(topic) {
+    try {
+        return kindFromNormalizedTopic0(normalizeTopicWord(topic)) != null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True if `log` looks like a native AMM `Log2` (two topics, known topic0). Does not validate `data`.
+ */
+export function isNativeAmmLog2Shape(log) {
+    if (log.topics.length !== 2)
+        return false;
+    return isNativeAmmLog2Topic0(log.topics[0]);
+}
+/**
+ * Parse one receipt / RPC log into a typed event, or `null` if shape or `data` does not match.
+ */
+export function tryParseNativeAmmLog2(log) {
+    try {
+        if (log.topics.length !== 2)
+            return null;
+        const t0 = normalizeTopicWord(log.topics[0]);
+        const t1 = normalizeTopicWord(log.topics[1]);
+        const kind = kindFromNormalizedTopic0(t0);
+        if (kind == null)
+            return null;
+        const [w0, w1, w2] = decodeNativeAmmLogDataU128Triple(log.data);
+        const callerHex = t1;
+        switch (kind) {
+            case 'swap':
+                return {
+                    kind: 'swap',
+                    callerHex,
+                    direction: w0,
+                    amountIn: w1,
+                    amountOutAfterFee: w2,
+                };
+            case 'addLiquidity':
+                return {
+                    kind: 'addLiquidity',
+                    callerHex,
+                    amountA: w0,
+                    amountB: w1,
+                    lpMinted: w2,
+                };
+            case 'removeLiquidity':
+                return {
+                    kind: 'removeLiquidity',
+                    callerHex,
+                    liquidityBurned: w0,
+                    amountAOut: w1,
+                    amountBOut: w2,
+                };
+        }
+    }
+    catch {
+        return null;
+    }
+}
+export function tryParseNativeAmmRpcLogEntry(entry) {
+    const event = tryParseNativeAmmLog2(entry);
+    if (!event)
+        return null;
+    return {
+        ...event,
+        block_height: entry.block_height,
+        tx_index: entry.tx_index,
+        tx_id: entry.tx_id,
+        log_index: entry.log_index,
+        address: entry.address,
+    };
+}
+/** Keep only `RpcLogEntry` rows that parse as native AMM `Log2`, with placement fields attached. */
+export function filterMapNativeAmmRpcLogs(entries) {
+    const out = [];
+    for (const e of entries) {
+        const p = tryParseNativeAmmRpcLogEntry(e);
+        if (p)
+            out.push(p);
+    }
+    return out;
+}
+/** All successfully parsed native AMM logs in one receipt (in log order). */
+export function collectNativeAmmLog2FromReceipt(receipt) {
+    const out = [];
+    for (const { log, logIndex } of iterReceiptLogs(receipt)) {
+        const event = tryParseNativeAmmLog2(log);
+        if (event)
+            out.push({ logIndex, event });
+    }
+    return out;
+}

package/dist/nativeAmmLpVault.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Native AMM LP vault calldata + Express / JSON-RPC access lists. Matches `boing_execution::native_amm_lp_vault`.
+ * See `docs/NATIVE-AMM-LP-VAULT.md`.
+ */
+import type { BoingClient } from './client.js';
+import type { SimulateResult } from './types.js';
+/** `configure(pool, share_token)` — **96** bytes. */
+export declare const SELECTOR_NATIVE_AMM_LP_VAULT_CONFIGURE = 192;
+/** `deposit_add(inner_add_liquidity_128, min_lp)` — **192** bytes. */
+export declare const SELECTOR_NATIVE_AMM_LP_VAULT_DEPOSIT_ADD = 193;
+/** `boing_getContractStorage` — non-zero after successful **`configure`**. */
+export declare const NATIVE_AMM_LP_VAULT_KEY_CONFIGURED_HEX: `0x${string}`;
+/** Configured native CP **pool** `AccountId`. */
+export declare const NATIVE_AMM_LP_VAULT_KEY_POOL_HEX: `0x${string}`;
+/** Configured **LP share token** `AccountId`. */
+export declare const NATIVE_AMM_LP_VAULT_KEY_SHARE_TOKEN_HEX: `0x${string}`;
+export type NativeAmmLpVaultStorageSnapshot = {
+    /** `configure` has been executed (configured word ≠ 0). */
+    configured: boolean;
+    poolHex: `0x${string}` | null;
+    shareTokenHex: `0x${string}` | null;
+};
+/**
+ * Read vault **`configure`** state from **`boing_getContractStorage`** (three parallel reads).
+ */
+export declare function fetchNativeAmmLpVaultStorageSnapshot(client: BoingClient, vaultHex32: string): Promise<NativeAmmLpVaultStorageSnapshot>;
+export type NativeAmmLpVaultProductReadiness = {
+    /** False when **`boing_getContractStorage`** fails for the vault (missing account, RPC error, etc.). */
+    vaultRpcOk: boolean;
+    vaultRpcError?: string;
+    vault: NativeAmmLpVaultStorageSnapshot;
+    /** From share token minter slot. */
+    shareMinterHex: `0x${string}` | null;
+    /**
+     * Vault configured, share minter equals vault, stored share id matches **`shareHex32`**, and
+     * **`expectedPoolHex32`** when provided equals stored pool.
+     */
+    depositAddReady: boolean;
+    /** Human-readable blockers for UI (empty when **`depositAddReady`**). */
+    blockingReasons: string[];
+};
+/**
+ * Probe whether the **LP vault product path** is safe to expose (**`deposit_add`**): vault
+ * **`configure(pool, share)`** done and LP share **`set_minter_once`** set the vault as minter.
+ * Optional **`expectedPoolHex32`** enforces the configured pool matches integration defaults.
+ */
+export declare function fetchNativeAmmLpVaultProductReadiness(client: BoingClient, input: {
+    vaultHex32: string;
+    shareHex32: string;
+    expectedPoolHex32?: string | undefined;
+}): Promise<NativeAmmLpVaultProductReadiness>;
+export declare function encodeNativeAmmLpVaultConfigureCalldata(poolHex32: string, shareTokenHex32: string): Uint8Array;
+export declare function encodeNativeAmmLpVaultConfigureCalldataHex(poolHex32: string, shareTokenHex32: string): string;
+export declare function encodeNativeAmmLpVaultDepositAddCalldata(innerAddLiquidity128: Uint8Array, minLp: bigint): Uint8Array;
+export declare function encodeNativeAmmLpVaultDepositAddCalldataHex(innerAddLiquidity128: Uint8Array, minLp: bigint): string;
+/** `read` / `write`: signer + vault (parallel scheduling minimum for configure-only). */
+export declare function buildNativeAmmLpVaultConfigureAccessList(senderHex32: string, vaultHex32: string): {
+    read: string[];
+    write: string[];
+};
+/**
+ * `read` / `write`: signer + vault + pool + share token (`deposit_add` nested `Call`s).
+ */
+export declare function buildNativeAmmLpVaultDepositAddAccessList(senderHex32: string, vaultHex32: string, poolHex32: string, shareTokenHex32: string): {
+    read: string[];
+    write: string[];
+};
+export declare function mergeNativeAmmLpVaultConfigureAccessListWithSimulation(senderHex32: string, vaultHex32: string, sim: SimulateResult): {
+    read: string[];
+    write: string[];
+};
+export declare function mergeNativeAmmLpVaultDepositAddAccessListWithSimulation(senderHex32: string, vaultHex32: string, poolHex32: string, shareTokenHex32: string, sim: SimulateResult): {
+    read: string[];
+    write: string[];
+};
+export declare function buildNativeAmmLpVaultConfigureContractCallTx(senderHex32: string, vaultHex32: string, calldataHex: string): {
+    type: 'contract_call';
+    contract: string;
+    calldata: string;
+    access_list: {
+        read: string[];
+        write: string[];
+    };
+};
+export declare function buildNativeAmmLpVaultDepositAddContractCallTx(senderHex32: string, vaultHex32: string, poolHex32: string, shareTokenHex32: string, calldataHex: string): {
+    type: 'contract_call';
+    contract: string;
+    calldata: string;
+    access_list: {
+        read: string[];
+        write: string[];
+    };
+};
+//# sourceMappingURL=nativeAmmLpVault.d.ts.map

package/dist/nativeAmmLpVault.d.ts.map

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

package/dist/nativeAmmLpVault.js

@@ -0,0 +1,205 @@
+/**
+ * Native AMM LP vault calldata + Express / JSON-RPC access lists. Matches `boing_execution::native_amm_lp_vault`.
+ * See `docs/NATIVE-AMM-LP-VAULT.md`.
+ */
+import { mergeAccessListWithSimulation } from './accessList.js';
+import { bytesToHex, decodeBoingStorageWordAccountId, ensureHex, hexToBytes, validateHex32, } from './hex.js';
+import { decodeBoingStorageWordU128 } from './nativeAmmPool.js';
+import { fetchLpShareTokenMinterAccountHex } from './nativeLpShareToken.js';
+/** `configure(pool, share_token)` — **96** bytes. */
+export const SELECTOR_NATIVE_AMM_LP_VAULT_CONFIGURE = 0xc0;
+/** `deposit_add(inner_add_liquidity_128, min_lp)` — **192** bytes. */
+export const SELECTOR_NATIVE_AMM_LP_VAULT_DEPOSIT_ADD = 0xc1;
+function nativeAmmLpVaultStorageKeyHex(lastByte) {
+    const k = new Uint8Array(32);
+    k[31] = lastByte & 0xff;
+    return validateHex32(bytesToHex(k));
+}
+/** `boing_getContractStorage` — non-zero after successful **`configure`**. */
+export const NATIVE_AMM_LP_VAULT_KEY_CONFIGURED_HEX = nativeAmmLpVaultStorageKeyHex(0xd1);
+/** Configured native CP **pool** `AccountId`. */
+export const NATIVE_AMM_LP_VAULT_KEY_POOL_HEX = nativeAmmLpVaultStorageKeyHex(0xd2);
+/** Configured **LP share token** `AccountId`. */
+export const NATIVE_AMM_LP_VAULT_KEY_SHARE_TOKEN_HEX = nativeAmmLpVaultStorageKeyHex(0xd3);
+/**
+ * Read vault **`configure`** state from **`boing_getContractStorage`** (three parallel reads).
+ */
+export async function fetchNativeAmmLpVaultStorageSnapshot(client, vaultHex32) {
+    const vault = validateHex32(vaultHex32);
+    const [wc, wp, ws] = await Promise.all([
+        client.getContractStorage(vault, NATIVE_AMM_LP_VAULT_KEY_CONFIGURED_HEX),
+        client.getContractStorage(vault, NATIVE_AMM_LP_VAULT_KEY_POOL_HEX),
+        client.getContractStorage(vault, NATIVE_AMM_LP_VAULT_KEY_SHARE_TOKEN_HEX),
+    ]);
+    const configured = decodeBoingStorageWordU128(wc.value) !== 0n;
+    return {
+        configured,
+        poolHex: decodeBoingStorageWordAccountId(wp.value),
+        shareTokenHex: decodeBoingStorageWordAccountId(ws.value),
+    };
+}
+/**
+ * Probe whether the **LP vault product path** is safe to expose (**`deposit_add`**): vault
+ * **`configure(pool, share)`** done and LP share **`set_minter_once`** set the vault as minter.
+ * Optional **`expectedPoolHex32`** enforces the configured pool matches integration defaults.
+ */
+export async function fetchNativeAmmLpVaultProductReadiness(client, input) {
+    const vaultNorm = validateHex32(input.vaultHex32).toLowerCase();
+    const shareNorm = validateHex32(input.shareHex32).toLowerCase();
+    const expectedPool = input.expectedPoolHex32 != null && String(input.expectedPoolHex32).trim()
+        ? validateHex32(String(input.expectedPoolHex32).trim()).toLowerCase()
+        : undefined;
+    let vaultRpcOk = true;
+    let vaultRpcError;
+    let vault = {
+        configured: false,
+        poolHex: null,
+        shareTokenHex: null,
+    };
+    let shareMinterHex = null;
+    try {
+        vault = await fetchNativeAmmLpVaultStorageSnapshot(client, vaultNorm);
+    }
+    catch (e) {
+        vaultRpcOk = false;
+        vaultRpcError = e instanceof Error ? e.message : String(e);
+    }
+    let shareMinterReadError;
+    try {
+        shareMinterHex = await fetchLpShareTokenMinterAccountHex(client, shareNorm);
+    }
+    catch (e) {
+        shareMinterReadError = e instanceof Error ? e.message : String(e);
+    }
+    const blockingReasons = [];
+    if (!vaultRpcOk) {
+        blockingReasons.push(vaultRpcError != null ? `vault_storage: ${vaultRpcError}` : 'vault_storage: error');
+    }
+    if (!vault.configured) {
+        blockingReasons.push('vault_not_configured');
+    }
+    if (vault.shareTokenHex == null || vault.shareTokenHex.toLowerCase() !== shareNorm) {
+        blockingReasons.push('vault_share_mismatch');
+    }
+    if (expectedPool != null && (vault.poolHex == null || vault.poolHex.toLowerCase() !== expectedPool)) {
+        blockingReasons.push('vault_pool_mismatch');
+    }
+    if (shareMinterReadError != null) {
+        blockingReasons.push(`share_minter_read: ${shareMinterReadError}`);
+    }
+    else if (shareMinterHex == null || shareMinterHex.toLowerCase() !== vaultNorm) {
+        blockingReasons.push('share_minter_not_vault');
+    }
+    const depositAddReady = blockingReasons.length === 0;
+    return {
+        vaultRpcOk,
+        ...(vaultRpcError != null ? { vaultRpcError } : {}),
+        vault,
+        shareMinterHex,
+        depositAddReady,
+        blockingReasons: depositAddReady ? [] : blockingReasons,
+    };
+}
+function selectorWord(selector) {
+    const w = new Uint8Array(32);
+    w[31] = selector & 0xff;
+    return w;
+}
+const CALldata_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 (!CALldata_HEX_RE.test(raw)) {
+        throw new Error('calldata: invalid hex');
+    }
+    return `0x${raw.toLowerCase()}`;
+}
+function sortedUniqueAccounts(hex32List) {
+    const seen = new Set();
+    const out = [];
+    for (const x of hex32List) {
+        const h = validateHex32(x).toLowerCase();
+        if (!seen.has(h)) {
+            seen.add(h);
+            out.push(h);
+        }
+    }
+    out.sort();
+    return out;
+}
+function amountWord(amount) {
+    const w = new Uint8Array(32);
+    if (amount < 0n || amount > (1n << 128n) - 1n) {
+        throw new RangeError('amount must fit in u128');
+    }
+    const be = new Uint8Array(16);
+    let x = amount;
+    for (let i = 15; i >= 0; i--) {
+        be[i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+    w.set(be, 16);
+    return w;
+}
+export function encodeNativeAmmLpVaultConfigureCalldata(poolHex32, shareTokenHex32) {
+    const out = new Uint8Array(96);
+    out.set(selectorWord(SELECTOR_NATIVE_AMM_LP_VAULT_CONFIGURE));
+    out.set(hexToBytes(validateHex32(poolHex32)), 32);
+    out.set(hexToBytes(validateHex32(shareTokenHex32)), 64);
+    return out;
+}
+export function encodeNativeAmmLpVaultConfigureCalldataHex(poolHex32, shareTokenHex32) {
+    return bytesToHex(encodeNativeAmmLpVaultConfigureCalldata(poolHex32, shareTokenHex32));
+}
+export function encodeNativeAmmLpVaultDepositAddCalldata(innerAddLiquidity128, minLp) {
+    if (innerAddLiquidity128.length !== 128) {
+        throw new Error('inner add_liquidity calldata must be 128 bytes');
+    }
+    const out = new Uint8Array(192);
+    out.set(selectorWord(SELECTOR_NATIVE_AMM_LP_VAULT_DEPOSIT_ADD));
+    out.set(innerAddLiquidity128, 32);
+    out.set(amountWord(minLp), 160);
+    return out;
+}
+export function encodeNativeAmmLpVaultDepositAddCalldataHex(innerAddLiquidity128, minLp) {
+    return bytesToHex(encodeNativeAmmLpVaultDepositAddCalldata(innerAddLiquidity128, minLp));
+}
+/** `read` / `write`: signer + vault (parallel scheduling minimum for configure-only). */
+export function buildNativeAmmLpVaultConfigureAccessList(senderHex32, vaultHex32) {
+    const accounts = sortedUniqueAccounts([senderHex32, vaultHex32]);
+    return { read: accounts, write: [...accounts] };
+}
+/**
+ * `read` / `write`: signer + vault + pool + share token (`deposit_add` nested `Call`s).
+ */
+export function buildNativeAmmLpVaultDepositAddAccessList(senderHex32, vaultHex32, poolHex32, shareTokenHex32) {
+    const accounts = sortedUniqueAccounts([senderHex32, vaultHex32, poolHex32, shareTokenHex32]);
+    return { read: accounts, write: [...accounts] };
+}
+export function mergeNativeAmmLpVaultConfigureAccessListWithSimulation(senderHex32, vaultHex32, sim) {
+    const base = buildNativeAmmLpVaultConfigureAccessList(senderHex32, vaultHex32);
+    return mergeAccessListWithSimulation(base.read, base.write, sim);
+}
+export function mergeNativeAmmLpVaultDepositAddAccessListWithSimulation(senderHex32, vaultHex32, poolHex32, shareTokenHex32, sim) {
+    const base = buildNativeAmmLpVaultDepositAddAccessList(senderHex32, vaultHex32, poolHex32, shareTokenHex32);
+    return mergeAccessListWithSimulation(base.read, base.write, sim);
+}
+export function buildNativeAmmLpVaultConfigureContractCallTx(senderHex32, vaultHex32, calldataHex) {
+    return {
+        type: 'contract_call',
+        contract: validateHex32(vaultHex32).toLowerCase(),
+        calldata: normalizeCalldataHex(calldataHex),
+        access_list: buildNativeAmmLpVaultConfigureAccessList(senderHex32, vaultHex32),
+    };
+}
+export function buildNativeAmmLpVaultDepositAddContractCallTx(senderHex32, vaultHex32, poolHex32, shareTokenHex32, calldataHex) {
+    return {
+        type: 'contract_call',
+        contract: validateHex32(vaultHex32).toLowerCase(),
+        calldata: normalizeCalldataHex(calldataHex),
+        access_list: buildNativeAmmLpVaultDepositAddAccessList(senderHex32, vaultHex32, poolHex32, shareTokenHex32),
+    };
+}

package/dist/nativeAmmPool.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 type { BoingClient } from './client.js';
+import type { SimulateResult } from './types.js';
+/** Optional accounts merged into native CP `contract_call` access lists (forward-compatible). */
+export type NativePoolAccessListOptions = {
+    /**
+     * Extra 32-byte account ids (e.g. reference-token contracts). **Required** for **v2** pools on `swap` / `remove_liquidity` when token slots are set (pool `CALL`s those contracts).
+     * Duplicates and ids equal to sender/pool are ignored; extras are appended in sorted hex order after signer + pool.
+     */
+    additionalAccountsHex32?: string[];
+};
+/** `read` and `write` both include signer + pool (parallel-scheduling minimum for pool-only bytecode). */
+export declare function buildNativeConstantProductPoolAccessList(senderHex32: string, poolHex32: string, options?: NativePoolAccessListOptions): {
+    read: string[];
+    write: string[];
+};
+/** Params for `boing_sendTransaction` / Express `contract_call` with explicit access list. */
+export declare function buildNativeConstantProductContractCallTx(senderHex32: string, poolHex32: string, calldataHex: string, options?: NativePoolAccessListOptions): {
+    type: 'contract_call';
+    contract: string;
+    calldata: string;
+    access_list: {
+        read: string[];
+        write: string[];
+    };
+};
+/**
+ * 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 declare function buildNativeDexMultihopRouterAccessList(senderHex32: string, routerHex32: string, poolHex32List: readonly string[], options?: NativePoolAccessListOptions): {
+    read: string[];
+    write: string[];
+};
+/** Multihop router **`contract_call`** with {@link buildNativeDexMultihopRouterAccessList}. */
+export declare function buildNativeDexMultihopRouterContractCallTx(senderHex32: string, routerHex32: string, calldataHex: string, poolHex32List: readonly string[], options?: NativePoolAccessListOptions): {
+    type: 'contract_call';
+    contract: string;
+    calldata: string;
+    access_list: {
+        read: string[];
+        write: string[];
+    };
+};
+/**
+ * Widen multihop router access list with `sim.suggested_access_list` (e.g. after `boing_simulateTransaction`).
+ */
+export declare function mergeNativeDexMultihopRouterAccessListWithSimulation(senderHex32: string, routerHex32: string, poolHex32List: readonly string[], sim: SimulateResult, options?: NativePoolAccessListOptions): {
+    read: string[];
+    write: string[];
+};
+/**
+ * Widen `read`/`write` with `sim.suggested_access_list` (e.g. after `boing_simulateTransaction`).
+ */
+export declare function mergeNativePoolAccessListWithSimulation(senderHex32: string, poolHex32: string, sim: SimulateResult, options?: NativePoolAccessListOptions): {
+    read: string[];
+    write: string[];
+};
+/** `boing_getContractStorage` key for reserve A (`native_amm::reserve_a_key`). */
+export declare const NATIVE_CONSTANT_PRODUCT_RESERVE_A_KEY_HEX: `0x${string}01`;
+/** `boing_getContractStorage` key for reserve B (`native_amm::reserve_b_key`). */
+export declare const NATIVE_CONSTANT_PRODUCT_RESERVE_B_KEY_HEX: `0x${string}02`;
+/** Total LP supply key (`native_amm::total_lp_supply_key`, `k[31] == 0x03`). */
+export declare const NATIVE_CONSTANT_PRODUCT_TOTAL_LP_KEY_HEX: `0x${string}03`;
+/** **v2:** On-chain reference-token id for reserve side A (`token_a_key`, `k[31] == 0x04`). */
+export declare const NATIVE_CONSTANT_PRODUCT_TOKEN_A_KEY_HEX: `0x${string}04`;
+/** **v2:** Reference-token id for side B (`k[31] == 0x05`). */
+export declare const NATIVE_CONSTANT_PRODUCT_TOKEN_B_KEY_HEX: `0x${string}05`;
+/** **v2:** Non-zero after successful `set_tokens` (`k[31] == 0x06`). */
+export declare const NATIVE_CONSTANT_PRODUCT_TOKENS_CONFIGURED_KEY_HEX: `0x${string}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 declare const NATIVE_CONSTANT_PRODUCT_SWAP_FEE_BPS_KEY_HEX: `0x${string}07`;
+/**
+ * `boing_getContractStorage` key for the caller's LP balance (`native_amm::lp_balance_storage_key`).
+ */
+export declare function nativeAmmLpBalanceStorageKeyHex(senderHex32: string): string;
+/**
+ * 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 declare function decodeBoingStorageWordU128(valueHex: string): bigint;
+/**
+ * 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 declare function decodeNativeAmmAddLiquidityReturnLpMinted(returnDataHex: string): bigint;
+/**
+ * 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 declare function decodeNativeAmmLogDataU128Triple(dataHex: string): readonly [bigint, bigint, bigint];
+/**
+ * Read both in-ledger reserves for the MVP constant-product pool (`Promise.all` of two storage reads).
+ */
+export declare function fetchNativeConstantProductReserves(client: BoingClient, poolHex32: string): Promise<{
+    reserveA: bigint;
+    reserveB: bigint;
+}>;
+/** Single `boing_getContractStorage` read for **`total_lp_supply_key`**. */
+export declare function fetchNativeConstantProductTotalLpSupply(client: BoingClient, poolHex32: string): Promise<bigint>;
+/** **v3/v4:** Raw u128 at **`swap_fee_bps_key`**. Use **`0n`** → default fee **`NATIVE_CP_SWAP_FEE_BPS`** when quoting swaps. */
+export declare function fetchNativeConstantProductSwapFeeBps(client: BoingClient, poolHex32: string): Promise<bigint>;
+/** LP balance for **`signerHex32`** in **`poolHex32`** (XOR-derived storage key). */
+export declare function fetchNativeAmmSignerLpBalance(client: BoingClient, poolHex32: string, signerHex32: string): Promise<bigint>;
+export interface NativeConstantProductPoolSnapshot {
+    reserveA: bigint;
+    reserveB: bigint;
+    totalLpSupply: bigint;
+    /** Present only when **`options.signerHex32`** was set. */
+    signerLpBalance?: bigint;
+}
+/**
+ * One round-trip batch: reserves + total LP, and optionally the given signer's LP balance (**3** or **4** parallel storage reads).
+ */
+export declare function fetchNativeConstantProductPoolSnapshot(client: BoingClient, poolHex32: string, options?: {
+    signerHex32?: string;
+}): Promise<NativeConstantProductPoolSnapshot>;
+//# sourceMappingURL=nativeAmmPool.d.ts.map

package/dist/nativeAmmPool.d.ts.map

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