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.
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.
Writes binary data to the file name in the directory by an account with write permission.
Returns the binary data from the file name in the directory and existence of the file.
Returns the binary data from the file prefixedName (prefixed with /) in the directory.
Returns the size of the data from the file name in the directory and the number of chunks of the data.
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.
Returns the number of chunks of the file name.
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.
Returns the chunk data of the file name and the existence of the chunk.
Returns the size of a chunk of the file name and the existence of the chunk.
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.
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().
Returns the hash value of the chunk data.
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.
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 succeedread("hello.txt") => "abc"writeChunk("hello.txt", 1, "efg") will succeedread("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; andtruncate(filename, chunkId=1), which will remove the rest chunks.No backwards compatibility issues were identified.
No security considerations were found.
Copyright and related rights waived via CC0.