@arkade-os/sdk 0.4.22 → 0.4.24

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 "./utils/timelock";
 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, };

package/dist/types/providers/electrum.d.ts

@@ -1,7 +1,39 @@
 import type { ElectrumWS } from "ws-electrumx-client";
-import type { Network } from "../networks";
+import type { Network, NetworkName } from "../networks";
 import type { Coin } from "../wallet";
 import type { ExplorerTransaction, OnchainProvider } from "./onchain";
+/**
+ * Default WebSocket Electrum endpoints. Mainnet, mutinynet, and signet
+ * point at Ark Labs–operated Fulcrum 2.1 deployments (which support
+ * `blockchain.transaction.broadcast_package` for atomic 1P1C TRUC
+ * relay; see `ElectrumOnchainProvider.broadcastTransaction`). Testnet
+ * defaults to Blockstream's public Fulcrum because Ark doesn't host
+ * it. Regtest assumes the `electrum-ws` websocat bridge from
+ * `vulpemventures/nigiri`.
+ *
+ * @example
+ * ```typescript
+ * import { ElectrumWS } from "ws-electrumx-client";
+ * import { ELECTRUM_WS_URL, ElectrumOnchainProvider, networks } from "@arkade-os/sdk";
+ *
+ * const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin);
+ * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
+ * ```
+ */
+export declare const ELECTRUM_WS_URL: Record<NetworkName, string>;
+/**
+ * Hostnames for Electrum endpoints reachable over raw TCP. Provided as
+ * a reference for Node-side consumers — the SDK's
+ * {@link ElectrumOnchainProvider} only speaks WebSocket because it has
+ * to run in browsers, so this map is informational only and not
+ * consumed by any built-in provider.
+ *
+ * Public Ark Labs Fulcrum instances expose:
+ *   - port 50001 — plain TCP (Electrum protocol)
+ *   - port 50002 — TCP + TLS (Electrum protocol)
+ *   - port 50003 — WebSocket (Electrum-over-WS, see {@link ELECTRUM_WS_URL})
+ */
+export declare const ELECTRUM_TCP_HOST: Record<NetworkName, string | null>;
 export type TransactionHistory = {
     tx_hash: string;
     height: number;
@@ -70,12 +102,46 @@ export declare class WsElectrumChainSource {
     private cachedTip;
     private headersSubscribePromise;
     constructor(ws: ElectrumWS, network: Network);
+    /**
+     * Send N requests in parallel and aggregate the results, replacement
+     * for `ws.batchRequest`. The library's batchRequest is implemented as
+     * `Promise.all` over individual request promises — when one element
+     * rejects, the others remain pending. When their (often error)
+     * responses arrive later, the library rejects them too, and nobody is
+     * awaiting them: the rejections become unhandled and crash the test
+     * runner / pollute production logs.
+     *
+     * `safeBatchRequest` issues each request through `ws.request` (so each
+     * has its own request-promise lifecycle), waits for all of them via
+     * `Promise.allSettled` (every promise gets an explicit handler), and
+     * then surfaces the first error if any failed. Same wall-clock cost
+     * as the library's batch (parallel send), no orphan rejections.
+     *
+     * Use this in place of `ws.batchRequest` for any call where one or
+     * more elements may legitimately error (e.g. electrs index lag
+     * surfacing as `missingheight` for a subset of heights/txids).
+     */
+    safeBatchRequest<T>(requests: {
+        method: string;
+        params: unknown[];
+    }[]): Promise<T[]>;
     fetchTransactions(txids: string[]): Promise<{
         txID: string;
         hex: string;
     }[]>;
     fetchVerboseTransaction(txid: string): Promise<VerboseTransaction>;
     fetchVerboseTransactions(txids: string[]): Promise<VerboseTransaction[]>;
+    /**
+     * Look up the block height of a confirmed transaction without relying
+     * on the verbose-tx endpoint. `blockchain.transaction.get_merkle` is
+     * part of the standard SPV protocol and is supported by both Fulcrum
+     * and electrs (whereas `blockchain.transaction.get` with verbose=true
+     * is Fulcrum-only). Returns `null` when the tx is in the mempool —
+     * electrs in that case rejects with a "not yet in a block" error.
+     */
+    fetchTxMerkle(txid: string): Promise<{
+        blockHeight: number;
+    } | null>;
     unsubscribeScriptStatus(script: Uint8Array): Promise<void>;
     subscribeScriptStatus(script: Uint8Array, callback: (scripthash: string, status: string | null) => void): Promise<void>;
     fetchHistories(scripts: Uint8Array[]): Promise<TransactionHistory[][]>;
@@ -130,19 +196,45 @@ export declare class WsElectrumChainSource {
     addressForScript(scriptHex: string): string | undefined;
 }
 /**
- * Electrum-based implementation of the OnchainProvider interface.
- * Replaces esplora polling with electrum subscriptions where possible.
+ * Electrum-based implementation of the {@link OnchainProvider} interface.
  *
- * @example
+ * Built around the subset of the Electrum protocol that both **Fulcrum**
+ * and **electrs** support — listunspent, get_history, transaction.get
+ * (non-verbose), transaction.get_merkle, block.header,
+ * headers.subscribe, scripthash.subscribe, estimatefee, relayfee, and
+ * broadcast. The verbose form of `transaction.get` is **not** used (it's
+ * Fulcrum-only and rejected by electrs); confirmation status is derived
+ * from `transaction.get_merkle` plus parsed block headers.
+ *
+ * Output amounts are derived from parsed raw transaction bytes (exact
+ * bigints), never the floating-point `value` fields some servers return.
+ *
+ * Atomic 1P1C package broadcast (TRUC / BIP 431) is supported via
+ * Fulcrum's `blockchain.transaction.broadcast_package`. There is **no
+ * fallback** to sequential parent-then-child broadcasts — TRUC packages
+ * with a zero-fee parent would silently fail, so the call surfaces an
+ * error against servers that don't support the method.
+ *
+ * @example Default URL via {@link ELECTRUM_WS_URL}
  * ```typescript
  * import { ElectrumWS } from "ws-electrumx-client";
- * import { ElectrumOnchainProvider } from "./providers/electrum";
- * import { networks } from "./networks";
+ * import {
+ *   ElectrumOnchainProvider,
+ *   ELECTRUM_WS_URL,
+ *   networks,
+ * } from "@arkade-os/sdk";
  *
- * const ws = new ElectrumWS("wss://electrum.blockstream.info:50004");
+ * const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin);
  * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
  *
  * const coins = await provider.getCoins("bc1q...");
+ * await provider.close();
+ * ```
+ *
+ * @example Custom server
+ * ```typescript
+ * const ws = new ElectrumWS("wss://my-fulcrum.example:50004");
+ * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
  * ```
  */
 export declare class ElectrumOnchainProvider implements OnchainProvider {
@@ -178,15 +270,23 @@ export declare class ElectrumOnchainProvider implements OnchainProvider {
     }[]>;
     getTransactions(address: string): Promise<ExplorerTransaction[]>;
     /**
-     * Map an electrum verbose transaction to the ExplorerTransaction shape.
-     *
-     * Output values are derived from the raw transaction hex when available,
-     * never from the floating-point `value` field returned by the daemon.
-     * That field has 8 decimal places and `Math.round(value * 1e8)` is safe
-     * in the common case but a footgun for protocol-level money handling —
-     * the raw bytes are exact.
+     * Resolve a list of `{tx_hash, height}` entries (as returned by the
+     * scripthash history endpoint) into ExplorerTransaction shape **without
+     * using the verbose-tx endpoint**, which only Fulcrum implements. We
+     * reconstruct everything the verbose response would have given us:
+     *   - vouts ← parse the raw tx (exact sat amounts, no float precision risk)
+     *   - block_time ← batch-fetch the block headers for the heights present
+     *   - addresses ← decode each output's scriptPubKey via @scure/btc-signer
+     */
+    private historyToExplorerTxs;
+    /**
+     * Build an ExplorerTransaction from a history entry plus the raw tx hex
+     * (when known) and a height→block_time map. Parse errors propagate —
+     * silently returning an empty vout would hide real outputs (e.g. a
+     * deposit) and is far worse for protocol-level money handling than
+     * failing the whole batch.
      */
-    private verboseToExplorer;
+    private buildExplorerTx;
     /**
      * Decode `address` into its scriptPubKey, throwing a clear error if the
      * input is malformed. @scure/btc-signer raises a generic decode error

package/dist/types/providers/onchain.d.ts

@@ -2,6 +2,12 @@ import type { NetworkName } from "../networks";
 import { Coin } from "../wallet";
 /**
  * The default base URLs for esplora API providers.
+ *
+ * Mainnet, mutinynet, and signet point at Ark Labs–operated
+ * mempool deployments (mempool.space-compatible esplora API).
+ * Testnet falls back to the public mempool.space deployment
+ * because Ark doesn't host it. Regtest assumes a local nigiri
+ * stack on the standard port.
  */
 export declare const ESPLORA_URL: Record<NetworkName, string>;
 export type ExplorerTransaction = {

package/dist/types/repositories/serialization.d.ts

@@ -1,17 +1,33 @@
 import { TapLeafScript } from "../script/base";
-import { ExtendedCoin, ExtendedVirtualCoin } from "../wallet";
+import { ArkTransaction, Asset, ExtendedCoin, ExtendedVirtualCoin } from "../wallet";
 export type SerializedTapLeaf = {
     cb: string;
     s: string;
 };
 export type SerializedVtxo = ReturnType<typeof serializeVtxo>;
 export type SerializedUtxo = ReturnType<typeof serializeUtxo>;
+export type SerializedTransaction = ReturnType<typeof serializeTransaction>;
+export type SerializedAsset = {
+    assetId: string;
+    amount: string;
+};
 export declare const serializeTapLeaf: ([cb, s,]: TapLeafScript) => SerializedTapLeaf;
+export declare const serializeAsset: (a: Asset) => SerializedAsset;
+export declare const deserializeAsset: (a: {
+    assetId: string;
+    amount: string | number | bigint;
+}) => Asset;
+export declare const serializeAssets: (assets: Asset[] | undefined) => SerializedAsset[] | undefined;
+export declare const deserializeAssets: (assets: Array<{
+    assetId: string;
+    amount: string | number | bigint;
+}> | undefined) => Asset[] | undefined;
 export declare const serializeVtxo: (v: ExtendedVirtualCoin) => {
     tapTree: string;
     forfeitTapLeafScript: SerializedTapLeaf;
     intentTapLeafScript: SerializedTapLeaf;
     extraWitness: string[] | undefined;
+    assets: SerializedAsset[] | undefined;
     virtualStatus: import("../wallet").VirtualStatus;
     spentBy?: string;
     settledBy?: string;
@@ -19,7 +35,6 @@ export declare const serializeVtxo: (v: ExtendedVirtualCoin) => {
     createdAt: Date;
     isUnrolled: boolean;
     isSpent?: boolean;
-    assets?: import("../wallet").Asset[];
     script: string;
     value: number;
     status: import("../wallet").Status;
@@ -36,6 +51,15 @@ export declare const serializeUtxo: (u: ExtendedCoin) => {
     txid: string;
     vout: number;
 };
+export declare const serializeTransaction: (t: ArkTransaction) => {
+    assets: SerializedAsset[] | undefined;
+    key: import("../wallet").TxKey;
+    type: import("../wallet").TxType;
+    amount: number;
+    settled: boolean;
+    createdAt: number;
+};
 export declare const deserializeTapLeaf: (t: SerializedTapLeaf) => TapLeafScript;
 export declare const deserializeVtxo: (o: SerializedVtxo) => ExtendedVirtualCoin;
 export declare const deserializeUtxo: (o: SerializedUtxo) => ExtendedCoin;
+export declare const deserializeTransaction: (o: SerializedTransaction) => ArkTransaction;

package/dist/types/script/address.d.ts

@@ -43,7 +43,7 @@ export declare class ArkAddress {
      * @defaultValue `version = 0`
      * @throws Error if either public key is not 32 bytes long
      */
-    constructor(serverPubKey: Bytes, vtxoTaprootKey: Bytes, hrp: string, version?: number);
+    constructor(serverPubKey: Bytes, vtxoTaprootKey: Bytes, hrp?: string, version?: number);
     /**
      * Decode an Arkade address from its bech32m string form.
      *

package/dist/types/script/tapscript.d.ts

@@ -90,6 +90,7 @@ export declare namespace CSVMultisigTapscript {
     function decode(script: Uint8Array): Type;
     /** Return true when the tapscript is a CSV multisig tapscript. */
     function is(tapscript: ArkTapscript<any, any>): tapscript is Type;
+    function isScriptValid(script: Uint8Array): true | Error;
 }
 /**
  * Combines a condition script with an exit closure. The resulting script requires
@@ -114,6 +115,7 @@ export declare namespace ConditionCSVMultisigTapscript {
     function decode(script: Uint8Array): Type;
     /** Return true when the tapscript is a condition + CSV multisig tapscript. */
     function is(tapscript: ArkTapscript<any, any>): tapscript is Type;
+    function isScriptValid(script: Uint8Array): true | Error;
 }
 /**
  * Combines a condition script with a forfeit closure. The resulting script requires
@@ -138,6 +140,7 @@ export declare namespace ConditionMultisigTapscript {
     function decode(script: Uint8Array): Type;
     /** Return true when the tapscript is a condition + multisig tapscript. */
     function is(tapscript: ArkTapscript<any, any>): tapscript is Type;
+    function isScriptValid(script: Uint8Array): true | Error;
 }
 /**
  * Implements an absolute timelock (CLTV) script combined with a forfeit closure.
@@ -162,4 +165,5 @@ export declare namespace CLTVMultisigTapscript {
     function decode(script: Uint8Array): Type;
     /** Return true when the tapscript is a CLTV multisig tapscript. */
     function is(tapscript: ArkTapscript<any, any>): tapscript is Type;
+    function isScriptValid(script: Uint8Array): true | Error;
 }

package/dist/types/utils/timelock.d.ts

@@ -0,0 +1,9 @@
+import type { RelativeTimelock } from "../script/tapscript";
+/**
+ * Convert RelativeTimelock to BIP68 sequence number.
+ */
+export declare function timelockToSequence(timelock: RelativeTimelock): number;
+/**
+ * Convert BIP68 sequence number back to RelativeTimelock.
+ */
+export declare function sequenceToTimelock(sequence: number): RelativeTimelock;

package/dist/types/wallet/hdDescriptorProvider.d.ts

@@ -0,0 +1,93 @@
+import { DescriptorProvider, DescriptorSigningRequest } from "../identity/descriptorProvider";
+import { HDCapableIdentity } from "../identity/hdCapableIdentity";
+import { WalletRepository } from "../repositories/walletRepository";
+import { Transaction } from "../utils/transaction";
+/**
+ * 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 declare class HDDescriptorProvider implements DescriptorProvider {
+    private readonly identity;
+    private readonly walletRepository;
+    private constructor();
+    /**
+     * 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 create(identity: HDCapableIdentity, walletRepository: WalletRepository): Promise<HDDescriptorProvider>;
+    /**
+     * 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.
+     */
+    getNextSigningDescriptor(): Promise<string>;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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.
+     */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /** Signs a message using the key derived from `descriptor`. */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    private materializeAt;
+    /**
+     * 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.
+     */
+    private mutate;
+    /**
+     * 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.
+     */
+    private parseSettings;
+}

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

@@ -11,6 +11,10 @@ import { ContractRepository, WalletRepository } from "../repositories";
 import { IContractManager } from "../contracts/contractManager";
 import { IDelegatorManager } from "./delegator";
 import { DelegatorProvider } from "../providers/delegator";
+/** Defaults */
+export declare const DEFAULT_ARKADE_SERVER_URL: "https://arkade.computer";
+export declare const DEFAULT_ARKADE_HRP = "ark";
+export declare const DEFAULT_NETWORK_NAME = "bitcoin";
 /**
  * Base configuration options shared by all wallet types.
  *
@@ -22,9 +26,6 @@ import { DelegatorProvider } from "../providers/delegator";
  * Provider-based configuration supplies concrete provider instances directly,
  * including the ArkProvider, IndexerProvider, OnchainProvider, and DelegatorProvider.
  *
- * At least one of the following must be provided:
- * - arkServerUrl OR arkProvider
- *
  * The wallet will use provided URLs to create default providers if custom provider
  * instances are not supplied. If optional parameters are not provided, the wallet
  * will fetch configuration from the Arkade server.
@@ -255,8 +256,12 @@ export interface SendBitcoinParams {
 export interface Asset {
     /** Asset identifier. */
     assetId: string;
-    /** Asset amount in base units. */
-    amount: number;
+    /**
+     * Asset amount in base units. Typed as `bigint` because asset
+     * supplies routinely exceed `Number.MAX_SAFE_INTEGER` (2^53 - 1)
+     * and silently truncating in arithmetic would corrupt balances.
+     */
+    amount: bigint;
 }
 /**
  * Recipient accepted by `IWallet.send`.
@@ -310,8 +315,12 @@ export type AssetMetadata = KnownMetadata & Record<string, unknown>;
 export type AssetDetails = {
     /** Asset identifier. */
     assetId: string;
-    /** Total issued supply in base units. */
-    supply: number;
+    /**
+     * Total issued supply in base units. Typed as `bigint` for the
+     * same reason as {@link Asset.amount} — supplies often exceed
+     * `Number.MAX_SAFE_INTEGER`.
+     */
+    supply: bigint;
     /** Optional immutable metadata associated with the asset. */
     metadata?: AssetMetadata;
     /** Optional control asset id required for future reissuance. */
@@ -325,7 +334,7 @@ export type AssetDetails = {
  */
 export interface IssuanceParams {
     /** Initial amount of asset to issue */
-    amount: number;
+    amount: bigint;
     /** Optional control asset ID that can be used for future reissuance */
     controlAssetId?: string;
     /** Immutable asset metadata including `ticker`, `decimals`, `icon` */
@@ -352,7 +361,7 @@ export interface ReissuanceParams {
     /** Existing asset ID, made up of genesis (Arkade) transaction ID and zero-based asset group index */
     assetId: string;
     /** Amount of asset to issue */
-    amount: number;
+    amount: bigint;
 }
 /**
  * Parameters accepted by `IAssetManager.burn`.
@@ -363,7 +372,7 @@ export interface BurnParams {
     /** Existing asset ID, made up of genesis (Arkade) transaction ID and zero-based asset group index */
     assetId: string;
     /** Amount of asset to burn */
-    amount: number;
+    amount: bigint;
 }
 /**
  * Explicit inputs and outputs accepted by `IWallet.settle`.

package/dist/types/wallet/onchain.d.ts

@@ -39,7 +39,7 @@ export declare class OnchainWallet implements AnchorBumper {
      * @defaultValue `provider = new EsploraProvider('https://mempool.space/api')`
      * @throws Error if the configured identity cannot produce a valid x-only public key
      */
-    static create(identity: Identity, networkName: NetworkName, provider?: OnchainProvider): Promise<OnchainWallet>;
+    static create(identity: Identity, networkName?: NetworkName, provider?: OnchainProvider): Promise<OnchainWallet>;
     get address(): string;
     /**
      * Fetch spendable onchain outputs for the wallet address.

package/dist/types/wallet/serviceWorker/wallet.d.ts

@@ -45,7 +45,7 @@ interface ServiceWorkerWalletOptions {
     /** Optional Arkade server public key used to construct and validate Arkade addresses. */
     arkServerPublicKey?: string;
     /** Base URL of the Arkade server. */
-    arkServerUrl: string;
+    arkServerUrl?: string;
     /** Optional override for the indexer URL. */
     indexerUrl?: string;
     /** Optional override for the Esplora API URL. */

package/dist/types/wallet/unroll.d.ts

@@ -15,6 +15,7 @@ export declare namespace Unroll {
      */
     type UnrollStep = {
         tx: Transaction;
+        pkg: [parent: string, child: string];
     };
     /**
      * Wait step where the transaction has to be confirmed onchain
@@ -102,3 +103,12 @@ export declare namespace Unroll {
      */
     function completeUnroll(wallet: Wallet, vtxoTxids: string[], outputAddress: string): Promise<string>;
 }
+/**
+ * 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 declare function prepareUnrollTransaction(wallet: Wallet, vtxoTxIds: string[], outputAddress: string): Promise<Transaction>;

package/dist/types/wallet/wallet.d.ts

@@ -19,6 +19,9 @@ import { DelegatorProvider } from "../providers/delegator";
 import { DelegateVtxo } from "../script/delegate";
 import { IDelegatorManager } from "./delegator";
 import { ContractManager } from "../contracts/contractManager";
+export declare const getArkadeServerUrl: ({ arkServerUrl, }: {
+    arkServerUrl?: string;
+}) => string;
 export type IncomingFunds = {
     type: "utxo";
     coins: Coin[];
@@ -321,7 +324,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * 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
      * });
      * ```
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",