@arkade-os/sdk 0.3.13 → 0.4.0-next.1

package/dist/esm/worker/browser/service-worker-manager.js

@@ -0,0 +1,76 @@
+const registrations = new Map();
+function ensureServiceWorkerSupport() {
+    if (!("serviceWorker" in navigator)) {
+        throw new Error("Service workers are not supported in this browser");
+    }
+}
+function registerOnce(path) {
+    if (!registrations.has(path)) {
+        const registrationPromise = navigator.serviceWorker
+            .register(path)
+            .then(async (registration) => {
+            try {
+                await registration.update();
+            }
+            catch (error) {
+                console.warn("Service worker update failed; continuing with registration", error);
+            }
+            return registration;
+        })
+            .catch((error) => {
+            // delete failed registration to allow retrials
+            registrations.delete(path);
+            throw error;
+        });
+        registrations.set(path, registrationPromise);
+    }
+    return registrations.get(path);
+}
+/**
+ * Registers a service worker for the given path only once and caches the
+ * registration promise for subsequent calls.
+ *
+ * @param path - Service worker script path to register.
+ * @throws if service workers are not supported or registration fails.
+ */
+export async function setupServiceWorkerOnce(path) {
+    ensureServiceWorkerSupport();
+    return registerOnce(path);
+}
+/**
+ * Returns an active service worker instance, optionally ensuring a specific
+ * script path is registered before resolving.
+ *
+ * @param path - Optional service worker script path to register and prefer.
+ * @throws if service workers are not supported or no active worker is available.
+ */
+export async function getActiveServiceWorker(path) {
+    ensureServiceWorkerSupport();
+    // Avoid mixing registrations when a specific script path is provided.
+    const registration = path
+        ? await registerOnce(path)
+        : await navigator.serviceWorker.ready;
+    let serviceWorker = registration.active ||
+        registration.waiting ||
+        registration.installing ||
+        navigator.serviceWorker.controller;
+    if (!serviceWorker && path) {
+        const readyRegistration = await navigator.serviceWorker.ready;
+        serviceWorker =
+            readyRegistration.active ||
+                readyRegistration.waiting ||
+                readyRegistration.installing ||
+                navigator.serviceWorker.controller;
+    }
+    if (!serviceWorker) {
+        throw new Error("Service worker not ready yet");
+    }
+    return serviceWorker;
+}
+/**
+ * Clears the cached registration promises.
+ * Intended for tests to reset state between runs.
+ */
+export const __resetServiceWorkerManager = () => {
+    registrations.clear();
+};

package/dist/esm/{wallet/serviceWorker → worker/browser}/utils.js

