@arkade-os/sdk 0.4.14 → 0.4.16

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

@@ -7,9 +7,25 @@ import { AssetOutputs } from './assetOutput.js';
 import { MetadataList } from './metadata.js';
 import { BufferReader, BufferWriter } from './utils.js';
 /**
- * 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 class AssetGroup {
+    /** @see create */
     constructor(assetId, controlAsset, inputs, outputs, metadata) {
         this.assetId = assetId;
         this.controlAsset = controlAsset;
@@ -17,12 +33,31 @@ export class AssetGroup {
         this.outputs = outputs;
         this.metadataList = new MetadataList(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, controlAsset, inputs, outputs, metadata) {
         const ag = new AssetGroup(assetId, controlAsset, inputs, outputs, metadata);
         ag.validate();
         return ag;
     }
-    // from hex encoded
+    /**
+     * 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) {
         let buf;
         try {
@@ -33,6 +68,13 @@ export class AssetGroup {
         }
         return AssetGroup.fromBytes(buf);
     }
+    /**
+     * 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) {
         if (!buf || buf.length === 0) {
             throw new Error("missing asset group");
@@ -40,12 +82,21 @@ export class AssetGroup {
         const reader = new BufferReader(buf);
         return AssetGroup.fromReader(reader);
     }
-    // an issuance is a group with null assetId
+    /**
+     * Return true when the group represents an issuance.
+     *
+     * @returns `true` when the group has no asset id
+     */
     isIssuance() {
         return this.assetId === null;
     }
-    // a reissuance is a group that is not an issuance
-    // but where the sum of the outputs is greater than the sum of the inputs
+    /**
+     * 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() {
         const sumReducer = (s, { amount }) => s + amount;
         const sumOutputs = this.outputs.reduce(sumReducer, 0n);
@@ -56,12 +107,23 @@ export class AssetGroup {
             .reduce(sumReducer, 0n);
         return !this.isIssuance() && sumInputs < sumOutputs;
     }
+    /**
+     * Serialize the asset group to raw bytes.
+     *
+     * @returns Serialized asset group bytes
+     * @see fromBytes
+     */
     serialize() {
         this.validate();
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /**
+     * Validate the asset group and its child structures.
+     *
+     * @throws Error if the group is empty or violates issuance invariants
+     */
     validate() {
         if (this.inputs.length === 0 && this.outputs.length === 0) {
             throw new Error("empty asset group");
@@ -77,13 +139,33 @@ export class AssetGroup {
             }
         }
     }
+    /**
+     * 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) {
         const leafInput = AssetInput.createIntent(hex.encode(intentTxid), 0, 0);
         return new AssetGroup(this.assetId, this.controlAsset, [leafInput], this.outputs, this.metadataList.items);
     }
+    /**
+     * Encode the asset group to a hex string.
+     *
+     * @returns Hex-encoded asset group
+     * @see fromString
+     */
     toString() {
         return hex.encode(this.serialize());
     }
+    /**
+     * 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) {
         const presence = reader.readByte();
         let assetId = null;
@@ -104,6 +186,11 @@ export class AssetGroup {
         ag.validate();
         return ag;
     }
+    /**
+     * Serialize the asset group into an existing binary writer.
+     *
+     * @param writer - Writer to append the asset group to
+     */
     serializeTo(writer) {
         let presence = 0;
         if (this.assetId !== null) {

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) {