ARC-22: Add `read-only` annotation to ABI methods Source

Convention for creating methods which don't mutate state

TypeStandards Track
Requires 4

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.


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.


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;


Security Considerations


Copyright and related rights waived via CCO.


Please cite this document as:

ori-shem-tov, "ARC-22: Add `read-only` annotation to ABI methods," Algorand Requests for Comments, no. 22, March 2022. [Online serial]. Available: