@ouronet/ouronet-core 4.3.6

package/dist/interactions/crossChainFunctions.js

@@ -0,0 +1,463 @@
+import { Pact } from "@stoachain/kadena-stoic-legacy/client";
+import { getFailoverClient, withFailover } from "@stoachain/stoa-core/network";
+import { KADENA_NETWORK, getPactUrl, STOA_AUTONOMIC_OURONETGASSTATION, KADENA_NAMESPACE } from "../constants/index.js";
+import { GAS_PRICE_MIN_ANU, anuToStoa } from "@stoachain/stoa-core/gas";
+import { pactRead } from "@stoachain/stoa-core/reads";
+import { safeCreationTime, formatDecimalForPact } from "@stoachain/stoa-core/pact";
+/**
+ * Get KDA balance for an account on a specific chain.
+ * exists=false means the account row does not exist on that chain (not just zero balance).
+ */
+export async function getBalanceOnChain(account, chainId, tier = "T1") {
+    try {
+        const pactCode = `(coin.get-balance "${account}")`;
+        const response = await pactRead(pactCode, {
+            pactUrl: getPactUrl(chainId),
+            chainId,
+            tier,
+        });
+        if (!response?.result || response.result.status === "failure") {
+            return { balance: "0", exists: false };
+        }
+        const data = response.result.data;
+        let balance = "0";
+        if (data) {
+            if (typeof data === "string") {
+                balance = data;
+            }
+            else if (typeof data === "number") {
+                balance = data.toString();
+            }
+            else if (typeof data === "object" && data.decimal) {
+                balance = data.decimal;
+            }
+            else if (typeof data === "object" && data.int) {
+                balance = data.int;
+            }
+        }
+        return { balance, exists: true };
+    }
+    catch (error) {
+        return {
+            balance: "0",
+            exists: false,
+            error: error instanceof Error ? error.message : "Failed to fetch balance",
+        };
+    }
+}
+/**
+ * Build a cross-chain transfer transaction (step 1)
+ * This creates a transaction that needs to be signed and submitted
+ */
+export function buildCrossChainTransfer(params) {
+    const { sender, receiver, receiverGuard, amount, sourceChain, targetChain, senderPublicKey, } = params;
+    // v3.2.1: replaced `parseFloat(amount).toFixed(12)` with the validated
+    // formatter to close audit finding F-BUG-003. The old form silently
+    // truncated precision on values past float64's ~15-17 significant digits
+    // (a 20-digit-fractional KDA amount would lose ~5 digits of precision)
+    // and silently rounded inputs that exceeded 12 decimals. The formatter
+    // preserves arbitrary precision (truncates at 24 decimals by default) and
+    // throws on malformed input rather than producing "NaN" downstream.
+    const formattedAmount = formatDecimalForPact(amount);
+    const receiverKeysetName = `receiver-guard-${Date.now()}`;
+    const transaction = Pact.builder
+        .execution(`(coin.transfer-crosschain "${sender}" "${receiver}" (read-keyset "${receiverKeysetName}") "${targetChain}" ${formattedAmount})`)
+        .addData(receiverKeysetName, receiverGuard)
+        .addSigner(senderPublicKey, (withCapability) => [
+        withCapability("coin.TRANSFER_XCHAIN", sender, receiver, {
+            decimal: formattedAmount,
+        }, targetChain),
+        withCapability("coin.GAS"),
+    ])
+        .setMeta({
+        chainId: sourceChain,
+        senderAccount: sender,
+        // v3.2.3: added `creationTime: safeCreationTime()` to close audit
+        // finding F-BUG-002. The v2.3.0 audit consolidated `safeCreationTime()`
+        // (returns `Date.now()/1000 - 30`) precisely so client-side clock drift
+        // doesn't trigger chain-side "creation time too far in the future"
+        // rejections; without this field, `@kadena/client` falls back to the
+        // raw current time and any consumer with a clock slightly ahead of
+        // node time gets sporadic submit failures. This was the lone builder
+        // in interactions/* that omitted the helper after the v2.3.0 sweep —
+        // every other setMeta block (including `buildCTransferAcross` two
+        // functions below) already includes it.
+        creationTime: safeCreationTime(),
+        gasLimit: 2500,
+        gasPrice: 0.00000001,
+        ttl: 28800,
+    })
+        .setNetworkId(KADENA_NETWORK)
+        .createTransaction();
+    return transaction;
+}
+/**
+ * Build a coin.C_TransferAcross transaction (step 0 of cross-chain transfer).
+ *
+ * Chain 0: Gas paid by Ouronet Gas Station (DALOS.GAS_PAYER).
+ * Other chains: Gas paid by kadena-xchain-gas (unsigned).
+ */
+export function buildCTransferAcross(params) {
+    const { sender, receiver, receiverGuard, amount, sourceChain, targetChain, senderPublicKey, gasStationPublicKey, } = params;
+    const keysetName = `receiver-guard-${Date.now()}`;
+    const pactCode = `(coin.C_TransferAcross "${sender}" "${receiver}" (read-keyset "${keysetName}") "${targetChain}" ${amount})`;
+    if (sourceChain === "0") {
+        // Chain 0: Gas Station pays via DALOS.GAS_PAYER
+        if (!gasStationPublicKey) {
+            throw new Error("gasStationPublicKey is required for chain 0 transfers");
+        }
+        return Pact.builder
+            .execution(pactCode)
+            .addData(keysetName, receiverGuard)
+            .addSigner(gasStationPublicKey, (w) => [
+            w(`${KADENA_NAMESPACE}.DALOS.GAS_PAYER`, "", { int: 0 }, { decimal: "0.0" }),
+        ])
+            .addSigner(senderPublicKey, (w) => [
+            w("coin.TRANSFER_XCHAIN", sender, receiver, { decimal: amount }, targetChain),
+        ])
+            .setMeta({
+            chainId: "0",
+            senderAccount: STOA_AUTONOMIC_OURONETGASSTATION,
+            creationTime: safeCreationTime(),
+            gasLimit: 2500,
+            gasPrice: anuToStoa(GAS_PRICE_MIN_ANU),
+            ttl: 28800,
+        })
+            .setNetworkId(KADENA_NETWORK)
+            .createTransaction();
+    }
+    else {
+        // Non-chain-0: kadena-xchain-gas pays gas.
+        // Its guard uses coin.gas-only (no signature needed) BUT requires:
+        //   - gasPrice <= 0.00000001
+        //   - gasLimit <= 850
+        // No signer needed for gas — only sender signs TRANSFER_XCHAIN cap.
+        return Pact.builder
+            .execution(pactCode)
+            .addData(keysetName, receiverGuard)
+            .addSigner(senderPublicKey, (w) => [
+            w("coin.TRANSFER_XCHAIN", sender, receiver, { decimal: amount }, targetChain),
+        ])
+            .setMeta({
+            chainId: sourceChain,
+            senderAccount: "kadena-xchain-gas",
+            gasLimit: 850, // must be ≤ 850 for kadena-xchain-gas guard
+            gasPrice: 0.00000001, // must be ≤ 0.00000001 for kadena-xchain-gas guard
+            ttl: 28800,
+        })
+            .setNetworkId(KADENA_NETWORK)
+            .createTransaction();
+    }
+}
+/**
+ * Submit a cross-chain transfer and get the request key.
+ *
+ * Resolves to the chainweb `ITransactionDescriptor` (request key + chain id +
+ * network id) for the submitted transaction. Caller is responsible for
+ * persisting the descriptor — it's the only handle for `pollTransactionStatus`,
+ * `fetchSpvProof`, and `submitContinuation` later in the cross-chain flow.
+ *
+ * **Error contract** (closes audit finding F-ERR-001 — v3.2.3):
+ *
+ * Unlike its sibling `pollTransactionStatus` (which catches errors and
+ * returns `{ status: "pending", error: ... }` — the codebase's discriminated-
+ * union convention), this function deliberately propagates errors rather
+ * than swallowing them. A failed submit is not a transient state to poll
+ * past — it means the transaction did NOT land on chain, and the caller's
+ * UI must surface that as a hard failure (refund the user's escrowed gas
+ * estimate, present a retry button, etc.). Wrapping the throw in an
+ * envelope would mask the failure.
+ *
+ * @throws {SigningError} with `code: "TIMEOUT"` if the underlying
+ *   `submit()` exceeds the per-tier deadline (default 60s for submit).
+ *   See `runWithTimeout` in `src/network/failoverClient.ts`.
+ * @throws {Error} On network failure that survives both the primary and
+ *   fallback node attempts. Both errors propagate verbatim from
+ *   `getFailoverClient`'s submit method — the caller's catch block
+ *   should distinguish via `error instanceof SigningError && error.code === "TIMEOUT"`.
+ */
+export async function submitCrossChainTransfer(signedTransaction, sourceChain) {
+    const { submit } = getFailoverClient(sourceChain);
+    return await submit(signedTransaction);
+}
+/**
+ * Poll for transaction status on source chain
+ */
+export async function pollTransactionStatus(requestKey, chainId) {
+    try {
+        const { pollOne } = getFailoverClient(chainId);
+        const result = await pollOne({ requestKey, chainId: chainId, networkId: KADENA_NETWORK });
+        if (!result) {
+            return { status: "pending" };
+        }
+        if (result.result.status === "failure") {
+            return {
+                status: "failure",
+                error: result.result.error?.message || "Transaction failed",
+                result,
+            };
+        }
+        // Check if this is a defpact with continuation info
+        const continuation = result.continuation ? {
+            pactId: result.continuation.pactId,
+            step: result.continuation.step,
+            stepHasRollback: result.continuation.stepHasRollback,
+        } : undefined;
+        return {
+            status: "success",
+            continuation,
+            result,
+        };
+    }
+    catch (error) {
+        return {
+            status: "pending",
+            error: error instanceof Error ? error.message : "Unknown error",
+        };
+    }
+}
+/**
+ * Default per-attempt timeout for `fetchSpvProof` in milliseconds. Picked to
+ * be longer than the chainweb dirty-read default (15s) since SPV proof
+ * generation may pull from disk on the node, but short enough that a wedged
+ * primary node doesn't hang the consumer's retry loop. The `pollSpvProof`
+ * outer loop adds its own retry budget on top of this per-attempt cap.
+ *
+ * Added in v3.2.3 to close audit finding F-BUG-004.
+ */
+const SPV_PROOF_TIMEOUT_MS = 30000;
+/**
+ * Fetch SPV proof for a cross-chain transfer.
+ *
+ * Requires waiting for block finality (~100-120 seconds). The on-chain
+ * proof becomes available a few blocks after the source-chain submit
+ * commits; before that, the chainweb node returns `400 not available`.
+ *
+ * v3.2.3 (closes audit finding F-BUG-004): wrapped in `withFailover` and
+ * `AbortSignal.timeout(SPV_PROOF_TIMEOUT_MS)`. Pre-v3.2.3, this was the
+ * only chain-RPC function in the entire codebase that called raw `fetch()`
+ * without either guard:
+ *
+ *   - No `AbortController`: a wedged primary node (slow, not erroring)
+ *     would hang the `await fetch(...)` indefinitely. The outer
+ *     `pollSpvProof` retry loop never advanced because each attempt
+ *     awaited the hung fetch.
+ *
+ *   - No `withFailover`: even if the primary node returned an error or
+ *     timed out, traffic stayed pinned to the primary; the consumer's
+ *     subsequent attempts hit the same wedged node forever.
+ *
+ *   - Combined consequence: the user's KDA was committed to
+ *     `kadena-xchain-gas` escrow on the source chain (step 1 succeeded),
+ *     but step 2's SPV proof retrieval hung silently with the UI showing
+ *     a perpetual "Waiting for SPV proof..." spinner and no recovery
+ *     path. This is the highest-impact bug surfaced by the 2026-05-05
+ *     audit.
+ *
+ * Post-v3.2.3 behaviour: each attempt has a hard 30s deadline; on timeout
+ * (or any network-class error on the primary node), `withFailover`
+ * switches to the fallback node and retries once. The outer
+ * `pollSpvProof` loop then re-invokes this function after the configured
+ * `delayMs` (default 5s), so a stuck primary surfaces as ~30s of
+ * waiting, then automatic fallback, then continued polling — never an
+ * infinite hang.
+ */
+export async function fetchSpvProof(requestKey, sourceChain, targetChain) {
+    try {
+        const response = await withFailover((baseUrl) => fetch(`${baseUrl}/chain/${sourceChain}/pact/spv`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                requestKey,
+                targetChainId: targetChain,
+            }),
+            signal: AbortSignal.timeout(SPV_PROOF_TIMEOUT_MS),
+        }));
+        if (!response.ok) {
+            const errorText = await response.text();
+            // Chainweb returns 400 "not available" while the proof is still being
+            // generated (pre-finality). pollSpvProof's outer loop translates this
+            // into "wait and try again" — pass null + descriptive error.
+            if (response.status === 400 && errorText.includes("not available")) {
+                return { proof: null, error: "SPV proof not ready yet. Please wait for block confirmation." };
+            }
+            return { proof: null, error: `Failed to fetch SPV proof: ${errorText}` };
+        }
+        const proof = await response.text();
+        // Remove quotes if present (API returns JSON string)
+        const cleanProof = proof.replace(/^"|"$/g, "");
+        return { proof: cleanProof };
+    }
+    catch (error) {
+        // AbortError surfaces here when the 30s timeout fires. withFailover
+        // will already have retried on fallback by this point — if BOTH primary
+        // and fallback timed out (or otherwise failed), the error propagates
+        // out as the standard `{ proof: null, error }` shape so the polling
+        // loop above can decide whether to retry the whole sequence.
+        const message = error instanceof Error
+            ? (error.name === "TimeoutError" || error.name === "AbortError"
+                ? `SPV proof fetch timed out after ${SPV_PROOF_TIMEOUT_MS}ms (both primary and fallback nodes)`
+                : error.message)
+            : "Failed to fetch SPV proof";
+        return {
+            proof: null,
+            error: message,
+        };
+    }
+}
+/**
+ * Poll for SPV proof with retry logic
+ * Will retry until proof is available or max attempts reached
+ */
+export async function pollSpvProof(requestKey, sourceChain, targetChain, maxAttempts = 30, delayMs = 5000, onProgress) {
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        onProgress?.(attempt, maxAttempts);
+        const result = await fetchSpvProof(requestKey, sourceChain, targetChain);
+        if (result.proof) {
+            return result;
+        }
+        if (attempt < maxAttempts) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    return { proof: null, error: "Timeout waiting for SPV proof" };
+}
+/**
+ * Build a continuation transaction for step 2 of cross-chain transfer
+ * This can be executed by anyone - no signature required from original sender
+ */
+export function buildContinuationTransaction(pactId, proof, targetChain, gasPayerAccount = "kadena-xchain-gas") {
+    const transaction = Pact.builder
+        .continuation({
+        pactId,
+        rollback: false,
+        step: 1,
+        proof,
+    })
+        .setMeta({
+        chainId: targetChain,
+        senderAccount: gasPayerAccount,
+        gasLimit: 850,
+        gasPrice: 0.00000001,
+        ttl: 28800,
+    })
+        .setNetworkId(KADENA_NETWORK)
+        .createTransaction();
+    return transaction;
+}
+/**
+ * Submit a continuation transaction.
+ *
+ * Note: for the public gas station path (chain 0 + DALOS.GAS_PAYER), no
+ * signature is needed — the caller passes the unsigned `transaction`
+ * directly. For user-paid-gas paths the transaction MUST be signed before
+ * this function is called; the function itself does not sign.
+ *
+ * **Error contract** (closes audit finding F-ERR-001 — v3.2.3): same
+ * propagating-throw pattern as `submitCrossChainTransfer`. A failed
+ * continuation submit is a hard failure, not a transient state — surface
+ * to the user, don't swallow.
+ *
+ * @throws {SigningError} with `code: "TIMEOUT"` if `submit()` exceeds
+ *   the per-tier deadline.
+ * @throws {Error} On network failure surviving both primary and fallback
+ *   node attempts.
+ */
+export async function submitContinuation(transaction, targetChain) {
+    const { submit } = getFailoverClient(targetChain);
+    return await submit(transaction);
+}
+/**
+ * Listen for transaction completion (long-poll for chainweb inclusion).
+ *
+ * Resolves to the chainweb command-result envelope when the transaction
+ * is included in a block (~30-180s on mainnet depending on block density).
+ *
+ * **Error contract** (closes audit finding F-ERR-001 — v3.2.3): a thrown
+ * error from this function is **NOT** a definitive failure. The chainweb
+ * `listen` endpoint times out after a per-tier deadline (default 180s,
+ * approximately 6 Kadena blocks); if the deadline fires, the transaction
+ * may still complete on chain — it just hasn't been included yet by the
+ * time this function gives up. Callers should treat a `SigningError(code:
+ * "TIMEOUT")` from this function as `status: "pending"` (poll again
+ * later via `pollTransactionStatus`), NOT as `status: "failed"` (do not
+ * retry the submit; it would double-pay gas for a transaction that may
+ * already be confirmed). This is the exact pattern that audit finding
+ * F-ERR-014 surfaced for the multi-step add-liquidity flow before that
+ * surface was deleted in v3.2.2.
+ *
+ * @throws {SigningError} with `code: "TIMEOUT"` if `listen()` exceeds
+ *   the 180s deadline. **Treat as pending, not failed.**
+ * @throws {Error} On network failure surviving both primary and fallback
+ *   node attempts.
+ */
+export async function listenForCompletion(requestKey, chainId) {
+    const { listen } = getFailoverClient(chainId);
+    return await listen({ requestKey, chainId: chainId, networkId: KADENA_NETWORK });
+}
+/**
+ * Simulate a Pact code execution to check if it will succeed.
+ *
+ * Public-API break (v1.8): the first parameter is now the raw Pact code string
+ * rather than a built transaction. Consumers that previously held the built
+ * transaction now hold the pact-code string they fed into `.execution(...)`.
+ */
+export async function simulateTransaction(pactCode, chainId) {
+    try {
+        const result = await pactRead(pactCode, {
+            pactUrl: getPactUrl(chainId),
+            chainId,
+            tier: "T2",
+        });
+        if (result.result.status === "failure") {
+            return {
+                success: false,
+                error: result.result.error?.message || "Simulation failed",
+                result,
+            };
+        }
+        return {
+            success: true,
+            result,
+            gas: result.gas,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : "Simulation failed",
+        };
+    }
+}
+/**
+ * Get pending cross-chain transfers for an account
+ * Checks for continuation status
+ */
+export async function getContinuationStatus(requestKey, sourceChain) {
+    try {
+        const status = await pollTransactionStatus(requestKey, sourceChain);
+        if (status.status === "not-found") {
+            return { exists: false, completed: false, error: "Transaction not found" };
+        }
+        if (status.status === "failure") {
+            return { exists: true, completed: false, error: status.error };
+        }
+        if (status.continuation) {
+            return {
+                exists: true,
+                completed: false,
+                pactId: status.continuation.pactId,
+                step: status.continuation.step,
+            };
+        }
+        // If no continuation info, transaction might be complete
+        return { exists: true, completed: true };
+    }
+    catch (error) {
+        return {
+            exists: false,
+            completed: false,
+            error: error instanceof Error ? error.message : "Unknown error",
+        };
+    }
+}

