@arkade-os/sdk 0.4.26 → 0.4.28

package/dist/esm/wallet/onchain.js

@@ -1,285 +0,0 @@
-import { p2tr } from "@scure/btc-signer";
-import { DEFAULT_NETWORK_NAME } from "./index.js";
-import { getNetwork } from "../networks.js";
-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.
- *
- * This wallet handles regular Bitcoin transactions on the blockchain without
- * using the Arkade protocol. It supports P2TR (Pay-to-Taproot) addresses and
- * provides basic Bitcoin wallet functionality.
- *
- * @example
- * ```typescript
- * const wallet = await OnchainWallet.create(identity, 'mainnet');
- * const balance = await wallet.getBalance();
- * const txid = await wallet.send({
- *   address: 'bc1...',
- *   amount: 50000
- * });
- * ```
- */
-export class OnchainWallet {
-    constructor(identity, network, onchainP2TR, provider) {
-        this.identity = identity;
-        this.network = network;
-        this.onchainP2TR = onchainP2TR;
-        this.provider = provider;
-    }
-    /**
-     * Create an onchain wallet for the given identity and Bitcoin network.
-     *
-     * @param identity - Identity used to derive the Taproot key and sign transactions
-     * @param networkName - Bitcoin network name, @see NetworkName
-     * @param provider - Optional onchain provider override, @see OnchainProvider
-     * @returns Configured onchain wallet
-     * @defaultValue `provider = new EsploraProvider('https://mempool.space/api')`
-     * @throws Error if the configured identity cannot produce a valid x-only public key
-     */
-    static async create(identity, networkName = DEFAULT_NETWORK_NAME, provider) {
-        const pubkey = await identity.xOnlyPublicKey();
-        if (!pubkey) {
-            throw new Error("Invalid configured public key");
-        }
-        const network = getNetwork(networkName);
-        const onchainProvider = provider || new EsploraProvider(ESPLORA_URL[networkName]);
-        const onchainP2TR = p2tr(pubkey, undefined, network);
-        return new OnchainWallet(identity, network, onchainP2TR, onchainProvider);
-    }
-    get address() {
-        return this.onchainP2TR.address || "";
-    }
-    /**
-     * Fetch spendable onchain outputs for the wallet address.
-     *
-     * @returns Spendable onchain outputs for the wallet address
-     * @see getBalance
-     */
-    async getCoins() {
-        return this.provider.getCoins(this.address);
-    }
-    /**
-     * Return the wallet's total onchain balance in satoshis.
-     *
-     * @returns Confirmed plus unconfirmed onchain balance
-     * @see getCoins
-     */
-    async getBalance() {
-        const coins = await this.getCoins();
-        const onchainConfirmed = coins
-            .filter((coin) => coin.status.confirmed)
-            .reduce((sum, coin) => sum + coin.value, 0);
-        const onchainUnconfirmed = coins
-            .filter((coin) => !coin.status.confirmed)
-            .reduce((sum, coin) => sum + coin.value, 0);
-        const onchainTotal = onchainConfirmed + onchainUnconfirmed;
-        return onchainTotal;
-    }
-    /**
-     * Iteratively selects coins and estimates transaction fees until convergence.
-     *
-     * This method handles the circular dependency between output selection and fee
-     * estimation: the fee depends on transaction size, which depends on the number
-     * of inputs (selected outputs) 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 onchain outputs 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");
-    }
-    /**
-     * Send bitcoin to a single onchain address.
-     *
-     * @param params - destination `address`, `amount` (in satoshis), and optional `feeRate` override (other fields ignored)
-     * @returns Broadcast transaction id
-     * @throws Error if the amount is non-positive, below dust, or cannot be funded
-     * @see SendBitcoinParams
-     */
-    async send(params) {
-        if (params.amount <= 0) {
-            throw new Error("Amount must be positive");
-        }
-        if (params.amount < DUST_AMOUNT) {
-            throw new Error("Amount is below dust limit");
-        }
-        const coins = await this.getCoins();
-        let feeRate = params.feeRate;
-        if (!feeRate) {
-            feeRate = await this.provider.getFeeRate();
-        }
-        if (!feeRate || feeRate < OnchainWallet.MIN_FEE_RATE) {
-            feeRate = OnchainWallet.MIN_FEE_RATE;
-        }
-        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 inputs) {
-            tx.addInput({
-                txid: input.txid,
-                index: input.vout,
-                witnessUtxo: {
-                    script: this.onchainP2TR.script,
-                    amount: BigInt(input.value),
-                },
-                tapInternalKey: this.onchainP2TR.tapInternalKey,
-            });
-        }
-        // Add payment output
-        tx.addOutputAddress(params.address, BigInt(params.amount), this.network);
-        if (changeAmount >= BigInt(DUST_AMOUNT)) {
-            tx.addOutputAddress(this.address, changeAmount, this.network);
-        }
-        // Sign inputs and Finalize
-        tx = await this.identity.sign(tx);
-        tx.finalize();
-        // Broadcast
-        const txid = await this.provider.broadcastTransaction(tx.hex);
-        return txid;
-    }
-    /**
-     * CPFP-bump a parent transaction that contains a pay-to-anchor output.
-     *
-     * @param parent - Parent transaction containing a pay-to-anchor output
-     * @returns Tuple of parent transaction id and child transaction id
-     * @throws Error if the parent transaction has no pay-to-anchor output or bumping cannot be funded
-     * @see send
-     */
-    async bumpP2A(parent) {
-        const parentVsize = parent.vsize;
-        let child = new Transaction({
-            version: 3,
-            allowLegacyWitnessUtxo: true,
-        });
-        child.addInput(findP2AOutput(parent)); // throws if not found
-        const childVsize = TxWeightEstimator.create()
-            .addKeySpendInput(true)
-            .addP2AInput()
-            .addOutputAddress(this.address, this.network)
-            .vsize().value;
-        const packageVSize = parentVsize + Number(childVsize);
-        let feeRate = await this.provider.getFeeRate();
-        if (!feeRate || feeRate < OnchainWallet.MIN_FEE_RATE) {
-            feeRate = OnchainWallet.MIN_FEE_RATE;
-        }
-        const fee = Math.ceil(feeRate * packageVSize);
-        if (!fee) {
-            throw new Error(`invalid fee, got ${fee} with vsize ${packageVSize}, feeRate ${feeRate}`);
-        }
-        // Select onchain outputs
-        const coins = await this.getCoins();
-        const selected = selectCoins(coins, fee, true);
-        for (const input of selected.inputs) {
-            child.addInput({
-                txid: input.txid,
-                index: input.vout,
-                witnessUtxo: {
-                    script: this.onchainP2TR.script,
-                    amount: BigInt(input.value),
-                },
-                tapInternalKey: this.onchainP2TR.tapInternalKey,
-            });
-        }
-        child.addOutputAddress(this.address, P2A.amount + selected.changeAmount, this.network);
-        // Sign inputs and Finalize
-        child = await this.identity.sign(child);
-        for (let i = 1; i < child.inputsLength; i++) {
-            child.finalizeIdx(i);
-        }
-        try {
-            await this.provider.broadcastTransaction(parent.hex, child.hex);
-        }
-        catch (error) {
-            console.error(error);
-        }
-        finally {
-            return [parent.hex, child.hex];
-        }
-    }
-}
-OnchainWallet.MIN_FEE_RATE = 1; // sat/vbyte
-/**
- * Select coins to reach a target amount, prioritizing those closer to expiry
- * @param coins List of coins to select from
- * @param targetAmount Target amount to reach in satoshis
- * @param forceChange If true, ensure the coin selection will require a change output
- * @returns Selected coins and change amount, or null if insufficient funds
- */
-export function selectCoins(coins, targetAmount, forceChange = false) {
-    if (isNaN(targetAmount)) {
-        throw new Error("Target amount is NaN, got " + targetAmount);
-    }
-    if (targetAmount < 0) {
-        throw new Error("Target amount is negative, got " + targetAmount);
-    }
-    if (targetAmount === 0) {
-        return { inputs: [], changeAmount: 0n };
-    }
-    // Sort coins by amount (descending)
-    const sortedCoins = [...coins].sort((a, b) => b.value - a.value);
-    const selectedCoins = [];
-    let selectedAmount = 0;
-    // Select coins until we have enough
-    for (const coin of sortedCoins) {
-        selectedCoins.push(coin);
-        selectedAmount += coin.value;
-        if (forceChange
-            ? selectedAmount > targetAmount
-            : selectedAmount >= targetAmount) {
-            break;
-        }
-    }
-    if (selectedAmount === targetAmount) {
-        return { inputs: selectedCoins, changeAmount: 0n };
-    }
-    if (selectedAmount < targetAmount) {
-        throw new Error("Insufficient funds");
-    }
-    const changeAmount = BigInt(selectedAmount - targetAmount);
-    return {
-        inputs: selectedCoins,
-        changeAmount,
-    };
-}

