0xMiden/protocol

advice-provider-hygiene

Use when writing kernel, account, or note MASM code that reads from or writes to the advice provider (advice stack / advice map) — validate advice data.

concise-pr-and-issue-descriptions

Keep PR and issue descriptions short and decision-focused. Use when writing or editing a pull request body or a GitHub issue.

concise-changelog-entries

Keep CHANGELOG.md entries to a single concise sentence. Use when adding or editing entries in CHANGELOG.md.

cheap-masm-equivalents

Use when writing or reviewing MASM hot paths or loops — prefer the cheaper equivalent: loop counters and pointers on the operand stack instead of procedure locals, `neq.0` over `gt.0` for non-zero checks, `cdrop` over an `if/else` selecting between two…

masm-locals-over-globals

Use when a MASM procedure needs temporary scratch storage — keep it in procedure-local memory so it cannot collide in a shared global region.

masm-proc-type-signatures

Enforce type-signature conventions for public Miden Assembly (.masm) procedures. Use when adding, editing, or reviewing a `pub proc` signature — parameter and return types, semantic type aliases, struct/array/tuple types, and how the signature maps onto the…

masm-inline-comments

Enforce inline commenting conventions for Miden Assembly (.masm) files. Use when editing, reviewing, or creating .masm files.

masm-doc-comments

Enforce doc comment conventions for Miden Assembly (.masm) procedures. Use when editing, reviewing, or creating .masm procedures, especially when documenting inputs, outputs, panic conditions, or invocation types.

assert-specific-error-in-tests

Use when writing a Rust test that exercises a failure path or a MASM test that expects a `panic` / `assert` — assert on the specific expected error variant or error code.

checked-arithmetic

Use when writing Rust arithmetic on amounts or other quantities derived from external/user input — guard against silent overflow.

conversion-method-naming

Use when naming a conversion or accessor method in Rust — follow the Rust API naming conventions for the method's cost and ownership.

decouple-component-from-storage

Use when writing a MASM procedure inside a reusable account component that accesses account storage — receive the storage slot as a parameter so the component is portable across storage layouts.

domain-newtypes-over-primitives

Use when introducing API parameters, struct fields, or return types that carry a domain value — represent them with a domain newtype that enforces their invariants.

felt-construction

Use when constructing a `Felt` from a numeric value in Rust — avoid silently truncating values that may exceed the field modulus.

intra-doc-links

Use when writing or editing a Rust doc comment that references a type, method, or module — link the reference so renames are caught by rustdoc.

lowercase-error-messages

Use when writing or editing a Rust error message, panic/assert string, or MASM `ERR_*` constant — follow the Rust convention for error-message casing and punctuation.

masm-error-constants

Use when adding or editing MASM `assert*` / `panic` instructions — give every assertion a descriptive named error code.

masm-explicit-stack-inputs

Use when defining the interface for a new MASM procedure — keep its inputs explicit on the stack so the signature reflects what it consumes.

masm-named-literals

Use when writing or editing MASM or Rust code that contains meaningful numeric literals — promote them to named constants with a single source of truth.

masm-rust-constant-parity

Use when changing a numeric or string constant in Rust or MASM that has a counterpart on the other side — keep the two definitions from drifting apart.

non-exhaustive-public-types

Use when defining a public `enum` or `struct` in a library crate that may gain variants or fields later — keep future additions from being breaking changes.

parametrize-related-tests

Use when writing two or more tests that differ only by inputs or expected outputs — collapse the duplication into parameterized cases.

preserve-error-source

Use when defining a new error variant or wrapping a lower-level error — keep the underlying error's source chain intact.

private-fields-with-accessors

Use when adding a public struct or changing a field's visibility in a Rust library crate — keep fields encapsulated so the layout can evolve without breaking callers.

return-error-not-panic

Use when writing a public Rust API, a deserialization path, or any code reachable from untrusted input — surface recoverable failures as a `Result`.

u32-assert-before-u32-ops

Use when writing MASM `u32*` instructions on values from user input or untrusted sources — ensure the operands are valid u32s first.

use-bon-builder

Use when introducing a Rust type whose constructor takes more than ~3 optional or named parameters — give it a generated builder instead of hand-written boilerplate.

use-test-fixtures

Use when a Rust or MASM test needs to construct an account, note, transaction, or other domain object — build it with the existing test fixtures.

validate-in-constructor

Use when writing or reviewing a Rust constructor, `try_new`, or builder `build` — centralize validation so every instance is valid by construction.

workspace-shared-dependencies

Use when adding or modifying a dependency in a crate's `Cargo.toml` that is or may become shared by multiple workspace crates — keep its version defined in one place.

masm-constants

Enforce constant definition and organization conventions for Miden Assembly (.masm) files. Use when editing, reviewing, or creating .masm files that define or use constants.

masm-file-structure

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

masm-padding

Enforce stack padding conventions for Miden Assembly (.masm) procedures based on invocation type (call vs exec). Use when editing, reviewing, or creating .masm procedures, especially those with Invocation annotations.