feat: Support ARC65 errors (#347)

Two new utility functions are introduced `loggedErr()` and `loggedAssert()`.

These new functions work like the already present err and assert facilities with the addition of logging the error message (as specified in ARC65).

This work is the `puya-ts` continuation of algorandfoundation/puya#657

Co-authored-by: Ignacio Losiggio <[email protected]>

Author: Argimirodelpozo

packages/algo-ts/src/index.ts

@@ -1,5 +1,18 @@
 export * from './primitives'
-export { log, err, assert, match, assertMatch, ensureBudget, urange, OpUpFeeSource, clone, validateEncoding } from './util'
+export {
+  log,
+  err,
+  assert,
+  match,
+  assertMatch,
+  ensureBudget,
+  urange,
+  OpUpFeeSource,
+  clone,
+  validateEncoding,
+  loggedAssert,
+  loggedErr,
+} from './util'
 export * from './reference'
 export * as op from './op'
 export { Txn, Global } from './op'

packages/algo-ts/src/util.ts

@@ -20,6 +20,88 @@ export function assert(condition: unknown, message?: string): asserts condition
   throw new NoImplementation()
 }
 
+/**
+ * Asserts that `condition` is truthy, logging a formatted error message before failing
+ * if the condition is false.
+ *
+ * The logged output follows the format `{prefix}:{code}` or `{prefix}:{code}:{message}`
+ * and is compatible with ARC-56 and ARC-32 clients.
+ *
+ * Note that this will generate extra bytecode, so it is strongly advised to keep your
+ * messages and error codes short.
+ *
+ * @param condition The condition to assert; if false, logs an error and fails.
+ * @param code An error code. Must not contain `:`. Should be alphanumeric.
+ * @param options An optional object containing the message and prefix for the error.
+ * @param options.message Message appended after the code. Must not contain `:`.
+ *                        Defaults to no message.
+ * @param options.prefix Error prefix, either `"ERR"` or `"AER"`. Defaults to `"ERR"`.
+ */
+export function loggedAssert(
+  condition: unknown,
+  code: string,
+  options?: { message?: string | undefined; prefix?: 'ERR' | 'AER' },
+): asserts condition
+/**
+ * Asserts that `condition` is truthy, logging a formatted error message before failing
+ * if the condition is false.
+ *
+ * The logged output follows the format `ERR:{code}:{message}` and is compatible with
+ * ARC-56 and ARC-32 clients.
+ *
+ * Note that this will generate extra bytecode, so it is strongly advised to keep your
+ * messages and error codes short.
+ *
+ * @param condition The condition to assert; if false, logs an error and fails.
+ * @param code An error code. Must not contain `:`. Should be alphanumeric.
+ * @param message Message appended after the code. Must not contain `:`.
+ */
+export function loggedAssert(condition: unknown, code: string, message: string): asserts condition
+export function loggedAssert(
+  condition: unknown,
+  code: string,
+  messageOrOptions?: string | { message?: string | undefined; prefix?: 'ERR' | 'AER' },
+): asserts condition {
+  throw new NoImplementation()
+}
+
+/**
+ * Logs a formatted ARC-65 error message and immediately fails the transaction.
+ *
+ * Equivalent to `loggedAssert(false, code, {message, prefix})`.
+ *
+ * The logged output follows the format `{prefix}:{code}` or `{prefix}:{code}:{message}`
+ * and is compatible with ARC-56 and ARC-32 clients.
+ *
+ * Note that this will generate extra bytecode, so it is strongly advised to keep your
+ * messages and error codes short.
+ *
+ * @param code An error code. Must not contain `:`. Should be alphanumeric.
+ * @param options An optional object containing the message and prefix for the error.
+ * @param options.message Message appended after the code. Must not contain `:`.
+ *                        Defaults to no message.
+ * @param options.prefix Error prefix, either `"ERR"` or `"AER"`. Defaults to `"ERR"`.
+ */
+export function loggedErr(code: string, options?: { message?: string; prefix?: 'ERR' | 'AER' }): never
+/**
+ * Logs a formatted ARC-65 error message and immediately fails the transaction.
+ *
+ * Equivalent to `loggedAssert(false, code, {message, prefix})`.
+ *
+ * The logged output follows the format `ERR:{code}:{message}` and is compatible with
+ * ARC-56 and ARC-32 clients.
+ *
+ * Note that this will generate extra bytecode, so it is strongly advised to keep your
+ * messages and error codes short.
+ *
+ * @param code An error code. Must not contain `:`. Should be alphanumeric.
+ * @param message Message appended after the code. Must not contain `:`.
+ */
+export function loggedErr(code: string, message: string): never
+export function loggedErr(code: string, messageOrOptions?: string | { message?: string; prefix?: 'ERR' | 'AER' }): never {
+  throw new NoImplementation()
+}
+
 /**
  * Raise an error and halt execution
  * @param message The message to accompany the error

src/awst/intrinsic-factory.ts

@@ -40,20 +40,32 @@ export const intrinsicFactory = {
       opCode: 'concat',
     })
   },
-  err({ sourceLocation, comment }: { sourceLocation: SourceLocation; comment: string | null }) {
+  err({ sourceLocation, comment, logError }: { sourceLocation: SourceLocation; comment: string | null; logError?: boolean }) {
     return nodeFactory.assertExpression({
       condition: null,
       sourceLocation,
       wtype: wtypes.voidWType,
       errorMessage: comment,
+      logError,
     })
   },
-  assert({ sourceLocation, comment, condition }: { sourceLocation: SourceLocation; comment: string | null; condition: Expression }) {
+  assert({
+    sourceLocation,
+    comment,
+    condition,
+    logError,
+  }: {
+    sourceLocation: SourceLocation
+    comment: string | null
+    condition: Expression
+    logError?: boolean
+  }) {
     return nodeFactory.assertExpression({
       sourceLocation,
       condition,
       wtype: wtypes.voidWType,
       errorMessage: comment,
+      logError,
     })
   },
   bytesLen({ value, sourceLocation }: { value: awst.Expression; sourceLocation: SourceLocation }) {

src/awst/node-factory.ts

@@ -51,11 +51,13 @@ const explicitNodeFactory = {
     sourceLocation: SourceLocation
     wtype: wtypes.WType
     errorMessage: string | null
+    logError?: boolean
   }) {
     return new AssertExpression({
       ...props,
       wtype: wtypes.voidWType,
       explicit: true,
+      logError: props.logError ?? false,
     })
   },
   voidConstant(props: { sourceLocation: SourceLocation }): VoidConstant {

src/awst/nodes.ts

@@ -134,11 +134,13 @@ export class AssertExpression extends Expression {
     this.errorMessage = props.errorMessage
     this.wtype = props.wtype
     this.explicit = props.explicit
+    this.logError = props.logError
   }
   readonly condition: Expression | null
   readonly errorMessage: string | null
   readonly wtype: wtypes.WType
   readonly explicit: boolean
+  readonly logError: boolean
   accept<T>(visitor: ExpressionVisitor<T>): T {
     return visitor.visitAssertExpression(this)
   }

src/awst/to-code-visitor.ts

@@ -404,12 +404,12 @@ export class ToCodeVisitor
     return ['', `logicsig ${moduleStatement.id} {`, ...indent(moduleStatement.program.body.accept(this)), '}']
   }
   visitAssertExpression(expression: nodes.AssertExpression): string {
-    return [
-      expression.condition ? 'assert(' : 'err(',
-      expression.condition?.accept(this) ?? '',
-      expression.errorMessage ? `, comment=${expression.errorMessage}` : '',
-      ')',
-    ].join('')
+    if (!expression.condition) {
+      const func = expression.logError ? 'logged_err(' : 'err('
+      return `${func}${expression.errorMessage ?? ''})`
+    }
+    const func = expression.logError ? 'logged_assert(' : 'assert('
+    return `${func}${expression.condition.accept(this)}${expression.errorMessage ? `, comment=${expression.errorMessage}` : ''})`
   }
 
   visitConvertArray(expression: nodes.ConvertArray): string {

src/awst_build/eb/logged-error-builder.ts

@@ -0,0 +1,120 @@
+import type ts from 'typescript'
+import { intrinsicFactory } from '../../awst/intrinsic-factory'
+import type { SourceLocation } from '../../awst/source-location'
+import { logger } from '../../logger'
+import type { PType } from '../ptypes'
+import { stringPType } from '../ptypes'
+import type { InstanceBuilder, NodeBuilder } from './index'
+import { FunctionBuilder } from './index'
+import { requestBuilderOfType, requireInstanceBuilder, requireStringConstant } from './util'
+import { parseFunctionArgs } from './util/arg-parsing'
+import { VoidExpressionBuilder } from './void-expression-builder'
+
+const VALID_PREFIXES = new Set(['ERR', 'AER'])
+
+function resolveErrorMessage(code: InstanceBuilder, message: InstanceBuilder | undefined, prefix: InstanceBuilder | undefined): string {
+  const codeStr = requireStringConstant(code).value
+
+  if (codeStr.includes(':')) {
+    logger.error(code.sourceLocation, "error code must not contain domain separator ':'")
+  }
+
+  let messageStr: string | undefined
+  if (message) {
+    messageStr = requireStringConstant(message).value
+    if (messageStr.includes(':')) {
+      logger.error(message.sourceLocation, "error message must not contain domain separator ':'")
+    }
+  }
+
+  let prefixStr = 'ERR'
+  if (prefix) {
+    prefixStr = requireStringConstant(prefix).value
+    if (!VALID_PREFIXES.has(prefixStr)) {
+      logger.error(prefix.sourceLocation, 'error prefix must be one of AER, ERR')
+    }
+  }
+
+  return messageStr ? `${prefixStr}:${codeStr}:${messageStr}` : `${prefixStr}:${codeStr}`
+}
+
+function resolveMessageAndPrefix(maybeMessageOrOptions: InstanceBuilder | undefined): {
+  message: InstanceBuilder | undefined
+  prefix: InstanceBuilder | undefined
+} {
+  /**
+   * Tries to get a field from the optional options object.
+   *
+   * Returns `undefined` if the field does not exist or no options object was passed.
+   */
+  function get(field: string) {
+    return maybeMessageOrOptions?.hasProperty(field)
+      ? requireInstanceBuilder(maybeMessageOrOptions.memberAccess(field, maybeMessageOrOptions.sourceLocation))
+      : undefined
+  }
+
+  // Desugar string-only overload (passing `"the message"` instead of `{ message: "the message" }`)
+  if (maybeMessageOrOptions) {
+    const message = requestBuilderOfType(maybeMessageOrOptions, stringPType)
+    if (message) {
+      return { message: message, prefix: undefined }
+    }
+  }
+
+  const message = get('message')
+  const prefix = get('prefix')
+  return { message, prefix }
+}
+
+export class LoggedAssertFunctionBuilder extends FunctionBuilder {
+  call(args: ReadonlyArray<NodeBuilder>, typeArgs: ReadonlyArray<PType>, sourceLocation: SourceLocation<ts.CallExpression>): NodeBuilder {
+    const {
+      args: [condition, code, maybeMessageOrOptions],
+    } = parseFunctionArgs({
+      args,
+      typeArgs,
+      genericTypeArgs: 0,
+      callLocation: sourceLocation,
+      funcName: 'loggedAssert',
+      argSpec: (a) => [a.required(), a.required(stringPType), a.optional()],
+    })
+
+    const { message, prefix } = resolveMessageAndPrefix(maybeMessageOrOptions)
+    const errorMessage = resolveErrorMessage(code, message, prefix)
+
+    return new VoidExpressionBuilder(
+      intrinsicFactory.assert({
+        sourceLocation,
+        condition: condition!.boolEval(sourceLocation),
+        comment: errorMessage,
+        logError: true,
+      }),
+    )
+  }
+}
+
+export class LoggedErrFunctionBuilder extends FunctionBuilder {
+  call(args: ReadonlyArray<NodeBuilder>, typeArgs: ReadonlyArray<PType>, sourceLocation: SourceLocation<ts.CallExpression>): NodeBuilder {
+    const {
+      args: [code, maybeMessageOrOptions],
+    } = parseFunctionArgs({
+      args,
+      typeArgs,
+      genericTypeArgs: 0,
+      callLocation: sourceLocation,
+      funcName: 'loggedErr',
+      argSpec: (a) => [a.required(stringPType), a.optional()],
+    })
+
+    const { message, prefix } = resolveMessageAndPrefix(maybeMessageOrOptions)
+    const errorMessage = resolveErrorMessage(code, message, prefix)
+
+    return new VoidExpressionBuilder(
+      intrinsicFactory.err({
+        sourceLocation,
+        comment: errorMessage,
+        logError: true,
+      }),
+    )
+  }
+}

