@1sat/wallet-toolbox 0.0.1 → 0.0.2

package/README.md

@@ -186,6 +186,26 @@ const services = new OneSatServices("main", "https://ordfs.network");
 | `getBsv21TokenByTxid(tokenId, txid)` | Get BSV21 token data |
 | `getBsv21TokenDetails(tokenId)` | Get BSV21 token metadata (cached) |
 
+#### Available Clients
+
+OneSatServices exposes specialized API clients as public properties:
+
+| Client | Property | Purpose |
+|--------|----------|---------|
+| Chaintracks | `.chaintracks` | Block headers and chain tracking |
+| BEEF | `.beef` | Raw transactions and BEEF proofs |
+| Arcade | `.arcade` | Transaction broadcasting |
+| TXO | `.txo` | Transaction output queries |
+| Owner | `.owner` | Address queries and SSE sync |
+| OrdFS | `.ordfs` | Content and inscription metadata |
+| BSV21 | `.bsv21` | BSV21 token data |
+
+```typescript
+const services = new OneSatServices("main");
+const rawTx = await services.beef.getRawTx(txid);
+const metadata = await services.ordfs.getMetadata(outpoint);
+```
+
 ---
 
 ### ReadOnlySigner
@@ -242,25 +262,6 @@ Tags enable filtered queries via `listOutputs({ tags })`. Tags are only added fo
 
 ---
 
-### TransactionParser
-
-Runs indexers over transactions to extract basket/tags for wallet-toolbox storage.
-
-```typescript
-import { TransactionParser, FundIndexer, OriginIndexer } from "@1sat/wallet-toolbox";
-
-const parser = new TransactionParser(
-  [new FundIndexer(owners, "mainnet"), new OriginIndexer(owners, "mainnet", services)],
-  owners,
-  services
-);
-
-const result = await parser.parse(transaction, true);
-// result.outputs: ParsedOutput[] with vout, basket, tags, customInstructions
-```
-
----
-
 ## Project Status
 
 ### Completed
@@ -269,12 +270,12 @@ const result = await parser.parse(transaction, true);
 - [x] Read-only mode via public key
 - [x] OneSatServices (WalletServices implementation)
 - [x] All indexers migrated from yours-wallet
-- [x] TransactionParser for indexed ingestion
 - [x] `ingestTransaction()` method
 - [x] `syncAddress()` / `syncAll()` synchronization
 - [x] Event system for sync progress
 - [x] `broadcast()` method
 - [x] `getChainTracker()` implementation
+- [x] Modular API client architecture
 
 ### TODO
 
@@ -287,7 +288,6 @@ const result = await parser.parse(transaction, true);
   - [ ] `getScriptHashHistory()`
   - [ ] `hashToHeader()`
   - [ ] `nLockTimeIsFinal()`
-- [ ] Improve basket/tag extraction in TransactionParser
 - [ ] Tests
 - [ ] Integration with yours-wallet
 

package/dist/OneSatWallet.d.ts

@@ -1,37 +1,68 @@
-import { Wallet, WalletStorageManager } from "@bsv/wallet-toolbox/mobile";
+import { type PrivateKey, Transaction } from "@bsv/sdk";
+import { Wallet, type WalletStorageManager } from "@bsv/wallet-toolbox/mobile";
 import type { Chain } from "@bsv/wallet-toolbox/mobile/out/src/sdk/types";
