@arkade-os/sdk 0.4.14 → 0.4.16

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

@@ -10,9 +10,25 @@ const assetOutput_1 = require("./assetOutput");
 const metadata_1 = require("./metadata");
 const utils_1 = require("./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
+ * )
+ * ```
  */
 class AssetGroup {
+    /** @see create */
     constructor(assetId, controlAsset, inputs, outputs, metadata) {
         this.assetId = assetId;
         this.controlAsset = controlAsset;
@@ -20,12 +36,31 @@ class AssetGroup {
         this.outputs = outputs;
         this.metadataList = new metadata_1.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 {
@@ -36,6 +71,13 @@ 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");
@@ -43,12 +85,21 @@ class AssetGroup {
         const reader = new utils_1.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);
@@ -59,12 +110,23 @@ 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 utils_1.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");
@@ -80,13 +142,33 @@ 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_1.AssetInput.createIntent(base_1.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 base_1.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;
@@ -107,6 +189,11 @@ 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/cjs/extension/asset/assetId.js

@@ -5,15 +5,34 @@ const base_1 = require("@scure/base");
 const types_1 = require("./types");
 const utils_1 = require("./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)
+ * ```
  */
 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");
@@ -32,6 +51,14 @@ 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 {
@@ -42,6 +69,13 @@ 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");
@@ -52,14 +86,31 @@ class AssetId {
         const reader = new utils_1.BufferReader(buf);
         return AssetId.fromReader(reader);
     }
+    /**
+     * Serialize the asset id to raw bytes.
+     *
+     * @returns Serialized asset id bytes
+     * @see fromBytes
+     */
     serialize() {
         const writer = new utils_1.BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /**
+     * Encode the asset id to a hex string.
+     *
+     * @returns Hex-encoded asset id
+     * @see fromString
+     */
     toString() {
         return base_1.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 ((0, utils_1.isZeroBytes)(this.txid)) {
             throw new Error("empty txid");
@@ -70,6 +121,13 @@ 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() < types_1.ASSET_ID_SIZE) {
             throw new Error(`invalid asset id length: got ${reader.remaining()}, want ${types_1.ASSET_ID_SIZE}`);
@@ -80,6 +138,12 @@ 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/cjs/extension/asset/assetInput.js

@@ -13,12 +13,15 @@ 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: types_1.AssetInputType.Local,
@@ -28,6 +31,7 @@ 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");
@@ -51,6 +55,7 @@ class AssetInput {
         input.validate();
         return input;
     }
+    /** Decode an asset input from its hex string form. */
     static fromString(s) {
         let buf;
         try {
@@ -61,18 +66,22 @@ class AssetInput {
         }
         return AssetInput.fromBytes(buf);
     }
+    /** Decode an asset input from its serialized bytes. */
     static fromBytes(buf) {
         const reader = new utils_1.BufferReader(buf);
         return AssetInput.fromReader(reader);
     }
+    /** Serialize the asset input to raw bytes. */
     serialize() {
         const writer = new utils_1.BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode the asset input to a hex string. */
     toString() {
         return base_1.hex.encode(this.serialize());
     }
+    /** Validate the asset input fields. */
     validate() {
         switch (this.input.type) {
             case types_1.AssetInputType.Local:
@@ -84,6 +93,7 @@ class AssetInput {
                 break;
         }
     }
+    /** Decode an asset input from a buffer reader. */
     static fromReader(reader) {
         const type = reader.readByte();
         let input;
@@ -121,6 +131,7 @@ 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 === types_1.AssetInputType.Intent) {
@@ -138,11 +149,13 @@ 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");
@@ -157,14 +170,17 @@ class AssetInputs {
         const reader = new utils_1.BufferReader(buf);
         return AssetInputs.fromReader(reader);
     }
+    /** Serialize the asset input list to raw bytes. */
     serialize() {
         const writer = new utils_1.BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode the asset input list to a hex string. */
     toString() {
         return base_1.hex.encode(this.serialize());
     }
+    /** Validate the asset input list. */
     validate() {
         const seen = new Set();
         let listType = types_1.AssetInputType.Unspecified;
@@ -186,6 +202,7 @@ class AssetInputs {
             }
         }
     }
+    /** Decode an asset input list from a buffer reader. */
     static fromReader(reader) {
         const count = Number(reader.readVarUint());
         const inputs = [];
@@ -194,6 +211,7 @@ 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/cjs/extension/asset/assetOutput.js

@@ -15,11 +15,13 @@ 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 {
@@ -30,6 +32,7 @@ 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");
@@ -39,14 +42,17 @@ class AssetOutput {
         output.validate();
         return output;
     }
+    /** Serialize the asset output to raw bytes. */
     serialize() {
         const writer = new utils_1.BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode the asset output to a hex string. */
     toString() {
         return base_1.hex.encode(this.serialize());
     }
+    /** Validate the asset output fields. */
     validate() {
         if (!Number.isInteger(this.vout) ||
             this.vout < 0 ||
@@ -57,6 +63,7 @@ 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");
@@ -78,6 +85,7 @@ 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);
@@ -98,11 +106,13 @@ 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");
@@ -117,14 +127,17 @@ class AssetOutputs {
         const reader = new utils_1.BufferReader(buf);
         return AssetOutputs.fromReader(reader);
     }
+    /** Serialize the asset output list to raw bytes. */
     serialize() {
         const writer = new utils_1.BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode the asset output list to a hex string. */
     toString() {
         return base_1.hex.encode(this.serialize());
     }
+    /** Validate the asset output list. */
     validate() {
         const seen = new Set();
         for (const output of this.outputs) {
@@ -135,6 +148,7 @@ 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) {
@@ -148,6 +162,7 @@ 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/cjs/extension/asset/assetRef.js

@@ -5,19 +5,53 @@ const base_1 = require("@scure/base");
 const types_1 = require("./types");
 const assetId_1 = require("./assetId");
 const utils_1 = require("./utils");
+/**
+ * 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)
+ * ```
+ */
 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: types_1.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: types_1.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 {
@@ -28,6 +62,13 @@ 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");
@@ -35,14 +76,33 @@ class AssetRef {
         const reader = new utils_1.BufferReader(buf);
         return AssetRef.fromReader(reader);
     }
+    /**
+     * Serialize the asset reference to raw bytes.
+     *
+     * @returns Serialized asset reference bytes
+     * @see fromBytes
+     */
     serialize() {
         const writer = new utils_1.BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /**
+     * Encode the asset reference to a hex string.
+     *
+     * @returns Hex-encoded asset reference
+     * @see fromString
+     */
     toString() {
         return base_1.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;
@@ -67,6 +127,12 @@ 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) {