@arkade-os/sdk 0.4.26 → 0.4.28

package/dist/cjs/wallet/hdDescriptorProvider.js

@@ -1,159 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.HDDescriptorProvider = void 0;
-const descriptors_scure_1 = require("@bitcoinerlab/descriptors-scure");
-const descriptor_1 = require("../identity/descriptor");
-const syncCursors_1 = require("../utils/syncCursors");
-/** Settings key under {@link WalletState.settings} where HD state lives. */
-const HD_SETTINGS_KEY = "hd";
-/**
- * HD-wallet {@link DescriptorProvider} that allocates a fresh signing
- * descriptor on every call. The provider holds no notion of "current" — it
- * is a pure rotating allocator. The question of "which descriptor is the
- * wallet currently bound to?" is answered by querying the contract
- * repository for active contracts, not by asking this provider.
- *
- * State is persisted under `WalletRepository.getWalletState().settings.hd` so
- * that no storage-schema migration is required when switching a wallet from
- * single-key to HD. The provider is backed by an {@link HDCapableIdentity},
- * which carries the wildcard account descriptor template (for derivation)
- * and the signing primitives.
- *
- * The read-modify-write of the persisted index runs inside the shared per-
- * repo `updateWalletState` mutex, so two `getNextSigningDescriptor` callers
- * — including those driving separate `HDDescriptorProvider` instances on
- * the same repo — can never observe the same index.
- *
- * @example
- * ```ts
- * const provider = await HDDescriptorProvider.create(identity, walletRepo);
- * const descriptor = await provider.getNextSigningDescriptor();
- * // descriptor: tr([fp/86'/0'/0']xpub/0/0)
- * const next = await provider.getNextSigningDescriptor();
- * // next: tr([fp/86'/0'/0']xpub/0/1)
- * ```
- */
-class HDDescriptorProvider {
-    constructor(identity, walletRepository) {
-        this.identity = identity;
-        this.walletRepository = walletRepository;
-    }
-    /**
-     * Construct an HDDescriptorProvider. No I/O is performed here;
-     * persisted state is read lazily on the first call to
-     * `getNextSigningDescriptor`. A descriptor-mismatch error surfaces on
-     * first use rather than at boot.
-     */
-    static async create(identity, walletRepository) {
-        return new HDDescriptorProvider(identity, walletRepository);
-    }
-    /**
-     * Allocate the next descriptor and return it. The first call on a fresh
-     * wallet returns descriptor at index 0; subsequent calls return 1, 2, 3,
-     * ... in order. Each call is atomic with respect to other rotations on
-     * the same repo: two concurrent callers can never observe the same
-     * index.
-     */
-    async getNextSigningDescriptor() {
-        return this.mutate((settings) => {
-            const next = settings.lastIndexUsed === undefined
-                ? 0
-                : settings.lastIndexUsed + 1;
-            settings.lastIndexUsed = next;
-            return this.materializeAt(next);
-        });
-    }
-    /**
-     * Returns true when the given descriptor is derivable from this wallet's
-     * seed. Delegates to the underlying identity, which handles both HD and
-     * simple `tr(pubkey)` descriptors.
-     */
-    isOurs(descriptor) {
-        return this.identity.isOurs(descriptor);
-    }
-    /**
-     * Signs each request with the key derived from its descriptor. Delegates
-     * to the identity's signing primitives — the identity, not the provider,
-     * holds the seed.
-     */
-    async signWithDescriptor(requests) {
-        return this.identity.signWithDescriptor(requests);
-    }
-    /** Signs a message using the key derived from `descriptor`. */
-    async signMessageWithDescriptor(descriptor, message, signatureType = "schnorr") {
-        return this.identity.signMessageWithDescriptor(descriptor, message, signatureType);
-    }
-    // ── internals ────────────────────────────────────────────────────
-    /**
-     * Substitute the wildcard in the identity's account-descriptor template
-     * with a concrete index, going through the descriptors-scure parser
-     * rather than ad-hoc string substitution. The parser's `expand({ index })`
-     * call validates that the input is a ranged template AND produces a
-     * canonical materialized key expression at the given index.
-     */
-    materializeAt(index) {
-        const descriptor = this.identity.descriptor;
-        const network = (0, descriptor_1.isMainnetDescriptor)(descriptor)
-            ? descriptors_scure_1.networks.bitcoin
-            : descriptors_scure_1.networks.testnet;
-        const expansion = (0, descriptors_scure_1.expand)({ descriptor, network, index });
-        const keyInfo = expansion.expansionMap?.["@0"];
-        if (!keyInfo?.keyExpression) {
-            throw new Error(`HDDescriptorProvider: cannot materialize descriptor at index ${index}`);
-        }
-        return `tr(${keyInfo.keyExpression})`;
-    }
-    /**
-     * Run the read-modify-write of HD settings inside the shared per-repo
-     * wallet-state mutex. The closure receives a freshly-validated settings
-     * snapshot, mutates it, and returns whatever value the caller wants to
-     * surface; the mutated settings are then persisted as part of the same
-     * atomic update.
-     *
-     * Doing the read inside the lock is what prevents two providers (or two
-     * concurrent callers on the same provider) from racing on a stale index.
-     */
-    async mutate(fn) {
-        let result;
-        await (0, syncCursors_1.updateWalletState)(this.walletRepository, (state) => {
-            const settings = this.parseSettings(state);
-            result = fn(settings);
-            return {
-                ...state,
-                settings: {
-                    ...(state.settings ?? {}),
-                    [HD_SETTINGS_KEY]: settings,
-                },
-            };
-        });
-        return result;
-    }
-    /**
-     * Validate the persisted HD settings (or initialize a fresh record when
-     * absent) and return a clone safe for the caller to mutate.
-     *
-     * The cast to `HDWalletSettings` trusts storage; a corrupted or
-     * partially-migrated repo could otherwise produce `NaN` descriptors.
-     * Fail loud rather than silently derive garbage.
-     */
-    parseSettings(state) {
-        const stored = state.settings?.[HD_SETTINGS_KEY];
-        const expected = this.identity.descriptor;
-        if (!stored) {
-            return { descriptor: expected };
-        }
-        if (stored.descriptor !== expected) {
-            throw new Error(`HD descriptor mismatch: stored "${stored.descriptor}", expected "${expected}". ` +
-                `Refusing to reuse HD state from a different identity.`);
-        }
-        if (stored.lastIndexUsed !== undefined &&
-            (typeof stored.lastIndexUsed !== "number" ||
-                !Number.isInteger(stored.lastIndexUsed) ||
-                stored.lastIndexUsed < 0)) {
-            throw new Error(`Corrupt HD settings: lastIndexUsed is not a non-negative integer (got ${String(stored.lastIndexUsed)}).`);
-        }
-        // Shallow clone so the closure may mutate without aliasing the repo's copy.
-        return { ...stored };
-    }
-}
-exports.HDDescriptorProvider = HDDescriptorProvider;

