@arkade-os/sdk 0.4.22 → 0.4.24

package/dist/esm/wallet/hdDescriptorProvider.js

@@ -0,0 +1,155 @@
+import { expand, networks } from "@bitcoinerlab/descriptors-scure";
+import { isMainnetDescriptor } from '../identity/descriptor.js';
+import { updateWalletState } from '../utils/syncCursors.js';
+/** 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)
+ * ```
+ */
+export 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 = isMainnetDescriptor(descriptor)
+            ? networks.bitcoin
+            : networks.testnet;
+        const expansion = 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 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 };
+    }
+}

package/dist/esm/wallet/index.js

@@ -1,3 +1,7 @@
+/** Defaults */
+export const DEFAULT_ARKADE_SERVER_URL = "https://arkade.computer";
+export const DEFAULT_ARKADE_HRP = "ark";
+export const DEFAULT_NETWORK_NAME = "bitcoin";
 /** Wallet transaction direction. */
 export var TxType;
 (function (TxType) {

package/dist/esm/wallet/onchain.js

@@ -1,4 +1,5 @@
 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';
@@ -39,7 +40,7 @@ export class OnchainWallet {
      * @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, provider) {
+    static async create(identity, networkName = DEFAULT_NETWORK_NAME, provider) {
         const pubkey = await identity.xOnlyPublicKey();
         if (!pubkey) {
             throw new Error("Invalid configured public key");

package/dist/esm/wallet/serviceWorker/wallet-message-handler.js

@@ -2,6 +2,8 @@ import { RestIndexerProvider } from '../../providers/indexer.js';
 import { isExpired, isRecoverable, isSpendable, isSubdust, } from '../index.js';
 import { extendCoin } from '../utils.js';
 import { buildTransactionHistory } from '../../utils/transactionHistory.js';
+import { filterVtxosForScript, warnAndFilterVtxosForScript, } from '../../contracts/vtxoOwnership.js';
+import { scriptFromArkAddress } from '../../repositories/scriptFromAddress.js';
 export class WalletNotInitializedError extends Error {
     constructor() {
         super("Wallet handler not initialized");
@@ -508,7 +510,7 @@ export class WalletMessageHandler {
         for (const vtxo of spendableVtxos) {
             if (vtxo.assets) {
                 for (const a of vtxo.assets) {
-                    const current = assetBalances.get(a.assetId) ?? 0;
+                    const current = assetBalances.get(a.assetId) ?? 0n;
                     assetBalances.set(a.assetId, current + a.amount);
                 }
             }
@@ -581,11 +583,45 @@ export class WalletMessageHandler {
                     const { newVtxos, spentVtxos } = funds;
                     if (newVtxos.length + spentVtxos.length === 0)
                         return;
-                    // save virtual outputs using unified repository
-                    await this.walletRepository?.saveVtxos(address, [
-                        ...newVtxos,
-                        ...spentVtxos,
-                    ]);
+                    // Save virtual outputs using unified repository. The
+                    // event may carry rows for several scripts (other
+                    // contracts the wallet watches), so split by script and
+                    // save each bucket under its own contract address rather
+                    // than saving a mixed-script array under one address.
+                    const byScript = new Map();
+                    for (const v of [...newVtxos, ...spentVtxos]) {
+                        if (!v.script) {
+                            // Without a script we can't route the row to the
+                            // right contract bucket; surface the drop instead
+                            // of silently losing the VTXO.
+                            console.warn(`WalletMessageHandler.notifyIncomingFunds: dropping VTXO without script ${v.txid}:${v.vout}`);
+                            continue;
+                        }
+                        const arr = byScript.get(v.script) ?? [];
+                        arr.push(v);
+                        byScript.set(v.script, arr);
+                    }
+                    let walletScript;
+                    try {
+                        walletScript = scriptFromArkAddress(address);
+                    }
+                    catch {
+                        walletScript = undefined;
+                    }
+                    const cm = await this.readonlyWallet.getContractManager();
+                    const contracts = await cm.getContracts();
+                    const addrByScript = new Map(contracts.map((c) => [c.script, c.address]));
+                    for (const [script, vtxos] of byScript) {
+                        const filtered = warnAndFilterVtxosForScript(vtxos, script, "WalletMessageHandler.notifyIncomingFunds");
+                        if (filtered.length === 0)
+                            continue;
+                        const targetAddress = script === walletScript
+                            ? address
+                            : addrByScript.get(script);
+                        if (!targetAddress)
+                            continue;
+                        await this.walletRepository?.saveVtxos(targetAddress, filtered);
+                    }
                     // notify all clients about the virtual output state update
                     this.scheduleForNextTick(() => this.tagged({
                         type: "VTXO_UPDATE",
@@ -797,17 +833,31 @@ export class WalletMessageHandler {
                 }
             }
         };
-        // Aggregate virtual outputs from all contract addresses
+        // Aggregate virtual outputs from all contract addresses. Address
+        // buckets may carry legacy duplicate rows from other contracts; gate
+        // each bucket by its owning contract script before deduplication so a
+        // wrong-script row never wins the txid:vout race.
         const manager = await this.readonlyWallet.getContractManager();
         const contracts = await manager.getContracts();
         for (const contract of contracts) {
             const vtxos = await this.walletRepository.getVtxos(contract.address);
-            addVtxos(vtxos);
+            addVtxos(filterVtxosForScript(vtxos, contract.script));
         }
-        // Also check the wallet's primary address
+        // Also check the wallet's primary address. Decode it to its script
+        // and apply the same script gate. Failing to decode the wallet's own
+        // address is a structural bug — surfacing the error is safer than
+        // silently dropping the primary bucket and zeroing the user's
+        // visible balance.
         const walletAddress = await this.readonlyWallet.getAddress();
+        let walletScript;
+        try {
+            walletScript = scriptFromArkAddress(walletAddress);
+        }
+        catch (e) {
+            throw new Error(`WalletMessageHandler.getVtxosFromRepo: failed to derive script from wallet address ${walletAddress}: ${e instanceof Error ? e.message : String(e)}`);
+        }
         const walletVtxos = await this.walletRepository.getVtxos(walletAddress);
-        addVtxos(walletVtxos);
+        addVtxos(filterVtxosForScript(walletVtxos, walletScript));
         return allVtxos;
     }
     /**

package/dist/esm/wallet/serviceWorker/wallet.js

@@ -5,6 +5,7 @@ import { IndexedDBContractRepository, IndexedDBWalletRepository, } from '../../r
 import { DEFAULT_MESSAGE_TAG, } from './wallet-message-handler.js';
 import { getRandomId } from '../utils.js';
 import { MESSAGE_BUS_NOT_INITIALIZED, ServiceWorkerTimeoutError, } from '../../worker/errors.js';
+import { getArkadeServerUrl } from '../wallet.js';
 // Check by error message content instead of instanceof because postMessage uses the
 // structured clone algorithm which strips the prototype chain — the page
 // receives a plain Error, not the original MessageBusNotInitializedError.
@@ -211,7 +212,7 @@ export class ServiceWorkerReadonlyWallet {
             .then(hex.encode);
         const initWalletPayload = {
             key: { publicKey },
-            arkServerUrl: options.arkServerUrl,
+            arkServerUrl: getArkadeServerUrl(options),
             arkServerPublicKey: options.arkServerPublicKey,
             delegatorUrl: options.delegatorUrl,
         };
@@ -226,7 +227,7 @@ export class ServiceWorkerReadonlyWallet {
         const busInitConfig = {
             wallet: serializedWallet,
             arkServer: {
-                url: options.arkServerUrl,
+                url: getArkadeServerUrl(options),
                 publicKey: options.arkServerPublicKey,
             },
             delegatorUrl: options.delegatorUrl,
@@ -884,7 +885,7 @@ export class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet {
             : null;
         const initWalletPayload = {
             key: legacyPrivateKey ? { privateKey: legacyPrivateKey } : {},
-            arkServerUrl: options.arkServerUrl,
+            arkServerUrl: getArkadeServerUrl(options),
             arkServerPublicKey: options.arkServerPublicKey,
             delegatorUrl: options.delegatorUrl,
         };
@@ -899,7 +900,7 @@ export class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet {
         const busInitConfig = {
             wallet: serializedWallet,
             arkServer: {
-                url: options.arkServerUrl,
+                url: getArkadeServerUrl(options),
                 publicKey: options.arkServerPublicKey,
             },
             delegatorUrl: options.delegatorUrl,

package/dist/esm/wallet/unroll.js

@@ -1,6 +1,6 @@
 import { base64, hex } from "@scure/base";
 import { SigHash, TaprootControlBlock } from "@scure/btc-signer";
-import { timelockToSequence } from '../contracts/handlers/helpers.js';
+import { timelockToSequence } from '../utils/timelock.js';
 import { ChainTxType } from '../providers/indexer.js';
 import { VtxoScript } from '../script/base.js';
 import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
@@ -126,10 +126,12 @@ export var Unroll;
                 // finalize Arkade transaction
                 tx.finalize();
             }
+            const pkg = await this.bumper.bumpP2A(tx);
             return {
                 type: StepType.UNROLL,
                 tx,
-                do: doUnroll(this.bumper, this.explorer, tx),
+                pkg,
+                do: doUnroll(this.explorer, pkg),
             };
         }
         /**
@@ -161,79 +163,88 @@ export var Unroll;
      * @returns the txid of the transaction spending the unrolled funds
      */
     async function completeUnroll(wallet, vtxoTxids, outputAddress) {
-        const chainTip = await wallet.onchainProvider.getChainTip();
-        let vtxos = await wallet.getVtxos({ withUnrolled: true });
-        vtxos = vtxos.filter((vtxo) => vtxoTxids.includes(vtxo.txid));
-        if (vtxos.length === 0) {
-            throw new Error("No vtxos to complete unroll");
-        }
-        const inputs = [];
-        let totalAmount = 0n;
-        const txWeightEstimator = TxWeightEstimator.create();
-        for (const vtxo of vtxos) {
-            if (!vtxo.isUnrolled) {
-                throw new Error(`Vtxo ${vtxo.txid}:${vtxo.vout} is not fully unrolled, use unroll first`);
-            }
-            const txStatus = await wallet.onchainProvider.getTxStatus(vtxo.txid);
-            if (!txStatus.confirmed) {
-                throw new Error(`tx ${vtxo.txid} is not confirmed`);
-            }
-            const exit = availableExitPath({ height: txStatus.blockHeight, time: txStatus.blockTime }, chainTip, vtxo);
-            if (!exit) {
-                throw new Error(`no available exit path found for vtxo ${vtxo.txid}:${vtxo.vout}`);
-            }
-            const spendingLeaf = VtxoScript.decode(vtxo.tapTree).findLeaf(hex.encode(exit.script));
-            if (!spendingLeaf) {
-                throw new Error(`spending leaf not found for vtxo ${vtxo.txid}:${vtxo.vout}`);
-            }
-            totalAmount += BigInt(vtxo.value);
-            const sequence = timelockToSequence(exit.params.timelock);
-            inputs.push({
-                txid: vtxo.txid,
-                index: vtxo.vout,
-                tapLeafScript: [spendingLeaf],
-                sequence,
-                witnessUtxo: {
-                    amount: BigInt(vtxo.value),
-                    script: VtxoScript.decode(vtxo.tapTree).pkScript,
-                },
-                sighashType: SigHash.DEFAULT,
-            });
-            txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, TaprootControlBlock.encode(spendingLeaf[0]).length);
-        }
-        const tx = new Transaction({ version: 2 });
-        for (const input of inputs) {
-            tx.addInput(input);
-        }
-        txWeightEstimator.addOutputAddress(outputAddress, wallet.network);
-        let feeRate = await wallet.onchainProvider.getFeeRate();
-        if (!feeRate || feeRate < Wallet.MIN_FEE_RATE) {
-            feeRate = Wallet.MIN_FEE_RATE;
-        }
-        const feeAmount = txWeightEstimator.vsize().fee(BigInt(feeRate));
-        if (feeAmount > totalAmount) {
-            throw new Error("fee amount is greater than the total amount");
-        }
-        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();
+        const signedTx = await prepareUnrollTransaction(wallet, vtxoTxids, outputAddress);
         await wallet.onchainProvider.broadcastTransaction(signedTx.hex);
         return signedTx.id;
     }
     Unroll.completeUnroll = completeUnroll;
 })(Unroll || (Unroll = {}));
+/**
+ * Prepares the transaction that spends the CSV path to complete unrolling a VTXO.
+ * @param wallet the wallet owning the VTXO(s)
+ * @param vtxoTxIds the txids of the VTXO(s) to complete unroll
+ * @param outputAddress the address to send the unrolled funds to
+ * @throws if the VTXO(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
+ * @returns the transaction spending the unrolled funds
+ */
+export async function prepareUnrollTransaction(wallet, vtxoTxIds, outputAddress) {
+    const chainTip = await wallet.onchainProvider.getChainTip();
+    let vtxos = await wallet.getVtxos({ withUnrolled: true });
+    vtxos = vtxos.filter((vtxo) => vtxoTxIds.includes(vtxo.txid));
+    if (vtxos.length === 0) {
+        throw new Error("No vtxos to complete unroll");
+    }
+    const inputs = [];
+    let totalAmount = 0n;
+    const txWeightEstimator = TxWeightEstimator.create();
+    for (const vtxo of vtxos) {
+        if (!vtxo.isUnrolled) {
+            throw new Error(`Vtxo ${vtxo.txid}:${vtxo.vout} is not fully unrolled, use unroll first`);
+        }
+        const txStatus = await wallet.onchainProvider.getTxStatus(vtxo.txid);
+        if (!txStatus.confirmed) {
+            throw new Error(`tx ${vtxo.txid} is not confirmed`);
+        }
+        const exit = availableExitPath({ height: txStatus.blockHeight, time: txStatus.blockTime }, chainTip, vtxo);
+        if (!exit) {
+            throw new Error(`no available exit path found for vtxo ${vtxo.txid}:${vtxo.vout}`);
+        }
+        const spendingLeaf = VtxoScript.decode(vtxo.tapTree).findLeaf(hex.encode(exit.script));
+        if (!spendingLeaf) {
+            throw new Error(`spending leaf not found for vtxo ${vtxo.txid}:${vtxo.vout}`);
+        }
+        totalAmount += BigInt(vtxo.value);
+        const sequence = timelockToSequence(exit.params.timelock);
+        inputs.push({
+            txid: vtxo.txid,
+            index: vtxo.vout,
+            tapLeafScript: [spendingLeaf],
+            sequence,
+            witnessUtxo: {
+                amount: BigInt(vtxo.value),
+                script: VtxoScript.decode(vtxo.tapTree).pkScript,
+            },
+            sighashType: SigHash.DEFAULT,
+        });
+        txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, TaprootControlBlock.encode(spendingLeaf[0]).length);
+    }
+    const tx = new Transaction({ version: 2 });
+    for (const input of inputs) {
+        tx.addInput(input);
+    }
+    txWeightEstimator.addOutputAddress(outputAddress, wallet.network);
+    let feeRate = await wallet.onchainProvider.getFeeRate();
+    if (!feeRate || feeRate < Wallet.MIN_FEE_RATE) {
+        feeRate = Wallet.MIN_FEE_RATE;
+    }
+    const feeAmount = txWeightEstimator.vsize().fee(BigInt(feeRate));
+    if (feeAmount > totalAmount) {
+        throw new Error("fee amount is greater than the total amount");
+    }
+    const sendAmount = totalAmount - feeAmount;
+    if (sendAmount < BigInt(DUST_AMOUNT)) {
+        throw new Error("send amount is less than dust amount");
+    }
+    tx.addOutputAddress(outputAddress, sendAmount, wallet.network);
+    const signedTx = await wallet.identity.sign(tx);
+    signedTx.finalize();
+    return signedTx;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function doUnroll(bumper, onchainProvider, tx) {
-    return async () => {
-        const [parent, child] = await bumper.bumpP2A(tx);
-        await onchainProvider.broadcastTransaction(parent, child);
-    };
+function doUnroll(onchainProvider, pkg) {
+    return () => onchainProvider.broadcastTransaction(...pkg).then(() => undefined);
 }
 function doWait(onchainProvider, txid) {
     return () => {

package/dist/esm/wallet/validation.js

@@ -136,8 +136,7 @@ function validateAssetGroupOutput(packet, outputIndex, assetId, expectedAmount)
     if (!assetOutput) {
         throw ErrAssetOutputNotFound(assetId, outputIndex);
     }
-    const expectedAmountBigInt = BigInt(expectedAmount);
-    if (assetOutput.amount !== expectedAmountBigInt) {
-        throw ErrInvalidAssetOutputAmount(assetOutput.amount, expectedAmountBigInt, assetId);
+    if (assetOutput.amount !== expectedAmount) {
+        throw ErrInvalidAssetOutputAmount(assetOutput.amount, expectedAmount, assetId);
     }
 }