@arkade-os/sdk 0.4.15 → 0.4.17

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

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

@@ -15,11 +15,13 @@ 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 {
@@ -30,6 +32,7 @@ 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");
@@ -37,11 +40,13 @@ class Metadata {
         const reader = new utils_1.BufferReader(buf);
         return Metadata.fromReader(reader);
     }
+    /** Serialize metadata to raw bytes. */
     serialize() {
         const writer = new utils_1.BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /** Encode metadata to a hex string. */
     toString() {
         return base_1.hex.encode(this.serialize());
     }
@@ -51,6 +56,7 @@ 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");
@@ -59,6 +65,7 @@ class Metadata {
             throw new Error("missing metadata value");
         }
     }
+    /** Decode metadata from a buffer reader. */
     static fromReader(reader) {
         let key;
         let value;
@@ -78,6 +85,7 @@ class Metadata {
         md.validate();
         return md;
     }
+    /** Serialize metadata into an existing buffer writer. */
     serializeTo(writer) {
         writer.writeVarSlice(this.key);
         writer.writeVarSlice(this.value);
@@ -88,6 +96,7 @@ class MetadataList {
     constructor(items) {
         this.items = items;
     }
+    /** Create a metadata list from its hex string form. */
     static fromString(s) {
         let buf;
         try {
@@ -98,6 +107,7 @@ 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");
@@ -105,28 +115,33 @@ class MetadataList {
         const reader = new utils_1.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 utils_1.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/cjs/extension/asset/packet.js

@@ -13,6 +13,7 @@ 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();
@@ -46,13 +47,14 @@ 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() {
@@ -72,6 +74,7 @@ class Packet {
     toString() {
         return base_1.hex.encode(this.serialize());
     }
+    /** Validate packet structure and cross-group references. */
     validate() {
         if (this.groups.length === 0) {
             throw new Error("missing assets");

package/dist/cjs/extension/index.js

@@ -11,7 +11,7 @@ var packet_3 = require("./packet");
 Object.defineProperty(exports, "UnknownPacket", { enumerable: true, get: function () { return packet_3.UnknownPacket; } });
 /**
  * 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.
  */
 exports.ARKADE_MAGIC = new Uint8Array([0x41, 0x52, 0x4b]); // "ARK"
 /**

package/dist/cjs/forfeit.js

@@ -4,6 +4,13 @@ exports.buildForfeitTx = buildForfeitTx;
 exports.buildForfeitTxWithOutput = buildForfeitTxWithOutput;
 const transaction_1 = require("./utils/transaction");
 const anchor_1 = require("./utils/anchor");
+/**
+ * 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
+ */
 function buildForfeitTx(inputs, forfeitPkScript, txLocktime) {
     let amount = 0n;
     for (const input of inputs) {
@@ -17,6 +24,13 @@ 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
+ */
 function buildForfeitTxWithOutput(inputs, output, txLocktime) {
     const tx = new transaction_1.Transaction({
         version: 3,

package/dist/cjs/identity/seedIdentity.js

@@ -44,7 +44,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.
  *
@@ -161,7 +161,7 @@ exports.SeedIdentity = 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/cjs/identity/singleKey.js

@@ -29,12 +29,15 @@ class SingleKey {
     constructor(key) {
         this.key = key || (0, utils_js_1.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(base_1.hex.decode(privateKeyHex));
     }
+    /** Create a signing identity with a freshly generated random private key. */
     static fromRandomBytes() {
         return new SingleKey((0, utils_js_1.randomPrivateKeyBytes)());
     }
@@ -92,6 +95,7 @@ class SingleKey {
 }
 exports.SingleKey = SingleKey;
 class ReadonlySingleKey {
+    /** Create a readonly identity from a compressed public key. */
     constructor(publicKey) {
         this.publicKey = publicKey;
         if (publicKey.length !== 33) {

package/dist/cjs/intent/index.js

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

package/dist/cjs/providers/ark.js

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