@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.15.0-bopen.1

package/out/src/services/chaintracker/chaintracks/index.all.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.all.js","sourceRoot":"","sources":["../../../../../src/services/chaintracker/chaintracks/index.all.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA8B;AAE9B,uDAAoC;AACpC,mEAAgD;AAChD,qEAAkD;AAElD,wEAAqD;AACrD,0DAAuC;AAEvC,uDAAoC;AACpC,sEAAmD;AACnD,sEAAmD"}
+{"version":3,"file":"index.all.js","sourceRoot":"","sources":["../../../../../src/services/chaintracker/chaintracks/index.all.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA8B;AAE9B,uDAAoC;AACpC,6DAA0C;AAC1C,mEAAgD;AAChD,2EAAwD;AACxD,mEAAgD;AAChD,qEAAkD;AAElD,wEAAqD;AACrD,0DAAuC;AAEvC,uDAAoC;AACpC,sEAAmD;AACnD,sEAAmD"}

package/out/src/services/chaintracker/chaintracks/index.mobile.d.ts

@@ -8,6 +8,8 @@ export * from './Api/BulkStorageApi';
 export * from './Api/BulkIngestorApi';
 export * from './Api/LiveIngestorApi';
 export * from './Api/BlockHeaderApi';
+export * from './Api/BulkFileDataCacheApi';
+export * from './Api/BulkFileDataValidatorApi';
 export * from './Chaintracks';
 export * from './ChaintracksServiceClient';
 export * from './GoChaintracksServiceClient';
@@ -30,6 +32,9 @@ export * from './configureChaintracksIngestors';
 export * from './util/BulkFilesReader';
 export * from './util/HeightRange';
 export * from './util/BulkFileDataManager';
+export * from './util/BulkHeaderFile';
 export * from './util/ChaintracksFetch';
+export * from './util/FixedWindowBulkFileDownloadBudget';
+export * from './util/InlineBulkFileDataValidator';
 export * as utils from './util/blockHeaderUtilities';
 //# sourceMappingURL=index.mobile.d.ts.map

package/out/src/services/chaintracker/chaintracks/index.mobile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.mobile.d.ts","sourceRoot":"","sources":["../../../../../src/services/chaintracker/chaintracks/index.mobile.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE/C,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,sBAAsB,CAAA;AACpC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AAEpC,cAAc,eAAe,CAAA;AAC7B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,8BAA8B,CAAA;AAE5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,2BAA2B,CAAA;AAEzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iCAAiC,CAAA;AAC/C,cAAc,sCAAsC,CAAA;AACpD,cAAc,kCAAkC,CAAA;AAChD,cAAc,uCAAuC,CAAA;AACrD,cAAc,qCAAqC,CAAA;AACnD,cAAc,+BAA+B,CAAA;AAE7C,cAAc,2BAA2B,CAAA;AACzC,cAAc,kCAAkC,CAAA;AAChD,cAAc,kCAAkC,CAAA;AAChD,cAAc,iCAAiC,CAAA;AAE/C,cAAc,uCAAuC,CAAA;AACrD,cAAc,yBAAyB,CAAA;AACvC,cAAc,iCAAiC,CAAA;AAE/C,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,6BAA6B,CAAA"}
+{"version":3,"file":"index.mobile.d.ts","sourceRoot":"","sources":["../../../../../src/services/chaintracker/chaintracks/index.mobile.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE/C,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,sBAAsB,CAAA;AACpC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gCAAgC,CAAA;AAE9C,cAAc,eAAe,CAAA;AAC7B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,8BAA8B,CAAA;AAE5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,2BAA2B,CAAA;AAEzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iCAAiC,CAAA;AAC/C,cAAc,sCAAsC,CAAA;AACpD,cAAc,kCAAkC,CAAA;AAChD,cAAc,uCAAuC,CAAA;AACrD,cAAc,qCAAqC,CAAA;AACnD,cAAc,+BAA+B,CAAA;AAE7C,cAAc,2BAA2B,CAAA;AACzC,cAAc,kCAAkC,CAAA;AAChD,cAAc,kCAAkC,CAAA;AAChD,cAAc,iCAAiC,CAAA;AAE/C,cAAc,uCAAuC,CAAA;AACrD,cAAc,yBAAyB,CAAA;AACvC,cAAc,iCAAiC,CAAA;AAE/C,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,uBAAuB,CAAA;AACrC,cAAc,yBAAyB,CAAA;AACvC,cAAc,0CAA0C,CAAA;AACxD,cAAc,oCAAoC,CAAA;AAElD,OAAO,KAAK,KAAK,MAAM,6BAA6B,CAAA"}

package/out/src/services/chaintracker/chaintracks/index.mobile.js

@@ -46,6 +46,8 @@ __exportStar(require("./Api/BulkStorageApi"), exports);
 __exportStar(require("./Api/BulkIngestorApi"), exports);
 __exportStar(require("./Api/LiveIngestorApi"), exports);
 __exportStar(require("./Api/BlockHeaderApi"), exports);
+__exportStar(require("./Api/BulkFileDataCacheApi"), exports);
+__exportStar(require("./Api/BulkFileDataValidatorApi"), exports);
 __exportStar(require("./Chaintracks"), exports);
 __exportStar(require("./ChaintracksServiceClient"), exports);
 __exportStar(require("./GoChaintracksServiceClient"), exports);
@@ -68,6 +70,9 @@ __exportStar(require("./configureChaintracksIngestors"), exports);
 __exportStar(require("./util/BulkFilesReader"), exports);
 __exportStar(require("./util/HeightRange"), exports);
 __exportStar(require("./util/BulkFileDataManager"), exports);
+__exportStar(require("./util/BulkHeaderFile"), exports);
 __exportStar(require("./util/ChaintracksFetch"), exports);
+__exportStar(require("./util/FixedWindowBulkFileDownloadBudget"), exports);
+__exportStar(require("./util/InlineBulkFileDataValidator"), exports);
 exports.utils = __importStar(require("./util/blockHeaderUtilities"));
 //# sourceMappingURL=index.mobile.js.map

package/out/src/services/chaintracker/chaintracks/index.mobile.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.mobile.js","sourceRoot":"","sources":["../../../../../src/services/chaintracker/chaintracks/index.mobile.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,uDAAoC;AACpC,6DAA0C;AAC1C,yDAAsC;AACtC,4DAAyC;AACzC,8DAA2C;AAC3C,uDAAoC;AACpC,wDAAqC;AACrC,wDAAqC;AACrC,uDAAoC;AAEpC,gDAA6B;AAC7B,6DAA0C;AAC1C,+DAA4C;AAE5C,4DAAyC;AACzC,4DAAyC;AAEzC,2DAAwC;AACxC,kEAA+C;AAC/C,uEAAoD;AACpD,mEAAgD;AAChD,wEAAqD;AACrD,sEAAmD;AACnD,gEAA6C;AAE7C,4DAAyC;AACzC,mEAAgD;AAChD,mEAAgD;AAChD,kEAA+C;AAE/C,wEAAqD;AACrD,0DAAuC;AACvC,kEAA+C;AAE/C,yDAAsC;AACtC,qDAAkC;AAClC,6DAA0C;AAC1C,0DAAuC;AAEvC,QAAY,KAAK,wDAAmC"}
+{"version":3,"file":"index.mobile.js","sourceRoot":"","sources":["../../../../../src/services/chaintracker/chaintracks/index.mobile.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,uDAAoC;AACpC,6DAA0C;AAC1C,yDAAsC;AACtC,4DAAyC;AACzC,8DAA2C;AAC3C,uDAAoC;AACpC,wDAAqC;AACrC,wDAAqC;AACrC,uDAAoC;AACpC,6DAA0C;AAC1C,iEAA8C;AAE9C,gDAA6B;AAC7B,6DAA0C;AAC1C,+DAA4C;AAE5C,4DAAyC;AACzC,4DAAyC;AAEzC,2DAAwC;AACxC,kEAA+C;AAC/C,uEAAoD;AACpD,mEAAgD;AAChD,wEAAqD;AACrD,sEAAmD;AACnD,gEAA6C;AAE7C,4DAAyC;AACzC,mEAAgD;AAChD,mEAAgD;AAChD,kEAA+C;AAE/C,wEAAqD;AACrD,0DAAuC;AACvC,kEAA+C;AAE/C,yDAAsC;AACtC,qDAAkC;AAClC,6DAA0C;AAC1C,wDAAqC;AACrC,0DAAuC;AACvC,2EAAwD;AACxD,qEAAkD;AAElD,QAAY,KAAK,wDAAmC"}

package/out/src/services/chaintracker/chaintracks/util/BulkFileDataCacheFs.d.ts

@@ -0,0 +1,51 @@
+import type { BulkFileDataCacheApi } from '../Api/BulkFileDataCacheApi';
+import type { BulkHeaderFileInfo } from './BulkHeaderFile';
+export interface BulkFileDataCacheFsOptions {
+    /** Root for immutable content-addressed cache objects. */
+    rootFolder: string;
+    /** Read-only legacy locations consulted during in-place migration. */
+    legacyRoots?: string[];
+    /** Maximum wait for a per-object cross-process mutation lock. Default: 30 seconds. */
+    lockTimeoutMsecs?: number;
+    /** Delay between lock attempts. Default: 25 milliseconds. */
+    lockRetryMsecs?: number;
+}
+/**
+ * Atomic filesystem implementation of the bulk-header cache contract.
+ *
+ * This Node-only export is intentionally absent from browser and mobile entry
+ * points. Cache contents are untrusted until the manager verifies their exact
+ * byte length and SHA-256 digest.
+ *
+ * @public
+ */
+export declare class BulkFileDataCacheFs implements BulkFileDataCacheApi {
+    private static readonly MAX_HEADERS_PER_FILE;
+    private static readonly MAX_LEGACY_ROOTS;
+    private static readonly SAFE_FILE_NAME;
+    private readonly rootFolder;
+    private readonly legacyRoots;
+    private readonly lockTimeoutMsecs;
+    private readonly lockRetryMsecs;
+    constructor(rootFolderOrOptions: string | BulkFileDataCacheFsOptions);
+    private legacyFilePath;
+    private validateFileName;
+    private validateRoot;
+    private expectedBytes;
+    private validateData;
+    private digestHex;
+    private objectPath;
+    private legacyRejectionMarker;
+    get(file: Readonly<BulkHeaderFileInfo>): Promise<Uint8Array | undefined>;
+    set(file: Readonly<BulkHeaderFileInfo>, data: Uint8Array): Promise<void>;
+    private setNoLock;
+    promoteValidated(file: Readonly<BulkHeaderFileInfo>, data: Uint8Array): Promise<void>;
+    quarantine(file: Readonly<BulkHeaderFileInfo>, reason: string, rejectedData?: Uint8Array): Promise<void>;
+    private quarantineNoLock;
+    delete(file: Readonly<BulkHeaderFileInfo>): Promise<void>;
+    private readBoundedFile;
+    private positiveInteger;
+    private snapshotFile;
+    private withObjectLock;
+}
+//# sourceMappingURL=BulkFileDataCacheFs.d.ts.map

package/out/src/services/chaintracker/chaintracks/util/BulkFileDataCacheFs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BulkFileDataCacheFs.d.ts","sourceRoot":"","sources":["../../../../../../src/services/chaintracker/chaintracks/util/BulkFileDataCacheFs.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAU;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAK;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAwC;IAE9E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IAEvC,YAAY,mBAAmB,EAAE,MAAM,GAAG,0BAA0B,EAoBnE;IAED,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,qBAAqB;IAIvB,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAqB7E;IAEK,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAK7E;YAEa,SAAS;IAsBjB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1F;IAEK,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAa7G;YAEa,gBAAgB;IA4BxB,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;YAEa,eAAe;IA+B7B,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,YAAY;YAeN,cAAc;CAsD7B"}

package/out/src/services/chaintracker/chaintracks/util/BulkFileDataCacheFs.js

@@ -0,0 +1,394 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkFileDataCacheFs = void 0;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const path = __importStar(require("node:path"));
+/**
+ * Atomic filesystem implementation of the bulk-header cache contract.
+ *
+ * This Node-only export is intentionally absent from browser and mobile entry
+ * points. Cache contents are untrusted until the manager verifies their exact
+ * byte length and SHA-256 digest.
+ *
+ * @public
+ */
+class BulkFileDataCacheFs {
+    static MAX_HEADERS_PER_FILE = 100_000;
+    static MAX_LEGACY_ROOTS = 64;
+    static SAFE_FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$/;
+    rootFolder;
+    legacyRoots;
+    lockTimeoutMsecs;
+    lockRetryMsecs;
+    constructor(rootFolderOrOptions) {
+        const options = typeof rootFolderOrOptions === 'string' ? { rootFolder: rootFolderOrOptions } : rootFolderOrOptions;
+        if (options == null || typeof options !== 'object' || Array.isArray(options)) {
+            throw new Error('Bulk-header cache options must be a root path or options object.');
+        }
+        this.rootFolder = this.validateRoot(options.rootFolder, 'rootFolder');
+        this.lockTimeoutMsecs = this.positiveInteger(options.lockTimeoutMsecs ?? 30_000, 'lockTimeoutMsecs');
+        this.lockRetryMsecs = this.positiveInteger(options.lockRetryMsecs ?? 25, 'lockRetryMsecs');
+        if (this.lockRetryMsecs > this.lockTimeoutMsecs) {
+            throw new Error('lockRetryMsecs must be no greater than lockTimeoutMsecs.');
+        }
+        const legacyRoots = options.legacyRoots ?? [];
+        if (!Array.isArray(legacyRoots) || legacyRoots.length > BulkFileDataCacheFs.MAX_LEGACY_ROOTS) {
+            throw new Error(`legacyRoots must be an array of no more than ${BulkFileDataCacheFs.MAX_LEGACY_ROOTS} paths.`);
+        }
+        this.legacyRoots = [];
+        for (let index = 0; index < legacyRoots.length; index++) {
+            if (!Object.hasOwn(legacyRoots, index))
+                throw new Error('legacyRoots must be a dense array of paths.');
+            this.legacyRoots.push(this.validateRoot(legacyRoots[index], `legacyRoots[${index}]`));
+        }
+    }
+    legacyFilePath(root, file) {
+        this.validateFileName(file);
+        return path.join(root, file.fileName);
+    }
+    validateFileName(file) {
+        if (typeof file.fileName !== 'string' ||
+            !BulkFileDataCacheFs.SAFE_FILE_NAME.test(file.fileName) ||
+            path.basename(file.fileName) !== file.fileName ||
+            file.fileName === '.' ||
+            file.fileName === '..') {
+            throw new Error(`Invalid bulk-header cache file name: ${file.fileName}`);
+        }
+    }
+    validateRoot(value, name) {
+        if (typeof value !== 'string' || value.trim() === '' || /[\r\n]/.test(value) || value.includes('\u0000')) {
+            throw new Error(`${name} must be a non-empty filesystem path without control lines.`);
+        }
+        const resolved = path.resolve(value);
+        if (resolved === path.parse(resolved).root)
+            throw new Error(`${name} cannot be a filesystem root.`);
+        return resolved;
+    }
+    expectedBytes(file) {
+        if (!Number.isSafeInteger(file.count) || file.count < 1 || file.count > BulkFileDataCacheFs.MAX_HEADERS_PER_FILE) {
+            throw new Error(`Invalid bulk-header count for ${file.fileName}`);
+        }
+        return file.count * 80;
+    }
+    validateData(file, data) {
+        if (!(data instanceof Uint8Array))
+            throw new Error(`Invalid bulk-header data for ${file.fileName}`);
+        if (data.byteLength !== this.expectedBytes(file)) {
+            throw new Error(`Invalid bulk-header data length for ${file.fileName}`);
+        }
+        if ((0, node_crypto_1.createHash)('sha256').update(data).digest('base64') !== file.fileHash) {
+            throw new Error(`Invalid bulk-header data digest for ${file.fileName}`);
+        }
+    }
+    digestHex(file) {
+        if (file.fileHash == null)
+            throw new Error(`Missing bulk-header digest for ${file.fileName}`);
+        const digest = Buffer.from(file.fileHash, 'base64');
+        if (digest.length !== 32 || digest.toString('base64') !== file.fileHash) {
+            throw new Error(`Invalid bulk-header digest for ${file.fileName}`);
+        }
+        return digest.toString('hex');
+    }
+    objectPath(file) {
+        this.validateFileName(file);
+        const digest = this.digestHex(file);
+        return path.join(this.rootFolder, 'objects', digest.slice(0, 2), `${digest}.headers`);
+    }
+    legacyRejectionMarker(file) {
+        return path.join(this.rootFolder, 'quarantine', `${this.digestHex(file)}.legacy-rejected.json`);
+    }
+    async get(file) {
+        file = this.snapshotFile(file);
+        try {
+            return await this.readBoundedFile(this.objectPath(file), file);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        try {
+            await node_fs_1.promises.access(this.legacyRejectionMarker(file));
+            return undefined;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        for (const root of this.legacyRoots) {
+            try {
+                return await this.readBoundedFile(this.legacyFilePath(root, file), file);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        return undefined;
+    }
+    async set(file, data) {
+        file = this.snapshotFile(file);
+        const ownedData = data instanceof Uint8Array ? data.slice() : data;
+        this.validateData(file, ownedData);
+        await this.withObjectLock(file, async () => await this.setNoLock(file, ownedData));
+    }
+    async setNoLock(file, data) {
+        const destination = this.objectPath(file);
+        const folder = path.dirname(destination);
+        await node_fs_1.promises.mkdir(folder, { recursive: true });
+        const temporary = path.join(folder, `.${path.basename(destination)}.${process.pid}.${(0, node_crypto_1.randomUUID)()}.tmp`);
+        let handle;
+        try {
+            handle = await node_fs_1.promises.open(temporary, 'wx', 0o600);
+            await handle.writeFile(data);
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await node_fs_1.promises.rename(temporary, destination);
+            await syncDirectory(folder);
+        }
+        finally {
+            await handle?.close().catch(() => undefined);
+            await node_fs_1.promises.unlink(temporary).catch(error => {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            });
+        }
+    }
+    async promoteValidated(file, data) {
+        file = this.snapshotFile(file);
+        const ownedData = data instanceof Uint8Array ? data.slice() : data;
+        this.validateData(file, ownedData);
+        await this.withObjectLock(file, async () => {
+            try {
+                await node_fs_1.promises.access(this.objectPath(file));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                await this.setNoLock(file, ownedData);
+            }
+        });
+    }
+    async quarantine(file, reason, rejectedData) {
+        file = this.snapshotFile(file);
+        if (typeof reason !== 'string' || reason.length > 4096 || /[\r\n]/.test(reason) || reason.includes('\u0000')) {
+            throw new Error('Bulk-header quarantine reason must be a single-line string no longer than 4096 characters.');
+        }
+        if (rejectedData !== undefined && !(rejectedData instanceof Uint8Array)) {
+            throw new Error('Rejected bulk-header data exceeds the bounded cache-object size.');
+        }
+        rejectedData = rejectedData?.slice();
+        if (rejectedData !== undefined && rejectedData.byteLength > this.expectedBytes(file) + 1) {
+            throw new Error('Rejected bulk-header data exceeds the bounded cache-object size.');
+        }
+        await this.withObjectLock(file, async () => await this.quarantineNoLock(file, reason, rejectedData));
+    }
+    async quarantineNoLock(file, reason, rejectedData) {
+        const source = this.objectPath(file);
+        const quarantineFolder = path.join(this.rootFolder, 'quarantine');
+        const destination = path.join(quarantineFolder, `${this.digestHex(file)}.${Date.now()}.${(0, node_crypto_1.randomUUID)()}.invalid`);
+        await node_fs_1.promises.mkdir(quarantineFolder, { recursive: true });
+        try {
+            const candidate = await this.readBoundedFile(source, file);
+            if (rejectedData != null && !Buffer.from(candidate).equals(Buffer.from(rejectedData)))
+                return;
+            await node_fs_1.promises.rename(source, destination);
+            await syncDirectory(path.dirname(source));
+            await syncDirectory(quarantineFolder);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            if (this.legacyRoots.length === 0)
+                return;
+            // Legacy entries are intentionally read-only. Once replacement succeeds,
+            // the content-addressed object takes precedence without destroying the
+            // old deployment's only retained bytes.
+            await writeAtomicFile(this.legacyRejectionMarker(file), Buffer.from(JSON.stringify({ fileName: file.fileName, fileHash: file.fileHash, reason })));
+        }
+    }
+    async delete(file) {
+        await this.quarantine(file, 'delete requested through legacy cache contract');
+    }
+    async readBoundedFile(source, file) {
+        const maximum = this.expectedBytes(file);
+        const handle = await node_fs_1.promises.open(source, 'r');
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile())
+                throw new Error(`Bulk-header cache object is not a regular file: ${file.fileName}`);
+            const requested = stat.size > maximum ? maximum + 1 : stat.size;
+            const data = new Uint8Array(requested);
+            let offset = 0;
+            while (offset < data.length) {
+                const { bytesRead } = await handle.read(data, offset, data.length - offset, offset);
+                if (bytesRead === 0)
+                    break;
+                offset += bytesRead;
+            }
+            let result = offset === data.length ? data : data.slice(0, offset);
+            if (result.length <= maximum) {
+                const extra = new Uint8Array(1);
+                const { bytesRead } = await handle.read(extra, 0, 1, result.length);
+                if (bytesRead > 0) {
+                    const grown = new Uint8Array(result.length + 1);
+                    grown.set(result);
+                    grown[result.length] = extra[0];
+                    result = grown;
+                }
+            }
+            return result;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    positiveInteger(value, name) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > 60 * 60 * 1000) {
+            throw new Error(`${name} must be an integer from 1 through 3600000.`);
+        }
+        return value;
+    }
+    snapshotFile(file) {
+        if (file == null || typeof file !== 'object' || Array.isArray(file)) {
+            throw new Error('Bulk-header cache metadata must be a data object.');
+        }
+        const values = {};
+        for (const name of ['fileName', 'fileHash', 'count']) {
+            const descriptor = Object.getOwnPropertyDescriptor(file, name);
+            if (descriptor == null || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+                throw new Error(`Bulk-header cache metadata ${name} must be an own data property.`);
+            }
+            values[name] = descriptor.value;
+        }
+        return values;
+    }
+    async withObjectLock(file, work) {
+        const destination = this.objectPath(file);
+        const lockFolder = `${destination}.lock`;
+        const ownerFile = path.join(lockFolder, 'owner');
+        const token = (0, node_crypto_1.randomUUID)();
+        const startedAt = Date.now();
+        await node_fs_1.promises.mkdir(path.dirname(destination), { recursive: true });
+        for (;;) {
+            try {
+                await node_fs_1.promises.mkdir(lockFolder, { mode: 0o700 });
+                try {
+                    await node_fs_1.promises.writeFile(ownerFile, token, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+                }
+                catch (error) {
+                    await node_fs_1.promises.rmdir(lockFolder).catch(() => undefined);
+                    throw error;
+                }
+                break;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                if (Date.now() - startedAt >= this.lockTimeoutMsecs) {
+                    throw new Error(`Timed out acquiring bulk-header cache lock ${lockFolder}. ` +
+                        'The lock is never reclaimed automatically after a crash; verify that no writer is active before removing it.');
+                }
+                await new Promise(resolve => setTimeout(resolve, this.lockRetryMsecs));
+            }
+        }
+        let outcome;
+        try {
+            outcome = { ok: true, value: await work() };
+        }
+        catch (error) {
+            outcome = { ok: false, error };
+        }
+        let releaseError;
+        try {
+            let owner;
+            try {
+                owner = await node_fs_1.promises.readFile(ownerFile, 'utf8');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (owner === token) {
+                await node_fs_1.promises.unlink(ownerFile);
+                await node_fs_1.promises.rmdir(lockFolder);
+            }
+        }
+        catch (error) {
+            releaseError = error;
+        }
+        if (!outcome.ok)
+            throw outcome.error;
+        if (releaseError != null)
+            throw releaseError;
+        return outcome.value;
+    }
+}
+exports.BulkFileDataCacheFs = BulkFileDataCacheFs;
+async function writeAtomicFile(destination, data) {
+    const folder = path.dirname(destination);
+    await node_fs_1.promises.mkdir(folder, { recursive: true });
+    const temporary = path.join(folder, `.${path.basename(destination)}.${process.pid}.${(0, node_crypto_1.randomUUID)()}.tmp`);
+    let handle;
+    try {
+        handle = await node_fs_1.promises.open(temporary, 'wx', 0o600);
+        await handle.writeFile(data);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await node_fs_1.promises.rename(temporary, destination);
+        await syncDirectory(folder);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await node_fs_1.promises.unlink(temporary).catch(error => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+    }
+}
+async function syncDirectory(folder) {
+    let handle;
+    try {
+        handle = await node_fs_1.promises.open(folder, 'r');
+        await handle.sync();
+    }
+    finally {
+        await handle?.close();
+    }
+}
+//# sourceMappingURL=BulkFileDataCacheFs.js.map

package/out/src/services/chaintracker/chaintracks/util/BulkFileDataCacheFs.js.map

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

package/out/src/services/chaintracker/chaintracks/util/BulkFileDataManager.d.ts

@@ -1,16 +1,43 @@
 import { BulkFileDataReader } from './BulkFileDataReader';
 import { ChaintracksFetchApi } from '../Api/ChaintracksFetchApi';
 import { BlockHeader, Chain } from '../../../../sdk';
-import { BulkHeaderFileInfo } from './BulkHeaderFile';
+import { BulkHeaderFileInfo, BulkHeaderFilesInfo } from './BulkHeaderFile';
 import { HeightRange } from './HeightRange';
 import { ChaintracksStorageBulkFileApi } from '../Api/ChaintracksStorageApi';
 import { ChaintracksFsApi } from '../Api/ChaintracksFsApi';
+import type { BulkFileDataCacheApi, BulkFileDownloadBudgetApi, BulkFileDownloadBudgetSnapshot } from '../Api/BulkFileDataCacheApi';
+import { type BulkFileDataValidatorApi, type BulkFileDataValidatorStats } from '../Api/BulkFileDataValidatorApi';
+export declare function normalizeBulkHeaderFileInfo(value: unknown, allowStoredBoolean?: boolean): BulkHeaderFileInfo;
+export declare function normalizeBulkHeaderFilesInfo(value: unknown): BulkHeaderFilesInfo;
+export declare function normalizeBulkHeaderFileSequence(files: unknown, allowStoredBoolean?: boolean): BulkHeaderFileInfo[];
 export interface BulkFileDataManagerOptions {
     chain: Chain;
     maxPerFile: number;
     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 */
+export 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).
@@ -27,13 +54,21 @@ export 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;
     /**
@@ -60,6 +95,7 @@ export 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>;
@@ -77,6 +113,8 @@ export declare class BulkFileDataManager {
     private validateBfdForAdd;
     private add;
     private replaceBfdAtIndex;
+    private setBulkFilesState;
+    private applyCommittedBulkFiles;
     /**
      * Updating an existing file occurs in two specific contexts:
      *
@@ -126,8 +164,14 @@ export 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;