@1sat/wallet-toolbox 0.0.5 → 0.0.7

package/dist/services/OneSatServices.js

@@ -0,0 +1,231 @@
+import { Beef, Hash, MerklePath, Transaction, Utils } from "@bsv/sdk";
+/**
+ * Simple error class for WalletServices error responses.
+ */
+class ServiceError extends Error {
+    code;
+    description;
+    isError = true;
+    constructor(code, description) {
+        super(description);
+        this.code = code;
+        this.description = description;
+        this.name = code;
+    }
+}
+import { ArcadeClient, BeefClient, Bsv21Client, ChaintracksClient, OrdfsClient, OwnerClient, TxoClient, } from "./client";
+/**
+ * WalletServices implementation for 1Sat ecosystem.
+ *
+ * Provides access to 1Sat API clients and implements the WalletServices
+ * interface required by wallet-toolbox.
+ *
+ * API Routes:
+ * - /1sat/chaintracks/* - Block headers and chain tracking
+ * - /1sat/beef/* - Raw transactions and proofs
+ * - /1sat/arcade/* - Transaction broadcasting
+ * - /1sat/bsv21/* - BSV21 token data
+ * - /1sat/txo/* - Transaction outputs
+ * - /1sat/owner/* - Address queries and sync
+ * - /1sat/ordfs/* - Content/inscription serving
+ */
+export class OneSatServices {
+    chain;
+    baseUrl;
+    storage;
+    // ===== API Clients =====
+    chaintracks;
+    beef;
+    arcade;
+    txo;
+    owner;
+    ordfs;
+    bsv21;
+    constructor(chain, baseUrl, storage) {
+        this.chain = chain;
+        this.baseUrl =
+            baseUrl ||
+                (chain === "main"
+                    ? "https://1sat.shruggr.cloud"
+                    : "https://testnet.api.1sat.app");
+        this.storage = storage;
+        const opts = { timeout: 30000 };
+        this.chaintracks = new ChaintracksClient(this.baseUrl, opts);
+        this.beef = new BeefClient(this.baseUrl, opts);
+        this.arcade = new ArcadeClient(this.baseUrl, opts);
+        this.txo = new TxoClient(this.baseUrl, opts);
+        this.owner = new OwnerClient(this.baseUrl, opts);
+        this.ordfs = new OrdfsClient(this.baseUrl, opts);
+        this.bsv21 = new Bsv21Client(this.baseUrl, opts);
+    }
+    // ===== Utility Methods =====
+    /**
+     * Get list of enabled capabilities from the server
+     */
+    async getCapabilities() {
+        const response = await fetch(`${this.baseUrl}/capabilities`);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch capabilities: ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Close all client connections
+     */
+    close() {
+        this.chaintracks.close();
+    }
+    // ===== WalletServices Interface (Required by wallet-toolbox) =====
+    async getRawTx(txid, _useNext) {
+        // This is a network-only call for the WalletServices interface.
+        // Wallet should check storage before calling this.
+        try {
+            const beefBytes = await this.beef.getBeef(txid);
+            const tx = Transaction.fromBEEF(Array.from(beefBytes));
+            return { txid, name: "1sat-api", rawTx: Array.from(tx.toBinary()) };
+        }
+        catch (error) {
+            return {
+                txid,
+                error: new ServiceError("NETWORK_ERROR", error instanceof Error ? error.message : "Unknown error"),
+            };
+        }
+    }
+    async getChainTracker() {
+        return this.chaintracks;
+    }
+    async getHeaderForHeight(height) {
+        return this.chaintracks.getHeaderBytes(height);
+    }
+    async getHeight() {
+        return this.chaintracks.currentHeight();
+    }
+    async getMerklePath(txid, _useNext) {
+        try {
+            const proofBytes = await this.beef.getProof(txid);
+            const merklePath = MerklePath.fromBinary(Array.from(proofBytes));
+            return { name: "1sat-api", merklePath };
+        }
+        catch (error) {
+            return {
+                name: "1sat-api",
+                error: new ServiceError("NETWORK_ERROR", error instanceof Error ? error.message : "Unknown error"),
+            };
+        }
+    }
+    async postBeef(beef, txids) {
+        const results = [];
+        for (const txid of txids) {
+            try {
+                const beefTx = beef.findTxid(txid);
+                if (!beefTx?.tx) {
+                    results.push({
+                        name: "1sat-api",
+                        status: "error",
+                        error: new ServiceError("TX_NOT_FOUND", `Transaction ${txid} not found in BEEF`),
+                        txidResults: [
+                            {
+                                txid,
+                                status: "error",
+                                data: { detail: "Transaction not found in BEEF" },
+                            },
+                        ],
+                    });
+                    continue;
+                }
+                // Use Extended Format (EF) which includes source transaction data
+                const status = await this.arcade.submitTransaction(beefTx.tx.toEF());
+                if (status.txStatus === "MINED" ||
+                    status.txStatus === "SEEN_ON_NETWORK" ||
+                    status.txStatus === "ACCEPTED_BY_NETWORK") {
+                    results.push({
+                        name: "1sat-api",
+                        status: "success",
+                        txidResults: [{ txid: status.txid || txid, status: "success" }],
+                    });
+                }
+                else if (status.txStatus === "REJECTED" ||
+                    status.txStatus === "DOUBLE_SPEND_ATTEMPTED") {
+                    results.push({
+                        name: "1sat-api",
+                        status: "error",
+                        error: new ServiceError(status.txStatus, status.extraInfo || "Transaction rejected"),
+                        txidResults: [{ txid, status: "error", data: status }],
+                    });
+                }
+                else {
+                    // Still processing - report as success since tx was accepted
+                    results.push({
+                        name: "1sat-api",
+                        status: "success",
+                        txidResults: [{ txid: status.txid || txid, status: "success" }],
+                    });
+                }
+            }
+            catch (error) {
+                results.push({
+                    name: "1sat-api",
+                    status: "error",
+                    error: new ServiceError("NETWORK_ERROR", error instanceof Error ? error.message : "Unknown error"),
+                    txidResults: [{ txid, status: "error" }],
+                });
+            }
+        }
+        return results;
+    }
+    async getBeefForTxid(txid) {
+        const beefBytes = await this.beef.getBeef(txid);
+        return Beef.fromBinary(Array.from(beefBytes));
+    }
+    hashOutputScript(script) {
+        const scriptBin = Utils.toArray(script, "hex");
+        return Utils.toHex(Hash.hash256(scriptBin).reverse());
+    }
+    getServicesCallHistory(_reset) {
+        const emptyHistory = {
+            serviceName: "",
+            historyByProvider: {},
+        };
+        return {
+            version: 1,
+            getMerklePath: { ...emptyHistory, serviceName: "getMerklePath" },
+            getRawTx: { ...emptyHistory, serviceName: "getRawTx" },
+            postBeef: { ...emptyHistory, serviceName: "postBeef" },
+            getUtxoStatus: { ...emptyHistory, serviceName: "getUtxoStatus" },
+            getStatusForTxids: { ...emptyHistory, serviceName: "getStatusForTxids" },
+            getScriptHashHistory: {
+                ...emptyHistory,
+                serviceName: "getScriptHashHistory",
+            },
+            updateFiatExchangeRates: {
+                ...emptyHistory,
+                serviceName: "updateFiatExchangeRates",
+            },
+        };
+    }
+    // ===== WalletServices Interface (Not Yet Implemented) =====
+    async getBsvExchangeRate() {
+        throw new Error("getBsvExchangeRate not yet implemented");
+    }
+    async getFiatExchangeRate(_currency, _base) {
+        throw new Error("getFiatExchangeRate not yet implemented");
+    }
+    async getStatusForTxids(_txids, _useNext) {
+        throw new Error("getStatusForTxids not yet implemented");
+    }
+    async isUtxo(_output) {
+        throw new Error("isUtxo not yet implemented");
+    }
+    async getUtxoStatus(_output, _outputFormat, _outpoint, _useNext) {
+        throw new Error("getUtxoStatus not yet implemented");
+    }
+    async getScriptHashHistory(_hash, _useNext) {
+        throw new Error("getScriptHashHistory not yet implemented");
+    }
+    async hashToHeader(_hash) {
+        throw new Error("hashToHeader not yet implemented");
+    }
+    async nLockTimeIsFinal(_txOrLockTime) {
+        throw new Error("nLockTimeIsFinal not yet implemented");
+    }
+}

package/dist/services/client/ArcadeClient.js

@@ -0,0 +1,107 @@
+import { Utils } from "@bsv/sdk";
+import { BaseClient } from "./BaseClient";
+/**
+ * Client for /1sat/arcade/* routes.
+ * Provides transaction broadcast and status checking.
+ *
+ * Routes:
+ * - POST /tx - Submit single transaction
+ * - POST /txs - Submit multiple transactions
+ * - GET /tx/:txid - Get transaction status
+ * - GET /policy - Get mining policy
+ * - GET /events - SSE stream of transaction events
+ */
+export class ArcadeClient extends BaseClient {
+    constructor(baseUrl, options = {}) {
+        super(`${baseUrl}/1sat/arcade`, options);
+    }
+    /**
+     * Submit a single transaction for broadcast
+     */
+    async submitTransaction(rawTx, options) {
+        const bytes = rawTx instanceof Uint8Array ? rawTx : new Uint8Array(rawTx);
+        return this.request("/tx", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/octet-stream",
+                ...this.buildSubmitHeaders(options),
+            },
+            body: bytes,
+        });
+    }
+    /**
+     * Submit a transaction as hex string
+     */
+    async submitTransactionHex(rawTxHex, options) {
+        return this.submitTransaction(Utils.toArray(rawTxHex, "hex"), options);
+    }
+    /**
+     * Submit multiple transactions for broadcast
+     */
+    async submitTransactions(rawTxs, options) {
+        return this.request("/txs", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...this.buildSubmitHeaders(options),
+            },
+            body: JSON.stringify(rawTxs.map((tx) => ({
+                rawTx: Utils.toHex(tx instanceof Uint8Array ? Array.from(tx) : tx),
+            }))),
+        });
+    }
+    /**
+     * Get status of a submitted transaction
+     */
+    async getStatus(txid) {
+        return this.request(`/tx/${txid}`);
+    }
+    /**
+     * Get current mining policy
+     */
+    async getPolicy() {
+        return this.request("/policy");
+    }
+    /**
+     * Subscribe to transaction status events via SSE
+     * Returns unsubscribe function
+     */
+    subscribeEvents(callback, callbackToken) {
+        const url = callbackToken
+            ? `${this.baseUrl}/events?token=${encodeURIComponent(callbackToken)}`
+            : `${this.baseUrl}/events`;
+        const eventSource = new EventSource(url);
+        eventSource.onmessage = (event) => {
+            try {
+                const status = JSON.parse(event.data);
+                callback(status);
+            }
+            catch {
+                // Ignore parse errors
+            }
+        };
+        eventSource.onerror = () => {
+            eventSource.close();
+        };
+        return () => {
+            eventSource.close();
+        };
+    }
+    /**
+     * Build headers for submit requests
+     */
+    buildSubmitHeaders(options) {
+        const headers = {};
+        if (options?.callbackUrl)
+            headers["X-CallbackUrl"] = options.callbackUrl;
+        if (options?.callbackToken)
+            headers["X-CallbackToken"] = options.callbackToken;
+        if (options?.fullStatusUpdates)
+            headers["X-FullStatusUpdates"] = "true";
+        if (options?.skipFeeValidation)
+            headers["X-SkipFeeValidation"] = "true";
+        if (options?.skipScriptValidation)
+            headers["X-SkipScriptValidation"] = "true";
+        return headers;
+    }
+}

