@ouronet/ouronet-core 4.3.6

package/dist/interactions/kpayFunctions.js

@@ -0,0 +1,191 @@
+import { calculateAutoGasLimit } from "@stoachain/stoa-core/gas";
+import { KADENA_CHAIN_ID, KADENA_NAMESPACE, STOA_AUTONOMIC_OURONETGASSTATION, KADENA_NETWORK, } from "../constants/index.js";
+import { Pact } from "@stoachain/kadena-stoic-legacy/client";
+import { getFailoverClient } from "@stoachain/stoa-core/network";
+import { pactRead } from "@stoachain/stoa-core/reads";
+import { universalSignTransaction, fromKeypair } from "@stoachain/stoa-core/signing";
+import { safeCreationTime } from "@stoachain/stoa-core/pact";
+import { getLogger } from "@stoachain/stoa-core/observability";
+/**
+ * Get KPay data for a specific Ouro account
+ * @param account - Ouro account address
+ * @returns KPay data object or null on failure
+ */
+export async function getKpayData(account) {
+    try {
+        const response = await pactRead(`(${KADENA_NAMESPACE}.DEMIPAD-KPAY.UR_Kpay "${account}")`, { tier: "T5" });
+        if (!response || !response.result || response.result.status === "failure") {
+            return null;
+        }
+        return response.result.data;
+    }
+    catch (error) {
+        getLogger().error("Error getting KPay data:", error);
+        return null;
+    }
+}
+/**
+ * Get cost for specific amount of KPAY tokens with future price projection
+ * @param amount - Amount of KPAY tokens (integer)
+ * @param futureSeconds - Seconds in the future to calculate price (default 900 = 15 minutes)
+ * @returns Object with pid (price in dollars) and wkda (WSTOA amount) or null
+ */
+export async function getKpayAmountCosts(amount, futureSeconds = 900.0) {
+    try {
+        const integerAmount = Math.floor(amount);
+        const response = await pactRead(`(${KADENA_NAMESPACE}.DEMIPAD-KPAY.URC_KpayAmountCosts ${integerAmount} ${futureSeconds})`, { tier: "T6" });
+        if (!response || !response.result || response.result.status === "failure") {
+            return null;
+        }
+        return response.result.data;
+    }
+    catch (error) {
+        getLogger().error("Error getting KPay amount costs:", error);
+        return null;
+    }
+}
+/**
+ * Get required capabilities for KPAY acquisition
+ * @param buyer - Buyer Ouro account address
+ * @param amount - Amount of KPAY tokens (integer)
+ * @param isNative - true for KDA native, false for WSTOA
+ * @returns Array of capability strings or null
+ */
+export async function getKpayAcquireCapabilities(buyer, amount, isNative) {
+    try {
+        const integerAmount = Math.floor(amount);
+        const response = await pactRead(`(${KADENA_NAMESPACE}.DEMIPAD-KPAY.URC_Acquire "${buyer}" ${integerAmount} ${isNative})`, { tier: "T5" });
+        if (!response || !response.result || response.result.status === "failure") {
+            return null;
+        }
+        return response.result.data;
+    }
+    catch (error) {
+        getLogger().error("Error getting KPay acquire capabilities:", error);
+        return null;
+    }
+}
+/**
+ * Parse capability string from blockchain format to withCapability format
+ * @param capString - Capability string like "<(coin.TRANSFER \"k:...\" \"c:...\" 46.298)>"
+ * @returns Parsed capability object or null
+ */
+function parseCapabilityString(capString) {
+    try {
+        // Remove < > wrapper and extra whitespace
+        const cleaned = capString.replace(/^<\s*|\s*>$/g, '').trim();
+        // Pattern for: (coin.TRANSFER "from" "to" amount)
+        // More flexible regex that allows dots, pipes, and other chars in module names
+        const regex = /\(([^\s]+)\s+"([^"]+)"\s+"([^"]+)"\s+([\d.]+)\)/;
+        const match = cleaned.match(regex);
+        if (!match) {
+            return null;
+        }
+        const [, name, from, to, amount] = match;
+        // For coin.TRANSFER, format args as [from, to, { decimal: amount }]
+        if (name === "coin.TRANSFER") {
+            return {
+                name,
+                args: [from, to, { decimal: amount }]
+            };
+        }
+        // Generic fallback for other capabilities
+        return {
+            name,
+            args: [from, to, { decimal: amount }]
+        };
+    }
+    catch (error) {
+        getLogger().error("Error parsing capability string:", error);
+        return null;
+    }
+}
+/**
+ * Buy KPAY tokens with KDA or WSTOA
+ * @param patronAccount - Patron Ouro account
+ * @param buyerAccount - Buyer Ouro address (usually same as patron)
+ * @param kpayAmount - Amount of KPAY tokens to buy (integer)
+ * @param isNative - true for KDA native, false for WSTOA
+ * @param kadenaAccount - Kadena account for gas and payments
+ * @param guardAccount - Guard account from Ouro account
+ * @returns Transaction result
+ */
+export async function kpayBuy(patronAccount, buyerAccount, kpayAmount, isNative, kadenaAccount, guardAccount, guardKeyset) {
+    const keysetName = `ks`;
+    // 1. Convert to integer
+    const integerAmount = Math.floor(kpayAmount);
+    // 2. Get required capabilities from blockchain
+    const capabilitiesStrings = await getKpayAcquireCapabilities(buyerAccount, integerAmount, isNative);
+    if (!capabilitiesStrings || capabilitiesStrings.length === 0) {
+        throw new Error("Failed to retrieve capabilities for KPAY purchase");
+    }
+    // 3. Parse capabilities
+    const parsedCapabilities = [];
+    for (const capString of capabilitiesStrings) {
+        const parsed = parseCapabilityString(capString);
+        if (parsed) {
+            parsedCapabilities.push(parsed);
+        }
+    }
+    if (parsedCapabilities.length === 0) {
+        throw new Error("Failed to parse any capabilities for KPAY purchase");
+    }
+    let gasLimit = 2000000; // Default gas limit for KPAY buy
+    // 4. Build transaction
+    const buildTransaction = (gasLimitOverride) => {
+        return Pact.builder
+            .execution(`(${KADENA_NAMESPACE}.TS02-DPAD.KPAY|C_BuyKpay "${patronAccount.address}" "${buyerAccount}" ${integerAmount} ${isNative})`)
+            .addData(keysetName, {
+            keys: guardKeyset.keys,
+            pred: guardKeyset.pred,
+        })
+            .setMeta({
+            senderAccount: STOA_AUTONOMIC_OURONETGASSTATION,
+            creationTime: safeCreationTime(), // Gas station
+            chainId: KADENA_CHAIN_ID,
+            gasLimit: gasLimitOverride || gasLimit,
+        })
+            .setNetworkId(KADENA_NETWORK)
+            .addSigner(kadenaAccount.publicKey, (withCapability) => {
+            const capabilities = [];
+            // Always add GAS_PAYER first
+            capabilities.push(withCapability(`${KADENA_NAMESPACE}.DALOS.GAS_PAYER`, "", { int: 0 }, { decimal: "0.0" }));
+            // Add all parsed capabilities from URC_Acquire
+            for (const cap of parsedCapabilities) {
+                try {
+                    const addedCap = withCapability(cap.name, ...cap.args);
+                    capabilities.push(addedCap);
+                }
+                catch (error) {
+                    getLogger().error(`Failed to add capability: ${cap.name}`, error);
+                }
+            }
+            return capabilities;
+        })
+            .addSigner(guardAccount.publicKey)
+            .createTransaction();
+    };
+    const { dirtyRead, submit } = getFailoverClient(KADENA_CHAIN_ID);
+    // 5. Build and simulate UNSIGNED to check gas
+    let transaction = buildTransaction();
+    const simulation = await dirtyRead(transaction);
+    // Check if simulation failed
+    if (simulation.result.status === "failure") {
+        const errorMessage = simulation.result.error?.message || "Transaction simulation failed";
+        throw new Error(`KPAY purchase simulation failed: ${errorMessage}`);
+    }
+    // 6. Adjust gas limit if needed
+    const requiredGas = simulation.gas;
+    if (requiredGas && requiredGas > gasLimit) {
+        gasLimit = calculateAutoGasLimit(requiredGas); // 20% buffer
+        transaction = buildTransaction(gasLimit);
+    }
+    // 7. Sign the transaction with both keypairs
+    const signedTransaction = await universalSignTransaction(transaction, [
+        fromKeypair(kadenaAccount),
+        fromKeypair(guardAccount),
+    ]);
+    // 8. Submit the signed transaction
+    const result = await submit(signedTransaction);
+    return result;
+}

