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

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

Original ERC · ← ERCs