Add `read-only` annotation to ABI methods | Algorand Developer Portal

Add `read-only` annotation to ABI 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 (according 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.

Add read-only annotation to ABI methods