@aztec/blob-client 0.0.1-commit.03f7ef2 → 0.0.1-commit.04d373f

package/src/client/interface.ts

@@ -6,11 +6,20 @@ import type { Blob } from '@aztec/blob-lib';
 export interface GetBlobSidecarOptions {
   /**
    * True if the archiver is catching up (historical sync), false if near tip.
-   * This affects source ordering:
-   * - Historical: FileStore first (data should exist), then L1 consensus, then archive (eg. blobscan)
-   * - Near tip: FileStore first with no retries (data should exist), L1 consensus second (freshest data), then FileStore with retries, then archive (eg. blobscan)
+   * Historical sync uses a shorter retry backoff since blobs should already exist.
    */
   isHistoricalSync?: boolean;
+  /**
+   * The parent beacon block root for the L1 block containing the blobs.
+   * If provided, skips the eth_getBlockByHash execution RPC call inside getSlotNumber.
+   */
+  parentBeaconBlockRoot?: string;
+  /**
+   * The timestamp of the L1 execution block containing the blobs.
+   * When provided alongside a cached beacon genesis config (fetched at startup), allows computing
+   * the beacon slot directly via timestamp math, skipping the beacon headers network call entirely.
+   */
+  l1BlockTimestamp?: bigint;
 }
 
 export interface BlobClientInterface {
@@ -18,6 +27,12 @@ export interface BlobClientInterface {
   sendBlobsToFilestore(blobs: Blob[]): Promise<boolean>;
   /** Fetches the given blob sidecars by block hash and blob hashes. */
   getBlobSidecar(blockId: string, blobHashes?: Buffer[], opts?: GetBlobSidecarOptions): Promise<Blob[]>;
+  /** Starts the blob client (e.g., uploads healthcheck file if not exists). */
+  start?(): Promise<void>;
   /** Tests all configured blob sources and logs whether they are reachable or not. */
   testSources(): Promise<void>;
+  /** Stops the blob client, clearing any periodic tasks. */
+  stop?(): void;
+  /** Returns true if this client can upload blobs to filestore. */
+  canUpload(): boolean;
 }

package/src/client/local.ts

@@ -22,4 +22,9 @@ export class LocalBlobClient implements BlobClientInterface {
   public getBlobSidecar(_blockId: string, blobHashes: Buffer[], _opts?: GetBlobSidecarOptions): Promise<Blob[]> {
     return this.blobStore.getBlobsByHashes(blobHashes);
   }
+
+  /** Returns true if this client can upload blobs. Always true for local client. */
+  public canUpload(): boolean {
+    return true;
+  }
 }

package/src/client/tests.ts

@@ -28,7 +28,7 @@ export function runBlobClientTests(
   });
 
   it('should send and retrieve blobs by hash', async () => {
-    const blob = makeRandomBlob(5);
+    const blob = await makeRandomBlob(5);
     const blobHash = blob.getEthVersionedBlobHash();
 
     await client.sendBlobsToFilestore([blob]);
@@ -39,7 +39,7 @@ export function runBlobClientTests(
   });
 
   it('should handle multiple blobs', async () => {
-    const blobs = Array.from({ length: 3 }, () => makeRandomBlob(7));
+    const blobs = await Promise.all(Array.from({ length: 3 }, () => makeRandomBlob(7)));
     const blobHashes = blobs.map(blob => blob.getEthVersionedBlobHash());
 
     await client.sendBlobsToFilestore(blobs);

package/src/filestore/factory.ts

@@ -1,6 +1,7 @@
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import {
   type FileStore,
+  type HttpFileStoreOptions,
   type ReadOnlyFileStore,
   createFileStore,
   createReadOnlyFileStore,
@@ -44,16 +45,19 @@ export async function createReadOnlyFileStoreBlobClient(
   storeUrl: string,
   metadata: BlobFileStoreMetadata,
   logger?: Logger,
+  httpOptions?: HttpFileStoreOptions,
 ): Promise<FileStoreBlobClient>;
 export async function createReadOnlyFileStoreBlobClient(
   storeUrl: string | undefined,
   metadata: BlobFileStoreMetadata,
   logger?: Logger,
+  httpOptions?: HttpFileStoreOptions,
 ): Promise<FileStoreBlobClient | undefined>;
 export async function createReadOnlyFileStoreBlobClient(
   storeUrl: string | undefined,
   metadata: BlobFileStoreMetadata,
   logger?: Logger,
+  httpOptions?: HttpFileStoreOptions,
 ): Promise<FileStoreBlobClient | undefined> {
   if (!storeUrl) {
     return undefined;
@@ -64,7 +68,7 @@ export async function createReadOnlyFileStoreBlobClient(
 
   log.debug(`Creating read-only filestore blob client`, { storeUrl, basePath });
 
-  const store: ReadOnlyFileStore = await createReadOnlyFileStore(storeUrl, log);
+  const store: ReadOnlyFileStore = await createReadOnlyFileStore(storeUrl, log, httpOptions);
   return new FileStoreBlobClient(store, basePath, log);
 }
 
@@ -80,6 +84,7 @@ export async function createReadOnlyFileStoreBlobClients(
   storeUrls: string[] | undefined,
   metadata: BlobFileStoreMetadata,
   logger?: Logger,
+  httpOptions?: HttpFileStoreOptions,
 ): Promise<FileStoreBlobClient[]> {
   if (!storeUrls || storeUrls.length === 0) {
     return [];
@@ -90,7 +95,7 @@ export async function createReadOnlyFileStoreBlobClients(
 
   for (const storeUrl of storeUrls) {
     try {
-      const client = await createReadOnlyFileStoreBlobClient(storeUrl, metadata, log);
+      const client = await createReadOnlyFileStoreBlobClient(storeUrl, metadata, log, httpOptions);
       if (client) {
         clients.push(client);
       }

package/src/filestore/filestore_blob_client.ts

@@ -3,6 +3,7 @@ import { type Logger, createLogger } from '@aztec/foundation/log';
 import type { FileStore, ReadOnlyFileStore } from '@aztec/stdlib/file-store';
 
 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.
@@ -27,6 +28,14 @@ export class FileStoreBlobClient {
     return `${this.basePath}/blobs/${versionedBlobHash}.data`;
   }
 
+  /**
+   * Get the path for the healthcheck file.
+   * Format: basePath/.healthcheck
+   */
+  private healthcheckPath(): string {
+    return `${this.basePath}/${HEALTHCHECK_FILENAME}`;
+  }
+
   /**
    * Fetch blobs by their versioned hashes.
    * @param blobHashes - Array of versioned blob hashes (0x-prefixed hex strings)
@@ -104,12 +113,31 @@ export class FileStoreBlobClient {
   }
 
   /**
-   * Test if the filestore connection is working.
+   * 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(): Promise<boolean> {
+    try {
+      return await this.store.exists(this.healthcheckPath());
+    } catch (err: any) {
+      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.
    */
-  testConnection(): Promise<boolean> {
-    // 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);
+  async uploadHealthcheck(): Promise<void> {
+    if (!this.isWritable()) {
+      this.log.trace('Cannot upload healthcheck: store is read-only');
+      return;
+    }
+    const path = this.healthcheckPath();
+    await (this.store as FileStore).save(path, Buffer.from(HEALTHCHECK_CONTENT));
+    this.log.debug(`Uploaded healthcheck file to ${path}`);
   }
 
   /**

package/src/filestore/healthcheck.ts

@@ -0,0 +1,5 @@
+/** 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