@1sat/wallet-toolbox 0.0.5 → 0.0.7

package/dist/OneSatWallet.js

@@ -0,0 +1,956 @@
+import { Beef, Hash, Random, Transaction, Utils, } from "@bsv/sdk";
+import { Bsv21Indexer } from "./indexers/Bsv21Indexer";
+import { CosignIndexer } from "./indexers/CosignIndexer";
+import { FundIndexer } from "./indexers/FundIndexer";
+import { InscriptionIndexer } from "./indexers/InscriptionIndexer";
+import { LockIndexer } from "./indexers/LockIndexer";
+import { MapIndexer } from "./indexers/MapIndexer";
+import { OpNSIndexer } from "./indexers/OpNSIndexer";
+import { OrdLockIndexer } from "./indexers/OrdLockIndexer";
+import { OriginIndexer } from "./indexers/OriginIndexer";
+import { Outpoint } from "./indexers/Outpoint";
+import { SigmaIndexer } from "./indexers/SigmaIndexer";
+import { OneSatServices } from "./services/OneSatServices";
+/** Number of blocks to wait before considering a score "safe" from reorgs */
+const REORG_SAFE_DEPTH = 6;
+/** Default batch size for queue processing */
+const DEFAULT_BATCH_SIZE = 20;
+/**
+ * OneSatWallet wraps a BRC-100 Wallet with 1Sat-specific indexing and services.
+ *
+ * The consumer is responsible for constructing the underlying Wallet with
+ * the appropriate storage and key derivation for their environment.
+ */
+export class OneSatWallet {
+    wallet;
+    storage;
+    indexers;
+    services;
+    owners;
+    listeners = {};
+    // Queue-based sync
+    syncQueue = null;
+    syncBatchSize = DEFAULT_BATCH_SIZE;
+    syncRunning = false;
+    syncStopRequested = false;
+    activeQueueSync = null;
+    // Separate stream/processor state for testing
+    sseStreamActive = false;
+    sseUnsubscribe = null;
+    processorActive = false;
+    processorStopRequested = false;
+    streamDone = false;
+    constructor(args) {
+        this.wallet = args.wallet;
+        this.storage = args.storage;
+        const services = new OneSatServices(args.chain, args.onesatUrl, args.storage);
+        const network = args.chain === "main" ? "mainnet" : "testnet";
+        const owners = args.owners || new Set();
+        this.services = services;
+        this.owners = owners;
+        // Use provided indexers or create defaults
+        this.indexers = args.indexers ?? [
+            new FundIndexer(owners, network),
+            new LockIndexer(owners, network),
+            new InscriptionIndexer(owners, network),
+            new SigmaIndexer(owners, network),
+            new MapIndexer(owners, network),
+            new OriginIndexer(owners, network, services),
+            new Bsv21Indexer(owners, network, services),
+            new OrdLockIndexer(owners, network),
+            new OpNSIndexer(owners, network),
+            new CosignIndexer(owners, network),
+        ];
+        // Queue-based sync settings
+        this.syncQueue = args.syncQueue ?? null;
+        this.syncBatchSize = args.syncBatchSize ?? DEFAULT_BATCH_SIZE;
+        if (args.autoSync) {
+            this.sync();
+        }
+    }
+    // ===== WalletInterface Delegation =====
+    getPublicKey = (args, originator) => this.wallet.getPublicKey(args, originator);
+    revealCounterpartyKeyLinkage = (args, originator) => this.wallet.revealCounterpartyKeyLinkage(args, originator);
+    revealSpecificKeyLinkage = (args, originator) => this.wallet.revealSpecificKeyLinkage(args, originator);
+    encrypt = (args, originator) => this.wallet.encrypt(args, originator);
+    decrypt = (args, originator) => this.wallet.decrypt(args, originator);
+    createHmac = (args, originator) => this.wallet.createHmac(args, originator);
+    verifyHmac = (args, originator) => this.wallet.verifyHmac(args, originator);
+    createSignature = (args, originator) => this.wallet.createSignature(args, originator);
+    verifySignature = (args, originator) => this.wallet.verifySignature(args, originator);
+    createAction = (args, originator) => this.wallet.createAction(args, originator);
+    signAction = (args, originator) => this.wallet.signAction(args, originator);
+    abortAction = (args, originator) => this.wallet.abortAction(args, originator);
+    listActions = (args, originator) => this.wallet.listActions(args, originator);
+    internalizeAction = (args, originator) => this.wallet.internalizeAction(args, originator);
+    listOutputs = (args, originator) => this.wallet.listOutputs(args, originator);
+    relinquishOutput = (args, originator) => this.wallet.relinquishOutput(args, originator);
+    acquireCertificate = (args, originator) => this.wallet.acquireCertificate(args, originator);
+    listCertificates = (args, originator) => this.wallet.listCertificates(args, originator);
+    proveCertificate = (args, originator) => this.wallet.proveCertificate(args, originator);
+    relinquishCertificate = (args, originator) => this.wallet.relinquishCertificate(args, originator);
+    discoverByIdentityKey = (args, originator) => this.wallet.discoverByIdentityKey(args, originator);
+    discoverByAttributes = (args, originator) => this.wallet.discoverByAttributes(args, originator);
+    isAuthenticated = (args, originator) => this.wallet.isAuthenticated(args, originator);
+    waitForAuthentication = (args, originator) => this.wallet.waitForAuthentication(args, originator);
+    getHeight = (args, originator) => this.wallet.getHeight(args, originator);
+    getHeaderForHeight = (args, originator) => this.wallet.getHeaderForHeight(args, originator);
+    getNetwork = (args, originator) => this.wallet.getNetwork(args, originator);
+    getVersion = (args, originator) => this.wallet.getVersion(args, originator);
+    // ===== Event Emitter =====
+    /**
+     * Subscribe to wallet events
+     */
+    on(event, callback) {
+        if (!this.listeners[event]) {
+            this.listeners[event] = new Set();
+        }
+        this.listeners[event].add(callback);
+    }
+    /**
+     * Unsubscribe from wallet events
+     */
+    off(event, callback) {
+        this.listeners[event]?.delete(callback);
+    }
+    /**
+     * Emit a wallet event
+     */
+    emit(event, data) {
+        const callbacks = this.listeners[event];
+        if (callbacks) {
+            for (const cb of callbacks) {
+                cb(data);
+            }
+        }
+    }
+    /**
+     * Add an address to the set of owned addresses.
+     * Outputs to these addresses will be indexed.
+     */
+    addOwner(address) {
+        this.owners.add(address);
+    }
+    /**
+     * Parse a transaction through indexers without internalizing.
+     *
+     * This is useful for debugging/testing to see what the indexers produce
+     * without actually storing the transaction in the wallet.
+     *
+     * @param tx - Transaction or txid to parse
+     * @param isBroadcasted - Whether this transaction has been broadcast
+     * @returns ParseContext with all indexer data
+     */
+    async parseTransaction(txOrTxid, isBroadcasted = true) {
+        // Load transaction if needed
+        const tx = typeof txOrTxid === "string"
+            ? await this.loadTransaction(txOrTxid)
+            : txOrTxid;
+        // Hydrate source transactions for inputs
+        await this.hydrateSourceTransactions(tx);
+        // Build context
+        const ctx = this.buildParseContext(tx);
+        // Parse all inputs (build ctx.spends)
+        await this.parseInputs(ctx);
+        // Run parse on each output with each indexer
+        for (const txo of ctx.txos) {
+            await this.runIndexersOnTxo(txo);
+        }
+        // Run summarize on each indexer
+        for (const indexer of this.indexers) {
+            const summary = await indexer.summarize(ctx, isBroadcasted);
+            if (summary) {
+                ctx.summary[indexer.tag] = summary;
+            }
+        }
+        return ctx;
+    }
+    /**
+     * Parse a single output without full transaction context.
+     * Runs all indexers' parse() methods but NOT summarize().
+     *
+     * @param output - The TransactionOutput to parse
+     * @param outpoint - The outpoint identifying this output
+     * @returns Txo with all indexer data populated
+     */
+    async parseOutput(output, outpoint) {
+        const txo = {
+            output,
+            outpoint,
+            data: {},
+        };
+        await this.runIndexersOnTxo(txo);
+        return txo;
+    }
+    /**
+     * Load and parse a single output by outpoint.
+     * Loads the transaction, extracts the output, and runs indexers on it.
+     *
+     * @param outpoint - Outpoint string (txid_vout)
+     * @returns Txo with all indexer data populated
+     */
+    async loadTxo(outpoint) {
+        const op = new Outpoint(outpoint);
+        const tx = await this.loadTransaction(op.txid);
+        const output = tx.outputs[op.vout];
+        if (!output) {
+            throw new Error(`Output ${op.vout} not found in transaction ${op.txid}`);
+        }
+        return this.parseOutput(output, op);
+    }
+    /**
+     * Run all indexers on a single Txo and populate its data/owner/basket
+     */
+    async runIndexersOnTxo(txo) {
+        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,
+                };
+                if (result.owner) {
+                    txo.owner = result.owner;
+                }
+                if (result.basket) {
+                    txo.basket = result.basket;
+                }
+            }
+        }
+    }
+    /**
+     * Parse all inputs - run indexers on source outputs to populate ctx.spends
+     */
+    async parseInputs(ctx) {
+        for (const input of ctx.tx.inputs) {
+            if (!input.sourceTransaction)
+                continue;
+            const sourceOutput = input.sourceTransaction.outputs[input.sourceOutputIndex];
+            if (!sourceOutput)
+                continue;
+            const sourceTxid = input.sourceTransaction.id("hex");
+            const sourceVout = input.sourceOutputIndex;
+            // Create Txo for the spent output
+            const spendTxo = {
+                output: sourceOutput,
+                outpoint: new Outpoint(sourceTxid, sourceVout),
+                data: {},
+            };
+            // Run all indexers on the spent output
+            await this.runIndexersOnTxo(spendTxo);
+            // Add to spends
+            ctx.spends.push(spendTxo);
+        }
+    }
+    /**
+     * Load a transaction by txid.
+     * Checks storage first, falls back to beef service.
+     *
+     * @param txid - Transaction ID to load
+     * @returns Transaction (without source transactions hydrated)
+     */
+    async loadTransaction(txid) {
+        // Check storage first
+        const userId = await this.storage.getUserId();
+        const existingTx = await this.storage.runAsStorageProvider(async (sp) => {
+            const txs = await sp.findTransactions({ partial: { userId, txid } });
+            return txs.length > 0 ? txs[0] : null;
+        });
+        if (existingTx?.rawTx) {
+            return Transaction.fromBinary(existingTx.rawTx);
+        }
+        // Fall back to network
+        const beefBytes = await this.services.beef.getBeef(txid);
+        const tx = Transaction.fromBEEF(Array.from(beefBytes));
+        return tx;
+    }
+    /**
+     * Load and attach source transactions for all inputs (1 level deep).
+     * Modifies the transaction in place.
+     */
+    async hydrateSourceTransactions(tx) {
+        const loaded = new Map();
+        for (const input of tx.inputs) {
+            if (!input.sourceTransaction && input.sourceTXID) {
+                if (!loaded.has(input.sourceTXID)) {
+                    loaded.set(input.sourceTXID, await this.loadTransaction(input.sourceTXID));
+                }
+                input.sourceTransaction = loaded.get(input.sourceTXID);
+            }
+        }
+    }
+    /**
+     * Build minimal parse context from transaction
+     */
+    buildParseContext(tx) {
+        const txid = tx.id("hex");
+        return {
+            tx,
+            txid,
+            txos: tx.outputs.map((output, vout) => ({
+                output,
+                outpoint: new Outpoint(txid, vout),
+                data: {},
+            })),
+            spends: [],
+            summary: {},
+            indexers: this.indexers,
+        };
+    }
+    /**
+     * Calculate the byte offset and length of each output's locking script
+     * within the raw transaction binary. This is needed for wallet-toolbox's
+     * listOutputs to extract locking scripts on demand.
+     */
+    calculateScriptOffsets(tx) {
+        const rawTx = tx.toBinary();
+        const reader = new Utils.Reader(rawTx);
+        // Skip version (4 bytes)
+        reader.pos = 4;
+        // Read input count (varint)
+        const inputCount = reader.readVarIntNum();
+        // Skip all inputs
+        for (let i = 0; i < inputCount; i++) {
+            reader.pos += 32; // txid
+            reader.pos += 4; // vout
+            const scriptLen = reader.readVarIntNum();
+            reader.pos += scriptLen; // unlocking script
+            reader.pos += 4; // sequence
+        }
+        // Read output count (varint)
+        const outputCount = reader.readVarIntNum();
+        // Calculate offset for each output's locking script
+        const offsets = [];
+        for (let i = 0; i < outputCount; i++) {
+            reader.pos += 8; // satoshis (8 bytes)
+            const scriptLen = reader.readVarIntNum();
+            const scriptOffset = reader.pos;
+            reader.pos += scriptLen; // locking script
+            offsets.push({ offset: scriptOffset, length: scriptLen });
+        }
+        return offsets;
+    }
+    /**
+     * Ingest a transaction by running it through indexers and writing directly to storage.
+     *
+     * This is the main entry point for adding external transactions to the wallet.
+     * The indexers extract basket, tags, and custom instructions which are then
+     * written directly to the wallet's storage.
+     *
+     * Unlike internalizeAction, this method also marks any wallet outputs that are
+     * consumed as inputs in the transaction as spent (spentBy, spendable: false).
+     *
+     * @param tx - Transaction to ingest
+     * @param description - Human-readable description
+     * @param labels - Optional labels for the transaction
+     * @param isBroadcasted - Whether this transaction has been broadcast (affects validation)
+     * @returns Result including parse details for all outputs
+     */
+    async ingestTransaction(tx, description, labels, isBroadcasted = true) {
+        // Run through indexers (parseTransaction handles loading source txs)
+        const ctx = await this.parseTransaction(tx, isBroadcasted);
+        const txid = tx.id("hex");
+        // Calculate script offsets for all outputs (needed for listOutputs with locking scripts)
+        const scriptOffsets = this.calculateScriptOffsets(tx);
+        // Collect owned outputs
+        const ownedTxos = ctx.txos.filter((txo) => txo.owner && this.owners.has(txo.owner));
+        // Get userId from storage manager
+        const userId = await this.storage.getUserId();
+        // Pre-fetch header for merkle proof BEFORE starting the IDB transaction
+        // This avoids IDB auto-commit issue caused by network calls inside transaction
+        let provenTxBlockHash;
+        let provenTxMerkleRoot;
+        if (tx.merklePath) {
+            const mp = tx.merklePath;
+            const header = await this.services.getHeaderForHeight(mp.blockHeight);
+            provenTxBlockHash = Utils.toHex(Hash.hash256(header).reverse());
+            provenTxMerkleRoot = mp.computeRoot();
+        }
+        // Write directly to storage within a transaction
+        const internalizedCount = await this.storage.runAsStorageProvider(async (sp) => {
+            return await sp.transaction(async (trx) => {
+                // Check if transaction already exists
+                const existingTxs = await sp.findTransactions({
+                    partial: { userId, txid },
+                    trx,
+                });
+                let transactionId;
+                let isNewTransaction = false;
+                if (existingTxs.length > 0) {
+                    // Transaction already exists, use its ID
+                    transactionId = existingTxs[0].transactionId;
+                }
+                else {
+                    // Determine if this is an outgoing transaction (we're spending our own outputs)
+                    // by checking if any inputs spend our outputs
+                    let isOutgoing = false;
+                    let satoshisSpent = 0;
+                    for (const input of tx.inputs) {
+                        // Get source txid from either sourceTXID or sourceTransaction
+                        const sourceTxid = input.sourceTXID || input.sourceTransaction?.id("hex");
+                        if (sourceTxid) {
+                            const spentOutputs = await sp.findOutputs({
+                                partial: {
+                                    userId,
+                                    txid: sourceTxid,
+                                    vout: input.sourceOutputIndex,
+                                },
+                                trx,
+                            });
+                            if (spentOutputs.length > 0) {
+                                isOutgoing = true;
+                                satoshisSpent += spentOutputs[0].satoshis;
+                            }
+                        }
+                    }
+                    // Calculate satoshis received
+                    const satoshisReceived = ownedTxos.reduce((sum, txo) => sum + (txo.output.satoshis || 0), 0);
+                    // Net satoshis: positive if receiving, negative if spending
+                    const satoshis = satoshisReceived - satoshisSpent;
+                    // Create transaction record
+                    const now = new Date();
+                    const reference = Utils.toBase64(Random(12));
+                    const newTx = {
+                        created_at: now,
+                        updated_at: now,
+                        transactionId: 0,
+                        userId,
+                        status: isBroadcasted
+                            ? "completed"
+                            : "unproven",
+                        reference,
+                        isOutgoing,
+                        satoshis,
+                        description,
+                        version: tx.version,
+                        lockTime: tx.lockTime,
+                        txid,
+                        rawTx: Array.from(tx.toBinary()),
+                    };
+                    transactionId = await sp.insertTransaction(newTx, trx);
+                    isNewTransaction = true;
+                    // Store in ProvenTx or ProvenTxReq for listOutputs compatibility
+                    // This enables include: 'entire transactions' and 'locking scripts'
+                    if (tx.merklePath && provenTxBlockHash && provenTxMerkleRoot) {
+                        // Transaction has merkle proof - store as ProvenTx
+                        const existingProven = await sp.findProvenTxs({
+                            partial: { txid },
+                            trx,
+                        });
+                        if (existingProven.length === 0) {
+                            const mp = tx.merklePath;
+                            const index = mp.path[0].find((l) => l.hash === txid)?.offset ?? 0;
+                            const provenNow = new Date();
+                            await sp.insertProvenTx({
+                                created_at: provenNow,
+                                updated_at: provenNow,
+                                provenTxId: 0,
+                                txid,
+                                height: mp.blockHeight,
+                                index,
+                                merklePath: mp.toBinary(),
+                                rawTx: Array.from(tx.toBinary()),
+                                blockHash: provenTxBlockHash,
+                                merkleRoot: provenTxMerkleRoot,
+                            }, trx);
+                        }
+                    }
+                    else if (!tx.merklePath) {
+                        // No merkle proof - store as ProvenTxReq (pending confirmation)
+                        const existingReq = await sp.findProvenTxReqs({
+                            partial: { txid },
+                            trx,
+                        });
+                        if (existingReq.length === 0) {
+                            // Build inputBEEF from source transactions
+                            const inputBeef = new Beef();
+                            inputBeef.mergeTransaction(tx);
+                            const reqNow = new Date();
+                            await sp.insertProvenTxReq({
+                                created_at: reqNow,
+                                updated_at: reqNow,
+                                provenTxReqId: 0,
+                                status: isBroadcasted ? "unmined" : "unsent",
+                                attempts: 0,
+                                notified: false,
+                                txid,
+                                history: "[]",
+                                notify: "{}",
+                                rawTx: Array.from(tx.toBinary()),
+                                inputBEEF: inputBeef.toBinary(),
+                            }, trx);
+                        }
+                    }
+                    // Add labels
+                    for (const label of labels || []) {
+                        const txLabel = await sp.findOrInsertTxLabel(userId, label, trx);
+                        if (txLabel.txLabelId) {
+                            await sp.findOrInsertTxLabelMap(transactionId, txLabel.txLabelId, trx);
+                        }
+                    }
+                }
+                // Mark inputs as spent (only for new transactions)
+                if (isNewTransaction) {
+                    for (const input of tx.inputs) {
+                        // Get source txid from either sourceTXID or sourceTransaction
+                        const sourceTxid = input.sourceTXID || input.sourceTransaction?.id("hex");
+                        if (sourceTxid) {
+                            const spentOutputs = await sp.findOutputs({
+                                partial: {
+                                    userId,
+                                    txid: sourceTxid,
+                                    vout: input.sourceOutputIndex,
+                                },
+                                trx,
+                            });
+                            if (spentOutputs.length > 0) {
+                                const output = spentOutputs[0];
+                                // Mark as spent
+                                if (output.outputId) {
+                                    await sp.updateOutput(output.outputId, {
+                                        spendable: false,
+                                        spentBy: transactionId,
+                                    }, trx);
+                                }
+                            }
+                        }
+                    }
+                }
+                // Create output records for owned outputs
+                let outputsCreated = 0;
+                for (const txo of ownedTxos) {
+                    // Check if output already exists
+                    const existingOutputs = await sp.findOutputs({
+                        partial: { userId, txid, vout: txo.outpoint.vout },
+                        trx,
+                    });
+                    if (existingOutputs.length > 0) {
+                        // Output already exists, skip
+                        continue;
+                    }
+                    // Collect tags and content from all indexer data
+                    const tags = [];
+                    let content;
+                    if (txo.owner) {
+                        tags.push(`own:${txo.owner}`);
+                    }
+                    for (const indexData of Object.values(txo.data)) {
+                        if (indexData.tags) {
+                            tags.push(...indexData.tags);
+                        }
+                        // Use first non-empty content found
+                        if (!content && indexData.content) {
+                            content = indexData.content;
+                        }
+                    }
+                    // Get or create basket
+                    const basketName = txo.basket || "default";
+                    const basket = await sp.findOrInsertOutputBasket(userId, basketName, trx);
+                    // Create output record
+                    const now = new Date();
+                    const scriptInfo = scriptOffsets[txo.outpoint.vout];
+                    const newOutput = {
+                        created_at: now,
+                        updated_at: now,
+                        outputId: 0,
+                        userId,
+                        transactionId,
+                        basketId: basket.basketId,
+                        spendable: true,
+                        change: basketName === "default",
+                        outputDescription: "",
+                        vout: txo.outpoint.vout,
+                        satoshis: txo.output.satoshis || 0,
+                        providedBy: "you",
+                        purpose: basketName === "default" ? "change" : "",
+                        type: "custom",
+                        txid,
+                        lockingScript: Array.from(txo.output.lockingScript.toBinary()),
+                        scriptOffset: scriptInfo?.offset,
+                        scriptLength: scriptInfo?.length,
+                        spentBy: undefined,
+                        customInstructions: content?.substring(0, 1000),
+                    };
+                    const outputId = await sp.insertOutput(newOutput, trx);
+                    // Add tags to output
+                    for (const tag of tags) {
+                        const outputTag = await sp.findOrInsertOutputTag(userId, tag, trx);
+                        if (outputTag.outputTagId) {
+                            await sp.findOrInsertOutputTagMap(outputId, outputTag.outputTagId, trx);
+                        }
+                    }
+                    outputsCreated++;
+                }
+                return outputsCreated;
+            });
+        });
+        return { parseContext: ctx, internalizedCount };
+    }
+    /**
+     * Broadcast a transaction and ingest it into the wallet if successful.
+     *
+     * @param tx - Transaction to broadcast
+     * @param description - Human-readable description for the transaction
+     * @param labels - Optional labels for the transaction
+     * @returns The ingest result if successful
+     * @throws Error if broadcast fails
+     */
+    async broadcast(tx, description, labels) {
+        const txid = tx.id("hex");
+        const beef = new Beef();
+        beef.mergeTransaction(tx);
+        const results = await this.services.postBeef(beef, [txid]);
+        const result = results[0];
+        if (result.status !== "success") {
+            const errorMsg = result.error?.message || "Broadcast failed";
+            throw new Error(`Broadcast failed for ${txid}: ${errorMsg}`);
+        }
+        return this.ingestTransaction(tx, description, labels, true);
+    }
+    // ===== Queue-Based Sync =====
+    /**
+     * Start queue-based sync for all owner addresses.
+     * Requires syncQueue to be provided in constructor args.
+     *
+     * This method:
+     * 1. Opens SSE stream and enqueues outputs
+     * 2. Processes queue in batches using Promise.all()
+     * 3. Continues until queue is empty and stream is done
+     */
+    async sync() {
+        if (!this.syncQueue) {
+            throw new Error("syncQueue not provided - provide syncQueue in constructor");
+        }
+        if (this.syncRunning) {
+            return;
+        }
+        const addresses = Array.from(this.owners);
+        if (addresses.length === 0) {
+            return;
+        }
+        this.syncRunning = true;
+        this.syncStopRequested = false;
+        // Reset any items stuck in "processing" from a previous crashed session
+        await this.syncQueue.resetProcessing();
+        // Get last queued score from queue state
+        const state = await this.syncQueue.getState();
+        const fromScore = state.lastQueuedScore;
+        // Fetch current height once for reorg protection checks
+        const currentHeight = await this.services.getHeight();
+        this.emit("sync:start", { addresses });
+        // Start SSE stream
+        let streamDone = false;
+        const unsubscribe = this.services.owner.sync(addresses, async (output) => {
+            await this.handleSyncOutput(output, currentHeight);
+        }, fromScore, () => {
+            streamDone = true;
+        }, (error) => {
+            streamDone = true;
+            this.emit("sync:error", { message: error.message });
+        });
+        this.activeQueueSync = unsubscribe;
+        // Start processing loop
+        await this.processQueueLoop(streamDone, () => streamDone);
+        this.syncRunning = false;
+        this.activeQueueSync = null;
+    }
+    /**
+     * Handle a single output from the SSE stream.
+     * Enqueues to the sync queue and updates lastQueuedScore with reorg protection.
+     */
+    async handleSyncOutput(output, currentHeight) {
+        if (!this.syncQueue)
+            return;
+        // Enqueue the output
+        await this.syncQueue.enqueue([
+            {
+                outpoint: output.outpoint,
+                score: output.score,
+                spendTxid: output.spendTxid,
+            },
+        ]);
+        // Update lastQueuedScore with reorg protection
+        const blockHeight = Math.floor(output.score);
+        if (blockHeight <= currentHeight - REORG_SAFE_DEPTH) {
+            await this.syncQueue.setState({
+                lastQueuedScore: output.score,
+                lastSyncedAt: Date.now(),
+            });
+        }
+    }
+    /**
+     * Process queue in batches until empty or stopped.
+     */
+    async processQueueLoop(_streamDone, isStreamDone) {
+        if (!this.syncQueue)
+            return;
+        while (!this.syncStopRequested) {
+            // claim() returns items already grouped by txid, all marked as "processing"
+            const byTxid = await this.syncQueue.claim(this.syncBatchSize);
+            if (byTxid.size === 0) {
+                if (isStreamDone()) {
+                    // Stream done and queue empty - sync complete
+                    this.emit("sync:complete", {});
+                    break;
+                }
+                // Queue empty but stream still running - wait a bit
+                await new Promise((r) => setTimeout(r, 100));
+                continue;
+            }
+            // Process each txid in parallel
+            await Promise.all(Array.from(byTxid.entries()).map(([txid, txidItems]) => this.processTxid(txid, txidItems)));
+            // Emit progress
+            const stats = await this.syncQueue.getStats();
+            this.emit("sync:progress", {
+                pending: stats.pending,
+                done: stats.done,
+                failed: stats.failed,
+            });
+        }
+    }
+    /**
+     * Group queue items by txid.
+     * @deprecated - claim() now returns items already grouped
+     */
+    groupItemsByTxid(items) {
+        const byTxid = new Map();
+        for (const item of items) {
+            const txid = item.outpoint.substring(0, 64);
+            const existing = byTxid.get(txid);
+            if (existing) {
+                existing.push(item);
+            }
+            else {
+                byTxid.set(txid, [item]);
+            }
+        }
+        return byTxid;
+    }
+    /**
+     * Process a single txid - ingest transaction and complete queue items.
+     * Items are already marked as "processing" by claim().
+     */
+    async processTxid(txid, items) {
+        if (!this.syncQueue)
+            return;
+        try {
+            const itemIds = items.map((i) => i.id);
+            // Build spend map: vout -> spendTxid
+            const spendMap = new Map();
+            for (const item of items) {
+                if (item.spendTxid) {
+                    const vout = Number.parseInt(item.outpoint.substring(65), 10);
+                    spendMap.set(vout, item.spendTxid);
+                }
+            }
+            // Check if this is purely a spend-only batch (all items have spendTxid, no new outputs)
+            const hasUnspentCreation = items.some((item) => !item.spendTxid);
+            if (hasUnspentCreation) {
+                // Need to ingest the transaction
+                await this.ingestWithSpendInfo(txid, spendMap);
+            }
+            else {
+                // All items are spends - just mark outputs as spent
+                await this.markOutputsSpent(items);
+            }
+            // Complete all items
+            await this.syncQueue.completeMany(itemIds);
+        }
+        catch (error) {
+            this.emit("sync:error", {
+                message: error instanceof Error ? error.message : String(error),
+            });
+            // Mark items as failed
+            for (const item of items) {
+                await this.syncQueue.fail(item.id, String(error));
+            }
+        }
+    }
+    /**
+     * Ingest a transaction with knowledge of which outputs are already spent.
+     */
+    async ingestWithSpendInfo(txid, spendMap) {
+        // Load and ingest the transaction
+        const tx = await this.loadTransaction(txid);
+        const result = await this.ingestTransaction(tx, "1sat-sync");
+        // Mark any outputs that we know are spent
+        if (spendMap.size > 0) {
+            const userId = await this.storage.getUserId();
+            await this.storage.runAsStorageProvider(async (sp) => {
+                await sp.transaction(async (trx) => {
+                    for (const [vout] of spendMap) {
+                        const outputs = await sp.findOutputs({
+                            partial: { userId, txid, vout },
+                            trx,
+                        });
+                        if (outputs.length > 0 && outputs[0].spendable) {
+                            const output = outputs[0];
+                            if (output.outputId) {
+                                await sp.updateOutput(output.outputId, { spendable: false }, trx);
+                            }
+                        }
+                    }
+                });
+            });
+        }
+    }
+    /**
+     * Mark outputs as spent for spend-only queue items.
+     */
+    async markOutputsSpent(items) {
+        const userId = await this.storage.getUserId();
+        await this.storage.runAsStorageProvider(async (sp) => {
+            await sp.transaction(async (trx) => {
+                for (const item of items) {
+                    if (!item.spendTxid)
+                        continue;
+                    const txid = item.outpoint.substring(0, 64);
+                    const vout = Number.parseInt(item.outpoint.substring(65), 10);
+                    const outputs = await sp.findOutputs({
+                        partial: { userId, txid, vout },
+                        trx,
+                    });
+                    if (outputs.length > 0 && outputs[0].spendable && outputs[0].outputId) {
+                        await sp.updateOutput(outputs[0].outputId, { spendable: false }, trx);
+                    }
+                }
+            });
+        });
+    }
+    /**
+     * Stop the sync.
+     */
+    stopSync() {
+        this.syncStopRequested = true;
+        if (this.activeQueueSync) {
+            this.activeQueueSync();
+            this.activeQueueSync = null;
+        }
+        // Also stop individual components
+        this.stopStream();
+        this.stopProcessor();
+    }
+    /**
+     * Close the wallet and cleanup all sync connections.
+     */
+    close() {
+        this.stopSync();
+        this.services.close();
+    }
+    /**
+     * Check if sync is currently running.
+     */
+    isSyncing() {
+        return this.syncRunning;
+    }
+    /**
+     * Get the sync queue instance (if provided).
+     */
+    getQueue() {
+        return this.syncQueue;
+    }
+    // ===== Separate Stream/Processor Controls (for testing) =====
+    /**
+     * Start only the SSE stream, enqueueing outputs without processing.
+     * Useful for testing to observe queue buildup.
+     */
+    async startStream() {
+        if (!this.syncQueue) {
+            throw new Error("syncQueue not provided");
+        }
+        if (this.sseStreamActive) {
+            return;
+        }
+        const addresses = Array.from(this.owners);
+        if (addresses.length === 0) {
+            return;
+        }
+        const state = await this.syncQueue.getState();
+        const fromScore = state.lastQueuedScore;
+        // Fetch current height once for reorg protection checks
+        const currentHeight = await this.services.getHeight();
+        this.sseStreamActive = true;
+        this.streamDone = false;
+        this.emit("sync:start", { addresses });
+        this.sseUnsubscribe = this.services.owner.sync(addresses, async (output) => {
+            await this.handleSyncOutput(output, currentHeight);
+        }, fromScore, () => {
+            this.streamDone = true;
+            this.sseStreamActive = false;
+        }, (error) => {
+            this.streamDone = true;
+            this.sseStreamActive = false;
+            this.emit("sync:error", { message: error.message });
+        });
+    }
+    /**
+     * Stop the SSE stream.
+     */
+    stopStream() {
+        if (this.sseUnsubscribe) {
+            this.sseUnsubscribe();
+            this.sseUnsubscribe = null;
+        }
+        this.sseStreamActive = false;
+    }
+    /**
+     * Check if SSE stream is active.
+     */
+    isStreamActive() {
+        return this.sseStreamActive;
+    }
+    /**
+     * Check if SSE stream has completed.
+     */
+    isStreamDone() {
+        return this.streamDone;
+    }
+    /**
+     * Start only the queue processor, without starting a new SSE stream.
+     * Useful for testing to process queued items independently.
+     */
+    async startProcessor() {
+        if (!this.syncQueue) {
+            throw new Error("syncQueue not provided");
+        }
+        if (this.processorActive) {
+            return;
+        }
+        this.processorActive = true;
+        this.processorStopRequested = false;
+        // Reset any items stuck in "processing" from a previous crashed session
+        await this.syncQueue.resetProcessing();
+        while (!this.processorStopRequested) {
+            // claim() returns items already grouped by txid, all marked as "processing"
+            const byTxid = await this.syncQueue.claim(this.syncBatchSize);
+            if (byTxid.size === 0) {
+                // Queue empty - wait a bit and check again
+                await new Promise((r) => setTimeout(r, 100));
+                continue;
+            }
+            // Process each txid in parallel
+            await Promise.all(Array.from(byTxid.entries()).map(([txid, txidItems]) => this.processTxid(txid, txidItems)));
+            // Emit progress
+            const stats = await this.syncQueue.getStats();
+            this.emit("sync:progress", {
+                pending: stats.pending,
+                done: stats.done,
+                failed: stats.failed,
+            });
+        }
+        this.processorActive = false;
+    }
+    /**
+     * Stop the queue processor.
+     */
+    stopProcessor() {
+        this.processorStopRequested = true;
+    }
+    /**
+     * Check if queue processor is active.
+     */
+    isProcessorActive() {
+        return this.processorActive;
+    }
+}