feat: add logged_assert and logged_err functions

- add functions to stubs (util namespace)
- add log_error field to AssertExpression AWST node
- add arc65_error function builders
- add the proper ebs to the type registry
- backend changes (IR) to support the logged error compilation path
- ToCodeVisitor changes to show logged errors

Author: Argimirodelpozo

src/puya/awst/nodes.py

@@ -338,6 +338,7 @@ class AssertExpression(Expression):
     """An error message to be associated with the assertion failure"""
     wtype: WType = attrs.field(default=wtypes.void_wtype, init=False)
     explicit: bool = True
+    log_error: bool = False
 
     def accept(self, visitor: ExpressionVisitor[T]) -> T:
         return visitor.visit_assert_expression(self)
@@ -1211,13 +1212,13 @@ def _validate_wtype(self, _attr: object, wtype: WType) -> None:
         match self.base.wtype, wtype:
             case wtypes.BytesWType(), wtypes.BytesWType(length=1 | None):
                 pass
-            case wtypes.ARC4Array(
-                element_type=array_element_type
-            ), _ if array_element_type == wtype:
+            case wtypes.ARC4Array(element_type=array_element_type), _ if (
+                array_element_type == wtype
+            ):
                 pass
-            case wtypes.ReferenceArray(
-                element_type=array_element_type
-            ), _ if array_element_type == wtype:
+            case wtypes.ReferenceArray(element_type=array_element_type), _ if (
+                array_element_type == wtype
+            ):
                 pass
             case _:
                 raise InternalError(

src/puya/awst/to_code_visitor.py

@@ -654,12 +654,13 @@ def visit_return_statement(self, statement: nodes.ReturnStatement) -> list[str]:
     def visit_assert_expression(self, statement: nodes.AssertExpression) -> str:
         error_message = "" if statement.error_message is None else f'"{statement.error_message}"'
         if not statement.condition:
-            result = "err("
+            result = "err(" if not statement.log_error else "logged_err("
             if error_message:
                 result += error_message
             result += ")"
         else:
-            result = f"assert({statement.condition.accept(self)}"
+            result = "assert(" if not statement.log_error else "logged_assert("
+            result += f"{statement.condition.accept(self)}"
             if error_message:
                 result += f", comment={error_message}"
             result += ")"

src/puya/ir/builder/main.py

@@ -40,7 +40,7 @@
     method_signature_to_abi_signature,
 )
 from puya.ir.builder.encoding_validation import validate_encoding
-from puya.ir.context import IRBuildContext
+from puya.ir.context import IRBuildContext, IRFunctionBuildContext
 from puya.ir.encodings import wtype_to_encoding
 from puya.ir.op_utils import OpFactory, assert_value, assign_intrinsic_op, assign_targets, mktemp
 from puya.ir.types_ import wtype_to_encoded_ir_type, wtype_to_ir_type
@@ -1120,6 +1120,13 @@ def visit_assert_expression(self, expr: awst_nodes.AssertExpression) -> TStateme
                 else:  # false constant, treat as fail/err
                     condition_value = None
 
