@arkade-os/sdk 0.3.12 → 0.4.0-next.0

package/dist/esm/asset/metadata.js

@@ -0,0 +1,167 @@
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { hex } from "@scure/base";
+import { compareBytes } from "@scure/btc-signer/utils.js";
+import { BufferReader, BufferWriter } from './utils.js';
+/**
+ * Metadata represents a key-value pair.
+ * @param key - the key
+ * @param value - the value
+ */
+export class Metadata {
+    constructor(key, value) {
+        this.key = key;
+        this.value = value;
+    }
+    static create(key, value) {
+        const md = new Metadata(key, value);
+        md.validate();
+        return md;
+    }
+    static fromString(s) {
+        let buf;
+        try {
+            buf = hex.decode(s);
+        }
+        catch {
+            throw new Error("invalid metadata format, must be hex");
+        }
+        return Metadata.fromBytes(buf);
+    }
+    static fromBytes(buf) {
+        if (!buf || buf.length === 0) {
+            throw new Error("missing metadata");
+        }
+        const reader = new BufferReader(buf);
+        return Metadata.fromReader(reader);
+    }
+    serialize() {
+        const writer = new BufferWriter();
+        this.serializeTo(writer);
+        return writer.toBytes();
+    }
+    toString() {
+        return hex.encode(this.serialize());
+    }
+    get keyString() {
+        return new TextDecoder().decode(this.key);
+    }
+    get valueString() {
+        return new TextDecoder().decode(this.value);
+    }
+    validate() {
+        if (this.key.length === 0) {
+            throw new Error("missing metadata key");
+        }
+        if (this.value.length === 0) {
+            throw new Error("missing metadata value");
+        }
+    }
+    static fromReader(reader) {
+        let key;
+        let value;
+        try {
+            key = reader.readVarSlice();
+        }
+        catch {
+            throw new Error("invalid metadata length");
+        }
+        try {
+            value = reader.readVarSlice();
+        }
+        catch {
+            throw new Error("invalid metadata length");
+        }
+        const md = new Metadata(key, value);
+        md.validate();
+        return md;
+    }
+    serializeTo(writer) {
+        writer.writeVarSlice(this.key);
+        writer.writeVarSlice(this.value);
+    }
+}
+export class MetadataList {
+    constructor(items) {
+        this.items = items;
+    }
+    static fromString(s) {
+        let buf;
+        try {
+            buf = hex.decode(s);
+        }
+        catch {
+            throw new Error("invalid metadata list format");
+        }
+        return MetadataList.fromBytes(buf);
+    }
+    static fromBytes(buf) {
+        if (!buf || buf.length === 0) {
+            throw new Error("missing metadata list");
+        }
+        const reader = new BufferReader(buf);
+        return MetadataList.fromReader(reader);
+    }
+    static fromReader(reader) {
+        const count = Number(reader.readVarUint());
+        const items = Array.from({ length: count }, () => Metadata.fromReader(reader));
+        return new MetadataList(items);
+    }
+    serializeTo(writer) {
+        writer.writeVarUint(this.items.length);
+        for (const item of this) {
+            item.serializeTo(writer);
+        }
+    }
+    serialize() {
+        const writer = new BufferWriter();
+        this.serializeTo(writer);
+        return writer.toBytes();
+    }
+    [Symbol.iterator]() {
+        return this.items[Symbol.iterator]();
+    }
+    get length() {
+        return this.items.length;
+    }
+    hash() {
+        if (this.items.length === 0)
+            throw new Error("missing metadata list");
+        const levels = buildMetadataMerkleTree(this.items);
+        return levels[levels.length - 1][0]; // the last level is the root
+    }
+}
+MetadataList.ARK_LEAF_TAG = "ArkadeAssetLeaf";
+MetadataList.ARK_BRANCH_TAG = "ArkadeAssetBranch";
+MetadataList.ARK_LEAF_VERSION = 0x00;
+function computeMetadataLeafHash(md) {
+    const writer = new BufferWriter();
+    writer.writeByte(MetadataList.ARK_LEAF_VERSION);
+    writer.writeVarSlice(md.key);
+    writer.writeVarSlice(md.value);
+    return schnorr.utils.taggedHash(MetadataList.ARK_LEAF_TAG, writer.toBytes());
+}
+function computeMetadataBranchHash(a, b) {
+    const [smaller, larger] = compareBytes(a, b) === -1 ? [a, b] : [b, a];
+    return schnorr.utils.taggedHash(MetadataList.ARK_BRANCH_TAG, smaller, larger);
+}
+function buildMetadataMerkleTree(leaves) {
+    if (leaves.length === 0)
+        return [];
+    const leafHashes = leaves.map(computeMetadataLeafHash);
+    const levels = [leafHashes];
+    let current = leafHashes;
+    while (current.length > 1) {
+        const next = [];
+        for (let i = 0; i < current.length; i += 2) {
+            if (i + 1 < current.length) {
+                next.push(computeMetadataBranchHash(current[i], current[i + 1]));
+            }
+            else {
+                next.push(current[i]);
+            }
+        }
+        levels.push(next);
+        current = next;
+    }
+    return levels;
+}

