@ouronet/ouronet-core 4.3.6

package/dist/interactions/ouroWrapFunctions.js

@@ -0,0 +1,234 @@
+/**
+ * ouroWrapFunctions.ts
+ * KDA wrap/unwrap and unwrap-stoa execution + supporting reads.
+ */
+import { calculateAutoGasLimit } from "@stoachain/stoa-core/gas";
+import { KADENA_CHAIN_ID, KADENA_NAMESPACE, STOA_AUTONOMIC_OURONETGASSTATION, STOA_AUTONOMIC_LIQUIDPOT, KADENA_NETWORK, } from "../constants/index.js";
+import { safeCreationTime, formatDecimalForPact } from "@stoachain/stoa-core/pact";
+import { Pact } from "@stoachain/kadena-stoic-legacy/client";
+import { getFailoverClient } from "@stoachain/stoa-core/network";
+import { universalSignTransaction, fromKeypair } from "@stoachain/stoa-core/signing";
+import { createSimulationError, logDetailedError } from "@stoachain/stoa-core/errors";
+import { pactRead } from "@stoachain/stoa-core/reads";
+import { getLogger } from "@stoachain/stoa-core/observability";
+// Wrap Kadena
+// (defun LQD|C_WrapStoa (patron:string wrapper:string amount:decimal))
+// patron is current ouro account public key | wrapper by default is the same but can also be a different ouro account public key amount should be decimal
+// as keys we need to use the ouro account kadena_ledger that has the capability coin.TRANSFER and the value of the amount. STOA_AUTONOMIC_OURONETGASSTATION
+export async function wrapKadena(patronAccount, wrapperAccount, // Ouro address that will receive the wrapped KDA
+kadenaAccount, // The kadena account that will transfer KDA
+guardAccount, // The guard account from the Ouro account
+amount) {
+    const keysetName = `ks`;
+    // Ensure amount is formatted as decimal
+    const decimalAmount = formatDecimalForPact(amount);
+    let gasLimit = 2000000; // Default gas limit for wrap operation
+    const buildTransaction = (gasLimitOverride) => {
+        return Pact.builder
+            .execution(`(${KADENA_NAMESPACE}.TS01-C2.LQD|C_WrapStoa "${patronAccount.address}" "${wrapperAccount}" ${decimalAmount})`)
+            .addData(keysetName, {
+            keys: [guardAccount.publicKey],
+            pred: "keys-all",
+        })
+            .setMeta({
+            senderAccount: STOA_AUTONOMIC_OURONETGASSTATION,
+            creationTime: safeCreationTime(),
+            chainId: KADENA_CHAIN_ID,
+            gasLimit: gasLimitOverride || gasLimit,
+        })
+            .setNetworkId(KADENA_NETWORK)
+            .addSigner(kadenaAccount.publicKey, (withCapability) => [
+            withCapability(`${KADENA_NAMESPACE}.DALOS.GAS_PAYER`, "", { int: 0 }, { decimal: "0.0" }),
+            withCapability("coin.TRANSFER", `k:${kadenaAccount.publicKey}`, STOA_AUTONOMIC_LIQUIDPOT, { decimal: decimalAmount }),
+        ])
+            .addSigner(guardAccount.publicKey)
+            .createTransaction();
+    };
+    const { dirtyRead, submit } = getFailoverClient(KADENA_CHAIN_ID);
+    // First do a simulation 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(`Simulation failed: ${errorMessage}`);
+    }
+    // Check if we need to adjust gas limit
+    const requiredGas = simulation.gas;
+    if (requiredGas && requiredGas > gasLimit) {
+        // Rebuild transaction with adjusted gas limit (20% buffer)
+        gasLimit = calculateAutoGasLimit(requiredGas);
+        transaction = buildTransaction(gasLimit);
+    }
+    // Sign the transaction with both keypairs
+    const signedTransaction = await universalSignTransaction(transaction, [
+        fromKeypair(kadenaAccount),
+        fromKeypair(guardAccount),
+    ]);
+    // Submit the signed transaction
+    const result = await submit(signedTransaction);
+    return result;
+}
+// unwrap Kadena
+// (ouronet-ns.TS01-C2.LQD|C_UnwrapStoa patron unwrapper amount)
+export async function unwrapKadena(patronAccount, // Ouro account that owns the WSTOA
+unwrapperAccount, // Ouro address that will receive the unwrapped KDA
+kadenaAccount, // The kadena account (payer)
+guardAccount, // The guard account from the Ouro account
+amount) {
+    // Ensure amount is formatted as decimal
+    const decimalAmount = formatDecimalForPact(amount);
+    let gasLimit = 2000000; // Default gas limit for unwrap operation
+    const buildTransaction = (gasLimitOverride) => {
+        return Pact.builder
+            .execution(`(${KADENA_NAMESPACE}.TS01-C2.LQD|C_UnwrapStoa "${patronAccount.address}" "${unwrapperAccount}" ${decimalAmount})`)
+            .setMeta({
+            senderAccount: STOA_AUTONOMIC_OURONETGASSTATION,
+            creationTime: safeCreationTime(),
+            chainId: KADENA_CHAIN_ID,
+            gasLimit: gasLimitOverride || gasLimit,
+        })
+            .setNetworkId(KADENA_NETWORK)
+            .addSigner(kadenaAccount.publicKey, (withCapability) => [
+            withCapability(`${KADENA_NAMESPACE}.DALOS.GAS_PAYER`, "", { int: 0 }, { decimal: "0.0" }),
+            withCapability("coin.TRANSFER", STOA_AUTONOMIC_LIQUIDPOT, `k:${kadenaAccount.publicKey}`, { decimal: decimalAmount }),
+        ])
+            .addSigner(guardAccount.publicKey)
+            .createTransaction();
+    };
+    const { dirtyRead, submit } = getFailoverClient(KADENA_CHAIN_ID);
+    // First do a simulation 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(`Simulation failed: ${errorMessage}`);
+    }
+    // Check if we need to adjust gas limit
+    const requiredGas = simulation.gas;
+    if (requiredGas && requiredGas > gasLimit) {
+        // Rebuild transaction with adjusted gas limit (20% buffer)
+        gasLimit = calculateAutoGasLimit(requiredGas);
+        transaction = buildTransaction(gasLimit);
+    }
+    // Sign the transaction with both keypairs
+    const signedTransaction = await universalSignTransaction(transaction, [
+        fromKeypair(kadenaAccount),
+        fromKeypair(guardAccount),
+    ]);
+    // Submit the signed transaction
+    const result = await submit(signedTransaction);
+    return result;
+}
+/**
+ * Resolve the target Kadena address for an Ouronet unwrapper account.
+ * (ouronet-ns.DALOS.UR_AccountKadena <unwrapper>)
+ */
+export async function getUnwrapStoaTarget(unwrapper) {
+    try {
+        const pactCode = `(${KADENA_NAMESPACE}.DALOS.UR_AccountKadena "${unwrapper}")`;
+        const response = await pactRead(pactCode, { tier: "T5" });
+        if (response?.result?.status === "success") {
+            return String(response.result.data);
+        }
+        return null;
+    }
+    catch (error) {
+        getLogger().error("Error resolving UnwrapStoa target:", error);
+        return null;
+    }
+}
+export async function getUnwrapStoaInfo(patron, unwrapper, amount) {
+    try {
+        const decimalAmount = formatDecimalForPact(amount);
+        const pactCode = `(${KADENA_NAMESPACE}.INFO-ONE.LIQUID|INFO_UnwrapStoa "${patron}" "${unwrapper}" ${decimalAmount})`;
+        const response = await pactRead(pactCode, { tier: "T2" });
+        if (response?.result?.status === "success") {
+            return response.result.data;
+        }
+        return null;
+    }
+    catch (error) {
+        getLogger().error("Error getting UnwrapStoa info:", error);
+        return null;
+    }
+}
+// ─── executeUnwrapStoa ────────────────────────────────────────────────────────
+// Handles both execution cases for UnwrapStoa:
+//   Case 2 — target exists → simple unwrap
+//   Case 1 — target is new k: account → create account + unwrap
+// Adaptive gas: simulate first, then rebuild with calculateAutoGasLimit.
+export async function executeUnwrapStoa(params) {
+    const { patronAddress, unwrapperAddress, amount, numAmount, targetAddress, targetExists, gasStationKey, patronGuardKeys, accountGuardKeys, } = params;
+    // All unique signers (gas station first, then guard keys de-duped)
+    const allSigners = [gasStationKey];
+    const addedPubs = new Set([gasStationKey.publicKey]);
+    for (const k of [...patronGuardKeys, ...accountGuardKeys]) {
+        if (!addedPubs.has(k.publicKey)) {
+            allSigners.push(k);
+            addedPubs.add(k.publicKey);
+        }
+    }
+    let gasLimit = 2000000;
+    const buildTransaction = (gasLimitOverride) => {
+        const effectiveGasLimit = gasLimitOverride ?? gasLimit;
+        let builder = targetExists
+            // Case 2 — target exists: simple unwrap
+            ? Pact.builder.execution(`(${KADENA_NAMESPACE}.TS01-C2.LQD|C_UnwrapStoa "${patronAddress}" "${unwrapperAddress}" ${amount})`)
+            // Case 1 — new k: account: create + unwrap
+            : Pact.builder
+                .execution(`(namespace "${KADENA_NAMESPACE}")\n` +
+                `(IGNIS.C_Collect "${patronAddress}" (IGNIS.UDC_CustomCodeCumulator))\n` +
+                `(let\n` +
+                `  (\n` +
+                `    (wp:string "${unwrapperAddress}")\n` +
+                `    (target:string (DALOS.UR_AccountKadena wp))\n` +
+                `  )\n` +
+                `  [\n` +
+                `    (coin.C_CreateAccount target (read-keyset "ks"))\n` +
+                `    (TS01-C2.LQD|C_UnwrapStoa "${patronAddress}" "${unwrapperAddress}" ${amount})\n` +
+                `  ]\n` +
+                `)`)
+                .addData("ks", {
+                keys: [targetAddress.slice(2)], // k:<pubkey> → strip "k:"
+                pred: "keys-all",
+            });
+        builder = builder
+            .setMeta({ senderAccount: STOA_AUTONOMIC_OURONETGASSTATION, chainId: KADENA_CHAIN_ID, creationTime: safeCreationTime(),
+            gasLimit: effectiveGasLimit })
+            .setNetworkId(KADENA_NETWORK)
+            // Gas Station: GAS_PAYER + coin.TRANSFER
+            .addSigner(gasStationKey.publicKey, (w) => [
+            w(`${KADENA_NAMESPACE}.DALOS.GAS_PAYER`, "", { int: 0 }, { decimal: "0.0" }),
+            w("coin.TRANSFER", STOA_AUTONOMIC_LIQUIDPOT, targetAddress, { decimal: String(numAmount) }),
+        ]);
+        // Patron + account guard keys: pure signers
+        const addedSignerPubs = new Set([gasStationKey.publicKey]);
+        for (const k of [...patronGuardKeys, ...accountGuardKeys]) {
+            if (!addedSignerPubs.has(k.publicKey)) {
+                builder = builder.addSigner(k.publicKey);
+                addedSignerPubs.add(k.publicKey);
+            }
+        }
+        return builder.createTransaction();
+    };
+    const { dirtyRead, submit } = getFailoverClient(KADENA_CHAIN_ID);
+    // 1. Simulate with 2M (network max)
+    let transaction = buildTransaction();
+    const simulation = await dirtyRead(transaction);
+    if (simulation.result.status === "failure") {
+        const error = createSimulationError("Unwrap STOA", simulation.result, `Patron: ${patronAddress} | Unwrapper: ${unwrapperAddress} | Target: ${targetAddress} | Amount: ${amount}`);
+        logDetailedError(error);
+        throw error;
+    }
+    // 2. Adaptive gas: rebuild with calibrated limit
+    const requiredGas = simulation.gas;
+    if (requiredGas) {
+        gasLimit = calculateAutoGasLimit(requiredGas);
+        transaction = buildTransaction(gasLimit);
+    }
+    // 3. Sign & submit
+    const signed = await universalSignTransaction(transaction, allSigners.map((s) => fromKeypair(s)));
+    return await submit(signed);
+}

