πŸ“’ This ARC is in the last call for review stage. The authors wish to finalize the ARC and appreciate feedback.

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

Convention for creating methods which don't mutate state

Authorori-shem-tov
Discussions-Tohttps://github.com/algorandfoundation/ARCs/issues/125
StatusLast Call
Last Call Deadline2023-03-23
TypeStandards Track
CategoryInterface
Created2022-03-16
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.

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 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.