package/dist/services/client/BaseClient.js

@@ -0,0 +1,125 @@
+import { HttpError } from "../../errors";
+/**
+ * Base client with shared HTTP utilities for all 1sat-stack API clients.
+ * Provides timeout handling, error parsing, and request helpers.
+ */
+export class BaseClient {
+    baseUrl;
+    timeout;
+    fetchFn;
+    constructor(baseUrl, options = {}) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.timeout = options.timeout ?? 30000;
+        this.fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Make a JSON request and parse the response
+     */
+    async request(path, init) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw await this.parseError(response);
+            }
+            // Handle empty responses
+            const text = await response.text();
+            if (!text) {
+                return undefined;
+            }
+            return JSON.parse(text);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Make a request and return raw binary data
+     */
+    async requestBinary(path, init) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw await this.parseError(response);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            return new Uint8Array(arrayBuffer);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Make a request and return the raw Response object
+     * Useful for streaming responses
+     */
+    async requestRaw(path, init) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await this.fetchFn(`${this.baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw await this.parseError(response);
+            }
+            return response;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Parse error response into HttpError
+     */
+    async parseError(response) {
+        try {
+            const data = await response.json();
+            const message = data.message || data.error || data.detail || response.statusText;
+            return new HttpError(response.status, message);
+        }
+        catch {
+            try {
+                const text = await response.text();
+                return new HttpError(response.status, text || response.statusText);
+            }
+            catch {
+                return new HttpError(response.status, response.statusText);
+            }
+        }
+    }
+    /**
+     * Build query string from options object
+     */
+    buildQueryString(params) {
+        const entries = [];
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                if (value.length > 0) {
+                    entries.push(`${key}=${encodeURIComponent(value.join(","))}`);
+                }
+            }
+            else if (typeof value === "boolean") {
+                if (value) {
+                    entries.push(`${key}=true`);
+                }
+            }
+            else {
+                entries.push(`${key}=${encodeURIComponent(String(value))}`);
+            }
+        }
+        return entries.length > 0 ? `?${entries.join("&")}` : "";
+    }
+}

package/dist/services/client/BeefClient.js

@@ -0,0 +1,33 @@
+import { BaseClient } from "./BaseClient";
+/**
+ * Client for /1sat/beef/* routes.
+ * Provides BEEF data, raw transactions, and merkle proofs.
+ *
+ * Routes:
+ * - GET /:txid - Get BEEF for transaction
+ * - GET /:txid/raw - Get raw transaction bytes
+ * - GET /:txid/proof - Get merkle proof
+ */
+export class BeefClient extends BaseClient {
+    constructor(baseUrl, options = {}) {
+        super(`${baseUrl}/1sat/beef`, options);
+    }
+    /**
+     * Get BEEF (Background Evaluation Extended Format) for a transaction
+     */
+    async getBeef(txid) {
+        return this.requestBinary(`/${txid}`);
+    }
+    /**
+     * Get raw transaction bytes
+     */
+    async getRawTx(txid) {
+        return this.requestBinary(`/${txid}/tx`);
+    }
+    /**
+     * Get merkle proof bytes for a mined transaction
+     */
+    async getProof(txid) {
+        return this.requestBinary(`/${txid}/proof`);
+    }
+}

package/dist/services/client/Bsv21Client.js

@@ -0,0 +1,65 @@
+import { BaseClient } from "./BaseClient";
+/**
+ * Client for /1sat/bsv21/* routes.
+ * Provides BSV21 token queries.
+ *
+ * Routes:
+ * - GET /:tokenId - Get token details
+ * - GET /:tokenId/blk/:height - Get token data at block height
+ * - GET /:tokenId/tx/:txid - Get token data for transaction
+ * - GET /:tokenId/:lockType/:address/balance - Get token balance
+ * - GET /:tokenId/:lockType/:address/unspent - Get unspent token UTXOs
+ * - GET /:tokenId/:lockType/:address/history - Get token transaction history
+ */
+export class Bsv21Client extends BaseClient {
+    cache = new Map();
+    constructor(baseUrl, options = {}) {
+        super(`${baseUrl}/1sat/bsv21`, options);
+    }
+    /**
+     * Get token details (deploy data).
+     * Results are cached since token details are immutable.
+     */
+    async getTokenDetails(tokenId) {
+        const cached = this.cache.get(tokenId);
+        if (cached)
+            return cached;
+        const details = await this.request(`/${tokenId}`);
+        this.cache.set(tokenId, details);
+        return details;
+    }
+    /**
+     * Get token transaction data for a specific txid
+     */
+    async getTokenByTxid(tokenId, txid) {
+        return this.request(`/${tokenId}/tx/${txid}`);
+    }
+    /**
+     * Get token balance for an address
+     * @param tokenId - Token ID (outpoint of deploy tx)
+     * @param lockType - Lock type (e.g., 'p2pkh', 'ordlock')
+     * @param address - Address to check
+     */
+    async getBalance(tokenId, lockType, address) {
+        const data = await this.request(`/${tokenId}/${lockType}/${address}/balance`);
+        return BigInt(data.balance);
+    }
+    /**
+     * Get unspent token UTXOs for an address
+     */
+    async getUnspent(tokenId, lockType, address) {
+        return this.request(`/${tokenId}/${lockType}/${address}/unspent`);
+    }
+    /**
+     * Get token transaction history for an address
+     */
+    async getHistory(tokenId, lockType, address) {
+        return this.request(`/${tokenId}/${lockType}/${address}/history`);
+    }
+    /**
+     * Clear the token details cache
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+}