package/dist/interactions/pensionFunctions.d.ts

@@ -0,0 +1,12 @@
+import { type IKadenaKeypair } from "@stoachain/stoa-core/signing";
+import type { IOuroAccountKeypair } from "./ouroTypes.js";
+export declare function brumateWkdaToPkda(ouroAccount: IOuroAccountKeypair, kadenaAccount: IKadenaKeypair, guard: IKadenaKeypair, wkdaAmount: string, lockDays: number): Promise<import("@stoachain/kadena-stoic-legacy/client").ITransactionDescriptor>;
+export declare function constrictLkdaToPkda(ouroAccount: IOuroAccountKeypair, kadenaAccount: IKadenaKeypair, guard: IKadenaKeypair, lkdaAmount: string, lockDays: number): Promise<import("@stoachain/kadena-stoic-legacy/client").ITransactionDescriptor>;
+/**
+ * Get Hibernate/Pension entry fee for a specific lock period
+ * Formula: 12% - 0.0008% per day locked (0% at 15000 days)
+ * @param korIndexId - KORIndex pool ID (e.g., "GoldenStoaPillar-O136CBn22ncY")
+ * @param lockDays - Number of days to lock
+ * @returns Fee as decimal (e.g., 0.12 for 12%)
+ */
+export declare function getHibernateFee(korIndexId: string, lockDays: number): Promise<number>;

