ERC-7654: Request Method Types

Use a set of request methods to indicate the type of action to take on the contract.


Metadata
Status: DraftStandards Track: ERCCreated: 2024-03-13
Authors
Rickey (@HelloRickey)

Abstract


This proposal standardizes a set of request and response communication standards between clients and smart contracts, using POST, GET, and PUT requests to create, read, and update the states of smart contracts. You can customize different request method names, request parameters and response values, and each request method will be mapped to a specific operation.

Motivation


Since each contract has different functions, the client cannot use a standard to call different functions of different contracts. Contract Request Methods redefines the request method of the contract, so that different functions of multiple different contracts can be called using a consistent set of rules and protocols.

By dividing the function types into POST, GET, and PUT, different operations can be performed on the contract. This clear operation type can not only help all parties limit the access and operation of contract data, but also effectively simplify the interaction between the client and the contract, making it easier for all parties to understand the functions and hierarchical structure of the contract. The request and response parameter data types of each function of this standard can express the expected operation of the contract and have the ability to describe its own structure, which is conducive to the parties and contracts to create a unified and predictable way of exchanging data.

Specification


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

It consists of four request method types:

GET: Request the contract to retrieve records.

POST: Request the contract to create a new record.

PUT: Request the contract to update a record.

OPTIONS: Supported request method types.

Workflow:

  1. Call options to obtain supported request method types.
  2. Call getMethods to obtain the request method name.
  3. Call getMethodReqAndRes to obtain the request parameter data type and response value data type.
  4. Encode request parameters and call get, post, and put.
  5. Decode response value.

Interfaces

IRequestMethodTypes.sol


Library

The library Types.sol contains an enumeration of Solidity types used in the above interfaces.

Rationale


Type of request method

In order to enable the client to operate the contract in a standardized and predictable way, three request method types GET, POST, and PUT are set. The functions of each need to be defined in these three types to facilitate the contract caller to understand and process the information required for the request. However, there is no DELETE operation type because deleting data in the contract is an inefficient operation. Developers can add a PUT request method by themselves to set the data to be valid and invalid, and only return valid data in the GET method.

Request method parameter type

Some functions are defined in each request method type. They all include request parameter data type and response parameter data type, which need to be set in the constructor and then obtained according to the method name through getMethodReqAndRes. The data type of the parameter is defined by the enumeration of the data type. When processing the request parameter, abi.decode is used to decode according to the request parameter type and the request value. When returning the response, abi.encode is used to encode according to the response value and the response parameter type.

Reference Implementation


See Request Method Types Example

Security Considerations


Contract request methods are divided into safe methods and unsafe methods. If the method request is a read-only operation and will not change the state of the contract, then the method is safe.

Safe Methods: GET, OPTIONS
Unsafe Methods: POST, PUT

Copyright


Copyright and related rights waived via CC0.