package/dist/interactions/dexAcquisitionPoolFunctions.d.ts

@@ -0,0 +1,18 @@
+/**
+ * dexAcquisitionPoolFunctions.ts
+ *
+ * Acquisition Pool (AP) entity — placeholder file.
+ *
+ * The Acquisition Pool is one of Ouronet's seven entity types per the locked
+ * taxonomy (TF, OF, Collectables [Semi+Non Fungibles], ASP, SWP, AP). Its Pact
+ * module is **pending deployment** — chain-call functions for read/execute
+ * surfaces will be added to this file once the AP Pact module ships.
+ *
+ * This placeholder anchors the AP entity in the entity-oriented file layout so
+ * downstream consumers (OuronetUI, AncientHolder HUB) can see the entity exists
+ * in the taxonomy even though no chain calls are wired yet.
+ *
+ * See the v4.2.0 integration guide (Phase 8) for the seven-entity taxonomy
+ * documentation and AP-specific roadmap notes.
+ */
+export {};

package/dist/interactions/dexAcquisitionPoolFunctions.js

@@ -0,0 +1,18 @@
+/**
+ * dexAcquisitionPoolFunctions.ts
+ *
+ * Acquisition Pool (AP) entity — placeholder file.
+ *
+ * The Acquisition Pool is one of Ouronet's seven entity types per the locked
+ * taxonomy (TF, OF, Collectables [Semi+Non Fungibles], ASP, SWP, AP). Its Pact
+ * module is **pending deployment** — chain-call functions for read/execute
+ * surfaces will be added to this file once the AP Pact module ships.
+ *
+ * This placeholder anchors the AP entity in the entity-oriented file layout so
+ * downstream consumers (OuronetUI, AncientHolder HUB) can see the entity exists
+ * in the taxonomy even though no chain calls are wired yet.
+ *
+ * See the v4.2.0 integration guide (Phase 8) for the seven-entity taxonomy
+ * documentation and AP-specific roadmap notes.
+ */
+export {};

