ERC-7827 JSON contract with value version control
Draft · Other · created 2024-11-07
A standard that lets a smart contract manage a JSON object and query the version history of each key's value changes. It provides a read interface that developers familiar with REST can easily use.
Why it is needed
Most web developers are used to exchanging data via REST APIs and JSON. But Ethereum smart contracts store and read data differently, so developers new to the ecosystem must separately learn each contract's distinct storage structure and functions to work with structured data. Without a common approach, there is no standard way to read a contract's data back as a whole, as if it were JSON, nor a standard way to check the history of when and how a given value changed. This proposal aims to provide JSON data management and value version control through a common, REST-like interface, so that developers with a web background can adapt to Ethereum more easily.
What to implement
function json() external view returns (string memory);: Returns the entire current state of the JSON object as a single string.function version(string calldata key) external view returns (string memory);: Returns all values the specified key has ever held, as a time-ordered JSON array string.
In depth
json(): returns the entire state as a JSON string
json() is a read function called with no input, and it returns the current state of the entire JSON object as a single string. The design intent is to let the contract be treated like a RESTful API, improving accessibility for developers accustomed to traditional web development.
version(key): per-key version history
version(string key) returns all values the requested key has ever held, as a string in JSON array form. The array is sorted chronologically, with the earliest version at index 0 and the most recent version at the highest index. Past values are never altered; new values are only appended, which preserves the immutability of the history while still allowing updates.
write(keys, values, replace): write rules
write(string[] keys, string[] values, bool replace) takes an array of keys and a corresponding array of values and writes them into the JSON object. If replace is true, it replaces the existing value; if false, the transaction reverts when the key already exists. There is no return value. Adding a new key versus updating an existing key is distinguished by the single replace parameter.
All values are treated as strings
Given that on-chain JSON encoding is inherently gas-intensive, this standard treats values as strings to limit complexity and leaves encoding efficiency to client libraries. The Solidity interface IERC7827 is presented as non-normative.
Relationship to existing standards
Since this is a new standard, it does not conflict with existing standards. However, the original notes that introducing JSON object handling and version control may require separate consideration from a gas optimization standpoint.
A proposal still in Draft stage
This document is a proposal in Draft status, created on November 7, 2024. Keep in mind that its content may still change and it has not been finalized as a standard.
Things to watch out for
- Gas burden of on-chain JSON encoding: Encoding JSON on-chain is inherently gas-intensive. This standard limits complexity by treating values as strings and leaves encoding efficiency to client libraries.
- Preventing unbounded array writes: Contracts SHOULD prevent writes of arrays with no size limit. Failing to do so can cause write call costs to balloon or expose the contract to denial-of-service (DoS) attacks.
- Handling large JSON objects: Large JSON objects should be handled efficiently to avoid excessive gas consumption.