@aztec/blob-client 0.0.1-commit.023c3e5

package/dest/client/tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tests.d.ts","sourceRoot":"","sources":["../../src/client/tests.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,OAAO,CAAC;IAAE,MAAM,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,QAiD3F"}

package/dest/client/tests.js

@@ -0,0 +1,51 @@
+import { makeRandomBlob } from '@aztec/blob-lib/testing';
+/**
+ * Shared test suite for blob clients
+ * @param createClient - Function that creates a client instance for testing
+ * @param cleanup - Optional cleanup function to run after each test
+ */ export function runBlobClientTests(createClient) {
+    let blockId;
+    let client;
+    let cleanup;
+    beforeEach(async ()=>{
+        blockId = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
+        const setup = await createClient();
+        client = setup.client;
+        cleanup = setup.cleanup;
+    });
+    afterEach(async ()=>{
+        await cleanup();
+    });
+    it('should send and retrieve blobs by hash', async ()=>{
+        const blob = makeRandomBlob(5);
+        const blobHash = blob.getEthVersionedBlobHash();
+        await client.sendBlobsToFilestore([
+            blob
+        ]);
+        const retrievedBlobs = await client.getBlobSidecar(blockId, [
+            blobHash
+        ]);
+        expect(retrievedBlobs).toHaveLength(1);
+        expect(retrievedBlobs[0]).toEqual(blob);
+    });
+    it('should handle multiple blobs', async ()=>{
+        const blobs = Array.from({
+            length: 3
+        }, ()=>makeRandomBlob(7));
+        const blobHashes = blobs.map((blob)=>blob.getEthVersionedBlobHash());
+        await client.sendBlobsToFilestore(blobs);
+        const retrievedBlobs = await client.getBlobSidecar(blockId, blobHashes);
+        expect(retrievedBlobs.length).toBe(3);
+        for(let i = 0; i < blobs.length; i++){
+            expect(retrievedBlobs[i]).toEqual(blobs[i]);
+        }
+    });
+    it('should return empty array for non-existent blob hash', async ()=>{
+        const nonExistentHash = Buffer.alloc(32);
+        nonExistentHash.fill(0xff);
+        const retrievedBlobs = await client.getBlobSidecar(blockId, [
+            nonExistentHash
+        ]);
+        expect(retrievedBlobs).toEqual([]);
+    });
+}

package/dest/encoding/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Snappy decompress the blob buffer
+ *
+ * @param data - The blob buffer
+ * @returns The decompressed blob buffer
+ */
+export declare function inboundTransform(data: Buffer): Buffer;
+/**
+ * Snappy compress the blob buffer
+ *
+ * @param data - The blob buffer
+ * @returns The compressed blob buffer
+ */
+export declare function outboundTransform(data: Buffer): Buffer;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9lbmNvZGluZy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFFQTs7Ozs7R0FLRztBQUNILHdCQUFnQixnQkFBZ0IsQ0FBQyxJQUFJLEVBQUUsTUFBTSxHQUFHLE1BQU0sQ0FFckQ7QUFFRDs7Ozs7R0FLRztBQUNILHdCQUFnQixpQkFBaUIsQ0FBQyxJQUFJLEVBQUUsTUFBTSxHQUFHLE1BQU0sQ0FFdEQifQ==

package/dest/encoding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/encoding/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dest/encoding/index.js

@@ -0,0 +1,19 @@
+import { compressSync, uncompressSync } from 'snappy';
+/**
+ * Snappy decompress the blob buffer
+ *
+ * @param data - The blob buffer
+ * @returns The decompressed blob buffer
+ */ export function inboundTransform(data) {
+    return Buffer.from(uncompressSync(data, {
+        asBuffer: true
+    }));
+}
+/**
+ * Snappy compress the blob buffer
+ *
+ * @param data - The blob buffer
+ * @returns The compressed blob buffer
+ */ export function outboundTransform(data) {
+    return Buffer.from(compressSync(data));
+}

package/dest/filestore/factory.d.ts

