ERC-7654 Request method type (Request Method Types)

Draft · Other · created 2024-03-13

A standard that divides contract functions into web-request-like GET (read), POST (create), and PUT (update) types, allowing a client to call different contracts and interpret their responses under one consistent rule.

Why it is needed

Because every contract has different functions, a client (a program such as a wallet or app that calls the contract) has no common standard way to call the different functions of multiple contracts. A dedicated calling code must be written for each contract, and it is not outwardly clear which functions only read data and which change state. This standard redefines contract functions into read (GET), create (POST), and update (PUT) types. Once the type of each operation is clear, each party can restrict access to and manipulation of contract data by category, and interaction between client and contract becomes simpler, making the contract's functions and structure easier to understand. The request and response data types of each function also describe themselves, letting parties and contracts exchange data in a unified and predictable way.

What to implement

In depth

The four request method types

The standard defines four types with the MethodTypes enum: GET, POST, PUT, and OPTIONS. GET requests a record lookup from the contract, POST requests creation of a new record, PUT requests an update to a record, and OPTIONS tells you which request method types that contract supports. Each contract's functions MUST be defined within the three types GET, POST, and PUT, which makes it easier for the caller to understand and handle the information needed for the request. get is a view function, while post and put are payable functions. The response values of post and put are also announced via the Response event.

Self-describing method information

Each request method carries both a request parameter data type and a response parameter data type. These types are set in the constructor and later obtained by calling getMethodReqAndRes with the method name. The data types of the parameters are expressed using the Types.Type enum from the Types.sol library, which enumerates Solidity types. getMethods gives the list of method names per type, and getMethodInstruction gives the usage instructions for a method, so a client can query the information it needs directly from the contract without knowing its structure in advance.

ABI-encoding-based requests and responses

get, post, and put all share a common form: they take a method name (string) and encoded request parameters (bytes), and return an encoded response (bytes). When processing a request, the contract decodes it with abi.decode according to the request parameter type and value, and when returning a response, encodes it with abi.encode according to the response value and response parameter type. A client just needs to encode the request and decode the response according to the type information obtained from getMethodReqAndRes, so the same exchange method works across different contracts.

Why there is no DELETE type

This standard has no DELETE operation type, because deleting data in a contract is an inefficient operation. Instead, a developer can add a custom PUT request method to mark data as valid or invalid, and have the GET method return only valid data.

A Proposal in Draft Stage

This proposal is in Draft status. Its content may still change, so it is best to check the latest source text before implementing it.

Things to watch out for

Original ERC · ← ERCs