Use ethstorage-sdk to upload and download files

Introduction

In this tutorial, we will demonstrate how to upload and download files using the ethstorage-sdk tool.

The ethstorage-sdk provides APIs for file upload, download, and management.

In the following code examples, Sepolia is used by default. You can switch to other chains by specifying a different RPC endpoint, such as "https://rpc.delta.testnet.l2.quarkchain.io:8545" for the QuarkChain L2 testnet.

Step 1: Install ethstorage-sdk

You can install ethstorage-sdk by the following command:

 npm i ethstorage-sdk

Step 2: Manage Files

2.1 Create FlatDirectory

In this section, you will create a FlatDirectory contract for managing files.

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

const rpc = "https://rpc.sepolia.org";
// For QuarkChain L2 testnet:
// const rpc = "https://rpc.delta.testnet.l2.quarkchain.io:8545";
const privateKey = "0x...";

const flatDirectory = await FlatDirectory.create({
    rpc: rpc,
    privateKey: privateKey,
});
const contracAddress = await flatDirectory.deploy();
console.log(`FlatDirectory address: ${contracAddress}.`);
// FlatDirectory address: 0x37df32c7a3c30d352453dadacc838461d8629016

If you already have a FlatDirectory contract, you can set it.

const address = "0x37df32c7a3c30d352453dadacc838461d8629016"; // FlatDirectory address

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

2.2: Upload Files To FlatDirectory

In this section, you will upload some files into the FlatDirectory that you just created.

You can use Buffer to upload files.

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);

You can also upload File objects. This applies to both browser and Node.js environments.

Browser

// <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

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

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

const callback = {
    onProgress: function (progress, count, isChange) {
       ...
    },
    onFail: function (err) {
        ...
    },
    onFinish: function (totalUploadChunks, totalUploadSize, totalStorageCost) {
        ...
    }
};

2.3: Download Files From FlatDirectory

In this section, you will download files from the ethstorage network.

Standard SDK supports both uploading and downloading if created with ethStorageRpc. For read-only scenarios, you can create a download-only SDK instance without rpc or privateKey.

Note: Data may take a few seconds to sync after upload. You can wait a few seconds before downloading to ensure successful retrieval.

const ethStorageRpc = "https://rpc.testnet.ethstorage.io:9546"; // Sepolia
// For QuarkChain L2 testnet:
// const ethStorageRpc = "https://rpc.delta.testnet.l2.quarkchain.io:8545";

const key = "test.txt";

const callbackDownload = {
	onProgress: (progress, count, chunk) => {
		console.log(`Download progress: ${progress}% (${count} chunks)`);
	},
	onFail: (err) => {
		console.error("Download failed:", err);
	},
	onFinish: () => {
		console.log("Download finished (standard SDK).");
	}
};

// --- Option A: Standard SDK with ethStorageRpc ---
const flatDirectory = await FlatDirectory.create({
	rpc: rpc,
	ethStorageRpc: ethStorageRpc,
	privateKey: privateKey,
	address: address,
});

// Optional: only needed if downloading immediately after uploading
// await new Promise(resolve => setTimeout(resolve, 5000));

await flatDirectory.download(key, callbackDownload);


// --- Option B: Download-only SDK (read-only) ---
const downloadOnlySDK = await FlatDirectory.create({
	ethStorageRpc: ethStorageRpc,
	address: address,
});

await downloadOnlySDK.download(key, callbackDownload);

2.4: Close FlatDirectory SDK

After completing all uploading and downloading operations, you must call close() on your SDK instances to release internal Workers and threads. Failing to do so may prevent Node.js from exiting normally.

// Close the standard SDK instance (used for uploading and downloading)
await flatDirectory.close();
console.log("Standard SDK instance closed.");

// If you created a download-only SDK instance, make sure it is also closed
await downloadOnlySDK.close();
console.log("Download-only SDK instance closed.");

Step 3: Manage Blobs

3.1 Create EthStorage

In this section, you can create an EthStorage instance to interact directly with EthStorage for managing blobs.

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

const rpc = "https://rpc.sepolia.org";
const ethStorageRpc = "https://rpc.testnet.ethstorage.io:9546"; // Sepolia

const privateKey = "0x...";

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

3.2 Write Blob

Write blob data to the EthStorage network.

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

3.3 Read Blob

Read the written data from the EthStorage network.

const key = "test.txt";

// Optional: only needed if downloading immediately after uploading
// await new Promise(resolve => setTimeout(resolve, 5000));

const data = await ethStorage.read(key);

3.4: Close EthStorage SDK

After completing all uploading and downloading operations with EthStorage, you must call close() on your SDK instances to release internal Workers and threads. Failing to do so may prevent Node.js from exiting normally.

await ethStorage.close();
console.log("SDK instance closed.");