doc: ARC-65

ARCs/arc-0065.md

@@ -0,0 +1,118 @@
+---
+arc: 65
+title: AVM Run Time Errors In Program
+description: Informative AVM run time errors based on program bytecode
+author: Cosimo Bassi (@cusma), Tasos Bitsios (@tasosbit), Steve Ferrigno (@nullun)
+discussions-to: https://github.com/algorandfoundation/ARCs/issues/XXX
+status: Draft
+type: Standards Track
+category: ARC
+created: 2024-10-09
+
+---
+
+## Abstract
+
+This document introduces conventions for rising informative run time error messages
+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 <a href="https://datatracker.ietf.org/doc/html/rfc2119">RFC 2119</a>.
+
+> Notes like this are non-normative.
+
+### In Program Errors
+
+When a program wants to emit a run time error code, contained in the bytecode, 
+it **MUST**:
+
+1. Push to the stack the bytes string containing the error code;
+1. Push to the stack the `log` opcode;
+1. Push to the stack the `err` opcode.
+
+Upon a program run time failure, the Algod API returns both the failed *program 
+counter* (`pc`) and the `log` content.
+
+> The AVM programs bytecode have limited sized. In this convention, the errors are part of the bytecode. It is **RECOMMENDED** to use fixed length error codes or shorr error messages.
+
+### Example
+
+The program example raises the error code `ERR:001 - Invalid Method` for any application 
+call to methods different from `m1()void`.
+
+```teal
+#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:
+
+```json
+{
+    "data": {
+        "app-index":1004,
+        "eval-states": [
+            { 
+                "logs": ["RVJSOiBJbnZhbGlkIE1ldGhvZA=="]
+            }
+        ],
+        "group-index":0,
+        "pc":41
+    },
+    "message":"TransactionPool.Remember: transaction ESI4GHAZY46MCUCLPBSB5HBRZPGO6V7DDUM5XKMNVPIRJK6DDAGQ: logic eval error: err opcode executed. Details: app=1004, pc=41, opcodes=pushbytes 0x4552523a20496e76616c6964204d6574686f64 // \"ERR:001 - Invalid Method\"; log; err; label2:"
+}
+```
+
+The `message` field contains the error code `ERR:001 - Invalid Method`.
+
+## Rationale
+
+This convention for AVM run time error codes presents the following PROS and CONS.
+
+### PROS
+
+- No additional artifacts required to bind the failed *program counter* (`pc`) to 
+the informative *error code*;
+- Error codes are returned directly in the Algod API response, no additional client
+operation needed.
+
+### CONS
+
+- Error codes consume program bytecode size.
+
+## Security Considerations
+
+> Not applicable.
+
+## Copyright
+
+Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CCO</a>.