ERC-7827: JSON Smart Contract with Value Version Control

bestape · November 26, 2024, 4:40pm

Authors	Kyle Smith (@bestape) , Lex.Clinic (@lexclinic)
EIP Link	Github
Discussions	See MegaZu demo day , EIP Editing Office Hour 47
Status	Draft
Type	Standards Track
Category	ERC
Created	2024-11-07

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

json()
- Inputs: None.
- Output: string (a JSON object as a string)
- Description: Returns the JSON object in its latest state. The output uses the most recent value for each key in the JSON object, mimicking a REST JSON call.
- Behavior: Each key in the JSON object reflects the latest “Last In, First Out” (LIFO) state of its value.
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

write(string[] keys, string[] values, bool replace)
- Inputs:
  - keys (string[]): Array of JSON key strings, where each key represents a path within the JSON object.
  - values (string[]): Array of JSON-compatible strings corresponding to each key. Can represent primitive types, arrays, or objects.
  - replace (bool): Determines whether to replace an existing key’s latest value.
    - If replace is true and the key exists, the existing value is updated in the json output.
    - However, the previous value persists in the version output, with the new value appended at the end of the version history array.
    - If replace is false and the key already exists, the transaction reverts.
- 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.

Additional Requirements

Universal ABI: To support widespread adoption and ease of use, the ABI should be standardized for REST-like abstraction within popular Web3 libraries.
By making this contract accessible through Web3 abstractions, developers with REST experience can seamlessly interact with the contract.

Rationale

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.
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 method maintains immutability for historical values while allowing updates to be appended.
Compatibility with Web3 Abstractions
Ensuring a simple and standardized ABI is essential for usability with Web3 libraries, thus enhancing developer experience and facilitating onboarding.

Example Usage

Assume the following scenario with key-value management:

Initial Write:

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

JSON Output after this call:
```
{ "name": "Alice" }
```
Version History of name:
```
["Alice"]
```

Updating Value with Replacement:
```
write(["name"], ["Bob"], true);
```
- JSON Output after this call:
```
{ "name": "Bob" }
```
- Version History of name:
```
["Alice", "Bob"]
```
Attempting to Update without Replacement (Reverts if name exists):
```
write(["name"], ["Charlie"], false);
```
- This transaction would revert as name already exists, and replace is set to false.

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

Care should be taken to handle large JSON objects efficiently to avoid excessive gas consumption.