@arkade-os/sdk 0.4.21 → 0.4.23

package/dist/esm/wallet/wallet.js

@@ -11,7 +11,7 @@ import { buildForfeitTx } from '../forfeit.js';
 import { validateConnectorsTxGraph, validateVtxoTxGraph, } from '../tree/validation.js';
 import { validateBatchRecipients } from './validation.js';
 import { isBatchSignable } from '../identity/index.js';
-import { isExpired, isRecoverable, isSpendable, isSubdust, TxType, } from './index.js';
+import { DEFAULT_ARKADE_SERVER_URL, isExpired, isRecoverable, isSpendable, isSubdust, TxType, } from './index.js';
 import { createAssetPacket, selectCoinsWithAsset, selectedCoinsToAssetInputs, } from './asset.js';
 import { VtxoScript } from '../script/base.js';
 import { CSVMultisigTapscript } from '../script/tapscript.js';
@@ -34,6 +34,7 @@ import { ContractManager } from '../contracts/contractManager.js';
 import { contractHandlers } from '../contracts/handlers/index.js';
 import { timelockToSequence } from '../contracts/handlers/helpers.js';
 import { clearSyncCursor, updateWalletState } from '../utils/syncCursors.js';
+export const getArkadeServerUrl = ({ arkServerUrl, }) => arkServerUrl || DEFAULT_ARKADE_SERVER_URL;
 // Historical unilateral exit delay for mainnet (~7 days in seconds).
 // Kept so existing wallets can still discover and spend VTXOs sent to the
 // legacy address after arkd starts advertising a different delay.
@@ -120,10 +121,7 @@ export class ReadonlyWallet {
         // Use provided arkProvider instance or create a new one from arkServerUrl
         const arkProvider = config.arkProvider ||
             (() => {
-                if (!config.arkServerUrl) {
-                    throw new Error("Either arkProvider or arkServerUrl must be provided");
-                }
-                return new RestArkProvider(config.arkServerUrl);
+                return new RestArkProvider(getArkadeServerUrl(config));
             })();
         // Extract arkServerUrl from provider if not explicitly provided
         const arkServerUrl = config.arkServerUrl || arkProvider.serverUrl;
@@ -302,7 +300,7 @@ export class ReadonlyWallet {
                 continue;
             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);
                 }
             }
