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

package/dist/esm/wallet/delegator.js

@@ -0,0 +1,231 @@
+import { ArkAddress, decodeTapscript, Estimator, Intent, isRecoverable, MultisigTapscript, VtxoScript, } from '../index.js';
+import { base64, hex } from "@scure/base";
+import { scriptFromTapLeafScript } from '../script/base.js';
+import { buildForfeitTxWithOutput } from '../forfeit.js';
+import { Address, OutScript, SigHash } from "@scure/btc-signer";
+import { getNetwork } from '../networks.js';
+export class DelegatorManagerImpl {
+    constructor(delegatorProvider, arkInfoProvider, identity) {
+        this.delegatorProvider = delegatorProvider;
+        this.arkInfoProvider = arkInfoProvider;
+        this.identity = identity;
+    }
+    async delegate(vtxos, destination, delegateAt) {
+        if (vtxos.length === 0) {
+            return { delegated: [], failed: [] };
+        }
+        const destinationScript = ArkAddress.decode(destination).pkScript;
+        // if explicit delegateAt is provided, delegate all vtxos at once without sorting
+        if (delegateAt) {
+            try {
+                await delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, vtxos, destinationScript, delegateAt);
+            }
+            catch (error) {
+                return { delegated: [], failed: [{ outpoints: vtxos, error }] };
+            }
+            return { delegated: vtxos, failed: [] };
+        }
+        // if no explicit delegateAt is provided, sort vtxos by expiry and delegate in groups of the same expiry day
+        const groupByExpiry = new Map();
+        let recoverableVtxos = [];
+        for (const vtxo of vtxos) {
+            if (isRecoverable(vtxo)) {
+                recoverableVtxos.push(vtxo);
+                continue;
+            }
+            const expiry = vtxo.virtualStatus.batchExpiry;
+            if (!expiry)
+                continue;
+            const dayKey = getDayTimestamp(expiry);
+            groupByExpiry.set(dayKey, [
+                ...(groupByExpiry.get(dayKey) ?? []),
+                vtxo,
+            ]);
+        }
+        // if no groups, it means we only need to delegate the recoverable vtxos
+        if (groupByExpiry.size === 0) {
+            try {
+                await delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, recoverableVtxos, destinationScript, delegateAt);
+            }
+            catch (error) {
+                return {
+                    delegated: [],
+                    failed: [{ outpoints: recoverableVtxos, error }],
+                };
+            }
+            return { delegated: recoverableVtxos, failed: [] };
+        }
+        // search for the earliest group, include recoverable vtxos into it
+        const earliestGroup = Math.min(...groupByExpiry.keys());
+        groupByExpiry.set(earliestGroup, [
+            ...(groupByExpiry.get(earliestGroup) ?? []),
+            ...recoverableVtxos,
+        ]);
+        const groupsList = Array.from(groupByExpiry.entries());
+        const result = await Promise.allSettled(groupsList.map(async ([, vtxosGroup]) => delegate(this.identity, this.delegatorProvider, this.arkInfoProvider, vtxosGroup, destinationScript)));
+        const delegated = [];
+        const failed = [];
+        for (const [index, resultItem] of result.entries()) {
+            const vtxos = groupsList[index][1];
+            if (resultItem.status === "rejected") {
+                failed.push({ outpoints: vtxos, error: resultItem.reason });
+                continue;
+            }
+            delegated.push(...vtxos);
+        }
+        return { delegated, failed };
+    }
+}
+/**
+ * Delegates virtual coins to a delegator provider, allowing them to manage the coins renewal
+ * on behalf of the wallet.
+ * @param vtxos - Array of extended virtual coins to delegate. Must not be empty.
+ * @param delegateAt - Optional Date specifying when the delegation
+ *                     should occur. If not provided, defaults to 12 hours before the earliest
+ *                     expiry time of the provided vtxos.
+ */
+async function delegate(identity, delegatorProvider, arkInfoProvider, vtxos, destinationScript, delegateAt) {
+    if (vtxos.length === 0) {
+        throw new Error("unable to delegate: no vtxos provided");
+    }
+    if (!delegatorProvider) {
+        throw new Error("unable to delegate: delegator provider not configured");
+    }
+    if (!delegateAt) {
+        const expiryTimestamp = vtxos
+            .filter((coin) => !isRecoverable(coin) && coin.virtualStatus.batchExpiry)
+            .reduce((min, coin) => Math.min(min, coin.virtualStatus.batchExpiry), Number.MAX_SAFE_INTEGER);
+        if (!expiryTimestamp || expiryTimestamp === Number.MAX_SAFE_INTEGER) {
+            // if no expiry (recoverable vtxos), delegate 1 minute from now
+            delegateAt = new Date(Date.now() + 1 * 60 * 1000);
+        }
+        else {
+            const remainingTimeMs = expiryTimestamp - Date.now();
+            if (remainingTimeMs <= 0) {
+                delegateAt = new Date(Date.now() + 1 * 60 * 1000);
+            }
+            else {
+                // delegate 10% before the expiry
+                delegateAt = new Date(expiryTimestamp - remainingTimeMs * 0.1);
+            }
+        }
+    }
+    const { fees, dust, forfeitAddress, network } = await arkInfoProvider.getInfo();
+    const delegateAtSeconds = delegateAt.getTime() / 1000;
+    const estimator = new Estimator({
+        ...fees.intentFee,
+        // replace now() function with the delegateAt timestamp
+        offchainInput: fees.intentFee.offchainInput?.replace("now()", `double(${delegateAtSeconds})`),
+        offchainOutput: fees.intentFee.offchainOutput?.replace("now()", `double(${delegateAtSeconds})`),
+    });
+    let amount = 0n;
+    for (const coin of vtxos) {
+        const inputFee = estimator.evalOffchainInput({
+            amount: BigInt(coin.value),
+            type: "vtxo",
+            weight: 0,
+            birth: coin.createdAt,
+            expiry: coin.virtualStatus.batchExpiry
+                ? new Date(coin.virtualStatus.batchExpiry)
+                : undefined,
+        });
+        if (inputFee.value >= coin.value) {
+            continue;
+        }
+        amount += BigInt(coin.value) - BigInt(inputFee.value);
+    }
+    const { delegatorAddress, pubkey, fee } = await delegatorProvider.getDelegateInfo();
+    const outputs = [];
+    const delegatorFee = BigInt(Number(fee));
+    if (delegatorFee > 0n) {
+        outputs.push({
+            script: ArkAddress.decode(delegatorAddress).pkScript,
+            amount: delegatorFee,
+        });
+    }
+    const outputFee = outputs.reduce((fee, output) => {
+        if (!output.amount || !output.script)
+            return fee;
+        return (fee +
+            estimator.evalOffchainOutput({
+                amount: output.amount,
+                script: hex.encode(output.script),
+            }).satoshis);
+    }, 0);
+    if (amount - BigInt(outputFee) <= dust) {
+        throw new Error("Amount is below dust limit, cannot delegate");
+    }
+    amount -= BigInt(outputFee);
+    amount -= delegatorFee;
+    if (amount <= dust) {
+        throw new Error("Amount is below dust limit, cannot delegate");
+    }
+    outputs.push({
+        script: destinationScript,
+        amount: amount,
+    });
+    const registerIntent = await makeSignedDelegateIntent(identity, vtxos, outputs, [], [pubkey], delegateAtSeconds);
+    const forfeitOutputScript = OutScript.encode(Address(getNetwork(network)).decode(forfeitAddress));
+    const forfeits = await Promise.all(vtxos
+        .filter((v) => !isRecoverable(v))
+        .map(async (coin) => {
+        const forfeit = await makeDelegateForfeitTx(coin, dust, pubkey, forfeitOutputScript, identity);
+        return base64.encode(forfeit.toPSBT());
+    }));
+    await delegatorProvider.delegate(registerIntent, forfeits);
+}
+async function makeDelegateForfeitTx(input, connectorAmount, delegatePubkey, forfeitOutputScript, identity) {
+    if (delegatePubkey.length === 66) {
+        delegatePubkey = delegatePubkey.slice(2);
+    }
+    const vtxoScript = VtxoScript.decode(input.tapTree);
+    const delegateTapLeaf = vtxoScript.leaves.find((tapLeaf) => {
+        const arkTapscript = decodeTapscript(scriptFromTapLeafScript(tapLeaf));
+        if (!MultisigTapscript.is(arkTapscript))
+            return false;
+        if (!arkTapscript.params.pubkeys
+            .map(hex.encode)
+            .includes(delegatePubkey))
+            return false;
+        return true;
+    });
+    if (!delegateTapLeaf) {
+        throw new Error(`delegate tap leaf not found for input: ${input.txid}:${input.vout}`);
+    }
+    const tx = buildForfeitTxWithOutput([
+        {
+            txid: input.txid,
+            index: input.vout,
+            witnessUtxo: {
+                amount: BigInt(input.value),
+                script: VtxoScript.decode(input.tapTree).pkScript,
+            },
+            sighashType: SigHash.ALL_ANYONECANPAY,
+            tapLeafScript: [delegateTapLeaf],
+        },
+    ], {
+        script: forfeitOutputScript,
+        amount: BigInt(input.value) + connectorAmount,
+    });
+    return identity.sign(tx);
+}
+async function makeSignedDelegateIntent(identity, coins, outputs, onchainOutputsIndexes, cosignerPubKeys, validAt) {
+    const message = {
+        type: "register",
+        onchain_output_indexes: onchainOutputsIndexes,
+        valid_at: Math.floor(validAt),
+        expire_at: 0,
+        cosigners_public_keys: cosignerPubKeys,
+    };
+    const proof = Intent.create(message, coins, outputs);
+    const signedProof = await identity.sign(proof);
+    return {
+        proof: base64.encode(signedProof.toPSBT()),
+        message,
+    };
+}
+function getDayTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    date.setUTCHours(0, 0, 0, 0);
+    return date.getTime();
+}

