ERC-5018: Filesystem-like Interface for Contracts
An interface to provide access to binary objects similar to filesystems.
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 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 samewrite
method data; andtruncate(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.