@1sat/wallet-toolbox 0.0.9 → 0.0.10

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export { ReadOnlySigner } from "./signers/ReadOnlySigner";
 export * from "./indexers";
 export * from "./sync";
 export * from "./cwi";
+export * from "./wallet";

package/dist/index.js

@@ -15,3 +15,5 @@ export * from "./indexers";
 export * from "./sync";
 // CWI (Chrome Wallet Interface) - BRC-100 implementations
 export * from "./cwi";
+// Wallet factory for creating 1Sat web wallets
+export * from "./wallet";

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 {};

package/dist/wallet/factory.js

@@ -0,0 +1,129 @@
+/**
+ * Factory for creating web wallets.
+ *
+ * This consolidates the common wallet setup used by both yours-wallet
+ * (browser extension) and 1sat-website (React app).
+ */
+import { KeyDeriver, PrivateKey } from "@bsv/sdk";
+import { Wallet, WalletStorageManager, StorageProvider, StorageIdb, StorageClient, WalletPermissionsManager, Services, Monitor, } from "@bsv/wallet-toolbox-mobile/out/src/index.client.js";
+import { OneSatServices } from "../services/OneSatServices";
+// Default database name for IndexedDB storage
+const DEFAULT_DATABASE_NAME = "wallet";
+// Default timeout for remote storage connection
+const DEFAULT_REMOTE_STORAGE_TIMEOUT = 5000;
+// Default fee model
+const DEFAULT_FEE_MODEL = { model: "sat/kb", value: 1 };
+/**
+ * Parse a private key from various input formats.
+ * Supports PrivateKey instance, WIF string, or hex string.
+ */
+function parsePrivateKey(input) {
+    if (input instanceof PrivateKey) {
+        return input;
+    }
+    // Try WIF first (starts with 5, K, L for mainnet or c for testnet)
+    if (/^[5KLc][1-9A-HJ-NP-Za-km-z]{50,51}$/.test(input)) {
+        return PrivateKey.fromWif(input);
+    }
+    // Try hex (64 characters)
+    if (/^[0-9a-fA-F]{64}$/.test(input)) {
+        return new PrivateKey(input);
+    }
+    // Last resort - try WIF anyway
+    try {
+        return PrivateKey.fromWif(input);
+    }
+    catch {
+        throw new Error("Invalid private key format. Expected PrivateKey instance, WIF string, or 64-char hex string.");
+    }
+}
+/**
+ * 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 async function createWebWallet(config) {
+    const { chain, adminOriginator, permissionsConfig } = config;
+    const feeModel = config.feeModel ?? DEFAULT_FEE_MODEL;
+    // 1. Parse private key and create KeyDeriver
+    const privateKey = parsePrivateKey(config.privateKey);
+    const identityPubKey = privateKey.toPublicKey().toString();
+    const keyDeriver = new KeyDeriver(privateKey);
+    // 2. Create fallback services and OneSatServices
+    const fallbackServices = new Services(chain);
+    const oneSatServices = new OneSatServices(chain, undefined, fallbackServices);
+    // 3. Create local storage
+    const storageOptions = StorageProvider.createStorageBaseOptions(chain);
+    storageOptions.feeModel = feeModel;
+    const localStorage = new StorageIdb(storageOptions);
+    await localStorage.migrate(DEFAULT_DATABASE_NAME, identityPubKey);
+    // 4. Create storage manager (local-only initially)
+    let storage = new WalletStorageManager(identityPubKey, localStorage);
+    await storage.makeAvailable();
+    // 5. Create the underlying Wallet
+    const underlyingWallet = new Wallet({
+        chain,
+        keyDeriver,
+        storage,
+        services: oneSatServices,
+    });
+    // 6. Attempt remote storage connection if URL provided
+    if (config.remoteStorageUrl) {
+        try {
+            const remoteClient = new StorageClient(underlyingWallet, config.remoteStorageUrl);
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Remote storage connection timeout")), DEFAULT_REMOTE_STORAGE_TIMEOUT));
+            await Promise.race([remoteClient.makeAvailable(), timeoutPromise]);
+            // Remote connected - recreate storage manager with backup
+            storage = new WalletStorageManager(identityPubKey, localStorage, [
+                remoteClient,
+            ]);
+            await storage.makeAvailable();
+            // Update wallet's storage reference
+            underlyingWallet._storage = storage;
+        }
+        catch {
+            // Graceful degradation - continue with local only
+        }
+    }
+    // 7. Wrap with permissions manager
+    const wallet = new WalletPermissionsManager(underlyingWallet, adminOriginator, permissionsConfig);
+    // 8. Create monitor (not started - consumer calls startTasks() when ready)
+    const monitor = new Monitor({
+        chain,
+        services: oneSatServices,
+        storage,
+        chaintracks: oneSatServices.chaintracks,
+        msecsWaitPerMerkleProofServiceReq: 500,
+        taskRunWaitMsecs: 5000,
+        abandonedMsecs: 300000,
+        unprovenAttemptsLimitTest: 10,
+        unprovenAttemptsLimitMain: 144,
+    });
+    monitor.addDefaultTasks();
+    // 9. Create cleanup function
+    const destroy = async () => {
+        monitor.stopTasks();
+        await monitor.destroy();
+        await underlyingWallet.destroy();
+    };
+    return {
+        wallet,
+        services: oneSatServices,
+        monitor,
+        destroy,
+    };
+}

package/dist/wallet/index.d.ts

@@ -0,0 +1 @@
+export * from "./factory";

package/dist/wallet/index.js

@@ -0,0 +1 @@
+export * from "./factory";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1sat/wallet-toolbox",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "BSV wallet library extending @bsv/wallet-toolbox with 1Sat Ordinals protocol support",
   "author": "1Sat Team",
   "license": "MIT",
@@ -41,9 +41,18 @@
     "@bsv/sdk": "^1.9.31",
     "buffer": "^6.0.3"
   },
+  "peerDependencies": {
+    "@bsv/wallet-toolbox-mobile": "npm:@bopen-io/wallet-toolbox-mobile@^1.7.19"
+  },
+  "peerDependenciesMeta": {
+    "@bsv/wallet-toolbox-mobile": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@bsv/wallet-toolbox": "npm:@bopen-io/wallet-toolbox@^1.7.19",
+    "@bsv/wallet-toolbox-mobile": "npm:@bopen-io/wallet-toolbox-mobile@^1.7.19",
     "@types/bun": "^1.3.4",
     "@types/chrome": "^0.1.32",
     "typescript": "^5.9.3"

package/dist/OneSatWallet.d.ts

@@ -1,316 +0,0 @@
-import { Transaction, type WalletInterface } from "@bsv/sdk";
-import type { WalletStorageManager, sdk as toolboxSdk } from "@bsv/wallet-toolbox";
-type Chain = toolboxSdk.Chain;
-import { Outpoint } from "./indexers/Outpoint";
-import type { Indexer, ParseContext, Txo } from "./indexers/types";
-import { OneSatServices } from "./services/OneSatServices";
-import type { SyncQueueStorage } from "./sync/types";
-/**
- * Result of ingestTransaction including parse context for debugging
- */
-export interface IngestResult {
-    parseContext: ParseContext;
-    internalizedCount: number;
-}
-/**
- * Events emitted by OneSatWallet during sync operations
- */
-export interface OneSatWalletEvents {
-    /** Sync started */
-    "sync:start": {
-        addresses: string[];
-    };
-    /** Sync progress update */
-    "sync:progress": {
-        pending: number;
-        done: number;
-        failed: number;
-    };
-    /** Sync complete (queue empty and stream done) */
-    "sync:complete": Record<string, never>;
-    /** Sync error */
-    "sync:error": {
-        message: string;
-    };
-}
-type EventCallback<T> = (event: T) => void;
-export interface OneSatWalletArgs {
-    /**
-     * The underlying BRC-100 wallet to wrap.
-     */
-    wallet: WalletInterface;
-    /**
-     * The storage manager from the wallet (needed for direct storage access).
-     */
-    storage: WalletStorageManager;
-    /**
-     * Network: 'main' or 'test'
-     */
-    chain: Chain;
-    /**
-     * Addresses owned by this wallet, used for filtering indexed outputs.
-     */
-    owners?: Set<string>;
-    /**
-     * Indexers to use for parsing transactions.
-     * If not provided, default indexers will be used.
-     */
-    indexers?: Indexer[];
-    /**
-     * Custom 1Sat API URL (default: based on chain - mainnet or testnet)
-     */
-    onesatUrl?: string;
-    /**
-     * Automatically start syncing all owner addresses on construction.
-     */
-    autoSync?: boolean;
-    /**
-     * Sync queue storage for background processing.
-     * If provided, enables queue-based sync via sync() method.
-     */
-    syncQueue?: SyncQueueStorage;
-    /**
-     * Batch size for queue processing (default: 20).
-     */
-    syncBatchSize?: number;
-}
-/**
- * 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 declare class OneSatWallet implements WalletInterface {
-    private readonly wallet;
-    private readonly storage;
-    private readonly indexers;
-    readonly services: OneSatServices;
-    private owners;
-    private listeners;
-    private syncQueue;
-    private syncBatchSize;
-    private syncRunning;
-    private syncStopRequested;
-    private activeQueueSync;
-    private sseStreamActive;
-    private sseUnsubscribe;
-    private processorActive;
-    private processorStopRequested;
-    private streamDone;
-    constructor(args: OneSatWalletArgs);
-    getPublicKey: WalletInterface["getPublicKey"];
-    revealCounterpartyKeyLinkage: WalletInterface["revealCounterpartyKeyLinkage"];
-    revealSpecificKeyLinkage: WalletInterface["revealSpecificKeyLinkage"];
-    encrypt: WalletInterface["encrypt"];
-    decrypt: WalletInterface["decrypt"];
-    createHmac: WalletInterface["createHmac"];
-    verifyHmac: WalletInterface["verifyHmac"];
-    createSignature: WalletInterface["createSignature"];
-    verifySignature: WalletInterface["verifySignature"];
-    createAction: WalletInterface["createAction"];
-    signAction: WalletInterface["signAction"];
-    abortAction: WalletInterface["abortAction"];
-    listActions: WalletInterface["listActions"];
-    internalizeAction: WalletInterface["internalizeAction"];
-    listOutputs: WalletInterface["listOutputs"];
-    relinquishOutput: WalletInterface["relinquishOutput"];
-    acquireCertificate: WalletInterface["acquireCertificate"];
-    listCertificates: WalletInterface["listCertificates"];
-    proveCertificate: WalletInterface["proveCertificate"];
-    relinquishCertificate: WalletInterface["relinquishCertificate"];
-    discoverByIdentityKey: WalletInterface["discoverByIdentityKey"];
-    discoverByAttributes: WalletInterface["discoverByAttributes"];
-    isAuthenticated: WalletInterface["isAuthenticated"];
-    waitForAuthentication: WalletInterface["waitForAuthentication"];
-    getHeight: WalletInterface["getHeight"];
-    getHeaderForHeight: WalletInterface["getHeaderForHeight"];
-    getNetwork: WalletInterface["getNetwork"];
-    getVersion: WalletInterface["getVersion"];
-    /**
-     * Subscribe to wallet events
-     */
-    on<K extends keyof OneSatWalletEvents>(event: K, callback: EventCallback<OneSatWalletEvents[K]>): void;
-    /**
-     * Unsubscribe from wallet events
-     */
-    off<K extends keyof OneSatWalletEvents>(event: K, callback: EventCallback<OneSatWalletEvents[K]>): void;
-    /**
-     * Emit a wallet event
-     */
-    private emit;
-    /**
-     * Add an address to the set of owned addresses.
-     * Outputs to these addresses will be indexed.
-     */
-    addOwner(address: string): void;
-    /**
-     * 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
-     */
-    parseTransaction(txOrTxid: Transaction | string, isBroadcasted?: boolean): Promise<ParseContext>;
-    /**
-     * 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
-     */
-    parseOutput(output: Transaction["outputs"][0], outpoint: Outpoint): Promise<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
-     */
-    loadTxo(outpoint: string): Promise<Txo>;
-    /**
-     * Run all indexers on a single Txo and populate its data/owner/basket
-     */
-    runIndexersOnTxo(txo: Txo): Promise<void>;
-    /**
-     * Parse all inputs - run indexers on source outputs to populate ctx.spends
-     */
-    private parseInputs;
-    /**
-     * 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)
-     */
-    loadTransaction(txid: string): Promise<Transaction>;
-    /**
-     * Load and attach source transactions for all inputs (1 level deep).
-     * Modifies the transaction in place.
-     */
-    hydrateSourceTransactions(tx: Transaction): Promise<void>;
-    /**
-     * Build minimal parse context from transaction
-     */
-    buildParseContext(tx: Transaction): ParseContext;
-    /**
-     * 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.
-     */
-    private calculateScriptOffsets;
-    /**
-     * 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
-     */
-    ingestTransaction(tx: Transaction, description: string, labels?: string[], isBroadcasted?: boolean): Promise<IngestResult>;
-    /**
-     * 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
-     */
-    broadcast(tx: Transaction, description: string, labels?: string[]): Promise<IngestResult>;
-    /**
-     * 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
-     */
-    sync(): Promise<void>;
-    /**
-     * Handle a single output from the SSE stream.
-     * Enqueues to the sync queue and updates lastQueuedScore with reorg protection.
-     */
-    private handleSyncOutput;
-    /**
-     * Process queue in batches until empty or stopped.
-     */
-    private processQueueLoop;
-    /**
-     * Group queue items by txid.
-     * @deprecated - claim() now returns items already grouped
-     */
-    private groupItemsByTxid;
-    /**
-     * Process a single txid - ingest transaction and complete queue items.
-     * Items are already marked as "processing" by claim().
-     */
-    private processTxid;
-    /**
-     * Ingest a transaction with knowledge of which outputs are already spent.
-     */
-    private ingestWithSpendInfo;
-    /**
-     * Mark outputs as spent for spend-only queue items.
-     */
-    private markOutputsSpent;
-    /**
-     * Stop the sync.
-     */
-    stopSync(): void;
-    /**
-     * Close the wallet and cleanup all sync connections.
-     */
-    close(): void;
-    /**
-     * Check if sync is currently running.
-     */
-    isSyncing(): boolean;
-    /**
-     * Get the sync queue instance (if provided).
-     */
-    getQueue(): SyncQueueStorage | null;
-    /**
-     * Start only the SSE stream, enqueueing outputs without processing.
-     * Useful for testing to observe queue buildup.
-     */
-    startStream(): Promise<void>;
-    /**
-     * Stop the SSE stream.
-     */
-    stopStream(): void;
-    /**
-     * Check if SSE stream is active.
-     */
-    isStreamActive(): boolean;
-    /**
-     * Check if SSE stream has completed.
-     */
-    isStreamDone(): boolean;
-    /**
-     * Start only the queue processor, without starting a new SSE stream.
-     * Useful for testing to process queued items independently.
-     */
-    startProcessor(): Promise<void>;
-    /**
-     * Stop the queue processor.
-     */
-    stopProcessor(): void;
-    /**
-     * Check if queue processor is active.
-     */
-    isProcessorActive(): boolean;
-}
-export {};