package/dist/esm/wallet/expo/background.js

@@ -0,0 +1,128 @@
+import { hex } from "@scure/base";
+import { runTasks } from '../../worker/expo/taskRunner.js';
+import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from '../../worker/expo/processors/index.js';
+import { DefaultVtxo } from '../../script/default.js';
+import { ExpoArkProvider } from '../../providers/expoArk.js';
+import { ExpoIndexerProvider } from '../../providers/expoIndexer.js';
+import { extendVirtualCoin, extendVtxoFromContract, getRandomId, } from '../utils.js';
+function requireTaskManager() {
+    try {
+        return require("expo-task-manager");
+    }
+    catch {
+        throw new Error("expo-task-manager is required for background tasks. " +
+            "Install it with: npx expo install expo-task-manager");
+    }
+}
+function requireBackgroundTask() {
+    try {
+        return require("expo-background-task");
+    }
+    catch {
+        throw new Error("expo-background-task is required for background tasks. " +
+            "Install it with: npx expo install expo-background-task");
+    }
+}
+/**
+ * Define the Expo background task handler.
+ *
+ * **Must be called at module/global scope** (before React mounts).
+ * Internally calls `TaskManager.defineTask()`.
+ *
+ * @example
+ * ```ts
+ * // At the top of your app entry file
+ * import { defineExpoBackgroundTask } from "@arkade-os/sdk/wallet/expo";
+ * import { AsyncStorageTaskQueue } from "@arkade-os/sdk/worker/expo";
+ * import AsyncStorage from "@react-native-async-storage/async-storage";
+ *
+ * const taskQueue = new AsyncStorageTaskQueue(AsyncStorage);
+ * defineExpoBackgroundTask("ark-background-poll", {
+ *     taskQueue,
+ *     walletRepository: new IndexedDBWalletRepository(),
+ *     contractRepository: new IndexedDBContractRepository(),
+ * });
+ * ```
+ */
+export function defineExpoBackgroundTask(taskName, options) {
+    const TaskManager = requireTaskManager();
+    const BackgroundTask = requireBackgroundTask();
+    const { taskQueue, walletRepository, contractRepository, processors = [contractPollProcessor], } = options;
+    TaskManager.defineTask(taskName, async () => {
+        try {
+            const config = await taskQueue.loadConfig();
+            if (!config) {
+                // No config persisted yet — ExpoWallet.setup() hasn't run.
+                // Nothing to do.
+                return BackgroundTask.BackgroundTaskResult.Success;
+            }
+            // Reconstruct providers
+            const indexerProvider = new ExpoIndexerProvider(config.arkServerUrl);
+            const arkProvider = new ExpoArkProvider(config.arkServerUrl);
+            // Reconstruct default offchainTapscript as fallback
+            // for VTXOs not associated with a contract.
+            const defaultTapscript = new DefaultVtxo.Script({
+                pubKey: hex.decode(config.pubkeyHex),
+                serverPubKey: hex.decode(config.serverPubKeyHex),
+                csvTimelock: {
+                    value: BigInt(config.exitTimelockValue),
+                    type: config.exitTimelockType,
+                },
+            });
+            await runTasks(taskQueue, processors, {
+                walletRepository,
+                contractRepository,
+                indexerProvider,
+                arkProvider,
+                extendVtxo: (vtxo, contract) => {
+                    if (contract) {
+                        return extendVtxoFromContract(vtxo, contract);
+                    }
+                    return extendVirtualCoin({ offchainTapscript: defaultTapscript }, vtxo);
+                },
+            });
+            // Acknowledge outbox results (no foreground to consume them)
+            const results = await taskQueue.getResults();
+            if (results.length > 0) {
+                await taskQueue.acknowledgeResults(results.map((r) => r.id));
+            }
+            // Re-seed the contract-poll task for the next OS wake
+            const existing = await taskQueue.getTasks(CONTRACT_POLL_TASK_TYPE);
+            if (existing.length === 0) {
+                const task = {
+                    id: getRandomId(),
+                    type: CONTRACT_POLL_TASK_TYPE,
+                    data: {},
+                    createdAt: Date.now(),
+                };
+                await taskQueue.addTask(task);
+            }
+            return BackgroundTask.BackgroundTaskResult.Success;
+        }
+        catch (error) {
+            console.error("[ark-sdk] Background task failed:", error instanceof Error ? error.message : error);
+            return BackgroundTask.BackgroundTaskResult.Failed;
+        }
+    });
+}
+/**
+ * Activate the OS-level background task scheduler.
+ *
+ * Call this after {@link defineExpoBackgroundTask} (typically inside
+ * {@link ExpoWallet.setup} or in a React component after wallet init).
+ *
+ * @param minimumInterval - Minimum interval in minutes (default 15).
+ */
+export async function registerExpoBackgroundTask(taskName, options) {
+    const BackgroundTask = requireBackgroundTask();
+    await BackgroundTask.registerTaskAsync(taskName, {
+        minimumInterval: (options?.minimumInterval ?? 15) * 60,
+    });
+}
+/**
+ * Unregister the background task from the OS scheduler.
+ */
+export async function unregisterExpoBackgroundTask(taskName) {
+    const BackgroundTask = requireBackgroundTask();
+    await BackgroundTask.unregisterTaskAsync(taskName);
+}