src/awst_build/ptypes/index.ts

@@ -1304,6 +1304,16 @@ export const errFunction = new LibFunctionType({
   module: Constants.moduleNames.algoTs.util,
 })
 
+export const loggedAssertFunction = new LibFunctionType({
+  name: 'loggedAssert',
+  module: Constants.moduleNames.algoTs.util,
+})
+
+export const loggedErrFunction = new LibFunctionType({
+  name: 'loggedErr',
+  module: Constants.moduleNames.algoTs.util,
+})
+
 export const assetPType = new ABICompatibleInstanceType({
   name: 'Asset',
   wtype: wtypes.assetWType,

src/awst_build/ptypes/register.ts

@@ -50,6 +50,7 @@ import { CloneFunctionBuilder } from '../eb/clone-function-builder'
 import { CompileFunctionBuilder } from '../eb/compiled/compile-function'
 import { ContractClassBuilder, ContractOptionsDecoratorBuilder } from '../eb/contract-builder'
 import { EnsureBudgetFunctionBuilder } from '../eb/ensure-budget'
+import { LoggedAssertFunctionBuilder, LoggedErrFunctionBuilder } from '../eb/logged-error-builder'
 
 import { FreeSubroutineExpressionBuilder } from '../eb/free-subroutine-expression-builder'
 import { IntrinsicEnumBuilder } from '../eb/intrinsic-enum-builder'
@@ -210,6 +211,8 @@ import {
   LocalStateGeneric,
   LocalStateType,
   logFunction,
+  loggedAssertFunction,
+  loggedErrFunction,
   logicSigOptionsDecorator,
   LogicSigPType,
   matchFunction,
@@ -316,6 +319,8 @@ export function registerPTypes(typeRegistry: TypeRegistry) {
   typeRegistry.register({ ptype: logFunction, singletonEb: LogFunctionBuilder })
   typeRegistry.register({ ptype: assertFunction, singletonEb: AssertFunctionBuilder })
   typeRegistry.register({ ptype: errFunction, singletonEb: ErrFunctionBuilder })
+  typeRegistry.register({ ptype: loggedAssertFunction, singletonEb: LoggedAssertFunctionBuilder })
+  typeRegistry.register({ ptype: loggedErrFunction, singletonEb: LoggedErrFunctionBuilder })
   typeRegistry.register({ ptype: matchFunction, singletonEb: MatchFunctionBuilder })
   typeRegistry.register({ ptype: assertMatchFunction, singletonEb: AssertMatchFunctionBuilder })
   typeRegistry.register({ ptype: ensureBudgetFunction, singletonEb: EnsureBudgetFunctionBuilder })

tests/approvals/logged-errors-warnings.algo.ts

@@ -0,0 +1,36 @@
+import type { uint64 } from '@algorandfoundation/algorand-typescript'
+import { Contract, loggedAssert, loggedErr } from '@algorandfoundation/algorand-typescript'
+
+export class LoggedErrorsWarningsContract extends Contract {
+  public testInvalidCode(arg: uint64): void {
+    loggedAssert(arg !== 1, 'not-alnum!')
+    loggedErr('not-alnum!')
+  }
+
+  public testCamelCaseCode(arg: uint64): void {
+    loggedAssert(arg !== 1, 'MyCode')
+    loggedErr('MyCode')
+  }
+
+  public testAERPrefix(arg: uint64): void {
+    loggedAssert(arg !== 1, '01', { prefix: 'AER' })
+    loggedErr('01', { prefix: 'AER' })
+  }
+
+  public testLongMessage(arg: uint64): void {
+    loggedAssert(arg !== 1, '01', {
+      message: 'I will now provide a succint description of the error. I guess it all started when I was 5...',
+    })
+    loggedErr('01', { message: 'I will now provide a succint description of the error. I guess it all started when I was 5...' })
+  }
+
+  public test8ByteMessage(arg: uint64): void {
+    loggedAssert(arg !== 1, 'abcd')
+    loggedErr('abcd')
+  }
+
+  public test32ByteMessage(arg: uint64): void {
+    loggedAssert(arg !== 1, '01', { message: 'aaaaaaaaaaaaaaaaaaaaaaaaa' })
+    loggedErr('01', { message: 'aaaaaaaaaaaaaaaaaaaaaaaaa' })
+  }
+}