@@ -0,0 +1,50 @@
+import { type Logger } from '@aztec/foundation/log';
+import { FileStoreBlobClient } from './filestore_blob_client.js';
+/**
+ * Metadata required to construct the base path for blob storage.
+ * Path format: aztec-{l1ChainId}-{rollupVersion}-{rollupAddress}/
+ */
+export interface BlobFileStoreMetadata {
+    /** The L1 chain ID */
+    l1ChainId: number;
+    /** The rollup version */
+    rollupVersion: number;
+    /** The rollup contract address (with or without 0x prefix) */
+    rollupAddress: string;
+}
+/**
+ * Constructs the base path for blob storage.
+ * Format: aztec-{l1ChainId}-{rollupVersion}-{rollupAddress}
+ */
+export declare function makeBlobBasePath(metadata: BlobFileStoreMetadata): string;
+/**
+ * Creates a read-only FileStoreBlobClient for fetching blobs.
+ *
+ * @param storeUrl - The URL of the filestore (s3://, gs://, file://, https://)
+ * @param metadata - Chain metadata for constructing the base path
+ * @param logger - Optional logger
+ * @returns A FileStoreBlobClient for reading blobs, or undefined if storeUrl is undefined
+ */
+export declare function createReadOnlyFileStoreBlobClient(storeUrl: string, metadata: BlobFileStoreMetadata, logger?: Logger): Promise<FileStoreBlobClient>;
+export declare function createReadOnlyFileStoreBlobClient(storeUrl: string | undefined, metadata: BlobFileStoreMetadata, logger?: Logger): Promise<FileStoreBlobClient | undefined>;
+/**
+ * Creates multiple read-only FileStoreBlobClients from an array of URLs.
+ *
+ * @param storeUrls - Array of filestore URLs
+ * @param metadata - Chain metadata for constructing the base path
+ * @param logger - Optional logger
+ * @returns Array of FileStoreBlobClients (excludes any that failed to create)
+ */
+export declare function createReadOnlyFileStoreBlobClients(storeUrls: string[] | undefined, metadata: BlobFileStoreMetadata, logger?: Logger): Promise<FileStoreBlobClient[]>;
+/**
+ * Creates a writable FileStoreBlobClient for uploading blobs.
+ * Note: https:// URLs are not supported for upload, only s3://, gs://, or file://.
+ *
+ * @param storeUrl - The URL of the filestore (s3://, gs://, file://)
+ * @param metadata - Chain metadata for constructing the base path
+ * @param logger - Optional logger
+ * @returns A writable FileStoreBlobClient, or undefined if storeUrl is undefined
+ */
+export declare function createWritableFileStoreBlobClient(storeUrl: string, metadata: BlobFileStoreMetadata, logger?: Logger): Promise<FileStoreBlobClient>;
+export declare function createWritableFileStoreBlobClient(storeUrl: string | undefined, metadata: BlobFileStoreMetadata, logger?: Logger): Promise<FileStoreBlobClient | undefined>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdG9yeS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ZpbGVzdG9yZS9mYWN0b3J5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQVFsRSxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSw0QkFBNEIsQ0FBQztBQUVqRTs7O0dBR0c7QUFDSCxNQUFNLFdBQVcscUJBQXFCO0lBQ3BDLHNCQUFzQjtJQUN0QixTQUFTLEVBQUUsTUFBTSxDQUFDO0lBQ2xCLHlCQUF5QjtJQUN6QixhQUFhLEVBQUUsTUFBTSxDQUFDO0lBQ3RCLDhEQUE4RDtJQUM5RCxhQUFhLEVBQUUsTUFBTSxDQUFDO0NBQ3ZCO0FBRUQ7OztHQUdHO0FBQ0gsd0JBQWdCLGdCQUFnQixDQUFDLFFBQVEsRUFBRSxxQkFBcUIsR0FBRyxNQUFNLENBS3hFO0FBRUQ7Ozs7Ozs7R0FPRztBQUNILHdCQUFzQixpQ0FBaUMsQ0FDckQsUUFBUSxFQUFFLE1BQU0sRUFDaEIsUUFBUSxFQUFFLHFCQUFxQixFQUMvQixNQUFNLENBQUMsRUFBRSxNQUFNLEdBQ2QsT0FBTyxDQUFDLG1CQUFtQixDQUFDLENBQUM7QUFDaEMsd0JBQXNCLGlDQUFpQyxDQUNyRCxRQUFRLEVBQUUsTUFBTSxHQUFHLFNBQVMsRUFDNUIsUUFBUSxFQUFFLHFCQUFxQixFQUMvQixNQUFNLENBQUMsRUFBRSxNQUFNLEdBQ2QsT0FBTyxDQUFDLG1CQUFtQixHQUFHLFNBQVMsQ0FBQyxDQUFDO0FBbUI1Qzs7Ozs7OztHQU9HO0FBQ0gsd0JBQXNCLGtDQUFrQyxDQUN0RCxTQUFTLEVBQUUsTUFBTSxFQUFFLEdBQUcsU0FBUyxFQUMvQixRQUFRLEVBQUUscUJBQXFCLEVBQy9CLE1BQU0sQ0FBQyxFQUFFLE1BQU0sR0FDZCxPQUFPLENBQUMsbUJBQW1CLEVBQUUsQ0FBQyxDQW9CaEM7QUFFRDs7Ozs7Ozs7R0FRRztBQUNILHdCQUFzQixpQ0FBaUMsQ0FDckQsUUFBUSxFQUFFLE1BQU0sRUFDaEIsUUFBUSxFQUFFLHFCQUFxQixFQUMvQixNQUFNLENBQUMsRUFBRSxNQUFNLEdBQ2QsT0FBTyxDQUFDLG1CQUFtQixDQUFDLENBQUM7QUFDaEMsd0JBQXNCLGlDQUFpQyxDQUNyRCxRQUFRLEVBQUUsTUFBTSxHQUFHLFNBQVMsRUFDNUIsUUFBUSxFQUFFLHFCQUFxQixFQUMvQixNQUFNLENBQUMsRUFBRSxNQUFNLEdBQ2QsT0FBTyxDQUFDLG1CQUFtQixHQUFHLFNBQVMsQ0FBQyxDQUFDIn0=

package/dest/filestore/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/filestore/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,uBAAuB,CAAC;AAQlE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAKxE;AAED;;;;;;;GAOG;AACH,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAChC,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;AAmB5C;;;;;;;GAOG;AACH,wBAAsB,kCAAkC,CACtD,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAoBhC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAChC,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC"}

package/dest/filestore/factory.js

@@ -0,0 +1,67 @@
+import { createLogger } from '@aztec/foundation/log';
+import { createFileStore, createReadOnlyFileStore } from '@aztec/stdlib/file-store';
+import { FileStoreBlobClient } from './filestore_blob_client.js';
+/**
+ * Constructs the base path for blob storage.
+ * Format: aztec-{l1ChainId}-{rollupVersion}-{rollupAddress}
+ */ export function makeBlobBasePath(metadata) {
+    const { l1ChainId, rollupVersion, rollupAddress } = metadata;
+    // Normalize rollup address to lowercase without 0x prefix for consistency
+    const normalizedAddress = rollupAddress.toLowerCase().replace(/^0x/, '');
+    return `aztec-${l1ChainId}-${rollupVersion}-0x${normalizedAddress}`;
+}
+export async function createReadOnlyFileStoreBlobClient(storeUrl, metadata, logger) {
+    if (!storeUrl) {
+        return undefined;
+    }
+    const log = logger ?? createLogger('blob-client:filestore-factory');
+    const basePath = makeBlobBasePath(metadata);
+    log.debug(`Creating read-only filestore blob client`, {
+        storeUrl,
+        basePath
+    });
+    const store = await createReadOnlyFileStore(storeUrl, log);
+    return new FileStoreBlobClient(store, basePath, log);
+}
+/**
+ * Creates multiple read-only FileStoreBlobClients from an array of URLs.
+ *
+ * @param storeUrls - Array of filestore URLs
+ * @param metadata - Chain metadata for constructing the base path
+ * @param logger - Optional logger
+ * @returns Array of FileStoreBlobClients (excludes any that failed to create)
+ */ export async function createReadOnlyFileStoreBlobClients(storeUrls, metadata, logger) {
+    if (!storeUrls || storeUrls.length === 0) {
+        return [];
+    }
+    const log = logger ?? createLogger('blob-client:filestore-factory');
+    const clients = [];
+    for (const storeUrl of storeUrls){
+        try {
+            const client = await createReadOnlyFileStoreBlobClient(storeUrl, metadata, log);
+            if (client) {
+                clients.push(client);
+            }
+        } catch (err) {
+            log.error(`Failed to create read-only filestore blob client for ${storeUrl}`, err);
+        }
+    }
+    return clients;
+}
+export async function createWritableFileStoreBlobClient(storeUrl, metadata, logger) {
+    if (!storeUrl) {
+        return undefined;
+    }
+    const log = logger ?? createLogger('blob-client:filestore-factory');
+    const basePath = makeBlobBasePath(metadata);
+    log.debug(`Creating writable filestore blob client`, {
+        storeUrl,
+        basePath
+    });
+    const store = await createFileStore(storeUrl, log);
+    if (!store) {
+        log.warn(`Failed to create writable filestore for ${storeUrl}`);
+        return undefined;
+    }
+    return new FileStoreBlobClient(store, basePath, log);
+}