package/dist/interactions/ouroAccountFunctions.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ouroAccountFunctions.ts
+ * Selector / overview / guard / ledger reads against the ouronet-ns DALOS / DPL-UR / DSP / TFT modules.
+ */
+import type { IKeyset } from "@stoachain/stoa-core/guard";
+import type { AccountSelectorData, StoaAccountSelectorData, AccountOverviewData, StoicTagSelectorData } from "./ouroTypes.js";
+export declare function getAccountSelectorData(accounts: string[], options?: {
+    skipTempWatcher?: boolean;
+}): Promise<AccountSelectorData[]>;
+/**
+ * Inverse StoicTag read — batch resolve a list of tag names to their on-chain
+ * status (existence / active / released) and bound Ouronet account, via
+ * `URC_0027b_StoicTagSelectorMapper`. Used by Address Book StoicTag entries,
+ * which watch a tag independently of any codex account. Returns one row per
+ * input tag, in order. Empty input → empty array.
+ */
+export declare function getStoicTagSelectorData(tagNames: string[]): Promise<StoicTagSelectorData[]>;
+/**
+ * Inverse StoicTag read — single tag name, via
+ * `URC_0027c_StoicTagSelectorSingle`. Returns `null` only on a read failure;
+ * a never-registered tag still resolves to a row with
+ * `iz-never-registered: true`.
+ */
+export declare function getStoicTagInfo(tagName: string): Promise<StoicTagSelectorData | null>;
+export interface RegisterStoicTagFullInfo {
+    /** The raw INFO_RegisterStoicTag ClientInfo (ignis + kadena/STOA split, text). */
+    info: any;
+    /** Split receiver k:/c: addresses — `kadena-targets` resolved via UR_AccountKadena. */
+    receivers: string[];
+}
+/**
+ * Full INFO for registering a StoicTag — fetches INFO_RegisterStoicTag AND
+ * resolves the STOA-split target Ouronet accounts (`kadena.kadena-targets`) to
+ * their actual k:/c: payment addresses in one read (mirrors
+ * getDeployStandardAccountInfo). The amounts live in `info.kadena.kadena-split`.
+ * Used to build the `coin.TRANSFER` capabilities the patron's payment key signs.
+ */
+export declare function getRegisterStoicTagInfo(patron: string, tagName: string, account: string): Promise<RegisterStoicTagFullInfo | null>;
+export declare function getStoaAccountSelectorData(accounts: string[]): Promise<StoaAccountSelectorData[]>;
+export declare function getAccountOverview(account: string): Promise<AccountOverviewData | null>;
+export declare function isAdministrativePause(): Promise<boolean>;
+export declare function kadenaLedger(address: string): Promise<any>;
+export declare const getKadenaAccountOwner: (address: string) => Promise<string | null>;
+export declare const readKeyset: (namespace: string, keysetName: string) => Promise<any>;
+/**
+ * Resolve a guard value — if it's a keyset ref, fetch the actual keyset.
+ * Handles both direct keyset objects and {keysetref: {ns, ksn}} references.
+ *
+ * Normalises the chain-native lowercase `keysetref` field to camelCase
+ * `keysetRef` at this boundary via `normalizeKeysetRef`, so internal code
+ * that follows downstream of `resolveGuard` only ever sees the camelCase
+ * form. The lowercase field is preserved for backwards-compat with
+ * existing reads.
+ */
+export declare function resolveGuard(guardData: any): Promise<any>;
+export declare const getKadenaAccountGuard: (address: string) => Promise<IKeyset | null>;
+export declare function getOuronetKdaDetails(address: string): Promise<any>;
+export declare function primordialPrices(): Promise<any>;
+export declare function eliteAccount(address: string): Promise<any>;
+export declare function filterKeysForInfo(address: string, table?: number, mode?: boolean): Promise<any>;
+export declare function usagePrice(tokenType?: string): Promise<any>;
+export declare function getHeaderData(address?: string, options?: {
+    skipTempWatcher?: boolean;
+}): Promise<any>;

