@1sat/wallet-toolbox 0.0.5 → 0.0.7

package/dist/services/client/ChaintracksClient.js

@@ -0,0 +1,175 @@
+import { BaseClient } from "./BaseClient";
+/**
+ * Helper to read a 32-bit unsigned integer from little-endian bytes
+ */
+function readUint32LE(data, offset) {
+    return ((data[offset] |
+        (data[offset + 1] << 8) |
+        (data[offset + 2] << 16) |
+        (data[offset + 3] << 24)) >>>
+        0);
+}
+/**
+ * Convert bytes to hex string (little-endian)
+ */
+function toHexLE(data) {
+    return Array.from(data)
+        .reverse()
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * SHA256 hash
+ */
+async function sha256(data) {
+    const buf = await crypto.subtle.digest("SHA-256", data);
+    return new Uint8Array(buf);
+}
+/**
+ * Double SHA256 hash (used for block header hash)
+ */
+async function doubleSha256(data) {
+    return sha256(await sha256(data));
+}
+/**
+ * Parse raw 80-byte header into BlockHeader object
+ */
+async function parseHeader(data, height) {
+    const version = readUint32LE(data, 0);
+    const prevHash = toHexLE(data.slice(4, 36));
+    const merkleRoot = toHexLE(data.slice(36, 68));
+    const time = readUint32LE(data, 68);
+    const bits = readUint32LE(data, 72);
+    const nonce = readUint32LE(data, 76);
+    const hash = toHexLE(await doubleSha256(data));
+    return { height, hash, version, prevHash, merkleRoot, time, bits, nonce };
+}
+/**
+ * Client for /1sat/chaintracks/* routes.
+ * Provides block header data and implements ChainTracker interface.
+ *
+ * Routes:
+ * - GET /tip - Get chain tip
+ * - GET /tip/stream - SSE stream of new blocks
+ * - GET /height - Get current height
+ * - GET /network - Get network type
+ * - GET /headers?height=N&count=M - Get raw header bytes
+ * - GET /header/height/:height - Get header by height
+ * - GET /header/hash/:hash - Get header by hash
+ */
+export class ChaintracksClient extends BaseClient {
+    eventSource = null;
+    subscribers = new Set();
+    constructor(baseUrl, options = {}) {
+        super(`${baseUrl}/1sat/chaintracks`, options);
+    }
+    /**
+     * Get current blockchain height (ChainTracker interface)
+     */
+    async currentHeight() {
+        const tip = await this.getTip();
+        return tip.height;
+    }
+    /**
+     * Validate merkle root for a given height (ChainTracker interface)
+     */
+    async isValidRootForHeight(root, height) {
+        try {
+            const header = await this.getHeaderByHeight(height);
+            const isValid = header.merkleRoot === root;
+            return isValid;
+        }
+        catch (e) {
+            console.error(`isValidRootForHeight(${height}) failed:`, e);
+            return false;
+        }
+    }
+    /**
+     * Get the network type (main or test)
+     */
+    async getNetwork() {
+        const data = await this.request("/network");
+        return data.network;
+    }
+    /**
+     * Get the current chain tip
+     */
+    async getTip() {
+        return this.request("/tip");
+    }
+    /**
+     * Get block header by height
+     */
+    async getHeaderByHeight(height) {
+        return this.request(`/header/height/${height}`);
+    }
+    /**
+     * Get block header by hash
+     */
+    async getHeaderByHash(hash) {
+        return this.request(`/header/hash/${hash}`);
+    }
+    /**
+     * Get multiple headers as parsed BlockHeader objects
+     */
+    async getHeaders(height, count) {
+        const data = await this.requestBinary(`/headers?height=${height}&count=${count}`);
+        if (data.length % 80 !== 0) {
+            throw new Error(`Invalid response length: ${data.length} bytes`);
+        }
+        const headers = [];
+        for (let i = 0; i < data.length; i += 80) {
+            headers.push(await parseHeader(data.slice(i, i + 80), height + i / 80));
+        }
+        return headers;
+    }
+    /**
+     * Get raw header bytes for one or more headers
+     */
+    async getHeaderBytes(height, count = 1) {
+        const data = await this.requestBinary(`/headers?height=${height}&count=${count}`);
+        return Array.from(data);
+    }
+    /**
+     * Subscribe to new block notifications via SSE
+     * Returns unsubscribe function
+     */
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        if (!this.eventSource) {
+            this.eventSource = new EventSource(`${this.baseUrl}/tip/stream`);
+            this.eventSource.onmessage = (event) => {
+                try {
+                    const header = JSON.parse(event.data);
+                    for (const cb of this.subscribers) {
+                        cb(header);
+                    }
+                }
+                catch {
+                    // Ignore parse errors (e.g., keepalive messages)
+                }
+            };
+            this.eventSource.onerror = () => {
+                this.eventSource?.close();
+                this.eventSource = null;
+            };
+        }
+        return () => {
+            this.subscribers.delete(callback);
+            if (this.subscribers.size === 0 && this.eventSource) {
+                this.eventSource.close();
+                this.eventSource = null;
+            }
+        };
+    }
+    /**
+     * Close all connections
+     */
+    close() {
+        if (this.eventSource) {
+            this.eventSource.close();
+            this.eventSource = null;
+        }
+        this.subscribers.clear();
+    }
+}

