masm-error-constants

name	masm-error-constants
description	Use when adding or editing MASM `assert*` instructions — give every assertion a descriptive error (a named `ERR_*` constant or an inline string).

MASM Error Constants

Rule

Every MASM assertion should carry a descriptive error message. There are two valid forms in v0.15 source:

• Named ERR_* constant — preferred for reusable or shared errors, and the dominant style in protocol/standards code:

assert.err=ERR_NOTE_NOT_FOUND
assert_eqw.err=ERR_COMMITMENT_MISMATCH

• Inline string literal with .err="..." — valid and common, especially in core-lib/stdlib and for one-off, local checks:

u32assert2.err="number of storage map elements should fit into a u32"
assert.err="number of storage map elements must be a multiple of 8"

Prefer a named constant when the same error is raised in more than one place, when it is part of a module's documented error surface, or when Rust code needs to match on it (named ERR_* constants are codegen'd into Rust bindings — see masm-rust-constant-parity). Reach for an inline string for a purely local, single-site check where a named constant would only add indirection.

When you define a named error constant, it must:

• Use the ERR_ prefix.
• Live in the file's dedicated errors section (see masm-constants skill).
• Have a descriptive string value, not a bare numeric code: const ERR_NOTE_NOT_FOUND = "note not found".
• Be unique per distinct failure condition — do not share one ERR_ across two unrelated asserts.

Why

A bare assert traps with the default error code 0, which tells the debugger nothing about which check failed; a descriptive error message (a named ERR_* constant or an inline string) ties each trap site to a specific failure mode. (The error string is hashed into a field element; an omitted code defaults to 0.) Distinct constants per condition also let tests pin the expected error rather than matching a generic failure.

Examples

# Good
const ERR_NOTE_NOT_FOUND = "note not found"
const ERR_COMMITMENT_MISMATCH = "stored commitment does not match recomputed value"

proc verify_note
    # ...
    assert.err=ERR_NOTE_NOT_FOUND
    # ...
    assert_eqw.err=ERR_COMMITMENT_MISMATCH
end

# Bad: bare assertion
proc verify_note
    assert
end

# Bad: shared generic constant for unrelated cases
const ERR_INVALID = "invalid"
assert.err=ERR_INVALID   # used in 6 places, each meaning something different