package/dist/esm/asset/packet.js

@@ -0,0 +1,159 @@
+import { hex } from "@scure/base";
+import { Script } from "@scure/btc-signer";
+import { concatBytes, equalBytes } from "@scure/btc-signer/utils.js";
+import { ARKADE_MAGIC, MARKER_ASSET_PAYLOAD, AssetRefType } from './types.js';
+import { AssetGroup } from './assetGroup.js';
+import { BufferReader, BufferWriter } from './utils.js';
+export class AssetPacketNotFoundError extends Error {
+    constructor(txid) {
+        super(`asset packet not found in tx ${txid}`);
+        this.name = "AssetPacketNotFoundError";
+    }
+}
+/**
+ * Packet represents a collection of asset groups.
+ * A packet is encoded in OP_RETURN output of an asset transaction.
+ * @param groups - the asset groups in the packet
+ */
+export class Packet {
+    constructor(groups) {
+        this.groups = groups;
+    }
+    static create(groups) {
+        const p = new Packet(groups);
+        p.validate();
+        return p;
+    }
+    static fromString(s) {
+        let buf;
+        try {
+            buf = hex.decode(s);
+        }
+        catch {
+            throw new Error("invalid output script format, must be hex");
+        }
+        return Packet.fromScript(buf);
+    }
+    static fromScript(script) {
+        const rawPacket = extractRawPacketFromScript(script);
+        const reader = new BufferReader(rawPacket);
+        return Packet.fromReader(reader);
+    }
+    static fromTxOut(pkScript) {
+        return Packet.fromScript(pkScript);
+    }
+    static fromTx(tx) {
+        for (let i = 0; i < tx.outputsLength; i++) {
+            try {
+                const output = tx.getOutput(i);
+                if (!output?.script) {
+                    continue;
+                }
+                return Packet.fromScript(output.script);
+            }
+            catch (error) {
+                continue;
+            }
+        }
+        throw new AssetPacketNotFoundError(tx.id);
+    }
+    static isAssetPacket(script) {
+        try {
+            extractRawPacketFromScript(script);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    leafTxPacket(intentTxid) {
+        const leafGroups = this.groups.map((group) => group.toBatchLeafAssetGroup(intentTxid));
+        return new Packet(leafGroups);
+    }
+    txOut() {
+        return {
+            script: this.serialize(),
+            amount: 0n,
+        };
+    }
+    serialize() {
+        const writer = new BufferWriter();
+        writer.writeVarUint(this.groups.length);
+        for (const group of this.groups) {
+            group.serializeTo(writer);
+        }
+        const packetData = writer.toBytes();
+        const data = concatBytes(ARKADE_MAGIC, new Uint8Array([MARKER_ASSET_PAYLOAD]), packetData);
+        return buildOpReturnScript(data);
+    }
+    toString() {
+        return hex.encode(this.serialize());
+    }
+    validate() {
+        if (this.groups.length === 0) {
+            throw new Error("missing assets");
+        }
+        for (const group of this.groups) {
+            if (group.controlAsset !== null &&
+                group.controlAsset.ref.type === AssetRefType.ByGroup &&
+                group.controlAsset.ref.groupIndex >= this.groups.length) {
+                throw new Error(`invalid control asset group index, ${group.controlAsset.ref.groupIndex} out of range [0, ${this.groups.length - 1}]`);
+            }
+        }
+    }
+    static fromReader(reader) {
+        const count = Number(reader.readVarUint());
+        const groups = [];
+        for (let i = 0; i < count; i++) {
+            groups.push(AssetGroup.fromReader(reader));
+        }
+        if (reader.remaining() > 0) {
+            throw new Error(`invalid packet length, left ${reader.remaining()} unknown bytes to read`);
+        }
+        const packet = new Packet(groups);
+        packet.validate();
+        return packet;
+    }
+}
+function extractRawPacketFromScript(script) {
+    if (!script || script.length === 0) {
+        throw new Error("missing output script");
+    }
+    let decoded;
+    try {
+        decoded = Script.decode(script);
+    }
+    catch {
+        throw new Error("invalid OP_RETURN output script");
+    }
+    if (decoded.length === 0 || decoded[0] !== "RETURN") {
+        throw new Error("OP_RETURN not found in output script");
+    }
+    // concat all data pushes after RETURN
+    const dataPushes = decoded
+        .slice(1)
+        .filter((item) => item instanceof Uint8Array);
+    if (dataPushes.length === 0) {
+        throw new Error("missing OP_RETURN data");
+    }
+    const payload = concatBytes(...dataPushes);
+    if (payload.length < ARKADE_MAGIC.length + 1) {
+        throw new Error("invalid script length");
+    }
+    const magicSlice = new Uint8Array(payload.slice(0, ARKADE_MAGIC.length));
+    if (!equalBytes(magicSlice, ARKADE_MAGIC)) {
+        throw new Error(`invalid magic prefix, got ${hex.encode(magicSlice)} want ${hex.encode(ARKADE_MAGIC)}`);
+    }
+    const marker = payload[ARKADE_MAGIC.length];
+    if (marker !== MARKER_ASSET_PAYLOAD) {
+        throw new Error(`invalid asset marker, got ${marker} want ${MARKER_ASSET_PAYLOAD}`);
+    }
+    const packetData = new Uint8Array(payload.slice(ARKADE_MAGIC.length + 1));
+    if (packetData.length === 0) {
+        throw new Error("missing packet data");
+    }
+    return packetData;
+}
+function buildOpReturnScript(data) {
+    return Script.encode(["RETURN", data]);
+}

package/dist/esm/asset/types.js

@@ -0,0 +1,22 @@
+export const TX_HASH_SIZE = 32;
+export const ASSET_ID_SIZE = 34;
+export const ASSET_VERSION = 0x01;
+export var AssetInputType;
+(function (AssetInputType) {
+    AssetInputType[AssetInputType["Unspecified"] = 0] = "Unspecified";
+    AssetInputType[AssetInputType["Local"] = 1] = "Local";
+    AssetInputType[AssetInputType["Intent"] = 2] = "Intent";
+})(AssetInputType || (AssetInputType = {}));
+export var AssetRefType;
+(function (AssetRefType) {
+    AssetRefType[AssetRefType["Unspecified"] = 0] = "Unspecified";
+    AssetRefType[AssetRefType["ByID"] = 1] = "ByID";
+    AssetRefType[AssetRefType["ByGroup"] = 2] = "ByGroup";
+})(AssetRefType || (AssetRefType = {}));
+// Presence byte masks for AssetGroup
+export const MASK_ASSET_ID = 0x01;
+export const MASK_CONTROL_ASSET = 0x02;
+export const MASK_METADATA = 0x04;
+// ARK magic bytes and marker
+export const ARKADE_MAGIC = new Uint8Array([0x41, 0x52, 0x4b]); // "ARK"
+export const MARKER_ASSET_PAYLOAD = 0x00;

package/dist/esm/asset/utils.js

@@ -0,0 +1,99 @@
+export class BufferWriter {
+    constructor() {
+        this.buffer = [];
+    }
+    write(data) {
+        for (const byte of data) {
+            this.buffer.push(byte);
+        }
+    }
+    writeByte(byte) {
+        this.buffer.push(byte & 0xff);
+    }
+    writeUint16LE(value) {
+        const buf = new Uint8Array(2);
+        new DataView(buf.buffer).setUint16(0, value, true); // true = little endian
+        this.write(buf);
+    }
+    writeVarUint(value) {
+        if (typeof value === "number") {
+            if (!Number.isInteger(value) || value < 0) {
+                throw new RangeError("writeVarUint: value must be a non-negative integer");
+            }
+        }
+        else if (value < 0n) {
+            throw new RangeError("writeVarUint: value must be a non-negative integer");
+        }
+        const val = typeof value === "number" ? BigInt(value) : value;
+        const bytes = [];
+        let remaining = val;
+        do {
+            let byte = Number(remaining & 0x7fn);
+            remaining >>= 7n;
+            if (remaining > 0n) {
+                byte |= 0x80;
+            }
+            bytes.push(byte);
+        } while (remaining > 0n);
+        this.write(new Uint8Array(bytes));
+    }
+    writeVarSlice(data) {
+        this.writeVarUint(data.length);
+        this.write(data);
+    }
+    toBytes() {
+        return new Uint8Array(this.buffer);
+    }
+}
+export class BufferReader {
+    constructor(data) {
+        this.offset = 0;
+        this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    }
+    remaining() {
+        return this.view.byteLength - this.offset;
+    }
+    readByte() {
+        if (this.offset >= this.view.byteLength) {
+            throw new Error("unexpected end of buffer");
+        }
+        return this.view.getUint8(this.offset++);
+    }
+    readSlice(size) {
+        if (this.offset + size > this.view.byteLength) {
+            throw new Error("unexpected end of buffer");
+        }
+        const result = new Uint8Array(this.view.buffer, this.view.byteOffset + this.offset, size);
+        this.offset += size;
+        return result;
+    }
+    readUint16LE() {
+        if (this.offset + 2 > this.view.byteLength) {
+            throw new Error("unexpected end of buffer");
+        }
+        const value = this.view.getUint16(this.offset, true);
+        this.offset += 2;
+        return value;
+    }
+    readVarUint() {
+        let result = 0n;
+        let shift = 0n;
+        let byte;
+        do {
+            if (this.offset >= this.view.byteLength) {
+                throw new Error("unexpected end of buffer");
+            }
+            byte = this.view.getUint8(this.offset++);
+            result |= BigInt(byte & 0x7f) << shift;
+            shift += 7n;
+        } while (byte & 0x80);
+        return result;
+    }
+    readVarSlice() {
+        const length = Number(this.readVarUint());
+        return this.readSlice(length);
+    }
+}
+export function isZeroBytes(bytes) {
+    return bytes.every((byte) => byte === 0);
+}

package/dist/esm/contracts/arkcontract.js

@@ -0,0 +1,141 @@
+import { hex } from "@scure/base";
+import { contractHandlers } from './handlers/index.js';
+/**
+ * Prefix for arkcontract strings.
+ */
+const ARKCONTRACT_PREFIX = "arkcontract";
+/**
+ * Encode a contract to the arkcontract string format.
+ *
+ * Format: arkcontract={type}&{key1}={value1}&{key2}={value2}...
+ *
+ * This format is compatible with NArk and allows contracts to be
+ * shared/imported across different Ark implementations.
+ *
+ * @example
+ * ```typescript
+ * const contract: Contract = {
+ *   type: "vhtlc",
+ *   params: { sender: "ab12...", receiver: "cd34...", ... },
+ *   // ...
+ * };
+ *
+ * const encoded = encodeArkContract(contract);
+ * // "arkcontract=vhtlc&sender=ab12...&receiver=cd34...&..."
+ * ```
+ */
+export function encodeArkContract(contract) {
+    const params = new URLSearchParams();
+    // Add contract type first
+    params.set(ARKCONTRACT_PREFIX, contract.type);
+    // Add all params
+    for (const [key, value] of Object.entries(contract.params)) {
+        params.set(key, value);
+    }
+    return params.toString();
+}
+/**
+ * Decode an arkcontract string into raw type and data.
+ *
+ * This is a low-level function that parses the URL-encoded format.
+ * For creating typed Contract objects, use `contractFromArkContract`
+ * or `contractFromArkContractWithAddress` instead.
+ *
+ * @param encoded - The arkcontract string
+ * @returns Parsed type and key-value data
+ * @throws If the string is not a valid arkcontract
+ *
+ * @example
+ * ```typescript
+ * const parsed = decodeArkContract("arkcontract=vhtlc&sender=ab12...");
+ * // { type: "vhtlc", data: { sender: "ab12...", ... } }
+ * ```
+ */
+export function decodeArkContract(encoded) {
+    const params = new URLSearchParams(encoded);
+    // Extract type from the arkcontract key
+    const type = params.get(ARKCONTRACT_PREFIX);
+    if (!type) {
+        throw new Error(`Invalid arkcontract string: missing '${ARKCONTRACT_PREFIX}' key`);
+    }
+    // Build data object from all other params
+    const data = {};
+    for (const [key, value] of params.entries()) {
+        if (key !== ARKCONTRACT_PREFIX) {
+            data[key] = value;
+        }
+    }
+    return { type, data };
+}
+/**
+ * Create a Contract from an arkcontract string.
+ *
+ * This requires a handler to be registered for the contract type.
+ *
+ * @param encoded - The arkcontract string
+ * @param options - Additional options for the contract
+ * @returns A Contract object
+ * @throws If the string is invalid or no handler exists for the type
+ *
+ * @example
+ * ```typescript
+ * const contract = contractFromArkContract(
+ *   "arkcontract=vhtlc&sender=ab12...",
+ *   {
+ *     label: "Lightning Receive",
+ *   }
+ * );
+ * ```
+ */
+export function contractFromArkContract(encoded, options = {}) {
+    const parsed = decodeArkContract(encoded);
+    const handler = contractHandlers.get(parsed.type);
+    if (!handler) {
+        throw new Error(`No handler registered for contract type '${parsed.type}'`);
+    }
+    // Separate params from runtime data
+    // This is type-specific - the handler knows which keys are params
+    // For now, we treat all data as params
+    const params = parsed.data;
+    return {
+        label: options.label,
+        type: parsed.type,
+        params,
+        state: options.state || "active",
+        createdAt: Date.now(),
+        expiresAt: options.expiresAt,
+        metadata: options.metadata,
+    };
+}
+/**
+ * Create a full Contract with derived script and address.
+ *
+ * @param encoded - The arkcontract string
+ * @param serverPubKey - Server public key (for address derivation)
+ * @param addressPrefix - Address prefix (e.g., "tark" for testnet)
+ * @param options - Additional options
+ * @returns A complete Contract object
+ */
+export function contractFromArkContractWithAddress(encoded, serverPubKey, addressPrefix, options = {}) {
+    const parsed = decodeArkContract(encoded);
+    const handler = contractHandlers.getOrThrow(parsed.type);
+    const params = parsed.data;
+    const vtxoScript = handler.createScript(params);
+    return {
+        label: options.label,
+        type: parsed.type,
+        params,
+        script: hex.encode(vtxoScript.pkScript),
+        address: vtxoScript.address(addressPrefix, serverPubKey).encode(),
+        state: options.state || "active",
+        createdAt: Date.now(),
+        expiresAt: options.expiresAt,
+        metadata: options.metadata,
+    };
+}
+/**
+ * Check if a string is an arkcontract.
+ */
+export function isArkContract(str) {
+    return str.startsWith(ARKCONTRACT_PREFIX + "=");
+}