@@ -2,9 +2,10 @@ export const DEFAULT_DB_NAME = "arkade-service-worker";
 /**
  * setupServiceWorker sets up the service worker.
  * @param path - the path to the service worker script
+ * @throws if service workers are not supported or activation fails
  * @example
  * ```typescript
- * const serviceWorker = await setupServiceWorker("/service-worker.js");
+ * const worker = await setupServiceWorker("/service-worker.js");
  * ```
  */
 export async function setupServiceWorker(path) {

package/dist/esm/worker/expo/asyncStorageTaskQueue.js

@@ -0,0 +1,74 @@
+/**
+ * AsyncStorage-backed TaskQueue for Expo/React Native.
+ *
+ * Persists inbox, outbox, and an optional config blob to AsyncStorage
+ * so that data survives process restarts and can be shared between
+ * foreground and background execution contexts.
+ */
+export class AsyncStorageTaskQueue {
+    constructor(storage, prefix = "ark:task-queue") {
+        this.storage = storage;
+        this.inboxKey = `${prefix}:inbox`;
+        this.outboxKey = `${prefix}:outbox`;
+        this.configKey = `${prefix}:config`;
+    }
+    // ── Inbox ────────────────────────────────────────────────────────
+    async addTask(task) {
+        const tasks = await this.readList(this.inboxKey);
+        tasks.push(task);
+        await this.writeList(this.inboxKey, tasks);
+    }
+    async removeTask(id) {
+        const tasks = await this.readList(this.inboxKey);
+        await this.writeList(this.inboxKey, tasks.filter((t) => t.id !== id));
+    }
+    async getTasks(type) {
+        const tasks = await this.readList(this.inboxKey);
+        if (type) {
+            return tasks.filter((t) => t.type === type);
+        }
+        return tasks;
+    }
+    async clearTasks() {
+        await this.storage.removeItem(this.inboxKey);
+    }
+    // ── Outbox ───────────────────────────────────────────────────────
+    async pushResult(result) {
+        const results = await this.readList(this.outboxKey);
+        results.push(result);
+        await this.writeList(this.outboxKey, results);
+    }
+    async getResults() {
+        return this.readList(this.outboxKey);
+    }
+    async acknowledgeResults(ids) {
+        const idSet = new Set(ids);
+        const results = await this.readList(this.outboxKey);
+        await this.writeList(this.outboxKey, results.filter((r) => !idSet.has(r.id)));
+    }
+    // ── Config persistence (for background handler rehydration) ──────
+    /**
+     * Persist a config blob alongside the queue data.
+     * Used by {@link ExpoWallet.setup} to store the wallet parameters
+     * that the background handler needs to reconstruct providers.
+     */
+    async persistConfig(config) {
+        await this.storage.setItem(this.configKey, JSON.stringify(config));
+    }
+    /**
+     * Load the persisted config blob.
+     * Used by the background handler to rehydrate wallet dependencies.
+     */
+    async loadConfig() {
+        const raw = await this.storage.getItem(this.configKey);
+        return raw ? JSON.parse(raw) : null;
+    }
+    // ── Helpers ──────────────────────────────────────────────────────
+    async readList(key) {
+        const raw = await this.storage.getItem(key);
+        return raw ? JSON.parse(raw) : [];
+    }
+    async writeList(key, list) {
+        await this.storage.setItem(key, JSON.stringify(list));
+    }
+}

package/dist/esm/worker/expo/index.js

@@ -0,0 +1,4 @@
+export { InMemoryTaskQueue } from './taskQueue.js';
+export { AsyncStorageTaskQueue } from './asyncStorageTaskQueue.js';
+export { runTasks } from './taskRunner.js';
+export { contractPollProcessor, CONTRACT_POLL_TASK_TYPE } from './processors/index.js';

package/dist/esm/worker/expo/processors/contractPollProcessor.js

@@ -0,0 +1,58 @@
+export const CONTRACT_POLL_TASK_TYPE = "contract-poll";
+/**
+ * Polls the indexer for the latest VTXO state of every contract and
+ * persists the results to the wallet repository.
+ *
+ * Replicates the polling subset of {@link ContractManager.initialize}:
+ * 1. Load all contracts from the contract repository.
+ * 2. Mark expired active contracts as inactive.
+ * 3. Paginated fetch of spendable VTXOs from the indexer.
+ * 4. Extend each VTXO with tapscript data.
+ * 5. Save to the wallet repository.
+ */
+export const contractPollProcessor = {
+    taskType: CONTRACT_POLL_TASK_TYPE,
+    async execute(item, deps) {
+        const { contractRepository, walletRepository, indexerProvider, extendVtxo, } = deps;
+        const contracts = await contractRepository.getContracts();
+        const now = Date.now();
+        let contractsProcessed = 0;
+        let vtxosSaved = 0;
+        for (const contract of contracts) {
+            // Mark expired active contracts as inactive
+            if (contract.state === "active" &&
+                contract.expiresAt &&
+                contract.expiresAt <= now) {
+                contract.state = "inactive";
+                await contractRepository.saveContract(contract);
+            }
+            // Paginated fetch of spendable VTXOs
+            const pageSize = 100;
+            let pageIndex = 0;
+            let hasMore = true;
+            const allVtxos = [];
+            while (hasMore) {
+                const { vtxos, page } = await indexerProvider.getVtxos({
+                    scripts: [contract.script],
+                    spendableOnly: true,
+                    pageIndex,
+                    pageSize,
+                });
+                for (const vtxo of vtxos) {
+                    allVtxos.push(extendVtxo(vtxo, contract));
+                }
+                hasMore = page ? vtxos.length === pageSize : false;
+                pageIndex++;
+            }
+            await walletRepository.saveVtxos(contract.address, allVtxos);
+            vtxosSaved += allVtxos.length;
+            contractsProcessed++;
+        }
+        return {
+            taskItemId: item.id,
+            type: CONTRACT_POLL_TASK_TYPE,
+            status: "success",
+            data: { contractsProcessed, vtxosSaved },
+        };
+    },
+};

package/dist/esm/worker/expo/processors/index.js

@@ -0,0 +1 @@
+export { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from './contractPollProcessor.js';

package/dist/esm/worker/expo/taskQueue.js

@@ -0,0 +1,37 @@
+/**
+ * In-memory TaskQueue for testing and lightweight use.
+ * State is lost when the process exits.
+ */
+export class InMemoryTaskQueue {
+    constructor() {
+        this.inbox = new Map();
+        this.outbox = new Map();
+    }
+    async addTask(task) {
+        this.inbox.set(task.id, task);
+    }
+    async removeTask(id) {
+        this.inbox.delete(id);
+    }
+    async getTasks(type) {
+        const tasks = Array.from(this.inbox.values());
+        if (type) {
+            return tasks.filter((t) => t.type === type);
+        }
+        return tasks;
+    }
+    async clearTasks() {
+        this.inbox.clear();
+    }
+    async pushResult(result) {
+        this.outbox.set(result.id, result);
+    }
+    async getResults() {
+        return Array.from(this.outbox.values());
+    }
+    async acknowledgeResults(ids) {
+        for (const id of ids) {
+            this.outbox.delete(id);
+        }
+    }
+}

package/dist/esm/worker/expo/taskRunner.js

@@ -0,0 +1,54 @@
+import { getRandomId } from '../../wallet/utils.js';
+/**
+ * Run all pending tasks from the queue through matching processors.
+ *
+ * For each task in the inbox:
+ * 1. Find the processor whose `taskType` matches `task.type`.
+ * 2. Execute it, producing a {@link TaskResult}.
+ * 3. Push the result to the outbox and remove the task from the inbox.
+ *
+ * Tasks with no matching processor produce a `"noop"` result.
+ * Processor errors produce a `"failed"` result with the error message.
+ */
+export async function runTasks(queue, processors, deps) {
+    const tasks = await queue.getTasks();
+    const processorMap = new Map(processors.map((p) => [p.taskType, p]));
+    const results = [];
+    for (const task of tasks) {
+        const processor = processorMap.get(task.type);
+        let partial;
+        if (!processor) {
+            partial = {
+                taskItemId: task.id,
+                type: task.type,
+                status: "noop",
+            };
+        }
+        else {
+            try {
+                partial = await processor.execute(task, deps);
+            }
+            catch (error) {
+                partial = {
+                    taskItemId: task.id,
+                    type: task.type,
+                    status: "failed",
+                    data: {
+                        error: error instanceof Error
+                            ? error.message
+                            : String(error),
+                    },
+                };
+            }
+        }
+        const result = {
+            ...partial,
+            id: getRandomId(),
+            executedAt: Date.now(),
+        };
+        await queue.pushResult(result);
+        await queue.removeTask(task.id);
+        results.push(result);
+    }
+    return results;
+}

package/dist/esm/worker/messageBus.js

@@ -0,0 +1,248 @@
+/// <reference lib="webworker" />
+import { getActiveServiceWorker, setupServiceWorkerOnce, } from './browser/service-worker-manager.js';
+import { RestArkProvider } from '../providers/ark.js';
+import { ReadonlySingleKey, SingleKey } from '../identity/index.js';
+import { ReadonlyWallet, Wallet } from '../wallet/wallet.js';
+import { hex } from "@scure/base";
+export class MessageBus {
+    constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, debug = false, buildServices, }) {
+        this.walletRepository = walletRepository;
+        this.contractRepository = contractRepository;
+        this.running = false;
+        this.tickTimeout = null;
+        this.tickInProgress = false;
+        this.debug = false;
+        this.initialized = false;
+        this.handlers = new Map(messageHandlers.map((u) => [u.messageTag, u]));
+        this.tickIntervalMs = tickIntervalMs;
+        this.debug = debug;
+        this.buildServicesFn = buildServices ?? this.buildServices.bind(this);
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        if (this.debug)
+            console.log("MessageBus starting");
+        // Hook message routing
+        self.addEventListener("message", this.onMessage.bind(this));
+        // activate service worker immediately
+        self.addEventListener("install", () => {
+            self.skipWaiting();
+        });
+        // take control of clients immediately
+        self.addEventListener("activate", () => {
+            self.clients.claim();
+            if (this.initialized) {
+                this.runTick();
+            }
+        });
+    }
+    async stop() {
+        if (this.debug)
+            console.log("MessageBus stopping");
+        this.running = false;
+        this.tickInProgress = false;
+        this.initialized = false;
+        if (this.tickTimeout !== null) {
+            self.clearTimeout(this.tickTimeout);
+            this.tickTimeout = null;
+        }
+        self.removeEventListener("message", this.onMessage.bind(this));
+        await Promise.all(Array.from(this.handlers.values()).map((updater) => updater.stop()));
+    }
+    scheduleNextTick() {
+        if (!this.running)
+            return;
+        if (this.tickTimeout !== null)
+            return;
+        if (this.tickInProgress)
+            return;
+        this.tickTimeout = self.setTimeout(() => this.runTick(), this.tickIntervalMs);
+    }
+    async runTick() {
+        if (!this.running)
+            return;
+        if (this.tickInProgress)
+            return;
+        this.tickInProgress = true;
+        if (this.tickTimeout !== null) {
+            self.clearTimeout(this.tickTimeout);
+            this.tickTimeout = null;
+        }
+        try {
+            const now = Date.now();
+            for (const updater of this.handlers.values()) {
+                try {
+                    const response = await updater.tick(now);
+                    if (this.debug)
+                        console.log(`[${updater.messageTag}] outgoing tick response:`, response);
+                    if (response && response.length > 0) {
+                        self.clients
+                            .matchAll({
+                            includeUncontrolled: true,
+                            type: "window",
+                        })
+                            .then((clients) => {
+                            for (const message of response) {
+                                clients.forEach((client) => {
+                                    client.postMessage(message);
+                                });
+                            }
+                        });
+                    }
+                }
+                catch (err) {
+                    if (this.debug)
+                        console.error(`[${updater.messageTag}] tick failed`, err);
+                }
+            }
+        }
+        finally {
+            this.tickInProgress = false;
+            this.scheduleNextTick();
+        }
+    }
+    async waitForInit(config) {
+        if (this.initialized)
+            return;
+        const services = await this.buildServicesFn(config);
+        // Start all handlers
+        for (const updater of this.handlers.values()) {
+            if (this.debug)
+                console.log(`Starting updater: ${updater.messageTag}`);
+            await updater.start(services, {
+                walletRepository: this.walletRepository,
+            });
+        }
+        // Kick off scheduler
+        this.scheduleNextTick();
+        this.initialized = true;
+    }
+    async buildServices(config) {
+        const arkProvider = new RestArkProvider(config.arkServer.url);
+        const storage = {
+            walletRepository: this.walletRepository,
+            contractRepository: this.contractRepository,
+        };
+        if ("privateKey" in config.wallet) {
+            const identity = SingleKey.fromHex(config.wallet.privateKey);
+            const wallet = await Wallet.create({
+                identity,
+                arkServerUrl: config.arkServer.url,
+                arkServerPublicKey: config.arkServer.publicKey,
+                storage,
+            });
+            return { wallet, arkProvider, readonlyWallet: wallet };
+        }
+        else if ("publicKey" in config.wallet) {
+            const identity = ReadonlySingleKey.fromPublicKey(hex.decode(config.wallet.publicKey));
+            const readonlyWallet = await ReadonlyWallet.create({
+                identity,
+                arkServerUrl: config.arkServer.url,
+                arkServerPublicKey: config.arkServer.publicKey,
+                storage,
+            });
+            return { readonlyWallet, arkProvider };
+        }
+        else {
+            throw new Error("Missing privateKey or publicKey in configuration object");
+        }
+    }
+    async onMessage(event) {
+        const { id, tag, broadcast } = event.data;
+        if (tag === "INITIALIZE_MESSAGE_BUS") {
+            if (this.debug) {
+                console.log("Init Command received");
+            }
+            await this.waitForInit(event.data.config);
+            event.source?.postMessage({ id, tag });
+            if (this.debug) {
+                console.log("MessageBus initialized");
+            }
+            return;
+        }
+        if (!this.initialized) {
+            if (this.debug)
+                console.warn("Event received before initialization, dropping", event.data);
+            return;
+        }
+        if (!id || !tag) {
+            if (this.debug)
+                console.error("Invalid message received, missing required fields:", event.data);
+            event.source?.postMessage({
+                id,
+                tag: tag ?? "unknown",
+                error: new TypeError("Invalid message received, missing required fields"),
+            });
+            return;
+        }
+        if (broadcast) {
+            const updaters = Array.from(this.handlers.values());
+            const results = await Promise.allSettled(updaters.map((updater) => updater.handleMessage(event.data)));
+            results.forEach((result, index) => {
+                const updater = updaters[index];
+                if (result.status === "fulfilled") {
+                    const response = result.value;
+                    if (response) {
+                        event.source?.postMessage(response);
+                    }
+                }
+                else {
+                    if (this.debug)
+                        console.error(`[${updater.messageTag}] handleMessage failed`, result.reason);
+                    const error = result.reason instanceof Error
+                        ? result.reason
+                        : new Error(String(result.reason));
+                    event.source?.postMessage({
+                        id,
+                        tag: updater.messageTag,
+                        error,
+                    });
+                }
+            });
+            return;
+        }
+        const updater = this.handlers.get(tag);
+        if (!updater) {
+            if (this.debug)
+                console.warn(`[${tag}] unknown message tag, ignoring message`);
+            return;
+        }
+        try {
+            const response = await updater.handleMessage(event.data);
+            if (this.debug)
+                console.log(`[${tag}] outgoing response:`, response);
+            if (response) {
+                event.source?.postMessage(response);
+            }
+        }
+        catch (err) {
+            if (this.debug)
+                console.error(`[${tag}] handleMessage failed`, err);
+            const error = err instanceof Error ? err : new Error(String(err));
+            event.source?.postMessage({ id, tag, error });
+        }
+    }
+    /**
+     * Returns the registered SW for the path.
+     * It uses the functions in `service-worker-manager.ts` module.
+     * @param path
+     * @return the Service Worker
+     * @throws if not running in a browser environment
+     */
+    static async getServiceWorker(path) {
+        return getActiveServiceWorker(path);
+    }
+    /**
+     * Set up and register the Service Worker, ensuring it's done once at most.
+     * It uses the functions in `service-worker-manager.ts` module.
+     * @param path
+     * @return the Service Worker
+     * @throws if not running in a browser environment
+     */
+    static async setup(path) {
+        await setupServiceWorkerOnce(path);
+        return getActiveServiceWorker(path);
+    }
+}

