ERC-5018: Filesystem-like Interface for Contracts

An interface to provide access to binary objects similar to filesystems.


Metadata
Status: StagnantStandards Track: ERCCreated: 2022-04-18
Authors
Qi Zhou (@qizhou)

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.


read

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


fallback read

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


size

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


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.


countChunks

Returns the number of chunks of the file name.


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.


readChunk

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


chunkSize

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


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.


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().


getChunkHash

Returns the hash value of the chunk data.


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:

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

Backwards Compatibility


No backwards compatibility issues were identified.

Security Considerations


No security considerations were found.

Copyright


Copyright and related rights waived via CC0.