@bsv/wallet-toolbox-client 1.7.15 → 1.7.17

package/out/src/storage/WalletStorageManager.d.ts

@@ -0,0 +1,221 @@
+import { AbortActionArgs, AbortActionResult, Beef, InternalizeActionArgs, ListActionsResult, ListCertificatesResult, ListOutputsResult, RelinquishCertificateArgs, RelinquishOutputArgs, Validation } from '@bsv/sdk';
+import * as sdk from '../sdk';
+import { TableCertificate, TableCertificateX, TableOutput, TableOutputBasket, TableProvenTx, TableProvenTxReq, TableSettings, TableUser } from '../storage/schema/tables';
+import { StorageProvider } from './StorageProvider';
+declare class ManagedStorage {
+    storage: sdk.WalletStorageProvider;
+    isAvailable: boolean;
+    isStorageProvider: boolean;
+    settings?: TableSettings;
+    user?: TableUser;
+    constructor(storage: sdk.WalletStorageProvider);
+}
+/**
+ * The `WalletStorageManager` class delivers authentication checking storage access to the wallet.
+ *
+ * If manages multiple `StorageBase` derived storage services: one actice, the rest as backups.
+ *
+ * Of the storage services, one is 'active' at any one time.
+ * On startup, and whenever triggered by the wallet, `WalletStorageManager` runs a syncrhonization sequence:
+ *
+ * 1. While synchronizing, all other access to storage is blocked waiting.
+ * 2. The active service is confirmed, potentially triggering a resolution process if there is disagreement.
+ * 3. Changes are pushed from the active storage service to each inactive, backup service.
+ *
+ * Some storage services do not support multiple writers. `WalletStorageManager` manages wait-blocking write requests
+ * for these services.
+ */
+export declare class WalletStorageManager implements sdk.WalletStorage {
+    /**
+     * All configured stores including current active, backups, and conflicting actives.
+     */
+    _stores: ManagedStorage[];
+    /**
+     * True if makeAvailable has been run and access to managed stores (active) is allowed
+     */
+    _isAvailable: boolean;
+    /**
+     * The current active store which is only enabled if the store's user record activeStorage property matches its settings record storageIdentityKey property
+     */
+    _active?: ManagedStorage;
+    /**
+     * Stores to which state is pushed by updateBackups.
+     */
+    _backups?: ManagedStorage[];
+    /**
+     * Stores whose user record activeStorage property disagrees with the active store's user record activeStorage property.
+     */
+    _conflictingActives?: ManagedStorage[];
+    /**
+     * identityKey is always valid, userId and isActive are valid only if _isAvailable
+     */
+    _authId: sdk.AuthId;
+    /**
+     * Configured services if any. If valid, shared with stores (which may ignore it).
+     */
+    _services?: sdk.WalletServices;
+    /**
+     * Creates a new WalletStorageManager with the given identityKey and optional active and backup storage providers.
+     *
+     * @param identityKey The identity key of the user for whom this wallet is being managed.
+     * @param active An optional active storage provider. If not provided, no active storage will be set.
+     * @param backups An optional array of backup storage providers. If not provided, no backups will be set.
+     */
+    constructor(identityKey: string, active?: sdk.WalletStorageProvider, backups?: sdk.WalletStorageProvider[]);
+    isStorageProvider(): boolean;
+    isAvailable(): boolean;
+    /**
+     * The active storage is "enabled" only if its `storageIdentityKey` matches the user's currently selected `activeStorage`,
+     * and only if there are no stores with conflicting `activeStorage` selections.
+     *
+     * A wallet may be created without including the user's currently selected active storage. This allows readonly access to their wallet data.
+     *
+     * In addition, if there are conflicting `activeStorage` selections among backup storage providers then the active remains disabled.
+     */
+    get isActiveEnabled(): boolean;
+    /**
+     * @returns true if at least one WalletStorageProvider has been added.
+     */
+    canMakeAvailable(): boolean;
+    /**
+     * This async function must be called after construction and before
+     * any other async function can proceed.
+     *
+     * Runs through `_stores` validating all properties and partitioning across `_active`, `_backups`, `_conflictingActives`.
+     *
+     * @throws WERR_INVALID_PARAMETER if canMakeAvailable returns false.
+     *
+     * @returns {TableSettings} from the active storage.
+     */
+    makeAvailable(): Promise<TableSettings>;
+    private verifyActive;
+    getAuth(mustBeActive?: boolean): Promise<sdk.AuthId>;
+    getUserId(): Promise<number>;
+    getActive(): sdk.WalletStorageProvider;
+    getActiveSettings(): TableSettings;
+    getActiveUser(): TableUser;
+    getActiveStore(): string;
+    getActiveStoreName(): string;
+    getBackupStores(): string[];
+    getConflictingStores(): string[];
+    getAllStores(): string[];
+    private readonly readerLocks;
+    private readonly writerLocks;
+    private readonly syncLocks;
+    private readonly spLocks;
+    private getActiveLock;
+    private releaseActiveLock;
+    private getActiveForReader;
+    private releaseActiveForReader;
+    private getActiveForWriter;
+    private releaseActiveForWriter;
+    private getActiveForSync;
+    private releaseActiveForSync;
+    private getActiveForStorageProvider;
+    private releaseActiveForStorageProvider;
+    runAsWriter<R>(writer: (active: sdk.WalletStorageWriter) => Promise<R>): Promise<R>;
+    runAsReader<R>(reader: (active: sdk.WalletStorageReader) => Promise<R>): Promise<R>;
+    /**
+     *
+     * @param sync the function to run with sync access lock
+     * @param activeSync from chained sync functions, active storage already held under sync access lock.
+     * @returns
+     */
+    runAsSync<R>(sync: (active: sdk.WalletStorageSync) => Promise<R>, activeSync?: sdk.WalletStorageSync): Promise<R>;
+    runAsStorageProvider<R>(sync: (active: StorageProvider) => Promise<R>): Promise<R>;
+    /**
+     *
+     * @returns true if the active `WalletStorageProvider` also implements `StorageProvider`
+     */
+    isActiveStorageProvider(): boolean;
+    addWalletStorageProvider(provider: sdk.WalletStorageProvider): Promise<void>;
+    setServices(v: sdk.WalletServices): void;
+    getServices(): sdk.WalletServices;
+    getSettings(): TableSettings;
+    migrate(storageName: string, storageIdentityKey: string): Promise<string>;
+    destroy(): Promise<void>;
+    findOrInsertUser(identityKey: string): Promise<{
+        user: TableUser;
+        isNew: boolean;
+    }>;
+    abortAction(args: AbortActionArgs): Promise<AbortActionResult>;
+    createAction(vargs: Validation.ValidCreateActionArgs): Promise<sdk.StorageCreateActionResult>;
+    internalizeAction(args: InternalizeActionArgs): Promise<sdk.StorageInternalizeActionResult>;
+    relinquishCertificate(args: RelinquishCertificateArgs): Promise<number>;
+    relinquishOutput(args: RelinquishOutputArgs): Promise<number>;
+    processAction(args: sdk.StorageProcessActionArgs): Promise<sdk.StorageProcessActionResults>;
+    insertCertificate(certificate: TableCertificate): Promise<number>;
+    listActions(vargs: Validation.ValidListActionsArgs): Promise<ListActionsResult>;
+    listCertificates(args: Validation.ValidListCertificatesArgs): Promise<ListCertificatesResult>;
+    listOutputs(vargs: Validation.ValidListOutputsArgs): Promise<ListOutputsResult>;
+    findCertificates(args: sdk.FindCertificatesArgs): Promise<TableCertificateX[]>;
+    findOutputBaskets(args: sdk.FindOutputBasketsArgs): Promise<TableOutputBasket[]>;
+    findOutputs(args: sdk.FindOutputsArgs): Promise<TableOutput[]>;
+    findProvenTxReqs(args: sdk.FindProvenTxReqsArgs): Promise<TableProvenTxReq[]>;
+    /**
+     * For each proven_txs record currently sourcing its transaction merkle proof from the given deactivated header,
+     * attempt to reprove the transaction against the current chain,
+     * updating the proven_txs record if a new valid proof is found.
+     *
+     * @param deactivatedHash An orphaned header than may have served as a proof source for proven_txs records.
+     * @returns
+     */
+    reproveHeader(deactivatedHash: string): Promise<sdk.ReproveHeaderResult>;
+    /**
+     * Extends the Beef `verify` function to handle BUMPs that have become invalid due to a chain reorg,
+     * and originated from proven_txs records tracked by this storage.
+     *
+     * This method is optimized for making sure outgoing beefs are valid before sharing them externally.
+     * In particular, it only "repairs" proofs previously tracked by this storage.
+     *
+     * Any merkle root that fails `isValidRootForHeight` triggers a reprove attempt for that block header.
+     * This results in proven_txs with invalid proofs being updated with new valid proofs where possible.
+     *
+     * @param beef
+     * @param allowTxidOnly
+     * @returns VerifyAndRepairBeefResult, in particular `verifiedBeef` is valid only verify and repair succeeded fully.
+     */
+    verifyAndRepairBeef(beef: Beef, allowTxidOnly?: boolean): Promise<VerifyAndRepairBeefResult>;
+    /**
+     * Attempt to reprove the transaction against the current chain,
+     * If a new valid proof is found and noUpdate is not true,
+     * update the proven_txs record with new block and merkle proof data.
+     * If noUpdate is true, the update to be applied is available in the returned result.
+     *
+     * @param ptx proven_txs record to reprove
+     * @param noUpdate
+     * @returns
+     */
+    reproveProven(ptx: TableProvenTx, noUpdate?: boolean): Promise<sdk.ReproveProvenResult>;
+    syncFromReader(identityKey: string, reader: sdk.WalletStorageSyncReader, activeSync?: sdk.WalletStorageSync, log?: string): Promise<{
+        inserts: number;
+        updates: number;
+        log: string;
+    }>;
+    syncToWriter(auth: sdk.AuthId, writer: sdk.WalletStorageProvider, activeSync?: sdk.WalletStorageSync, log?: string, progLog?: (s: string) => string): Promise<{
+        inserts: number;
+        updates: number;
+        log: string;
+    }>;
+    updateBackups(activeSync?: sdk.WalletStorageSync, progLog?: (s: string) => string): Promise<string>;
+    /**
+     * Updates backups and switches to new active storage provider from among current backup providers.
+     *
+     * Also resolves conflicting actives.
+     *
+     * @param storageIdentityKey of current backup storage provider that is to become the new active provider.
+     */
+    setActive(storageIdentityKey: string, progLog?: (s: string) => string): Promise<string>;
+    getStoreEndpointURL(store: ManagedStorage): string | undefined;
+    getStores(): sdk.WalletStorageInfo[];
+}
+export interface VerifyAndRepairBeefResult {
+    isStructurallyValid: boolean;
+    originalRoots: Record<number, string>;
+    invalidRoots: Record<number, {
+        root: string;
+        reproveResults: sdk.ReproveHeaderResult;
+    }>;
+}
+export {};
+//# sourceMappingURL=WalletStorageManager.d.ts.map

package/out/src/storage/WalletStorageManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WalletStorageManager.d.ts","sourceRoot":"","sources":["../../../../src/storage/WalletStorageManager.ts"],"names":[],"mappings":"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"}