package/dist/interactions/pensionFunctions.js

@@ -0,0 +1,127 @@
+import { calculateAutoGasLimit } from "@stoachain/stoa-core/gas";
+import { KADENA_CHAIN_ID, KADENA_NAMESPACE, STOA_AUTONOMIC_OURONETGASSTATION, KADENA_NETWORK, } from "../constants/index.js";
+import { formatDecimalForPact, safeCreationTime } from "@stoachain/stoa-core/pact";
+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";
+// Brumate WSTOA to H|GSTOA (Hibernated Pension Kadena)
+// (namespace.TS01-C2.ATS|C_Brumate patron:string brumate-account:string "SilverStoaPillar-O136CBn22ncY" "GoldenStoaPillar-O136CBn22ncY" "WSTOA-8Nh-JO8JO4F5" amount:decimal lock-days:integer)
+export async function brumateWkdaToPkda(ouroAccount, kadenaAccount, guard, wkdaAmount, lockDays) {
+    const keysetName = `ks`;
+    const decimalAmount = formatDecimalForPact(wkdaAmount);
+    let gasLimit = 2000000;
+    const buildTransaction = (gasLimitOverride) => {
+        return Pact.builder
+            .execution(`(${KADENA_NAMESPACE}.TS01-C2.ATS|C_Brumate "${ouroAccount.address}" "${ouroAccount.address}" "SilverStoaPillar-O136CBn22ncY" "GoldenStoaPillar-O136CBn22ncY" "WSTOA-8Nh-JO8JO4F5" ${decimalAmount} ${lockDays})`)
+            .addData(keysetName, {
+            keys: [guard.publicKey],
+            pred: "keys-all",
+        })
+            .setMeta({
+            senderAccount: STOA_AUTONOMIC_OURONETGASSTATION,
+            creationTime: safeCreationTime(),
+            chainId: KADENA_CHAIN_ID,
+            gasLimit: gasLimitOverride || gasLimit,
+        })
+            .setNetworkId(KADENA_NETWORK)
+            .addSigner(kadenaAccount.publicKey, (withCapability) => [
+            withCapability(`${KADENA_NAMESPACE}.DALOS.GAS_PAYER`, "", { int: 0 }, { decimal: "0.0" }),
+        ])
+            .addSigner(guard.publicKey)
+            .createTransaction();
+    };
+    const { dirtyRead, submit } = getFailoverClient(KADENA_CHAIN_ID);
+    let transaction = buildTransaction();
+    const simulation = await dirtyRead(transaction);
+    if (simulation.result.status === "failure") {
+        const errorMessage = simulation.result.error?.message || "Transaction simulation failed";
+        throw new Error(`Simulation failed: ${errorMessage}`);
+    }
+    const requiredGas = simulation.gas;
+    if (requiredGas && requiredGas > gasLimit) {
+        gasLimit = calculateAutoGasLimit(requiredGas);
+        transaction = buildTransaction(gasLimit);
+    }
+    const signedTransaction = await universalSignTransaction(transaction, [
+        fromKeypair(kadenaAccount),
+        fromKeypair(guard),
+    ]);
+    const result = await submit(signedTransaction);
+    return result;
+}
+// Constrict SSTOA to H|GSTOA (Hibernated Pension Kadena)
+// (namespace.TS01-C2.ATS|C_Constrict patron:string constrictor:string "GoldenStoaPillar-O136CBn22ncY" "SSTOA-8Nh-JO8JO4F5" amount:decimal lock-days:integer)
+export async function constrictLkdaToPkda(ouroAccount, kadenaAccount, guard, lkdaAmount, lockDays) {
+    const keysetName = `ks`;
+    const decimalAmount = formatDecimalForPact(lkdaAmount);
+    let gasLimit = 2000000;
+    const buildTransaction = (gasLimitOverride) => {
+        return Pact.builder
+            .execution(`(${KADENA_NAMESPACE}.TS01-C2.ATS|C_Constrict "${ouroAccount.address}" "${ouroAccount.address}" "GoldenStoaPillar-O136CBn22ncY" "SSTOA-8Nh-JO8JO4F5" ${decimalAmount} ${lockDays})`)
+            .addData(keysetName, {
+            keys: [guard.publicKey],
+            pred: "keys-all",
+        })
+            .setMeta({
+            senderAccount: STOA_AUTONOMIC_OURONETGASSTATION,
+            creationTime: safeCreationTime(),
+            chainId: KADENA_CHAIN_ID,
+            gasLimit: gasLimitOverride || gasLimit,
+        })
+            .setNetworkId(KADENA_NETWORK)
+            .addSigner(kadenaAccount.publicKey, (withCapability) => [
+            withCapability(`${KADENA_NAMESPACE}.DALOS.GAS_PAYER`, "", { int: 0 }, { decimal: "0.0" }),
+        ])
+            .addSigner(guard.publicKey)
+            .createTransaction();
+    };
+    const { dirtyRead, submit } = getFailoverClient(KADENA_CHAIN_ID);
+    let transaction = buildTransaction();
+    const simulation = await dirtyRead(transaction);
+    if (simulation.result.status === "failure") {
+        const errorMessage = simulation.result.error?.message || "Transaction simulation failed";
+        throw new Error(`Simulation failed: ${errorMessage}`);
+    }
+    const requiredGas = simulation.gas;
+    if (requiredGas && requiredGas > gasLimit) {
+        gasLimit = calculateAutoGasLimit(requiredGas);
+        transaction = buildTransaction(gasLimit);
+    }
+    const signedTransaction = await universalSignTransaction(transaction, [
+        fromKeypair(kadenaAccount),
+        fromKeypair(guard),
+    ]);
+    const result = await submit(signedTransaction);
+    return result;
+}
+/**
+ * Get Hibernate/Pension entry fee for a specific lock period
+ * Formula: 12% - 0.0008% per day locked (0% at 15000 days)
+ * @param korIndexId - KORIndex pool ID (e.g., "GoldenStoaPillar-O136CBn22ncY")
+ * @param lockDays - Number of days to lock
+ * @returns Fee as decimal (e.g., 0.12 for 12%)
+ */
+export async function getHibernateFee(korIndexId, lockDays) {
+    try {
+        const response = await pactRead(`(${KADENA_NAMESPACE}.DPL-UR.URC_0012_HibernateFee "${korIndexId}" ${lockDays})`, { tier: "T2" });
+        if (!response || !response.result) {
+            throw new Error("Failed to retrieve hibernate fee");
+        }
+        if (response.result.status === "failure") {
+            throw new Error(`Hibernate fee query failed: ${response.result.error?.message || "Unknown error"}`);
+        }
+        const data = response.result.data;
+        // API returns decimal value, convert to number
+        if (typeof data === 'object' && data !== null && 'decimal' in data) {
+            return parseFloat(String(data.decimal));
+        }
+        return typeof data === 'number' ? data : parseFloat(String(data));
+    }
+    catch (error) {
+        // Silent fallback - function may not be deployed yet on blockchain
+        // Using local calculation: 12% - 0.0008% per day (0% at 15000 days)
+        const fee = 0.12 - (0.000008 * lockDays);
+        return Math.max(0, fee); // Never negative
+    }
+}

