Upload your file/folder with ethfs-cli

Introduction

In this tutorial, we will demonstrate how to use the ethfs-cli tool to upload files or folders to EVM-compatible chains such as Super World Computer beta testnet or Sepolia.

You can find the full list of currently supported chains here.

For the content to be uploaded, let's assume that

• there is a folder to be uploaded; (e.g., dist)

• there are two files in the folder. (e.g., hello.txt and img/1.jpeg)

Step 1: Install ethfs-cli

If you have not already done so, you can install ethfs-cli using the following command:

npm i -g ethfs-cli

If you installed it a long time ago, please run the same command to update to the latest version.

Step 2: Create a FlatDirectory Contract

A FlatDirectory contract serves as a container that needs to be created before uploading files.

Command Syntax

ethfs-cli create -p <private-key> -c <chain-id>

This command creates a FlatDirectory on a specified blockchain. You need to provide a private key and the chain ID.

If the part -c <chain-id> is omitted, Ethereum Mainnet will be specified by default.

Example: SWC Beta

ethfs-cli create -p 0x112233... -c 3335

You will get a FlatDirectory address after the transaction is confirmed on SWC beta testnet:

FlatDirectory: Address is 0xab351F35B82B20C1a253ae16523c5E2D60B56D6E

Example: Sepolia

ethfs-cli create -p 0x112233... -c 11155111

You will get a FlatDirectory address after the transaction is confirmed on Sepolia:

FlatDirectory: Address is 0x2f7696D4284358A2E8fDb4DF772dAd60c2c8fbAd

Step 3: Upload Files

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

Command Syntax

ethfs-cli upload \
    -f <directory|file> \
    -a <address> \
    -c <chain-id> \
    -p <private-key> \
    -t <upload-type>

You need to provide the contract address (-a <address>), chain ID (-c <chain-id>), private key (-p <private-key>), and the type of upload (-t <upload-type>).

Notice that you have 2 options to specify the file upload type: calldata, blob. The default type is blob which requires network support for EIP-4844.

If the part -c <chain-id> is omitted, Ethereum Mainnet will be specified by default.

Example: SWC Beta

ethfs-cli upload -f dist -a 0xab351F35B82B20C1a253ae16523c5E2D60B56D6E -c 3335 -p 0x112233...

Example log:

providerUrl = https://rpc.beta.testnet.l2.quarkchain.io:8545
chainId = 3335
address = 0xab351F35B82B20C1a253ae16523c5E2D60B56D6E 
threadPoolSize = 15 

FlatDirectory: The transaction hash for chunk 0 is 0x2526108470cb100837ac1a724df91c9ba3d1422fb2e45fec458cc3f566d5f210  hello.txt
FlatDirectory: Chunks 0 have been uploaded  hello.txt
FlatDirectory: The transaction hash for chunks 0,1,2 is 0xfec795480524f81964e62251e8ac7d0f0dc9ed8422bc96a300254377043d3721  img/1.jpeg
FlatDirectory: Chunks 0,1,2 have been uploaded  img/1.jpeg

Total File Count: 2
Total Upload Chunk Count: 4
Total Upload Data Size: 324.1015625 KB
Total Storage Cost: 2.259012840557991428 ETH

Example: Sepolia

ethfs-cli upload -f dist -a 0x2f7696D4284358A2E8fDb4DF772dAd60c2c8fbAd -c 11155111 -p 0x112233... -t blob

Example log:

providerUrl = https://rpc.sepolia.org
chainId = 11155111
address: 0x2f7696D4284358A2E8fDb4DF772dAd60c2c8fbAd


FlatDirectory: The transaction hash for chunk 0 is 0x809411aeb708023a33dadf17791d994dc3b4b2db1a6bbd36792bbedb68646978 img/1.jpeg
FlatDirectory: Chunks 0 have been uploaded hello.txt
FlatDirectory: The transaction hash for chunk 0 is 0x7cea7ea7e4898e03bee4fbc031799689dbe215bd6dd36733721150a099680be7 hello.txt
FlatDirectory: Chunks 0 have been uploaded img/1.jpeg

Total File Count: 2
Total Upload Chunk Count: 2
Total Upload Data size: 52.6513671875 KB
Total Storage Cost: 0.001492087764775451 ETH

Step 4: Download Your File!

Now you should be able to download the file you just uploaded.

Command Syntax

ethfs-cli download -a <address> -c <chain-id> -f <file>

Example: SWC Beta

ethfs-cli download -a 0xab351F35B82B20C1a253ae16523c5E2D60B56D6E -c 3335 -f img/1.jpeg

Example: Sepolia

ethfs-cli download -a 0x2f7696D4284358A2E8fDb4DF772dAd60c2c8fbAd -c 11155111 -f img/1.jpeg

Now, your file has been saved locally.

Step 5: Access Your File via web3://

Of course, you can also easily access the file you just uploaded using the web3:// protocol.

Example: SWC Beta

text: web3://0xab351F35B82B20C1a253ae16523c5E2D60B56D6E:3337/hello.txt

image: web3://0xab351F35B82B20C1a253ae16523c5E2D60B56D6E:3337/img/1.jpeg

Example: Sepolia

text: web3://0x2f7696D4284358A2E8fDb4DF772dAd60c2c8fbAd:3333/hello.txt

image: web3://0x2f7696D4284358A2E8fDb4DF772dAd60c2c8fbAd:3333/img/1.jpeg

Note: In the above URLs, you may need to specify a different chain ID than the one used in the ethfs-cli commands. This distinct chain ID is necessary for identifying the EthStorage network responsible for storing the files.

To gain further insights into web3:// protocol, you can visit web3url.io.

Optional: Using Your Own RPC Endpoint

You can also specify your own RPC for better performance by -r flag in the above steps.

For example when create FlatDirectory contract:

ethfs-cli create -p 0x112233... -c 11155111 -r http://...rpc.io

When uploading files:

ethfs-cli upload -f /Users/.../dist -a 0x2f7696D4284358A2E8fDb4DF772dAd60c2c8fbAd -c 11155111 -p 0x112233... -r https://...rpc.io