package/dist/esm/wallet/ramps.js

@@ -1,212 +0,0 @@
-import { Estimator } from "../arkfee/index.js";
-import { Address, OutScript } from "@scure/btc-signer";
-import { hex } from "@scure/base";
-import { networks } from "../networks.js";
-import { ArkAddress } from "../script/address.js";
-/**
- * Ramps is a class wrapping `settle` method to provide a more convenient interface for onboarding and offboarding operations.
- *
- * @see IWallet.settle
- * @see onboard
- * @see offboard
- *
- * @example
- * ```typescript
- * const ramps = new Ramps(wallet);
- * const feeInfo = { intentFee: {}, txFeeRate: '1' };
- * await ramps.onboard(feeInfo); // onboard all boarding inputs
- * await ramps.offboard('bc1q...', feeInfo); // collaboratively exit all virtual outputs to an onchain address
- * ```
- */
-export class Ramps {
-    /**
-     * Create convenience wrappers for onboarding and offboarding flows.
-     *
-     * @param wallet - Wallet used to query funds and execute settlement transactions
-     */
-    constructor(wallet) {
-        this.wallet = wallet;
-    }
-    /**
-     * Onboard boarding inputs.
-     *
-     * @param feeInfo - The fee info to deduct from the onboard amount.
-     * @param boardingUtxos - Specific boarding inputs to onboard. If not provided, all boarding inputs will be used.
-     * @param amount - Amount to onboard. If not provided, the total amount of boarding inputs will be onboarded.
-     * @param eventCallback - Optional callback that receives settlement events
-     * @returns The Arkade transaction id created by settlement
-     * @throws Error if no boarding inputs remain after fee deduction or if `amount` exceeds available value
-     * @see IWallet.getBoardingUtxos
-     * @see IWallet.settle
-     * @example
-     * ```typescript
-     * const feeInfo = { intentFee: {}, txFeeRate: '1' };
-     * const ramps = new Ramps(wallet);
-     * await ramps.onboard(feeInfo);
-     * ```
-     */
-    async onboard(feeInfo, boardingUtxos, amount, eventCallback) {
-        boardingUtxos = boardingUtxos ?? (await this.wallet.getBoardingUtxos());
-        // Calculate input fees and filter out boarding inputs where fee >= value.
-        const estimator = new Estimator(feeInfo?.intentFee ?? {});
-        const filteredBoardingUtxos = [];
-        let totalAmount = 0n;
-        for (const utxo of boardingUtxos) {
-            const inputFee = estimator.evalOnchainInput({
-                amount: BigInt(utxo.value),
-            });
-            if (inputFee.satoshis >= utxo.value) {
-                // Skip boarding inputs where spending fees are greater than or equal to the input value.
-                continue;
-            }
-            filteredBoardingUtxos.push(utxo);
-            totalAmount += BigInt(utxo.value) - BigInt(inputFee.satoshis);
-        }
-        if (filteredBoardingUtxos.length === 0) {
-            throw new Error("No boarding utxos available after deducting fees");
-        }
-        let change = 0n;
-        if (amount) {
-            if (amount > totalAmount) {
-                throw new Error("Amount is greater than total amount of boarding utxos after fees");
-            }
-            change = totalAmount - amount;
-        }
-        amount = amount ?? totalAmount;
-        // Calculate offchain output fee using Estimator
-        const offchainAddress = await this.wallet.getAddress();
-        const offchainAddr = ArkAddress.decode(offchainAddress);
-        const offchainScript = hex.encode(offchainAddr.pkScript);
-        const outputFee = estimator.evalOffchainOutput({
-            amount,
-            script: offchainScript,
-        });
-        if (BigInt(outputFee.satoshis) > amount) {
-            throw new Error(`can't deduct fees from onboard amount (${outputFee.satoshis} > ${amount})`);
-        }
-        amount -= BigInt(outputFee.satoshis);
-        const outputs = [
-            {
-                address: offchainAddress,
-                amount,
-            },
-        ];
-        if (change > 0n) {
-            const boardingAddress = await this.wallet.getBoardingAddress();
-            outputs.push({
-                address: boardingAddress,
-                amount: change,
-            });
-        }
-        return this.wallet.settle({
-            inputs: filteredBoardingUtxos,
-            outputs,
-        }, eventCallback);
-    }
-    /**
-     * Offboard virtual outputs, or collaboratively exit them to an onchain address.
-     *
-     * @param destinationAddress - The destination address to offboard to.
-     * @param feeInfo - The fee info to deduct from the offboard amount.
-     * @param amount - The amount to offboard. If not provided, the total amount of virtual outputs will be offboarded.
-     * @param eventCallback - Optional callback that receives settlement events
-     * @returns The Arkade transaction id created by settlement
-     * @throws Error if no virtual outputs remain after fee deduction or the destination address cannot be decoded
-     * @see IWallet.getVtxos
-     * @see IWallet.settle
-     * @example
-     * ```typescript
-     * const feeInfo = { intentFee: {}, txFeeRate: '1' };
-     * const ramps = new Ramps(wallet);
-     * await ramps.offboard('bc1q...', feeInfo);
-     * ```
-     */
-    async offboard(destinationAddress, feeInfo, amount, eventCallback) {
-        const vtxos = await this.wallet.getVtxos({
-            withRecoverable: true,
-            withUnrolled: false,
-        });
-        // Calculate input fees and filter out virtual outputs where fee >= value.
-        const estimator = new Estimator(feeInfo?.intentFee ?? {});
-        const filteredVtxos = [];
-        let totalAmount = 0n;
-        for (const vtxo of vtxos) {
-            const inputFee = estimator.evalOffchainInput({
-                amount: BigInt(vtxo.value),
-                type: vtxo.virtualStatus.state === "swept"
-                    ? "recoverable"
-                    : "vtxo",
-                weight: 0,
-                birth: vtxo.createdAt,
-                expiry: vtxo.virtualStatus.batchExpiry
-                    ? new Date(vtxo.virtualStatus.batchExpiry)
-                    : undefined,
-            });
-            if (inputFee.satoshis >= vtxo.value) {
-                // Skip virtual outputs where spending fees are greater than or equal to the output value.
-                continue;
-            }
-            filteredVtxos.push(vtxo);
-            totalAmount += BigInt(vtxo.value) - BigInt(inputFee.satoshis);
-        }
-        if (filteredVtxos.length === 0) {
-            throw new Error("No vtxos available after deducting fees");
-        }
-        let change = 0n;
-        if (amount) {
-            if (amount > totalAmount) {
-                throw new Error("Amount is greater than total amount of vtxos after fees");
-            }
-            change = totalAmount - amount;
-        }
-        amount = amount ?? totalAmount;
-        const networkNames = [
-            "bitcoin",
-            "regtest",
-            "testnet",
-            "signet",
-            "mutinynet",
-        ];
-        let destinationScript;
-        for (const networkName of networkNames) {
-            try {
-                const network = networks[networkName];
-                const addr = Address(network).decode(destinationAddress);
-                destinationScript = OutScript.encode(addr);
-                break;
-            }
-            catch {
-                // Try next network
-                continue;
-            }
-        }
-        if (!destinationScript) {
-            throw new Error(`Failed to decode destination address: ${destinationAddress}`);
-        }
-        const outputFee = estimator.evalOnchainOutput({
-            amount,
-            script: hex.encode(destinationScript),
-        });
-        if (BigInt(outputFee.satoshis) > amount) {
-            throw new Error(`can't deduct fees from offboard amount (${outputFee.satoshis} > ${amount})`);
-        }
-        amount -= BigInt(outputFee.satoshis);
-        const outputs = [
-            {
-                address: destinationAddress,
-                amount,
-            },
-        ];
-        if (change > 0n) {
-            const offchainAddress = await this.wallet.getAddress();
-            outputs.push({
-                address: offchainAddress,
-                amount: change,
-            });
-        }
-        return this.wallet.settle({
-            inputs: filteredVtxos,
-            outputs,
-        }, eventCallback);
-    }
-}