package/dist/interactions/urStoaFunctions.d.ts

@@ -0,0 +1,104 @@
+/**
+ * urStoaFunctions.ts — Native UrStoa on-chain interactions
+ *
+ * Balance:  (try 0.0 (coin.UR_UR|Balance "<account>"))
+ * Guard:    (try false (coin.UR_UR|Guard "<account>"))
+ * Transfer: coin.C_UR|Transfer / Transmit / TransferAnew / TransmitAnew
+ */
+import { type IKadenaKeypair } from "@stoachain/stoa-core/signing";
+export interface UrStoaGuardResult {
+    exists: boolean;
+    guard?: any;
+    isKeyset: boolean;
+    keys: string[];
+    pred: string;
+}
+export declare function getUrStoaBalance(account: string): Promise<number | null>;
+export declare function getUrStoaGuard(account: string): Promise<UrStoaGuardResult | null>;
+/** Keypair with optional Chainweaver/Ecko signing fields */
+export interface UrStoaKeypair {
+    publicKey: string;
+    privateKey?: string;
+    secretKey?: string;
+    seedType?: string;
+    encryptedSecretKey?: any;
+    password?: string;
+}
+export interface ExecuteNativeUrStoaParams {
+    senderAddress: string;
+    receiverAddress: string;
+    amount: string;
+    paymentKeyAddress: string;
+    paymentKeypair: UrStoaKeypair;
+    senderGuardKeys: UrStoaKeypair[];
+    isTransferFamily: boolean;
+    receiverExists: boolean;
+    receiverKeyset?: {
+        keys: string[];
+        pred: string;
+    };
+}
+export declare function executeNativeUrStoaTransfer(params: ExecuteNativeUrStoaParams): Promise<any>;
+/**
+ * (coin.C_URV|Stake <account:string> <urstoa-amount:decimal>)
+ * Caps: GAS_PAYER + coin.URV|STAKE(account, amount) — both on payment key
+ */
+export interface StakeUrStoaParams {
+    paymentKeyAddress: string;
+    amount: string;
+    /**
+     * @deprecated since v3.2.1 — the `amount` string is now the single source
+     * of truth. `numAmount` is retained on the interface for non-breaking
+     * compatibility with v3.x callers but is no longer read by the executor.
+     * Will be removed in v4.0.0.
+     */
+    numAmount?: number;
+    gasStationKey: IKadenaKeypair;
+}
+export declare function executeStakeUrStoa(params: StakeUrStoaParams): Promise<any>;
+/**
+ * (coin.C_URV|Unstake <account:string> <urstoa-amount:decimal>)
+ * Caps: GAS_PAYER + coin.URV|UNSTAKE(account, amount) — both on payment key
+ */
+export interface UnstakeUrStoaParams {
+    paymentKeyAddress: string;
+    amount: string;
+    /**
+     * @deprecated since v3.2.1 — same rationale as `StakeUrStoaParams.numAmount`.
+     * Retained for non-breaking compatibility; will be removed in v4.0.0.
+     */
+    numAmount?: number;
+    gasStationKey: IKadenaKeypair;
+}
+export declare function executeUnstakeUrStoa(params: UnstakeUrStoaParams): Promise<any>;
+/**
+ * Polls for urStoa account existence in the coin table using:
+ * (if (= (typeof (try false (coin.UR_Balance account))) "bool") false true)
+ *
+ * Returns: true = exists, null = doesn't exist OR RPC error (both collapse
+ * to a non-existence/uncertainty signal — callers should treat null as
+ * "do not proceed assuming the account exists").
+ *
+ * @see {@link checkCoinAccountExists} in `ouroFunctions.ts` — both functions
+ * share the nullable-boolean return shape (`Promise<boolean | null>`) but
+ * differ in account scope: this one probes urStoa account existence via
+ * `coin.UR_Balance`; the sibling probes a generic coin account via
+ * `coin.get-balance`. Renaming to disambiguate the two identifiers is
+ * deferred to a separate breaking change to keep the consumer migration
+ * surface tight.
+ */
+export declare function checkCoinAccountExists(account: string): Promise<boolean | null>;
+/**
+ * (coin.C_URV|Collect <account:string>)
+ * Caps: GAS_PAYER + coin.URV|COLLECT(account)
+ *
+ * If accountExists=false, wraps in 2-line tx:
+ * (coin.C_CreateAccount <account> (read-keyset "ks"))
+ * (coin.C_URV|Collect <account>)
+ */
+export interface CollectUrStoaParams {
+    paymentKeyAddress: string;
+    gasStationKey: IKadenaKeypair;
+    accountExists?: boolean;
+}
+export declare function executeCollectUrStoa(params: CollectUrStoaParams): Promise<any>;