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

Convention for creating methods which don't mutate state

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.