package/dist/services/client/OrdfsClient.js

@@ -0,0 +1,122 @@
+import { BaseClient } from "./BaseClient";
+/**
+ * Client for ordfs routes.
+ * Provides inscription content and metadata.
+ *
+ * Content is served from /1sat/content (e.g., https://api.1sat.app/1sat/content/:outpoint)
+ * API routes use /1sat/ordfs (e.g., https://api.1sat.app/1sat/ordfs/metadata/:outpoint)
+ */
+export class OrdfsClient extends BaseClient {
+    contentBaseUrl;
+    constructor(baseUrl, options = {}) {
+        super(`${baseUrl}/1sat/ordfs`, options);
+        this.contentBaseUrl = `${baseUrl.replace(/\/$/, "")}/1sat/content`;
+    }
+    /**
+     * Get metadata for an inscription
+     * @param outpoint - Outpoint (txid_vout) or txid
+     * @param seq - Optional sequence number (-1 for latest)
+     */
+    async getMetadata(outpoint, seq) {
+        const path = seq !== undefined ? `${outpoint}:${seq}` : outpoint;
+        return this.request(`/metadata/${path}`);
+    }
+    /**
+     * Get inscription content with full response headers
+     * @param outpoint - Outpoint (txid_vout) or txid
+     * @param options - Content request options
+     */
+    async getContent(outpoint, options = {}) {
+        const url = this.getContentUrl(outpoint, options);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await this.fetchFn(url, {
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch content: ${response.statusText}`);
+            }
+            const headers = this.parseResponseHeaders(response);
+            const arrayBuffer = await response.arrayBuffer();
+            return {
+                data: new Uint8Array(arrayBuffer),
+                headers,
+            };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Preview base64-encoded HTML content
+     * @param b64HtmlData - Base64-encoded HTML
+     */
+    async previewHtml(b64HtmlData) {
+        const response = await this.requestRaw(`/preview/${b64HtmlData}`);
+        return response.text();
+    }
+    /**
+     * Preview content by posting it directly
+     * @param content - Content to preview
+     * @param contentType - Content type header
+     */
+    async previewContent(content, contentType) {
+        return this.requestBinary("/preview", {
+            method: "POST",
+            headers: { "Content-Type": contentType },
+            body: content,
+        });
+    }
+    /**
+     * Get the URL for fetching inscription content directly.
+     * Useful for displaying in img/video tags.
+     * @param outpoint - Outpoint (txid_vout) or txid
+     * @param options - Content request options
+     */
+    getContentUrl(outpoint, options = {}) {
+        let path = outpoint;
+        if (options.seq !== undefined) {
+            path = `${outpoint}:${options.seq}`;
+        }
+        const queryParams = this.buildQueryString({
+            map: options.map,
+            parent: options.parent,
+            raw: options.raw,
+        });
+        return `${this.contentBaseUrl}/${path}${queryParams}`;
+    }
+    /**
+     * Parse response headers into structured object
+     */
+    parseResponseHeaders(response) {
+        const headers = {
+            contentType: response.headers.get("content-type") || "application/octet-stream",
+        };
+        const outpoint = response.headers.get("x-outpoint");
+        if (outpoint)
+            headers.outpoint = outpoint;
+        const origin = response.headers.get("x-origin");
+        if (origin)
+            headers.origin = origin;
+        const seq = response.headers.get("x-ord-seq");
+        if (seq)
+            headers.sequence = Number.parseInt(seq, 10);
+        const cacheControl = response.headers.get("cache-control");
+        if (cacheControl)
+            headers.cacheControl = cacheControl;
+        const mapData = response.headers.get("x-map");
+        if (mapData) {
+            try {
+                headers.map = JSON.parse(mapData);
+            }
+            catch {
+                // Invalid JSON, skip
+            }
+        }
+        const parent = response.headers.get("x-parent");
+        if (parent)
+            headers.parent = parent;
+        return headers;
+    }
+}

package/dist/services/client/OwnerClient.js

@@ -0,0 +1,123 @@
+import { BaseClient } from "./BaseClient";
+/**
+ * Client for /1sat/owner/* routes.
+ * Provides owner (address) queries and sync.
+ *
+ * Routes:
+ * - GET /:owner/txos - Get TXOs for owner
+ * - GET /:owner/balance - Get balance
+ * - GET /sync?owner=... - SSE stream of outputs for sync (supports multiple owners)
+ */
+export class OwnerClient extends BaseClient {
+    constructor(baseUrl, options = {}) {
+        super(`${baseUrl}/1sat/owner`, options);
+    }
+    /**
+     * Get TXOs owned by an address/owner
+     */
+    async getTxos(owner, opts) {
+        const qs = this.buildQueryString({
+            tags: opts?.tags,
+            from: opts?.from,
+            limit: opts?.limit,
+            rev: opts?.rev,
+            unspent: opts?.unspent,
+            refresh: opts?.refresh,
+        });
+        return this.request(`/${owner}/txos${qs}`);
+    }
+    /**
+     * Get balance for an address/owner
+     */
+    async getBalance(owner) {
+        return this.request(`/${owner}/balance`);
+    }
+    /**
+     * Sync outputs for owner(s) via SSE stream.
+     * The server merges results from all owners in score order.
+     *
+     * @param owners - Array of addresses/owners to sync
+     * @param onOutput - Callback for each output
+     * @param from - Starting score (for pagination/resumption)
+     * @param onDone - Callback when sync completes (client should retry after delay)
+     * @param onError - Callback for errors
+     * @returns Unsubscribe function
+     */
+    sync(owners, onOutput, from, onDone, onError) {
+        const params = new URLSearchParams();
+        for (const owner of owners) {
+            params.append("owner", owner);
+        }
+        if (from !== undefined) {
+            params.set("from", String(from));
+        }
+        const url = `${this.baseUrl}/sync?${params.toString()}`;
+        const eventSource = new EventSource(url);
+        eventSource.onmessage = (event) => {
+            try {
+                const output = JSON.parse(event.data);
+                onOutput(output);
+            }
+            catch (e) {
+                onError?.(e instanceof Error ? e : new Error(String(e)));
+            }
+        };
+        eventSource.addEventListener("done", () => {
+            eventSource.close();
+            onDone?.();
+        });
+        eventSource.onerror = () => {
+            eventSource.close();
+            onError?.(new Error("SSE connection error"));
+        };
+        return () => {
+            eventSource.close();
+        };
+    }
+    /**
+     * Sync outputs as an async iterator.
+     * Yields SyncOutput objects until the stream is done.
+     */
+    async *syncIterator(owners, from) {
+        const outputs = [];
+        let done = false;
+        let error = null;
+        let resolve = null;
+        const unsubscribe = this.sync(owners, (output) => {
+            outputs.push(output);
+            resolve?.();
+        }, from, () => {
+            done = true;
+            resolve?.();
+        }, (e) => {
+            error = e;
+            resolve?.();
+        });
+        try {
+            while (!done && !error) {
+                if (outputs.length > 0) {
+                    const output = outputs.shift();
+                    if (output)
+                        yield output;
+                }
+                else {
+                    await new Promise((r) => {
+                        resolve = r;
+                    });
+                }
+            }
+            // Yield remaining outputs
+            while (outputs.length > 0) {
+                const output = outputs.shift();
+                if (output)
+                    yield output;
+            }
+            if (error) {
+                throw error;
+            }
+        }
+        finally {
+            unsubscribe();
+        }
+    }
+}

package/dist/services/client/TxoClient.js

@@ -0,0 +1,85 @@
+import { BaseClient } from "./BaseClient";
+/**
+ * Client for /1sat/txo/* routes.
+ * Provides TXO (transaction output) lookup and search.
+ *
+ * Routes:
+ * - GET /:outpoint - Get single TXO (outpoint pattern-matched)
+ * - GET /:outpoint/spend - Get spend info
+ * - POST /outpoints - Get multiple TXOs
+ * - POST /spends - Get multiple spends
+ * - GET /tx/:txid - Get all TXOs for a transaction
+ * - GET /search?key=... - Search by key(s)
+ */
+export class TxoClient extends BaseClient {
+    constructor(baseUrl, options = {}) {
+        super(`${baseUrl}/1sat/txo`, options);
+    }
+    /**
+     * Get a single TXO by outpoint
+     */
+    async get(outpoint, opts) {
+        const qs = this.buildQueryString({
+            tags: opts?.tags,
+        });
+        return this.request(`/${outpoint}${qs}`);
+    }
+    /**
+     * Get multiple TXOs by outpoints
+     */
+    async getBatch(outpoints, opts) {
+        const qs = this.buildQueryString({
+            tags: opts?.tags,
+        });
+        return this.request(`/outpoints${qs}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(outpoints),
+        });
+    }
+    /**
+     * Get spend info for an outpoint
+     */
+    async getSpend(outpoint) {
+        const resp = await this.request(`/${outpoint}/spend`);
+        return resp.spendTxid;
+    }
+    /**
+     * Get spend info for multiple outpoints
+     */
+    async getSpends(outpoints) {
+        const resp = await this.request("/spends", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(outpoints),
+        });
+        return resp.map((r) => r.spendTxid);
+    }
+    /**
+     * Get all TXOs for a transaction
+     */
+    async getByTxid(txid, opts) {
+        const qs = this.buildQueryString({
+            tags: opts?.tags,
+        });
+        return this.request(`/tx/${txid}${qs}`);
+    }
+    /**
+     * Search TXOs by key(s)
+     */
+    async search(keys, opts) {
+        const qs = this.buildQueryString({
+            key: Array.isArray(keys) ? keys : [keys],
+            tags: opts?.tags,
+            from: opts?.from,
+            limit: opts?.limit,
+            rev: opts?.rev,
+            unspent: opts?.unspent,
+            sats: opts?.sats,
+            spend: opts?.spend,
+            events: opts?.events,
+            block: opts?.block,
+        });
+        return this.request(`/search${qs}`);
+    }
+}

