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
event Response(bytes _response);: An event that announces the response value of a POST or PUT request.function getMethods(MethodTypes _methodTypes)external view returns (string[] memory);: Given a request method type, returns the list of method names belonging to that type.function getMethodReqAndRes(string memory _methodName) external view returns(Types.Type[] memory ,Types.Type[] memory );: Given a method name, returns the request parameter data type and response parameter data type of that method.function getMethodInstruction(string memory _methodName) external view returns(string memory);: Given a method name, returns the usage instructions for that method.function get(string memory _methodName,bytes memory _methodReq)external view returns(bytes memory);: Requests a record lookup from the contract. Takes a method name and encoded request parameters and returns the response.function post(string memory _methodName,bytes memory _methodReq)external payable returns(bytes memory);: Requests creation of a new record on the contract. Takes a method name and encoded request parameters and returns the response.function put(string memory _methodName,bytes memory _methodReq)external payable returns(bytes memory);: Requests an update to a record on the contract. Takes a method name and encoded request parameters and returns the response.function options()external returns(MethodTypes[] memory);: Returns the list of request method types this contract supports.
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
- Distinction between safe and unsafe methods: Contract request methods are divided into safe and unsafe methods. A method that is read-only and does not change contract state is safe. GET and OPTIONS are safe methods, while POST and PUT are unsafe methods.