@arkade-os/sdk 0.4.14 → 0.4.16

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

@@ -7,7 +7,7 @@ import { ContractFilter } from "../repositories";
  */
 export type ContractState = "active" | "inactive";
 /**
- * Represents a contract that can receive and manage VTXOs.
+ * Represents a contract that can receive and manage virtual outputs.
  *
  * A contract is defined by its type and parameters, which together
  * determine the VtxoScript (spending paths). The wallet's default
@@ -29,14 +29,14 @@ export type ContractState = "active" | "inactive";
  *     // ... timelocks
  *   },
  *   script: "5120...",
- *   address: "tark1...",
+ *   address: "ark1q...",
  *   state: "active",
  *   createdAt: 1704067200000,
  * };
  * ```
  */
 export interface Contract {
-    /** Human-readable label for display purposes */
+    /** Human-readable label for display purposes. */
     label?: string;
     /**
      * Contract type identifier.
@@ -50,15 +50,15 @@ export interface Contract {
      * The ContractHandler for this type knows how to interpret these.
      */
     params: Record<string, string>;
-    /** The pkScript hex - unique identifier and primary key for contracts */
+    /** The pkScript hex, used as the unique identifier and primary key for contracts. */
     script: string;
-    /** The address derived from the script */
+    /** Address derived from the contract script. */
     address: string;
-    /** Current state of the contract */
+    /** Current state of the contract. */
     state: ContractState;
-    /** Unix timestamp (ms) when this contract was created */
+    /** Unix timestamp in milliseconds when this contract was created. */
     createdAt: number;
-    /** Unix timestamp (ms) when this contract expires (optional) */
+    /** Unix timestamp in milliseconds when this contract expires. */
     expiresAt?: number;
     /**
      * Optional metadata for external integrations.
@@ -66,50 +66,54 @@ export interface Contract {
     metadata?: Record<string, unknown>;
 }
 /**
- * A VTXO that has been associated with a specific contract.
+ * A virtual output that has been associated with a specific contract.
  */
 export interface ContractVtxo extends ExtendedVirtualCoin {
-    /** The contract script this VTXO belongs to */
+    /** The contract script this virtual output belongs to. */
     contractScript: string;
 }
 /**
- * Result of path selection - which tapleaf to use and extra witness data.
+ * Result of path selection, including the tapleaf to use and any extra witness data.
  */
 export interface PathSelection {
-    /** The tapleaf script to use for spending */
+    /** Tapleaf script to use for spending. */
     leaf: TapLeafScript;
-    /** Additional witness elements (e.g., preimage for HTLC) */
+    /** Additional witness elements, for example a preimage for HTLC-like paths. */
     extraWitness?: Bytes[];
-    /** Sequence number override (for CSV timelocks) */
+    /**
+     * nSequence for the spending input, BIP-68 encoded when the leaf
+     * uses CSV. Decode with `sequenceToTimelock`; do NOT use as an
+     * absolute `Transaction.lockTime`.
+     */
     sequence?: number;
 }
 /**
  * Context for path selection decisions.
  */
 export interface PathContext {
-    /** Is collaborative spending available (server cooperation)? */
+    /** Whether collaborative spending is available through server cooperation. */
     collaborative: boolean;
-    /** Current time in milliseconds */
+    /** Current time in milliseconds. */
     currentTime: number;
-    /** Current block height (optional) */
+    /** Current block height, when known. */
     blockHeight?: number;
     /**
-     * Wallet's public key (x-only, 32 bytes hex).
-     * Used by handlers to determine wallet's role in multi-party contracts.
+     * Wallet public key encoded as 32-byte x-only hex.
+     * Used by handlers to determine the wallet's role in multi-party contracts.
      */
     walletPubKey?: string;
     /**
-     * Explicit role override (for multi-party contracts like VHTLC).
-     * If not provided, handler may derive role from walletPubKey.
+     * Explicit role override for multi-party contracts such as VHTLC.
+     * If not provided, the handler may derive the role from `walletPubKey`.
      */
     role?: string;
-    /** The specific VTXO being evaluated */
+    /** The specific virtual output being evaluated. */
     vtxo?: VirtualCoin;
 }
 /**
  * Handler for a specific contract type.
  *
- * Each contract type (default, vhtlc, etc.) has a handler that knows how to:
+ * Each contract type (`default`, `vhtlc`, etc.) has a handler that knows how to:
  * 1. Create the VtxoScript from parameters
  * 2. Serialize/deserialize parameters for storage
  * 3. Select the appropriate spending path based on context
@@ -134,14 +138,20 @@ export interface PathContext {
  * ```
  */
 export interface ContractHandler<P = Record<string, unknown>, S extends VtxoScript = VtxoScript> {
-    /** The contract type this handler manages */
+    /** Contract type managed by this handler. */
     readonly type: string;
     /**
      * Create the VtxoScript from serialized parameters.
+     *
+     * @param params - Serialized contract parameters
+     * @returns Contract script instance
      */
     createScript(params: Record<string, string>): S;
     /**
      * Serialize typed parameters to string key-value pairs.
+     *
+     * @param params - Typed contract parameters
+     * @returns Serialized key-value representation
      */
     serializeParams(params: P): Record<string, string>;
     /**
@@ -203,7 +213,7 @@ export type ContractEventCallback = (event: ContractEvent) => void;
  */
 export type GetContractsFilter = ContractFilter;
 /**
- * Contract with its VTXOs included.
+ * Contract with its virtual outputs included.
  */
 export type ContractWithVtxos = {
     contract: Contract;
@@ -217,6 +227,6 @@ export interface ContractBalance {
     total: number;
     /** Spendable balance in satoshis */
     spendable: number;
-    /** Number of VTXOs in this contract */
+    /** Number of virtual outputs in this contract */
     vtxoCount: number;
 }

package/dist/types/extension/asset/assetGroup.d.ts

@@ -5,7 +5,22 @@ import { AssetOutput } from "./assetOutput";
 import { Metadata } from "./metadata";
 import { BufferReader, BufferWriter } from "./utils";
 /**
- * An asset group contains inputs/outputs and all data related to a given asset id.
+ * An asset group contains inputs, outputs, and all data related to a given asset id.
+ *
+ * @see Packet
+ * @see AssetId
+ * @see AssetRef
+ *
+ * @example
+ * ```typescript
+ * const group = AssetGroup.create(
+ *   null,                              // asset ID: null for new issuance
+ *   null,                              // control asset ID: null when reissuance not needed
+ *   [],                                // asset inputs: empty for new issuance
+ *   [AssetOutput.create(0, 1000)],     // asset outputs: 1000 units at vout index 0
+ *   []                                 // metadata: can be empty
+ * )
+ * ```
  */
 export declare class AssetGroup {
     readonly assetId: AssetId | null;
@@ -13,16 +28,92 @@ export declare class AssetGroup {
     readonly inputs: AssetInput[];
     readonly outputs: AssetOutput[];
     private readonly metadataList;
+    /** @see create */
     constructor(assetId: AssetId | null, controlAsset: AssetRef | null, inputs: AssetInput[], outputs: AssetOutput[], metadata: Metadata[]);
+    /**
+     * Create and validate an asset group.
+     *
+     * @param assetId - Asset id for this group, or `null` for fresh issuance
+     * @param controlAsset - Optional control asset reference for (re) issuance
+     * @param inputs - Asset inputs in the group
+     * @param outputs - Asset outputs in the group
+     * @param metadata - Metadata entries associated with the group
+     * @returns A validated asset group
+     * @throws Error if the group fails validation
+     * @see validate
+     */
     static create(assetId: AssetId | null, controlAsset: AssetRef | null, inputs: AssetInput[], outputs: AssetOutput[], metadata: Metadata[]): AssetGroup;
+    /**
+     * Decode an asset group from its hex string form.
+     *
+     * @param s - Hex-encoded asset group
+     * @returns Decoded asset group
+     * @throws Error if the string is not valid hex or does not encode a valid asset group
+     * @see toString
+     */
     static fromString(s: string): AssetGroup;
+    /**
+     * Decode an asset group from its serialized bytes.
+     *
+     * @param buf - Serialized asset group bytes
+     * @returns Decoded asset group
+     * @throws Error if the buffer is empty or malformed
+     */
     static fromBytes(buf: Uint8Array): AssetGroup;
+    /**
+     * Return true when the group represents an issuance.
+     *
+     * @returns `true` when the group has no asset id
+     */
     isIssuance(): boolean;
+    /**
+     * Return true when the group represents a reissuance.
+     *
+     * @returns `true` when the group has an asset id and outputs exceed local inputs
+     * @remarks
+     * Only local inputs contribute to the comparison; intent-backed inputs contribute `0` here.
+     */
     isReissuance(): boolean;
+    /**
+     * Serialize the asset group to raw bytes.
+     *
+     * @returns Serialized asset group bytes
+     * @see fromBytes
+     */
     serialize(): Uint8Array;
+    /**
+     * Validate the asset group and its child structures.
+     *
+     * @throws Error if the group is empty or violates issuance invariants
+     */
     validate(): void;
+    /**
+     * Convert the group into its batch-leaf representation for the given intent txid.
+     *
+     * @param intentTxid - Intent transaction id used to build the leaf input reference
+     * @returns Batch-leaf asset group
+     * @see AssetInput.createIntent
+     */
     toBatchLeafAssetGroup(intentTxid: Uint8Array): AssetGroup;
+    /**
+     * Encode the asset group to a hex string.
+     *
+     * @returns Hex-encoded asset group
+     * @see fromString
+     */
     toString(): string;
+    /**
+     * Decode an asset group from a binary reader.
+     *
+     * @param reader - Reader positioned at an asset group
+     * @returns Decoded asset group
+     * @throws Error if the encoded group is malformed
+     */
     static fromReader(reader: BufferReader): AssetGroup;
+    /**
+     * Serialize the asset group into an existing binary writer.
+     *
+     * @param writer - Writer to append the asset group to
+     */
     serializeTo(writer: BufferWriter): void;
 }

package/dist/types/extension/asset/assetId.d.ts

@@ -1,19 +1,83 @@
 import { BufferReader, BufferWriter } from "./utils";
 /**
- * AssetId represents the id of an asset.
- * @param txid - the genesis transaction id (decoded from hex)
- * @param groupIndex - the asset group index in the genesis transaction
+ * AssetId identifies a specific asset.
+ *
+ * @remarks
+ * Asset ids are derived from the genesis transaction id plus the asset group index.
+ *
+ * @see AssetRef
+ *
+ * @example
+ * ```typescript
+ * const assetId = AssetId.create('00'.repeat(32), 0)
+ * const encoded = assetId.toString()
+ * const decoded = AssetId.fromString(encoded)
+ * ```
  */
 export declare class AssetId {
     readonly txid: Uint8Array;
     readonly groupIndex: number;
     private constructor();
+    /**
+     * Create an asset id from a genesis transaction id and group index.
+     *
+     * @param txid - Hex-encoded genesis transaction id
+     * @param groupIndex - Asset group index within the genesis transaction
+     * @returns A validated asset id
+     * @throws Error if the txid is missing, malformed, or not 32 bytes long
+     * @see fromString
+     */
     static create(txid: string, groupIndex: number): AssetId;
+    /**
+     * Decode an asset id from its hex string representation.
+     *
+     * @param s - Hex-encoded asset id
+     * @returns Decoded asset id
+     * @throws Error if the string is not valid hex or does not encode a valid asset id
+     * @see toString
+     */
     static fromString(s: string): AssetId;
+    /**
+     * Decode an asset id from its serialized bytes.
+     *
+     * @param buf - Serialized asset id bytes
+     * @returns Decoded asset id
+     * @throws Error if the buffer length is invalid
+     */
     static fromBytes(buf: Uint8Array): AssetId;
+    /**
+     * Serialize the asset id to raw bytes.
+     *
+     * @returns Serialized asset id bytes
+     * @see fromBytes
+     */
     serialize(): Uint8Array;
+    /**
+     * Encode the asset id to a hex string.
+     *
+     * @returns Hex-encoded asset id
+     * @see fromString
+     */
     toString(): string;
+    /**
+     * Validate the asset id fields.
+     *
+     * @throws Error if the txid is empty or the group index is out of range
+     */
     validate(): void;
+    /**
+     * Decode an asset id from a binary reader.
+     *
+     * @param reader - Reader positioned at an asset id
+     * @returns Decoded asset id
+     * @throws Error if the reader does not contain enough bytes
+     */
     static fromReader(reader: BufferReader): AssetId;
+    /**
+     * Serialize the asset id into an existing binary writer.
+     *
+     * @param writer - Writer to append the asset id to
+     * @see serialize
+     */
     serializeTo(writer: BufferWriter): void;
 }

package/dist/types/extension/asset/assetInput.d.ts

@@ -17,16 +17,27 @@ type AssetInputIntent = Pick<AssetInputLocal, "vin" | "amount"> & {
 export declare class AssetInput {
     readonly input: AssetInputLocal | AssetInputIntent;
     private constructor();
+    /** Gets the transaction input index for an asset input, e.g. 0 */
     get vin(): number;
+    /** Gets the amount for an input (in most cases, 330 sats) */
     get amount(): bigint;
+    /** Create a local asset input that points at a transaction input index. */
     static create(vin: number, amount: bigint | number): AssetInput;
+    /** Create an intent-backed asset input referencing an external intent transaction. */
     static createIntent(txid: string, vin: number, amount: bigint | number): AssetInput;
+    /** Decode an asset input from its hex string form. */
     static fromString(s: string): AssetInput;
+    /** Decode an asset input from its serialized bytes. */
     static fromBytes(buf: Uint8Array): AssetInput;
+    /** Serialize the asset input to raw bytes. */
     serialize(): Uint8Array;
+    /** Encode the asset input to a hex string. */
     toString(): string;
+    /** Validate the asset input fields. */
     validate(): void;
+    /** Decode an asset input from a buffer reader. */
     static fromReader(reader: BufferReader): AssetInput;
+    /** Serialize the asset input into an existing buffer writer. */
     serializeTo(writer: BufferWriter): void;
 }
 /**
@@ -35,12 +46,19 @@ export declare class AssetInput {
 export declare class AssetInputs {
     readonly inputs: AssetInput[];
     private constructor();
+    /** Create a validated list of asset inputs. */
     static create(inputs: AssetInput[]): AssetInputs;
+    /** Decode an asset input list from its hex string form. */
     static fromString(s: string): AssetInputs;
+    /** Serialize the asset input list to raw bytes. */
     serialize(): Uint8Array;
+    /** Encode the asset input list to a hex string. */
     toString(): string;
+    /** Validate the asset input list. */
     validate(): void;
+    /** Decode an asset input list from a buffer reader. */
     static fromReader(reader: BufferReader): AssetInputs;
+    /** Serialize the asset input list into an existing buffer writer. */
     serializeTo(writer: BufferWriter): void;
 }
 export {};

package/dist/types/extension/asset/assetOutput.d.ts

@@ -11,13 +11,21 @@ export declare class AssetOutput {
     readonly amount: bigint;
     static readonly TYPE_LOCAL = 1;
     private constructor();
+    /** Create a local asset output referencing a transaction output index. */
     static create(vout: number, amount: bigint | number): AssetOutput;
+    /** Decode an asset output from its hex string form. */
     static fromString(s: string): AssetOutput;
+    /** Decode an asset output from its serialized bytes. */
     static fromBytes(buf: Uint8Array): AssetOutput;
+    /** Serialize the asset output to raw bytes. */
     serialize(): Uint8Array;
+    /** Encode the asset output to a hex string. */
     toString(): string;
+    /** Validate the asset output fields. */
     validate(): void;
+    /** Decode an asset output from a buffer reader. */
     static fromReader(reader: BufferReader): AssetOutput;
+    /** Serialize the asset output into an existing buffer writer. */
     serializeTo(writer: BufferWriter): void;
 }
 /**
@@ -29,11 +37,18 @@ export declare class AssetOutput {
 export declare class AssetOutputs {
     readonly outputs: AssetOutput[];
     private constructor();
+    /** Create a validated list of asset outputs. */
     static create(outputs: AssetOutput[]): AssetOutputs;
+    /** Decode an asset output list from its hex string form. */
     static fromString(s: string): AssetOutputs;
+    /** Serialize the asset output list to raw bytes. */
     serialize(): Uint8Array;
+    /** Encode the asset output list to a hex string. */
     toString(): string;
+    /** Validate the asset output list. */
     validate(): void;
+    /** Decode an asset output list from a buffer reader. */
     static fromReader(reader: BufferReader): AssetOutputs;
+    /** Serialize the asset output list into an existing buffer writer. */
     serializeTo(writer: BufferWriter): void;
 }

package/dist/types/extension/asset/assetRef.d.ts

@@ -9,17 +9,83 @@ type AssetRefByGroup = {
     type: AssetRefType.ByGroup;
     groupIndex: number;
 };
+/**
+ * Reference to either an explicit asset id or another asset group in the same packet.
+ *
+ * @see AssetId
+ *
+ * @example
+ * ```typescript
+ * const refById = AssetRef.fromId(assetId)
+ * const refByGroup = AssetRef.fromGroupIndex(0)
+ * ```
+ */
 export declare class AssetRef {
     readonly ref: AssetRefByID | AssetRefByGroup;
     private constructor();
+    /** Reference type discriminator. */
     get type(): AssetRefType;
+    /**
+     * Create an asset reference that points to a specific asset id.
+     *
+     * @param assetId - Asset id referenced by this pointer
+     * @returns Asset reference by id
+     * @see fromGroupIndex
+     */
     static fromId(assetId: AssetId): AssetRef;
+    /**
+     * Create an asset reference that points to another asset group by index.
+     *
+     * @param groupIndex - Zero-based asset group index in the packet
+     * @returns Asset reference by group index
+     * @see fromId
+     */
     static fromGroupIndex(groupIndex: number): AssetRef;
+    /**
+     * Decode an asset reference from its hex string form.
+     *
+     * @param s - Hex-encoded asset reference
+     * @returns Decoded asset reference
+     * @throws Error if the string is not valid hex or does not encode a valid asset reference
+     * @see toString
+     */
     static fromString(s: string): AssetRef;
+    /**
+     * Decode an asset reference from its serialized bytes.
+     *
+     * @param buf - Serialized asset reference bytes
+     * @returns Decoded asset reference
+     * @throws Error if the buffer is empty or malformed
+     */
     static fromBytes(buf: Uint8Array): AssetRef;
+    /**
+     * Serialize the asset reference to raw bytes.
+     *
+     * @returns Serialized asset reference bytes
+     * @see fromBytes
+     */
     serialize(): Uint8Array;
+    /**
+     * Encode the asset reference to a hex string.
+     *
+     * @returns Hex-encoded asset reference
+     * @see fromString
+     */
     toString(): string;
+    /**
+     * Decode an asset reference from a binary reader.
+     *
+     * @param reader - Reader positioned at an asset reference
+     * @returns Decoded asset reference
+     * @throws Error if the type is unknown or the reader does not contain enough bytes
+     */
     static fromReader(reader: BufferReader): AssetRef;
+    /**
+     * Serialize the asset reference into an existing binary writer.
+     *
+     * @param writer - Writer to append the asset reference to
+     * @see serialize
+     */
     serializeTo(writer: BufferWriter): void;
 }
 export {};

package/dist/types/extension/asset/metadata.d.ts

@@ -9,15 +9,23 @@ export declare class Metadata {
     readonly key: Uint8Array;
     readonly value: Uint8Array;
     private constructor();
+    /** Create a metadata entry from raw key and value bytes. */
     static create(key: Bytes, value: Bytes): Metadata;
+    /** Decode metadata from its hex string form. */
     static fromString(s: string): Metadata;
+    /** Decode metadata from its serialized bytes. */
     static fromBytes(buf: Uint8Array): Metadata;
+    /** Serialize metadata to raw bytes. */
     serialize(): Uint8Array;
+    /** Encode metadata to a hex string. */
     toString(): string;
     get keyString(): string;
     get valueString(): string;
+    /** Validate the metadata key and value. */
     validate(): void;
+    /** Decode metadata from a buffer reader. */
     static fromReader(reader: BufferReader): Metadata;
+    /** Serialize metadata into an existing buffer writer. */
     serializeTo(writer: BufferWriter): void;
 }
 export declare class MetadataList {
@@ -26,12 +34,19 @@ export declare class MetadataList {
     static readonly ARK_BRANCH_TAG = "ArkadeAssetBranch";
     static readonly ARK_LEAF_VERSION = 0;
     constructor(items: Metadata[]);
+    /** Create a metadata list from its hex string form. */
     static fromString(s: string): MetadataList;
+    /** Decode a metadata list from its serialized bytes. */
     static fromBytes(buf: Uint8Array): MetadataList;
+    /** Decode a metadata list from a buffer reader. */
     static fromReader(reader: BufferReader): MetadataList;
+    /** Serialize the metadata list into an existing buffer writer. */
     serializeTo(writer: BufferWriter): void;
+    /** Serialize the metadata list to raw bytes. */
     serialize(): Uint8Array;
+    /** Iterate through metadata entries in insertion order. */
     [Symbol.iterator](): Iterator<Metadata>;
     get length(): number;
+    /** Compute the tagged Merkle root for the metadata list. */
     hash(): Uint8Array;
 }

package/dist/types/extension/asset/packet.d.ts

@@ -9,6 +9,7 @@ export declare class Packet implements ExtensionPacket {
     /** PACKET_TYPE is the 1-byte TLV type tag used in the Extension envelope. */
     static readonly PACKET_TYPE = 0;
     private constructor();
+    /** Create a validated asset packet from a list of asset groups. */
     static create(groups: AssetGroup[]): Packet;
     /**
      * fromBytes parses a Packet from raw bytes.
@@ -22,10 +23,11 @@ export declare class Packet implements ExtensionPacket {
      * type returns the TLV packet type tag. Implements ExtensionPacket interface.
      */
     type(): number;
+    /** Convert the packet into the batch-leaf form for a specific intent transaction id. */
     leafTxPacket(intentTxid: Uint8Array): Packet;
     /**
      * 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(): Uint8Array;
@@ -33,6 +35,7 @@ export declare class Packet implements ExtensionPacket {
      * toString returns the hex-encoded raw packet bytes.
      */
     toString(): string;
+    /** Validate packet structure and cross-group references. */
     validate(): void;
     private static fromReader;
 }

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

@@ -6,7 +6,7 @@ export type { ExtensionPacket } from "./packet";
 export { UnknownPacket } from "./packet";
 /**
  * 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 declare const ARKADE_MAGIC: Uint8Array<ArrayBuffer>;
 /**

package/dist/types/forfeit.d.ts

@@ -1,4 +1,18 @@
 import { Transaction } from "./utils/transaction";
 import { TransactionInputUpdate, TransactionOutput } from "@scure/btc-signer/psbt.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 declare function buildForfeitTx(inputs: TransactionInputUpdate[], forfeitPkScript: Uint8Array, txLocktime?: number): Transaction;
+/**
+ * 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 declare function buildForfeitTxWithOutput(inputs: TransactionInputUpdate[], output: TransactionOutput, txLocktime?: number): Transaction;