@arkade-os/sdk 0.4.0-next.2 → 0.4.0-next.4

package/dist/cjs/{asset → extension/asset}/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AssetPacketNotFoundError = exports.Packet = exports.AssetGroup = exports.MetadataList = exports.Metadata = exports.AssetOutputs = exports.AssetOutput = exports.AssetInputs = exports.AssetInput = exports.AssetRef = exports.AssetId = exports.AssetRefType = exports.AssetInputType = void 0;
+exports.Packet = exports.AssetGroup = exports.MetadataList = exports.Metadata = exports.AssetOutputs = exports.AssetOutput = exports.AssetInputs = exports.AssetInput = exports.AssetRef = exports.AssetId = exports.AssetRefType = exports.AssetInputType = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "AssetInputType", { enumerable: true, get: function () { return types_1.AssetInputType; } });
 Object.defineProperty(exports, "AssetRefType", { enumerable: true, get: function () { return types_1.AssetRefType; } });
@@ -21,4 +21,3 @@ var assetGroup_1 = require("./assetGroup");
 Object.defineProperty(exports, "AssetGroup", { enumerable: true, get: function () { return assetGroup_1.AssetGroup; } });
 var packet_1 = require("./packet");
 Object.defineProperty(exports, "Packet", { enumerable: true, get: function () { return packet_1.Packet; } });
