cashscript 0.13.0-next.5 → 0.13.0-next.7

package/dist/Argument.d.ts

@@ -5,6 +5,22 @@ export type FunctionArgument = ConstructorArgument | SignatureTemplate;
 export type EncodedConstructorArgument = Uint8Array;
 export type EncodedFunctionArgument = Uint8Array | SignatureTemplate;
 export type EncodeFunction = (arg: FunctionArgument, typeStr: string) => EncodedFunctionArgument;
+/**
+ * Encode a single CashScript function argument to its on-stack byte representation.
+ *
+ * The encoding is chosen based on `typeStr`:
+ * - `bool`, `int`, `string` → encoded via their CashScript primitive encoders.
+ * - `sig` passed as a `SignatureTemplate` → returned as-is so the transaction builder can
+ *   produce the signature at build time.
+ * - `sig` / `datasig` / `bytes[N]` passed as a `Uint8Array` or hex string → byte-checked and
+ *   returned as bytes.
+ *
+ * @param argument - The runtime argument value provided by the caller.
+ * @param typeStr - The CashScript type string from the contract ABI (e.g. `int`, `bytes20`, `sig`).
+ * @returns The encoded argument, ready for inclusion in an unlocking script.
+ * @throws A `TypeError` when the JS type does not match the expected CashScript type, or when a
+ *   bounded bytes type receives a value of the wrong length.
+ */
 export declare function encodeFunctionArgument(argument: FunctionArgument, typeStr: string): EncodedFunctionArgument;
 export declare const encodeConstructorArguments: (artifact: Artifact, constructorArgs: ConstructorArgument[], encodeFunction?: EncodeFunction) => Uint8Array[];
 export declare const encodeFunctionArguments: (abiFunction: AbiFunction, functionArgs: FunctionArgument[], encodeFunction?: EncodeFunction) => EncodedFunctionArgument[];

package/dist/Argument.js

@@ -2,6 +2,22 @@ import { hexToBin } from '@bitauth/libauth';
 import { BytesType, encodeBool, encodeInt, encodeString, parseType, PrimitiveType, } from '@cashscript/utils';
 import { TypeError } from './Errors.js';
 import SignatureTemplate from './SignatureTemplate.js';
