@1sat/wallet-toolbox 0.0.8 → 0.0.10

package/dist/sync/SyncManager.js

@@ -0,0 +1,507 @@
+/**
+ * SyncManager - Syncs external transactions to the BRC-100 wallet.
+ *
+ * Split into two components for Chrome extension compatibility:
+ * - SyncFetcher: Calls SSE endpoint and enqueues txids (runs in UI context)
+ * - SyncProcessor: Processes queue and internalizes outputs (runs in service worker)
+ *
+ * This separation is necessary because EventSource (SSE) doesn't work reliably
+ * in Chrome extension service workers due to their ephemeral nature.
+ */
+import { Beef } from "@bsv/sdk";
+import { Outpoint } from "../indexers/Outpoint";
+import { FundIndexer } from "../indexers/FundIndexer";
+import { InscriptionIndexer } from "../indexers/InscriptionIndexer";
+import { Bsv21Indexer } from "../indexers/Bsv21Indexer";
+import { OriginIndexer } from "../indexers/OriginIndexer";
+import { OpNSIndexer } from "../indexers/OpNSIndexer";
+import { SigmaIndexer } from "../indexers/SigmaIndexer";
+import { MapIndexer } from "../indexers/MapIndexer";
+/** Reorg-safe depth - only update lastQueuedScore for outputs this many blocks deep */
+const REORG_SAFE_DEPTH = 6;
+/** Default batch size for queue processing */
+const DEFAULT_BATCH_SIZE = 20;
+/**
+ * SyncFetcher - Fetches outputs via SSE and enqueues them.
+ *
+ * Run this from the UI context (popup) when the wallet opens.
+ * It will fetch all new outputs since the last sync and add them to the queue.
+ */
+export class SyncFetcher {
+    services;
+    syncQueue;
+    addressManager;
+    unsubscribeStream = null;
+    listeners = new Map();
+    constructor(options) {
+        this.services = options.services;
+        this.syncQueue = options.syncQueue;
+        this.addressManager = options.addressManager;
+    }
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+    }
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    emit(event, data) {
+        this.listeners.get(event)?.forEach((listener) => listener(data));
+    }
+    /**
+     * Fetch new outputs via SSE and enqueue them.
+     * Returns when the stream completes (all historical data fetched).
+     */
+    async fetch(currentHeight) {
+        if (this.unsubscribeStream) {
+            console.warn("Fetch already running");
+            return 0;
+        }
+        const addresses = this.addressManager.getAddresses();
+        if (addresses.length === 0) {
+            console.warn("No addresses to fetch");
+            return 0;
+        }
+        this.emit("fetch:start", { addresses });
+        // Get last score for resumption
+        const state = await this.syncQueue.getState();
+        const fromScore = state.lastQueuedScore;
+        let queuedCount = 0;
+        return new Promise((resolve, reject) => {
+            this.unsubscribeStream = this.services.owner.sync(addresses, async (output) => {
+                await this.handleSyncOutput(output, currentHeight);
+                queuedCount++;
+                this.emit("fetch:queued", { outpoint: output.outpoint, score: output.score });
+            }, fromScore, () => {
+                // Stream complete
+                this.unsubscribeStream = null;
+                this.emit("fetch:complete", { queuedCount });
+                resolve(queuedCount);
+            }, (error) => {
+                this.unsubscribeStream = null;
+                this.emit("fetch:error", { message: error.message });
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Stop the SSE stream if running.
+     */
+    stop() {
+        if (this.unsubscribeStream) {
+            this.unsubscribeStream();
+            this.unsubscribeStream = null;
+        }
+    }
+    async handleSyncOutput(output, currentHeight) {
+        // Enqueue the output
+        await this.syncQueue.enqueue([
+            {
+                outpoint: output.outpoint,
+                score: output.score,
+                spendTxid: output.spendTxid,
+            },
+        ]);
+        // Update lastQueuedScore only for reorg-safe outputs
+        const outputHeight = Math.floor(output.score / 1e9);
+        if (currentHeight - outputHeight >= REORG_SAFE_DEPTH) {
+            await this.syncQueue.setState({ lastQueuedScore: output.score });
+        }
+    }
+}
+/**
+ * SyncProcessor - Processes the sync queue and internalizes outputs.
+ *
+ * Run this from the service worker. It will process items from the queue
+ * until the queue is empty or stop() is called.
+ */
+export class SyncProcessor {
+    wallet;
+    services;
+    syncQueue;
+    addressManager;
+    network;
+    batchSize;
+    indexers;
+    processorRunning = false;
+    stopRequested = false;
+    listeners = new Map();
+    constructor(options) {
+        this.wallet = options.wallet;
+        this.services = options.services;
+        this.syncQueue = options.syncQueue;
+        this.addressManager = options.addressManager;
+        this.network = options.network;
+        this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+        // Build owners set from address manager
+        const owners = new Set(this.addressManager.getAddresses());
+        // Initialize indexers for sync (P2PKH-based outputs only)
+        this.indexers = options.indexers ?? [
+            new FundIndexer(owners, this.network),
+            new InscriptionIndexer(owners, this.network),
+            new Bsv21Indexer(owners, this.network, this.services),
+            new OriginIndexer(owners, this.network, this.services),
+            new OpNSIndexer(owners, this.network),
+            new SigmaIndexer(owners, this.network),
+            new MapIndexer(owners, this.network),
+        ];
+    }
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+    }
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    emit(event, data) {
+        this.listeners.get(event)?.forEach((listener) => listener(data));
+    }
+    /**
+     * Start processing the queue.
+     * Processes until queue is empty or stop() is called.
+     */
+    async start() {
+        if (this.processorRunning) {
+            console.warn("Processor already running");
+            return;
+        }
+        // Reset any stuck processing items
+        await this.syncQueue.resetProcessing();
+        this.stopRequested = false;
+        this.emit("process:start", {});
+        await this.processQueueLoop();
+    }
+    /**
+     * Stop processing the queue.
+     */
+    stop() {
+        this.stopRequested = true;
+    }
+    /**
+     * Check if processor is currently running.
+     */
+    isRunning() {
+        return this.processorRunning;
+    }
+    async processQueueLoop() {
+        this.processorRunning = true;
+        try {
+            while (!this.stopRequested) {
+                // Claim batch of pending items grouped by txid
+                const byTxid = await this.syncQueue.claim(this.batchSize);
+                if (byTxid.size === 0) {
+                    // Queue empty - wait and poll again
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                    continue;
+                }
+                // Process each txid in parallel
+                await Promise.all(Array.from(byTxid.entries()).map(([txid, items]) => this.processTxid(txid, items)));
+                // Emit progress
+                const stats = await this.syncQueue.getStats();
+                this.emit("process:progress", {
+                    pending: stats.pending,
+                    done: stats.done,
+                    failed: stats.failed,
+                });
+            }
+            this.emit("process:complete", {});
+        }
+        catch (error) {
+            this.emit("process:error", {
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            this.processorRunning = false;
+        }
+    }
+    async processTxid(txid, items) {
+        try {
+            // Build spend map: vout → spendTxid
+            const spendMap = new Map();
+            for (const item of items) {
+                if (item.spendTxid) {
+                    const vout = parseInt(item.outpoint.split("_")[1], 10);
+                    spendMap.set(vout, item.spendTxid);
+                }
+            }
+            // If all items are spend-only (no new outputs), just mark outputs as spent
+            const hasNewOutputs = items.some((item) => !item.spendTxid);
+            if (!hasNewOutputs) {
+                // TODO: Mark outputs as spent in wallet storage
+                // For now, just complete the items
+                await this.syncQueue.completeMany(items.map((i) => i.id));
+                return;
+            }
+            // Load transaction as BEEF
+            const beef = await this.services.beef.getBeef(txid);
+            if (!beef) {
+                throw new Error(`Failed to load transaction ${txid}`);
+            }
+            // Parse transaction with indexers
+            const beefObj = Beef.fromBinary(Array.from(beef));
+            const btx = beefObj.findTxid(txid);
+            if (!btx?.tx) {
+                throw new Error(`Transaction ${txid} not found in BEEF`);
+            }
+            const ctx = await this.parseTransaction(btx.tx);
+            // Build InternalizeOutput entries for owned outputs
+            const outputs = [];
+            let internalizedCount = 0;
+            for (const txo of ctx.txos) {
+                if (!txo.owner)
+                    continue;
+                // Check if this output is at one of our receive addresses
+                const derivation = this.addressManager.getDerivation(txo.owner);
+                if (!derivation)
+                    continue;
+                // Build internalize output using protocol from indexer
+                const internalizeOutput = this.buildInternalizeOutput(txo, derivation);
+                if (internalizeOutput) {
+                    outputs.push(internalizeOutput);
+                    internalizedCount++;
+                }
+            }
+            // Internalize if we have owned outputs
+            if (outputs.length > 0) {
+                const args = {
+                    tx: Array.from(beef),
+                    outputs,
+                    description: "1sat sync",
+                };
+                console.log(`[SyncProcessor] Internalizing ${outputs.length} outputs for txid ${txid}`, outputs.map((o) => ({ vout: o.outputIndex, protocol: o.protocol })));
+                await this.wallet.internalizeAction(args);
+                console.log(`[SyncProcessor] Internalization complete for txid ${txid}`);
+                this.emit("process:parsed", { internalizedCount });
+            }
+            // Complete all items for this txid
+            await this.syncQueue.completeMany(items.map((i) => i.id));
+        }
+        catch (error) {
+            // Fail all items for this txid
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            console.error(`[SyncProcessor] Failed to process txid ${txid}:`, errorMsg);
+            for (const item of items) {
+                await this.syncQueue.fail(item.id, errorMsg);
+            }
+        }
+    }
+    async parseTransaction(tx) {
+        const txid = tx.id("hex");
+        // Initialize parse context
+        const ctx = {
+            tx,
+            txid,
+            txos: [],
+            spends: [],
+            summary: {},
+            indexers: this.indexers,
+        };
+        // Parse each output
+        for (let vout = 0; vout < tx.outputs.length; vout++) {
+            const output = tx.outputs[vout];
+            const txo = {
+                output,
+                outpoint: new Outpoint(txid, vout),
+                data: {},
+            };
+            // Run through all indexers
+            for (const indexer of this.indexers) {
+                const result = await indexer.parse(txo);
+                if (result) {
+                    txo.data[indexer.tag] = {
+                        data: result.data,
+                        tags: result.tags,
+                        content: result.content,
+                    };
+                    // First indexer to set owner wins
+                    if (result.owner && !txo.owner) {
+                        txo.owner = result.owner;
+                    }
+                    // First indexer to set basket wins
+                    if (result.basket && !txo.basket) {
+                        txo.basket = result.basket;
+                    }
+                    // First indexer to set protocol wins (custom scripts override P2PKH)
+                    if (result.protocol && !txo.protocol) {
+                        txo.protocol = result.protocol;
+                    }
+                }
+            }
+            ctx.txos.push(txo);
+        }
+        // Run summarize phase for all indexers
+        for (const indexer of this.indexers) {
+            const summary = await indexer.summarize(ctx, true);
+            if (summary) {
+                ctx.summary[indexer.tag] = summary;
+            }
+        }
+        return ctx;
+    }
+    buildInternalizeOutput(txo, derivation) {
+        const vout = txo.outpoint.vout;
+        // Use protocol from indexer, default to "wallet payment" for P2PKH
+        const protocol = txo.protocol || "wallet payment";
+        if (protocol === "basket insertion") {
+            // Custom script - use basket insertion
+            // These outputs need custom unlock scripts when spent
+            const basket = txo.basket || "custom";
+            const tags = this.collectTags(txo);
+            return {
+                outputIndex: vout,
+                protocol: "basket insertion",
+                insertionRemittance: {
+                    basket,
+                    tags,
+                    // Store derivation info for future signing
+                    customInstructions: JSON.stringify({
+                        derivationPrefix: derivation.derivationPrefix,
+                        derivationSuffix: derivation.derivationSuffix,
+                        senderIdentityKey: derivation.senderIdentityKey,
+                    }),
+                },
+            };
+        }
+        else {
+            // P2PKH-based output - use wallet payment for auto-signing
+            return {
+                outputIndex: vout,
+                protocol: "wallet payment",
+                paymentRemittance: {
+                    derivationPrefix: derivation.derivationPrefix,
+                    derivationSuffix: derivation.derivationSuffix,
+                    senderIdentityKey: derivation.senderIdentityKey,
+                },
+            };
+        }
+    }
+    collectTags(txo) {
+        const tags = [];
+        for (const indexData of Object.values(txo.data)) {
+            tags.push(...indexData.tags);
+        }
+        return tags;
+    }
+}
+/**
+ * SyncManager - Legacy class that combines SSE fetching and queue processing.
+ *
+ * @deprecated For Chrome extensions, use SyncFetcher (in UI) and SyncProcessor (in service worker)
+ * separately since EventSource doesn't work reliably in service workers.
+ *
+ * This class is kept for backwards compatibility and for environments where
+ * SSE works (e.g., Node.js, React Native).
+ */
+export class SyncManager {
+    fetcher;
+    processor;
+    wallet;
+    addressManager;
+    listeners = new Map();
+    fetchPromise = null;
+    constructor(options) {
+        this.wallet = options.wallet;
+        this.addressManager = options.addressManager;
+        // Create fetcher for SSE stream
+        this.fetcher = new SyncFetcher({
+            services: options.services,
+            syncQueue: options.syncQueue,
+            addressManager: options.addressManager,
+        });
+        // Create processor for queue processing
+        this.processor = new SyncProcessor({
+            wallet: options.wallet,
+            services: options.services,
+            syncQueue: options.syncQueue,
+            addressManager: options.addressManager,
+            network: options.network,
+            batchSize: options.batchSize,
+            indexers: options.indexers,
+        });
+        // Wire up event forwarding
+        this.setupEventForwarding();
+    }
+    setupEventForwarding() {
+        // Forward fetcher events
+        this.fetcher.on("fetch:start", (data) => {
+            this.emit("sync:start", { addresses: data.addresses });
+        });
+        this.fetcher.on("fetch:error", (data) => {
+            this.emit("sync:error", { message: data.message });
+        });
+        // Forward processor events
+        this.processor.on("process:progress", (data) => {
+            this.emit("sync:progress", data);
+        });
+        this.processor.on("process:complete", () => {
+            this.emit("sync:complete", {});
+        });
+        this.processor.on("process:error", (data) => {
+            this.emit("sync:error", { message: data.message });
+        });
+        this.processor.on("process:parsed", (data) => {
+            this.emit("sync:parsed", data);
+        });
+    }
+    // ===== Event Emitter =====
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+    }
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    emit(event, data) {
+        this.listeners.get(event)?.forEach((listener) => listener(data));
+    }
+    // ===== Sync Control =====
+    /**
+     * Start syncing - opens SSE stream and starts queue processor.
+     */
+    async sync() {
+        if (this.fetchPromise || this.processor.isRunning()) {
+            console.warn("Sync already running");
+            return;
+        }
+        const addresses = this.addressManager.getAddresses();
+        if (addresses.length === 0) {
+            console.warn("No addresses to sync");
+            return;
+        }
+        // Get current height for reorg protection
+        const { height: currentHeight } = await this.wallet.getHeight({});
+        // Start fetcher (SSE stream) - this runs until stream completes
+        this.fetchPromise = this.fetcher.fetch(currentHeight);
+        // Start processor in parallel - this processes items as they come in
+        // and waits for more until fetch completes
+        this.processor.start();
+        // Wait for fetch to complete, then let processor finish
+        try {
+            await this.fetchPromise;
+        }
+        finally {
+            this.fetchPromise = null;
+        }
+    }
+    /**
+     * Stop syncing - closes SSE stream and stops queue processor.
+     */
+    stop() {
+        this.fetcher.stop();
+        this.processor.stop();
+        this.fetchPromise = null;
+    }
+    /**
+     * Check if sync is currently running.
+     */
+    isSyncing() {
+        return this.fetchPromise !== null || this.processor.isRunning();
+    }
+}

package/dist/sync/index.d.ts

@@ -1,3 +1,7 @@
 export * from "./types";
 export { IndexedDbSyncQueue } from "./IndexedDbSyncQueue";
 export { SqliteSyncQueue } from "./SqliteSyncQueue";
+export { AddressManager, YOURS_PREFIX, BRC29_PROTOCOL_ID } from "./AddressManager";
+export type { AddressDerivation } from "./AddressManager";
+export { SyncFetcher, SyncProcessor, SyncManager } from "./SyncManager";
+export type { SyncFetcherOptions, SyncFetcherEvents, SyncProcessorOptions, SyncProcessorEvents, SyncManagerOptions, SyncEvents, } from "./SyncManager";

package/dist/sync/index.js

@@ -1,3 +1,5 @@
 export * from "./types";
 export { IndexedDbSyncQueue } from "./IndexedDbSyncQueue";
 export { SqliteSyncQueue } from "./SqliteSyncQueue";
+export { AddressManager, YOURS_PREFIX, BRC29_PROTOCOL_ID } from "./AddressManager";
+export { SyncFetcher, SyncProcessor, SyncManager } from "./SyncManager";

package/dist/wallet/factory.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Factory for creating web wallets.
+ *
+ * This consolidates the common wallet setup used by both yours-wallet
+ * (browser extension) and 1sat-website (React app).
+ */
+import { PrivateKey } from "@bsv/sdk";
+import { WalletPermissionsManager, Monitor, type PermissionsManagerConfig } from "@bsv/wallet-toolbox-mobile/out/src/index.client.js";
+import { OneSatServices } from "../services/OneSatServices";
+type Chain = "main" | "test";
+/**
+ * Configuration for creating a web wallet.
+ */
+export interface WebWalletConfig {
+    /** Private key - can be PrivateKey instance, WIF string, or hex string */
+    privateKey: PrivateKey | string;
+    /** Network: 'main' or 'test' */
+    chain: Chain;
+    /** Admin originator that bypasses permission checks (e.g., chrome-extension://id or https://wallet.example.com) */
+    adminOriginator: string;
+    /** Permission configuration for WalletPermissionsManager */
+    permissionsConfig: PermissionsManagerConfig;
+    /** Fee model. Default: { model: 'sat/kb', value: 1 } */
+    feeModel?: {
+        model: "sat/kb";
+        value: number;
+    };
+    /** Remote storage URL. If provided, attempts to connect for cloud backup. */
+    remoteStorageUrl?: string;
+}
+/**
+ * Result of wallet creation.
+ */
+export interface WebWalletResult {
+    /** Wallet instance with permission management */
+    wallet: WalletPermissionsManager;
+    /** 1Sat services for API access */
+    services: OneSatServices;
+    /** Monitor for transaction lifecycle (not started - call monitor.startTasks() when ready) */
+    monitor: Monitor;
+    /** Cleanup function - stops monitor, destroys wallet */
+    destroy: () => Promise<void>;
+}
+/**
+ * Create a web wallet with storage, services, permissions, and monitor.
+ *
+ * @example
+ * ```typescript
+ * const { wallet, services, monitor, destroy } = await createWebWallet({
+ *   privateKey: identityWif,
+ *   chain: 'main',
+ *   adminOriginator: 'https://wallet.example.com',
+ *   permissionsConfig: DEFAULT_PERMISSIONS_CONFIG,
+ * });
+ *
+ * // Wire up monitor callbacks
+ * monitor.onTransactionProven = async (status) => console.log('Proven:', status.txid);
+ *
+ * // Start monitor when ready
+ * monitor.startTasks();
+ * ```
+ */
+export declare function createWebWallet(config: WebWalletConfig): Promise<WebWalletResult>;
+export {};