@bsv/wallet-toolbox-client 2.7.1 → 2.9.0

package/out/index.client.d.cts

@@ -817,6 +817,41 @@ interface ChaintracksInfoApi {
   packages: ChaintracksPackageInfoApi[];
   /** Last observed source state. Additive and omitted by older services. */
   sources?: ChaintracksSourceStatusApi[];
+  /** Local bulk-header retrieval counters. Additive and omitted by older services. */
+  bulkData?: ChaintracksBulkDataStatsApi;
+}
+/** @public */
+interface ChaintracksBulkDataStatsApi {
+  memoryHits: number;
+  storageHits: number;
+  persistentCacheHits: number;
+  persistentCacheMisses: number;
+  persistentCacheRejects: number;
+  coalescedLoads: number;
+  downloads: number;
+  downloadedBytes: number;
+  loadBackoffs: number;
+  /** Worker or portable validator statistics when the implementation exposes them. */
+  validation?: {
+    submitted: number;
+    completed: number;
+    failed: number;
+    rejected: number;
+    workerRestarts: number;
+    inFlight: number;
+    queued: number;
+    maxQueueDepth: number;
+    totalValidationMsecs: number;
+    maxValidationMsecs: number;
+  };
+  /** Durable download reservation state when configured. */
+  downloadBudget?: {
+    maxBytes: number;
+    consumedBytes: number;
+    remainingBytes: number;
+    windowStartedAt: number;
+    windowMsecs: number;
+  };
 }
 /** @public */
 interface ChaintracksSourceStatusApi {
@@ -827,6 +862,17 @@ interface ChaintracksSourceStatusApi {
   lastFailure?: string;
   error?: string;
 }
+/** Constant-time, local-only process state for probes and operators. @public */
+interface ChaintracksAvailabilitySnapshotApi {
+  available: boolean;
+  startupError?: string;
+  presentHeight?: number;
+  presentHeightUpdatedAt?: string;
+  presentHeightRefreshInFlight: boolean;
+  mainLoopHeartbeatAt?: string;
+  sources: ChaintracksSourceStatusApi[];
+  bulkData: ChaintracksBulkDataStatsApi;
+}
 /**
  * Chaintracks client API excluding events and callbacks
  * @public
@@ -1133,6 +1179,14 @@ interface WalletServicesOptions {
   chain: Chain;
   /** Optional provider-neutral service and ChainTracks tracing. */
   telemetry?: TelemetryConfig;
+  /**
+   * Optional SDK verifier returned directly by `getChainTracker`.
+   *
+   * Use this for a local-primary or otherwise composed verifier. When omitted,
+   * Services preserves the existing behavior of wrapping `chaintracks` in a
+   * `ChaintracksChainTracker`.
+   */
+  chainTracker?: ChainTracker;
   /**
    * As of 2025-08-31 the `taalApiKey` is unused for default configured services.
    * See `arcConfig` instead.
@@ -5656,6 +5710,11 @@ interface ChaintracksFsApi {
 }
 //#endregion
 //#region ../src/services/chaintracker/chaintracks/Api/ChaintracksFetchApi.d.ts
+/** @public */
+interface ChaintracksDownloadOptions {
+  /** Called immediately before each retry after the initial request. */
+  beforeRetry?: (attempt: number) => void | Promise<void>;
+}
 /**
  * Provides a simplified interface based on the @bsv/sdk `HttpClient` class
  * with just the methods necesary for most Chaintracks operations.
@@ -5668,7 +5727,7 @@ interface ChaintracksFsApi {
  */
 interface ChaintracksFetchApi {
   httpClient: HttpClient;
-  download(url: string): Promise<Uint8Array>;
+  download(url: string, maxResponseBytes?: number, options?: ChaintracksDownloadOptions): Promise<Uint8Array>;
   fetchJson<R>(url: string): Promise<R>;
   pathJoin(baseUrl: string, subpath: string): string;
 }
@@ -5694,6 +5753,124 @@ declare class BulkFileDataReader {
   read(): Promise<Uint8Array | undefined>;
 }
 //#endregion
+//#region ../src/services/chaintracker/chaintracks/Api/BulkFileDataCacheApi.d.ts
+/**
+ * Persistent backing cache for immutable bulk-header objects.
+ *
+ * Implementations may read packaged checkpoint assets, application storage,
+ * or a filesystem. The manager validates the byte length and SHA-256 digest
+ * before using any returned value or persisting a downloaded value.
+ *
+ * @public
+ */
+interface BulkFileDataCacheApi {
+  get(file: Readonly<BulkHeaderFileInfo>): Promise<Uint8Array | undefined>;
+  set(file: Readonly<BulkHeaderFileInfo>, data: Uint8Array): Promise<void>;
+  /**
+   * Preserve a rejected object outside the active cache namespace. The manager
+   * calls this before attempting a replacement and never removes a last-good
+   * object merely because a newer source is unavailable.
+   */
+  quarantine?(file: Readonly<BulkHeaderFileInfo>, reason: string,
+  /** Exact rejected bytes, used to avoid quarantining a concurrent replacement. */
+  rejectedData?: Uint8Array): Promise<void>;
+  /**
+   * Promote a validated legacy entry into the implementation's preferred
+   * immutable namespace. Implementations should make this idempotent.
+   */
+  promoteValidated?(file: Readonly<BulkHeaderFileInfo>, data: Uint8Array): Promise<void>;
+  delete?(file: Readonly<BulkHeaderFileInfo>): Promise<void>;
+}
+/**
+ * A deployment-defined budget for remote bulk-header downloads.
+ * Implementations should throw before the request when the requested byte
+ * reservation would exceed the configured budget.
+ *
+ * @public
+ */
+interface BulkFileDownloadBudgetApi {
+  consume(byteCount: number): void | Promise<void>;
+  snapshot?(): BulkFileDownloadBudgetSnapshot;
+}
+/** @public */
+interface BulkFileDownloadBudgetSnapshot {
+  maxBytes: number;
+  consumedBytes: number;
+  remainingBytes: number;
+  windowStartedAt: number;
+  windowMsecs: number;
+}
+//#endregion
+//#region ../src/services/chaintracker/chaintracks/Api/BulkFileDataValidatorApi.d.ts
+/**
+ * Identifies deterministic rejection of the supplied immutable bytes.
+ * Operational failures such as worker crashes and queue saturation deliberately
+ * use ordinary errors so callers preserve the cache entry and avoid downloading
+ * a replacement that cannot be validated.
+ *
+ * @public
+ */
+declare class BulkFileDataValidationError extends Error {
+  readonly data?: Uint8Array | undefined;
+  constructor(message: string, data?: Uint8Array | undefined);
+}
+/**
+ * Complete immutable bulk-header object supplied to a validator.
+ *
+ * Implementations must validate the exact byte length and digest as well as
+ * every header's linkage, chain work, genesis, and proof of work.
+ *
+ * @public
+ */
+interface BulkFileDataValidationRequest {
+  fileName: string;
+  data: Uint8Array;
+  count: number;
+  /** Expected base64 SHA-256 digest. Omit only while producing a new export. */
+  fileHash?: string;
+  firstHeight: number;
+  prevHash: string;
+  prevChainWork: string;
+  lastHash?: string | null;
+  lastChainWork?: string | null;
+  chain?: Chain;
+}
+/** @public */
+interface BulkFileDataValidationResult {
+  /** The validated bytes. Worker implementations may transfer ownership. */
+  data: Uint8Array;
+  fileHash: string;
+  lastHeaderHash: string;
+  lastChainWork: string;
+}
+/** @public */
+interface BulkFileDataValidatorStats {
+  submitted: number;
+  completed: number;
+  failed: number;
+  rejected: number;
+  workerRestarts: number;
+  inFlight: number;
+  queued: number;
+  maxQueueDepth: number;
+  totalValidationMsecs: number;
+  maxValidationMsecs: number;
+}
+/**
+ * Asynchronous validation boundary for immutable bulk-header objects.
+ *
+ * Portable runtimes may validate in-process. Node services can inject a
+ * worker-backed implementation so proof-of-work validation never blocks the
+ * request event loop.
+ *
+ * @public
+ */
+interface BulkFileDataValidatorApi {
+  validate(request: BulkFileDataValidationRequest): Promise<BulkFileDataValidationResult>;
+  getStats?(): BulkFileDataValidatorStats;
+  destroy?(): Promise<void>;
+}
+//#endregion
 //#region ../src/services/chaintracker/chaintracks/util/BulkFileDataManager.d.ts
 interface BulkFileDataManagerOptions {
   chain: Chain;
@@ -5701,6 +5878,28 @@ interface BulkFileDataManagerOptions {
   maxRetained?: number;
   fetch?: ChaintracksFetchApi;
   fromKnownSourceUrl?: string;
+  /** Persistent cache consulted before any remote bulk-file download. */
+  cache?: BulkFileDataCacheApi;
+  /** Optional process-local or shared reservation budget for remote bytes. */
+  downloadBudget?: BulkFileDownloadBudgetApi;
+  /** Complete-object validator. Node services should inject a worker-backed implementation. */
+  validator?: BulkFileDataValidatorApi;
+  /** Cooldown after a failed load before the same immutable object can retry. */
+  failedLoadRetryMsecs?: number;
+}
+/** @public */
+interface BulkFileDataManagerStats {
+  memoryHits: number;
+  storageHits: number;
+  persistentCacheHits: number;
+  persistentCacheMisses: number;
+  persistentCacheRejects: number;
+  coalescedLoads: number;
+  downloads: number;
+  downloadedBytes: number;
+  loadBackoffs: number;
+  validation?: BulkFileDataValidatorStats;
+  downloadBudget?: BulkFileDownloadBudgetSnapshot;
 }
 /**
  * Manages bulk file data (typically 8MB chunks of 100,000 headers each).
@@ -5717,13 +5916,21 @@ declare class BulkFileDataManager {
   private bfds;
   private fileHashToIndex;
   private readonly lock;
+  private readonly inFlightLoads;
+  private readonly failedLoads;
   private storage?;
+  private readonly stats;
   readonly chain: Chain;
   readonly maxPerFile: number;
   readonly fetch?: ChaintracksFetchApi;
   readonly maxRetained?: number;
   readonly fromKnownSourceUrl?: string;
+  readonly cache?: BulkFileDataCacheApi;
+  readonly downloadBudget?: BulkFileDownloadBudgetApi;
+  readonly validator: BulkFileDataValidatorApi;
+  readonly failedLoadRetryMsecs: number;
   constructor(options: BulkFileDataManagerOptions | Chain);
+  getStats(): BulkFileDataManagerStats;
   deleteBulkFiles(): Promise<void>;
   private deleteBulkFilesNoLock;
   /**
@@ -5750,6 +5957,7 @@ declare class BulkFileDataManager {
   getBulkFiles(keepData?: boolean): Promise<BulkHeaderFileInfo[]>;
   getHeightRange(): Promise<HeightRange>;
   getDataFromFile(file: BulkHeaderFileInfo, offset?: number, length?: number): Promise<Uint8Array | undefined>;
+  private getDataFromSnapshot;
   private getDataFromFileNoLock;
   findHeaderForHeightOrUndefined(height: number): Promise<BlockHeader | undefined>;
   getFileForHeight(height: number): Promise<BulkHeaderFileInfo | undefined>;
@@ -5816,8 +6024,14 @@ declare class BulkFileDataManager {
    * @returns
    */
   private ensureData;
+  private loadAndValidateData;
+  private loadFromStorage;
+  private loadFromCache;
+  private loadFromRemote;
+  private validateRetrievedData;
   private ensureMaxRetained;
   exportHeadersToFs(toFs: ChaintracksFsApi, toHeadersPerFile: number, toFolder: string, sourceUrl?: string, maxHeight?: number): Promise<void>;
+  destroy(): Promise<void>;
 }
 interface BulkFileData extends BulkHeaderFileInfo {
   mru: number;
@@ -5941,7 +6155,8 @@ interface BulkHeaderFileInfo {
   chain?: Chain;
   data?: Uint8Array;
   /**
-   * true iff these properties should be considered pre-validated, including a valid required fileHash of data (when not undefined).
+   * Advisory process-local validation state. Never trust this value after it
+   * crosses a network or storage boundary; revalidate the object bytes.
    */
   validated?: boolean;
   /**
@@ -6015,6 +6230,13 @@ interface BulkHeaderFilesInfo {
    */
   headersPerFile: number;
 }
+declare abstract class BulkHeaderFiles implements BulkHeaderFilesInfo {
+  rootFolder: string;
+  jsonFilename: string;
+  files: BulkHeaderFileInfo[];
+  headersPerFile: number;
+  constructor(rootFolder: string, jsonFilename: string, files: BulkHeaderFileInfo[], headersPerFile: number);
+}
 //#endregion
 //#region ../src/services/chaintracker/chaintracks/Api/ChaintracksStorageApi.d.ts
 interface ChaintracksStorageBaseOptions {
@@ -6582,16 +6804,22 @@ declare class Chaintracks implements ChaintracksManagementApi {
   private lastPresentHeight;
   private lastPresentHeightMsecs;
   private readonly lastPresentHeightMaxAge;
+  private presentHeightRefresh?;
+  private mainLoopHeartbeatMsecs;
   private readonly lock;
   private readonly sourceStatus;
   constructor(options: ChaintracksOptions);
   getChain(): Promise<Chain>;
   /**
-   * Caches and returns most recently sourced value if less than one minute old.
-   * @returns the current externally available chain height (via bulk ingestors).
+   * Returns the last known valid height immediately and refreshes stale state
+   * once in the background. Cold start waits for the single shared refresh.
    */
   getPresentHeight(): Promise<number>;
+  private refreshPresentHeight;
+  private loadPresentHeight;
   currentHeight(): Promise<number>;
+  /** Returns local process state without locks, storage reads, or network I/O. */
+  getAvailabilitySnapshot(): ChaintracksAvailabilitySnapshotApi;
   subscribeHeaders(listener: HeaderListener): Promise<string>;
   subscribeReorgs(listener: ReorgListener): Promise<string>;
   unsubscribe(subscriptionId: string): Promise<boolean>;
@@ -7818,6 +8046,12 @@ interface ChaintracksSourceOptions {
   disableCdn?: boolean;
   /** Disable the keyless WhatsOnChain fallback on mainnet/testnet. */
   disableWhatsOnChain?: boolean;
+  /** Persistent checkpoint/cache storage used before any remote bulk download. */
+  bulkFileCache?: BulkFileDataCacheApi;
+  /** Optional byte budget applied before remote bulk-file downloads. */
+  bulkFileDownloadBudget?: BulkFileDownloadBudgetApi;
+  /** Optional complete-object validator; Node services should use a bounded worker implementation. */
+  bulkFileDataValidator?: BulkFileDataValidatorApi;
 }
 type ChaintracksArgumentsTail = [whatsonchainApiKey?: string, maxPerFile?: number, maxRetained?: number, fetch?: ChaintracksFetchApi, cdnUrl?: string, liveHeightThreshold?: number, reorgHeightThreshold?: number, bulkMigrationChunkSize?: number, batchInsertLimit?: number, addLiveRecursionLimit?: number, sources?: ChaintracksSourceOptions];
 type DefaultChaintracksArguments = [chain: Chain, ...options: ChaintracksArgumentsTail];
@@ -7956,6 +8190,18 @@ declare class BulkFilesReaderStorage extends BulkFilesReader {
 }
 //#endregion
 //#region ../src/services/chaintracker/chaintracks/util/ChaintracksFetch.d.ts
+interface ChaintracksFetchOptions {
+  /** Number of retries after the initial request. Defaults to three. */
+  maxRetries?: number;
+  /** Deadline covering connection, headers, and response body. */
+  timeoutMsecs?: number;
+  /** Maximum materialized response size for binary and JSON requests. */
+  maxResponseBytes?: number;
+  retryMsecs?: number;
+  maxRetryMsecs?: number;
+  /** Testable jitter source in the inclusive range 0..1. */
+  random?: () => number;
+}
 declare class ChaintracksFetchError extends Error {
   readonly url: string;
   readonly status: number;
@@ -7965,17 +8211,74 @@ declare class ChaintracksFetchError extends Error {
   get retryable(): boolean;
 }
 /**
- * This class implements the ChaintracksFetchApi
- * using the @bsv/sdk `defaultHttpClient`.
+ * Bounded fetch implementation shared by ChainTracks sources.
+ *
+ * Retry policy lives here so callers never multiply attempts. Every attempt
+ * has a deadline that remains active while the response body is consumed, and
+ * every materialized response has an explicit byte ceiling.
  */
 declare class ChaintracksFetch implements ChaintracksFetchApi {
   httpClient: HttpClient;
-  download(url: string): Promise<Uint8Array>;
+  private readonly maxRetries;
+  private readonly timeoutMsecs;
+  private readonly maxResponseBytes;
+  private readonly retryMsecs;
+  private readonly maxRetryMsecs;
+  private readonly random;
+  constructor(options?: ChaintracksFetchOptions);
+  download(url: string, maxResponseBytes?: number, options?: ChaintracksDownloadOptions): Promise<Uint8Array>;
   fetchJson<R>(url: string): Promise<R>;
+  private requestBytes;
+  private requestAttempt;
+  private readResponseBytes;
+  private responseTooLarge;
+  private retryWaitMsecs;
   pathJoin(baseUrl: string, subpath: string): string;
 }
+//#endregion
+//#region ../src/services/chaintracker/chaintracks/util/FixedWindowBulkFileDownloadBudget.d.ts
+interface FixedWindowBulkFileDownloadBudgetOptions {
+  maxBytes: number;
+  windowMsecs?: number;
+  now?: () => number;
+}
+/**
+ * Conservative process-local byte reservation budget for remote bulk-header
+ * downloads. A reservation is retained even when the subsequent request
+ * fails, preventing a failing upstream from bypassing the bound.
+ *
+ * @public
+ */
+declare class FixedWindowBulkFileDownloadBudget implements BulkFileDownloadBudgetApi {
+  private readonly maxBytes;
+  private readonly windowMsecs;
+  private readonly now;
+  private windowStartedAt;
+  private consumedBytes;
+  constructor(options: FixedWindowBulkFileDownloadBudgetOptions);
+  consume(byteCount: number): void;
+  snapshot(): {
+    maxBytes: number;
+    consumedBytes: number;
+    remainingBytes: number;
+    windowStartedAt: number;
+    windowMsecs: number;
+  };
+}
+//#endregion
+//#region ../src/services/chaintracker/chaintracks/util/InlineBulkFileDataValidator.d.ts
+/**
+ * Portable complete-object validator. Node services should normally inject
+ * `NodeBulkFileDataValidator`; browser and mobile consumers retain this
+ * dependency-free fallback.
+ *
+ * @public
+ */
+declare class InlineBulkFileDataValidator implements BulkFileDataValidatorApi {
+  validate(request: BulkFileDataValidationRequest): Promise<BulkFileDataValidationResult>;
+}
 declare namespace blockHeaderUtilities_d_exports {
-  export { addWork, blockHash, convertBitsToTarget, convertBitsToWork, convertBufferToUint32, convertUint32ToBuffer, deserializeBaseBlockHeader, deserializeBaseBlockHeaders, deserializeBlockHeader, deserializeBlockHeaders, genesisBuffer, genesisHeader, isMoreWork, readUInt32BE, readUInt32LE, serializeBaseBlockHeader, serializeBaseBlockHeaders, sha256HashOfBinaryFile, subWork, swapByteOrder, validateBufferOfHeaders, validateBulkFileData, validateGenesisHeader, validateHeaderDifficulty, validateHeaderFormat, workBNtoBuffer, writeUInt32BE, writeUInt32LE };
+  export { addWork, blockHash, convertBitsToTarget, convertBitsToWork, convertBufferToUint32, convertUint32ToBuffer, deserializeBaseBlockHeader, deserializeBaseBlockHeaders, deserializeBlockHeader, deserializeBlockHeaders, genesisBuffer, genesisHeader, isMoreWork, readUInt32BE, readUInt32LE, serializeBaseBlockHeader, serializeBaseBlockHeaders, sha256HashOfBinaryFile, subWork, swapByteOrder, validateBufferOfHeaders, validateBulkFileData, validateGenesisHeader, validateHeaderDifficulty, validateHeaderFormat, validateHeaderProofOfWork, workBNtoBuffer, writeUInt32BE, writeUInt32LE };
 }
 /**
  * Computes sha256 hash of file contents read as bytes with no encoding.
@@ -8050,14 +8353,22 @@ declare function deserializeBaseBlockHeaders(buffer: number[] | Uint8Array, offs
 declare function deserializeBlockHeaders(firstHeight: number, buffer: number[] | Uint8Array, offset?: number, count?: number | undefined): BlockHeader[];
 declare function validateHeaderFormat(header: BlockHeader): void;
 /**
- * Ensures that a header has a valid proof-of-work
- * Requires chain is 'main'
+ * Ensures that a header has a valid proof-of-work target and hash.
  *
  * @param header The header to validate
  *
  * @returns true if the header is valid
  */
-declare function validateHeaderDifficulty(hash: Buffer, bits: number): boolean;
+declare function validateHeaderDifficulty(hash: number[] | Uint8Array, bits: number): boolean;
+/**
+ * Ensures that a structured header's computed hash satisfies its declared
+ * proof-of-work target.
+ *
+ * @param header Header whose format and hash have already been checked.
+ * @returns true if the header has valid proof-of-work.
+ * @publicbody
+ */
+declare function validateHeaderProofOfWork(header: BlockHeader): true;
 /**
  * Computes double sha256 hash of bitcoin block header
  * bytes are reversed to bigendian order
@@ -8150,6 +8461,101 @@ declare class ChaintracksChainTracker implements ChainTracker {
   private isValidRootForHeightCore;
 }
 //#endregion
+//#region ../src/services/chaintracker/LocalChainTracker.d.ts
+/** @public */
+type LocalChainTrackerMode = 'local-primary' | 'remote-only';
+/** @public */
+type LocalChainTrackerConsistency = 'unchecked' | 'agreed' | 'lagging' | 'diverged' | 'insufficient-references' | 'error';
+/** @public */
+interface LocalChainTrackerRecoveryEvidence {
+  reason: 'lagging' | 'diverged';
+  localHeight: number;
+  referenceHeight: number;
+  heightLag: number;
+  comparisonHeight: number;
+  expectedHash: string;
+  referenceAgreement: number;
+}
+/** @public */
+interface LocalChainTrackerStatus {
+  mode: LocalChainTrackerMode;
+  activeSource: string;
+  consistency: LocalChainTrackerConsistency;
+  localHeight?: number;
+  localTipHash?: string;
+  referenceHeight?: number;
+  heightLag?: number;
+  comparisonHeight?: number;
+  expectedHash?: string;
+  referenceAgreement?: number;
+  checkedAt?: string;
+  recoveredAt?: string;
+  lastFallbackAt?: string;
+  lastError?: string;
+}
+/** @public */
+interface LocalChainTrackerOptions {
+  /** Locally persisted, proof-of-work-validating ChainTracks client. */
+  local: ChaintracksClientApi;
+  /** Independent references used for diagnostics and exceptional fallback. */
+  fallbacks?: ChaintracksClientApi[];
+  mode?: LocalChainTrackerMode;
+  fallbackOnLocalError?: boolean;
+  /** Number of matching references needed for a fallback validation result. */
+  requiredFallbackAgreement?: number;
+  /** Number of matching references needed to declare local divergence. */
+  requiredConsistencyAgreement?: number;
+  /** Quorum-backed height lag tolerated before local state is considered stuck. */
+  maxHeightLag?: number;
+  autoRecover?: boolean;
+  /** Clears/reseeds local state and returns the replacement local client. */
+  recoverLocal?: (evidence: LocalChainTrackerRecoveryEvidence) => Promise<ChaintracksClientApi>;
+  /** Clears local state and returns a fresh local client. */
+  clearLocal?: () => Promise<ChaintracksClientApi>;
+  now?: () => Date;
+}
+/**
+ * Local-first SDK ChainTracker with explicit management and fallback state.
+ *
+ * A definitive local `false` validation is never overridden by a remote
+ * source. Fallback is reserved for local exceptions or explicit remote-only
+ * mode, and applications can require agreement across multiple independent
+ * references before accepting a fallback result.
+ *
+ * @public
+ */
+declare class LocalChainTracker implements ChainTracker {
+  private local;
+  private readonly fallbacks;
+  private readonly fallbackOnLocalError;
+  private readonly requiredFallbackAgreement;
+  private readonly requiredConsistencyAgreement;
+  private readonly maxHeightLag;
+  private readonly autoRecover;
+  private readonly recoverLocal;
+  private readonly clearLocal;
+  private readonly now;
+  private status;
+  constructor(options: LocalChainTrackerOptions);
+  getMode(): LocalChainTrackerMode;
+  setMode(mode: LocalChainTrackerMode): void;
+  getStatus(): LocalChainTrackerStatus;
+  getLocalClient(): ChaintracksClientApi;
+  currentHeight(): Promise<number>;
+  isValidRootForHeight(root: string, height: number): Promise<boolean>;
+  synchronize(): Promise<LocalChainTrackerStatus>;
+  clearLocalData(): Promise<LocalChainTrackerStatus>;
+  checkConsistency(): Promise<LocalChainTrackerStatus>;
+  private checkConsistencyInternal;
+  private fallbackHeight;
+  private fallbackValidation;
+  private recordFallback;
+  private recordError;
+  private errorMessage;
+  private validateAgreement;
+  private validateHeightLag;
+}
+//#endregion
 //#region ../src/services/chaintracker/BHServiceClient.d.ts
 declare class BHServiceClient implements ChaintracksServiceClient {
   bhs: BlockHeadersService;
@@ -11159,5 +11565,5 @@ declare class WalletPermissionsManager implements WalletInterface {
   private buildActiveRequestKey;
 }
 //#endregion
-export { ARGON2ID_DEFAULT_HASH_LENGTH, ARGON2ID_DEFAULT_ITERATIONS, ARGON2ID_DEFAULT_MEMORY_KIB, ARGON2ID_DEFAULT_PARALLELISM, ARGON2ID_MAX_ITERATIONS, ARGON2ID_MAX_MEMORY_KIB, ARGON2ID_MAX_PARALLELISM, ActionBatchStatus, AdminStatsResult, AnyBlockHeader, AuthMethodInteractor, AuthPayload, BHServiceClient, BRC153_REFERENCE_PREFIX, BRC38ImportOptions, BRC38ImportResult, BRC38Tables, BRC38WalletData, BRC39Options, type BaseBlockHeader, type BlockHeader, BulkFileDataManager, BulkFileDataManagerMergeResult, BulkFileDataManagerOptions, BulkFileDataReader, BulkFilesReader, BulkFilesReaderFs, BulkFilesReaderStorage, BulkIngestorApi, BulkIngestorBase, BulkIngestorBaseOptions, BulkIngestorCDN, BulkIngestorCDNBabbage, BulkIngestorCDNOptions, BulkIngestorChaintracks, BulkIngestorChaintracksOptions, BulkIngestorWhatsOnChainCdn, BulkIngestorWhatsOnChainOptions, BulkStorageApi, BulkStorageBase, BulkStorageBaseOptions, BulkSyncResult, ByteEncoding, ByteInput, CWIStyleWalletManager, Certifier, type Chain, Chaintracks, ChaintracksApi, ChaintracksAppendableFileApi, ChaintracksArgumentsTail, ChaintracksChainTracker, ChaintracksChainTrackerOptions, ChaintracksClientApi, ChaintracksFetch, ChaintracksFetchApi, ChaintracksFetchError, ChaintracksFsApi, ChaintracksInfoApi, ChaintracksIngestorParams, ChaintracksManagementApi, ChaintracksOptions, ChaintracksPackageInfoApi, ChaintracksReadableFileApi, ChaintracksServiceClient, ChaintracksServiceClientOptions, ChaintracksSourceOptions, ChaintracksSourceStatusApi, ChaintracksStorageApi, ChaintracksStorageBase, ChaintracksStorageBaseOptions, ChaintracksStorageBulkFileApi, ChaintracksStorageIdb, ChaintracksStorageIdbOptions, ChaintracksStorageIdbSchema, ChaintracksStorageIngestApi, ChaintracksStorageNoDb, ChaintracksStorageNoDbOptions, ChaintracksStorageQueryApi, ChaintracksWritableFileApi, CompleteAuthResponse, ContactRecord, ContactSource, CounterpartyPermissionEventHandler, CounterpartyPermissionRequest, CounterpartyPermissions, CreatedChaintracks, DEFAULT_MANAGED_CHANGE_MAX_OUTPUTS_PER_ACTION, DEFAULT_MANAGED_CHANGE_MIGRATION_INPUTS_PER_ACTION, DEFAULT_MANAGED_CHANGE_MINIMUM_SATOSHIS, DEFAULT_MANAGED_CHANGE_PENDING_COMPARISON_INPUTS, DEFAULT_MANAGED_CHANGE_TARGET_UTXOS, DEFAULT_PROFILE_ID, DEFAULT_SETTINGS, DeactivedHeader, DefaultChaintracksArguments, DevConsoleInteractor, EnqueueHandler, EntityBase, EntityCertificate, EntityCertificateField, EntityCommission, EntityOutput, EntityOutputBasket, EntityOutputTag, EntityOutputTagMap, EntityProvenTx, EntityProvenTxReq, EntityStorage, EntitySyncMap, EntitySyncState, EntityTransaction, EntityTxLabel, EntityTxLabelMap, EntityUser, ErrorHandler, GetHeaderByteFileLinksResult, GoChaintracksServiceClient, GoChaintracksServiceClientOptions, GroupedPermissionEventHandler, GroupedPermissionRequest, GroupedPermissions, HeaderListener, HeightRange, HeightRangeApi, HeightRanges, InsertHeaderResult, KDF_MAX_HASH_LENGTH, KdfConfig, KeyPairAddress, LEGACY_MANAGED_CHANGE_MINIMUM_SATOSHIS, LineItemType, ListActionsSpecOp, ListOutputsSpecOp, LiveBlockHeader, LiveIngestorApi, LiveIngestorBase, LiveIngestorBaseOptions, LiveIngestorChaintracksSSE, LiveIngestorChaintracksSSEOptions, LiveIngestorWhatsOnChainOptions, LiveIngestorWhatsOnChainPoll, MAX_STATE_SNAPSHOT_BYTES, ManagedChangeBasketDefaults, ManagedChangePolicy, ManagedChangePolicyOptions, MergeEntity, Monitor, MonitorOptions, MonitorStartupTaskMode, MonitorStorage, OverlayUMPTokenInteractor, PBKDF2_MAX_ITERATIONS, PBKDF2_NUM_ROUNDS, ParsedBrc114ActionTimeLabels, PendingSignAction, PendingStorageInput, PermissionEventHandler, PermissionRequest, PermissionToken, PermissionsManagerConfig, PermissionsModule, PersonaIDInteractor, PrivilegedKeyManager, Profile, ProvenTxFromTxidResult, ProvenTxReqHistory, ProvenTxReqHistorySummaryApi, ProvenTxReqNotify, ReorgListener, ResolvedDefaultChaintracksParams, ScriptTemplateBRC29, ScriptTemplateParamsBRC29, SecurityLevel, Services, SetupClient, SetupClientWalletArgs, SetupClientWalletClientArgs, SetupWallet, SetupWalletClient, SetupWalletIdb, SetupWalletIdbArgs, SimpleWalletManager, StartAuthResponse, StorageAdminStats, StorageClient, StorageIdb, StorageIdbOptions, StorageProvider, StorageProviderOptions, StorageSyncReader, SyncError, SyncMap, TESTNET_DEFAULT_SETTINGS, TableActionBatch, TableActionBatchBlob, TableActionBatchOutput, TableAuthSession, TableCertificate, TableCertificateField, TableCertificateX, TableCommission, TableMonitorEvent, TableOutput, TableOutputBasket, TableOutputTag, TableOutputTagMap, TableOutputX, TableProvenTx, TableProvenTxReq, TableProvenTxReqDynamics, TableSettings, TableSyncState, TableTransaction, TableTxLabel, TableTxLabelMap, TableUser, TrustSettings, TscMerkleProofApi, TwilioPhoneInteractor, TxScriptOffsets, UMPToken, UMPTokenInteractor, UMPTokenLookupDiagnostics, UMPTokenLookupError, UMPTokenLookupFailureReason, VerifyAndRepairBeefResult, WABAccountContinuityError, WABClient, WABClientError, WABClientErrorCode, WABClientErrorOptions, WABClientOptions, WABFaucetResponse, WABOperationResponse, WABRequestOptions, WABServerInfo, WABTransport, WABTransportOptions, Wallet, WalletArgs, WalletAuthenticationManager, WalletAuthenticationManagerOptions, WalletLogger, WalletLoggerArgs, WalletLoggerLevel, WalletPermissionsManager, WalletPermissionsManagerCallbacks, WalletSettings, WalletSettingsManager, WalletSettingsManagerConfig, WalletSigner, WalletStorageManager, WalletTheme, WhatsOnChainServices, WhatsOnChainServicesOptions, WocGetHeaderByteFileLinks, WocGetHeadersHeader, applyBrc153ReferenceLabel, arcDefaultUrl, arcGorillaPoolUrl, arcadeDefaultUrl, arraysEqual, asArray, asBsvSdkPrivateKey, asBsvSdkPublickKey, asBsvSdkScript, asBsvSdkTx, asString, asUint8Array, brc29ProtocolID, buildChaintracksOptionsWithIngestors, convertProofToMerklePath, createAndStartDefaultChaintracks, createDefaultBulkFileDataManager, createDefaultChaintracksClient, createDefaultChaintracksStorageOptions, createDefaultIdbChaintracksOptions, createDefaultNoDbChaintracksOptions, createDefaultWalletServicesOptions, createIdbChaintracks, createNoDbChaintracks, createSyncMap, decryptBRC39, defaultManagedChangePolicy, doubleSha256BE, doubleSha256LE, encryptBRC39, exportBRC38, exportBRC38Json, exportBRC39, getIdentityKey, getLabelToSpecOp, getListOutputsSpecOp, importBRC38, importBRC39, isAutoSpendableChangeOutput, isBaseBlockHeader, isBlockHeader, isBrc153ReferenceLabel, isLegacyManagedChangeBasketDefault, isLive, isLiveBlockHeader, isManagedChangeOutput, logCreateActionArgs, logWalletError, logger, makeAtomicBeef, makeBrc114ActionTimeLabel, makeBrc153ReferenceLabel, managedChangeOutputFields, maxDate, optionalArraysEqual, outputColumnsWithoutLockingScript, parseBRC38Json, parseBrc114ActionTimeLabels, parseBrc153ReferenceLabel, parseFileLink, parseTxScriptOffsets, partitionActionLabels, randomBytes, randomBytesBase64, randomBytesHex, resolveDefaultChaintracksArguments, index_d_exports as sdk, selectBulkHeaderFiles, sha256Hash, stampLog, stampLogFormat, startChaintracks, tableAuthSessionToPeerSession, throwDummyReviewActions, toBinaryBaseBlockHeader, toDefaultChaintracksArguments, toLookupNetworkPreset, toWalletNetwork, transactionColumnsWithoutRawTx, upgradeLegacyManagedChangeBasketDefault, blockHeaderUtilities_d_exports as utils, validateManagedChangePolicy, validateScriptHash, validateSecondsSinceEpoch, validateStorageFeeModel, verifyHexString, verifyId, verifyInteger, verifyNumber, verifyOne, verifyOneOrNone, verifyOptionalHexString, verifyTruthy, wait, wocGetHeadersHeaderToBlockHeader };
+export { ARGON2ID_DEFAULT_HASH_LENGTH, ARGON2ID_DEFAULT_ITERATIONS, ARGON2ID_DEFAULT_MEMORY_KIB, ARGON2ID_DEFAULT_PARALLELISM, ARGON2ID_MAX_ITERATIONS, ARGON2ID_MAX_MEMORY_KIB, ARGON2ID_MAX_PARALLELISM, ActionBatchStatus, AdminStatsResult, AnyBlockHeader, AuthMethodInteractor, AuthPayload, BHServiceClient, BRC153_REFERENCE_PREFIX, BRC38ImportOptions, BRC38ImportResult, BRC38Tables, BRC38WalletData, BRC39Options, type BaseBlockHeader, type BlockHeader, BulkFileDataCacheApi, BulkFileDataManager, BulkFileDataManagerMergeResult, BulkFileDataManagerOptions, BulkFileDataManagerStats, BulkFileDataReader, BulkFileDataValidationError, BulkFileDataValidationRequest, BulkFileDataValidationResult, BulkFileDataValidatorApi, BulkFileDataValidatorStats, BulkFileDownloadBudgetApi, BulkFileDownloadBudgetSnapshot, BulkFilesReader, BulkFilesReaderFs, BulkFilesReaderStorage, BulkHeaderFile, BulkHeaderFileFs, BulkHeaderFileInfo, BulkHeaderFileStorage, BulkHeaderFiles, BulkHeaderFilesInfo, BulkIngestorApi, BulkIngestorBase, BulkIngestorBaseOptions, BulkIngestorCDN, BulkIngestorCDNBabbage, BulkIngestorCDNOptions, BulkIngestorChaintracks, BulkIngestorChaintracksOptions, BulkIngestorWhatsOnChainCdn, BulkIngestorWhatsOnChainOptions, BulkStorageApi, BulkStorageBase, BulkStorageBaseOptions, BulkSyncResult, ByteEncoding, ByteInput, CWIStyleWalletManager, Certifier, type Chain, Chaintracks, ChaintracksApi, ChaintracksAppendableFileApi, ChaintracksArgumentsTail, ChaintracksAvailabilitySnapshotApi, ChaintracksBulkDataStatsApi, ChaintracksChainTracker, ChaintracksChainTrackerOptions, ChaintracksClientApi, ChaintracksDownloadOptions, ChaintracksFetch, ChaintracksFetchApi, ChaintracksFetchError, ChaintracksFetchOptions, ChaintracksFsApi, ChaintracksInfoApi, ChaintracksIngestorParams, ChaintracksManagementApi, ChaintracksOptions, ChaintracksPackageInfoApi, ChaintracksReadableFileApi, ChaintracksServiceClient, ChaintracksServiceClientOptions, ChaintracksSourceOptions, ChaintracksSourceStatusApi, ChaintracksStorageApi, ChaintracksStorageBase, ChaintracksStorageBaseOptions, ChaintracksStorageBulkFileApi, ChaintracksStorageIdb, ChaintracksStorageIdbOptions, ChaintracksStorageIdbSchema, ChaintracksStorageIngestApi, ChaintracksStorageNoDb, ChaintracksStorageNoDbOptions, ChaintracksStorageQueryApi, ChaintracksWritableFileApi, CompleteAuthResponse, ContactRecord, ContactSource, CounterpartyPermissionEventHandler, CounterpartyPermissionRequest, CounterpartyPermissions, CreatedChaintracks, DEFAULT_MANAGED_CHANGE_MAX_OUTPUTS_PER_ACTION, DEFAULT_MANAGED_CHANGE_MIGRATION_INPUTS_PER_ACTION, DEFAULT_MANAGED_CHANGE_MINIMUM_SATOSHIS, DEFAULT_MANAGED_CHANGE_PENDING_COMPARISON_INPUTS, DEFAULT_MANAGED_CHANGE_TARGET_UTXOS, DEFAULT_PROFILE_ID, DEFAULT_SETTINGS, DeactivedHeader, DefaultChaintracksArguments, DevConsoleInteractor, EnqueueHandler, EntityBase, EntityCertificate, EntityCertificateField, EntityCommission, EntityOutput, EntityOutputBasket, EntityOutputTag, EntityOutputTagMap, EntityProvenTx, EntityProvenTxReq, EntityStorage, EntitySyncMap, EntitySyncState, EntityTransaction, EntityTxLabel, EntityTxLabelMap, EntityUser, ErrorHandler, FixedWindowBulkFileDownloadBudget, FixedWindowBulkFileDownloadBudgetOptions, GetHeaderByteFileLinksResult, GoChaintracksServiceClient, GoChaintracksServiceClientOptions, GroupedPermissionEventHandler, GroupedPermissionRequest, GroupedPermissions, HeaderListener, HeightRange, HeightRangeApi, HeightRanges, InlineBulkFileDataValidator, InsertHeaderResult, KDF_MAX_HASH_LENGTH, KdfConfig, KeyPairAddress, LEGACY_MANAGED_CHANGE_MINIMUM_SATOSHIS, LineItemType, ListActionsSpecOp, ListOutputsSpecOp, LiveBlockHeader, LiveIngestorApi, LiveIngestorBase, LiveIngestorBaseOptions, LiveIngestorChaintracksSSE, LiveIngestorChaintracksSSEOptions, LiveIngestorWhatsOnChainOptions, LiveIngestorWhatsOnChainPoll, LocalChainTracker, LocalChainTrackerConsistency, LocalChainTrackerMode, LocalChainTrackerOptions, LocalChainTrackerRecoveryEvidence, LocalChainTrackerStatus, MAX_STATE_SNAPSHOT_BYTES, ManagedChangeBasketDefaults, ManagedChangePolicy, ManagedChangePolicyOptions, MergeEntity, Monitor, MonitorOptions, MonitorStartupTaskMode, MonitorStorage, OverlayUMPTokenInteractor, PBKDF2_MAX_ITERATIONS, PBKDF2_NUM_ROUNDS, ParsedBrc114ActionTimeLabels, PendingSignAction, PendingStorageInput, PermissionEventHandler, PermissionRequest, PermissionToken, PermissionsManagerConfig, PermissionsModule, PersonaIDInteractor, PrivilegedKeyManager, Profile, ProvenTxFromTxidResult, ProvenTxReqHistory, ProvenTxReqHistorySummaryApi, ProvenTxReqNotify, ReorgListener, ResolvedDefaultChaintracksParams, ScriptTemplateBRC29, ScriptTemplateParamsBRC29, SecurityLevel, Services, SetupClient, SetupClientWalletArgs, SetupClientWalletClientArgs, SetupWallet, SetupWalletClient, SetupWalletIdb, SetupWalletIdbArgs, SimpleWalletManager, StartAuthResponse, StorageAdminStats, StorageClient, StorageIdb, StorageIdbOptions, StorageProvider, StorageProviderOptions, StorageSyncReader, SyncError, SyncMap, TESTNET_DEFAULT_SETTINGS, TableActionBatch, TableActionBatchBlob, TableActionBatchOutput, TableAuthSession, TableCertificate, TableCertificateField, TableCertificateX, TableCommission, TableMonitorEvent, TableOutput, TableOutputBasket, TableOutputTag, TableOutputTagMap, TableOutputX, TableProvenTx, TableProvenTxReq, TableProvenTxReqDynamics, TableSettings, TableSyncState, TableTransaction, TableTxLabel, TableTxLabelMap, TableUser, TrustSettings, TscMerkleProofApi, TwilioPhoneInteractor, TxScriptOffsets, UMPToken, UMPTokenInteractor, UMPTokenLookupDiagnostics, UMPTokenLookupError, UMPTokenLookupFailureReason, VerifyAndRepairBeefResult, WABAccountContinuityError, WABClient, WABClientError, WABClientErrorCode, WABClientErrorOptions, WABClientOptions, WABFaucetResponse, WABOperationResponse, WABRequestOptions, WABServerInfo, WABTransport, WABTransportOptions, Wallet, WalletArgs, WalletAuthenticationManager, WalletAuthenticationManagerOptions, WalletLogger, WalletLoggerArgs, WalletLoggerLevel, WalletPermissionsManager, WalletPermissionsManagerCallbacks, WalletSettings, WalletSettingsManager, WalletSettingsManagerConfig, WalletSigner, WalletStorageManager, WalletTheme, WhatsOnChainServices, WhatsOnChainServicesOptions, WocGetHeaderByteFileLinks, WocGetHeadersHeader, applyBrc153ReferenceLabel, arcDefaultUrl, arcGorillaPoolUrl, arcadeDefaultUrl, arraysEqual, asArray, asBsvSdkPrivateKey, asBsvSdkPublickKey, asBsvSdkScript, asBsvSdkTx, asString, asUint8Array, brc29ProtocolID, buildChaintracksOptionsWithIngestors, convertProofToMerklePath, createAndStartDefaultChaintracks, createDefaultBulkFileDataManager, createDefaultChaintracksClient, createDefaultChaintracksStorageOptions, createDefaultIdbChaintracksOptions, createDefaultNoDbChaintracksOptions, createDefaultWalletServicesOptions, createIdbChaintracks, createNoDbChaintracks, createSyncMap, decryptBRC39, defaultManagedChangePolicy, doubleSha256BE, doubleSha256LE, encryptBRC39, exportBRC38, exportBRC38Json, exportBRC39, getIdentityKey, getLabelToSpecOp, getListOutputsSpecOp, importBRC38, importBRC39, isAutoSpendableChangeOutput, isBaseBlockHeader, isBlockHeader, isBrc153ReferenceLabel, isLegacyManagedChangeBasketDefault, isLive, isLiveBlockHeader, isManagedChangeOutput, logCreateActionArgs, logWalletError, logger, makeAtomicBeef, makeBrc114ActionTimeLabel, makeBrc153ReferenceLabel, managedChangeOutputFields, maxDate, optionalArraysEqual, outputColumnsWithoutLockingScript, parseBRC38Json, parseBrc114ActionTimeLabels, parseBrc153ReferenceLabel, parseFileLink, parseTxScriptOffsets, partitionActionLabels, randomBytes, randomBytesBase64, randomBytesHex, resolveDefaultChaintracksArguments, index_d_exports as sdk, selectBulkHeaderFiles, sha256Hash, stampLog, stampLogFormat, startChaintracks, tableAuthSessionToPeerSession, throwDummyReviewActions, toBinaryBaseBlockHeader, toDefaultChaintracksArguments, toLookupNetworkPreset, toWalletNetwork, transactionColumnsWithoutRawTx, upgradeLegacyManagedChangeBasketDefault, blockHeaderUtilities_d_exports as utils, validateManagedChangePolicy, validateScriptHash, validateSecondsSinceEpoch, validateStorageFeeModel, verifyHexString, verifyId, verifyInteger, verifyNumber, verifyOne, verifyOneOrNone, verifyOptionalHexString, verifyTruthy, wait, wocGetHeadersHeaderToBlockHeader };
 //# sourceMappingURL=index.client.d.cts.map