+/**
+ * Encode a single CashScript function argument to its on-stack byte representation.
+ *
+ * The encoding is chosen based on `typeStr`:
+ * - `bool`, `int`, `string` → encoded via their CashScript primitive encoders.
+ * - `sig` passed as a `SignatureTemplate` → returned as-is so the transaction builder can
+ *   produce the signature at build time.
+ * - `sig` / `datasig` / `bytes[N]` passed as a `Uint8Array` or hex string → byte-checked and
+ *   returned as bytes.
+ *
+ * @param argument - The runtime argument value provided by the caller.
+ * @param typeStr - The CashScript type string from the contract ABI (e.g. `int`, `bytes20`, `sig`).
+ * @returns The encoded argument, ready for inclusion in an unlocking script.
+ * @throws A `TypeError` when the JS type does not match the expected CashScript type, or when a
+ *   bounded bytes type receives a value of the wrong length.
+ */
 export function encodeFunctionArgument(argument, typeStr) {
     let type = parseType(typeStr);
     if (type === PrimitiveType.BOOL) {

package/dist/Contract.d.ts

@@ -11,23 +11,61 @@ type DefaultResolved<TArtifact extends Artifact> = {
     constructorInputs: ParamsToTuple<TArtifact['constructorInputs']>;
     unlock: AbiToFunctionMap<TArtifact['abi'], Unlocker>;
 };
-declare class ContractInternal<TArtifact extends Artifact, TResolved extends ResolvedConstraint, TContractType extends ContractType> {
-    artifact: TArtifact;
-    private options;
+declare class ContractBase {
+    /** The contract name as defined in the source CashScript code. */
     name: string;
+    /** The CashAddress of the contract. Not available for `p2s` contracts. */
     address: string;
+    /** The token-aware CashAddress of the contract. Not available for `p2s` contracts. */
     tokenAddress: string;
+    /** Hex-encoded locking bytecode of the contract. */
     lockingBytecode: string;
+    /** Hex-encoded redeem bytecode of the contract (constructor args prepended to the compiled script). */
     bytecode: string;
+    /** Size of the contract bytecode in bytes. */
     bytesize: number;
+    /** Number of opcodes in the contract bytecode. */
     opcount: number;
-    unlock: TResolved['unlock'];
+    /** The network provider used to query UTXOs for this contract and get network information. */
     provider: NetworkProvider;
-    contractType: TContractType;
+    /** The address type of this contract: `p2sh20`, `p2sh32`, or `p2s`. */
+    contractType: ContractType;
+    /** Encoded constructor arguments in the order expected by the contract's constructor. */
     encodedConstructorArgs: Uint8Array[];
-    constructor(artifact: TArtifact, constructorArgs: TResolved['constructorInputs'], options: ContractOptions<TContractType>);
+    /**
+     * Retrieve the total BCH balance of the contract by summing the satoshis of all UTXOs at the
+     * contract's address.
+     *
+     * @returns The total balance in satoshis.
+     */
     getBalance(): Promise<bigint>;
+    /**
+     * Retrieve all UTXOs (confirmed and unconfirmed) locked at the contract's address.
+     *
+     * @returns A list of UTXOs spendable by this contract.
+     */
     getUtxos(): Promise<Utxo[]>;
+}
+declare class ContractInternal<TArtifact extends Artifact, TResolved extends ResolvedConstraint, TContractType extends ContractType> extends ContractBase {
+    artifact: TArtifact;
+    private options;
+    contractType: TContractType;
+    /**
+     * Call a contract function to spend a UTXO locked by this contract. Use as
+     * `contract.unlock.<functionName>(...args)` — the returned value is passed as the `unlocker`
+     * argument of `transactionBuilder.addInput(utxo, unlocker)`.
+     */
+    unlock: TResolved['unlock'];
+    /**
+     * Instantiate a contract from a compiled CashScript artifact.
+     *
+     * @param artifact - The compiled contract artifact produced by `cashc`.
+     * @param constructorArgs - Constructor arguments in the order defined in the contract source.
+     * @param options - Contract options including the network provider and (optional) address type.
+     * @throws If the artifact is missing required properties, was compiled with an unsupported
+     *   compiler version, or if the number or types of constructor arguments does not match the artifact.
+     */
+    constructor(artifact: TArtifact, constructorArgs: TResolved['constructorInputs'], options: ContractOptions<TContractType>);
     private createUnlocker;
 }
 export type Contract<TArtifact extends Artifact = Artifact, TResolved extends ResolvedConstraint = DefaultResolved<TArtifact>, TContractType extends ContractType = ContractType> = [TContractType] extends ['p2s'] ? Omit<ContractInternal<TArtifact, TResolved, TContractType>, 'address' | 'tokenAddress'> : ContractInternal<TArtifact, TResolved, TContractType>;

package/dist/Contract.js

@@ -4,8 +4,45 @@ import { encodeFunctionArgument, encodeConstructorArguments, } from './Argument.
 import { addressToLockScript, createUnlockingBytecode, createSighashPreimage, scriptToAddress, } from './utils.js';
 import SignatureTemplate from './SignatureTemplate.js';
 import semver from 'semver';
-class ContractInternal {
+// Non-generic base class holding the public API whose types do not depend on the Contract's
+// generic parameters. Declaring these members here (rather than on `ContractInternal<...>`) keeps
+// IDE hovers clean — tooltips show `ContractBase.name` instead of the fully resolved generic
+// `ContractInternal<{ readonly contractName: ...; readonly abi: ...; ... }, ...>.name`.
+class ContractBase {
+    /**
+     * Retrieve the total BCH balance of the contract by summing the satoshis of all UTXOs at the
+     * contract's address.
+     *
+     * @returns The total balance in satoshis.
+     */
+    async getBalance() {
+        const utxos = await this.getUtxos();
+        return utxos.reduce((acc, utxo) => acc + utxo.satoshis, 0n);
+    }
+    /**
+     * Retrieve all UTXOs (confirmed and unconfirmed) locked at the contract's address.
+     *
+     * @returns A list of UTXOs spendable by this contract.
+     */
+    async getUtxos() {
+        if (this.contractType === 'p2s') {
+            return this.provider.getUtxosForLockingBytecode(this.bytecode);
+        }
+        return this.provider.getUtxos(this.address);
+    }
+}
+class ContractInternal extends ContractBase {
+    /**
+     * Instantiate a contract from a compiled CashScript artifact.
+     *
+     * @param artifact - The compiled contract artifact produced by `cashc`.
+     * @param constructorArgs - Constructor arguments in the order defined in the contract source.
+     * @param options - Contract options including the network provider and (optional) address type.
+     * @throws If the artifact is missing required properties, was compiled with an unsupported
+     *   compiler version, or if the number or types of constructor arguments does not match the artifact.
+     */
     constructor(artifact, constructorArgs, options) {
+        super();
         this.artifact = artifact;
         this.options = options;
         this.provider = this.options.provider;
@@ -50,16 +87,6 @@ class ContractInternal {
         this.bytesize = calculateBytesize(contractBytecodeScript);
         this.opcount = countOpcodes(contractBytecodeScript);
     }
-    async getBalance() {
-        const utxos = await this.getUtxos();
-        return utxos.reduce((acc, utxo) => acc + utxo.satoshis, 0n);
-    }
-    async getUtxos() {
-        if (this.contractType === 'p2s') {
-            return this.provider.getUtxosForLockingBytecode(this.bytecode);
-        }
-        return this.provider.getUtxos(this.address);
-    }
     createUnlocker(abiFunction, selector) {
         return (...args) => {
             if (abiFunction.inputs.length !== args.length) {

package/dist/Errors.d.ts

@@ -11,9 +11,18 @@ export declare class OutputSatoshisTooSmallError extends Error {
 export declare class OutputTokenAmountTooSmallError extends Error {
     constructor(amount: bigint);
 }
+export declare class OutputTokenCategoryInvalidError extends Error {
+    constructor(category: string);
+}
+export declare class OutputTokenCommitmentInvalidError extends Error {
+    constructor(commitment: string);
+}
 export declare class TokensToNonTokenAddressError extends Error {
     constructor(address: string);
 }
+export declare class OutputAddressNetworkMismatchError extends Error {
+    constructor(address: string, expectedNetworkPrefix: string);
+}
 export declare class NoDebugInformationInArtifactError extends Error {
     constructor();
 }

package/dist/Errors.js

@@ -19,11 +19,26 @@ export class OutputTokenAmountTooSmallError extends Error {
         super(`Tried to add an output with ${amount} tokens, which is invalid`);
     }
 }
+export class OutputTokenCategoryInvalidError extends Error {
+    constructor(category) {
+        super(`Provided token category ${category} is not a hex string`);
+    }
+}
+export class OutputTokenCommitmentInvalidError extends Error {
+    constructor(commitment) {
+        super(`Provided token commitment ${commitment} is not a hex string`);
+    }
+}
 export class TokensToNonTokenAddressError extends Error {
     constructor(address) {
         super(`Tried to send tokens to an address without token support, ${address}.`);
     }
 }
+export class OutputAddressNetworkMismatchError extends Error {
+    constructor(address, expectedNetworkPrefix) {
+        super(`Tried to add an output to an address on the wrong network, ${address}. Expected network prefix: ${expectedNetworkPrefix}.`);
+    }
+}
 export class NoDebugInformationInArtifactError extends Error {
     constructor() {
         super('No debug information found in artifact, please recompile with cashc version 0.10.0 or newer.');

package/dist/SignatureTemplate.d.ts

@@ -1,14 +1,64 @@
 import { HashType, SignatureAlgorithm, P2PKHUnlocker } from './interfaces.js';
+/**
+ * A signature template used to sign CashScript transactions. Wraps a private key together with
+ * the desired `HashType` and `SignatureAlgorithm`, and is consumed by the `TransactionBuilder`
+ * whenever a `sig` argument is required or when unlocking a P2PKH input.
+ */
 export default class SignatureTemplate {
     private hashtype;
     private signatureAlgorithm;
+    /** The raw private key bytes used for signing. */
     privateKey: Uint8Array;
+    /**
+     * Create a new SignatureTemplate.
+     *
+     * @param signer - A 32-byte private key (Uint8Array), a WIF or hex-encoded private key string,
+     *   or any object exposing a `toWIF()` method (e.g. bitcore-lib or bitcoincashjs `ECPair`).
+     * @param hashtype - Sighash flags to use when signing. Defaults to `SIGHASH_ALL | SIGHASH_UTXOS`.
+     * @param signatureAlgorithm - The signature algorithm to use. Defaults to
+     *   `SignatureAlgorithm.SCHNORR`.
+     */
     constructor(signer: Keypair | Uint8Array | string, hashtype?: HashType, signatureAlgorithm?: SignatureAlgorithm);
+    /**
+     * Sign the provided sighash payload and return the signature concatenated with the hashtype
+     * byte, ready to be used as a transaction signature.
+     *
+     * @param payload - The 32-byte sighash to sign.
+     * @param bchForkId - Whether to include the BCH fork id flag in the appended hashtype byte.
+     *   Defaults to `true`.
+     * @returns The signature bytes followed by the hashtype byte.
+     */
     generateSignature(payload: Uint8Array, bchForkId?: boolean): Uint8Array;
+    /**
+     * Sign a raw 32-byte message hash using the template's private key and signature algorithm.
+     *
+     * @param payload - The 32-byte hash to sign.
+     * @returns The raw signature bytes (without an appended hashtype byte).
+     */
     signMessageHash(payload: Uint8Array): Uint8Array;
+    /**
+     * Get the sighash flags used by this template.
+     *
+     * @param bchForkId - Whether to OR in the BCH fork id flag. Defaults to `true`.
+     * @returns The combined hashtype byte.
+     */
     getHashType(bchForkId?: boolean): number;
+    /**
+     * @returns The signature algorithm (ECDSA or Schnorr) used by this template.
+     */
     getSignatureAlgorithm(): SignatureAlgorithm;
+    /**
+     * Derive the compressed public key that corresponds to the template's private key.
+     *
+     * @returns The 33-byte compressed public key.
+     */
     getPublicKey(): Uint8Array;
+    /**
+     * Build a P2PKH `Unlocker` for the address derived from this template's private key. The
+     * returned unlocker can be passed directly to `TransactionBuilder.addInput`.
+     *
+     * @returns An unlocker that signs the corresponding P2PKH UTXO.
+     */
     unlockP2PKH(): P2PKHUnlocker;
 }
 interface Keypair {

package/dist/SignatureTemplate.js

@@ -2,7 +2,21 @@ import { decodePrivateKeyWif, hexToBin, isHex, secp256k1, SigningSerializationFl
 import { hash256, scriptToBytecode } from '@cashscript/utils';
 import { HashType, SignatureAlgorithm, } from './interfaces.js';
 import { createSighashPreimage, publicKeyToP2PKHLockingBytecode } from './utils.js';
+/**
+ * A signature template used to sign CashScript transactions. Wraps a private key together with
+ * the desired `HashType` and `SignatureAlgorithm`, and is consumed by the `TransactionBuilder`
+ * whenever a `sig` argument is required or when unlocking a P2PKH input.
+ */
 export default class SignatureTemplate {
+    /**
+     * Create a new SignatureTemplate.
+     *
+     * @param signer - A 32-byte private key (Uint8Array), a WIF or hex-encoded private key string,
+     *   or any object exposing a `toWIF()` method (e.g. bitcore-lib or bitcoincashjs `ECPair`).
+     * @param hashtype - Sighash flags to use when signing. Defaults to `SIGHASH_ALL | SIGHASH_UTXOS`.
+     * @param signatureAlgorithm - The signature algorithm to use. Defaults to
+     *   `SignatureAlgorithm.SCHNORR`.
+     */
     constructor(signer, hashtype = HashType.SIGHASH_ALL | HashType.SIGHASH_UTXOS, signatureAlgorithm = SignatureAlgorithm.SCHNORR) {
         this.hashtype = hashtype;
         this.signatureAlgorithm = signatureAlgorithm;
@@ -23,25 +37,60 @@ export default class SignatureTemplate {
             this.privateKey = signer;
         }
     }
+    /**
+     * Sign the provided sighash payload and return the signature concatenated with the hashtype
+     * byte, ready to be used as a transaction signature.
+     *
+     * @param payload - The 32-byte sighash to sign.
+     * @param bchForkId - Whether to include the BCH fork id flag in the appended hashtype byte.
+     *   Defaults to `true`.
+     * @returns The signature bytes followed by the hashtype byte.
+     */
     generateSignature(payload, bchForkId) {
         const signature = this.signMessageHash(payload);
         return Uint8Array.from([...signature, this.getHashType(bchForkId)]);
     }
+    /**
+     * Sign a raw 32-byte message hash using the template's private key and signature algorithm.
+     *
+     * @param payload - The 32-byte hash to sign.
+     * @returns The raw signature bytes (without an appended hashtype byte).
+     */
     signMessageHash(payload) {
         const signature = this.signatureAlgorithm === SignatureAlgorithm.SCHNORR
             ? secp256k1.signMessageHashSchnorr(this.privateKey, payload)
             : secp256k1.signMessageHashDER(this.privateKey, payload);
         return signature;
     }
+    /**
+     * Get the sighash flags used by this template.
+     *
+     * @param bchForkId - Whether to OR in the BCH fork id flag. Defaults to `true`.
+     * @returns The combined hashtype byte.
+     */
     getHashType(bchForkId = true) {
         return bchForkId ? (this.hashtype | SigningSerializationFlag.forkId) : this.hashtype;
     }
+    /**
+     * @returns The signature algorithm (ECDSA or Schnorr) used by this template.
+     */
     getSignatureAlgorithm() {
         return this.signatureAlgorithm;
     }
+    /**
+     * Derive the compressed public key that corresponds to the template's private key.
+     *
+     * @returns The 33-byte compressed public key.
+     */
     getPublicKey() {
         return secp256k1.derivePublicKeyCompressed(this.privateKey);
     }
+    /**
+     * Build a P2PKH `Unlocker` for the address derived from this template's private key. The
+     * returned unlocker can be passed directly to `TransactionBuilder.addInput`.
+     *
+     * @returns An unlocker that signs the corresponding P2PKH UTXO.
+     */
     unlockP2PKH() {
         const publicKey = this.getPublicKey();
         const prevOutScript = publicKeyToP2PKHLockingBytecode(publicKey);

package/dist/TransactionBuilder.d.ts

@@ -1,39 +1,198 @@
-import { Transaction as LibauthTransaction, WalletTemplate } from '@bitauth/libauth';
-import { Unlocker, Output, TransactionDetails, UnlockableUtxo, Utxo, InputOptions, VmResourceUsage } from './interfaces.js';
+import { WalletTemplate } from '@bitauth/libauth';
+import { Unlocker, Output, TransactionDetails, UnlockableUtxo, Utxo, InputOptions, VmResourceUsage, BchChangeOutputOptions } from './interfaces.js';
 import { NetworkProvider } from './network/index.js';
 import { DebugResults } from './debugging.js';
 import { WcTransactionOptions } from './walletconnect-utils.js';
 import { WcTransactionObject } from './walletconnect-utils.js';
+/**
+ * Options accepted by the `TransactionBuilder` constructor.
+ */
 export interface TransactionBuilderOptions {
+    /** Network provider used to broadcast the transaction and fetch details after sending. */
     provider: NetworkProvider;
+    /** Optional absolute cap on the transaction fee. Build/send throws if the fee exceeds this value. */
     maximumFeeSatoshis?: bigint;
+    /** Optional cap on the transaction fee rate in sats/byte. Build/send throws if exceeded. */
     maximumFeeSatsPerByte?: number;
+    /** Allow fungible token inputs to exceed token outputs (implicit burn). Defaults to `false`. */
     allowImplicitFungibleTokenBurn?: boolean;
 }
+/**
+ * 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 declare class TransactionBuilder {
     provider: NetworkProvider;
     inputs: UnlockableUtxo[];
     outputs: Output[];
     locktime: number;
     options: TransactionBuilderOptions;
+    /**
+     * Create a new TransactionBuilder.
+     *
+     * @param options - Builder options, including the network provider and optional fee/burn limits.
+     */
     constructor(options: TransactionBuilderOptions);
+    /**
+     * 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: Utxo, unlocker: Unlocker, options?: InputOptions): this;
+    /**
+     * Add multiple UTXOs to the transaction that all share the same unlocker.
+     *
+     * @param utxos - The UTXOs to spend.
+     * @param unlocker - The shared unlocker used to unlock all provided UTXOs.
+     * @param options - Optional per-input options applied to every added input.
+     * @returns This builder for chaining.
+     * @throws If any UTXO is invalid.
+     */
     addInputs(utxos: Utxo[], unlocker: Unlocker, options?: InputOptions): this;
+    /**
+     * Add multiple UTXOs that each carry their own unlocker.
+     *
+     * @param utxos - UTXOs that have already been paired with their individual unlockers.
+     * @returns This builder for chaining.
+     * @throws If any UTXO is missing its unlocker.
+     */
     addInputs(utxos: UnlockableUtxo[]): 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: Output): this;
+    /**
+     * 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: Output[]): this;
+    /**
+     * 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: string[]): 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.
+     *
+     * @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.
+     */
+    addBchChangeOutputIfNeeded(changeOutputOptions: BchChangeOutputOptions): this;
+    /**
+     * Build the transaction (skipping fee and burn checks) and return its encoded byte length.
+     *
+     * @returns The size of the transaction in bytes.
+     */
+    getTransactionSize(): bigint;
+    /**
+     * 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: number): this;
     private checkMaxFee;
     private checkFungibleTokenBurn;
-    buildLibauthTransaction(): LibauthTransaction;
+    private buildLibauthTransaction;
+    /**
+     * 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(): string;
+    /**
+     * 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(): DebugResults;
+    /**
+     * 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?: boolean): Array<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(): string;
+    /**
+     * 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(): WalletTemplate;
+    /**
+     * Build and broadcast the transaction via the configured network provider. Before broadcasting,
+     * the transaction is evaluated locally (when all inputs use standard unlockers) so that failing
+     * require statements or VM errors surface with descriptive messages.
+     *
+     * @returns The decoded transaction details (including txid and raw hex).
+     * @throws A `FailedTransactionError` if the network rejects the transaction, or any of the
+     *   build / local evaluation errors (e.g. fee cap, implicit burn, failing require statement).
+     */
     send(): Promise<TransactionDetails>;
+    /**
+     * Build and broadcast the transaction, returning only the raw transaction hex string as retrieved
+     * from the network after broadcast.
+     *
+     * @param raw - Pass `true` to receive the raw transaction hex instead of decoded details.
+     * @returns The raw transaction hex as retrieved from the network after broadcast.
+     * @throws A `FailedTransactionError` if the network rejects the transaction, or any of the
+     *   build / local evaluation errors (e.g. fee cap, implicit burn, failing require statement).
+     */
     send(raw: true): Promise<string>;
     private getTxDetails;
+    /**
+     * 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?: WcTransactionOptions): WcTransactionObject;
 }