@bsv/wallet-toolbox 2.7.1 → 2.9.0

package/out/src/services/chaintracker/LocalChainTracker.d.ts

@@ -0,0 +1,96 @@
+import type { ChainTracker } from '@bsv/sdk';
+import type { ChaintracksClientApi } from './chaintracks/Api/ChaintracksClientApi';
+/** @public */
+export type LocalChainTrackerMode = 'local-primary' | 'remote-only';
+/** @public */
+export type LocalChainTrackerConsistency = 'unchecked' | 'agreed' | 'lagging' | 'diverged' | 'insufficient-references' | 'error';
+/** @public */
+export interface LocalChainTrackerRecoveryEvidence {
+    reason: 'lagging' | 'diverged';
+    localHeight: number;
+    referenceHeight: number;
+    heightLag: number;
+    comparisonHeight: number;
+    expectedHash: string;
+    referenceAgreement: number;
+}
+/** @public */
+export 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 */
+export 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
+ */
+export 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;
+}
+//# sourceMappingURL=LocalChainTracker.d.ts.map

package/out/src/services/chaintracker/LocalChainTracker.d.ts.map

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

package/out/src/services/chaintracker/LocalChainTracker.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalChainTracker = void 0;
+/**
+ * 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
+ */
+class LocalChainTracker {
+    local;
+    fallbacks;
+    fallbackOnLocalError;
+    requiredFallbackAgreement;
+    requiredConsistencyAgreement;
+    maxHeightLag;
+    autoRecover;
+    recoverLocal;
+    clearLocal;
+    now;
+    status;
+    constructor(options) {
+        this.local = options.local;
+        this.fallbacks = [...(options.fallbacks ?? [])];
+        this.fallbackOnLocalError = options.fallbackOnLocalError ?? true;
+        this.requiredFallbackAgreement = this.validateAgreement(options.requiredFallbackAgreement ?? 1, 'requiredFallbackAgreement');
+        this.requiredConsistencyAgreement = this.validateAgreement(options.requiredConsistencyAgreement ?? 2, 'requiredConsistencyAgreement');
+        this.maxHeightLag = this.validateHeightLag(options.maxHeightLag ?? 6);
+        this.autoRecover = options.autoRecover ?? false;
+        this.recoverLocal = options.recoverLocal;
+        this.clearLocal = options.clearLocal;
+        this.now = options.now ?? (() => new Date());
+        this.status = {
+            mode: options.mode ?? 'local-primary',
+            activeSource: options.mode === 'remote-only' ? 'fallback' : 'local',
+            consistency: 'unchecked'
+        };
+    }
+    getMode() {
+        return this.status.mode;
+    }
+    setMode(mode) {
+        this.status = {
+            ...this.status,
+            mode,
+            activeSource: mode === 'remote-only' ? 'fallback' : 'local'
+        };
+    }
+    getStatus() {
+        return { ...this.status };
+    }
+    getLocalClient() {
+        return this.local;
+    }
+    async currentHeight() {
+        if (this.status.mode === 'remote-only') {
+            return await this.fallbackHeight();
+        }
+        try {
+            const height = await this.local.getPresentHeight();
+            this.status = { ...this.status, activeSource: 'local', localHeight: height, lastError: undefined };
+            return height;
+        }
+        catch (error) {
+            this.recordError(error);
+            if (!this.fallbackOnLocalError)
+                throw error;
+            return await this.fallbackHeight();
+        }
+    }
+    async isValidRootForHeight(root, height) {
+        if (this.status.mode !== 'remote-only') {
+            try {
+                const valid = await this.local.isValidRootForHeight(root, height);
+                this.status = { ...this.status, activeSource: 'local', lastError: undefined };
+                return valid;
+            }
+            catch (error) {
+                this.recordError(error);
+                if (!this.fallbackOnLocalError)
+                    throw error;
+            }
+        }
+        return await this.fallbackValidation(root, height);
+    }
+    async synchronize() {
+        await this.local.startListening();
+        await this.local.listening();
+        return await this.checkConsistency();
+    }
+    async clearLocalData() {
+        if (this.clearLocal == null)
+            throw new Error('Local ChainTracks clearing is not configured.');
+        this.local = await this.clearLocal();
+        this.status = {
+            mode: this.status.mode,
+            activeSource: this.status.mode === 'remote-only' ? 'fallback' : 'local',
+            consistency: 'unchecked'
+        };
+        return this.getStatus();
+    }
+    async checkConsistency() {
+        return await this.checkConsistencyInternal(true);
+    }
+    async checkConsistencyInternal(allowRecovery) {
+        const checkedAt = this.now().toISOString();
+        try {
+            const localHeight = await this.local.getPresentHeight();
+            const localTipHash = await this.local.findChainTipHash();
+            const references = await Promise.all(this.fallbacks.map(async (client, index) => {
+                try {
+                    return { client, index, height: await client.getPresentHeight() };
+                }
+                catch {
+                    return undefined;
+                }
+            }));
+            const available = references.filter((value) => value != null);
+            if (available.length === 0) {
+                this.status = {
+                    ...this.status,
+                    activeSource: 'local',
+                    consistency: 'insufficient-references',
+                    localHeight,
+                    localTipHash,
+                    checkedAt,
+                    lastError: undefined
+                };
+                return this.getStatus();
+            }
+            if (available.length < this.requiredConsistencyAgreement) {
+                this.status = {
+                    ...this.status,
+                    activeSource: 'local',
+                    consistency: 'insufficient-references',
+                    localHeight,
+                    localTipHash,
+                    checkedAt,
+                    lastError: undefined
+                };
+                return this.getStatus();
+            }
+            // The Nth highest reference height is the greatest height reached by at
+            // least N references. A stale or inflated minority cannot move it.
+            const referenceHeight = [...available].map(reference => reference.height).sort((a, b) => b - a)[this.requiredConsistencyAgreement - 1];
+            const comparisonHeight = Math.min(localHeight, referenceHeight);
+            const heightLag = Math.max(0, referenceHeight - localHeight);
+            const localHeader = await this.local.findHeaderForHeight(comparisonHeight);
+            const referenceHeaders = await Promise.all(available
+                .filter(reference => reference.height >= comparisonHeight)
+                .map(async (reference) => {
+                try {
+                    return await reference.client.findHeaderForHeight(comparisonHeight);
+                }
+                catch {
+                    return undefined;
+                }
+            }));
+            const agreements = new Map();
+            for (const header of referenceHeaders) {
+                if (header != null)
+                    agreements.set(header.hash, (agreements.get(header.hash) ?? 0) + 1);
+            }
+            const [expectedHash, referenceAgreement] = [...agreements.entries()].sort(([hashA, countA], [hashB, countB]) => countB - countA || hashA.localeCompare(hashB))[0] ?? [undefined, 0];
+            const enoughReferences = referenceAgreement >= this.requiredConsistencyAgreement;
+            let consistency;
+            if (!enoughReferences)
+                consistency = 'insufficient-references';
+            else if (localHeader?.hash !== expectedHash)
+                consistency = 'diverged';
+            else if (heightLag > this.maxHeightLag)
+                consistency = 'lagging';
+            else
+                consistency = 'agreed';
+            this.status = {
+                ...this.status,
+                activeSource: 'local',
+                consistency,
+                localHeight,
+                localTipHash,
+                referenceHeight,
+                heightLag,
+                comparisonHeight,
+                expectedHash,
+                referenceAgreement,
+                checkedAt,
+                lastError: undefined
+            };
+            if ((consistency === 'diverged' || consistency === 'lagging') &&
+                allowRecovery &&
+                this.autoRecover &&
+                this.recoverLocal != null &&
+                expectedHash != null) {
+                this.local = await this.recoverLocal({
+                    reason: consistency,
+                    localHeight,
+                    referenceHeight,
+                    heightLag,
+                    comparisonHeight,
+                    expectedHash,
+                    referenceAgreement
+                });
+                const recoveredAt = this.now().toISOString();
+                const recovered = await this.checkConsistencyInternal(false);
+                this.status = { ...recovered, recoveredAt };
+            }
+            return this.getStatus();
+        }
+        catch (error) {
+            this.status = {
+                ...this.status,
+                consistency: 'error',
+                checkedAt,
+                lastError: this.errorMessage(error)
+            };
+            return this.getStatus();
+        }
+    }
+    async fallbackHeight() {
+        let lastError;
+        for (const [index, fallback] of this.fallbacks.entries()) {
+            try {
+                const height = await fallback.getPresentHeight();
+                this.recordFallback(index);
+                return height;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        const error = lastError ?? new Error('No fallback ChainTracks source is configured.');
+        this.recordError(error);
+        throw error;
+    }
+    async fallbackValidation(root, height) {
+        let valid = 0;
+        let invalid = 0;
+        let lastError;
+        for (const [index, fallback] of this.fallbacks.entries()) {
+            try {
+                if (await fallback.isValidRootForHeight(root, height))
+                    valid++;
+                else
+                    invalid++;
+                if (valid >= this.requiredFallbackAgreement) {
+                    this.recordFallback(index);
+                    return true;
+                }
+                if (invalid >= this.requiredFallbackAgreement) {
+                    this.recordFallback(index);
+                    return false;
+                }
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        const error = lastError ??
+            new Error(`Fallback agreement unavailable: ${valid} valid and ${invalid} invalid responses, ` +
+                `${this.requiredFallbackAgreement} required.`);
+        this.recordError(error);
+        throw error;
+    }
+    recordFallback(index) {
+        this.status = {
+            ...this.status,
+            activeSource: `fallback-${index + 1}`,
+            lastFallbackAt: this.now().toISOString(),
+            lastError: undefined
+        };
+    }
+    recordError(error) {
+        this.status = { ...this.status, activeSource: 'unavailable', lastError: this.errorMessage(error) };
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    validateAgreement(value, name) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new Error(`${name} must be a positive safe integer`);
+        return value;
+    }
+    validateHeightLag(value) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new Error('maxHeightLag must be a non-negative safe integer');
+        }
+        return value;
+    }
+}
+exports.LocalChainTracker = LocalChainTracker;
+//# sourceMappingURL=LocalChainTracker.js.map

package/out/src/services/chaintracker/LocalChainTracker.js.map

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

package/out/src/services/chaintracker/chaintracks/Api/BulkFileDataCacheApi.d.ts

@@ -0,0 +1,48 @@
+import type { BulkHeaderFileInfo } from '../util/BulkHeaderFile';
+/**
+ * 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
+ */
+export 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
+ */
+export interface BulkFileDownloadBudgetApi {
+    consume(byteCount: number): void | Promise<void>;
+    snapshot?(): BulkFileDownloadBudgetSnapshot;
+}
+/** @public */
+export interface BulkFileDownloadBudgetSnapshot {
+    maxBytes: number;
+    consumedBytes: number;
+    remainingBytes: number;
+    windowStartedAt: number;
+    windowMsecs: number;
+}
+//# sourceMappingURL=BulkFileDataCacheApi.d.ts.map

package/out/src/services/chaintracker/chaintracks/Api/BulkFileDataCacheApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BulkFileDataCacheApi.d.ts","sourceRoot":"","sources":["../../../../../../src/services/chaintracker/chaintracks/Api/BulkFileDataCacheApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAEhE;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;IACxE,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxE;;;;OAIG;IACH,UAAU,CAAC,CACT,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAClC,MAAM,EAAE,MAAM;IACd,iFAAiF;IACjF,YAAY,CAAC,EAAE,UAAU,GACxB,OAAO,CAAC,IAAI,CAAC,CAAA;IAChB;;;OAGG;IACH,gBAAgB,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtF,MAAM,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChD,QAAQ,CAAC,IAAI,8BAA8B,CAAA;CAC5C;AAED,cAAc;AACd,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,MAAM,CAAA;IACvB,WAAW,EAAE,MAAM,CAAA;CACpB"}

package/out/src/services/chaintracker/chaintracks/Api/BulkFileDataCacheApi.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=BulkFileDataCacheApi.js.map

package/out/src/services/chaintracker/chaintracks/Api/BulkFileDataCacheApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BulkFileDataCacheApi.js","sourceRoot":"","sources":["../../../../../../src/services/chaintracker/chaintracks/Api/BulkFileDataCacheApi.ts"],"names":[],"mappings":""}

package/out/src/services/chaintracker/chaintracks/Api/BulkFileDataValidatorApi.d.ts

@@ -0,0 +1,70 @@
+import type { Chain } from '../../../../sdk/types';
+/**
+ * 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
+ */
+export 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
+ */
+export 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 */
+export interface BulkFileDataValidationResult {
+    /** The validated bytes. Worker implementations may transfer ownership. */
+    data: Uint8Array;
+    fileHash: string;
+    lastHeaderHash: string;
+    lastChainWork: string;
+}
+/** @public */
+export 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
+ */
+export interface BulkFileDataValidatorApi {
+    validate(request: BulkFileDataValidationRequest): Promise<BulkFileDataValidationResult>;
+    getStats?(): BulkFileDataValidatorStats;
+    destroy?(): Promise<void>;
+}
+//# sourceMappingURL=BulkFileDataValidatorApi.d.ts.map

package/out/src/services/chaintracker/chaintracks/Api/BulkFileDataValidatorApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BulkFileDataValidatorApi.d.ts","sourceRoot":"","sources":["../../../../../../src/services/chaintracker/chaintracks/Api/BulkFileDataValidatorApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAElD;;;;;;;GAOG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;aAGlC,IAAI,CAAC,EAAE,UAAU;IAFnC,YACE,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,UAAU,YAAA,EAIlC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAED,cAAc;AACd,MAAM,WAAW,4BAA4B;IAC3C,0EAA0E;IAC1E,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,cAAc;AACd,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAA;IACvF,QAAQ,CAAC,IAAI,0BAA0B,CAAA;IACvC,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B"}

package/out/src/services/chaintracker/chaintracks/Api/BulkFileDataValidatorApi.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkFileDataValidationError = void 0;
+/**
+ * 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
+ */
+class BulkFileDataValidationError extends Error {
+    data;
+    constructor(message, data) {
+        super(message);
+        this.data = data;
+        this.name = 'BulkFileDataValidationError';
+    }
+}
+exports.BulkFileDataValidationError = BulkFileDataValidationError;
+//# sourceMappingURL=BulkFileDataValidatorApi.js.map

package/out/src/services/chaintracker/chaintracks/Api/BulkFileDataValidatorApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BulkFileDataValidatorApi.js","sourceRoot":"","sources":["../../../../../../src/services/chaintracker/chaintracks/Api/BulkFileDataValidatorApi.ts"],"names":[],"mappings":";;;AAEA;;;;;;;GAOG;AACH,iCAAyC,SAAQ,KAAK;IAGlC,IAAI;IAFtB,YACE,OAAe,EACC,IAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAA;oBAFE,IAAI;QAGpB,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAA;IAC3C,CAAC;CACF"}

package/out/src/services/chaintracker/chaintracks/Api/ChaintracksClientApi.d.ts

@@ -29,6 +29,41 @@ export 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 */
+export 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 */
 export interface ChaintracksSourceStatusApi {
@@ -39,6 +74,17 @@ export interface ChaintracksSourceStatusApi {
     lastFailure?: string;
     error?: string;
 }
+/** Constant-time, local-only process state for probes and operators. @public */
+export 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

package/out/src/services/chaintracker/chaintracks/Api/ChaintracksClientApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChaintracksClientApi.d.ts","sourceRoot":"","sources":["../../../../../../src/services/chaintracker/chaintracks/Api/ChaintracksClientApi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ChaintracksClientApi.d.ts","sourceRoot":"","sources":["../../../../../../src/services/chaintracker/chaintracks/Api/ChaintracksClientApi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAE7C;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;AAE1D;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,kBAAkB,CAAC,EAAE,WAAW,EAAE,KAC/B,IAAI,CAAA;AAET;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,QAAQ,EAAE,yBAAyB,EAAE,CAAA;IACrC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,0BAA0B,EAAE,CAAA;IACtC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,2BAA2B,CAAA;CACvC;AAED,cAAc;AACd,MAAM,WAAW,2BAA2B;IAC1C,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,qBAAqB,EAAE,MAAM,CAAA;IAC7B,sBAAsB,EAAE,MAAM,CAAA;IAC9B,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,oFAAoF;IACpF,UAAU,CAAC,EAAE;QACX,SAAS,EAAE,MAAM,CAAA;QACjB,SAAS,EAAE,MAAM,CAAA;QACjB,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,cAAc,EAAE,MAAM,CAAA;QACtB,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,aAAa,EAAE,MAAM,CAAA;QACrB,oBAAoB,EAAE,MAAM,CAAA;QAC5B,kBAAkB,EAAE,MAAM,CAAA;KAC3B,CAAA;IACD,0DAA0D;IAC1D,cAAc,CAAC,EAAE;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,aAAa,EAAE,MAAM,CAAA;QACrB,cAAc,EAAE,MAAM,CAAA;QACtB,eAAe,EAAE,MAAM,CAAA;QACvB,WAAW,EAAE,MAAM,CAAA;KACpB,CAAA;CACF;AAED,cAAc;AACd,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IACrB,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAA;IACzC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,gFAAgF;AAChF,MAAM,WAAW,kCAAkC;IACjD,SAAS,EAAE,OAAO,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,4BAA4B,EAAE,OAAO,CAAA;IACrC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,OAAO,EAAE,0BAA0B,EAAE,CAAA;IACrC,QAAQ,EAAE,2BAA2B,CAAA;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAE1B;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAEtC;;OAEG;IACH,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAEnC;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE1D;;OAEG;IACH,kBAAkB,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;IAE1C;;OAEG;IACH,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAEnC;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAA;IAErE;;;OAGG;IACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAA;IAEtE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjD;;;;;;;;;;;;;OAaG;IACH,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/B;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IAE/B;;OAEG;IACH,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IAElC;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE3D;;;;;OAKG;IACH,eAAe,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzD;;;;;;OAMG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAErD,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACpE,aAAa,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,oBAAoB;IAC1D;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD"}