# @aztec/blob-client

> A client library for storing and retrieving blob data from various sources.

Latest version **5.2.0** (published 2026-08-17) · 4.3K weekly downloads

## Install

```sh
npm install @aztec/blob-client
pnpm add @aztec/blob-client
yarn add @aztec/blob-client
bun add @aztec/blob-client
```

Provides the command `blob-client`.

## Health

**Score 80/100 (A)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

## Facts

| | |
|---|---|
| Version | 5.2.0 |
| Published | 2026-08-17 |
| First published | 2025-12-23 |
| Weekly downloads | 4.3K |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20.10 |
| Dependencies | 12 |
| Unpacked size | 962.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | zac-williamson, leilawang, charlielye, jaosef, joss-aztecprotocol, ludamad |

## Links

- npm: https://www.npmjs.com/package/@aztec/blob-client
- npm.io page: https://npm.io/package/@aztec/blob-client

## Dependencies (12)

- [zod](https://npm.io/package/zod.md) ^4
- [viem](https://npm.io/package/viem.md) npm:@aztec/viem@2.38.2
- [tslib](https://npm.io/package/tslib.md) ^2.4.0
- [snappy](https://npm.io/package/snappy.md) 7.2.2
- [express](https://npm.io/package/express.md) ^4.21.2
- [@aztec/stdlib](https://npm.io/package/@aztec/stdlib.md) 5.2.0
- [@aztec/blob-lib](https://npm.io/package/@aztec/blob-lib.md) 5.2.0
- [@aztec/ethereum](https://npm.io/package/@aztec/ethereum.md) 5.2.0
- [@aztec/kv-store](https://npm.io/package/@aztec/kv-store.md) 5.2.0
- [@aztec/foundation](https://npm.io/package/@aztec/foundation.md) 5.2.0
- [source-map-support](https://npm.io/package/source-map-support.md) ^0.5.21
- [@aztec/telemetry-client](https://npm.io/package/@aztec/telemetry-client.md) 5.2.0

## Recent versions

- 5.2.0 (latest) — 2026-08-17
- 5.3.0-nightly.20260919 (prerelease) — 2026-09-19
- 0.0.1-dev (dev) — 2026-06-26
- 4.4.0-nightly.20260618 (nightly) — 2026-06-18
- 4.3.0-rc.1 (rc) — 2026-05-15
- 0.0.1-commit.fff30aa (commit) — 2026-04-17
- 4.0.0-devnet.4-patch.0 (devnet) — 2026-04-06
- 4.2.0-aztecnr-rc.2 (aztecnr-rc) — 2026-03-26
- 5.0.0-private.20260319 (private) — 2026-03-19
- 5.0.0-patched.20260318 (patched) — 2026-03-18
- 4.0.0-spartan.20260218 (spartan) — 2026-02-18
- 5.3.0-nightly.20260918.a — 2026-09-18
- 5.3.0-nightly.20260918 — 2026-09-18
- 5.3.0-nightly.20260917 — 2026-09-17
- 5.3.0-nightly.20260916 — 2026-09-16
- … 659 more at https://npm.io/package/@aztec/blob-client/versions

## README

## Blob Client

A client library for storing and retrieving blob data from various sources.

## When is this used?

The blob client is used by nodes to store and retrieve blob data that accompanies `propose` transactions on L1.

### Why?

Blob data is only available in the L1 consensus layer for a limited period (~3 weeks). The blob client provides a unified interface for:
- Fetching blobs from L1 consensus layer (beacon nodes)
- Storing/retrieving blobs from file stores (local files, S3, GCS)
- Caching blobs locally for faster access

### How?

The blob client supports multiple blob sources:
1. **File Store**: Local filesystem (`file://`), S3 (`s3://`), or GCS (`gs://`)
2. **L1 Consensus**: Beacon node API for recent blobs
3. **Archive**: Blobscan API for historical blobs

### Configurations

**File Store URLs** (`BLOB_FILE_STORE_URLS`):
Comma-separated list of URLs to read blobs from. Tried in order until blobs are found.

**File Store Upload URL** (`BLOB_FILE_STORE_UPLOAD_URL`):
URL for uploading blobs to a file store.

**L1 Consensus Host URLs** (`L1_CONSENSUS_HOST_URLS`):
Beacon node URLs for fetching recent blobs directly from L1.

**Archive API URL** (`BLOB_ARCHIVE_API_URL`):
Blobscan or similar archive API for historical blob data.

### File Store Connectivity Testing

All file stores (S3, GCS, HTTP, local) test connectivity by checking if a well-known healthcheck file (`.healthcheck`) exists. This approach was chosen because:

1. **HTTP compatibility**: For HTTP-based file stores, requesting a known file is the only reliable way to verify connectivity
2. **Uniform behavior**: Using the same healthcheck mechanism across all store types ensures consistent behavior and simplifies testing

When uploading is enabled, the sequencer uploads the healthcheck file on startup and then periodically re-uploads it (by default every 60 minutes) to ensure it remains available. This guards against accidental deletion, storage pruning, or other failures that might remove the file.

### Example Usage

```typescript
import { createBlobClient, createBlobClientWithFileStores } from '@aztec/blob-client/client';

// Simple client with L1 consensus and archive sources
const client = createBlobClient({
  l1ConsensusHostUrls: ['https://beacon.example.com'],
  archiveApiUrl: 'https://api.blobscan.com',
});

// Client with file store support
const clientWithFileStore = await createBlobClientWithFileStores({
  l1ChainId: 1,
  rollupVersion: 1,
  l1Contracts: { rollupAddress: { toString: () => '0x...' } },
  blobFileStoreUrls: ['s3://bucket/blobs', 'file:///local/blobs'],
  blobFileStoreUploadUrl: 's3://bucket/blobs',
});

// Fetch blobs
const blobs = await client.getBlobSidecar(blockHash, blobHashes);

// Upload blobs to file store
await client.sendBlobsToFilestore(blobs);
```

---
_Source: https://npm.io/package/@aztec/blob-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._