cashscript 0.13.0-next.6 → 0.13.0-next.8

package/dist/TransactionBuilder.js

@@ -6,22 +6,45 @@ import { debugLibauthTemplate, getLibauthTemplate, getBitauthUri } from './libau
 import { getWcContractInfo } from './walletconnect-utils.js';
 import semver from 'semver';
 const DEFAULT_SEQUENCE = 0xfffffffe;
+/**
+ * Fluent builder for constructing, debugging, and broadcasting CashScript transactions.
+ *
+ * Inputs are added via `addInput` / `addInputs` with an `Unlocker` produced by a `Contract` or
+ * `SignatureTemplate`, outputs are added via `addOutput` / `addOutputs`, and the resulting
+ * transaction can be built (`build`), debugged (`debug`), or broadcast (`send`).
+ */
 export class TransactionBuilder {
+    /**
+     * Create a new TransactionBuilder.
+     *
+     * @param options - Builder options, including the network provider and optional fee/burn limits.
+     */
     constructor(options) {
         this.inputs = [];
         this.outputs = [];
         this.locktime = 0;
+        this.changeLocks = {};
         this.provider = options.provider;
         this.options = {
             allowImplicitFungibleTokenBurn: options.allowImplicitFungibleTokenBurn ?? false,
             ...options,
         };
     }
+    /**
+     * Add a single UTXO as an input to the transaction.
+     *
+     * @param utxo - The UTXO to spend.
+     * @param unlocker - The unlocker to generate the unlocking bytecode for this input. Typically
+     *   obtained from `contract.unlock.<functionName>(...args)` or `signatureTemplate.unlockP2PKH()`.
+     * @param options - Optional per-input options such as a custom sequence number.
+     * @returns This builder for chaining.
+     * @throws If the UTXO is invalid.
+     */
     addInput(utxo, unlocker, options) {
         return this.addInputs([utxo], unlocker, options);
     }
     addInputs(utxos, unlocker, options) {
-        utxos.forEach(validateInput);
+        utxos.forEach((utxo) => validateInput(utxo, this.changeLocks));
         if ((!unlocker && utxos.some((utxo) => !isUnlockableUtxo(utxo)))
             || (unlocker && utxos.some((utxo) => isUnlockableUtxo(utxo)))) {
             throw new Error('Either all UTXOs must have an individual unlocker specified, or no UTXOs must have an individual unlocker specified and a shared unlocker must be provided');
@@ -33,19 +56,53 @@ export class TransactionBuilder {
         this.inputs = this.inputs.concat(utxos.map(((utxo) => ({ ...utxo, unlocker, options }))));
         return this;
     }
+    /**
+     * Add a single output to the transaction.
+     *
+     * @param output - The output to add. Its address, amount and optional token are validated
+     *   against the provider's network.
+     * @returns This builder for chaining.
+     * @throws If the output is invalid.
+     */
     addOutput(output) {
         return this.addOutputs([output]);
     }
+    /**
+     * Add multiple outputs to the transaction.
+     *
+     * @param outputs - The outputs to add. Each output is validated against the provider's network.
+     * @returns This builder for chaining.
+     * @throws If any output is invalid.
+     */
     addOutputs(outputs) {
-        outputs.forEach(validateOutput);
+        outputs.forEach((output) => validateOutput(output, this.provider.network, this.changeLocks));
         this.outputs = this.outputs.concat(outputs);
         return this;
     }
     // TODO: allow uint8array for chunks
+    /**
+     * Append an `OP_RETURN` output containing the provided data chunks. Hex strings prefixed with
+     * `0x` are decoded as bytes; other strings are encoded as UTF-8.
+     *
+     * @param chunks - The data chunks to include after the `OP_RETURN` opcode.
+     * @returns This builder for chaining.
+     */
     addOpReturnOutput(chunks) {
-        this.outputs.push(createOpReturnOutput(chunks));
+        this.addOutput(createOpReturnOutput(chunks));
         return this;
     }
+    /**
+     * Add a BCH change output for the remaining value after fees, if it exceeds the dust limit. The
+     * fee is computed from the transaction size at the configured fee rate; dust-sized change is
+     * simply absorbed into the fee.
+     *
+     * Should be called *after* all explicit inputs and outputs are added.
+     *
+     * @param changeOutputOptions - The destination address and the fee rate (in sats/byte) to use.
+     * @returns This builder for chaining.
+     * @throws If the available surplus is insufficient to cover the fee for the configured rate or
+     * if a BCH change output was already added.
+     */
     addBchChangeOutputIfNeeded(changeOutputOptions) {
         const totalBchInputAmount = this.inputs.reduce((total, input) => total + input.satoshis, 0n);
         const totalBchOutputAmount = this.outputs.reduce((total, output) => total + output.amount, 0n);
@@ -66,15 +123,64 @@ export class TransactionBuilder {
         const changeOutput = { to: changeOutputOptions.to, amount: changeAmount };
         const changeOutputDust = calculateDust(changeOutput);
         if (changeAmount < changeOutputDust) {
+            this.changeLocks.BCH = true;
             return this;
         }
-        this.outputs.push(changeOutput);
+        this.addOutput(changeOutput);
+        this.changeLocks.BCH = true;
         return this;
     }
+    /**
+     * Add a fungible token change output for the configured category if the transaction's inputs
+     * contain more tokens of that category than its outputs. The change output is sent to the
+     * provided token address and carries the dust-minimum BCH amount.
+     *
+     * Should be called *after* all explicit token outputs for the category are added and *before*
+     * `addBchChangeOutputIfNeeded`.
+     *
+     * @param changeOutputOptions - The token category to handle and the destination token address.
+     * @returns This builder for chaining.
+     * @throws If the destination is not a token-supporting address, or if a corresponding change output
+     * or BCH change output was already added.
+     */
+    addTokenChangeOutputIfNeeded(changeOutputOptions) {
+        const { category, to } = changeOutputOptions;
+        const inputAmount = this.inputs
+            .filter((input) => input.token?.category === category)
+            .reduce((total, input) => total + input.token.amount, 0n);
+        const outputAmount = this.outputs
+            .filter((output) => output.token?.category === category)
+            .reduce((total, output) => total + output.token.amount, 0n);
+        const changeAmount = inputAmount - outputAmount;
+        if (changeAmount <= 0n) {
+            this.changeLocks[category] = true;
+            return this;
+        }
+        const changeOutput = {
+            to,
+            amount: 0n,
+            token: { amount: changeAmount, category },
+        };
+        changeOutput.amount = BigInt(calculateDust(changeOutput));
+        this.addOutput(changeOutput);
+        this.changeLocks[category] = true;
+        return this;
+    }
+    /**
+     * Build the transaction (skipping fee and burn checks) and return its encoded byte length.
+     *
+     * @returns The size of the transaction in bytes.
+     */
     getTransactionSize() {
         const transaction = this.buildLibauthTransaction(true);
         return BigInt(encodeTransaction(transaction).byteLength);
     }
+    /**
+     * Set the `nLockTime` of the transaction.
+     *
+     * @param locktime - The absolute locktime to use (block height or UNIX timestamp).
+     * @returns This builder for chaining.
+     */
     setLocktime(locktime) {
         this.locktime = locktime;
         return this;
@@ -144,10 +250,26 @@ export class TransactionBuilder {
         }
         return transaction;
     }
+    /**
+     * Build the transaction, applying fee and implicit-burn checks, and return the hex-encoded
+     * transaction bytes.
+     *
+     * @returns The signed transaction as a hex string.
+     * @throws If the transaction fee exceeds the configured maximum, or if fungible tokens are
+     *   implicitly burned without `allowImplicitFungibleTokenBurn` enabled.
+     */
     build() {
         const transaction = this.buildLibauthTransaction();
         return binToHex(encodeTransaction(transaction));
     }
+    /**
+     * Locally evaluate the transaction against the Bitcoin Cash VM using debug information from the
+     * contract artifacts. Throws a descriptive error if any input fails evaluation.
+     *
+     * @returns The full debug execution trace for every scenario in the generated libauth template.
+     * @throws If the transaction contains inputs with custom (non-standard) unlockers, or if the
+     *   evaluation fails (e.g. a failing `require` statement).
+     */
     debug() {
         if (this.inputs.some((input) => !isStandardUnlockableUtxo(input))) {
             throw new Error('Cannot debug a transaction with custom unlocker');
@@ -161,6 +283,15 @@ export class TransactionBuilder {
         }
         return debugLibauthTemplate(this.getLibauthTemplate(), this);
     }
+    /**
+     * Compute VM resource usage (ops, op cost budget, sigchecks, hash iterations) for each input
+     * by running the transaction through `debug`.
+     *
+     * @param verbose - When `true`, also prints a formatted table of the results via `console.table`.
+     * @returns One entry per input with its VM resource usage metrics.
+     * @throws If the transaction contains inputs with custom (non-standard) unlockers, or if the
+     *   evaluation fails.
+     */
     getVmResourceUsage(verbose = false) {
         // Note that only StandardUnlockableUtxo inputs are supported for debugging, so any transaction with custom unlockers
         // cannot be debugged (and therefore cannot return VM resource usage)
@@ -191,10 +322,27 @@ export class TransactionBuilder {
         }
         return vmResourceUsage;
     }
+    /**
+     * Build a Bitauth IDE URI that loads the transaction (and all private keys required to sign it)
+     * in the online Bitauth IDE debugger.
+     *
+     * WARNING: The URI embeds every private key used in the transaction. Do not share this URI if
+     * the transaction is signed with real private keys.
+     *
+     * @returns A Bitauth IDE URL for debugging this transaction.
+     * @throws If the transaction cannot be built (fee exceeds limit or fungible tokens burned).
+     */
     getBitauthUri() {
         console.warn('WARNING: it is unsafe to use this Bitauth URI when using real private keys as they are included in the transaction template');
         return getBitauthUri(this.getLibauthTemplate());
     }
+    /**
+     * Build the transaction and return the corresponding libauth `WalletTemplate`. Useful for
+     * exporting the transaction to external libauth-compatible tooling.
+     *
+     * @returns A libauth `WalletTemplate` describing this transaction.
+     * @throws If the transaction cannot be built (fee exceeds limit or fungible tokens burned).
+     */
     getLibauthTemplate() {
         const libauthTransaction = this.buildLibauthTransaction();
         return getLibauthTemplate(this, libauthTransaction);
@@ -212,7 +360,14 @@ export class TransactionBuilder {
         }
         catch (e) {
             const reason = e.error ?? e.message;
-            throw new FailedTransactionError(reason, this.getBitauthUri());
+            try {
+                const bitauthUri = getBitauthUri(this.getLibauthTemplate());
+                throw new FailedTransactionError(reason, bitauthUri);
+            }
+            catch {
+                // Preserve the original broadcast failure reason if URI generation fails
+                throw new FailedTransactionError(reason, 'Bitauth URI generation failed');
+            }
         }
     }
     async getTxDetails(txid, raw) {
@@ -232,6 +387,16 @@ export class TransactionBuilder {
         // Should not happen
         throw new Error('Could not retrieve transaction details for over 10 minutes');
     }
+    /**
+     * Build the transaction and format it as a BCH WalletConnect transaction object suitable for
+     * signing and broadcasting via a BCH WalletConnect-compatible Bitcoin Cash wallet.
+     *
+     * See the [BCH WalletConnect spec](https://github.com/mainnet-pat/wc2-bch-bcr) for the object format.
+     *
+     * @param options - Optional WalletConnect options such as `broadcast` and `userPrompt`.
+     * @returns A WalletConnect transaction object ready to be sent to a WalletConnect wallet.
+     * @throws If the transaction cannot be built (fee exceeds limit or fungible tokens burned).
+     */
     generateWcTransactionObject(options) {
         const encodedTransaction = this.build();
         const transaction = decodeTransactionUnsafe(hexToBin(encodedTransaction));

package/dist/index.d.ts

@@ -6,7 +6,8 @@ export type { Artifact, AbiFunction, AbiInput } from '@cashscript/utils';
 export * as utils from '@cashscript/utils';
 export * from './interfaces.js';
 export * from './Errors.js';
-export { type NetworkProvider, BitcoinRpcNetworkProvider, ElectrumNetworkProvider, FullStackNetworkProvider, MockNetworkProvider, } from './network/index.js';
+export * from './network/errors.js';
+export { type NetworkProvider, ElectrumNetworkProvider, MockNetworkProvider, } from './network/index.js';
 export { randomUtxo, randomToken, randomNFT } from './utils.js';
 export * from './walletconnect-utils.js';
 export { gatherBchUtxos, gatherFungibleTokenUtxos, type GatherUtxosResult } from './transaction-utils.js';

package/dist/index.js

@@ -5,7 +5,8 @@ export { encodeFunctionArgument, } from './Argument.js';
 export * as utils from '@cashscript/utils';
 export * from './interfaces.js';
 export * from './Errors.js';
-export { BitcoinRpcNetworkProvider, ElectrumNetworkProvider, FullStackNetworkProvider, MockNetworkProvider, } from './network/index.js';
+export * from './network/errors.js';
+export { ElectrumNetworkProvider, MockNetworkProvider, } from './network/index.js';
 export { randomUtxo, randomToken, randomNFT } from './utils.js';
 export * from './walletconnect-utils.js';
 export { gatherBchUtxos, gatherFungibleTokenUtxos } from './transaction-utils.js';

package/dist/interfaces.d.ts

@@ -62,6 +62,10 @@ export interface BchChangeOutputOptions {
     to: string | Uint8Array;
     feeRate: number;
 }
+export interface TokenChangeOutputOptions {
+    category: string;
+    to: string | Uint8Array;
+}
 export interface TokenDetails {
     amount: bigint;
     category: string;

package/dist/network/ElectrumNetworkProvider.d.ts

@@ -11,11 +11,23 @@ interface CustomElectrumOptions extends OptionsBase {
     electrum: ElectrumClient<ElectrumClientEvents>;
 }
 type Options = OptionsBase | CustomHostNameOptions | CustomElectrumOptions;
+/**
+ * A `NetworkProvider` implementation backed by an Electrum Cash server. By default it manages
+ * its own connection lifecycle, connecting on demand and disconnecting when idle; for long-lived
+ * clients, pass `manualConnectionManagement: true` and call `connect` / `disconnect` explicitly.
+ */
 export default class ElectrumNetworkProvider implements NetworkProvider {
     network: Network;
     private electrum;
     private concurrentRequests;
     private manualConnectionManagement;
+    /**
+     * Create a new ElectrumNetworkProvider.
+     *
+     * @param network - The BCH network to connect to. Defaults to `Network.MAINNET`.
+     * @param options - Optional hostname, pre-configured `ElectrumClient`, and/or
+     *   `manualConnectionManagement` flag.
+     */
     constructor(network?: Network, options?: Options);
     private instantiateElectrumClient;
     private getServerForNetwork;
@@ -24,8 +36,29 @@ export default class ElectrumNetworkProvider implements NetworkProvider {
     getBlockHeight(): Promise<number>;
     getRawTransaction(txid: string): Promise<string>;
     sendRawTransaction(txHex: string): Promise<string>;
+    /**
+     * Manually open the underlying Electrum connection. Only allowed when the provider was created
+     * with `manualConnectionManagement: true`.
+     *
+     * @throws If manual connection management is disabled.
+     */
     connect(): Promise<void>;
+    /**
+     * Manually close the underlying Electrum connection. Only allowed when the provider was created
+     * with `manualConnectionManagement: true`.
+     *
+     * @throws If manual connection management is disabled.
+     * @returns Whether the connection was disconnected successfully.
+     */
     disconnect(): Promise<boolean>;
+    /**
+     * Perform an arbitrary Electrum JSON-RPC request against the underlying server. Automatically
+     * manages the connection lifecycle unless `manualConnectionManagement` was set.
+     *
+     * @param name - The Electrum method name (e.g. `blockchain.transaction.get`).
+     * @param parameters - Parameters passed to the method.
+     * @returns The raw Electrum server response.
+     */
     performRequest(name: string, ...parameters: (string | number | boolean)[]): Promise<RequestResponse>;
     private shouldConnect;
     private shouldDisconnect;

package/dist/network/ElectrumNetworkProvider.js

@@ -3,7 +3,20 @@ import { sha256 } from '@cashscript/utils';
 import { ElectrumClient, } from '@electrum-cash/network';
 import { Network } from '../interfaces.js';
 import { addressToLockScript } from '../utils.js';
+import { NetworkProviderMissingInputsError, NetworkProviderMempoolConflictError, NetworkProviderTransactionAlreadySubmittedError, NetworkProviderAbsoluteTimelockError, NetworkProviderRelativeTimelockError, } from './errors.js';
+/**
+ * A `NetworkProvider` implementation backed by an Electrum Cash server. By default it manages
+ * its own connection lifecycle, connecting on demand and disconnecting when idle; for long-lived
+ * clients, pass `manualConnectionManagement: true` and call `connect` / `disconnect` explicitly.
+ */
 export default class ElectrumNetworkProvider {
+    /**
+     * Create a new ElectrumNetworkProvider.
+     *
+     * @param network - The BCH network to connect to. Defaults to `Network.MAINNET`.
+     * @param options - Optional hostname, pre-configured `ElectrumClient`, and/or
+     *   `manualConnectionManagement` flag.
+     */
     constructor(network = Network.MAINNET, options = {}) {
         this.network = network;
         this.concurrentRequests = 0;
@@ -62,20 +75,47 @@ export default class ElectrumNetworkProvider {
         return await this.performRequest('blockchain.transaction.get', txid);
     }
     async sendRawTransaction(txHex) {
-        return await this.performRequest('blockchain.transaction.broadcast', txHex);
+        try {
+            return await this.performRequest('blockchain.transaction.broadcast', txHex);
+        }
+        catch (e) {
+            const errorMessage = e.message ?? String(e);
+            throw classifyNetworkProviderError(errorMessage);
+        }
     }
+    /**
+     * Manually open the underlying Electrum connection. Only allowed when the provider was created
+     * with `manualConnectionManagement: true`.
+     *
+     * @throws If manual connection management is disabled.
+     */
     async connect() {
         if (!this.manualConnectionManagement) {
             throw new Error('Manual connection management is disabled');
         }
         return this.electrum.connect();
     }
+    /**
+     * Manually close the underlying Electrum connection. Only allowed when the provider was created
+     * with `manualConnectionManagement: true`.
+     *
+     * @throws If manual connection management is disabled.
+     * @returns Whether the connection was disconnected successfully.
+     */
     async disconnect() {
         if (!this.manualConnectionManagement) {
             throw new Error('Manual connection management is disabled');
         }
         return this.electrum.disconnect();
     }
+    /**
+     * Perform an arbitrary Electrum JSON-RPC request against the underlying server. Automatically
+     * manages the connection lifecycle unless `manualConnectionManagement` was set.
+     *
+     * @param name - The Electrum method name (e.g. `blockchain.transaction.get`).
+     * @param parameters - Parameters passed to the method.
+     * @returns The raw Electrum server response.
+     */
     async performRequest(name, ...parameters) {
         // Only connect the electrum client when no concurrent requests are running
         if (this.shouldConnect()) {
@@ -113,6 +153,43 @@ export default class ElectrumNetworkProvider {
         return true;
     }
 }
+const MISSING_INPUTS_PATTERNS = [
+    'Missing inputs',
+    'bad-txns-inputs-missingorspent',
+    'bad-txns-inputs-spent',
+];
+const MEMPOOL_CONFLICT_PATTERNS = [
+    'txn-mempool-conflict',
+];
+const ALREADY_SUBMITTED_PATTERNS = [
+    'transaction already in block chain',
+    'txn-already-known',
+    'txn-already-in-mempool',
+];
+const ABSOLUTE_TIMELOCK_PATTERNS = [
+    'bad-txns-nonfinal',
+];
+const RELATIVE_TIMELOCK_PATTERNS = [
+    'non-BIP68-final',
+];
+function classifyNetworkProviderError(errorMessage) {
+    if (MISSING_INPUTS_PATTERNS.some((pattern) => errorMessage.includes(pattern))) {
+        return new NetworkProviderMissingInputsError(errorMessage);
+    }
+    if (MEMPOOL_CONFLICT_PATTERNS.some((pattern) => errorMessage.includes(pattern))) {
+        return new NetworkProviderMempoolConflictError(errorMessage);
+    }
+    if (ALREADY_SUBMITTED_PATTERNS.some((pattern) => errorMessage.includes(pattern))) {
+        return new NetworkProviderTransactionAlreadySubmittedError(errorMessage);
+    }
+    if (ABSOLUTE_TIMELOCK_PATTERNS.some((pattern) => errorMessage.includes(pattern))) {
+        return new NetworkProviderAbsoluteTimelockError(errorMessage);
+    }
+    if (RELATIVE_TIMELOCK_PATTERNS.some((pattern) => errorMessage.includes(pattern))) {
+        return new NetworkProviderRelativeTimelockError(errorMessage);
+    }
+    return new Error(errorMessage);
+}
 function lockingBytecodeToElectrumScriptHash(lockingBytecode) {
     const scriptHash = sha256(lockingBytecode);
     scriptHash.reverse();

package/dist/network/MockNetworkProvider.d.ts

@@ -1,9 +1,23 @@
 import { Utxo, Network, VmTarget } from '../interfaces.js';
 import NetworkProvider from './NetworkProvider.js';
+/**
+ * Options accepted by the `MockNetworkProvider` constructor.
+ */
 export interface MockNetworkProviderOptions {
+    /**
+     * When `true` (default), broadcasting a transaction via `sendRawTransaction` updates the
+     * in-memory UTXO set: input UTXOs are removed and output UTXOs are added. Set to `false` to
+     * keep the UTXO set static.
+     */
     updateUtxoSet?: boolean;
+    /** The BCH VM target used for local debugging. Defaults to the current stable VM. */
     vmTarget?: VmTarget;
 }
+/**
+ * An in-memory `NetworkProvider` useful for tests and examples. It does not connect to any
+ * external server; instead UTXOs are manually added via `addUtxo` and transactions are tracked
+ * in memory.
+ */
 export default class MockNetworkProvider implements NetworkProvider {
     private utxoSet;
     private transactionMap;
@@ -11,13 +25,34 @@ export default class MockNetworkProvider implements NetworkProvider {
     network: Network;
     options: MockNetworkProviderOptions;
     vmTarget: VmTarget;
+    /**
+     * Create a new MockNetworkProvider.
+     *
+     * @param options - Optional settings controlling UTXO-set updating and the VM target used by
+     *   `TransactionBuilder.debug`.
+     */
     constructor(options?: Partial<MockNetworkProviderOptions>);
     getUtxos(address: string): Promise<Utxo[]>;
     getUtxosForLockingBytecode(lockingBytecode: Uint8Array | string): Promise<Utxo[]>;
+    /**
+     * Override the current block height returned by `getBlockHeight`.
+     *
+     * @param newBlockHeight - The block height to report for subsequent queries.
+     */
     setBlockHeight(newBlockHeight: number): void;
     getBlockHeight(): Promise<number>;
     getRawTransaction(txid: string): Promise<string>;
     sendRawTransaction(txHex: string): Promise<string>;
+    /**
+     * Add a UTXO to the in-memory set so that it becomes spendable by the specified address or
+     * locking bytecode.
+     *
+     * @param addressOrLockingBytecode - Either a CashAddress or a hex-encoded locking bytecode.
+     * @param utxo - The UTXO to make spendable.
+     */
     addUtxo(addressOrLockingBytecode: string, utxo: Utxo): void;
+    /**
+     * Clear the in-memory UTXO set and transaction history. Block height is preserved.
+     */
     reset(): void;
 }

package/dist/network/MockNetworkProvider.js

@@ -3,7 +3,18 @@ import { sha256 } from '@cashscript/utils';
 import { Network } from '../interfaces.js';
 import { addressToLockScript, libauthTokenDetailsToCashScriptTokenDetails } from '../utils.js';
 import { DEFAULT_VM_TARGET } from '../libauth-template/utils.js';
+/**
+ * An in-memory `NetworkProvider` useful for tests and examples. It does not connect to any
+ * external server; instead UTXOs are manually added via `addUtxo` and transactions are tracked
+ * in memory.
+ */
 export default class MockNetworkProvider {
+    /**
+     * Create a new MockNetworkProvider.
+     *
+     * @param options - Optional settings controlling UTXO-set updating and the VM target used by
+     *   `TransactionBuilder.debug`.
+     */
     constructor(options) {
         // we use lockingBytecode hex as the key for utxoMap to make cash addresses and token addresses interchangeable
         this.utxoSet = [];
@@ -21,6 +32,11 @@ export default class MockNetworkProvider {
         const lockingBytecodeHex = typeof lockingBytecode === 'string' ? lockingBytecode : binToHex(lockingBytecode);
         return this.utxoSet.filter(([key]) => key === lockingBytecodeHex).map(([, utxo]) => utxo);
     }
+    /**
+     * Override the current block height returned by `getBlockHeight`.
+     *
+     * @param newBlockHeight - The block height to report for subsequent queries.
+     */
     setBlockHeight(newBlockHeight) {
         this.blockHeight = newBlockHeight;
     }
@@ -62,11 +78,21 @@ export default class MockNetworkProvider {
     // Note: the user can technically add the same UTXO multiple times (txid + vout), to the same or different addresses
     // but we don't check for this in the sendRawTransaction method. We might want to prevent duplicates from being added
     // in the first place.
+    /**
+     * Add a UTXO to the in-memory set so that it becomes spendable by the specified address or
+     * locking bytecode.
+     *
+     * @param addressOrLockingBytecode - Either a CashAddress or a hex-encoded locking bytecode.
+     * @param utxo - The UTXO to make spendable.
+     */
     addUtxo(addressOrLockingBytecode, utxo) {
         const lockingBytecode = isHex(addressOrLockingBytecode) ?
             addressOrLockingBytecode : binToHex(addressToLockScript(addressOrLockingBytecode));
         this.utxoSet.push([lockingBytecode, utxo]);
     }
+    /**
+     * Clear the in-memory UTXO set and transaction history. Block height is preserved.
+     */
     reset() {
         this.utxoSet = [];
         this.transactionMap = {};

package/dist/network/errors.d.ts

@@ -0,0 +1,19 @@
+export declare class NetworkProviderError extends Error {
+    originalError: string;
+    constructor(message: string, originalError: string);
+}
+export declare class NetworkProviderMissingInputsError extends NetworkProviderError {
+    constructor(originalError: string);
+}
+export declare class NetworkProviderMempoolConflictError extends NetworkProviderError {
+    constructor(originalError: string);
+}
+export declare class NetworkProviderTransactionAlreadySubmittedError extends NetworkProviderError {
+    constructor(originalError: string);
+}
+export declare class NetworkProviderAbsoluteTimelockError extends NetworkProviderError {
+    constructor(originalError: string);
+}
+export declare class NetworkProviderRelativeTimelockError extends NetworkProviderError {
+    constructor(originalError: string);
+}

package/dist/network/errors.js

@@ -0,0 +1,38 @@
+// Base class for errors returned by a network provider when broadcasting a transaction.
+export class NetworkProviderError extends Error {
+    constructor(message, originalError) {
+        super(message);
+        this.originalError = originalError;
+    }
+}
+// Thrown when one or more inputs reference UTXOs that are missing or already spent.
+export class NetworkProviderMissingInputsError extends NetworkProviderError {
+    constructor(originalError) {
+        super(`Transaction inputs are missing or already spent: ${originalError}`, originalError);
+    }
+}
+// Thrown when an input is already being spent by another transaction in the mempool (double-spend).
+export class NetworkProviderMempoolConflictError extends NetworkProviderError {
+    constructor(originalError) {
+        super(`Transaction conflicts with an unconfirmed transaction in the mempool: ${originalError}`, originalError);
+    }
+}
+// Thrown when the same transaction has already been submitted (already in mempool or confirmed).
+export class NetworkProviderTransactionAlreadySubmittedError extends NetworkProviderError {
+    constructor(originalError) {
+        super(`Transaction has already been submitted: ${originalError}`, originalError);
+    }
+}
+// Thrown when the transaction's nLockTime has not been satisfied (transaction is not yet final).
+export class NetworkProviderAbsoluteTimelockError extends NetworkProviderError {
+    constructor(originalError) {
+        super(`Transaction is not yet final (nLockTime not satisfied): ${originalError}`, originalError);
+    }
+}
+// Thrown when a BIP68 relative timelock (sequence lock) on an input has not been satisfied.
+export class NetworkProviderRelativeTimelockError extends NetworkProviderError {
+    constructor(originalError) {
+        super(`BIP68 sequence lock not satisfied: ${originalError}`, originalError);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/network/index.d.ts

@@ -1,5 +1,3 @@
 export type { default as NetworkProvider } from './NetworkProvider.js';
-export { default as BitcoinRpcNetworkProvider } from './BitcoinRpcNetworkProvider.js';
 export { default as ElectrumNetworkProvider } from './ElectrumNetworkProvider.js';
-export { default as FullStackNetworkProvider } from './FullStackNetworkProvider.js';
 export { default as MockNetworkProvider } from './MockNetworkProvider.js';

package/dist/network/index.js

@@ -1,5 +1,3 @@
-export { default as BitcoinRpcNetworkProvider } from './BitcoinRpcNetworkProvider.js';
 export { default as ElectrumNetworkProvider } from './ElectrumNetworkProvider.js';
-export { default as FullStackNetworkProvider } from './FullStackNetworkProvider.js';
 export { default as MockNetworkProvider } from './MockNetworkProvider.js';
 //# sourceMappingURL=index.js.map