Rust Sdk Pitfalls

P2: Felt Comparison Operators Are Misleading for Quantity Logic

Severity: High — silently produces incorrect results

<, >, <=, >= on Felt values compare field elements, which differs from natural number ordering. In protocol-level code working with field elements, these comparisons may be intentional. For business logic (balances, amounts, counts), the results are misleading.

// MISLEADING for business logic — compares field elements
if balance > threshold { ... }

// CORRECT for business logic — compare as integers
if balance.as_u64() > threshold.as_u64() { ... }

Rule: For quantity/business logic, ALWAYS convert to .as_u64() before using comparison operators.

P3: Function Argument Limit (4 Words / 16 Felts)

Severity: Medium — causes compilation errors

Functions can receive at most 4 Words (16 Felts) as arguments.

// PROBLEM — too many arguments
fn process(a: Word, b: Word, c: Word, d: Word, e: Word) { ... } // > 4 Words!

// SOLUTION — pass fat types by reference
fn process(a: &Word, b: &Word, c: &Word, d: &Word, e: &Word) { ... }

P4: Storage Slot Naming Convention

Severity: Medium — causes silent zero returns in tests

Storage slot names follow a strict pattern. Getting it wrong returns zero silently.

Pattern: miden::component::[snake_case(package)]::[field_name]

Conversion rule: Replace : and - with _ in the package name from [package.metadata.component] package = "...".

P5: No-std Environment

Severity: Medium -- causes compilation errors

All contract code must be #![no_std]. Forgetting this or using std types causes build failures.

Required at the top of every contract file: See any contract in contracts/ for the correct pattern (#![no_std] + #![feature(alloc_error_handler)]).

For heap allocation (Vec, String, Box):

extern crate alloc;
use alloc::vec::Vec;

P6: Asset Word Layout

Severity: Medium — creates invalid assets

Fungible assets have a specific Word layout. Getting the order wrong creates invalid assets or reads wrong amounts.

Asset Word: [amount, 0, faucet_suffix, faucet_prefix]
              [0]   [1]      [2]            [3]

// Reading amount from an asset
let amount = asset.inner[0];

// Constructing asset key for storage (including faucet identity)
let key = Word::from([
    depositor.prefix,
    depositor.suffix,
    asset.inner[3],  // faucet prefix
    asset.inner[2],  // faucet suffix
]);

P7: P2ID Note Root Hardcoding

Severity: Low-Medium — breaks after miden-standards updates

Creating P2ID output notes requires the MAST root digest of the P2ID script. This is typically hardcoded as a constant.

For any note that is being created within the compiler code, the MAST root digest is needed. Below you find the example of a P2ID note

fn p2id_note_root() -> Digest {
    Digest::from_word(Word::new([
        Felt::from_u64_unchecked(13362761878458161062),
        Felt::from_u64_unchecked(15090726097241769395),
        Felt::from_u64_unchecked(444910447169617901),
        Felt::from_u64_unchecked(3558201871398422326),
    ]))
}

Risk: If miden-standards updates the P2ID script, this digest becomes invalid and withdrawals silently fail.

Mitigation: Use P2idNote::script_root() from miden-standards if available, or verify the hardcoded root matches the current version after dependency updates.

NoteType for P2ID: P2ID output notes created in contract code should use the private note type value via NoteType::from(felt!(2)) (see P8). Using the public note type triggers an opaque "missing details in advice provider" error at execution time. See miden-bank withdraw for the working pattern.

P8: NoteType Variants Unavailable in Compiler SDK

Severity: Medium -- causes compilation errors

Named enum variants (NoteType::Private, NoteType::Public, NoteType::Encrypted) don't exist in contract code. Construct via NoteType::from():

See miden-bank bank-account for NoteType::from(note_type) usage.

P9: Note Scripts Cannot Call Native Account Functions

Severity: High -- causes runtime failures

Note scripts cannot call native_account::add_asset() or other native_account:: functions directly. The kernel's authenticate_account_origin check rejects these calls from a note context. Instead, note scripts must call an account component method, which then calls native_account::add_asset() internally.

See miden-bank deposit-note for the correct pattern: the note script calls bank_account::deposit(), which internally calls native_account::add_asset().

P10: Note Inputs Are Immutable After Creation

Severity: Low -- causes incorrect architecture

Note inputs (active_note::get_storage()) are baked at note creation time and cannot be modified after creation. Design note input layouts carefully before deployment.

Quick Reference