@@ -1123,12 +1121,12 @@ export class Wallet extends ReadonlyWallet {
             for (const [, assets] of assetInputs) {
                 for (const asset of assets) {
                     const existing = allAssets.get(asset.assetId) ?? 0n;
-                    allAssets.set(asset.assetId, existing + BigInt(asset.amount));
+                    allAssets.set(asset.assetId, existing + asset.amount);
                 }
             }
             outputAssets = [];
             for (const [assetId, amount] of allAssets) {
-                outputAssets.push({ assetId, amount: Number(amount) });
+                outputAssets.push({ assetId, amount });
             }
         }
         const recipients = params.outputs.map((output, i) => ({
@@ -1563,7 +1561,7 @@ export class Wallet extends ReadonlyWallet {
      * const txid = await wallet.send({
      *     address: 'ark1q...',
      *     amount: 1000, // (optional, default to dust) btc amount to send to the output
-     *     assets: [{ assetId: 'abc123...', amount: 50 }] // (optional) list of assets to send
+     *     assets: [{ assetId: 'abc123...', amount: 50n }] // (optional) list of assets to send
      * });
      * ```
      */
@@ -1594,7 +1592,7 @@ export class Wallet extends ReadonlyWallet {
                 continue;
             }
             for (const receiverAsset of recipient.assets) {
-                let amountToSelect = BigInt(receiverAsset.amount);
+                let amountToSelect = receiverAsset.amount;
                 // check if existing change covers the needed amount
                 const existingChange = assetChanges.get(receiverAsset.assetId) ?? 0n;
                 if (existingChange >= amountToSelect) {
@@ -1621,7 +1619,7 @@ export class Wallet extends ReadonlyWallet {
                                 continue;
                             }
                             const existing = assetChanges.get(a.assetId) ?? 0n;
-                            assetChanges.set(a.assetId, existing + BigInt(a.amount));
+                            assetChanges.set(a.assetId, existing + a.amount);
                         }
                     }
                 }
@@ -1641,7 +1639,7 @@ export class Wallet extends ReadonlyWallet {
                 if (coin.assets) {
                     for (const asset of coin.assets) {
                         const existing = assetChanges.get(asset.assetId) ?? 0n;
-                        assetChanges.set(asset.assetId, existing + BigInt(asset.amount));
+                        assetChanges.set(asset.assetId, existing + asset.amount);
                     }
                 }
             }
@@ -1663,7 +1661,7 @@ export class Wallet extends ReadonlyWallet {
                 if (coin.assets) {
                     for (const asset of coin.assets) {
                         const existing = assetChanges.get(asset.assetId) ?? 0n;
-                        assetChanges.set(asset.assetId, existing + BigInt(asset.amount));
+                        assetChanges.set(asset.assetId, existing + asset.amount);
                     }
                 }
             }
@@ -1678,7 +1676,7 @@ export class Wallet extends ReadonlyWallet {
             const changeAssets = [];
             for (const [assetId, amount] of assetChanges) {
                 if (amount > 0n) {
-                    changeAssets.push({ assetId, amount: Number(amount) });
+                    changeAssets.push({ assetId, amount });
                 }
             }
             changeIndex = outputs.length;

package/dist/types/contracts/arkcontract.d.ts

@@ -88,7 +88,7 @@ export declare function contractFromArkContract(encoded: string, options?: {
  * @param options - Additional options
  * @returns A complete Contract object
  */
-export declare function contractFromArkContractWithAddress(encoded: string, serverPubKey: Uint8Array, addressPrefix: string, options?: {
+export declare function contractFromArkContractWithAddress(encoded: string, serverPubKey: Uint8Array, addressPrefix?: string, options?: {
     label?: string;
     state?: "active" | "inactive";
     metadata?: Record<string, unknown>;

package/dist/types/contracts/types.d.ts

@@ -1,6 +1,6 @@
 import { Bytes } from "@scure/btc-signer/utils.js";
-import { TapLeafScript, VtxoScript } from "../script/base";
-import { VirtualCoin, ExtendedVirtualCoin } from "../wallet";
+import { EncodedVtxoScript, TapLeafScript, VtxoScript } from "../script/base";
+import { VirtualCoin, TapLeaves } from "../wallet";
 import { ContractFilter } from "../repositories";
 /**
  * Contract state indicating whether it should be actively monitored.
@@ -66,10 +66,10 @@ export interface Contract {
 /**
  * A virtual output that has been associated with a specific contract.
  */
-export interface ContractVtxo extends ExtendedVirtualCoin {
-    /** The contract script this virtual output belongs to. */
+export type ContractVtxo = VirtualCoin & Partial<TapLeaves & EncodedVtxoScript> & {
+    extraWitness?: Bytes[];
     contractScript: string;
-}
+};
 /**
  * Result of path selection, including the tapleaf to use and any extra witness data.
  */

package/dist/types/identity/descriptor.d.ts

@@ -1,3 +1,29 @@
+/**
+ * True iff `descriptor` is a Bitcoin mainnet descriptor (xpub-prefixed
+ * BIP32 key).
+ *
+ * Note: testnet, signet, regtest, mutinynet, and other non-mainnet
+ * networks all share the same `tpub` BIP32 version bytes — they cannot
+ * be distinguished from one another at the descriptor level. Callers
+ * that need a `Network` constants object for `expand()` pick
+ * `networks.bitcoin` vs `networks.testnet` themselves; callers that
+ * need the *actual* network the wallet is on must track that
+ * out-of-band.
+ */
+export declare function isMainnetDescriptor(descriptor: string): boolean;
+/**
+ * Shared "does `candidate` belong to the identity backed by
+ * `ourDescriptor`?" predicate.
+ *
+ * - HD descriptors (expanding to a `bip32` key) match by account xpub
+ *   on both sides — index-agnostic, so a wildcard template and any
+ *   concrete index under it all collapse to the same xpub.
+ * - Bare `tr(pubkey)` candidates fall back to comparing the candidate
+ *   pubkey against `ourXOnlyPubkey` (the cached pubkey on the identity
+ *   side, since pulling it from `ourDescriptor` would require an index
+ *   substitution the caller already performed).
+ */
+export declare function descriptorIsOurs(candidate: string, ourDescriptor: string, ourXOnlyPubkey: Uint8Array): boolean;
 /**
  * Check if a string is a descriptor of the shape `tr(...)`.
  *

package/dist/types/identity/descriptorProvider.d.ts

@@ -13,12 +13,19 @@ export interface DescriptorSigningRequest {
  *
  * Implementations include:
  * - {@link StaticDescriptorProvider}: wraps a legacy {@link Identity} with a single key.
- * - HD-wallet provider: signs with keys derived from an xpub-based descriptor
- *   (planned — tracked separately from this interface).
+ * - {@link HDDescriptorProvider}: rotates through HD-derived descriptors.
+ *
+ * The provider has no read accessor for "current" — it is a pure descriptor
+ * allocator. "What addresses am I currently bound to?" is a question the
+ * contract repository answers, not the provider.
  */
 export interface DescriptorProvider {
-    /** Returns the current signing descriptor. */
-    getSigningDescriptor(): string;
+    /**
+     * Allocate a new signing descriptor. For HD providers each call advances
+     * the internal index and returns a fresh descriptor; for single-key
+     * providers each call returns the same descriptor.
+     */
+    getNextSigningDescriptor(): Promise<string>;
     /** Checks if a descriptor belongs to this provider. */
     isOurs(descriptor: string): boolean;
     /** Signs transactions, each with its own descriptor-derived key. */

package/dist/types/identity/hdCapableIdentity.d.ts

@@ -0,0 +1,44 @@
+import { Identity, ReadonlyIdentity } from ".";
+import { DescriptorSigningRequest } from "./descriptorProvider";
+import { Transaction } from "../utils/transaction";
+/**
+ * Read-side HD capability marker. Exposes the wildcard-suffixed account
+ * descriptor *template* and the descriptor-membership predicate, but no
+ * signing primitives — suitable for watch-only identities backed by an
+ * xpub.
+ *
+ * Extracted from {@link HDCapableIdentity} so that
+ * `ReadonlyDescriptorIdentity` can stand in for an HD wallet's read-only
+ * surface (template-aware, derives pubkeys at any index) without having
+ * to claim signing capability it cannot honour.
+ */
+export interface ReadonlyHDCapableIdentity extends ReadonlyIdentity {
+    /**
+     * The wildcard-suffixed account descriptor template
+     * (e.g. `tr([fp/86'/0'/0']xpub/0/*)`). Consumers materialize a
+     * concrete descriptor by replacing the `*` with a derivation index.
+     */
+    readonly descriptor: string;
+    /** True iff `descriptor` derives from this identity's xpub/seed. */
+    isOurs(descriptor: string): boolean;
+}
+/**
+ * Capability marker for identities that can be rotated through an HD
+ * derivation tree AND can sign at each rotated index.
+ *
+ * Deliberately does NOT extend `DescriptorProvider`: if an HD-capable
+ * identity were silently usable as a concrete descriptor source, callers
+ * could bypass receive rotation and unknowingly reuse a single address
+ * forever. To use this identity as a wallet's descriptor source, wrap
+ * it explicitly:
+ *
+ *  - `HDDescriptorProvider` — rotating, recommended for new wallets.
+ *  - `StaticDescriptorProvider` — pinned to a single key, for legacy or
+ *    explicitly-non-rotating use cases.
+ */
+export interface HDCapableIdentity extends ReadonlyHDCapableIdentity, Identity {
+    /** Signs each request with the key derived from its descriptor. */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /** Signs a message using the key derived from `descriptor`. */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+}

package/dist/types/identity/index.d.ts

@@ -52,4 +52,5 @@ export * from "./serialize";
 export { isDescriptor, normalizeToDescriptor, extractPubKey, parseHDDescriptor, } from "./descriptor";
 export type { ParsedHDDescriptor } from "./descriptor";
 export type { DescriptorProvider, DescriptorSigningRequest, } from "./descriptorProvider";
+export type { HDCapableIdentity, ReadonlyHDCapableIdentity, } from "./hdCapableIdentity";
 export { StaticDescriptorProvider } from "./staticDescriptorProvider";

package/dist/types/identity/seedIdentity.d.ts

@@ -1,7 +1,8 @@
-import { Identity, ReadonlyIdentity } from ".";
 import { Transaction } from "../utils/transaction";
 import { SignerSession } from "../tree/signingSession";
 import type { SerializedSigningIdentity, SerializedReadonlyIdentity } from "./serialize";
+import { DescriptorSigningRequest } from "./descriptorProvider";
+import { HDCapableIdentity, ReadonlyHDCapableIdentity } from "./hdCapableIdentity";
 /** Used for default BIP86 derivation with network selection. */
 export interface NetworkOptions {
     /**
@@ -11,12 +12,16 @@ export interface NetworkOptions {
      */
     isMainnet?: boolean;
 }
-/** Used for custom output descriptor derivation. */
+/** Used for a caller-supplied account-descriptor template. */
 export interface DescriptorOptions {
-    /** Custom output descriptor that determines the derivation path. */
+    /**
+     * Account-descriptor *template* — must end with the BIP-32 wildcard
+     * suffix `/*)`. Stored as-is on {@link SeedIdentity.descriptor} and
+     * read by HD providers to rotate through derivation indices.
+     */
     descriptor: string;
 }
-/** Either default BIP86 derivation (with optional network selection) or a custom descriptor. */
+/** Either default BIP86 derivation (with optional network selection) or a caller-supplied template. */
 export type SeedIdentityOptions = NetworkOptions | DescriptorOptions;
 /** Used for deriving an identity from a BIP39 mnemonic. */
 export type MnemonicOptions = SeedIdentityOptions & {
@@ -24,44 +29,77 @@ export type MnemonicOptions = SeedIdentityOptions & {
     passphrase?: string;
 };
 /**
- * Seed-based identity derived from a raw seed and an output descriptor.
+ * Seed-based identity derived from a raw seed and an account descriptor
+ * *template*.
  *
  * This is the recommended identity type for most applications. It uses
- * standard BIP86 (Taproot) derivation by default and stores an output
- * descriptor for interoperability with other wallets.
+ * standard BIP86 (Taproot) derivation by default; callers that need a
+ * different path supply the wildcard template directly.
  *
  * Prefer this (or @see MnemonicIdentity) over `SingleKey` for new
  * integrations — `SingleKey` exists for backward compatibility with
  * raw nsec-style keys.
  *
- * For descriptor-based signing, wrap with {@link StaticDescriptorProvider}.
+ * The identity holds the wildcard *template* (e.g.
+ * `tr([fp/86'/0'/0']xpub/0/*)`) on its public {@link descriptor}
+ * field. HD rotation reads it directly; consumers that need a
+ * concrete descriptor at a specific index materialize it themselves
+ * (see `HDDescriptorProvider` in the wallet layer).
+ *
+ * Exposes seed-level primitives (signing, derivation, the template)
+ * but is deliberately NOT a `DescriptorProvider`. Wrap it explicitly
+ * to get one:
+ *  - `HDDescriptorProvider` for rotating receive addresses.
+ *  - {@link StaticDescriptorProvider} for legacy, single-key behaviour.
+ *
+ * The split prevents a SeedIdentity from being silently used as a
+ * concrete descriptor source, which would defeat HD rotation without
+ * any compile-time signal that something was wrong.
  *
  * @example
  * ```typescript
  * const seed = mnemonicToSeedSync(mnemonic);
  *
- * // Testnet (BIP86 path m/86'/1'/0'/0/0)
+ * // Testnet (BIP86 wildcard descriptor m/86'/1'/0'/0/*)
  * const identity = SeedIdentity.fromSeed(seed, { isMainnet: false });
  *
- * // Mainnet (BIP86 path m/86'/0'/0'/0/0)
+ * // Mainnet (BIP86 wildcard descriptor m/86'/0'/0'/0/*)
  * const identity = SeedIdentity.fromSeed(seed, { isMainnet: true });
  *
- * // Custom descriptor
+ * // Caller-supplied wildcard descriptor (must end in `/*)`).
  * const identity = SeedIdentity.fromSeed(seed, { descriptor });
  * ```
  */
-export declare class SeedIdentity implements Identity {
+export declare class SeedIdentity implements HDCapableIdentity {
     private readonly derivedKey;
+    /**
+     * Wildcard account-descriptor template (e.g.
+     * `tr([fp/86'/0'/0']xpub/0/*)`). The canonical thing to pass
+     * through the system; consumers materialize a concrete descriptor
+     * at a specific index themselves (see `HDDescriptorProvider` in
+     * the wallet layer for the rotating-counter use case).
+     */
     readonly descriptor: string;
-    constructor(seed: Uint8Array, descriptor: string);
+    /**
+     * Constructs a SeedIdentity from a 64-byte seed and either a
+     * caller-supplied wildcard descriptor (`{ descriptor }`) or the
+     * default BIP86 path at the requested network (`{ isMainnet }`).
+     * Prefer the {@link fromSeed} factory for symmetry with
+     * {@link MnemonicIdentity.fromMnemonic}.
+     *
+     * Throws on a non-wildcard descriptor, an xpub mismatch with the
+     * seed, or a missing derivation path.
+     */
+    constructor(seed: Uint8Array, opts?: SeedIdentityOptions);
     /**
      * Creates a SeedIdentity from a raw 64-byte seed.
      *
      * Pass `{ isMainnet }` for default BIP86 derivation, or
-     * `{ descriptor }` for a custom derivation path.
+     * `{ descriptor }` for a caller-supplied account-descriptor
+     * template (the option's value must end with `/*)`).
      *
      * @param seed - 64-byte seed (typically from mnemonicToSeedSync)
-     * @param opts - Network selection or custom descriptor.
+     * @param opts - Network selection or descriptor template.
      */
     static fromSeed(seed: Uint8Array, opts?: SeedIdentityOptions): SeedIdentity;
     xOnlyPublicKey(): Promise<Uint8Array>;
@@ -70,9 +108,29 @@ export declare class SeedIdentity implements Identity {
     signMessage(message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
     signerSession(): SignerSession;
     /**
-     * Converts to a watch-only identity that cannot sign.
+     * Converts to a watch-only identity that cannot sign. Carries the
+     * template forward, so the readonly side stays HD-capable (can
+     * derive descriptors at any index without seed access).
      */
     toReadonly(): Promise<ReadonlyDescriptorIdentity>;
+    /**
+     * Returns true when `descriptor` is derived from this identity's seed.
+     * HD descriptors match by account xpub; bare `tr(pubkey)` descriptors
+     * match by raw pubkey. See {@link descriptorIsOurs}.
+     */
+    isOurs(descriptor: string): boolean;
+    /**
+     * Signs each request with the key derived from its descriptor.
+     * Each descriptor must share this identity's seed ({@link isOurs}).
+     */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /**
+     * Signs a message with the key derived from `descriptor`.
+     */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    private derivePrivateKeyForDescriptor;
+    private signTxWithKey;
+    private signMessageWithKey;
 }
 /**
  * Mnemonic-based identity derived from a BIP39 phrase.
@@ -96,40 +154,66 @@ export declare class MnemonicIdentity extends SeedIdentity {
      * Creates a MnemonicIdentity from a BIP39 mnemonic phrase.
      *
      * Pass `{ isMainnet }` for default BIP86 derivation, or
-     * `{ descriptor }` for a custom derivation path.
+     * `{ descriptor }` for a caller-supplied account-descriptor
+     * template (the option's value must end with `/*)`).
      *
      * @param phrase - BIP39 mnemonic phrase (12 or 24 words)
-     * @param opts - Network selection or custom descriptor, plus optional passphrase
+     * @param opts - Network selection or descriptor template, plus optional passphrase
      */
     static fromMnemonic(phrase: string, opts?: MnemonicOptions): MnemonicIdentity;
 }
 /**
- * Watch-only identity from an output descriptor.
+ * Watch-only HD identity from a descriptor *template*.
  *
  * Can derive public keys but cannot sign transactions. Use this for
- * watch-only wallets or when sharing identity information without
- * exposing private keys.
+ * watch-only wallets — given just an xpub-based template, the readonly
+ * side still rotates through HD indices.
+ *
+ * Constructed from a wildcard template (e.g.
+ * `tr([fp/86'/0'/0']xpub.../0/*)`); the {@link descriptor} field
+ * holds it for HD providers to consume.
  *
  * @example
  * ```typescript
- * const descriptor = "tr([fingerprint/86'/0'/0']xpub.../0/0)";
- * const readonly = ReadonlyDescriptorIdentity.fromDescriptor(descriptor);
- * const pubKey = await readonly.xOnlyPublicKey();
+ * const ro = ReadonlyDescriptorIdentity.fromDescriptor(
+ *   "tr([fp/86'/0'/0']xpub.../0/*)"
+ * );
+ * ro.descriptor;
+ * // => "tr([fp/86'/0'/0']xpub.../0/*)" — the template
  * ```
  */
-export declare class ReadonlyDescriptorIdentity implements ReadonlyIdentity {
+export declare class ReadonlyDescriptorIdentity implements ReadonlyHDCapableIdentity {
+    /**
+     * Index-0 expansion of {@link descriptor}. Both the x-only pubkey
+     * (taproot, returned by the library as 32 bytes) and the compressed
+     * pubkey (derived through the bip32 node when needed) are read off
+     * this on demand — no separate caches.
+     */
+    private readonly indexZero;
+    /**
+     * Wildcard account-descriptor template (e.g.
+     * `tr([fp/86'/0'/0']xpub/0/*)`). HD rotation consumers materialize
+     * a concrete descriptor at a specific index themselves.
+     */
     readonly descriptor: string;
-    private readonly xOnlyPubKey;
-    private readonly compressedPubKey;
     private constructor();
     /**
-     * Creates a ReadonlyDescriptorIdentity from an output descriptor.
+     * Creates a ReadonlyDescriptorIdentity from an account-descriptor
+     * *template* (must end with the BIP-32 wildcard suffix `/*)`).
      *
-     * @param descriptor - Taproot descriptor: tr([fingerprint/path']xpub.../child/path)
+     * @param descriptor - Wildcard-suffixed Taproot template
+     *   (`tr([fp/path']xpub.../child/*)`).
      */
     static fromDescriptor(descriptor: string): ReadonlyDescriptorIdentity;
     xOnlyPublicKey(): Promise<Uint8Array>;
     compressedPublicKey(): Promise<Uint8Array>;
+    /**
+     * Returns true when `descriptor` derives from this identity's xpub.
+     * HD descriptors match by account xpub; bare `tr(pubkey)` descriptors
+     * fall back to comparing against the index-0 x-only pubkey. See
+     * {@link descriptorIsOurs}.
+     */
+    isOurs(descriptor: string): boolean;
 }
 /**
  * Serialize a seed-backed signing identity into a

package/dist/types/identity/serialize.d.ts

@@ -4,6 +4,11 @@ import type { Identity, ReadonlyIdentity } from ".";
  * service-worker boundary. All variants are structured-clone safe
  * (plain strings only — no functions or prototypes).
  *
+ * `descriptor` carries the wildcard *template* (e.g.
+ * `tr([fp/86'/0'/0']xpub.../0/*)`), not a concrete index — the
+ * receiving factories require a template, and storing it directly
+ * means nothing here has to convert concrete → template on rehydrate.
+ *
  * Adding a new variant is a source change in every worker build; keep
  * old variants around until all deployed workers handle them.
  */
@@ -23,6 +28,8 @@ export type SerializedSigningIdentity = {
 /**
  * Tagged envelope for a readonly identity transported across the
  * service-worker boundary. All variants are structured-clone safe.
+ * `descriptor` is the wildcard template (see
+ * {@link SerializedSigningIdentity}).
  */
 export type SerializedReadonlyIdentity = {
     type: "readonly-single-key";
@@ -57,6 +64,11 @@ export declare function serializeReadonlyIdentity(identity: ReadonlyIdentity): P
  * The return type is the union of signing and readonly; use
  * {@link isSigningSerialized} on the envelope before hydration if the caller
  * needs to know which side it ends up on.
+ *
+ * Envelopes store the wildcard template directly (see
+ * `serializeSeedOwnedSigningIdentity` / `serializeSeedOwnedReadonlyIdentity`),
+ * so the `descriptor` field is passed straight through to the
+ * template-only factories.
  */
 export declare function hydrateIdentity(s: SerializedIdentity): Identity | ReadonlyIdentity;
 /**

package/dist/types/identity/staticDescriptorProvider.d.ts

@@ -11,7 +11,7 @@ export declare class StaticDescriptorProvider implements DescriptorProvider {
     private readonly pubKeyHex;
     constructor(identity: Identity, pubKeyHex: string);
     static create(identity: Identity): Promise<StaticDescriptorProvider>;
-    getSigningDescriptor(): string;
+    getNextSigningDescriptor(): Promise<string>;
     isOurs(descriptor: string): boolean;
     signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
     signMessageWithDescriptor(descriptor: string, message: Uint8Array, type?: "schnorr" | "ecdsa"): Promise<Uint8Array>;

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@ import { Wallet, ReadonlyWallet, waitForIncomingFunds, IncomingFunds } from "./w
 import { TxTree, TxTreeNode } from "./tree/txTree";
 import { SignerSession, TreeNonces, TreePartialSigs } from "./tree/signingSession";
 import { Ramps } from "./wallet/ramps";
+import { HDDescriptorProvider } from "./wallet/hdDescriptorProvider";
 import { isVtxoExpiringSoon, VtxoManager } from "./wallet/vtxo-manager";
 import type { IVtxoManager, SettlementConfig } from "./wallet/vtxo-manager";
 import { ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEOUTS } from "./wallet/serviceWorker/wallet";
@@ -22,7 +23,7 @@ import type { MessageTimeouts } from "./wallet/serviceWorker/wallet";
 import { OnchainWallet } from "./wallet/onchain";
 import { setupServiceWorker } from "./worker/browser/utils";
 import { ESPLORA_URL, EsploraProvider, OnchainProvider, ExplorerTransaction } from "./providers/onchain";
-import { ElectrumOnchainProvider, WsElectrumChainSource } from "./providers/electrum";
+import { ELECTRUM_TCP_HOST, ELECTRUM_WS_URL, ElectrumOnchainProvider, WsElectrumChainSource } from "./providers/electrum";
 import type { TransactionHistory as ElectrumTransactionHistory, BlockHeader as ElectrumBlockHeader, Unspent as ElectrumUnspent } from "./providers/electrum";
 import { RestArkProvider, ArkProvider, SettlementEvent, SettlementEventType, ArkInfo, SignedIntent, Output, TxNotification, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, FeeInfo } from "./providers/ark";
 import { DelegatorProvider, DelegateInfo, DelegateOptions, RestDelegatorProvider } from "./providers/delegator";
@@ -37,6 +38,7 @@ import { RestIndexerProvider, IndexerProvider, IndexerTxType, ChainTxType, PageR
 import { Nonces } from "./musig2/nonces";
 import { PartialSig } from "./musig2/sign";
 import { AnchorBumper, P2A } from "./utils/anchor";
+import { TxWeightEstimator, type VSize } from "./utils/txSizeEstimator";
 import { Unroll } from "./wallet/unroll";
 import { ArkError, maybeArkError } from "./providers/errors";
 import { validateVtxoTxGraph, validateConnectorsTxGraph } from "./tree/validation";
@@ -49,8 +51,9 @@ export * as asset from "./extension/asset";
 import { ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract } from "./contracts";
 import type { Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams } from "./contracts";
 import { IContractManager } from "./contracts/contractManager";
+import { timelockToSequence, sequenceToTimelock } from "./contracts/handlers/helpers";
 import { closeDatabase, openDatabase } from "./repositories/indexedDB/manager";
 import { WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError } from "./wallet/serviceWorker/wallet-message-handler";
 import { MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError } from "./worker/errors";
-export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, isBatchSignable, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, ElectrumOnchainProvider, WsElectrumChainSource, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEOUTS, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
-export type { Identity, ReadonlyIdentity, BatchSignableIdentity, SignRequest, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, ElectrumTransactionHistory, ElectrumBlockHeader, ElectrumUnspent, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, SettlementConfig, IVtxoManager, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, MessageTimeouts, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };
+export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, isBatchSignable, OnchainWallet, Ramps, VtxoManager, HDDescriptorProvider, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, ELECTRUM_WS_URL, ELECTRUM_TCP_HOST, ElectrumOnchainProvider, WsElectrumChainSource, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEOUTS, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, TxWeightEstimator, timelockToSequence, sequenceToTimelock, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
+export type { Identity, ReadonlyIdentity, BatchSignableIdentity, SignRequest, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, ElectrumTransactionHistory, ElectrumBlockHeader, ElectrumUnspent, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, SettlementConfig, IVtxoManager, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, VSize, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, MessageTimeouts, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };