@aztec/blob-client 0.0.1-commit.03f7ef2

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,55 @@
+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;
+    /**
+     * 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.
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Check if the store supports write operations.
+     */
+    private isWritable;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmlsZXN0b3JlX2Jsb2JfY2xpZW50LmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZmlsZXN0b3JlL2ZpbGVzdG9yZV9ibG9iX2NsaWVudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsSUFBSSxFQUFFLEtBQUssUUFBUSxFQUErQixNQUFNLGlCQUFpQixDQUFDO0FBQ25GLE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRSxPQUFPLEtBQUssRUFBRSxTQUFTLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQztBQUk3RTs7O0dBR0c7QUFDSCxxQkFBYSxtQkFBbUI7SUFJNUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxLQUFLO0lBQ3RCLE9BQU8sQ0FBQyxRQUFRLENBQUMsUUFBUTtJQUozQixPQUFPLENBQUMsUUFBUSxDQUFDLEdBQUcsQ0FBUztJQUU3QixZQUNtQixLQUFLLEVBQUUsaUJBQWlCLEdBQUcsU0FBUyxFQUNwQyxRQUFRLEVBQUUsTUFBTSxFQUNqQyxNQUFNLENBQUMsRUFBRSxNQUFNLEVBR2hCO0lBRUQ7OztPQUdHO0lBQ0gsT0FBTyxDQUFDLFFBQVE7SUFJaEI7Ozs7T0FJRztJQUNHLGdCQUFnQixDQUFDLFVBQVUsRUFBRSxNQUFNLEVBQUUsR0FBRyxPQUFPLENBQUMsUUFBUSxFQUFFLENBQUMsQ0FtQmhFO0lBRUQ7OztPQUdHO0lBQ0gsTUFBTSxDQUFDLGlCQUFpQixFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDLENBRWxEO0lBRUQ7Ozs7O09BS0c7SUFDRyxRQUFRLENBQUMsSUFBSSxFQUFFLElBQUksRUFBRSxZQUFZLFVBQU8sR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLENBa0I3RDtJQUVEOzs7O09BSUc7SUFDRyxTQUFTLENBQUMsS0FBSyxFQUFFLElBQUksRUFBRSxFQUFFLFlBQVksVUFBTyxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FFakU7SUFFRDs7T0FFRztJQUNILFVBQVUsSUFBSSxNQUFNLENBRW5CO0lBRUQ7O09BRUc7SUFDSCxjQUFjLElBQUksT0FBTyxDQUFDLE9BQU8sQ0FBQyxDQUlqQztJQUVEOztPQUVHO0lBQ0gsT0FBTyxDQUFDLFVBQVU7Q0FHbkIifQ==

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;AAI7E;;;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;;;;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;;OAEG;IACH,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAIjC;IAED;;OAEG;IACH,OAAO,CAAC,UAAU;CAGnB"}

package/dest/filestore/filestore_blob_client.js

@@ -0,0 +1,91 @@
+import { computeEthVersionedBlobHash } from '@aztec/blob-lib';
+import { createLogger } from '@aztec/foundation/log';
+import { inboundTransform, outboundTransform } from '../encoding/index.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`;
+    }
+    /**
+   * 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.
+   */ testConnection() {
+        // This implementation will be improved in a separate PR
+        // Currently underlying filestore implementations do not expose an easy way to test connectivitiy
+        return Promise.resolve(true);
+    }
+    /**
+   * Check if the store supports write operations.
+   */ isWritable() {
+        return 'save' in this.store;
+    }
+}

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.03f7ef2",
+  "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.03f7ef2",
+    "@aztec/ethereum": "0.0.1-commit.03f7ef2",
+    "@aztec/foundation": "0.0.1-commit.03f7ef2",
+    "@aztec/kv-store": "0.0.1-commit.03f7ef2",
+    "@aztec/stdlib": "0.0.1-commit.03f7ef2",
+    "@aztec/telemetry-client": "0.0.1-commit.03f7ef2",
+    "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.20251126.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"
+  }
+}

package/src/archive/blobscan_archive_client.ts

@@ -0,0 +1,176 @@
+import type { BlobJson } from '@aztec/blob-lib/types';
+import { createLogger } from '@aztec/foundation/log';
+import { makeBackoff, retry } from '@aztec/foundation/retry';
+import { schemas, zodFor } from '@aztec/foundation/schemas';
+import { type TelemetryClient, getTelemetryClient } from '@aztec/telemetry-client';
+
+import { z } from 'zod';
+
+import { BlobArchiveClientInstrumentation } from './instrumentation.js';
+import type { BlobArchiveClient } from './interface.js';
+
+export const BlobscanBlockResponseSchema = zodFor<BlobJson[]>()(
+  z
+    .object({
+      hash: z.string(),
+      slot: z.number().int(),
+      number: z.number().int(),
+      transactions: z.array(
+        z.object({
+          hash: z.string(),
+          blobs: z.array(
+            z.object({
+              versionedHash: z.string(),
+              data: z.string(),
+              commitment: z.string(),
+              proof: z.string(),
+              size: z.number().int(),
+              index: z.number().int().optional(), // Unused, kept for schema compatibility with blobscan API
+            }),
+          ),
+        }),
+      ),
+    })
+    .transform(data =>
+      data.transactions.flatMap(tx =>
+        tx.blobs.map(blob => ({
+          blob: blob.data,
+          // eslint-disable-next-line camelcase
+          kzg_commitment: blob.commitment,
+        })),
+      ),
+    ),
+);
+
+// Response from https://api.blobscan.com/blocks?sort=desc&type=canonical
+export const BlobscanBlocksResponseSchema = z.object({
+  blocks: z.array(
+    z.object({
+      hash: z.string(),
+      slot: z.number().int(),
+      number: z.number().int(),
+    }),
+  ),
+});
+
+export class BlobscanArchiveClient implements BlobArchiveClient {
+  private readonly logger = createLogger('blob-client:blobscan-archive-client');
+  private readonly fetchOpts = { headers: { accept: 'application/json' } };
+  private readonly fetch = async (...args: Parameters<typeof fetch>): Promise<Response> => {
+    return await retry(
+      () => fetch(...args),
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
+      `Fetching ${args[0]}`,
+      makeBackoff([1, 1, 3]),
+      this.logger,
+      /*failSilently=*/ false,
+    );
+  };
+
+  private readonly baseUrl: URL;
+
+  private instrumentation: BlobArchiveClientInstrumentation;
+
+  constructor(baseUrl: string, telemetry: TelemetryClient = getTelemetryClient()) {
+    this.baseUrl = new URL(baseUrl);
+    if (this.baseUrl.protocol !== 'https:') {
+      throw new TypeError('BaseURL must be secure: ' + baseUrl);
+    }
+    this.instrumentation = new BlobArchiveClientInstrumentation(
+      telemetry,
+      this.baseUrl.origin,
+      'BlobscanArchiveClient',
+    );
+  }
+
+  public async getLatestBlock(): Promise<{ hash: string; number: number; slot: number }> {
+    const url = new URL('blocks', this.baseUrl);
+    url.searchParams.set('sort', 'desc');
+    url.searchParams.set('type', 'canonical');
+    url.searchParams.set('p', '1');
+    url.searchParams.set('ps', '1');
+
+    this.logger.trace(`Fetching latest block from ${url.href}`);
+    const response = await this.fetch(url, this.fetchOpts);
+
+    if (response.status !== 200) {
+      throw new Error(`Failed to fetch latest block: ${response.statusText} (${response.status})`, {
+        cause: {
+          httpResponse: {
+            status: response.status,
+            body: await response.text().catch(() => 'Failed to read response body'),
+          },
+        },
+      });
+    }
+
+    const parsed = await response.json().then((data: any) => BlobscanBlocksResponseSchema.parse(data));
+    if (parsed.blocks.length === 0) {
+      throw new Error(`No blocks found at ${this.baseUrl}`);
+    }
+
+    return parsed.blocks[0];
+  }
+
+  public getBaseUrl(): string {
+    return this.baseUrl.href;
+  }
+
+  public async getBlobsFromBlock(blockId: string): Promise<BlobJson[] | undefined> {
+    const url = new URL(`blocks/${blockId}`, this.baseUrl);
+    url.searchParams.set('type', 'canonical');
+    url.searchParams.set('expand', 'blob,blob_data');
+
+    this.logger.trace(`Fetching blobs for block ${blockId} from ${url.href}`);
+    const response = await this.fetch(url, this.fetchOpts);
+
+    this.instrumentation.incRequest('blocks', response.status);
+
+    if (response.status === 404) {
+      this.logger.debug(`No blobs found for block ${blockId} at ${this.baseUrl}`);
+      return undefined;
+    } else if (response.status !== 200) {
+      throw new Error(`Failed to fetch blobs for block ${blockId}: ${response.statusText} (${response.status})`, {
+        cause: {
+          httpResponse: {
+            status: response.status,
+            body: await response.text().catch(() => 'Failed to read response body'),
+          },
+        },
+      });
+    } else {
+      const result = await response.json().then((data: any) => BlobscanBlockResponseSchema.parse(data));
+      this.logger.debug(`Fetched ${result.length} blobs for block ${blockId} from ${this.baseUrl}`);
+      this.instrumentation.incRetrievedBlobs(result.length);
+      return result;
+    }
+  }
+
+  public async getBlobData(id: string): Promise<Buffer | undefined> {
+    const url = new URL(`blobs/${id}/data`, this.baseUrl);
+
+    const response = await this.fetch(url, this.fetchOpts);
+    this.instrumentation.incRequest('blobs', response.status);
+    if (response.status === 404) {
+      return undefined;
+    } else if (response.status !== 200) {
+      throw new Error(`Failed to fetch blob data for blob ${id}: ${response.statusText} (${response.status})`, {
+        cause: {
+          httpResponse: {
+            status: response.status,
+            body: await response.text().catch(err => {
+              this.logger.warn('Failed to read response body', err);
+              return '';
+            }),
+          },
+        },
+      });
+    } else {
+      return await response.json().then((data: any) => {
+        const blob = schemas.BufferHex.parse(data);
+        this.instrumentation.incRetrievedBlobs(1);
+        return blob;
+      });
+    }
+  }
+}

package/src/archive/config.ts

@@ -0,0 +1,14 @@
+import { type L1ReaderConfig, l1ReaderConfigMappings } from '@aztec/ethereum/l1-reader';
+import { type ConfigMappingsType, pickConfigMappings } from '@aztec/foundation/config';
+
+export type BlobArchiveApiConfig = {
+  archiveApiUrl?: string;
+} & Partial<Pick<L1ReaderConfig, 'l1ChainId'>>;
+
+export const blobArchiveApiConfigMappings: ConfigMappingsType<BlobArchiveApiConfig> = {
+  archiveApiUrl: {
+    env: 'BLOB_SINK_ARCHIVE_API_URL',
+    description: 'The URL of the archive API',
+  },
+  ...pickConfigMappings(l1ReaderConfigMappings, ['l1ChainId']),
+};