package/dist/types/asset/assetGroup.d.ts

@@ -0,0 +1,28 @@
+import { AssetId } from "./assetId";
+import { AssetRef } from "./assetRef";
+import { AssetInput } from "./assetInput";
+import { AssetOutput } from "./assetOutput";
+import { Metadata } from "./metadata";
+import { BufferReader, BufferWriter } from "./utils";
+/**
+ * An asset group contains inputs/outputs and all data related to a given asset id.
+ */
+export declare class AssetGroup {
+    readonly assetId: AssetId | null;
+    readonly controlAsset: AssetRef | null;
+    readonly inputs: AssetInput[];
+    readonly outputs: AssetOutput[];
+    private readonly metadataList;
+    constructor(assetId: AssetId | null, controlAsset: AssetRef | null, inputs: AssetInput[], outputs: AssetOutput[], metadata: Metadata[]);
+    static create(assetId: AssetId | null, controlAsset: AssetRef | null, inputs: AssetInput[], outputs: AssetOutput[], metadata: Metadata[]): AssetGroup;
+    static fromString(s: string): AssetGroup;
+    static fromBytes(buf: Uint8Array): AssetGroup;
+    isIssuance(): boolean;
+    isReissuance(): boolean;
+    serialize(): Uint8Array;
+    validate(): void;
+    toBatchLeafAssetGroup(intentTxid: Uint8Array): AssetGroup;
+    toString(): string;
+    static fromReader(reader: BufferReader): AssetGroup;
+    serializeTo(writer: BufferWriter): void;
+}

