ARC-64: AVM Run Time Errors based on program source map

ARCs/arc-0064.md

@@ -0,0 +1,103 @@
+---
+arc: 64
+title: AVM Run Time Errors Source Map
+description: Informative AVM run time errors based on program counter source map
+author: Cosimo Bassi (@cusma), Tasos Bitsios (@tasosbit), Steve Ferrigno (@nullun)
+discussions-to: https://github.com/algorandfoundation/ARCs/issues/305
+status: Draft
+type: Standards Track
+category: ARC
+created: 2024-08-05
+---
+
+## Abstract
+
+This document introduces a convention for rising informative run time error on the
+Algorand Virtual Machine (AVM) based on a program counter *source map*.
+
+## 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 conventions to raise AVM run time errors based on a program
+counter source map.
+
+## 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 <a href="https://datatracker.ietf.org/doc/html/rfc2119">RFC 2119</a>.
+
+> Notes like this are non-normative.
+
+### Program Counter Error Source Map
+
+> TEAL source code instructions are uniquely identified by a program counter, returned
+> in the Algod API response upon AVM run time failure.
+
+> A program counter source map maps program counters back to the original TEAL
+> source code lines.
+
+> The program counter error source map convention is based on error messages written
+> as comments in the TEAL source code.
+
+When a program wants to emit a run time error, it **MUST**:
+
+1. Precede the failing TEAL instruction with a comment (error message);
+1. Produce a program counter source map for the client.
+
+Upon a program run time failure, the Algod API returns the failed *program counter*
+(`pc`).
+
+Using the program counter, the client **MUST**:
+
+1. Retrieve the error message preceding the failed TEAL instruction from the program
+counter source map;
+1. Return the error message.
+
+### Example
+
+```
+int 0				[pc=0]
+int 1				[pc=1]
+&&				[pc=2]
+// ERR_LOGIC_FALSE
+assert				[pc=3]
+```
+
+> The evaluation of the example program would result in a run time error on the
+> `assert` instruction, returning the failed program counter (`[pc=3]`) as part
+> of the Algod API response. Using a program counter source map, the client is
+> then able to retrieve and return the corresponding error message `ERR_LOGIC_FALSE`
+> (i.e. the comment preceding the failed program counter).
+
+## Rationale
+
+The program counter error source map convention for AVM run time error messages 
+presents the following PROS and CONS.
+
+### PROS
+
+- No program size consumed by error messages.
+
+### CONS
+
+- Standard program source maps required for clients to map errors to failed program
+counter;
+- Developers or compilers need to create an extra “errors source map” to map program
+assertion locations to specific error codes;
+  - Portability: errors source map needs to be kept up to date through different
+  iterations of a program;
+- Error message not returned directly in the Algod API response.
+
+## Security Considerations
+
+> Not applicable.
+
+## Copyright
+
+Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CCO</a>.