package/dist/services/client/index.js

@@ -0,0 +1,8 @@
+export { BaseClient } from "./BaseClient";
+export { ChaintracksClient } from "./ChaintracksClient";
+export { BeefClient } from "./BeefClient";
+export { ArcadeClient } from "./ArcadeClient";
+export { TxoClient } from "./TxoClient";
+export { OwnerClient } from "./OwnerClient";
+export { OrdfsClient } from "./OrdfsClient";
+export { Bsv21Client } from "./Bsv21Client";

package/dist/services/types.js

@@ -0,0 +1,5 @@
+/**
+ * Consolidated type definitions for 1sat-stack API clients.
+ * These types mirror the structures returned by the 1sat-stack server.
+ */
+export {};

package/dist/signers/ReadOnlySigner.js

@@ -0,0 +1,47 @@
+import { PublicKey, } from "@bsv/sdk";
+/**
+ * A mock PrivateKey that only supports toPublicKey().
+ * All other operations throw.
+ */
+class ReadOnlyPrivateKey {
+    publicKey;
+    constructor(publicKeyHex) {
+        this.publicKey = PublicKey.fromString(publicKeyHex);
+    }
+    toPublicKey() {
+        return this.publicKey;
+    }
+    toString() {
+        return this.publicKey.toString();
+    }
+    toHex() {
+        return this.publicKey.toString();
+    }
+}
+/**
+ * A read-only KeyDeriver that exposes an identity key but throws on any signing/derivation operation.
+ * Used when the wallet is instantiated with only a public key.
+ */
+export class ReadOnlySigner {
+    identityKey;
+    rootKey;
+    constructor(identityPublicKey) {
+        this.identityKey = identityPublicKey;
+        this.rootKey = new ReadOnlyPrivateKey(identityPublicKey);
+    }
+    derivePrivateKey(_protocolID, _keyID, _counterparty) {
+        throw new Error("Cannot derive private key in read-only mode");
+    }
+    derivePublicKey(_protocolID, _keyID, _counterparty, _forSelf) {
+        throw new Error("Cannot derive public key in read-only mode");
+    }
+    deriveSymmetricKey(_protocolID, _keyID, _counterparty) {
+        throw new Error("Cannot derive symmetric key in read-only mode");
+    }
+    revealCounterpartySecret(_counterparty) {
+        throw new Error("Cannot reveal secrets in read-only mode");
+    }
+    revealSpecificSecret(_counterparty, _protocolID, _keyID) {
+        throw new Error("Cannot reveal secrets in read-only mode");
+    }
+}