package/dist/types/asset/assetId.d.ts

@@ -0,0 +1,19 @@
+import { BufferReader, BufferWriter } from "./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
+ */
+export declare class AssetId {
+    readonly txid: Uint8Array;
+    readonly groupIndex: number;
+    private constructor();
+    static create(txid: string, groupIndex: number): AssetId;
+    static fromString(s: string): AssetId;
+    static fromBytes(buf: Uint8Array): AssetId;
+    serialize(): Uint8Array;
+    toString(): string;
+    validate(): void;
+    static fromReader(reader: BufferReader): AssetId;
+    serializeTo(writer: BufferWriter): void;
+}

package/dist/types/asset/assetInput.d.ts

@@ -0,0 +1,46 @@
+import { AssetInputType } from "./types";
+import { BufferReader, BufferWriter } from "./utils";
+type AssetInputLocal = {
+    type: AssetInputType.Local;
+    vin: number;
+    amount: bigint;
+};
+type AssetInputIntent = Pick<AssetInputLocal, "vin" | "amount"> & {
+    type: AssetInputType.Intent;
+    txid: Uint8Array;
+};
+/**
+ * AssetInput represents an input of an asset group.
+ * a local input references a real transaction input and specify the amount in satoshis.
+ * an intent input references an external intent transaction. It is created by the server to handle batch leaf transaction.
+ */
+export declare class AssetInput {
+    readonly input: AssetInputLocal | AssetInputIntent;
+    private constructor();
+    get vin(): number;
+    get amount(): bigint;
+    static create(vin: number, amount: bigint | number): AssetInput;
+    static createIntent(txid: string, vin: number, amount: bigint | number): AssetInput;
+    static fromString(s: string): AssetInput;
+    static fromBytes(buf: Uint8Array): AssetInput;
+    serialize(): Uint8Array;
+    toString(): string;
+    validate(): void;
+    static fromReader(reader: BufferReader): AssetInput;
+    serializeTo(writer: BufferWriter): void;
+}
+/**
+ * AssetInputs represents a list of asset inputs.
+ */
+export declare class AssetInputs {
+    readonly inputs: AssetInput[];
+    private constructor();
+    static create(inputs: AssetInput[]): AssetInputs;
+    static fromString(s: string): AssetInputs;
+    serialize(): Uint8Array;
+    toString(): string;
+    validate(): void;
+    static fromReader(reader: BufferReader): AssetInputs;
+    serializeTo(writer: BufferWriter): void;
+}
+export {};