package/dist/cjs/wallet/index.js

@@ -1,82 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TxType = exports.DEFAULT_NETWORK_NAME = exports.DEFAULT_ARKADE_HRP = exports.DEFAULT_ARKADE_SERVER_URL = void 0;
-exports.isSpendable = isSpendable;
-exports.isRecoverable = isRecoverable;
-exports.isExpired = isExpired;
-exports.isSubdust = isSubdust;
-/** Defaults */
-exports.DEFAULT_ARKADE_SERVER_URL = "https://arkade.computer";
-exports.DEFAULT_ARKADE_HRP = "ark";
-exports.DEFAULT_NETWORK_NAME = "bitcoin";
-/** Wallet transaction direction. */
-var TxType;
-(function (TxType) {
-    TxType["TxSent"] = "SENT";
-    TxType["TxReceived"] = "RECEIVED";
-})(TxType || (exports.TxType = TxType = {}));
-/**
- * Return whether a virtual output is still spendable.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is not marked as spent
- *
- * @see isRecoverable
- * @see isExpired
- */
-function isSpendable(vtxo) {
-    return !vtxo.isSpent;
-}
-/**
- * Return whether a virtual output is recoverable.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is swept but still spendable
- *
- * @remarks
- * Recoverable virtual outputs are typically re-settled into fresh virtual outputs by the virtual output manager.
- *
- * @see isSpendable
- * @see isExpired
- */
-function isRecoverable(vtxo) {
-    return vtxo.virtualStatus.state === "swept" && isSpendable(vtxo);
-}
-/**
- * Return whether a virtual output should be treated as expired.
- *
- * @param vtxo - virtual output to inspect
- * @returns `true` when the virtual output is swept or its batch expiry has passed
- * @remarks
- * On regtest-like environments the upstream expiry value may be expressed as a block
- * height instead of a timestamp. This helper intentionally ignores obviously non-time
- * values to avoid false positives.
- *
- * @see VirtualStatus.batchExpiry
- */
-function isExpired(vtxo) {
-    if (vtxo.virtualStatus.state === "swept")
-        return true; // swept by server = expired
-    const expiry = vtxo.virtualStatus.batchExpiry;
-    if (!expiry)
-        return false;
-    // we use this as a workaround to avoid issue on regtest where expiry date is expressed in blockheight instead of timestamp
-    // if expiry, as Date, is before 2025, then we admit it's too small to be a timestamp
-    // TODO: API should return the expiry unit
-    const expireAt = new Date(expiry);
-    if (expireAt.getFullYear() < 2025)
-        return false;
-    return expiry <= Date.now();
-}
-/**
- * Return whether a virtual output is below the dust threshold.
- *
- * @param vtxo - virtual output to inspect
- * @param dust - dust threshold in satoshis
- * @returns `true` when the virtual output value is below `dust`
- *
- * @see isRecoverable
- */
-function isSubdust(vtxo, dust) {
-    return vtxo.value < dust;
-}

package/dist/cjs/wallet/onchain.js

@@ -1,290 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OnchainWallet = void 0;
-exports.selectCoins = selectCoins;
-const btc_signer_1 = require("@scure/btc-signer");
-const _1 = require(".");
-const networks_1 = require("../networks");
-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.
- *
- * 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
- * });
- * ```
- */
-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 = _1.DEFAULT_NETWORK_NAME, provider) {
-        const pubkey = await identity.xOnlyPublicKey();
-        if (!pubkey) {
-            throw new Error("Invalid configured public key");
-        }
-        const network = (0, networks_1.getNetwork)(networkName);
-        const onchainProvider = provider || new onchain_1.EsploraProvider(onchain_1.ESPLORA_URL[networkName]);
-        const onchainP2TR = (0, btc_signer_1.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 = 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");
-    }
-    /**
-     * 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 < utils_1.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_1.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(utils_1.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_1.Transaction({
-            version: 3,
-            allowLegacyWitnessUtxo: true,
-        });
-        child.addInput((0, anchor_1.findP2AOutput)(parent)); // throws if not found
-        const childVsize = txSizeEstimator_1.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, anchor_1.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];
-        }
-    }
-}
-exports.OnchainWallet = OnchainWallet;
-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
- */
-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,
-    };
-}