package/dist/interactions/dexCollectablesFunctions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * dexCollectablesFunctions.ts
+ * Collectables (Semi + Non Fungibles) entity reads — header, entries, nonce data, sets, filters, button state.
+ */
+import type { CollectablesHeaderData, CollectableEntryData, NonceData, SetDefinition, CollectablesButtonState } from "./dexTypes.js";
+export declare function getCollectablesHeader(account: string): Promise<CollectablesHeaderData | null>;
+export declare function getSemifungibleEntries(account: string, dpdcIds: string[]): Promise<(CollectableEntryData | null)[]>;
+export declare function getNonfungibleEntries(account: string, dpdcIds: string[]): Promise<(CollectableEntryData | null)[]>;
+export declare function getCollectableNonceData(dpdcId: string, isSFT: boolean, nonces: number[]): Promise<NonceData[]>;
+export declare function getCollectableNonceSupply(dpdcId: string, isSFT: boolean, nonce: number): Promise<number>;
+/**
+ * Batched per-account per-nonce supplies (DPDC.UR_AccountNoncesSupplies).
+ * Replaces the per-nonce UR_NonceSupply loop with a single read for N nonces.
+ */
+export declare function getAccountNoncesSupplies(account: string, dpdcId: string, isSFT: boolean, nonces: number[]): Promise<number[]>;
+export declare function getCollectableSets(dpdcId: string, isSFT: boolean): Promise<SetDefinition[]>;
+/**
+ * Filter wallet nonces by nonce class for composite set positions.
+ * Returns only the nonces that match the given class.
+ */
+export declare function filterNoncesByClass(dpdcId: string, isSFT: boolean, nonces: number[], nonceClass: number): Promise<number[]>;
+/**
+ * Batched filter-nonces-by-classes (URC_0025a_FilterNoncesByClasses).
+ * One network call returns one filtered nonce list per class, in order.
+ * Replaces N per-position calls to filterNoncesByClass.
+ */
+export declare function filterNoncesByClasses(dpdcId: string, isSFT: boolean, nonces: number[], nonceClasses: number[]): Promise<number[][]>;
+export declare function getCollectablesButtonState(account: string, dpdcId: string, isSFT: boolean, selectedNonces: number[]): Promise<CollectablesButtonState | null>;