@arkade-os/sdk 0.3.11 → 0.3.13

package/README.md

@@ -164,9 +164,8 @@ const boardingUtxos = await wallet.getBoardingUtxos()
 ```typescript
 // Send bitcoin via Ark
 const txid = await wallet.sendBitcoin({
-  address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx',
-  amount: 50000,  // in satoshis
-  feeRate: 1      // optional, in sats/vbyte
+  address: 'ark1qq4...', // ark address
+  amount: 50000,         // in satoshis
 })
 ```
 

package/dist/cjs/providers/onchain.js

@@ -235,14 +235,14 @@ exports.EsploraProvider = EsploraProvider;
 function isValidBlocksTip(tip) {
     return (Array.isArray(tip) &&
         tip.every((t) => {
-            t &&
+            return (t &&
                 typeof t === "object" &&
                 typeof t.id === "string" &&
                 t.id.length > 0 &&
                 typeof t.height === "number" &&
                 t.height >= 0 &&
                 typeof t.mediantime === "number" &&
-                t.mediantime > 0;
+                t.mediantime > 0);
         }));
 }
 const isExplorerTransaction = (tx) => {

package/dist/cjs/utils/transactionHistory.js

@@ -16,7 +16,7 @@ const txKey = {
  * @param {Set<string>} commitmentsToIgnore - A set of commitment IDs that should be excluded from processing.
  * @return {ExtendedArkTransaction[]} A sorted array of extended Ark transactions, representing the transaction history.
  */
-function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore) {
+async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore, getTxCreatedAt) {
     const fromOldestVtxo = [...vtxos].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
     const sent = [];
     let received = [];
@@ -59,21 +59,23 @@ function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore) {
             if (vtxo.arkTxId &&
                 !sent.some((s) => s.key.arkTxid === vtxo.arkTxId)) {
                 const changes = fromOldestVtxo.filter((_) => _.txid === vtxo.arkTxId);
+                // We want to find all the other VTXOs spent by the same transaction to
+                // calculate the full amount of the change.
+                const allSpent = fromOldestVtxo.filter((v) => v.arkTxId === vtxo.arkTxId);
+                const spentAmount = allSpent.reduce((acc, v) => acc + v.value, 0);
                 let txAmount = 0;
                 let txTime = 0;
                 if (changes.length > 0) {
                     const changeAmount = changes.reduce((acc, v) => acc + v.value, 0);
-                    // We want to find all the other VTXOs spent by the same transaction to
-                    // calculate the full amount of the change.
-                    const allSpent = fromOldestVtxo.filter((v) => v.arkTxId === vtxo.arkTxId);
-                    const spentAmount = allSpent.reduce((acc, v) => acc + v.value, 0);
                     txAmount = spentAmount - changeAmount;
                     txTime = changes[0].createdAt.getTime();
                 }
                 else {
-                    txAmount = vtxo.value;
+                    txAmount = spentAmount;
                     // TODO: fetch the vtxo with /v1/indexer/vtxos?outpoints=<vtxo.arkTxid:0> to know when the tx was made
-                    txTime = vtxo.createdAt.getTime() + 1;
+                    txTime = getTxCreatedAt
+                        ? await getTxCreatedAt(vtxo.arkTxId)
+                        : vtxo.createdAt.getTime() + 1;
                 }
                 sent.push({
                     key: { ...txKey, arkTxid: vtxo.arkTxId },

package/dist/cjs/utils/txSizeEstimator.js

@@ -1,6 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TxWeightEstimator = void 0;
+const btc_signer_1 = require("@scure/btc-signer");
+/**
+ * Calculates the byte size required to store a variable-length integer (VarInt).
+ * Bitcoin uses VarInts to compact integer data (like array lengths).
+ *
+ * @param n - The integer value to check
+ * @returns The size in bytes (1, 3, 5, or 9)
+ */
+const getVarIntSize = (n) => {
+    if (n < 0xfd)
+        return 1;
+    if (n <= 0xffff)
+        return 3;
+    if (n <= 0xffffffff)
+        return 5;
+    return 9;
+};
 class TxWeightEstimator {
     constructor(hasWitness, inputCount, outputCount, inputSize, inputWitnessSize, outputSize) {
         this.hasWitness = hasWitness;
@@ -41,16 +58,16 @@ class TxWeightEstimator {
             1 +
             leafControlBlockSize;
         this.inputCount++;
-        this.inputWitnessSize += leafWitnessSize + controlBlockWitnessSize;
+        this.inputWitnessSize += leafWitnessSize + 1 + controlBlockWitnessSize;
         this.inputSize += TxWeightEstimator.INPUT_SIZE;
         this.hasWitness = true;
-        this.inputCount++;
         return this;
     }
-    addP2WKHOutput() {
+    addP2WPKHOutput() {
         this.outputCount++;
         this.outputSize +=
-            TxWeightEstimator.OUTPUT_SIZE + TxWeightEstimator.P2WKH_OUTPUT_SIZE;
+            TxWeightEstimator.OUTPUT_SIZE +
+                TxWeightEstimator.P2WPKH_OUTPUT_SIZE;
         return this;
     }
     addP2TROutput() {
@@ -59,16 +76,24 @@ class TxWeightEstimator {
             TxWeightEstimator.OUTPUT_SIZE + TxWeightEstimator.P2TR_OUTPUT_SIZE;
         return this;
     }
+    /**
+     * Adds an output given a raw script.
+     * Cost = 8 bytes (amount) + varint(scriptLen) + scriptLen
+     */
+    addOutputScript(script) {
+        this.outputCount++;
+        this.outputSize += 8 + getVarIntSize(script.length) + script.length;
+        return this;
+    }
+    /**
+     * Adds an output by decoding the address to get the exact script size.
+     */
+    addOutputAddress(address, network) {
+        const payment = (0, btc_signer_1.Address)(network).decode(address);
+        const script = btc_signer_1.OutScript.encode(payment);
+        return this.addOutputScript(script);
+    }
     vsize() {
-        const getVarIntSize = (n) => {
-            if (n < 0xfd)
-                return 1;
-            if (n < 0xffff)
-                return 3;
-            if (n < 0xffffffff)
-                return 5;
-            return 9;
-        };
         const inputCount = getVarIntSize(this.inputCount);
         const outputCount = getVarIntSize(this.outputCount);
         // Calculate the size of the transaction without witness data
@@ -93,7 +118,7 @@ TxWeightEstimator.P2PKH_SCRIPT_SIG_SIZE = 1 + 73 + 1 + 33;
 TxWeightEstimator.INPUT_SIZE = 32 + 4 + 1 + 4;
 TxWeightEstimator.BASE_CONTROL_BLOCK_SIZE = 1 + 32;
 TxWeightEstimator.OUTPUT_SIZE = 8 + 1;
-TxWeightEstimator.P2WKH_OUTPUT_SIZE = 1 + 1 + 20;
+TxWeightEstimator.P2WPKH_OUTPUT_SIZE = 1 + 1 + 20;
 TxWeightEstimator.BASE_TX_SIZE = 8 + 2; // Version + LockTime
 TxWeightEstimator.WITNESS_HEADER_SIZE = 2; // Flag + Marker
 TxWeightEstimator.WITNESS_SCALE_FACTOR = 4;

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

package/dist/cjs/wallet/unroll.js

@@ -8,6 +8,7 @@ const base_2 = require("../script/base");
 const txSizeEstimator_1 = require("../utils/txSizeEstimator");
 const wallet_1 = require("./wallet");
 const transaction_1 = require("../utils/transaction");
+const utils_1 = require("./utils");
 var Unroll;
 (function (Unroll) {
     let StepType;
@@ -203,7 +204,7 @@ var Unroll;
         for (const input of inputs) {
             tx.addInput(input);
         }
-        txWeightEstimator.addP2TROutput();
+        txWeightEstimator.addOutputAddress(outputAddress, wallet.network);
         let feeRate = await wallet.onchainProvider.getFeeRate();
         if (!feeRate || feeRate < wallet_1.Wallet.MIN_FEE_RATE) {
             feeRate = wallet_1.Wallet.MIN_FEE_RATE;
@@ -212,7 +213,11 @@ var Unroll;
         if (feeAmount > totalAmount) {
             throw new Error("fee amount is greater than the total amount");
         }
-        tx.addOutputAddress(outputAddress, totalAmount - feeAmount);
+        const sendAmount = totalAmount - feeAmount;
+        if (sendAmount < BigInt(utils_1.DUST_AMOUNT)) {
+            throw new Error("send amount is less than dust amount");
+        }
+        tx.addOutputAddress(outputAddress, sendAmount);
         const signedTx = await wallet.identity.sign(tx);
         signedTx.finalize();
         await wallet.onchainProvider.broadcastTransaction(signedTx.hex);

package/dist/cjs/wallet/utils.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DUST_AMOUNT = void 0;
 exports.extendVirtualCoin = extendVirtualCoin;
 exports.extendCoin = extendCoin;
+exports.DUST_AMOUNT = 546; // sats
 function extendVirtualCoin(wallet, vtxo) {
     return {
         ...vtxo,

package/dist/cjs/wallet/wallet.js

@@ -268,7 +268,10 @@ class ReadonlyWallet {
             scripts: [base_1.hex.encode(this.offchainTapscript.pkScript)],
         });
         const { boardingTxs, commitmentsToIgnore } = await this.getBoardingTxs();
-        return (0, transactionHistory_1.buildTransactionHistory)(response.vtxos, boardingTxs, commitmentsToIgnore);
+        const getTxCreatedAt = (txid) => this.indexerProvider
+            .getVtxos({ outpoints: [{ txid, vout: 0 }] })
+            .then((res) => res.vtxos[0]?.createdAt.getTime() || 0);
+        return (0, transactionHistory_1.buildTransactionHistory)(response.vtxos, boardingTxs, commitmentsToIgnore, getTxCreatedAt);
     }
     async getBoardingTxs() {
         const utxos = [];

package/dist/esm/providers/onchain.js

@@ -231,14 +231,14 @@ export class EsploraProvider {
 function isValidBlocksTip(tip) {
     return (Array.isArray(tip) &&
         tip.every((t) => {
-            t &&
+            return (t &&
                 typeof t === "object" &&
                 typeof t.id === "string" &&
                 t.id.length > 0 &&
                 typeof t.height === "number" &&
                 t.height >= 0 &&
                 typeof t.mediantime === "number" &&
-                t.mediantime > 0;
+                t.mediantime > 0);
         }));
 }
 const isExplorerTransaction = (tx) => {

package/dist/esm/utils/transactionHistory.js

@@ -13,7 +13,7 @@ const txKey = {
  * @param {Set<string>} commitmentsToIgnore - A set of commitment IDs that should be excluded from processing.
  * @return {ExtendedArkTransaction[]} A sorted array of extended Ark transactions, representing the transaction history.
  */
-export function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore) {
+export async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore, getTxCreatedAt) {
     const fromOldestVtxo = [...vtxos].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
     const sent = [];
     let received = [];
@@ -56,21 +56,23 @@ export function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgno
             if (vtxo.arkTxId &&
                 !sent.some((s) => s.key.arkTxid === vtxo.arkTxId)) {
                 const changes = fromOldestVtxo.filter((_) => _.txid === vtxo.arkTxId);
+                // We want to find all the other VTXOs spent by the same transaction to
+                // calculate the full amount of the change.
+                const allSpent = fromOldestVtxo.filter((v) => v.arkTxId === vtxo.arkTxId);
+                const spentAmount = allSpent.reduce((acc, v) => acc + v.value, 0);
                 let txAmount = 0;
                 let txTime = 0;
                 if (changes.length > 0) {
                     const changeAmount = changes.reduce((acc, v) => acc + v.value, 0);
-                    // We want to find all the other VTXOs spent by the same transaction to
-                    // calculate the full amount of the change.
-                    const allSpent = fromOldestVtxo.filter((v) => v.arkTxId === vtxo.arkTxId);
-                    const spentAmount = allSpent.reduce((acc, v) => acc + v.value, 0);
                     txAmount = spentAmount - changeAmount;
                     txTime = changes[0].createdAt.getTime();
                 }
                 else {
-                    txAmount = vtxo.value;
+                    txAmount = spentAmount;
                     // TODO: fetch the vtxo with /v1/indexer/vtxos?outpoints=<vtxo.arkTxid:0> to know when the tx was made
-                    txTime = vtxo.createdAt.getTime() + 1;
+                    txTime = getTxCreatedAt
+                        ? await getTxCreatedAt(vtxo.arkTxId)
+                        : vtxo.createdAt.getTime() + 1;
                 }
                 sent.push({
                     key: { ...txKey, arkTxid: vtxo.arkTxId },

package/dist/esm/utils/txSizeEstimator.js

@@ -1,3 +1,20 @@
+import { Address, OutScript } from "@scure/btc-signer";
+/**
+ * Calculates the byte size required to store a variable-length integer (VarInt).
+ * Bitcoin uses VarInts to compact integer data (like array lengths).
+ *
+ * @param n - The integer value to check
+ * @returns The size in bytes (1, 3, 5, or 9)
+ */
+const getVarIntSize = (n) => {
+    if (n < 0xfd)
+        return 1;
+    if (n <= 0xffff)
+        return 3;
+    if (n <= 0xffffffff)
+        return 5;
+    return 9;
+};
 export class TxWeightEstimator {
     constructor(hasWitness, inputCount, outputCount, inputSize, inputWitnessSize, outputSize) {
         this.hasWitness = hasWitness;
@@ -38,16 +55,16 @@ export class TxWeightEstimator {
             1 +
             leafControlBlockSize;
         this.inputCount++;
-        this.inputWitnessSize += leafWitnessSize + controlBlockWitnessSize;
+        this.inputWitnessSize += leafWitnessSize + 1 + controlBlockWitnessSize;
         this.inputSize += TxWeightEstimator.INPUT_SIZE;
         this.hasWitness = true;
-        this.inputCount++;
         return this;
     }
-    addP2WKHOutput() {
+    addP2WPKHOutput() {
         this.outputCount++;
         this.outputSize +=
-            TxWeightEstimator.OUTPUT_SIZE + TxWeightEstimator.P2WKH_OUTPUT_SIZE;
+            TxWeightEstimator.OUTPUT_SIZE +
+                TxWeightEstimator.P2WPKH_OUTPUT_SIZE;
         return this;
     }
     addP2TROutput() {
@@ -56,16 +73,24 @@ export class TxWeightEstimator {
             TxWeightEstimator.OUTPUT_SIZE + TxWeightEstimator.P2TR_OUTPUT_SIZE;
         return this;
     }
+    /**
+     * Adds an output given a raw script.
+     * Cost = 8 bytes (amount) + varint(scriptLen) + scriptLen
+     */
+    addOutputScript(script) {
+        this.outputCount++;
+        this.outputSize += 8 + getVarIntSize(script.length) + script.length;
+        return this;
+    }
+    /**
+     * Adds an output by decoding the address to get the exact script size.
+     */
+    addOutputAddress(address, network) {
+        const payment = Address(network).decode(address);
+        const script = OutScript.encode(payment);
+        return this.addOutputScript(script);
+    }
     vsize() {
-        const getVarIntSize = (n) => {
-            if (n < 0xfd)
-                return 1;
-            if (n < 0xffff)
-                return 3;
-            if (n < 0xffffffff)
-                return 5;
-            return 9;
-        };
         const inputCount = getVarIntSize(this.inputCount);
         const outputCount = getVarIntSize(this.outputCount);
         // Calculate the size of the transaction without witness data
@@ -89,7 +114,7 @@ TxWeightEstimator.P2PKH_SCRIPT_SIG_SIZE = 1 + 73 + 1 + 33;
 TxWeightEstimator.INPUT_SIZE = 32 + 4 + 1 + 4;
 TxWeightEstimator.BASE_CONTROL_BLOCK_SIZE = 1 + 32;
 TxWeightEstimator.OUTPUT_SIZE = 8 + 1;
-TxWeightEstimator.P2WKH_OUTPUT_SIZE = 1 + 1 + 20;
+TxWeightEstimator.P2WPKH_OUTPUT_SIZE = 1 + 1 + 20;
 TxWeightEstimator.BASE_TX_SIZE = 8 + 2; // Version + LockTime
 TxWeightEstimator.WITNESS_HEADER_SIZE = 2; // Flag + Marker
 TxWeightEstimator.WITNESS_SCALE_FACTOR = 4;

package/dist/esm/wallet/onchain.js

@@ -4,6 +4,7 @@ import { ESPLORA_URL, EsploraProvider, } from '../providers/onchain.js';
 import { findP2AOutput, P2A } from '../utils/anchor.js';
 import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
 import { Transaction } from '../utils/transaction.js';
+import { DUST_AMOUNT } from './utils.js';
 /**
  * Onchain Bitcoin wallet implementation for traditional Bitcoin transactions.
  *
@@ -55,11 +56,58 @@ export 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 = TxWeightEstimator.create();
+            for (const _ of selected.inputs) {
+                estimator.addKeySpendInput();
+            }
+            estimator.addOutputAddress(recipientAddress, this.network);
+            if (selected.changeAmount >= BigInt(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 < DUST_AMOUNT) {
             throw new Error("Amount is below dust limit");
         }
         const coins = await this.getCoins();
@@ -70,15 +118,14 @@ export 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();
         // Add inputs
-        for (const input of selected.inputs) {
+        for (const input of inputs) {
             tx.addInput({
                 txid: input.txid,
                 index: input.vout,
@@ -91,9 +138,8 @@ export 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(DUST_AMOUNT)) {
+            tx.addOutputAddress(this.address, changeAmount, this.network);
         }
         // Sign inputs and Finalize
         tx = await this.identity.sign(tx);
@@ -112,7 +158,7 @@ export class OnchainWallet {
         const childVsize = TxWeightEstimator.create()
             .addKeySpendInput(true)
             .addP2AInput()
-            .addP2TROutput()
+            .addOutputAddress(this.address, this.network)
             .vsize().value;
         const packageVSize = parentVsize + Number(childVsize);
         let feeRate = await this.provider.getFeeRate();
@@ -155,7 +201,6 @@ export class 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

package/dist/esm/wallet/unroll.js

@@ -5,6 +5,7 @@ import { VtxoScript } from '../script/base.js';
 import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
 import { Wallet } from './wallet.js';
 import { Transaction } from '../utils/transaction.js';
+import { DUST_AMOUNT } from './utils.js';
 export var Unroll;
 (function (Unroll) {
     let StepType;
@@ -200,7 +201,7 @@ export var Unroll;
         for (const input of inputs) {
             tx.addInput(input);
         }
-        txWeightEstimator.addP2TROutput();
+        txWeightEstimator.addOutputAddress(outputAddress, wallet.network);
         let feeRate = await wallet.onchainProvider.getFeeRate();
         if (!feeRate || feeRate < Wallet.MIN_FEE_RATE) {
             feeRate = Wallet.MIN_FEE_RATE;
@@ -209,7 +210,11 @@ export var Unroll;
         if (feeAmount > totalAmount) {
             throw new Error("fee amount is greater than the total amount");
         }
-        tx.addOutputAddress(outputAddress, totalAmount - feeAmount);
+        const sendAmount = totalAmount - feeAmount;
+        if (sendAmount < BigInt(DUST_AMOUNT)) {
+            throw new Error("send amount is less than dust amount");
+        }
+        tx.addOutputAddress(outputAddress, sendAmount);
         const signedTx = await wallet.identity.sign(tx);
         signedTx.finalize();
         await wallet.onchainProvider.broadcastTransaction(signedTx.hex);

package/dist/esm/wallet/utils.js

@@ -1,3 +1,4 @@
+export const DUST_AMOUNT = 546; // sats
 export function extendVirtualCoin(wallet, vtxo) {
     return {
         ...vtxo,

package/dist/esm/wallet/wallet.js

@@ -230,7 +230,10 @@ export class ReadonlyWallet {
             scripts: [hex.encode(this.offchainTapscript.pkScript)],
         });
         const { boardingTxs, commitmentsToIgnore } = await this.getBoardingTxs();
-        return buildTransactionHistory(response.vtxos, boardingTxs, commitmentsToIgnore);
+        const getTxCreatedAt = (txid) => this.indexerProvider
+            .getVtxos({ outpoints: [{ txid, vout: 0 }] })
+            .then((res) => res.vtxos[0]?.createdAt.getTime() || 0);
+        return buildTransactionHistory(response.vtxos, boardingTxs, commitmentsToIgnore, getTxCreatedAt);
     }
     async getBoardingTxs() {
         const utxos = [];

package/dist/types/utils/transactionHistory.d.ts

@@ -11,5 +11,5 @@ type ExtendedArkTransaction = ArkTransaction & {
  * @param {Set<string>} commitmentsToIgnore - A set of commitment IDs that should be excluded from processing.
  * @return {ExtendedArkTransaction[]} A sorted array of extended Ark transactions, representing the transaction history.
  */
-export declare function buildTransactionHistory(vtxos: VirtualCoin[], allBoardingTxs: ArkTransaction[], commitmentsToIgnore: Set<string>): ExtendedArkTransaction[];
+export declare function buildTransactionHistory(vtxos: VirtualCoin[], allBoardingTxs: ArkTransaction[], commitmentsToIgnore: Set<string>, getTxCreatedAt?: (txid: string) => Promise<number>): Promise<ExtendedArkTransaction[]>;
 export {};

package/dist/types/utils/txSizeEstimator.d.ts

@@ -1,3 +1,4 @@
+import { Network } from "../networks";
 export type VSize = {
     value: bigint;
     fee(feeRate: bigint): bigint;
@@ -7,7 +8,7 @@ export declare class TxWeightEstimator {
     static readonly INPUT_SIZE: number;
     static readonly BASE_CONTROL_BLOCK_SIZE: number;
     static readonly OUTPUT_SIZE: number;
-    static readonly P2WKH_OUTPUT_SIZE: number;
+    static readonly P2WPKH_OUTPUT_SIZE: number;
     static readonly BASE_TX_SIZE: number;
     static readonly WITNESS_HEADER_SIZE = 2;
     static readonly WITNESS_SCALE_FACTOR = 4;
@@ -24,7 +25,16 @@ export declare class TxWeightEstimator {
     addKeySpendInput(isDefault?: boolean): TxWeightEstimator;
     addP2PKHInput(): TxWeightEstimator;
     addTapscriptInput(leafWitnessSize: number, leafScriptSize: number, leafControlBlockSize: number): TxWeightEstimator;
-    addP2WKHOutput(): TxWeightEstimator;
+    addP2WPKHOutput(): TxWeightEstimator;
     addP2TROutput(): TxWeightEstimator;
+    /**
+     * Adds an output given a raw script.
+     * Cost = 8 bytes (amount) + varint(scriptLen) + scriptLen
+     */
+    addOutputScript(script: Uint8Array): TxWeightEstimator;
+    /**
+     * Adds an output by decoding the address to get the exact script size.
+     */
+    addOutputAddress(address: string, network: Network): TxWeightEstimator;
     vsize(): VSize;
 }

package/dist/types/wallet/onchain.d.ts

@@ -25,7 +25,6 @@ import { Transaction } from "../utils/transaction";
 export declare class OnchainWallet implements AnchorBumper {
     private identity;
     static MIN_FEE_RATE: number;
-    static DUST_AMOUNT: number;
     readonly onchainP2TR: P2TR;
     readonly provider: OnchainProvider;
     readonly network: Network;
@@ -34,6 +33,28 @@ export declare class OnchainWallet implements AnchorBumper {
     get address(): string;
     getCoins(): Promise<Coin[]>;
     getBalance(): Promise<number>;
+    /**
+     * 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
+     */
+    private estimateFeesAndSelectCoins;
     send(params: SendBitcoinParams): Promise<string>;
     bumpP2A(parent: Transaction): Promise<[string, string]>;
 }

package/dist/types/wallet/utils.d.ts

@@ -1,5 +1,6 @@
 import type { Coin, ExtendedCoin, ExtendedVirtualCoin, VirtualCoin } from "..";
 import { ReadonlyWallet } from "./wallet";
+export declare const DUST_AMOUNT = 546;
 export declare function extendVirtualCoin(wallet: {
     offchainTapscript: ReadonlyWallet["offchainTapscript"];
 }, vtxo: VirtualCoin): ExtendedVirtualCoin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -53,24 +53,24 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@marcbachmann/cel-js": "7.3.1",
     "@noble/curves": "2.0.0",
     "@noble/secp256k1": "3.0.0",
     "@scure/base": "2.0.0",
     "@scure/btc-signer": "2.0.1",
-    "bip68": "1.0.4",
-    "@marcbachmann/cel-js": "7.0.0"
+    "bip68": "1.0.4"
   },
   "devDependencies": {
     "@types/node": "24.3.1",
     "@vitest/coverage-v8": "3.2.4",
-    "esbuild": "^0.25.9",
-    "expo": "~52.0.47",
+    "esbuild": "^0.27.3",
     "eventsource": "4.0.0",
-    "glob": "11.0.3",
+    "expo": "~52.0.49",
+    "glob": "11.1.0",
     "husky": "9.1.7",
     "prettier": "3.6.2",
-    "rimraf": "^6.0.1",
-    "typedoc": "^0.28.12",
+    "rimraf": "^6.1.2",
+    "typedoc": "^0.28.16",
     "typescript": "5.9.2",
     "vitest": "3.2.4"
   },