ERC-7827: JSON Contract with Value Version Control

Manage a JSON object onchain with per-key version history and a REST-like read interface.

Abstract

This EIP defines a smart contract interface that allows for managing a JSON object within a smart contract, offering both real-time JSON output and a version-controlled history for each value. The interface includes methods to retrieve the most recent JSON state as well as the version history of each key in the JSON object. This approach supports REST developers familiar with JSON-based data interactions, thus improving accessibility for developers new to Web3 and Ethereum.

Motivation

With an increasing number of developers from RESTful backgrounds joining the Ethereum ecosystem, there is a need for a contract interface that allows developers to easily interact with structured JSON data. This EIP aims to create a universal standard that provides JSON data management and version control functionality in a straightforward and REST-like way, making Ethereum more accessible and developer-friendly.

Specification

The contract interface includes the following methods:

Read Methods

1. json()
   • Output: string (a JSON string representing the entire object)
   • Description: Returns the current state of the JSON object as a string.
2. version(string key)
   • Inputs:
     • key (string): The JSON key whose version history is requested.
   • Output: string (a JSON array as a string)
   • Description: Returns an array of all versions of the specified key’s value in JSON format. The array is ordered chronologically, with the earliest version at index 0 and the most recent version at the highest index.

Write Method

1. write(string[] keys, string[] values, bool replace)
   • Inputs:
     • keys (string[]): Array of keys to be added or updated in the JSON object.
     • values (string[]): Array of values corresponding to the keys.
     • replace (bool): If true, replaces existing values; if false, reverts if the key already exists.
   • Output: None
   • Description: Writes new values to the JSON object, either adding a new key or updating an existing one, based on the replace parameter.

Solidity Interface (non-normative)

interface IERC7827 {
    function json() external view returns (string memory);
    function version(string calldata key) external view returns (string memory);
    function write(
        string[] calldata keys,
        string[] calldata values,
        bool replace
    ) external;
}

Examples (non-normative)

Assume the following scenario with key-value management:

1. Initial Write:

   write(["name"], ["Alice"], false);
   

   • JSON Output:

     { "name": "Alice" }
     

   • Version History of name:

     ["Alice"]
     

2. Updating Value with Replacement:

   write(["name"], ["Bob"], true);
   

   • JSON Output:

     { "name": "Bob" }
     

   • Version History of name:

     ["Alice", "Bob"]
     

3. Attempting to Update without Replacement (reverts if name exists):

   write(["name"], ["Charlie"], false);
   

   • This transaction reverts because name already exists and replace is false.

Rationale

1. REST-like Access via JSON Method
   The json method enables developers to interact with the contract as if it were a RESTful API, improving accessibility for those familiar with traditional web development paradigms.

2. Version Management via Version Method
   The version method provides a straightforward version control system for each key, offering a history of values that developers can reference without altering the main JSON structure. This maintains immutability for historical values while allowing updates to be appended.

3. Compatibility with Web3 Abstractions
   Ensuring a simple and standardized ABI is essential for usability with Web3 libraries, thus enhancing developer experience and facilitating onboarding.

Backwards Compatibility

This EIP is a new standard and does not interfere with existing standards. However, it introduces JSON object handling and version control, which may have specific considerations for gas optimization.

Security Considerations

• JSON encoding onchain is inherently gas-heavy. This standard limits complexity by treating values as strings and leaving encoding efficiency to client libraries.
• Contracts SHOULD guard against unbounded array writes, which could otherwise make the write method expensive or DOS-prone.
• Care should be taken to handle large JSON objects efficiently to avoid excessive gas consumption.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

lex-clinic (@lex-clinic), "ERC-7827: JSON Contract with Value Version Control [DRAFT]," Ethereum Improvement Proposals, no. 7827, November 2024. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7827.