masm-file-structure

name	masm-file-structure
description	Enforce file structure and section ordering for Miden Assembly (.masm) files. Use when editing, reviewing, or creating .masm files.

MASM File Structure

MASM files must follow a fixed section order. Use section headers with the long separator line:

# SECTION NAME
# =================================================================================================

Section Order

1. Imports – use statements only; no section header
2. Type aliases – type definitions
3. Constants – see the masm-constants skill for organization (non-error constants first, then errors)
4. Public interface – pub proc procedures that form the module API
5. Helper procedures – proc (non-pub) procedures used internally

Example Structure

use miden::agglayer::bridge::bridge_config
use miden::agglayer::bridge::leaf_utils
use miden::core::mem
use miden::core::word

# TYPE ALIASES
# =================================================================================================

type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
type DoubleWord = struct { word_lo: BeWord, word_hi: BeWord }
type MemoryAddress = u32

# CONSTANTS
# =================================================================================================

const PROOF_DATA_PTR = 0
const PROOF_DATA_WORD_LEN = 134

# ERRORS
# =================================================================================================

const ERR_BRIDGE_NOT_MAINNET = "bridge not mainnet"
const ERR_LEADING_BITS_NON_ZERO = "leading bits of global index must be zero"

# PUBLIC INTERFACE
# =================================================================================================

#! Main entry point. Computes the leaf value and verifies it.
#!
#! Inputs:  [LEAF_DATA_KEY, PROOF_DATA_KEY, pad(8)]
#! Outputs: [pad(16)]
#!
#! Invocation: call
pub proc verify_leaf_bridge
    exec.get_leaf_value
    exec.verify_leaf
end

# HELPER PROCEDURES
# =================================================================================================

#! Loads leaf data and computes the leaf value.
#!
#! Inputs:  [LEAF_DATA_KEY]
#! Outputs: [LEAF_VALUE[8]]
#!
#! Invocation: exec
proc get_leaf_value(leaf_data_key: BeWord) -> DoubleWord
    ...
end

#! Verifies leaf against Merkle proof.
#!
#! Inputs:  [LEAF_VALUE[8], PROOF_DATA_KEY]
#! Outputs: []
#!
#! Invocation: exec
proc verify_leaf
    ...
end

Guidelines

• Imports: One use per line; group by module. No blank lines between imports.
• Type aliases: Define shared types (e.g. DoubleWord, MemoryAddress) before constants or procedures.
• Constants: Follow the masm-constants skill.
• Public interface: Only pub proc; these are the module’s API. Order by importance or call flow.
• Helper procedures: Non-pub procedures that support the public interface. May include pub proc helpers (e.g. get_leaf_value) if they are used internally or re-exported, or used for unit tests.

When Sections Are Omitted

• No imports → start with type aliases or constants
• No type aliases → constants follow imports
• No helpers → public interface is the last section

Validation Checklist

• Imports at top (if any)
• Type aliases before constants and procedures
• Constants before procedures; errors subsection after non-error constants
• Public interface (pub proc) before helper procedures
• Section headers use # SECTION NAME and # ===... separator