package/dist/interactions/ouroAccountFunctions.js

@@ -0,0 +1,229 @@
+/**
+ * ouroAccountFunctions.ts
+ * Selector / overview / guard / ledger reads against the ouronet-ns DALOS / DPL-UR / DSP / TFT modules.
+ */
+import { KADENA_NAMESPACE } from "../constants/index.js";
+import { normalizeKeysetRef } from "@stoachain/stoa-core/guard";
+import { pactRead } from "@stoachain/stoa-core/reads";
+import { getLogger } from "@stoachain/stoa-core/observability";
+export async function getAccountSelectorData(accounts, options) {
+    const accountsList = accounts.map(a => `"${a}"`).join(" ");
+    const pactCode = `(${KADENA_NAMESPACE}.DPL-UR.URC_0027_AccountSelectorMapper [${accountsList}])`;
+    const response = await pactRead(pactCode, { tier: "T5", skipTempWatcher: options?.skipTempWatcher });
+    if (!response?.result || response.result.status === "failure") {
+        getLogger().error("AccountSelectorMapper failed:", response);
+        return [];
+    }
+    return response.result?.data ?? [];
+}
+/**
+ * Inverse StoicTag read — batch resolve a list of tag names to their on-chain
+ * status (existence / active / released) and bound Ouronet account, via
+ * `URC_0027b_StoicTagSelectorMapper`. Used by Address Book StoicTag entries,
+ * which watch a tag independently of any codex account. Returns one row per
+ * input tag, in order. Empty input → empty array.
+ */
+export async function getStoicTagSelectorData(tagNames) {
+    if (tagNames.length === 0)
+        return [];
+    const tagList = tagNames.map(t => `"${t}"`).join(" ");
+    const pactCode = `(${KADENA_NAMESPACE}.DPL-UR.URC_0027b_StoicTagSelectorMapper [${tagList}])`;
+    const response = await pactRead(pactCode, { tier: "T5" });
+    if (!response?.result || response.result.status === "failure") {
+        getLogger().error("StoicTagSelectorMapper failed:", response);
+        return [];
+    }
+    return response.result?.data ?? [];
+}
+/**
+ * Inverse StoicTag read — single tag name, via
+ * `URC_0027c_StoicTagSelectorSingle`. Returns `null` only on a read failure;
+ * a never-registered tag still resolves to a row with
+ * `iz-never-registered: true`.
+ */
+export async function getStoicTagInfo(tagName) {
+    if (!tagName)
+        return null;
+    const pactCode = `(${KADENA_NAMESPACE}.DPL-UR.URC_0027c_StoicTagSelectorSingle "${tagName}")`;
+    const response = await pactRead(pactCode, { tier: "T5" });
+    if (!response?.result || response.result.status === "failure") {
+        getLogger().error("StoicTagSelectorSingle failed:", response);
+        return null;
+    }
+    return response.result?.data ?? null;
+}
+/**
+ * Full INFO for registering a StoicTag — fetches INFO_RegisterStoicTag AND
+ * resolves the STOA-split target Ouronet accounts (`kadena.kadena-targets`) to
+ * their actual k:/c: payment addresses in one read (mirrors
+ * getDeployStandardAccountInfo). The amounts live in `info.kadena.kadena-split`.
+ * Used to build the `coin.TRANSFER` capabilities the patron's payment key signs.
+ */
+export async function getRegisterStoicTagInfo(patron, tagName, account) {
+    if (!patron || !tagName || !account)
+        return null;
+    try {
+        const pactCode = `(let*` +
+            `  ((info (${KADENA_NAMESPACE}.CODEX.CODEX|INFO_RegisterStoicTag "${patron}" "${tagName}" "${account}"))` +
+            `   (receivers (map (${KADENA_NAMESPACE}.DALOS.UR_AccountKadena) (at "kadena-targets" (at "kadena" info)))))` +
+            `  { "info": info, "receivers": receivers })`;
+        const response = await pactRead(pactCode, { tier: "T5" });
+        if (response?.result && response.result.status !== "failure") {
+            const data = response.result.data;
+            return { info: data?.info ?? null, receivers: data?.receivers ?? [] };
+        }
+        getLogger().error("getRegisterStoicTagInfo failed:", response);
+        return null;
+    }
+    catch (error) {
+        getLogger().error("getRegisterStoicTagInfo error:", error);
+        return null;
+    }
+}
+export async function getStoaAccountSelectorData(accounts) {
+    if (accounts.length === 0)
+        return [];
+    const accountsList = accounts.map(a => `"${a}"`).join(" ");
+    const pactCode = `(${KADENA_NAMESPACE}.DPL-UR.URC_0028_StoaAccountSelectorMapper [${accountsList}])`;
+    const response = await pactRead(pactCode, { tier: "T5" });
+    if (!response?.result || response.result.status === "failure") {
+        getLogger().error("StoaAccountSelectorMapper failed:", response);
+        return [];
+    }
+    return response.result?.data ?? [];
+}
+export async function getAccountOverview(account) {
+    if (!account)
+        return null;
+    const pactCode = `(${KADENA_NAMESPACE}.DPL-UR.URC_0029_AccountOverview "${account}")`;
+    const response = await pactRead(pactCode, { tier: "T7" });
+    if (!response?.result || response.result.status === "failure") {
+        getLogger().error("AccountOverview failed:", response);
+        return null;
+    }
+    return response.result?.data ?? null;
+}
+export async function isAdministrativePause() {
+    const response = await pactRead(`(${KADENA_NAMESPACE}.DALOS.UR_GAP)`, { tier: "T7" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result.data;
+}
+export async function kadenaLedger(address) {
+    const response = await pactRead(`(${KADENA_NAMESPACE}.DALOS.UR_KadenaLedger "${address}")`, { tier: "T5" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result;
+}
+export const getKadenaAccountOwner = async (address) => {
+    const response = await pactRead(`(${KADENA_NAMESPACE}.DALOS.UR_AccountKadena "${address}")`, { tier: "T5" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result?.data || null;
+};
+export const readKeyset = async (namespace, keysetName) => {
+    const response = await pactRead(`(describe-keyset "${namespace}.${keysetName}")`, { tier: "T7" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result?.data || null;
+};
+/**
+ * Resolve a guard value — if it's a keyset ref, fetch the actual keyset.
+ * Handles both direct keyset objects and {keysetref: {ns, ksn}} references.
+ *
+ * Normalises the chain-native lowercase `keysetref` field to camelCase
+ * `keysetRef` at this boundary via `normalizeKeysetRef`, so internal code
+ * that follows downstream of `resolveGuard` only ever sees the camelCase
+ * form. The lowercase field is preserved for backwards-compat with
+ * existing reads.
+ */
+export async function resolveGuard(guardData) {
+    if (!guardData || guardData === false)
+        return null;
+    guardData = normalizeKeysetRef(guardData);
+    if (guardData.keysetref) {
+        const ks = await readKeyset(guardData.keysetref.ns, guardData.keysetref.ksn);
+        // Return a copy rather than mutating `ks` in place: the keyset object
+        // comes from `readKeyset`, which (under OuronetUI's cache-aware reader)
+        // hands back a shared, frozen reference. Writing `.keysetRef` onto it
+        // throws "Cannot assign to read only property 'keysetRef'".
+        return ks ? { ...ks, keysetRef: `${guardData.keysetref.ns}.${guardData.keysetref.ksn}` } : ks;
+    }
+    return guardData;
+}
+export const getKadenaAccountGuard = async (address) => {
+    const response = await pactRead(`(${KADENA_NAMESPACE}.DALOS.UR_AccountGuard "${address}")`, { tier: "T7" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    const { data } = response.result;
+    if (data?.hasOwnProperty("keysetref")) {
+        const ks2 = await readKeyset(data.keysetref.ns, data.keysetref.ksn);
+        // Copy, don't mutate — see resolveGuard above for the frozen-reference rationale.
+        return ks2 ? { ...ks2, keysetRef: `${data.keysetref.ns}.${data.keysetref.ksn}` } : ks2;
+    }
+    return data || null;
+};
+export async function getOuronetKdaDetails(address) {
+    // v3.3.6 (F-PERF-004): parallelize the two independent reads.
+    // `getKadenaAccountOwner` reads `DALOS.UR_AccountKadena` and
+    // `getKadenaAccountGuard` reads `DALOS.UR_AccountGuard` — neither
+    // depends on the other's result, so `Promise.all` halves the
+    // happy-path latency (was ~2 sequential RPC roundtrips, now ~1
+    // parallel roundtrip).
+    const [owner, guard] = await Promise.all([
+        getKadenaAccountOwner(address),
+        getKadenaAccountGuard(address),
+    ]);
+    return {
+        isActive: owner !== null,
+        owner: owner,
+        guard: guard,
+    };
+}
+// (namespace.DSP.URC_PrimordialPrices)
+export async function primordialPrices() {
+    const response = await pactRead(`(${KADENA_NAMESPACE}.DSP.URC_PrimordialPrices)`, { tier: "T6" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result?.data || null;
+}
+// DALOS.UR_Elite account
+export async function eliteAccount(address) {
+    const response = await pactRead(`(${KADENA_NAMESPACE}.DALOS.UR_Elite "${address}")`, { tier: "T6" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result?.data || null;
+}
+export async function filterKeysForInfo(address, table = 1, mode = true) {
+    const pactCode = `(${KADENA_NAMESPACE}.TFT.DPTF-DPMF-ATS|UR_FilterKeysForInfo "${address}" ${table} ${mode})`;
+    const response = await pactRead(pactCode, { tier: "T3" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result?.data || null;
+}
+// returns the price of the activation
+export async function usagePrice(tokenType = "standard") {
+    const response = await pactRead(`(${KADENA_NAMESPACE}.DALOS.UR_UsagePrice "${tokenType}")`, { tier: "T7" });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result?.data || null;
+}
+// (namespace.DPL-UR.URC_0001_Header account) 5000 gas
+// Legacy: getHeaderData removed — replaced by URC_0027_AccountSelectorMapper for header.
+// HeaderV3 is still used by Dashboard (IndexCardsGrid, OuroAccountCard, FirestarterSection).
+export async function getHeaderData(address = "", options) {
+    const response = await pactRead(`(${KADENA_NAMESPACE}.DPL-UR.URC_0001_HeaderV3 "${address}")`, { tier: "T6", skipTempWatcher: options?.skipTempWatcher });
+    if (!response || !response.result) {
+        throw new Error("Failed to retrieve data from the transaction.");
+    }
+    return response.result?.data || null;
+}

package/dist/interactions/ouroBalanceFunctions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ouroBalanceFunctions.ts
+ * IGNIS / DPTF / OURO-dispo / virtual-OURO balance reads.
+ * All four functions use catch-return-null per the v3.0.0 fabricated-fallbacks-removal contract.
+ */
+export declare const IGNIS_TOKEN_ID = "GAS-8Nh-JO8JO4F5";
+/**
+ * Get IGNIS (GAS) balance for an Ouronet account.
+ * Uses DPTF.UR_AccountSupply with the IGNIS token ID.
+ *
+ * Returns the balance as a decimal string on success, or `null` when the
+ * RPC call fails or the chain returns a non-success status. Consumers must
+ * distinguish "no balance" (legitimate `"0"` from chain) from "RPC failure"
+ * (`null`) — see v3.0.0 fabricated-fallbacks-removal.
+ */
+export declare function getIgnisBalance(account: string): Promise<string | null>;
+/**
+ * Fetch DPTF token balance for any account via DPTF.UR_AccountSupply
+ * (ouronet-ns.DPTF.UR_AccountSupply <token-id> <account>)
+ *
+ * Returns the balance as a decimal string on success, or `null` when the
+ * RPC call fails or the chain returns a non-success status (v3.0.0).
+ */
+export declare function getAccountTokenSupply(tokenId: string, account: string): Promise<string | null>;
+/**
+ * Fetch OURO dispo capacity for an account via DALOS.UR_DISPOSupply
+ *
+ * Returns the capacity as a decimal string on success, or `null` when the
+ * RPC call fails or the chain returns a non-success status (v3.0.0).
+ */
+export declare function getOuroDispoCapacity(account: string): Promise<string | null>;
+/**
+ * Fetch Virtual OURO balance for an account
+ * (ouronet-ns.TFT.URC_VirtualOuro <account>)
+ *
+ * Returns the virtual balance as a decimal string on success, or `null` when
+ * the RPC call fails or the chain returns a non-success status (v3.0.0).
+ */
+export declare function getVirtualOuro(account: string): Promise<string | null>;

package/dist/interactions/ouroBalanceFunctions.js

@@ -0,0 +1,100 @@
+/**
+ * ouroBalanceFunctions.ts
+ * IGNIS / DPTF / OURO-dispo / virtual-OURO balance reads.
+ * All four functions use catch-return-null per the v3.0.0 fabricated-fallbacks-removal contract.
+ */
+import { KADENA_NAMESPACE, TOKEN_ID_IGNIS } from "../constants/index.js";
+import { mayComeWithDeimal } from "@stoachain/stoa-core/pact";
+import { pactRead } from "@stoachain/stoa-core/reads";
+import { getLogger } from "@stoachain/stoa-core/observability";
+export const IGNIS_TOKEN_ID = TOKEN_ID_IGNIS;
+/**
+ * Get IGNIS (GAS) balance for an Ouronet account.
+ * Uses DPTF.UR_AccountSupply with the IGNIS token ID.
+ *
+ * Returns the balance as a decimal string on success, or `null` when the
+ * RPC call fails or the chain returns a non-success status. Consumers must
+ * distinguish "no balance" (legitimate `"0"` from chain) from "RPC failure"
+ * (`null`) — see v3.0.0 fabricated-fallbacks-removal.
+ */
+// All catch blocks below route via getLogger().error(...) from ../observability (F-CORE-019, v2.3.0)
+export async function getIgnisBalance(account) {
+    try {
+        const pactCode = `(${KADENA_NAMESPACE}.DPTF.UR_AccountSupply "${IGNIS_TOKEN_ID}" "${account}")`;
+        // T1, not T5 — this is a BALANCE read (the canonical tier mapping puts
+        // balance reads at T1: high churn, very short TTL). At T5 the patron IGNIS
+        // balance stayed stale right after a transfer, falsely blocking spends with
+        // "Insufficient IGNIS" until a hard refresh.
+        const response = await pactRead(pactCode, { tier: "T1" });
+        if (response?.result?.status === "success") {
+            return String(mayComeWithDeimal(response.result.data));
+        }
+        return null;
+    }
+    catch (error) {
+        getLogger().error("Error in getIgnisBalance:", error);
+        return null;
+    }
+}
+/**
+ * Fetch DPTF token balance for any account via DPTF.UR_AccountSupply
+ * (ouronet-ns.DPTF.UR_AccountSupply <token-id> <account>)
+ *
+ * Returns the balance as a decimal string on success, or `null` when the
+ * RPC call fails or the chain returns a non-success status (v3.0.0).
+ */
+export async function getAccountTokenSupply(tokenId, account) {
+    try {
+        const pactCode = `(${KADENA_NAMESPACE}.DPTF.UR_AccountSupply "${tokenId}" "${account}")`;
+        const response = await pactRead(pactCode, { tier: "T5" });
+        if (response?.result?.status === "success") {
+            return String(mayComeWithDeimal(response.result.data));
+        }
+        return null;
+    }
+    catch (error) {
+        getLogger().error("Error in getAccountTokenSupply:", error);
+        return null;
+    }
+}
+/**
+ * Fetch OURO dispo capacity for an account via DALOS.UR_DISPOSupply
+ *
+ * Returns the capacity as a decimal string on success, or `null` when the
+ * RPC call fails or the chain returns a non-success status (v3.0.0).
+ */
+export async function getOuroDispoCapacity(account) {
+    try {
+        const pactCode = `(${KADENA_NAMESPACE}.DALOS.UR_DISPOSupply "${account}")`;
+        const response = await pactRead(pactCode, { tier: "T5" });
+        if (response?.result?.status === "success") {
+            return String(mayComeWithDeimal(response.result.data));
+        }
+        return null;
+    }
+    catch (error) {
+        getLogger().error("Error in getOuroDispoCapacity:", error);
+        return null;
+    }
+}
+/**
+ * Fetch Virtual OURO balance for an account
+ * (ouronet-ns.TFT.URC_VirtualOuro <account>)
+ *
+ * Returns the virtual balance as a decimal string on success, or `null` when
+ * the RPC call fails or the chain returns a non-success status (v3.0.0).
+ */
+export async function getVirtualOuro(account) {
+    try {
+        const pactCode = `(${KADENA_NAMESPACE}.TFT.URC_VirtualOuro "${account}")`;
+        const response = await pactRead(pactCode, { tier: "T5" });
+        if (response?.result?.status === "success") {
+            return String(mayComeWithDeimal(response.result.data));
+        }
+        return null;
+    }
+    catch (error) {
+        getLogger().error("Error in getVirtualOuro:", error);
+        return null;
+    }
+}

package/dist/interactions/ouroCoilFunctions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ouroCoilFunctions.ts
+ * OURO-specific coil/curl execution + verbatim tail-block re-exports of the broader
+ * coil/pension/info-one preview surface (locked here because the original tail-block
+ * comment "Export new coiling functions for AURYN and WSTOA" places them in the coil domain).
+ */
+import type { IKadenaKeypair } from "@stoachain/stoa-core/signing";
+import type { IOuroAccountKeypair } from "./ouroTypes.js";
+export declare function getCoilPreview(ouroAmount: string): Promise<{
+    auryn: number;
+    fee: number;
+    kadenaInfo: {
+        text: string;
+        discount: number;
+        full: number;
+        need: number;
+    };
+    ignisInfo: {
+        text: string;
+        discount: number;
+        full: number;
+        need: number;
+    };
+    preText: string[];
+    postText: string[];
+} | null>;
+export declare function curlOuroToEliteAuryn(ouroAccount: IOuroAccountKeypair, kadenaAccount: IKadenaKeypair, guard: IKadenaKeypair, targetAccount: string, // The account that will receive the Elite AURYN (same as patron per client explanation)
+ouroAmount: string): Promise<import("@stoachain/kadena-stoic-legacy/client").ITransactionDescriptor>;
+export { getAurynCoilPreview, coilAurynToElite, getWkdaCoilPreview, coilWkdaToLkda, COIL_CONFIGS } from "./coilFunctions.js";
+export { brumateWkdaToPkda, constrictLkdaToPkda } from "./pensionFunctions.js";
+export { getTransferPreview, getCoilPreviewInfo, getCurlPreviewInfo, getBrumatePreviewInfo, getConstrictPreviewInfo, parseTransferPreview, type TransferPreviewData } from "./infoOneFunctions.js";
+export declare function coilOuroToAuryn(ouroAccount: IOuroAccountKeypair, kadenaAccount: IKadenaKeypair, guard: IKadenaKeypair, targetAccount: string, // The account that will receive the AURYN
+ouroAmount: string): Promise<import("@stoachain/kadena-stoic-legacy/client").ITransactionDescriptor>;