doc: rely on logs array instead of message field

ARCs/arc-0065.md

@@ -34,33 +34,42 @@ in this document are to be interpreted as described in <a href="https://datatrac
 
 > 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** statisfy this regexp: `ERR:(\w*)(?:\s?-\s?(.*))?`.
+
+It is **RECOMMENDED** to use `UTF-8` for the error bytes string encoding.
+
+It is **RECOMMENDED** to use fixed length error codes and _short_ error messages.
+
 ### In Program Errors
 
-When a program wants to emit informative run time errors, contained in the bytecode,
+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;
 1. Execute the `log` opcode to use the bytes from the top of the stack;
 1. Execute the `err` opcode to immediately terminate the program.
 
-Upon a program run time failure, the Algod API returns both the failed *program 
-counter* (`pc`) and the `log` content.
+Upon a program run time failure, the Algod API response contains both the failed
+_program counter_ (`pc`) and the `logs` array with the _errors_.
 
-### 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_.
+The program **MAY** return multiple errors in the same failed execution.
 
-Errors **MUST** statisfy the regexp: `ERR:(\w*)(?:\s?-\s?(.*))?`.
+The errors **MUST** be retrieved by:
 
-It is **RECOMMENDED** to use `UTF-8` for the error encoding.
-
-It is **RECOMMENDED** to use fixed length error codes and _short_ error messages.
+1. Decoding the `base64` elements of the `logs` array;
+1. 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`.
@@ -69,8 +78,8 @@ Error with a _numeric code_ and _short message_: `ERR:042 - A Funny Error`.
 
 ### Program example
 
-The program example raises the error `ERR:001 - Invalid Method` for any application 
-call to methods different from `m1()void`.
+The following program example raises the error `ERR:001 - Invalid Method` for any
+application call to methods different from `m1()void`.
 
 ```teal
 #pragma version 10
@@ -110,18 +119,22 @@ Full Algod API response of a failed execution:
 }
 ```
 
-The `message` field contains the error `ERR:001 - Invalid Method`.
+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 on the `message` field to retrieve errors.
 
 ## Rationale
 
 This convention for AVM run time errors presents the following PROS and CONS.
 
 ### PROS
 
-- No additional artifacts required to bind the failed *program counter* (`pc`) to 
-the informative _error_;
-- Errors are returned directly in the Algod API response, no additional client operation
-needed.
+- 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