ARC-65: AVM Run Time Errors In Program

Informative AVM run time errors based on program bytecode

Abstract

This document introduces a convention for rising informative run time errors on the Algorand Virtual Machine (AVM) directly from the program bytecode.

Motivation

The AVM does not offer native opcodes to catch and raise run time errors.

The lack of native error handling semantics could lead to fragmentation of tooling and frictions for AVM clients, who are unable to retrieve informative and useful hints about the occurred run time failures.

This ARC formalizes a convention to rise AVM run time errors based just on the program bytecode.

Specification

The keywords “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.

Notes like this are non-normative.

Error format

The AVM programs bytecode have limited sized. In this convention, the errors are part of the bytecode, therefore it is good to mind errors’ formatting and sizing.

Errors consist of a code and an optional short message.

Errors MUST be prefixed either with:

• ERR: for custom errors;
• AER: reserved for future ARC standard errors.

Errors MUST use : as domain separator.

It is RECOMMENDED to use UTF-8 for the error bytes string encoding.

It is RECOMMENDED to use short error messages.

It is RECOMMENDED to use camel case for alphanumeric error codes.

It is RECOMMENDED to avoid error byte strings of exactly 8 or 32 bytes.

In Program Errors

When a program wants to emit informative run time errors, directly from the bytecode, it MUST:

1. Push to the stack the bytes string containing the error;
2. Execute the log opcode to use the bytes from the top of the stack;
3. Execute the err opcode to immediately terminate the program.

Upon a program run time failure, the Algod API response contains both the failed program counter (pc) and the logs array with the errors.

The program MAY return multiple errors in the same failed execution.

The errors MUST be retrieved by:

1. Decoding the base64 elements of the logs array;
2. Validating the decoded elements against the error regexp.

Error examples

Error conforming this specification are always prefixed with ERR:.

Error with a numeric code: ERR:042.

Error with an alphanumeric code: ERR:BadRequest.

Error with a numeric code and short message: ERR:042:AFunnyError.

Program example

The following program example raises the error ERR:001:Invalid Method for any application call to methods different from m1()void.

#pragma version 10

txn ApplicationID
bz end

method "m1()void"
txn ApplicationArgs 0
match method1
byte "ERR:001:Invalid Method"
log
err

method1:
b end

end:
int 1

Full Algod API response of a failed execution:

{
    "data": {
        "app-index":1004,
        "eval-states": [
            {
                "logs": ["RVJSOjAwMTpJbnZhbGlkIE1ldGhvZA=="]
            }
        ],
        "group-index":0,
        "pc":41
    },
    "message":"TransactionPool.Remember: transaction ESI4GHAZY46MCUCLPBSB5HBRZPGO6V7DDUM5XKMNVPIRJK6DDAGQ: logic eval error: err opcode executed. Details: app=1004, pc=41"
}

The logs array contains the base64 encoded error ERR:001:Invalid Method.

The logs array MAY contain elements that are not errors (as specified by the regexp).

It is NOT RECOMMENDED to use the message field to retrieve errors.

AVM Compilers

AVM compilers (and related tools) SHOULD provide two error compiling options:

1. The one specified in this ARC as default;
2. The one specified in ARC-56 as fallback, if compiled bytecode size exceeds the AVM limits.

Compilers MAY optimize for program bytecode size by storing the error prefixes in the bytecblock and concatenating the error message at the cost of some extra opcodes.

Rationale

This convention for AVM run time errors presents the following PROS and CONS.

PROS:

• No additional artifacts required to return informative run time errors;
• Errors are directly returned in the Algod API response, which can be filtered with the specified error regexp.

CONS:

• Errors consume program bytecode size.

Security Considerations

Not applicable.

Copyright

Copyright and related rights waived via CCO.

Citation

Please cite this document as:

Cosimo Bassi, Tasos Bitsios, Steve Ferrigno, "ARC-65: AVM Run Time Errors In Program," Algorand Requests for Comments, no. 65, October 2024. [Online serial]. Available: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0065.md.