package/dist/esm/wallet/expo/index.js

@@ -0,0 +1,2 @@
+export { ExpoWallet } from './wallet.js';
+export { defineExpoBackgroundTask, registerExpoBackgroundTask, unregisterExpoBackgroundTask, } from './background.js';

package/dist/esm/wallet/expo/wallet.js

@@ -0,0 +1,194 @@
+import { hex } from "@scure/base";
+import { Wallet } from '../wallet.js';
+import { RestArkProvider } from '../../providers/ark.js';
+import { runTasks } from '../../worker/expo/taskRunner.js';
+import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from '../../worker/expo/processors/index.js';
+import { extendVirtualCoin, extendVtxoFromContract, getRandomId, } from '../utils.js';
+import { DefaultVtxo } from '../../script/default.js';
+/**
+ * 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();
+ * ```
+ */
+export 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.create(config);
+        const processors = config.background.processors ?? [
+            contractPollProcessor,
+        ];
+        const deps = {
+            walletRepository: wallet.walletRepository,
+            contractRepository: wallet.contractRepository,
+            indexerProvider: wallet.indexerProvider,
+            arkProvider: wallet.arkProvider,
+            extendVtxo: (vtxo, contract) => {
+                if (contract) {
+                    return extendVtxoFromContract(vtxo, contract);
+                }
+                return 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 RestArkProvider
+                    ? wallet.arkProvider.serverUrl
+                    : undefined);
+            if (arkServerUrl) {
+                const timelock = wallet.offchainTapscript.options.csvTimelock ??
+                    DefaultVtxo.Script.DEFAULT_TIMELOCK;
+                const bgConfig = {
+                    arkServerUrl,
+                    pubkeyHex: hex.encode(wallet.offchainTapscript.options.pubKey),
+                    serverPubKeyHex: 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 import("./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 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(CONTRACT_POLL_TASK_TYPE);
+        if (existing.length > 0)
+            return;
+        const task = {
+            id: getRandomId(),
+            type: 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 import("./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;
+    }
+}

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