# ethstorage-sdk

> eip-4844 blobs upload sdk

Latest version **4.2.4** (published 2025-12-25) · ISC license · 0 weekly downloads

## Install

```sh
npm install ethstorage-sdk
pnpm add ethstorage-sdk
yarn add ethstorage-sdk
bun add ethstorage-sdk
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.2.4 |
| Published | 2025-12-25 |
| First published | 2023-12-27 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 446.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | ethsorage |
| Maintainers | web3q |
| Keywords | EIP4844, eip-4844, Blobs, File, Upload |

## Links

- npm: https://www.npmjs.com/package/ethstorage-sdk
- Repository: https://github.com/ethstorage/ethstorage-sdk
- Homepage: https://github.com/ethstorage/ethstorage-sdk/main/
- Issues: https://github.com/ethstorage/ethstorage-sdk/issues
- npm.io page: https://npm.io/package/ethstorage-sdk

## Dependencies (6)

- [rxjs](https://npm.io/package/rxjs.md) ^7.8.2
- [dotenv](https://npm.io/package/dotenv.md) ^16.4.5
- [ethers](https://npm.io/package/ethers.md) ^6.16.0
- [js-kzg](https://npm.io/package/js-kzg.md) ^2.0.2
- [p-limit](https://npm.io/package/p-limit.md) ^7.2.0
- [async-mutex](https://npm.io/package/async-mutex.md) ^0.5.0

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 4.2.4 (latest) — 2025-12-25
- 4.2.3 — 2025-12-25
- 4.2.2 — 2025-12-23
- 4.1.7 — 2025-11-18
- 4.1.6 — 2025-11-11
- 4.1.5 — 2025-11-06
- 4.1.4 — 2025-10-22
- 4.1.3 — 2025-09-19
- 4.1.2 — 2025-09-17
- 4.1.1 — 2025-09-12
- 4.1.0 — 2025-09-11
- 4.0.2 — 2025-09-10
- 4.0.1 — 2025-09-03
- 4.0.0 — 2025-09-03
- 3.1.1 — 2025-04-30
- … 45 more at https://npm.io/package/ethstorage-sdk/versions

## README

# ethstorage-sdk

This SDK aims to standardize the interaction between applications and the EthStorage network to achieve reliable and
efficient data management functionality.

This SDK includes two classes: `EthStorage` and `FlatDirectory`.
The `EthStorage` class provides asynchronous read and write operations for key-value pairs of a specified size.
The `FlatDirectory` class is a higher-level data management tool that provides methods for uploading and downloading
data of arbitrary size.

Click here to view [spec](https://github.com/ethstorage/ethstorage-sdk/blob/main/spec.md).

# Installation

Install the SDK using [npm](https://www.npmjs.com/package/ethstorage-sdk):

```bash
$ npm install ethstorage-sdk
```

# Example Usage

## EthStorage

### create

Create an `EthStorage` instance.

```js
const { EthStorage } = require("ethstorage-sdk");

const rpc = "https://rpc.beta.testnet.l2.quarkchain.io:8545";
const ethStorageRpc = "https://rpc.beta.testnet.l2.ethstorage.io:9596";
const privateKey = "0xabcd...";

const ethStorage = await EthStorage.create({
    rpc: rpc,
    ethStorageRpc: ethStorageRpc,
    privateKey: privateKey,
});
```

If you only need the `read` function, you can create an `EthStorage` using the following pattern.

```js
const flatDirectory = await EthStorage.create({
    rpc: 'https://rpc.beta.testnet.l2.quarkchain.io:8545',
    ethStorageRpc: 'https://rpc.beta.testnet.l2.ethstorage.io:9596'
});
```


### write

Write blob data to the EthStorage network.

```js
const key = "test.txt";
const data = Buffer.from("test data");
await ethStorage.write(key, data);
```

### read

Read written data from the EthStorage network.

```js
const key = "test.txt";
const data = await ethStorage.read(key);
```

If it is in read-only mode.

```js
const key = "test.txt";
const walletAddress = "0xaaa...";
const data = await ethStorage.read(key, DecodeType.OptimismCompact, walletAddress);
```


### writeBlobs

Batch upload blob data.

```js
const keys = ["key1", "key2"];
const dataBlobs = [Buffer.from("some data"), Buffer.from("test data")];
const result = await ethStorage.writeBlobs(keys, dataBlobs);
```

### estimateCost

Estimate gas costs before uploading.

```js
const key = "example1.txt";
const data = Buffer.from("large data to upload");

const cost = await ethStorage.estimateCost(key, data);
console.log(`Gas Cost: ${cost.gasCost}, Storage Cost: ${cost.storageCost}`);
```

### close

Call the `close` function after completing the operation to properly release resources.

```javascript
const es = await EthStorage.create({
    rpc: rpc,
    ethStorageRpc: ethStorageRpc,
    privateKey: privateKey,
});

