Filesystem-like Interface for Contracts
The ERC-5018 standard is an API for directories and files within smart contracts, similar to traditional filesystems. It 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. This standard allows any binary objects on EVM-based blockchain to be re-used by other dApps.
Video
Original
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 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.
Adopted by projects
Not miss a beat of EIPs' update?
Subscribe EIPs Fun to receive the latest updates of EIPs Good for Buidlers to follow up.
View all