Filesystem-like Interface for Contracts

Abstract

The following standardizes an API for directories and files within smart contracts, similar to traditional filesystems. This standard provides basic functionality to read/write binary objects of any size, as well as allow reading/writing chunks of the object if the object is too large to fit in a single transaction.

Motivation

A standard interface allows any binary objects on EVM-based blockchain to be re-used by other dApps.

With EIP-4804, we are able to locate a Web3 resource on blockchain using HTTP-style URIs. One application of Web3 resources are web contents that are referenced within a directory using relative paths such as HTML/SVG. This standard proposes a contract-based directory to simplify the mapping between local web contents and on-chain web contents. Further, with relative paths referenced in the web contents and EIP-4804, the users will have a consistent view of the web contents locally and on-chain.

Specification

Directory

Methods

write

Writes binary data to the file name in the directory by an account with write permission.

function write(bytes memory name, bytes memory data) external payable

read

Returns the binary data from the file name in the directory and existence of the file.

function read(bytes memory name) external view returns (bytes memory data, bool exist)

fallback read

Returns the binary data from the file prefixedName (prefixed with /) in the directory.

fallback(bytes calldata prefixedName) external returns (bytes memory data)

size

Returns the size of the data from the file name in the directory and the number of chunks of the data.

function size(bytes memory name) external view returns (uint256 size, uint256 chunks)

remove

Removes the file name in the directory and returns the number of chunks removed (0 means the file does not exist) by an account with write permission.

function remove(bytes memory name) external returns (uint256 numOfChunksRemoved)

countChunks

Returns the number of chunks of the file name.

function countChunks(bytes memory name) external view returns (uint256 numOfChunks);

writeChunk

Writes a chunk of data to the file by an account with write permission. The write will fail if chunkId > numOfChunks, i.e., the write must append the file or replace the existing chunk.

 function writeChunk(bytes memory name, uint256 chunkId, bytes memory chunkData) external payable;

readChunk

Returns the chunk data of the file name and the existence of the chunk.

function readChunk(bytes memory name, uint256 chunkId) external view returns (bytes memory chunkData, bool exist);

chunkSize

Returns the size of a chunk of the file name and the existence of the chunk.

function chunkSize(bytes memory name, uint256 chunkId) external view returns (uint256 chunkSize, bool exist);

removeChunk

Removes a chunk of the file name and returns false if such chunk does not exist. The method should be called by an account with write permission.

function removeChunk(bytes memory name, uint256 chunkId) external returns (bool exist);

truncate

Removes the chunks of the file name in the directory from the given chunkId and returns the number of chunks removed by an account with write permission. When chunkId = 0, the method is essentially the same as remove().

function truncate(bytes memory name, uint256 chunkId) external returns (uint256 numOfChunksRemoved);

getChunkHash

Returns the hash value of the chunk data.

function getChunkHash(bytes memory name, uint256 chunkId) external view returns (bytes32);

Rationale

One issue of uploading the web contents to the blockchain is that the web contents may be too large to fit into a single transaction. As a result, the standard provides chunk-based operations so that uploading a content can be split into several transactions. Meanwhile, the read operation can be done in a single transaction, i.e., with a single Web3 URL defined in EIP-4804.

Interactions Between Unchunked/Chunked Functions

read method should return the concatenated chunked data written by writeChunk method. The following gives some examples of the interactions:

read("hello.txt") => “” (file is empty)
writeChunk("hello.txt", 0, "abc") will succeed
read("hello.txt") => “abc”
writeChunk("hello.txt", 1, "efg") will succeed
read("hello.txt") => “abcefg”
writeChunk("hello.txt", 0, "aaa") will succeed (replace chunk 0’s data)
read("hello.txt") => “aaaefg”
writeChunk("hello.txt", 3, "hij") will fail because the operation is not replacement or append.

With writeChunk method, we allow writing a file with external data that exceeds the current calldata limit (e.g., 1.8MB now), and it is able to read the whole file in a single read method (which is friendly for large web objects such as HTML/SVG/PNG/JPG, etc).

For write method, calling a write method will replace all data chunks of the file with write method data, and one implementation can be:

writeChunk(filename, chunkId=0, data_from_write) to chunk 0 with the same write method data; and
truncate(filename, chunkId=1), which will remove the rest chunks.