// Use EthStorage
await es.methodName();  // methodName() is just an example, replace it with the actual API method

// Close when done
await es.close();
```

## FlatDirectory

### create

Create a `FlatDirectory` instance.

```js
const { FlatDirectory } = require("ethstorage-sdk");

const rpc = "https://rpc.beta.testnet.l2.quarkchain.io:8545";
const ethStorageRpc = "https://rpc.beta.testnet.l2.ethstorage.io:9596";
const privateKey = "0xabcd...";

const flatDirectory = await FlatDirectory.create({
    rpc: rpc,
    ethStorageRpc: ethStorageRpc,
    privateKey: privateKey,
});
```

If `FlatDirectory` has been deployed, it can be set through the `address` field.

```js
const address = "0x987..."; // FlatDirectory address
const flatDirectory = await FlatDirectory.create({
    rpc: rpc,
    ethStorageRpc: ethStorageRpc,
    privateKey: privateKey,
    address: address,
});
```

If you only need the `download` function, you can create a `FlatDirectory` using the following pattern.

```js
const address = "0x987..."; // FlatDirectory address
const flatDirectory = await FlatDirectory.create({
    ethStorageRpc: 'https://rpc.beta.testnet.l2.ethstorage.io:9596',
    address: address
});
```

### deploy

Deploy the implementation
contract [FlatDirectory](https://github.com/ethstorage/evm-large-storage/blob/master/contracts/FlatDirectory.sol)
for [EIP-5018](https://eips.ethereum.org/EIPS/eip-5018) standard.

```js
const contractAddress = await flatDirectory.deploy();
console.log(`FlatDirectory address is ${contractAddress}.`);
```

### upload

Upload `buffer | file` to the FlatDirectory.

```js
const callback = {
    onProgress: function (progress, count, isChange) {
        console.log(`Uploaded ${progress} of ${count} chunks`);
    },
    onFail: function (err) {
        console.log(err);
    },
    onFinish: function (totalUploadChunks, totalUploadSize, totalCost) {
        console.log(`Total upload chunk count is ${totalUploadChunks}, size is ${totalUploadSize}, total cost is ${totalCost}`);
    }
};

const request = {
    key: "test.txt",
    content: Buffer.from("big data"),
    type: 2, // 1 for calldata and 2 for blob
    callback: callback
}
await flatDirectory.upload(request);
```

If you want to use `file`, it can be divided into browser and Node.js.

Browser
```javascript
// <input id='fileToUpload' />
const file = document.getElementById('fileToUpload').files[0];

const request = {
    key: "test.txt",
    content: file,
    type: 2,
    callback: callback
}
await flatDirectory.upload(request);
```

Node.js
```javascript
const {NodeFile} = require("ethstorage-sdk/file");
const file = new NodeFile("/usr/download/test.jpg");

const request = {
    key: "test.txt",
    content: file,
    type: 2,
    callback: callback
}
await flatDirectory.upload(request);
```

### download

Monitor the download progress by passing in a callback function.

```js
const key = "test.txt";
await flatDirectory.download(key, {
	onProgress: function (progress, count, chunk) {
		console.log(`Download ${progress} of ${count} chunks, this chunk is ${Buffer.from(chunk).toString()}`);
	},
    onFail: function (error) {
        console.error("Error download data:", error);
    },
    onFinish: function () {
        console.log("Download success.");
    }
});
```

### estimateCost

Estimate gas costs before uploading.

```js
const request = {
    key: "example1.txt",
    content: Buffer.from("large data to upload"),
    type: 2 // 1 for calldata and 2 for blob
}

const cost = await flatDirectory.estimateCost(request);
console.log(`Gas Cost: ${cost.gasCost}, Storage Cost: ${cost.storageCost}`);
```

Use `file`.

Browser
```javascript
// <input id='fileToUpload' />
const file = document.getElementById('fileToUpload').files[0];

const request = {
    key: "example1.txt",
    content: file,
    type: 2
}
const cost = await flatDirectory.estimateCost(request);
console.log(`Gas Cost: ${cost.gasCost}, Storage Cost: ${cost.storageCost}`);
```

Node.js
```javascript
const {NodeFile} = require("ethstorage-sdk/file");
const file = new NodeFile("/usr/download/test.jpg");

const request = {
    key: "example1.txt",
    content: file,
    type: 2
}
const cost = await flatDirectory.estimateCost(request);
```


### close

Call the `close` function after completing the operation to properly release resources.

```javascript
const flatDirectory = await FlatDirectory.create({
    rpc: rpc,
    ethStorageRpc: ethStorageRpc,
    privateKey: privateKey,
    address: address,
});

// Use flatDirectory
await flatDirectory.methodName();  // methodName() is just an example, replace it with the actual API method

// Close when done
await flatDirectory.close();
```

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