0xmiden/agent-tools/masm-constants

MASM Constant Conventions

Placement

Constants must be defined at the top of the file, before any procedure definitions, but after imports or type aliases.

Organization

Constants Section (first)

Group non-error constants by topic. Use blank lines between sections. Common topics:

• Slot names – use word("path::to::slot") for slot identifiers
• Memory pointer offsets – offsets into memory regions
• Magic numbers / values – domain-specific literals
• Event identifiers – for emit / trace

Order sections by dependency or by usage frequency. Put the most widely used first.

Errors Section (after constants)

Errors (panic/assert error codes, e.g. ERR_*) go in a dedicated "errors" section, placed after the constants section. Define them with string values describing the error.

Naming

Memory Pointers

Memory pointer constants describe offsets into memory regions that are shared or global (e.g. layout of a memory region, input/output structure offsets). They are not scoped to a single procedure and do not use the procedure prefix.

# Good: descriptive, shared usage
const ASSET_OFF = 0
const AMOUNT_OFF = 1
const NOTE_DATA_LEN = 16
 
# Or grouped by memory region if applicable
const INPUT_PTR_OFF = 0
const INPUT_LEN_OFF = 1

Memory Locals Offsets

Memory locals offsets are procedure-scoped: they describe offsets within a procedure's local memory. They must be prefixed with the procedure name they belong to:

# Good: procedure-prefixed
const validate_note_NOTE_IDX_LOC = 0
const validate_note_ASSET_LOC = 1
const process_input_INPUT_PTR_OFF = 0
 
# Bad: generic, ambiguous
const NOTE_IDX_LOC = 0
const ASSET_LOC = 1
const INPUT_PTR_OFF = 0

This keeps offsets scoped and avoids collisions when multiple procedures use local memory.

Formatting

Put spaces around the equals sign.

Errors – string value describing the error:

const ERR_BRIDGE_NOT_MAINNET = "bridge not mainnet"
const ERR_UNAUTHORIZED = "unauthorized"

Slots – use word() with the slot path:

const BRIDGE_ID_SLOT = word("miden::agglayer::faucet")
const SLOT_ACCOUNT_ID = word("account::id")

Offsets / numeric values – plain numbers:

const validate_note_NOTE_IDX_LOC = 0
const validate_note_ASSET_LOC = 1

Example Layout

# CONSTANTS
# =================================================================================================
 
# Slots
const BRIDGE_ID_SLOT = word("miden::agglayer::faucet")
const SLOT_ACCOUNT_ID = word("account::id")
 
# Memory pointers
const ASSET_OFF = 0
const AMOUNT_OFF = 1
 
# validate_note locals
const validate_note_NOTE_IDX_LOC = 0
const validate_note_ASSET_LOC = 1
 
# process_input locals
const process_input_INPUT_PTR_OFF = 0
const process_input_LEN_OFF = 1
 
# ERRORS
# =================================================================================================
 
const ERR_BRIDGE_NOT_MAINNET = "bridge not mainnet"
const ERR_UNAUTHORIZED = "unauthorized"
const ERR_NOTE_NOT_FOUND = "note not found"
 
# PUBLIC INTERFACE
# =================================================================================================
 
pub proc validate_note
    ...
end

Validation Checklist

• [ ] Errors in dedicated section, placed after constants
• [ ] All constants defined at top of file
• [ ] Non-error constants grouped by topic with blank lines between sections
• [ ] Memory pointers (shared/global) use descriptive names without procedure prefix
• [ ] Memory locals offsets prefixed with procedure name
• [ ] Spaces around = in all constant definitions
• [ ] Section comments used to label topic groups