@bsv/wallet-toolbox-client/out/src/storage/WalletStorageManager.d.ts

Client only Wallet Storage

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