@arkade-os/sdk 0.3.12 → 0.4.0-next.0

package/dist/cjs/wallet/expo/wallet.js

@@ -0,0 +1,231 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpoWallet = void 0;
+const base_1 = require("@scure/base");
+const wallet_1 = require("../wallet");
+const ark_1 = require("../../providers/ark");
+const taskRunner_1 = require("../../worker/expo/taskRunner");
+const processors_1 = require("../../worker/expo/processors");
+const utils_1 = require("../utils");
+const default_1 = require("../../script/default");
+/**
+ * Expo/React Native wallet with built-in background task processing.
+ *
+ * Wraps a standard {@link Wallet} and adds a lightweight task queue
+ * for keeping contract/VTXO state fresh while the app is active and
+ * across Expo BackgroundTask wakes.
+ *
+ * @example
+ * ```ts
+ * import { ExpoWallet } from "@arkade-os/sdk/wallet/expo";
+ * import { AsyncStorageTaskQueue } from "@arkade-os/sdk/worker/expo";
+ *
+ * const wallet = await ExpoWallet.setup({
+ *     identity: SingleKey.fromHex(privateKey),
+ *     arkServerUrl,
+ *     esploraUrl,
+ *     storage: { walletRepository, contractRepository },
+ *     background: {
+ *         taskName: "ark-background-poll",
+ *         taskQueue: new AsyncStorageTaskQueue(AsyncStorage),
+ *         foregroundIntervalMs: 20_000,
+ *         minimumBackgroundInterval: 15,
+ *     },
+ * });
+ *
+ * const balance = await wallet.getBalance();
+ * ```
+ */
+class ExpoWallet {
+    constructor(wallet, taskQueue, processors, deps, taskName, foregroundIntervalMs) {
+        this.wallet = wallet;
+        this.taskQueue = taskQueue;
+        this.processors = processors;
+        this.deps = deps;
+        this.identity = wallet.identity;
+        this.arkProvider = wallet.arkProvider;
+        this.indexerProvider = wallet.indexerProvider;
+        this.taskName = taskName;
+        if (foregroundIntervalMs && foregroundIntervalMs > 0) {
+            this.startForegroundPolling(foregroundIntervalMs);
+        }
+    }
+    /**
+     * Create an ExpoWallet with background task support.
+     *
+     * 1. Creates the inner {@link Wallet} via `Wallet.create()`.
+     * 2. Wires up processors (defaults to {@link contractPollProcessor}).
+     * 3. Persists background config for the background handler (if the queue supports it).
+     * 4. Seeds the task queue with a `contract-poll` task.
+     * 5. Registers the background task with the OS scheduler (if `minimumBackgroundInterval` is set).
+     * 6. Starts foreground polling if `foregroundIntervalMs` is set.
+     */
+    static async setup(config) {
+        const wallet = await wallet_1.Wallet.create(config);
+        const processors = config.background.processors ?? [
+            processors_1.contractPollProcessor,
+        ];
+        const deps = {
+            walletRepository: wallet.walletRepository,
+            contractRepository: wallet.contractRepository,
+            indexerProvider: wallet.indexerProvider,
+            arkProvider: wallet.arkProvider,
+            extendVtxo: (vtxo, contract) => {
+                if (contract) {
+                    return (0, utils_1.extendVtxoFromContract)(vtxo, contract);
+                }
+                return (0, utils_1.extendVirtualCoin)(wallet, vtxo);
+            },
+        };
+        const { taskQueue } = config.background;
+        // Persist wallet params so the background handler can rehydrate
+        // without a network call. Only works with AsyncStorageTaskQueue.
+        if ("persistConfig" in taskQueue) {
+            const arkServerUrl = config.arkServerUrl ??
+                (wallet.arkProvider instanceof ark_1.RestArkProvider
+                    ? wallet.arkProvider.serverUrl
+                    : undefined);
+            if (arkServerUrl) {
+                const timelock = wallet.offchainTapscript.options.csvTimelock ??
+                    default_1.DefaultVtxo.Script.DEFAULT_TIMELOCK;
+                const bgConfig = {
+                    arkServerUrl,
+                    pubkeyHex: base_1.hex.encode(wallet.offchainTapscript.options.pubKey),
+                    serverPubKeyHex: base_1.hex.encode(wallet.offchainTapscript.options.serverPubKey),
+                    exitTimelockValue: timelock.value.toString(),
+                    exitTimelockType: timelock.type,
+                };
+                await taskQueue.persistConfig(bgConfig);
+            }
+        }
+        const expoWallet = new ExpoWallet(wallet, taskQueue, processors, deps, config.background.taskName, config.background.foregroundIntervalMs);
+        // Seed the queue so the first tick (or background wake) has work to do
+        await expoWallet.seedContractPollTask();
+        // Activate OS-level background scheduling
+        if (config.background.minimumBackgroundInterval) {
+            try {
+                const { registerExpoBackgroundTask } = await Promise.resolve().then(() => __importStar(require("./background")));
+                await registerExpoBackgroundTask(config.background.taskName, {
+                    minimumInterval: config.background.minimumBackgroundInterval,
+                });
+            }
+            catch {
+                // expo-background-task not installed — foreground-only mode
+            }
+        }
+        return expoWallet;
+    }
+    // ── Foreground polling ───────────────────────────────────────────
+    startForegroundPolling(intervalMs) {
+        this.foregroundIntervalId = setInterval(() => {
+            this.runForegroundPoll().catch(console.error);
+        }, intervalMs);
+    }
+    async runForegroundPoll() {
+        await (0, taskRunner_1.runTasks)(this.taskQueue, this.processors, this.deps);
+        // Consume results immediately (no background handoff needed)
+        const results = await this.taskQueue.getResults();
+        if (results.length > 0) {
+            await this.taskQueue.acknowledgeResults(results.map((r) => r.id));
+        }
+        // Re-seed for the next tick
+        await this.seedContractPollTask();
+    }
+    async seedContractPollTask() {
+        const existing = await this.taskQueue.getTasks(processors_1.CONTRACT_POLL_TASK_TYPE);
+        if (existing.length > 0)
+            return;
+        const task = {
+            id: (0, utils_1.getRandomId)(),
+            type: processors_1.CONTRACT_POLL_TASK_TYPE,
+            data: {},
+            createdAt: Date.now(),
+        };
+        await this.taskQueue.addTask(task);
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────
+    /**
+     * Stop foreground polling and unregister the background task.
+     */
+    async dispose() {
+        if (this.foregroundIntervalId) {
+            clearInterval(this.foregroundIntervalId);
+            this.foregroundIntervalId = undefined;
+        }
+        try {
+            const { unregisterExpoBackgroundTask } = await Promise.resolve().then(() => __importStar(require("./background")));
+            await unregisterExpoBackgroundTask(this.taskName);
+        }
+        catch {
+            // expo-background-task not installed — nothing to unregister
+        }
+    }
+    // ── IWallet delegation ───────────────────────────────────────────
+    getAddress() {
+        return this.wallet.getAddress();
+    }
+    getBoardingAddress() {
+        return this.wallet.getBoardingAddress();
+    }
+    getBalance() {
+        return this.wallet.getBalance();
+    }
+    getVtxos(filter) {
+        return this.wallet.getVtxos(filter);
+    }
+    getBoardingUtxos() {
+        return this.wallet.getBoardingUtxos();
+    }
+    getTransactionHistory() {
+        return this.wallet.getTransactionHistory();
+    }
+    getContractManager() {
+        return this.wallet.getContractManager();
+    }
+    sendBitcoin(params) {
+        return this.wallet.sendBitcoin(params);
+    }
+    settle(params, eventCallback) {
+        return this.wallet.settle(params, eventCallback);
+    }
+    send(...recipients) {
+        return this.wallet.send(...recipients);
+    }
+    get assetManager() {
+        return this.wallet.assetManager;
+    }
+}
+exports.ExpoWallet = ExpoWallet;

package/dist/cjs/wallet/onchain.js

@@ -8,6 +8,7 @@ const onchain_1 = require("../providers/onchain");
 const anchor_1 = require("../utils/anchor");
 const txSizeEstimator_1 = require("../utils/txSizeEstimator");
 const transaction_1 = require("../utils/transaction");
+const utils_1 = require("./utils");
 /**
  * Onchain Bitcoin wallet implementation for traditional Bitcoin transactions.
  *
@@ -59,11 +60,58 @@ class OnchainWallet {
         const onchainTotal = onchainConfirmed + onchainUnconfirmed;
         return onchainTotal;
     }
+    /**
+     * Iteratively selects coins and estimates transaction fees until convergence.
+     *
+     * This method handles the circular dependency between coin selection and fee
+     * estimation: the fee depends on transaction size, which depends on the number
+     * of inputs (selected coins) and whether a change output is needed.
+     *
+     * The algorithm iterates up to 10 times, refining the fee estimate based on
+     * the actual transaction structure. It resolves dust oscillation loops that
+     * occur when the change amount hovers near the dust threshold—adding/removing
+     * the change output causes the fee to fluctuate, preventing convergence.
+     * When a lower fee is computed (indicating the change output was dropped),
+     * the function accepts this state to guarantee termination.
+     *
+     * @param coins - Available coins to select from
+     * @param amount - Target send amount in satoshis
+     * @param feeRate - Fee rate in sat/vbyte
+     * @param recipientAddress - Destination address for size estimation
+     * @returns Selected inputs, change amount, and calculated fee
+     * @throws Error if fee estimation fails to converge within max iterations
+     */
+    estimateFeesAndSelectCoins(coins, amount, feeRate, recipientAddress) {
+        const MAX_ITERATIONS = 10;
+        let fee = 0;
+        for (let i = 0; i < MAX_ITERATIONS; i++) {
+            const totalNeeded = amount + fee;
+            const selected = selectCoins(coins, totalNeeded);
+            const estimator = txSizeEstimator_1.TxWeightEstimator.create();
+            for (const _ of selected.inputs) {
+                estimator.addKeySpendInput();
+            }
+            estimator.addOutputAddress(recipientAddress, this.network);
+            if (selected.changeAmount >= BigInt(utils_1.DUST_AMOUNT)) {
+                estimator.addOutputAddress(this.address, this.network);
+            }
+            const newFee = Number(estimator.vsize().value) * feeRate;
+            const roundedNewFee = Math.ceil(newFee);
+            // Prevent oscillation loops when change falls just below the dust limit.
+            // If removing the change output reduces the fee below our budget,
+            // we accept the valid transaction state to guarantee convergence.
+            if (roundedNewFee <= fee) {
+                return { ...selected, fee: roundedNewFee };
+            }
+            fee = roundedNewFee;
+        }
+        throw new Error("Fee estimation failed: could not converge");
+    }
     async send(params) {
         if (params.amount <= 0) {
             throw new Error("Amount must be positive");
         }
-        if (params.amount < OnchainWallet.DUST_AMOUNT) {
+        if (params.amount < utils_1.DUST_AMOUNT) {
             throw new Error("Amount is below dust limit");
         }
         const coins = await this.getCoins();
@@ -74,15 +122,14 @@ class OnchainWallet {
         if (!feeRate || feeRate < OnchainWallet.MIN_FEE_RATE) {
             feeRate = OnchainWallet.MIN_FEE_RATE;
         }
-        // Ensure fee is an integer by rounding up
-        const estimatedFee = Math.ceil(174 * feeRate);
-        const totalNeeded = params.amount + estimatedFee;
-        // Select coins
-        const selected = selectCoins(coins, totalNeeded);
+        const { inputs, changeAmount } = this.estimateFeesAndSelectCoins(coins, params.amount, feeRate, params.address);
+        if (!inputs) {
+            throw new Error("Fee estimation failed");
+        }
         // Create transaction
         let tx = new transaction_1.Transaction();
         // Add inputs
-        for (const input of selected.inputs) {
+        for (const input of inputs) {
             tx.addInput({
                 txid: input.txid,
                 index: input.vout,
@@ -95,9 +142,8 @@ class OnchainWallet {
         }
         // Add payment output
         tx.addOutputAddress(params.address, BigInt(params.amount), this.network);
-        // Add change output if needed
-        if (selected.changeAmount > 0n) {
-            tx.addOutputAddress(this.address, selected.changeAmount, this.network);
+        if (changeAmount >= BigInt(utils_1.DUST_AMOUNT)) {
+            tx.addOutputAddress(this.address, changeAmount, this.network);
         }
         // Sign inputs and Finalize
         tx = await this.identity.sign(tx);
@@ -116,7 +162,7 @@ class OnchainWallet {
         const childVsize = txSizeEstimator_1.TxWeightEstimator.create()
             .addKeySpendInput(true)
             .addP2AInput()
-            .addP2TROutput()
+            .addOutputAddress(this.address, this.network)
             .vsize().value;
         const packageVSize = parentVsize + Number(childVsize);
         let feeRate = await this.provider.getFeeRate();
@@ -160,7 +206,6 @@ class OnchainWallet {
 }
 exports.OnchainWallet = OnchainWallet;
 OnchainWallet.MIN_FEE_RATE = 1; // sat/vbyte
-OnchainWallet.DUST_AMOUNT = 546; // sats
 /**
  * Select coins to reach a target amount, prioritizing those closer to expiry
  * @param coins List of coins to select from