@aztec/blob-client 3.0.0-nightly.20251223

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@aztec/blob-client",
+  "version": "3.0.0-nightly.20251223",
+  "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",
+    "./types": "./dest/types/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": "3.0.0-nightly.20251223",
+    "@aztec/ethereum": "3.0.0-nightly.20251223",
+    "@aztec/foundation": "3.0.0-nightly.20251223",
+    "@aztec/kv-store": "3.0.0-nightly.20251223",
+    "@aztec/stdlib": "3.0.0-nightly.20251223",
+    "@aztec/telemetry-client": "3.0.0-nightly.20251223",
+    "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,178 @@
+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(), // This is the index within the tx, not within the block!
+            }),
+          ),
+        }),
+      ),
+    })
+    .transform(data =>
+      data.transactions
+        .flatMap(tx =>
+          tx.blobs.map(blob => ({
+            blob: blob.data,
+            // eslint-disable-next-line camelcase
+            kzg_commitment: blob.commitment,
+          })),
+        )
+        .map((blob, index) => ({ ...blob, index: index.toString() })),
+    ),
+);
+
+// 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']),
+};

package/src/archive/factory.ts

@@ -0,0 +1,11 @@
+import type { BlobClientConfig } from '../client/config.js';
+import { BlobscanArchiveClient } from './blobscan_archive_client.js';
+import type { BlobArchiveClient } from './interface.js';
+
+export function createBlobArchiveClient(config: BlobClientConfig): BlobArchiveClient | undefined {
+  if (config.archiveApiUrl) {
+    return new BlobscanArchiveClient(config.archiveApiUrl);
+  }
+
+  return undefined;
+}