+        if expr.log_error:
+            if expr.error_message:
+                _build_logged_error(self.context, condition_value, expr.error_message, loc)
+            else:
+                raise InternalError("a logged error should have some kind of string to log")
+            return None
+
         if condition_value is None:
             self.context.block_builder.terminate(
                 ir.Fail(
@@ -1590,6 +1597,50 @@ def materialise_value_provider(
         return multi_value_to_values(value_or_tuple)
 
 
+def _build_logged_error(
+    context: IRFunctionBuildContext,
+    condition: ir.Value | None,
+    msg: str,
+    loc: SourceLocation,
+):
+    # model assert/err behavior as a conditional jump into a pushbytes X; log; err; pattern
+    if condition:
+        log_and_fail, after_assert = context.block_builder.mkblocks(
+            "logged_error_handling", "after_assert", source_location=loc
+        )
+        context.block_builder.terminate(
+            ir.ConditionalBranch(
+                condition=condition,
+                non_zero=after_assert,
+                zero=log_and_fail,
+                source_location=loc,
+            )
+        )
+        context.block_builder.activate_block(log_and_fail)
+    context.block_builder.add(
+        ir.Intrinsic(
+            op=AVMOp("log"),
+            args=[
+                ir.BytesConstant(
+                    value=msg.encode("utf8"),
+                    encoding=types.AVMBytesEncoding.utf8,
+                    source_location=loc,
+                )
+            ],
+            source_location=loc,
+        )
+    )
+    context.block_builder.terminate(
+        ir.Fail(
+            error_message=msg,
+            explicit=True,  # logged errors are always explicit
+            source_location=loc,
+        )
+    )
+    if condition:
+        context.block_builder.try_activate_block(after_assert)
+
+
 def create_uint64_binary_op(
     op: UInt64BinaryOperator,
     left: ir.Value,

src/puyapy/awst_build/eb/_type_registry.py

@@ -9,6 +9,7 @@
 from puyapy.awst_build import constants, intrinsic_data, pytypes
 from puyapy.awst_build.eb import (
     arc4,
+    arc65_error,
     biguint,
     bool as bool_,
     bytes as bytes_,
@@ -58,6 +59,8 @@
         template_variables.GenericTemplateVariableExpressionBuilder
     ),
     "algopy.op.err": intrinsics.ErrFunctionBuilder,
+    "algopy._util.logged_assert": arc65_error.LoggedAssertFunctionBuilder,
+    "algopy._util.logged_err": arc65_error.LoggedErrFunctionBuilder,
     **{
         (fullname := "".join((constants.ALGOPY_OP_PREFIX, name))): functools.partial(
             intrinsics.IntrinsicFunctionExpressionBuilder, fullname, mappings

src/puyapy/awst_build/eb/arc65_error.py

@@ -0,0 +1,143 @@
+import typing
+from collections.abc import Sequence
+
+from puya import log
+from puya.awst.nodes import AssertExpression
+from puya.parse import SourceLocation
+from puyapy import models
+from puyapy.awst_build import pytypes
+from puyapy.awst_build.eb import _expect as expect
+from puyapy.awst_build.eb._base import FunctionBuilder
+from puyapy.awst_build.eb.factories import builder_for_instance
+from puyapy.awst_build.eb.interface import InstanceBuilder, NodeBuilder
+from puyapy.awst_build.utils import get_arg_mapping
+
+logger = log.get_logger(__name__)
+
+_VALID_PREFIXES = frozenset(("AER", "ERR"))
+_LONG_ERROR_MESSAGE = 64  # long error message (in bytes)
+
+
+class LoggedAssertFunctionBuilder(FunctionBuilder):
+    @typing.override
+    def call(
+        self,
+        args: Sequence[NodeBuilder],
+        arg_kinds: list[models.ArgKind],
+        arg_names: list[str | None],
+        location: SourceLocation,
+    ) -> InstanceBuilder:
+        arg_mapping, _ = get_arg_mapping(
+            required_positional_names=["condition", "error_code"],
+            optional_positional_names=["error_message", "prefix"],
+            args=args,
+            arg_names=arg_names,
+            call_location=location,
+            raise_on_missing=False,
+        )
+
+        condition_arg = arg_mapping.get("condition")
+        if condition_arg is not None:
+            condition_eb = expect.instance_builder(condition_arg, default=expect.default_none)
+            condition_expr = condition_eb.bool_eval(location).resolve() if condition_eb else None
+        else:
+            condition_expr = None
+
+        error_message = _resolve_error_message(arg_mapping, location)
+        return builder_for_instance(
+            pytypes.NoneType,
+            AssertExpression(
+                condition=condition_expr,
+                error_message=error_message,
+                source_location=location,
+                log_error=True,
+            ),
+        )
+
+
+class LoggedErrFunctionBuilder(FunctionBuilder):
+    @typing.override
+    def call(
+        self,
+        args: Sequence[NodeBuilder],
+        arg_kinds: list[models.ArgKind],
+        arg_names: list[str | None],
+        location: SourceLocation,
+    ) -> InstanceBuilder:
+        arg_mapping, _ = get_arg_mapping(
+            required_positional_names=["error_code"],
+            optional_positional_names=["error_message", "prefix"],
+            args=args,
+            arg_names=arg_names,
+            call_location=location,
+            raise_on_missing=False,
+        )
+
+        error_message = _resolve_error_message(arg_mapping, location)
+        return builder_for_instance(
+            pytypes.NoneType,
+            AssertExpression(
+                condition=None,
+                error_message=error_message,
+                source_location=location,
+                log_error=True,
+            ),
+        )
+
+
+def _resolve_error_message(
+    arg_mapping: dict[str, NodeBuilder], location: SourceLocation
+) -> str | None:
+    code = (
+        expect.simple_string_literal(arg_mapping["error_code"], default=expect.default_none)
+        if "error_code" in arg_mapping
+        else None
+    )
+    message = (
+        expect.simple_string_literal(arg_mapping["error_message"], default=expect.default_none)
+        if "error_message" in arg_mapping
+        else None
+    )
+    prefix = (
+        expect.simple_string_literal(arg_mapping["prefix"], default=expect.default_none)
+        if "prefix" in arg_mapping
+        else "ERR"
+    )
+
+    # code validation
+    if code is None:
+        logger.error("error code is mandatory in logged errors", location=location)
+        return None
+    elif ":" in code:
+        logger.error("error code must not contain domain separator ':'", location=location)
+    elif not code.isalnum():
+        logger.warning("error code should be alphanumeric", location=location)
+
+    # message validation
+    if message is not None and ":" in message:
+        logger.error("error message must not contain domain separator ':'", location=location)
+
+    # prefix validation (note: prefix should already be validated by mypy typing check)
+    if prefix not in _VALID_PREFIXES:
+        logger.error(
+            "error prefix must be one of AER, ERR",
+            location=location,
+        )
+
+    arc65_msg = f"{prefix}:{code}:{message}" if message else f"{prefix}:{code}"
+
+    # arc65 recommendations
+    msglen = len(arc65_msg)
+    if msglen >= _LONG_ERROR_MESSAGE:
+        logger.warning(
+            f"error message is {msglen} bytes long, consider making it shorter",
+            location=location,
+        )
+    elif msglen in (8, 32):
+        logger.warning(
+            f"your final error message is {msglen} bytes long. "
+            "Error messages exactly 8 or 32 bytes long are discouraged",
+            location=location,
+        )
+
+    return arc65_msg

stubs/algopy-stubs/_util.pyi

@@ -30,3 +30,46 @@ def size_of(type_or_expression: type | object, /) -> UInt64:
     Returns the number of bytes required to store a statically sized type,
     given as a type object or an expression of that type.
     """
+
+def logged_assert(
+    condition: bool,
+    /,
+    error_code: typing.LiteralString,
+    error_message: typing.LiteralString | None = None,
+    prefix: typing.Literal["AER", "ERR"] = "ERR",
+) -> None:
+    """
+    Asserts that a condition is true, logging a formatted error message before failing
+    if the condition is false.
+
+    The logged output follows the format ``{prefix}:{error_code}`` or
+    ``{prefix}:{error_code}:{error_message}`` and is compatible with ARC-56 and ARC-32 clients.
+
+    Note this increases the generated bytecode, so keeping ``error_code`` and ``error_message``
+    short is recommended.
+
+    :arg condition: The condition to assert; if false, logs an error and fails.
+    :arg error_code: An alphanumeric error code. Must not contain ``:``.
+    :arg error_message: Optional message appended after the code. Must not contain ``:``.
+    :arg prefix: Error prefix, either ``"AER"`` or ``"ERR"``.
+    """
+
+def logged_err(
+    error_code: typing.LiteralString,
+    error_message: typing.LiteralString | None = None,
+    prefix: typing.Literal["AER", "ERR"] = "ERR",
+) -> None:
+    """
+    Logs a formatted error message and immediately fails the transaction.
+
+    Note this is equivalent to ``logged_assert(False, error_code, error_message, prefix)``.
+    This function increases the generated bytecode, so keeping ``error_code`` and ``error_message``
+    short is recommended.
+
+    The logged output follows the ARC-65 format ``{prefix}:{error_code}`` or
+    ``{prefix}:{error_code}:{error_message}`` and is compatible with ARC-56 and ARC-32 clients.
+
+    :arg error_code: An alphanumeric error code. Must not contain ``:``.
+    :arg error_message: Optional message appended after the code. Must not contain ``:``.
+    :arg prefix: Error prefix, either ``"AER"`` or ``"ERR"``.
+    """