Miden Concepts

Core Concepts

Accounts

Each account is an independent smart contract containing:

• Code — Immutable logic compiled from Rust components
• Storage — Up to 255 slots (Value or StorageMap)
• Vault — Holds fungible and non-fungible assets
• Nonce — Incremented with each state change
• ID — Unique identifier (prefix + suffix, 2 Felts)

Accounts are composed from components — reusable Rust modules annotated with #[component].

Notes

Notes are UTXO-like messages for asynchronous inter-account communication. A note contains:

• Script — Logic that executes when the note is consumed
• Inputs — Data passed to the script (Vec<Felt>)
• Assets — Fungible/non-fungible tokens attached to the note
• Metadata — Sender, tag, note type (public/private)

Notes are created as output notes by one transaction and consumed as input notes by another.

Transactions

A transaction is a single-account state transition with 4 phases:

1. Consume input notes (execute their scripts against the account)
2. Execute transaction script (optional, for one-off logic)
3. Update account state (storage, vault, nonce)
4. Produce output notes (for other accounts to consume later)

Important: A two-party transfer (Alice sends Bob tokens) requires TWO transactions:

1. Alice's transaction creates a P2ID note with tokens attached
2. Bob's transaction consumes that note, receiving the tokens

Assets

• Fungible: [amount, 0, faucet_suffix, faucet_prefix] (1 Word)
• Non-fungible: Unique token tied to a faucet account
• Assets live in account vaults and move between accounts via notes
• Created by faucet accounts using faucet::create_fungible_asset() or faucet::mint()

Felt and Word

• Felt: Field element in the Goldilocks prime field (p = 2^64 - 2^32 + 1). The fundamental data unit.
• Word: Array of 4 Felts (32 bytes). Used for cryptographic hashes, storage keys, account IDs.

WARNING: Felt arithmetic is modular. Subtraction wraps around the prime. Always validate with .as_u64() before subtracting. See the rust-sdk-pitfalls skill for details.

Standard Note Patterns

Development Model

Developer writes Rust → Compiler produces MASM → VM executes and proves

Three contract types:

• #[component] — Account logic and storage (can have multiple per account)
• #[note] — Note script (executes when consumed)
• #[tx_script] — One-off transaction logic

Contracts are tested locally with MockChain (no network needed) and deployed via miden-client.

Key Design Decisions for App Architects

1. One account per service — Each bank, vault, or DEX pool is a separate account
2. Notes for communication — Use deposit/withdraw/request notes instead of direct calls
3. Storage for state — Use Value for flags, StorageMap for mappings
4. Privacy by default — Choose NoteType::Public only when discoverability is needed
5. Components for reuse — Standard wallet, auth, and faucet components compose into accounts