-Object.defineProperty(exports, "AssetPacketNotFoundError", { enumerable: true, get: function () { return packet_1.AssetPacketNotFoundError; } });

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

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Packet = void 0;
+const base_1 = require("@scure/base");
+const types_1 = require("./types");
+const assetGroup_1 = require("./assetGroup");
+const utils_1 = require("./utils");
+/**
+ * Packet represents a collection of asset groups.
+ * It encodes/decodes as raw bytes only — OP_RETURN framing is handled by the Extension module.
+ */
+class Packet {
+    constructor(groups) {
+        this.groups = groups;
+    }
+    static create(groups) {
+        const p = new Packet(groups);
+        p.validate();
+        return p;
+    }
+    /**
+     * fromBytes parses a Packet from raw bytes.
+     */
+    static fromBytes(buf) {
+        return Packet.fromReader(new utils_1.BufferReader(buf));
+    }
+    /**
+     * fromString parses a Packet from a raw hex string (not an OP_RETURN script).
+     */
+    static fromString(s) {
+        if (!s) {
+            throw new Error("missing packet data");
+        }
+        let buf;
+        try {
+            buf = base_1.hex.decode(s);
+        }
+        catch {
+            throw new Error("invalid packet format, must be hex");
+        }
+        return Packet.fromBytes(buf);
+    }
+    /**
+     * type returns the TLV packet type tag. Implements ExtensionPacket interface.
+     */
+    type() {
+        return Packet.PACKET_TYPE;
+    }
+    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
+     * added by the Extension module.
+     */
+    serialize() {
+        if (this.groups.length === 0) {
+            return new Uint8Array(0);
+        }
+        const writer = new utils_1.BufferWriter();
+        writer.writeVarUint(this.groups.length);
+        for (const group of this.groups) {
+            group.serializeTo(writer);
+        }
+        return writer.toBytes();
+    }
+    /**
+     * toString returns the hex-encoded raw packet bytes.
+     */
+    toString() {
+        return base_1.hex.encode(this.serialize());
+    }
+    validate() {
+        if (this.groups.length === 0) {
+            throw new Error("missing assets");
+        }
+        const seenAssetIds = new Set();
+        for (const group of this.groups) {
+            if (group.assetId !== null) {
+                const key = group.assetId.toString();
+                if (seenAssetIds.has(key)) {
+                    throw new Error(`duplicate asset group for asset ${key}`);
+                }
+                seenAssetIds.add(key);
+            }
+            if (group.controlAsset !== null &&
+                group.controlAsset.ref.type === types_1.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_1.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;
+    }
+}
+exports.Packet = Packet;
+/** PACKET_TYPE is the 1-byte TLV type tag used in the Extension envelope. */
+Packet.PACKET_TYPE = 0;

package/dist/cjs/{asset → extension/asset}/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MARKER_ASSET_PAYLOAD = exports.ARKADE_MAGIC = exports.MASK_METADATA = exports.MASK_CONTROL_ASSET = exports.MASK_ASSET_ID = exports.AssetRefType = exports.AssetInputType = exports.ASSET_VERSION = exports.ASSET_ID_SIZE = exports.TX_HASH_SIZE = void 0;
+exports.MASK_METADATA = exports.MASK_CONTROL_ASSET = exports.MASK_ASSET_ID = exports.AssetRefType = exports.AssetInputType = exports.ASSET_VERSION = exports.ASSET_ID_SIZE = exports.TX_HASH_SIZE = void 0;
 exports.TX_HASH_SIZE = 32;
 exports.ASSET_ID_SIZE = 34;
 exports.ASSET_VERSION = 0x01;
@@ -20,6 +20,3 @@ var AssetRefType;
 exports.MASK_ASSET_ID = 0x01;
 exports.MASK_CONTROL_ASSET = 0x02;
 exports.MASK_METADATA = 0x04;
-// ARK magic bytes and marker
-exports.ARKADE_MAGIC = new Uint8Array([0x41, 0x52, 0x4b]); // "ARK"
-exports.MARKER_ASSET_PAYLOAD = 0x00;

package/dist/cjs/extension/index.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Extension = exports.ExtensionNotFoundError = exports.ARKADE_MAGIC = exports.UnknownPacket = void 0;
+const base_1 = require("@scure/base");
+const btc_signer_1 = require("@scure/btc-signer");
+const utils_js_1 = require("@scure/btc-signer/utils.js");
+const packet_1 = require("./asset/packet");
+const utils_1 = require("./asset/utils");
+const packet_2 = require("./packet");
+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.
+ */
+exports.ARKADE_MAGIC = new Uint8Array([0x41, 0x52, 0x4b]); // "ARK"
+/**
+ * ErrExtensionNotFound is thrown when no extension output is found in a transaction.
+ */
+class ExtensionNotFoundError extends Error {
+    constructor() {
+        super("no extension output found in transaction");
+        this.name = "ExtensionNotFoundError";
+    }
+}
+exports.ExtensionNotFoundError = ExtensionNotFoundError;
+/**
+ * Extension is a set of typed packets encoded in an OP_RETURN output.
+ *
+ * Wire format:
+ *   OP_RETURN | <push> | ARK(3B) | [type(1B) | varint_len | data]...
+ */
+class Extension {
+    constructor(packets) {
+        this.packets = packets;
+    }
+    static create(packets) {
+        if (packets.length === 0) {
+            throw new Error("missing packets");
+        }
+        const seen = new Set();
+        for (const p of packets) {
+            if (seen.has(p.type())) {
+                throw new Error(`duplicate packet type ${p.type()}`);
+            }
+            seen.add(p.type());
+        }
+        return new Extension(packets);
+    }
+    /**
+     * isExtension returns true if the script is an OP_RETURN whose push data
+     * begins with the ARK magic bytes.
+     */
+    static isExtension(script) {
+        try {
+            const decoded = btc_signer_1.Script.decode(script);
+            if (decoded.length < 2 || decoded[0] !== "RETURN")
+                return false;
+            const data = decoded[1];
+            if (!(data instanceof Uint8Array))
+                return false;
+            return (data.length >= exports.ARKADE_MAGIC.length &&
+                (0, utils_js_1.equalBytes)(data.slice(0, exports.ARKADE_MAGIC.length), exports.ARKADE_MAGIC));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * fromBytes parses an Extension from a raw OP_RETURN script.
+     */
+    static fromBytes(script) {
+        if (!script || script.length === 0) {
+            throw new Error("missing OP_RETURN");
+        }
+        let decoded;
+        try {
+            decoded = btc_signer_1.Script.decode(script);
+        }
+        catch {
+            throw new Error("expected OP_RETURN");
+        }
+        if (decoded.length === 0 || decoded[0] !== "RETURN") {
+            throw new Error("expected OP_RETURN");
+        }
+        const dataPushes = decoded
+            .slice(1)
+            .filter((x) => x instanceof Uint8Array);
+        if (dataPushes.length === 0) {
+            throw new Error("missing magic prefix: EOF");
+        }
+        // Concatenate all data pushes (handles OP_PUSHDATA1/2/4)
+        const payload = new Uint8Array(dataPushes.reduce((acc, d) => acc + d.length, 0));
+        let offset = 0;
+        for (const d of dataPushes) {
+            payload.set(d, offset);
+            offset += d.length;
+        }
+        // Check ARK magic
+        if (payload.length < exports.ARKADE_MAGIC.length ||
+            !(0, utils_js_1.equalBytes)(payload.slice(0, exports.ARKADE_MAGIC.length), exports.ARKADE_MAGIC)) {
+            throw new Error(`expected magic prefix ${base_1.hex.encode(exports.ARKADE_MAGIC)}, got ${base_1.hex.encode(payload.slice(0, Math.min(payload.length, exports.ARKADE_MAGIC.length)))}`);
+        }
+        // Parse TLV records
+        const reader = new utils_1.BufferReader(payload.slice(exports.ARKADE_MAGIC.length));
+        const packets = [];
+        while (reader.remaining() > 0) {
+            const packetType = reader.readByte();
+            let data;
+            try {
+                data = reader.readVarSlice();
+            }
+            catch {
+                throw new Error("missing packet data");
+            }
+            packets.push(parsePacket(packetType, data));
+        }
+        if (packets.length === 0) {
+            throw new Error("missing packets");
+        }
+        // Reject duplicate packet types
+        const seen = new Set();
+        for (const p of packets) {
+            if (seen.has(p.type())) {
+                throw new Error(`duplicate packet type ${p.type()}`);
+            }
+            seen.add(p.type());
+        }
+        return new Extension(packets);
+    }
+    /**
+     * fromTx searches the transaction outputs for an extension blob and parses it.
+     * Throws ExtensionNotFoundError if none is found.
+     */
+    static fromTx(tx) {
+        for (let i = 0; i < tx.outputsLength; i++) {
+            const output = tx.getOutput(i);
+            if (!output?.script)
+                continue;
+            if (Extension.isExtension(output.script)) {
+                return Extension.fromBytes(output.script);
+            }
+        }
+        throw new ExtensionNotFoundError();
+    }
+    /**
+     * serialize encodes the extension as an OP_RETURN script.
+     *
+     * Layout: OP_RETURN | <push> | ARK | [type | varint_len | data]...
+     */
+    serialize() {
+        // Build payload: ARK magic + TLV records
+        const parts = [exports.ARKADE_MAGIC];
+        for (const p of this.packets) {
+            const data = p.serialize();
+            // type (1 byte)
+            const typeByte = new Uint8Array([p.type()]);
+            // varint length prefix + data
+            const lengthBuf = encodeVarUint(data.length);
+            parts.push(typeByte, lengthBuf, data);
+        }
+        const totalLen = parts.reduce((acc, p) => acc + p.length, 0);
+        const payload = new Uint8Array(totalLen);
+        let off = 0;
+        for (const p of parts) {
+            payload.set(p, off);
+            off += p.length;
+        }
+        return buildOpReturnScript(payload);
+    }
+    /**
+     * txOut returns the extension as a zero-value OP_RETURN transaction output.
+     */
+    txOut() {
+        return {
+            script: this.serialize(),
+            amount: 0n,
+        };
+    }
+    /**
+     * getAssetPacket returns the embedded Packet, or null if not present.
+     */
+    getAssetPacket() {
+        for (const p of this.packets) {
+            if (p instanceof packet_1.Packet) {
+                return p;
+            }
+        }
+        return null;
+    }
+}
+exports.Extension = Extension;
+/**
+ * parsePacket dispatches to a known packet type or falls back to UnknownPacket.
+ */
+function parsePacket(packetType, data) {
+    if (packetType === packet_1.Packet.PACKET_TYPE) {
+        return packet_1.Packet.fromBytes(data);
+    }
+    return new packet_2.UnknownPacket(packetType, data);
+}
+/**
+ * encodeVarUint encodes a non-negative integer as a LEB128 unsigned varint.
+ */
+function encodeVarUint(value) {
+    const bytes = [];
+    let remaining = value;
+    do {
+        let byte = remaining & 0x7f;
+        remaining >>>= 7;
+        if (remaining > 0)
+            byte |= 0x80;
+        bytes.push(byte);
+    } while (remaining > 0);
+    return new Uint8Array(bytes);
+}
+/**
+ * buildOpReturnScript builds an OP_RETURN script with an arbitrary-length data push.
+ * Manually constructed to avoid the 520-byte cap in some script builders.
+ *
+ * Opcodes: 0x6a=OP_RETURN, 0x4c=OP_PUSHDATA1, 0x4d=OP_PUSHDATA2, 0x4e=OP_PUSHDATA4
+ */
+function buildOpReturnScript(data) {
+    const n = data.length;
+    let script;
+    if (n <= 75) {
+        script = new Uint8Array(2 + n);
+        script[0] = 0x6a; // OP_RETURN
+        script[1] = n;
+        script.set(data, 2);
+    }
+    else if (n <= 255) {
+        script = new Uint8Array(3 + n);
+        script[0] = 0x6a;
+        script[1] = 0x4c; // OP_PUSHDATA1
+        script[2] = n;
+        script.set(data, 3);
+    }
+    else if (n <= 65535) {
+        script = new Uint8Array(4 + n);
+        script[0] = 0x6a;
+        script[1] = 0x4d; // OP_PUSHDATA2
+        new DataView(script.buffer).setUint16(2, n, true);
+        script.set(data, 4);
+    }
+    else {
+        script = new Uint8Array(6 + n);
+        script[0] = 0x6a;
+        script[1] = 0x4e; // OP_PUSHDATA4
+        new DataView(script.buffer).setUint32(2, n, true);
+        script.set(data, 6);
+    }
+    return script;
+}

package/dist/cjs/extension/packet.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownPacket = void 0;
+/**
+ * UnknownPacket holds a packet whose type is not recognized by this implementation.
+ * It round-trips opaquely: the raw bytes are preserved as-is.
+ */
+class UnknownPacket {
+    constructor(packetType, data) {
+        this.packetType = packetType;
+        this.data = data;
+    }
+    type() {
+        return this.packetType;
+    }
+    serialize() {
+        return this.data;
+    }
+}
+exports.UnknownPacket = UnknownPacket;

package/dist/cjs/index.js

@@ -156,7 +156,7 @@ Object.defineProperty(exports, "ContractRepositoryImpl", { enumerable: true, get
 const delegator_2 = require("./wallet/delegator");
 Object.defineProperty(exports, "DelegatorManagerImpl", { enumerable: true, get: function () { return delegator_2.DelegatorManagerImpl; } });
 __exportStar(require("./arkfee"), exports);
-exports.asset = __importStar(require("./asset"));
+exports.asset = __importStar(require("./extension/asset"));
 // Contracts
 const contracts_1 = require("./contracts");
 Object.defineProperty(exports, "ContractManager", { enumerable: true, get: function () { return contracts_1.ContractManager; } });

package/dist/cjs/providers/ark.js

@@ -225,54 +225,69 @@ class RestArkProvider {
             handleError(errorText, `Failed to submit forfeit transactions: ${response.statusText}`);
         }
     }
-    async *getEventStream(signal, topics) {
+    getEventStream(signal, topics) {
         const url = `${this.serverUrl}/v1/batch/events`;
         const queryParams = topics.length > 0
             ? `?${topics.map((topic) => `topics=${encodeURIComponent(topic)}`).join("&")}`
             : "";
-        while (!signal?.aborted) {
-            try {
-                const eventSource = new EventSource(url + queryParams);
-                // Set up abort handling
-                const abortHandler = () => {
-                    eventSource.close();
-                };
-                signal?.addEventListener("abort", abortHandler);
+        // Create first EventSource eagerly so events are buffered
+        // before the caller starts iterating, preventing race conditions
+        // where the server emits events before iteration begins.
+        const eagerEventSource = new EventSource(url + queryParams);
+        const eagerIterator = (0, utils_1.eventSourceIterator)(eagerEventSource);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        return (async function* () {
+            let firstIteration = true;
+            while (!signal?.aborted) {
+                const eventSource = firstIteration
+                    ? eagerEventSource
+                    : new EventSource(url + queryParams);
+                const iterator = firstIteration
+                    ? eagerIterator
+                    : (0, utils_1.eventSourceIterator)(eventSource);
+                firstIteration = false;
                 try {
-                    for await (const event of (0, utils_1.eventSourceIterator)(eventSource)) {
-                        if (signal?.aborted)
-                            break;
-                        try {
-                            const data = JSON.parse(event.data);
-                            const settlementEvent = this.parseSettlementEvent(data);
-                            if (settlementEvent) {
-                                yield settlementEvent;
+                    const abortHandler = () => {
+                        eventSource.close();
+                    };
+                    signal?.addEventListener("abort", abortHandler);
+                    try {
+                        for await (const event of iterator) {
+                            if (signal?.aborted)
+                                break;
+                            try {
+                                const data = JSON.parse(event.data);
+                                const settlementEvent = self.parseSettlementEvent(data);
+                                if (settlementEvent) {
+                                    yield settlementEvent;
+                                }
+                            }
+                            catch (err) {
+                                console.error("Failed to parse event:", err);
+                                throw err;
                             }
-                        }
-                        catch (err) {
-                            console.error("Failed to parse event:", err);
-                            throw err;
                         }
                     }
+                    finally {
+                        signal?.removeEventListener("abort", abortHandler);
+                        eventSource.close();
+                    }
                 }
-                finally {
-                    signal?.removeEventListener("abort", abortHandler);
-                    eventSource.close();
-                }
-            }
-            catch (error) {
-                if (error instanceof Error && error.name === "AbortError") {
-                    break;
-                }
-                // ignore timeout errors, they're expected when the server is not sending anything for 5 min
-                if (isFetchTimeoutError(error)) {
-                    console.debug("Timeout error ignored");
-                    continue;
+                catch (error) {
+                    if (error instanceof Error && error.name === "AbortError") {
+                        break;
+                    }
+                    // ignore timeout errors, they're expected when the server is not sending anything for 5 min
+                    if (isFetchTimeoutError(error)) {
+                        console.debug("Timeout error ignored");
+                        continue;
+                    }
+                    console.error("Event stream error:", error);
+                    throw error;
                 }
-                console.error("Event stream error:", error);
-                throw error;
             }
-        }
+        })();
     }
     async *getTransactionsStream(signal) {
         const url = `${this.serverUrl}/v1/txs`;

package/dist/cjs/providers/indexer.js

@@ -4,7 +4,7 @@ exports.RestIndexerProvider = exports.ChainTxType = exports.IndexerTxType = void
 const base_1 = require("@scure/base");
 const ark_1 = require("./ark");
 const utils_1 = require("./utils");
-const asset_1 = require("../asset");
+const asset_1 = require("../extension/asset");
 var IndexerTxType;
 (function (IndexerTxType) {
     IndexerTxType[IndexerTxType["INDEXER_TX_TYPE_UNSPECIFIED"] = 0] = "INDEXER_TX_TYPE_UNSPECIFIED";

package/dist/cjs/providers/utils.js

@@ -1,7 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.eventSourceIterator = eventSourceIterator;
-async function* eventSourceIterator(eventSource) {
+/**
+ * Creates an async iterator over EventSource messages that attaches listeners
+ * eagerly (at call time) rather than lazily (at first .next() call).
+ * This ensures events are buffered immediately, preventing race conditions
+ * where events arrive before iteration begins.
+ */
+function eventSourceIterator(eventSource) {
     const messageQueue = [];
     const errorQueue = [];
     let messageResolve = null;
@@ -26,36 +32,40 @@ async function* eventSourceIterator(eventSource) {
             errorQueue.push(error);
         }
     };
+    // Attach listeners immediately so events are buffered
+    // even before the caller starts iterating
     eventSource.addEventListener("message", messageHandler);
     eventSource.addEventListener("error", errorHandler);
-    try {
-        while (true) {
-            // if we have queued messages, yield the first one, remove it from the queue
-            if (messageQueue.length > 0) {
-                yield messageQueue.shift();
-                continue;
-            }
-            // if we have queued errors, throw the first one, remove it from the queue
-            if (errorQueue.length > 0) {
-                const error = errorQueue.shift();
-                throw error;
-            }
-            // wait for the next message or error
-            const result = await new Promise((resolve, reject) => {
-                messageResolve = resolve;
-                errorResolve = reject;
-            }).finally(() => {
-                messageResolve = null;
-                errorResolve = null;
-            });
-            if (result) {
-                yield result;
+    return (async function* () {
+        try {
+            while (true) {
+                // if we have queued messages, yield the first one, remove it from the queue
+                if (messageQueue.length > 0) {
+                    yield messageQueue.shift();
+                    continue;
+                }
+                // if we have queued errors, throw the first one, remove it from the queue
+                if (errorQueue.length > 0) {
+                    const error = errorQueue.shift();
+                    throw error;
+                }
+                // wait for the next message or error
+                const result = await new Promise((resolve, reject) => {
+                    messageResolve = resolve;
+                    errorResolve = reject;
+                }).finally(() => {
+                    messageResolve = null;
+                    errorResolve = null;
+                });
+                if (result) {
+                    yield result;
+                }
             }
         }
-    }
-    finally {
-        // clean up
-        eventSource.removeEventListener("message", messageHandler);
-        eventSource.removeEventListener("error", errorHandler);
-    }
+        finally {
+            // clean up
+            eventSource.removeEventListener("message", messageHandler);
+            eventSource.removeEventListener("error", errorHandler);
+        }
+    })();
 }