ARC-22: Add `read-only` annotation to ABI methods
Convention for creating methods which don't mutate state
Author | ori-shem-tov |
---|---|
Discussions-To | https://github.com/algorandfoundation/ARCs/issues/125 |
Status | Last Call |
Last Call Deadline | 2023-03-23 |
Type | Standards Track |
Category | Interface |
Created | 2022-03-16 |
Requires | 4 |
Table of Contents
Extend ARC-4 to add read-only
annotation to methods
The following document introduces a convention for creating methods (as described in ARC-4) which donβt mutate state.
Abstract
The goal of this convention is to allow smart contract developers to distinguish between methods which mutate state and methods which donβt by introducing a new property to the Method
descriptor.
Specification
The key words βMUSTβ, βMUST NOTβ, βREQUIREDβ, βSHALLβ, βSHALL NOTβ, βSHOULDβ, βSHOULD NOTβ, βRECOMMENDEDβ, βMAYβ, and βOPTIONALβ in this document are to be interpreted as described in RFC-2119.
Comments like this are non-normative.
Read-only functions
A read-only
function is a function with no side-effects. In particular, a read-only
function SHOULD NOT include:
- local/global state modifications
- calls to non
read-only
functions - inner-transactions
It is RECOMMENDED for a read-only
function to not access transactions in a group or metadata of the group.
The goal is to allow algod to easily execute
read-only
functions without broadcasting a transaction
In order to support this annotation, the following Method
descriptor is suggested:
interface Method {
/** The name of the method */
name: string;
/** Optional, user-friendly description for the method */
desc?: string;
/** Optional, is it a read-only method (accroding to ARC-22) */
readonly?: boolean
/** The arguments of the method, in order */
args: Array<{
/** The type of the argument */
type: string;
/** Optional, user-friendly name for the argument */
name?: string;
/** Optional, user-friendly description for the argument */
desc?: string;
}>;
/** Information about the method's return value */
returns: {
/** The type of the return value, or "void" to indicate no return value. */
type: string;
/** Optional, user-friendly description for the return value */
desc?: string;
};
}
Rationale
Security Considerations
None.
Copyright
Copyright and related rights waived via CCO.
Citation
Please cite this document as:
ori-shem-tov, "ARC-22: Add `read-only` annotation to ABI methods [DRAFT]," Algorand Requests for Comments, no. 22, March 2022. [Online serial]. Available: https://algorandfoundation.github.io/ARCS/arc-22.