@arkade-os/sdk 0.4.15 → 0.4.17

package/dist/esm/extension/asset/metadata.js

@@ -12,11 +12,13 @@ export class Metadata {
         this.key = key;
         this.value = value;
     }
+    /** Create a metadata entry from raw key and value bytes. */
     static create(key, value) {
         const md = new Metadata(key, value);
         md.validate();
         return md;
     }
+    /** Decode metadata from its hex string form. */
     static fromString(s) {
         let buf;
         try {
@@ -27,6 +29,7 @@ export class Metadata {
         }
         return Metadata.fromBytes(buf);
     }
+    /** Decode metadata from its serialized bytes. */
     static fromBytes(buf) {
         if (!buf || buf.length === 0) {
             throw new Error("missing metadata");
@@ -34,11 +37,13 @@ export class Metadata {
         const reader = new BufferReader(buf);
         return Metadata.fromReader(reader);
     }
+    /** Serialize metadata to raw bytes. */
     serialize() {
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode metadata to a hex string. */
     toString() {
         return hex.encode(this.serialize());
     }
@@ -48,6 +53,7 @@ export class Metadata {
     get valueString() {
         return new TextDecoder().decode(this.value);
     }
+    /** Validate the metadata key and value. */
     validate() {
         if (this.key.length === 0) {
             throw new Error("missing metadata key");
@@ -56,6 +62,7 @@ export class Metadata {
             throw new Error("missing metadata value");
         }
     }
+    /** Decode metadata from a buffer reader. */
     static fromReader(reader) {
         let key;
         let value;
@@ -75,6 +82,7 @@ export class Metadata {
         md.validate();
         return md;
     }
+    /** Serialize metadata into an existing buffer writer. */
     serializeTo(writer) {
         writer.writeVarSlice(this.key);
         writer.writeVarSlice(this.value);
@@ -84,6 +92,7 @@ export class MetadataList {
     constructor(items) {
         this.items = items;
     }
+    /** Create a metadata list from its hex string form. */
     static fromString(s) {
         let buf;
         try {
@@ -94,6 +103,7 @@ export class MetadataList {
         }
         return MetadataList.fromBytes(buf);
     }
+    /** Decode a metadata list from its serialized bytes. */
     static fromBytes(buf) {
         if (!buf || buf.length === 0) {
             throw new Error("missing metadata list");
@@ -101,28 +111,33 @@ export class MetadataList {
         const reader = new BufferReader(buf);
         return MetadataList.fromReader(reader);
     }
+    /** Decode a metadata list from a buffer reader. */
     static fromReader(reader) {
         const count = Number(reader.readVarUint());
         const items = Array.from({ length: count }, () => Metadata.fromReader(reader));
         return new MetadataList(items);
     }
+    /** Serialize the metadata list into an existing buffer writer. */
     serializeTo(writer) {
         writer.writeVarUint(this.items.length);
         for (const item of this) {
             item.serializeTo(writer);
         }
     }
+    /** Serialize the metadata list to raw bytes. */
     serialize() {
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Iterate through metadata entries in insertion order. */
     [Symbol.iterator]() {
         return this.items[Symbol.iterator]();
     }
     get length() {
         return this.items.length;
     }
+    /** Compute the tagged Merkle root for the metadata list. */
     hash() {
         if (this.items.length === 0)
             throw new Error("missing metadata list");

package/dist/esm/extension/asset/packet.js

@@ -10,6 +10,7 @@ export class Packet {
     constructor(groups) {
         this.groups = groups;
     }
+    /** Create a validated asset packet from a list of asset groups. */
     static create(groups) {
         const p = new Packet(groups);
         p.validate();
@@ -43,13 +44,14 @@ export class Packet {
     type() {
         return Packet.PACKET_TYPE;
     }
+    /** Convert the packet into the batch-leaf form for a specific intent transaction id. */
     leafTxPacket(intentTxid) {
         const leafGroups = this.groups.map((group) => group.toBatchLeafAssetGroup(intentTxid));
         return new Packet(leafGroups);
     }
     /**
      * serialize encodes the packet as raw bytes (varint group count + group data).
-     * Does NOT include OP_RETURN, ARK magic, or TLV type/length — those are
+     * Does NOT include OP_RETURN, Arkade magic bytes (`ARK`), or TLV type/length; those are
      * added by the Extension module.
      */
     serialize() {
@@ -69,6 +71,7 @@ export class Packet {
     toString() {
         return hex.encode(this.serialize());
     }
+    /** Validate packet structure and cross-group references. */
     validate() {
         if (this.groups.length === 0) {
             throw new Error("missing assets");

package/dist/esm/extension/index.js

@@ -7,7 +7,7 @@ import { UnknownPacket } from './packet.js';
 export { UnknownPacket } from './packet.js';
 /**
  * ArkadeMagic is the 3-byte magic prefix ("ARK") that identifies an OP_RETURN
- * output as an ark extension blob.
+ * output as an Arkade extension blob.
  */
 export const ARKADE_MAGIC = new Uint8Array([0x41, 0x52, 0x4b]); // "ARK"
 /**

package/dist/esm/forfeit.js

@@ -1,5 +1,12 @@
 import { Transaction } from './utils/transaction.js';
 import { P2A } from './utils/anchor.js';
+/**
+ * Build a forfeit transaction that spends the provided inputs to a single forfeit output.
+ *
+ * @param inputs - Inputs to include in the forfeit transaction
+ * @param forfeitPkScript - ScriptPubKey for the forfeit output
+ * @param txLocktime - Optional locktime to apply to the transaction
+ */
 export function buildForfeitTx(inputs, forfeitPkScript, txLocktime) {
     let amount = 0n;
     for (const input of inputs) {
@@ -13,6 +20,13 @@ export function buildForfeitTx(inputs, forfeitPkScript, txLocktime) {
         amount,
     }, txLocktime);
 }
+/**
+ * Build a forfeit transaction using an explicit output descriptor (used for delegated renewals)
+ *
+ * @param inputs - Inputs to include in the forfeit transaction
+ * @param output - Primary transaction output
+ * @param txLocktime - Optional locktime to apply to the transaction
+ */
 export function buildForfeitTxWithOutput(inputs, output, txLocktime) {
     const tx = new Transaction({
         version: 3,

package/dist/esm/identity/seedIdentity.js

@@ -41,7 +41,7 @@ function buildDescriptor(seed, isMainnet) {
  * format is HD-ready, allowing future support for multiple addresses
  * and change derivation.
  *
- * Prefer this (or {@link MnemonicIdentity}) over `SingleKey` for new
+ * Prefer this (or @see MnemonicIdentity) over `SingleKey` for new
  * integrations — `SingleKey` exists for backward compatibility with
  * raw nsec-style keys.
  *
@@ -157,7 +157,7 @@ export class SeedIdentity {
  *
  * This is the most user-friendly identity type — recommended for wallet
  * applications where users manage their own backup phrase. Extends
- * {@link SeedIdentity} with mnemonic validation and optional passphrase
+ * @see SeedIdentity with mnemonic validation and optional passphrase
  * support.
  *
  * @example

package/dist/esm/identity/singleKey.js

@@ -26,12 +26,15 @@ export class SingleKey {
     constructor(key) {
         this.key = key || randomPrivateKeyBytes();
     }
+    /** Create a signing identity from raw private key bytes. */
     static fromPrivateKey(privateKey) {
         return new SingleKey(privateKey);
     }
+    /** Create a signing identity from a hex-encoded private key. */
     static fromHex(privateKeyHex) {
         return new SingleKey(hex.decode(privateKeyHex));
     }
+    /** Create a signing identity with a freshly generated random private key. */
     static fromRandomBytes() {
         return new SingleKey(randomPrivateKeyBytes());
     }
@@ -88,6 +91,7 @@ export class SingleKey {
     }
 }
 export class ReadonlySingleKey {
+    /** Create a readonly identity from a compressed public key. */
     constructor(publicKey) {
         this.publicKey = publicKey;
         if (publicKey.length !== 33) {

package/dist/esm/index.js

@@ -55,7 +55,7 @@ TxType, IndexerTxType, ChainTxType, SettlementEventType,
 setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEOUTS, 
 // Tapscript
 decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, 
-// Ark PSBT fields
+// Arkade PSBT fields
 ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, 
 // Utils
 buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, 

package/dist/esm/intent/index.js

@@ -8,10 +8,11 @@ import { getSequence, VtxoScript } from '../script/base.js';
  * Intent proof implementation for Bitcoin message signing.
  *
  * Intent proof defines a standard for signing Bitcoin messages as well as proving
- * ownership of coins. This namespace provides utilities for creating and
- * validating Intent proof.
+ * ownership of outputs.
  *
- * it is greatly inspired by BIP322.
+ * This namespace provides utilities for creating and validating Intent proof.
+ *
+ * It is greatly inspired by BIP322.
  * @see https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
  *
  * @example
@@ -33,11 +34,11 @@ export var Intent;
      * Creates a new Intent proof unsigned transaction.
      *
      * This function constructs a special transaction that can be signed to prove
-     * ownership of VTXOs and UTXOs. The proof includes the message to be
+     * ownership of onchain and virtual outputs. The proof includes the message to be
      * signed and the inputs/outputs that demonstrate ownership.
      *
      * @param message - The Intent message to be signed, either raw string of Message object
-     * @param inputs - Array of transaction inputs to prove ownership of
+     * @param ins - Array of transaction inputs to prove ownership of
      * @param outputs - Optional array of transaction outputs
      * @returns An unsigned Intent proof transaction
      */
@@ -52,12 +53,18 @@ export var Intent;
             throw new Error("invalid inputs");
         if (!validateOutputs(outputs))
             throw new Error("invalid outputs");
-        // create the initial transaction to spend
+        // Create the initial transaction to spend.
         const toSpend = craftToSpendTx(message, inputs[0].witnessUtxo.script);
-        // create the transaction to sign
+        // Create the transaction to sign.
         return craftToSignTx(toSpend, inputs, outputs);
     }
     Intent.create = create;
+    /**
+     * Compute the fee paid by an intent proof transaction.
+     *
+     * @param proof - Intent proof transaction
+     * @returns The fee in satoshis
+     */
     function fee(proof) {
         let sumOfInputs = 0n;
         for (let i = 0; i < proof.inputsLength; i++) {
@@ -79,6 +86,12 @@ export var Intent;
         return Number(sumOfInputs - sumOfOutputs);
     }
     Intent.fee = fee;
+    /**
+     * Serialize an intent message to the canonical JSON string used for signing.
+     *
+     * @param message - Intent message payload
+     * @returns Canonical string form of the message
+     */
     function encodeMessage(message) {
         switch (message.type) {
             case "register":
@@ -139,7 +152,7 @@ function validateOutputs(outputs) {
  *
  * @param message - The message to embed
  * @param pkScript - The scriptPubKey of the signer's address
- * @param tag - Tagged-hash tag (defaults to the Ark intent proof tag)
+ * @param tag - Tagged-hash tag (defaults to the Arkade intent proof tag)
  */
 export function craftToSpendTx(message, pkScript, tag = TAG_INTENT_PROOF) {
     const messageHash = hashMessage(message, tag);
@@ -165,12 +178,15 @@ export function craftToSpendTx(message, pkScript, tag = TAG_INTENT_PROOF) {
 // craftToSignTx creates the transaction that will be signed for the proof
 function craftToSignTx(toSpend, inputs, outputs) {
     const firstInput = inputs[0];
-    const lockTime = inputs
-        .map((input) => input.sequence || 0)
-        .reduce((a, b) => Math.max(a, b), 0);
+    // Proof tx is never broadcast onchain — toSpend references a zero-hash
+    // outpoint (see BIP-322). The tx exists only as a sighash commitment
+    // the server verifies signatures against; nLockTime and nSequence carry
+    // no consensus meaning here, they only need to match between signer and
+    // verifier. Use lockTime = 0 (BIP-322 convention) and leave each input's
+    // nSequence untouched.
     const tx = new Transaction({
         version: 2,
-        lockTime,
+        lockTime: 0,
     });
     // add the first "toSpend" input
     tx.addInput({

package/dist/esm/providers/ark.js

@@ -15,11 +15,12 @@ export var SettlementEventType;
     SettlementEventType["StreamStarted"] = "stream_started";
 })(SettlementEventType || (SettlementEventType = {}));
 /**
- * REST-based Ark provider implementation.
+ * REST-based Arkade provider implementation.
+ *
  * @see https://buf.build/arkade-os/arkd/docs/main:ark.v1#ark.v1.ArkService
  * @example
  * ```typescript
- * const provider = new RestArkProvider('https://ark.example.com');
+ * const provider = new RestArkProvider('https://arkade.computer');
  * const info = await provider.getInfo();
  * ```
  */

package/dist/esm/providers/delegator.js

@@ -1,6 +1,6 @@
 import { Intent } from '../intent/index.js';
 /**
- * REST-based Delegator provider implementation.
+ * REST-based delegation provider implementation.
  * @example
  * ```typescript
  * const provider = new RestDelegatorProvider('https://delegator.example.com');
@@ -9,9 +9,22 @@ import { Intent } from '../intent/index.js';
  * ```
  */
 export class RestDelegatorProvider {
+    /**
+     * Create a REST delegation provider targeting the given base URL.
+     *
+     * @param url - Base URL of the delegation service
+     */
     constructor(url) {
         this.url = url;
     }
+    /**
+     * Submit a delegation request to the remote delegation service.
+     *
+     * @param intent - Signed register intent to delegate
+     * @param forfeitTxs - Forfeit transactions associated with the delegation request
+     * @param options - Optional delegate behavior flags
+     * @throws Error if the remote service rejects the request
+     */
     async delegate(intent, forfeitTxs, options) {
         const url = `${this.url}/v1/delegate`;
         const response = await fetch(url, {
@@ -33,6 +46,12 @@ export class RestDelegatorProvider {
             throw new Error(`Failed to delegate: ${errorText}`);
         }
     }
+    /**
+     * Fetch delegate metadata exposed by the remote delegation service.
+     *
+     * @returns Delegate identity and fee information
+     * @throws Error if the remote service returns invalid data
+     */
     async getDelegateInfo() {
         const url = `${this.url}/v1/delegator/info`;
         const response = await fetch(url);

package/dist/esm/providers/expoArk.js

@@ -1,7 +1,7 @@
 import { RestArkProvider, isFetchTimeoutError, } from './ark.js';
 import { getExpoFetch, sseStreamIterator } from './expoUtils.js';
 /**
- * Expo-compatible Ark provider implementation using expo/fetch for SSE support.
+ * Expo-compatible Arkade provider implementation using expo/fetch for SSE support.
  * This provider works specifically in React Native/Expo environments where
  * standard EventSource is not available but expo/fetch provides SSE capabilities.
  *
@@ -9,7 +9,7 @@ import { getExpoFetch, sseStreamIterator } from './expoUtils.js';
  * ```typescript
  * import { ExpoArkProvider } from '@arkade-os/sdk/providers/expo';
  *
- * const provider = new ExpoArkProvider('https://ark.example.com');
+ * const provider = new ExpoArkProvider('https://arkade.computer');
  * const info = await provider.getInfo();
  * ```
  */

package/dist/esm/providers/indexer.js

@@ -17,11 +17,11 @@ export var ChainTxType;
     ChainTxType["CHECKPOINT"] = "INDEXER_CHAINED_TX_TYPE_CHECKPOINT";
 })(ChainTxType || (ChainTxType = {}));
 /**
- * REST-based Indexer provider implementation.
+ * REST-based indexer provider implementation.
  * @see https://buf.build/arkade-os/arkd/docs/main:ark.v1#ark.v1.IndexerService
  * @example
  * ```typescript
- * const provider = new RestIndexerProvider('https://ark.indexer.example.com');
+ * const provider = new RestIndexerProvider('https://arkade.computer');
  * const commitmentTx = await provider.getCommitmentTx("6686af8f3be3517880821f62e6c3d749b9d6713736a1d8e229a55daa659446b2");
  * ```
  */

package/dist/esm/providers/onchain.js

@@ -10,11 +10,12 @@ export const ESPLORA_URL = {
 };
 /**
  * Implementation of the onchain provider interface for esplora REST API.
+ *
  * @see https://mempool.space/docs/api/rest
  * @example
  * ```typescript
  * const provider = new EsploraProvider("https://mempool.space/api");
- * const utxos = await provider.getCoins("bcrt1q679zsd45msawvr7782r0twvmukns3drlstjt77");
+ * const outputs = await provider.getCoins("bcrt1q679zsd45msawvr7782r0twvmukns3drlstjt77");
  * ```
  */
 export class EsploraProvider {

package/dist/esm/repositories/realm/schemas.js

@@ -1,5 +1,5 @@
 /**
- * Realm object schemas for the Ark wallet.
+ * Realm object schemas for the Arkade wallet.
  *
  * All schema names are prefixed with "Ark" to avoid collisions with
  * other Realm schemas in the consuming application.
@@ -93,7 +93,7 @@ export const ArkContractSchema = {
     },
 };
 /**
- * All Realm schemas needed by the Ark wallet repositories.
+ * All Realm schemas needed by the Arkade wallet repositories.
  * Pass this array to your Realm configuration's `schema` property.
  */
 export const ArkRealmSchemas = [

package/dist/esm/repositories/realm/types.js

@@ -1,6 +1,6 @@
 /**
  * Minimal interface for the subset of the Realm API used by the
- * Ark repositories.  Consumers pass their real Realm instance and
+ * Arkade repositories. Consumers pass their real Realm instance and
  * the compiler validates it satisfies this shape.
  */
 export {};

package/dist/esm/script/address.js

@@ -1,13 +1,20 @@
 import { bech32m } from "@scure/base";
 import { Script } from "@scure/btc-signer/script.js";
 /**
- * ArkAddress allows to create and decode bech32m encoded ark address.
- * An ark address is composed of:
+ * ArkAddress allows creating and decoding bech32m-encoded Arkade addresses.
+ *
+ * An Arkade address is composed of:
  * - a human readable prefix (hrp)
  * - a version byte (1 byte)
  * - a server public key (32 bytes)
  * - a vtxo taproot public key (32 bytes)
  *
+ * @remarks
+ * This is an Arkade-specific address format.
+ * It is distinct from the Taproot onchain address returned by `VtxoScript.onchainAddress`.
+ *
+ * @see VtxoScript
+ *
  * @example
  * ```typescript
  * const address = new ArkAddress(
@@ -23,6 +30,16 @@ import { Script } from "@scure/btc-signer/script.js";
  * ```
  */
 export class ArkAddress {
+    /**
+     * Create an Arkade address from its server key, vtxo taproot public key, and prefix.
+     *
+     * @param serverPubKey - 32-byte Arkade server public key
+     * @param vtxoTaprootKey - 32-byte tweaked vtxo taproot public key
+     * @param hrp - Bech32 human-readable prefix
+     * @param version - Address version byte
+     * @defaultValue `version = 0`
+     * @throws Error if either public key is not 32 bytes long
+     */
     constructor(serverPubKey, vtxoTaprootKey, hrp, version = 0) {
         this.serverPubKey = serverPubKey;
         this.vtxoTaprootKey = vtxoTaprootKey;
@@ -37,13 +54,21 @@ export class ArkAddress {
                 vtxoTaprootKey.length);
         }
     }
+    /**
+     * Decode an Arkade address from its bech32m string form.
+     *
+     * @param address - Bech32m-encoded Arkade address
+     * @returns Decoded Arkade address
+     * @throws Error if the address is malformed or has an invalid payload length
+     * @see encode
+     */
     static decode(address) {
         const decoded = bech32m.decodeUnsafe(address, 1023);
         if (!decoded) {
             throw new Error("Invalid address");
         }
         const data = new Uint8Array(bech32m.fromWords(decoded.words));
-        // First the version byte, then 32 bytes server pubkey, then 32 bytes vtxo taproot pubkey
+        // First the version byte, then 32 bytes server pubkey, then 32 bytes vtxo taproot public key.
         if (data.length !== 1 + 32 + 32) {
             throw new Error("Invalid data length, expected 65 bytes, got " + data.length);
         }
@@ -52,8 +77,14 @@ export class ArkAddress {
         const vtxoTaprootPubKey = data.slice(33, 65);
         return new ArkAddress(serverPubKey, vtxoTaprootPubKey, decoded.prefix, version);
     }
+    /**
+     * Encode the address to its bech32m string form.
+     *
+     * @returns Bech32m-encoded Arkade address
+     * @see decode
+     */
     encode() {
-        // Combine version byte, server pubkey, and vtxo taproot pubkey
+        // Combine version byte, server pubkey, and vtxo taproot public key.
         const data = new Uint8Array(1 + 32 + 32);
         data[0] = this.version;
         data.set(this.serverPubKey, 1);
@@ -61,11 +92,11 @@ export class ArkAddress {
         const words = bech32m.toWords(data);
         return bech32m.encode(this.hrp, words, 1023);
     }
-    // pkScript is the script that should be used to send non-dust funds to the address
+    /** ScriptPubKey used to send non-dust funds to the address. */
     get pkScript() {
         return Script.encode(["OP_1", this.vtxoTaprootKey]);
     }
-    // subdustPkScript is the script that should be used to send sub-dust funds to the address
+    /** ScriptPubKey used to send sub-dust funds to the address. */
     get subdustPkScript() {
         return Script.encode(["RETURN", this.vtxoTaprootKey]);
     }

package/dist/esm/script/base.js

@@ -11,18 +11,35 @@ export function scriptFromTapLeafScript(leaf) {
 }
 /**
  * VtxoScript is a script that contains a list of tapleaf scripts.
- * It is used to create vtxo scripts.
+ * It is used to create virtual output scripts.
+ *
+ * @see ArkAddress
  *
  * @example
  * ```typescript
  * const vtxoScript = new VtxoScript([new Uint8Array(32), new Uint8Array(32)]);
+ * ```
  */
 export class VtxoScript {
+    /**
+     * Decode a virtual output script from an encoded TapTree.
+     *
+     * @param tapTree - Encoded TapTree bytes
+     * @returns Decoded virtual output script
+     * @throws Error if the TapTree cannot be decoded into a valid script set
+     * @see encode
+     */
     static decode(tapTree) {
         const leaves = TapTreeCoder.decode(tapTree);
         const scripts = leaves.map((leaf) => leaf.script);
         return new VtxoScript(scripts);
     }
+    /**
+     * Create a virtual output script from its tapleaf scripts.
+     *
+     * @param scripts - Raw tapscript bytes for each leaf
+     * @throws Error if the provided leaves cannot produce a valid Taproot tree
+     */
     constructor(scripts) {
         this.scripts = scripts;
         // reverse the scripts if the number of scripts is odd
@@ -43,6 +60,12 @@ export class VtxoScript {
         this.leaves = payment.tapLeafScript;
         this.tweakedPublicKey = payment.tweakedPubkey;
     }
+    /**
+     * Encode the virtual output script to a TapTree byte representation.
+     *
+     * @returns Encoded TapTree bytes
+     * @see decode
+     */
     encode() {
         const tapTree = TapTreeCoder.encode(this.scripts.map((script) => ({
             depth: 1,
@@ -51,18 +74,40 @@ export class VtxoScript {
         })));
         return tapTree;
     }
+    /**
+     * Build the Arkade address corresponding to this virtual output script.
+     *
+     * @param prefix - Bech32 human-readable prefix
+     * @param serverPubKey - 32-byte Arkade server public key
+     * @returns Arkade address for this script
+     * @see ArkAddress
+     */
     address(prefix, serverPubKey) {
         return new ArkAddress(serverPubKey, this.tweakedPublicKey, prefix);
     }
     get pkScript() {
         return Script.encode(["OP_1", this.tweakedPublicKey]);
     }
+    /**
+     * Build the Taproot onchain address corresponding to this virtual output script.
+     *
+     * @param network - Bitcoin network descriptor
+     * @returns Taproot onchain address
+     * @see address
+     */
     onchainAddress(network) {
         return Address(network).encode({
             type: "tr",
             pubkey: this.tweakedPublicKey,
         });
     }
+    /**
+     * Look up a tapleaf script by its hex-encoded tapscript body.
+     *
+     * @param scriptHex - Hex-encoded tapscript body without the leaf version byte
+     * @returns Matching tapleaf script
+     * @throws Error if no matching leaf exists
+     */
     findLeaf(scriptHex) {
         const leaf = this.leaves.find((leaf) => hex.encode(scriptFromTapLeafScript(leaf)) === scriptHex);
         if (!leaf) {
@@ -70,6 +115,12 @@ export class VtxoScript {
         }
         return leaf;
     }
+    /**
+     * Return all unilateral exit paths embedded in the virtual output script.
+     *
+     * @returns CSV-based exit paths found in the leaves
+     * @see getSequence
+     */
     exitPaths() {
         const paths = [];
         for (const leaf of this.leaves) {
@@ -91,6 +142,24 @@ export class VtxoScript {
         return paths;
     }
 }
+/**
+ * Extract the timelock value encoded in a timelocked tapleaf, if any.
+ *
+ * The return value is unit-ambiguous: for a CSV leaf it is a BIP-68
+ * nSequence (relative timelock); for a CLTV leaf it is an absolute
+ * nLockTime. Callers must know which leaf shape they are inspecting to
+ * interpret the number correctly, and must not copy a CSV result into
+ * `Transaction.lockTime` (or vice versa).
+ *
+ * @param tapLeafScript - Tapleaf script to inspect
+ * @returns The encoded timelock value, or `undefined` when neither a CSV
+ *          nor CLTV path is present
+ * @see VtxoScript.exitPaths
+ */
+// TODO(next-major): return a discriminated union
+// (`{ kind: "relative", nSequence } | { kind: "absolute", lockTime }`)
+// so callers can't conflate the two. Deferred because changing the
+// return type is a breaking change.
 export function getSequence(tapLeafScript) {
     let sequence = undefined;
     try {