-import { PrivateKey, Transaction, type InternalizeActionResult } from "@bsv/sdk";
-export interface SyncStartEvent {
-    address: string;
-    fromScore: number;
-}
-export interface SyncProgressEvent {
-    address: string;
-    processed: number;
-    remaining: number;
-    currentScore: number;
-    done: boolean;
-}
-export interface SyncTxEvent {
-    address: string;
-    txid: string;
-    type: "output" | "spend";
-}
-export interface SyncErrorEvent {
-    address: string;
-    error: Error;
-}
-export interface SyncCompleteEvent {
-    address: string;
-    processed: number;
-    finalScore: number;
+import { Outpoint } from "./indexers/Outpoint";
+import type { Indexer, ParseContext, Txo } from "./indexers/types";
+import { OneSatServices, type SyncOutput } from "./services/OneSatServices";
+/**
+ * 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:start": SyncStartEvent;
-    "sync:progress": SyncProgressEvent;
-    "sync:tx": SyncTxEvent;
-    "sync:error": SyncErrorEvent;
-    "sync:complete": SyncCompleteEvent;
+    "sync:start": {
+        address: string;
+        fromScore: number;
+    };
+    "sync:output": {
+        address: string;
+        output: SyncOutput;
+    };
+    "sync:skipped": {
+        address: string;
+        outpoint: string;
+        reason: string;
+    };
+    "sync:parsed": {
+        address: string;
+        txid: string;
+        parseContext: ParseContext;
+        internalizedCount: number;
+    };
+    "sync:error": {
+        address: string;
+        error: Error;
+    };
+    "sync:complete": {
+        address: string;
+    };
+    "syncAll:start": {
+        addresses: string[];
+        fromScore: number;
+    };
+    "syncAll:output": {
+        output: SyncOutput;
+    };
+    "syncAll:skipped": {
+        outpoint: string;
+        reason: string;
+    };
+    "syncAll:parsed": {
+        txid: string;
+        parseContext: ParseContext;
+        internalizedCount: number;
+    };
+    "syncAll:error": {
+        error: Error;
+    };
+    "syncAll:complete": {
+        addresses: string[];
+    };
 }
 type EventCallback<T> = (event: T) => void;
 export interface OneSatWalletArgs {
@@ -52,13 +83,18 @@ export interface OneSatWalletArgs {
      */
     owners?: Set<string>;
     /**
-     * Custom OrdFS server URL (default: https://ordfs.network)
+     * Indexers to use for parsing transactions.
+     * If not provided, default indexers will be used.
      */
-    ordfsUrl?: string;
+    indexers?: Indexer[];
     /**
-     * Custom 1Sat indexer URL (default: based on chain - mainnet or testnet)
+     * Custom 1Sat API URL (default: based on chain - mainnet or testnet)
      */
     onesatUrl?: string;
+    /**
+     * Automatically start syncing all owner addresses on construction.
+     */
+    autoSync?: boolean;
 }
 /**
  * OneSatWallet extends the BRC-100 Wallet with 1Sat-specific indexing and services.
@@ -69,64 +105,156 @@ export interface OneSatWalletArgs {
  */
 export declare class OneSatWallet extends Wallet {
     private readonly isReadOnly;
-    private readonly parser;
-    private readonly oneSatServices;
+    private readonly indexers;
+    readonly services: OneSatServices;
     private owners;
     private listeners;
+    private activeSyncs;
+    private activeMultiSync;
     constructor(args: OneSatWalletArgs);
     /**
      * Returns true if this wallet was created with only a public key.
      * Read-only wallets can query but not sign transactions.
      */
     get readOnly(): boolean;
+    /**
+     * 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;
     /**
-     * Subscribe to wallet events.
+     * 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
      */
-    on<K extends keyof OneSatWalletEvents>(event: K, callback: EventCallback<OneSatWalletEvents[K]>): void;
+    parseTransaction(txOrTxid: Transaction | string, isBroadcasted?: boolean): Promise<ParseContext>;
     /**
-     * Unsubscribe from wallet events.
+     * 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
      */
-    off<K extends keyof OneSatWalletEvents>(event: K, callback: EventCallback<OneSatWalletEvents[K]>): void;
-    private emit;
+    parseOutput(output: Transaction["outputs"][0], outpoint: Outpoint): Promise<Txo>;
     /**
-     * Ingest a transaction by running it through indexers and then internalizing.
+     * 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;
+    /**
+     * 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
-     * passed to the underlying wallet's internalizeAction.
+     * 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 or BEEF to ingest
+     * @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<InternalizeActionResult>;
+    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 internalize result if successful
+     * @returns The ingest result if successful
      * @throws Error if broadcast fails
      */
-    broadcast(tx: Transaction, description: string, labels?: string[]): Promise<InternalizeActionResult>;
+    broadcast(tx: Transaction, description: string, labels?: string[]): Promise<IngestResult>;
     /**
-     * Sync a single address from the 1Sat indexer.
-     * Fetches new outputs and spends, ingesting transactions as needed.
+     * Sync a single address from the 1Sat indexer using Server-Sent Events.
+     * Runs in the background - use stopSync() or close() to stop.
      *
      * @param address - The address to sync
-     * @param limit - Max outputs per page (default 100)
      */
-    syncAddress(address: string, limit?: number): Promise<void>;
+    syncAddress(address: string, fromScore?: number): void;
+    /**
+     * Process a spend transaction during sync.
+     * Only marks our output as spent - doesn't ingest the spend tx.
+     * If the spend tx has outputs we own, they'll come through sync separately.
+     */
+    private processSpendTx;
+    /**
+     * Stop syncing a specific address.
+     */
+    stopSync(address: string): void;
+    /**
+     * Close the wallet and cleanup all active sync connections.
+     */
+    close(): void;
+    /**
+     * Start syncing all owner addresses using a single multi-owner SSE connection.
+     * This is more efficient than syncing each address individually.
+     *
+     * @param fromScore - Starting score (for pagination/resumption)
+     */
+    syncAll(fromScore?: number): void;
+    /**
+     * Process a spend transaction during multi-owner sync.
+     * Only marks our output as spent - doesn't ingest the spend tx.
+     */
+    private processSpendTxMulti;
+    /**
+     * Stop the multi-owner sync.
+     */
+    stopSyncAll(): void;
     /**
-     * Sync all owner addresses in parallel.
+     * Start syncing each owner address individually.
+     * For most cases, use syncAll() instead which uses a single connection.
      */
-    syncAll(): Promise<void>;
+    syncEach(): void;
 }
 export {};

package/dist/index.d.ts

@@ -1,7 +1,6 @@
-export { OneSatWallet, type OneSatWalletArgs, type OneSatWalletEvents, type SyncStartEvent, type SyncProgressEvent, type SyncTxEvent, type SyncErrorEvent, type SyncCompleteEvent, } from "./OneSatWallet";
-export { OneSatServices, type OrdfsMetadata } from "./services/OneSatServices";
+export { OneSatWallet, type OneSatWalletArgs, type OneSatWalletEvents, type IngestResult, } from "./OneSatWallet";
+export { OneSatServices, type SyncOutput } from "./services/OneSatServices";
+export type { OrdfsMetadata, Capability } from "./services/types";
+export * from "./services/client";
 export { ReadOnlySigner } from "./signers/ReadOnlySigner";
 export * from "./indexers";
-export { WalletStorageManager } from "@bsv/wallet-toolbox/mobile";
-export { StorageIdb } from "@bsv/wallet-toolbox/mobile/out/src/storage/StorageIdb";
-export type { Chain } from "@bsv/wallet-toolbox/mobile/out/src/sdk/types";