@arkade-os/sdk 0.4.15 → 0.4.16

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

@@ -2,15 +2,34 @@ import { hex } from "@scure/base";
 import { TX_HASH_SIZE, ASSET_ID_SIZE } from './types.js';
 import { BufferReader, BufferWriter, isZeroBytes } from './utils.js';
 /**
- * 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 class AssetId {
     constructor(txid, groupIndex) {
         this.txid = txid;
         this.groupIndex = groupIndex;
     }
+    /**
+     * 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, groupIndex) {
         if (!txid) {
             throw new Error("missing txid");
@@ -29,6 +48,14 @@ export class AssetId {
         assetId.validate();
         return 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) {
         let buf;
         try {
@@ -39,6 +66,13 @@ export class AssetId {
         }
         return AssetId.fromBytes(buf);
     }
+    /**
+     * 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) {
         if (!buf || buf.length === 0) {
             throw new Error("missing asset id");
@@ -49,14 +83,31 @@ export class AssetId {
         const reader = new BufferReader(buf);
         return AssetId.fromReader(reader);
     }
+    /**
+     * Serialize the asset id to raw bytes.
+     *
+     * @returns Serialized asset id bytes
+     * @see fromBytes
+     */
     serialize() {
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /**
+     * Encode the asset id to a hex string.
+     *
+     * @returns Hex-encoded asset id
+     * @see fromString
+     */
     toString() {
         return hex.encode(this.serialize());
     }
+    /**
+     * Validate the asset id fields.
+     *
+     * @throws Error if the txid is empty or the group index is out of range
+     */
     validate() {
         if (isZeroBytes(this.txid)) {
             throw new Error("empty txid");
@@ -67,6 +118,13 @@ export class AssetId {
             throw new Error(`invalid group index: ${this.groupIndex}, must be in range [0, 65535]`);
         }
     }
+    /**
+     * 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) {
         if (reader.remaining() < ASSET_ID_SIZE) {
             throw new Error(`invalid asset id length: got ${reader.remaining()}, want ${ASSET_ID_SIZE}`);
@@ -77,6 +135,12 @@ export class AssetId {
         assetId.validate();
         return assetId;
     }
+    /**
+     * Serialize the asset id into an existing binary writer.
+     *
+     * @param writer - Writer to append the asset id to
+     * @see serialize
+     */
     serializeTo(writer) {
         writer.write(this.txid);
         writer.writeUint16LE(this.groupIndex);

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

@@ -10,12 +10,15 @@ export class AssetInput {
     constructor(input) {
         this.input = input;
     }
+    /** Gets the transaction input index for an asset input, e.g. 0 */
     get vin() {
         return this.input.vin;
     }
+    /** Gets the amount for an input (in most cases, 330 sats) */
     get amount() {
         return this.input.amount;
     }
+    /** Create a local asset input that points at a transaction input index. */
     static create(vin, amount) {
         const input = new AssetInput({
             type: AssetInputType.Local,
@@ -25,6 +28,7 @@ export class AssetInput {
         input.validate();
         return input;
     }
+    /** Create an intent-backed asset input referencing an external intent transaction. */
     static createIntent(txid, vin, amount) {
         if (!txid || txid.length === 0) {
             throw new Error("missing input intent txid");
@@ -48,6 +52,7 @@ export class AssetInput {
         input.validate();
         return input;
     }
+    /** Decode an asset input from its hex string form. */
     static fromString(s) {
         let buf;
         try {
@@ -58,18 +63,22 @@ export class AssetInput {
         }
         return AssetInput.fromBytes(buf);
     }
+    /** Decode an asset input from its serialized bytes. */
     static fromBytes(buf) {
         const reader = new BufferReader(buf);
         return AssetInput.fromReader(reader);
     }
+    /** Serialize the asset input to raw bytes. */
     serialize() {
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode the asset input to a hex string. */
     toString() {
         return hex.encode(this.serialize());
     }
+    /** Validate the asset input fields. */
     validate() {
         switch (this.input.type) {
             case AssetInputType.Local:
@@ -81,6 +90,7 @@ export class AssetInput {
                 break;
         }
     }
+    /** Decode an asset input from a buffer reader. */
     static fromReader(reader) {
         const type = reader.readByte();
         let input;
@@ -118,6 +128,7 @@ export class AssetInput {
         input.validate();
         return input;
     }
+    /** Serialize the asset input into an existing buffer writer. */
     serializeTo(writer) {
         writer.writeByte(this.input.type);
         if (this.input.type === AssetInputType.Intent) {
@@ -134,11 +145,13 @@ export class AssetInputs {
     constructor(inputs) {
         this.inputs = inputs;
     }
+    /** Create a validated list of asset inputs. */
     static create(inputs) {
         const list = new AssetInputs(inputs);
         list.validate();
         return list;
     }
+    /** Decode an asset input list from its hex string form. */
     static fromString(s) {
         if (!s || s.length === 0) {
             throw new Error("missing asset inputs");
@@ -153,14 +166,17 @@ export class AssetInputs {
         const reader = new BufferReader(buf);
         return AssetInputs.fromReader(reader);
     }
+    /** Serialize the asset input list to raw bytes. */
     serialize() {
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode the asset input list to a hex string. */
     toString() {
         return hex.encode(this.serialize());
     }
+    /** Validate the asset input list. */
     validate() {
         const seen = new Set();
         let listType = AssetInputType.Unspecified;
@@ -182,6 +198,7 @@ export class AssetInputs {
             }
         }
     }
+    /** Decode an asset input list from a buffer reader. */
     static fromReader(reader) {
         const count = Number(reader.readVarUint());
         const inputs = [];
@@ -190,6 +207,7 @@ export class AssetInputs {
         }
         return AssetInputs.create(inputs);
     }
+    /** Serialize the asset input list into an existing buffer writer. */
     serializeTo(writer) {
         writer.writeVarUint(this.inputs.length);
         for (const input of this.inputs) {

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

@@ -12,11 +12,13 @@ export class AssetOutput {
         this.vout = vout;
         this.amount = amount;
     }
+    /** Create a local asset output referencing a transaction output index. */
     static create(vout, amount) {
         const output = new AssetOutput(vout, typeof amount === "number" ? BigInt(amount) : amount);
         output.validate();
         return output;
     }
+    /** Decode an asset output from its hex string form. */
     static fromString(s) {
         let buf;
         try {
@@ -27,6 +29,7 @@ export class AssetOutput {
         }
         return AssetOutput.fromBytes(buf);
     }
+    /** Decode an asset output from its serialized bytes. */
     static fromBytes(buf) {
         if (!buf || buf.length === 0) {
             throw new Error("missing asset output");
@@ -36,14 +39,17 @@ export class AssetOutput {
         output.validate();
         return output;
     }
+    /** Serialize the asset output to raw bytes. */
     serialize() {
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode the asset output to a hex string. */
     toString() {
         return hex.encode(this.serialize());
     }
+    /** Validate the asset output fields. */
     validate() {
         if (!Number.isInteger(this.vout) ||
             this.vout < 0 ||
@@ -54,6 +60,7 @@ export class AssetOutput {
             throw new Error("asset output amount must be greater than 0");
         }
     }
+    /** Decode an asset output from a buffer reader. */
     static fromReader(reader) {
         if (reader.remaining() < 2) {
             throw new Error("invalid asset output vout length");
@@ -75,6 +82,7 @@ export class AssetOutput {
         const amount = reader.readVarUint();
         return new AssetOutput(vout, amount);
     }
+    /** Serialize the asset output into an existing buffer writer. */
     serializeTo(writer) {
         writer.writeByte(0x01);
         writer.writeUint16LE(this.vout);
@@ -94,11 +102,13 @@ export class AssetOutputs {
     constructor(outputs) {
         this.outputs = outputs;
     }
+    /** Create a validated list of asset outputs. */
     static create(outputs) {
         const list = new AssetOutputs(outputs);
         list.validate();
         return list;
     }
+    /** Decode an asset output list from its hex string form. */
     static fromString(s) {
         if (!s || s.length === 0) {
             throw new Error("missing asset outputs");
@@ -113,14 +123,17 @@ export class AssetOutputs {
         const reader = new BufferReader(buf);
         return AssetOutputs.fromReader(reader);
     }
+    /** Serialize the asset output list to raw bytes. */
     serialize() {
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode the asset output list to a hex string. */
     toString() {
         return hex.encode(this.serialize());
     }
+    /** Validate the asset output list. */
     validate() {
         const seen = new Set();
         for (const output of this.outputs) {
@@ -131,6 +144,7 @@ export class AssetOutputs {
             seen.add(output.vout);
         }
     }
+    /** Decode an asset output list from a buffer reader. */
     static fromReader(reader) {
         const count = Number(reader.readVarUint());
         if (count === 0) {
@@ -144,6 +158,7 @@ export class AssetOutputs {
         result.validate();
         return result;
     }
+    /** Serialize the asset output list into an existing buffer writer. */
     serializeTo(writer) {
         this.validate();
         writer.writeVarUint(this.outputs.length);

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

@@ -2,19 +2,53 @@ import { hex } from "@scure/base";
 import { AssetRefType } from './types.js';
 import { AssetId } from './assetId.js';
 import { BufferReader, BufferWriter } from './utils.js';
+/**
+ * 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 class AssetRef {
     constructor(ref) {
         this.ref = ref;
     }
+    /** Reference type discriminator. */
     get type() {
         return this.ref.type;
     }
+    /**
+     * 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) {
         return new AssetRef({ type: AssetRefType.ByID, assetId });
     }
+    /**
+     * 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) {
         return new AssetRef({ type: AssetRefType.ByGroup, groupIndex });
     }
+    /**
+     * 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) {
         let buf;
         try {
@@ -25,6 +59,13 @@ export class AssetRef {
         }
         return AssetRef.fromBytes(buf);
     }
+    /**
+     * 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) {
         if (!buf || buf.length === 0) {
             throw new Error("missing asset ref");
@@ -32,14 +73,33 @@ export class AssetRef {
         const reader = new BufferReader(buf);
         return AssetRef.fromReader(reader);
     }
+    /**
+     * Serialize the asset reference to raw bytes.
+     *
+     * @returns Serialized asset reference bytes
+     * @see fromBytes
+     */
     serialize() {
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /**
+     * Encode the asset reference to a hex string.
+     *
+     * @returns Hex-encoded asset reference
+     * @see fromString
+     */
     toString() {
         return hex.encode(this.serialize());
     }
+    /**
+     * 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) {
         const type = reader.readByte();
         let ref;
@@ -64,6 +124,12 @@ export class AssetRef {
         }
         return ref;
     }
+    /**
+     * Serialize the asset reference into an existing binary writer.
+     *
+     * @param writer - Writer to append the asset reference to
+     * @see serialize
+     */
     serializeTo(writer) {
         writer.writeByte(this.ref.type);
         switch (this.ref.type) {

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,