ERC-5018: 用于合约的类文件系统接口

提供对类似于文件系统的二进制对象进行访问的接口。

摘要

以下内容标准化了智能合约中目录和文件的 API，类似于传统的文件系统。 此标准提供读取/写入任何大小的二进制对象的基本功能，并且如果对象太大而无法放入单个交易中，则允许读取/写入对象的块。

动机

标准接口允许基于 EVM 的区块链上的任何二进制对象被其他 dApp 重用。

通过 EIP-4804，我们能够使用 HTTP 样式的 URI 在区块链上找到 Web3 资源。 Web3 资源的一个应用是使用相对路径（如 HTML/SVG）在目录中引用的 Web 内容。 该标准提出了一种基于合约的目录，以简化本地 Web 内容和链上 Web 内容之间的映射。 此外，通过 Web 内容和 EIP-4804 中引用的相对路径，用户将获得本地和链上 Web 内容的一致视图。

规范

目录

方法

write

通过具有写入权限的帐户将二进制 data 写入目录中的文件 name。

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

read

从目录中的文件 name 返回二进制 data 以及文件的存在情况。

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

fallback read

从目录中带有前缀 / 的文件 prefixedName 返回二进制 data。

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

size

从目录中的文件 name 返回 data 的大小和数据的块数。

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

remove

删除目录中的文件 name，并返回具有写入权限的帐户删除的块数（0 表示该文件不存在）。

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

countChunks

返回文件 name 的块数。

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

writeChunk

通过具有写入权限的帐户将数据块写入文件。 如果 chunkId > numOfChunks，则写入操作将失败，即，写入操作必须附加文件或替换现有块。

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

readChunk

返回文件 name 的块数据以及块的存在情况。

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

chunkSize

返回文件 name 的块的大小以及块的存在情况。

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

removeChunk

删除文件 name 的一个块，如果该块不存在，则返回 false。 该方法应由具有写入权限的帐户调用。

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

truncate

从给定的 chunkId 中删除目录中文件 name 的块，并返回具有写入权限的帐户删除的块数。 当 chunkId = 0 时，该方法本质上与 remove() 相同。

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

getChunkHash

返回块数据的哈希值。

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

合理依据

将 Web 内容上传到区块链的一个问题是，Web 内容可能太大而无法放入单个交易中。 因此，该标准提供了基于块的操作，以便可以将内容的上传分成多个事务。 同时，读取操作可以在单个交易中完成，即使用 EIP-4804 中定义的单个 Web3 URL。

未分块/分块函数之间的交互

read 方法应返回由 writeChunk 方法写入的串联的分块数据。 以下给出了一些交互示例：

• read("hello.txt") => “” （文件为空）
• writeChunk("hello.txt", 0, "abc") 将成功
• read("hello.txt") => “abc”
• writeChunk("hello.txt", 1, "efg") 将成功
• read("hello.txt") => “abcefg”
• writeChunk("hello.txt", 0, "aaa") 将成功（替换块 0 的数据）
• read("hello.txt") => “aaaefg”
• writeChunk("hello.txt", 3, "hij") 将失败，因为该操作不是替换或追加。

通过 writeChunk 方法，我们允许写入具有超过当前 calldata 限制（例如，现在为 1.8MB）的外部数据的文件，并且它能够在单个 read 方法中读取整个文件（这对于 HTML/SVG/PNG/JPG 等大型 Web 对象很友好）。

对于 write 方法，调用 write 方法将使用 write 方法数据替换文件的所有数据块，并且一种实现可以是：

1. writeChunk(filename, chunkId=0, data_from_write) 将具有相同 write 方法数据的块 0；和
2. truncate(filename, chunkId=1)，它将删除其余的块。

向后兼容性

未发现向后兼容性问题。

安全考虑

没有发现安全方面的考虑。

版权

在 CC0 下放弃版权及相关权利。

Citation

Please cite this document as:

Qi Zhou (@qizhou), "ERC-5018: 用于合约的类文件系统接口 [DRAFT]," Ethereum Improvement Proposals, no. 5018, April 2022. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-5018.