package/dest/filestore/filestore_blob_client.d.ts

@@ -0,0 +1,67 @@
+import { Blob, type BlobJson } from '@aztec/blob-lib';
+import { type Logger } from '@aztec/foundation/log';
+import type { FileStore, ReadOnlyFileStore } from '@aztec/stdlib/file-store';
+/**
+ * A blob client that uses a FileStore (S3/GCS/local) as the data source.
+ * Blobs are stored as JSON files keyed by their versioned blob hash.
+ */
+export declare class FileStoreBlobClient {
+    private readonly store;
+    private readonly basePath;
+    private readonly log;
+    constructor(store: ReadOnlyFileStore | FileStore, basePath: string, logger?: Logger);
+    /**
+     * Get the path for a blob file.
+     * Format: basePath/blobs/{versionedBlobHash}.data
+     */
+    private blobPath;
+    /**
+     * Get the path for the healthcheck file.
+     * Format: basePath/.healthcheck
+     */
+    private healthcheckPath;
+    /**
+     * Fetch blobs by their versioned hashes.
+     * @param blobHashes - Array of versioned blob hashes (0x-prefixed hex strings)
+     * @returns Array of BlobJson objects for found blobs
+     */
+    getBlobsByHashes(blobHashes: string[]): Promise<BlobJson[]>;
+    /**
+     * Check if a blob exists in the store.
+     * @param versionedBlobHash - The versioned blob hash (0x-prefixed hex string)
+     */
+    exists(versionedBlobHash: string): Promise<boolean>;
+    /**
+     * Save a single blob to the store.
+     * @param blob - The blob to save
+     * @param skipIfExists - Skip saving if blob already exists (default: true)
+     * @throws Error if the store is read-only
+     */
+    saveBlob(blob: Blob, skipIfExists?: boolean): Promise<void>;
+    /**
+     * Save multiple blobs to the store in parallel.
+     * @param blobs - The blobs to save
+     * @param skipIfExists - Skip saving if blob already exists (default: true)
+     */
+    saveBlobs(blobs: Blob[], skipIfExists?: boolean): Promise<void>;
+    /**
+     * Get the base URL/path of the filestore.
+     */
+    getBaseUrl(): string;
+    /**
+     * Test if the filestore connection is working by checking for healthcheck file.
+     * The healthcheck file is uploaded periodically by writable clients via HttpBlobClient.start().
+     * This provides a uniform connection test across all store types (S3/GCS/Local/HTTP).
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Upload the healthcheck file if it doesn't already exist.
+     * This enables read-only clients (HTTP) to verify connectivity.
+     */
+    uploadHealthcheck(): Promise<void>;
+    /**
+     * Check if the store supports write operations.
+     */
+    private isWritable;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmlsZXN0b3JlX2Jsb2JfY2xpZW50LmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZmlsZXN0b3JlL2ZpbGVzdG9yZV9ibG9iX2NsaWVudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsSUFBSSxFQUFFLEtBQUssUUFBUSxFQUErQixNQUFNLGlCQUFpQixDQUFDO0FBQ25GLE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQUs3RTs7O0dBR0c7QUFDSCxxQkFBYSxtQkFBbUI7SUFJNUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxLQUFLO0lBQ3RCLE9BQU8sQ0FBQyxRQUFRLENBQUMsUUFBUTtJQUozQixPQUFPLENBQUMsUUFBUSxDQUFDLEdBQUcsQ0FBUztJQUU3QixZQUNtQixLQUFLLEVBQUUsaUJBQWlCLEdBQUcsU0FBUyxFQUNwQyxRQUFRLEVBQUUsTUFBTSxFQUNqQyxNQUFNLENBQUMsRUFBRSxNQUFNLEVBR2hCO0lBRUQ7OztPQUdHO0lBQ0gsT0FBTyxDQUFDLFFBQVE7SUFJaEI7OztPQUdHO0lBQ0gsT0FBTyxDQUFDLGVBQWU7SUFJdkI7Ozs7T0FJRztJQUNHLGdCQUFnQixDQUFDLFVBQVUsRUFBRSxNQUFNLEVBQUUsR0FBRyxPQUFPLENBQUMsUUFBUSxFQUFFLENBQUMsQ0FtQmhFO0lBRUQ7OztPQUdHO0lBQ0gsTUFBTSxDQUFDLGlCQUFpQixFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDLENBRWxEO0lBRUQ7Ozs7O09BS0c7SUFDRyxRQUFRLENBQUMsSUFBSSxFQUFFLElBQUksRUFBRSxZQUFZLFVBQU8sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBa0I3RDtJQUVEOzs7O09BSUc7SUFDRyxTQUFTLENBQUMsS0FBSyxFQUFFLElBQUksRUFBRSxFQUFFLFlBQVksVUFBTyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFakU7SUFFRDs7T0FFRztJQUNILFVBQVUsSUFBSSxNQUFNLENBRW5CO0lBRUQ7Ozs7T0FJRztJQUNHLGNBQWMsSUFBSSxPQUFPLENBQUMsT0FBTyxDQUFDLENBT3ZDO0lBRUQ7OztPQUdHO0lBQ0csaUJBQWlCLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQVF2QztJQUVEOztPQUVHO0lBQ0gsT0FBTyxDQUFDLFVBQVU7Q0FHbkIifQ==

package/dest/filestore/filestore_blob_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filestore_blob_client.d.ts","sourceRoot":"","sources":["../../src/filestore/filestore_blob_client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,QAAQ,EAA+B,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAK7E;;;GAGG;AACH,qBAAa,mBAAmB;IAI5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YACmB,KAAK,EAAE,iBAAiB,GAAG,SAAS,EACpC,QAAQ,EAAE,MAAM,EACjC,MAAM,CAAC,EAAE,MAAM,EAGhB;IAED;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAIhB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;OAIG;IACG,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAmBhE;IAED;;;OAGG;IACH,MAAM,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAElD;IAED;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB7D;IAED;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,YAAY,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjE;IAED;;OAEG;IACH,UAAU,IAAI,MAAM,CAEnB;IAED;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAOvC;IAED;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvC;IAED;;OAEG;IACH,OAAO,CAAC,UAAU;CAGnB"}

package/dest/filestore/filestore_blob_client.js

@@ -0,0 +1,115 @@
+import { computeEthVersionedBlobHash } from '@aztec/blob-lib';
+import { createLogger } from '@aztec/foundation/log';
+import { inboundTransform, outboundTransform } from '../encoding/index.js';
+import { HEALTHCHECK_CONTENT, HEALTHCHECK_FILENAME } from './healthcheck.js';
+/**
+ * A blob client that uses a FileStore (S3/GCS/local) as the data source.
+ * Blobs are stored as JSON files keyed by their versioned blob hash.
+ */ export class FileStoreBlobClient {
+    store;
+    basePath;
+    log;
+    constructor(store, basePath, logger){
+        this.store = store;
+        this.basePath = basePath;
+        this.log = logger ?? createLogger('blob-client:filestore-client');
+    }
+    /**
+   * Get the path for a blob file.
+   * Format: basePath/blobs/{versionedBlobHash}.data
+   */ blobPath(versionedBlobHash) {
+        return `${this.basePath}/blobs/${versionedBlobHash}.data`;
+    }
+    /**
+   * Get the path for the healthcheck file.
+   * Format: basePath/.healthcheck
+   */ healthcheckPath() {
+        return `${this.basePath}/${HEALTHCHECK_FILENAME}`;
+    }
+    /**
+   * Fetch blobs by their versioned hashes.
+   * @param blobHashes - Array of versioned blob hashes (0x-prefixed hex strings)
+   * @returns Array of BlobJson objects for found blobs
+   */ async getBlobsByHashes(blobHashes) {
+        const blobs = [];
+        for(let i = 0; i < blobHashes.length; i++){
+            try {
+                const path = this.blobPath(blobHashes[i]);
+                if (!await this.store.exists(path)) {
+                    continue;
+                }
+                const data = await this.store.read(path);
+                const json = JSON.parse(inboundTransform(data).toString());
+                blobs.push(json);
+            } catch (err) {
+                this.log.warn(`Failed to read blob ${blobHashes[i]} from filestore`, err);
+            }
+        }
+        return blobs;
+    }
+    /**
+   * Check if a blob exists in the store.
+   * @param versionedBlobHash - The versioned blob hash (0x-prefixed hex string)
+   */ exists(versionedBlobHash) {
+        return this.store.exists(this.blobPath(versionedBlobHash));
+    }
+    /**
+   * Save a single blob to the store.
+   * @param blob - The blob to save
+   * @param skipIfExists - Skip saving if blob already exists (default: true)
+   * @throws Error if the store is read-only
+   */ async saveBlob(blob, skipIfExists = true) {
+        if (!this.isWritable()) {
+            throw new Error('FileStore is read-only');
+        }
+        const versionedHash = `0x${computeEthVersionedBlobHash(blob.commitment).toString('hex')}`;
+        if (skipIfExists && await this.store.exists(this.blobPath(versionedHash))) {
+            this.log.trace(`Blob ${versionedHash} already exists, skipping`);
+            return;
+        }
+        const json = blob.toJSON();
+        await this.store.save(this.blobPath(versionedHash), outboundTransform(Buffer.from(JSON.stringify(json))));
+        this.log.debug(`Saved blob ${versionedHash} to filestore`);
+    }
+    /**
+   * Save multiple blobs to the store in parallel.
+   * @param blobs - The blobs to save
+   * @param skipIfExists - Skip saving if blob already exists (default: true)
+   */ async saveBlobs(blobs, skipIfExists = true) {
+        await Promise.all(blobs.map((blob)=>this.saveBlob(blob, skipIfExists)));
+    }
+    /**
+   * Get the base URL/path of the filestore.
+   */ getBaseUrl() {
+        return this.basePath;
+    }
+    /**
+   * Test if the filestore connection is working by checking for healthcheck file.
+   * The healthcheck file is uploaded periodically by writable clients via HttpBlobClient.start().
+   * This provides a uniform connection test across all store types (S3/GCS/Local/HTTP).
+   */ async testConnection() {
+        try {
+            return await this.store.exists(this.healthcheckPath());
+        } catch (err) {
+            this.log.warn(`Connection test failed: ${err?.message ?? String(err)}`);
+            return false;
+        }
+    }
+    /**
+   * Upload the healthcheck file if it doesn't already exist.
+   * This enables read-only clients (HTTP) to verify connectivity.
+   */ async uploadHealthcheck() {
+        if (!this.isWritable()) {
+            this.log.trace('Cannot upload healthcheck: store is read-only');
+            return;
+        }
+        const path = this.healthcheckPath();
+        await this.store.save(path, Buffer.from(HEALTHCHECK_CONTENT));
+        this.log.debug(`Uploaded healthcheck file to ${path}`);
+    }
+    /**
+   * Check if the store supports write operations.
+   */ isWritable() {
+        return 'save' in this.store;
+    }
+}

package/dest/filestore/healthcheck.d.ts

@@ -0,0 +1,5 @@
+/** Constants for healthcheck file used to test file store connectivity. */
+export declare const HEALTHCHECK_FILENAME = ".healthcheck";
+export declare const HEALTHCHECK_CONTENT = "ok";
+export declare const DEFAULT_HEALTHCHECK_UPLOAD_INTERVAL_MINUTES = 60;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaGVhbHRoY2hlY2suZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9maWxlc3RvcmUvaGVhbHRoY2hlY2sudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsMkVBQTJFO0FBRTNFLGVBQU8sTUFBTSxvQkFBb0IsaUJBQWlCLENBQUM7QUFDbkQsZUFBTyxNQUFNLG1CQUFtQixPQUFPLENBQUM7QUFDeEMsZUFBTyxNQUFNLDJDQUEyQyxLQUFLLENBQUMifQ==

package/dest/filestore/healthcheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthcheck.d.ts","sourceRoot":"","sources":["../../src/filestore/healthcheck.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AACnD,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,2CAA2C,KAAK,CAAC"}

package/dest/filestore/healthcheck.js

@@ -0,0 +1,3 @@
+/** Constants for healthcheck file used to test file store connectivity. */ export const HEALTHCHECK_FILENAME = '.healthcheck';
+export const HEALTHCHECK_CONTENT = 'ok';
+export const DEFAULT_HEALTHCHECK_UPLOAD_INTERVAL_MINUTES = 60; // 1 hour

package/dest/filestore/index.d.ts

@@ -0,0 +1,3 @@
+export * from './filestore_blob_client.js';
+export * from './factory.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9maWxlc3RvcmUvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLGNBQWMsQ0FBQyJ9

package/dest/filestore/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/filestore/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,cAAc,CAAC"}

package/dest/filestore/index.js

@@ -0,0 +1,2 @@
+export * from './filestore_blob_client.js';
+export * from './factory.js';

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@aztec/blob-client",
+  "version": "0.0.1-commit.023c3e5",
+  "type": "module",
+  "bin": "./dest/client/bin/index.js",
+  "exports": {
+    "./client": "./dest/client/index.js",
+    "./client/config": "./dest/client/config.js",
+    "./encoding": "./dest/encoding/index.js",
+    "./filestore": "./dest/filestore/index.js"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "scripts": {
+    "build": "yarn clean && ../scripts/tsc.sh",
+    "build:dev": "../scripts/tsc.sh --watch",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ],
+    "testEnvironment": "../../foundation/src/jest/env.mjs",
+    "setupFilesAfterEnv": [
+      "../../foundation/src/jest/setupAfterEnv.mjs"
+    ]
+  },
+  "dependencies": {
+    "@aztec/blob-lib": "0.0.1-commit.023c3e5",
+    "@aztec/ethereum": "0.0.1-commit.023c3e5",
+    "@aztec/foundation": "0.0.1-commit.023c3e5",
+    "@aztec/kv-store": "0.0.1-commit.023c3e5",
+    "@aztec/stdlib": "0.0.1-commit.023c3e5",
+    "@aztec/telemetry-client": "0.0.1-commit.023c3e5",
+    "express": "^4.21.2",
+    "snappy": "^7.2.2",
+    "source-map-support": "^0.5.21",
+    "tslib": "^2.4.0",
+    "viem": "npm:@aztec/viem@2.38.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.15.17",
+    "@types/source-map-support": "^0.5.10",
+    "@types/supertest": "^6.0.2",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
+    "jest": "^30.0.0",
+    "jest-mock-extended": "^4.0.0",
+    "supertest": "^7.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "types": "./dest/index.d.ts",
+  "engines": {
+    "node": ">=20.10"
+  }
+}