0xmiden/compiler/rust-sdk-source-guide

Advanced Miden Development: Source-Guided Context Engineering

Development Approach

1. Plan Mode First

For any non-trivial smart contract application, start in Plan Mode before writing code.

• Explore Miden source repos to understand existing patterns
• Design the account/note architecture and present it to the user before implementing
• Identify which standard components can be reused vs what needs to be custom
• Map out the note flow: which accounts exist, what notes flow between them, what storage each needs

Rule of thumb: if the task involves more than one contract or a pattern not covered by the basic skills, plan first.

2. Verification-Driven Development

This is the single highest-leverage practice for AI-assisted Miden development.

Build loop: After every contract edit, run cargo miden build --manifest-path contracts/<name>/Cargo.toml --release from the project root (adjust the path to your contract layout). With the midenup miden wrapper, run miden build --release from the contract directory instead: miden build --manifest-path ... alone does not select that contract from the workspace root. The output is a .masp package written under <target_dir>/<profile>/. If your project has a build hook configured, it may run this automatically. If the build fails:

1. Read the error message
2. Translate obvious SDK/compiler errors first:

• .as_u64() -> .as_canonical_u64()
• Recipient::compute(...) -> note::build_recipient(...)
• Value -> StorageValue<T>
• StorageMap -> StorageMap<K, V>
• active_note::get_assets() -> active_note::get_initial_assets()
• a trait method that a note or tx script cannot reach -> it is missing #[account_procedure]

1. Search the source repos for a working example of the pattern that failed
2. Adapt the working pattern to your use case
3. Rebuild

Test loop: Write tests alongside contracts. Run full repo checks with cargo test — or make test if the repo ships a GNU Makefile. In the protocol repo the test target runs cargo nextest run --profile default --cargo-profile test-dev --features concurrent,testing,std (siblings: test-dev, test-release / testr, test-docs, lint, clippy, format, doc). cargo make test needs a Makefile.toml configuring cargo-make; among the referenced repos only the compiler ships one — protocol, the client and the VM each ship a GNU Makefile and no Makefile.toml, while the compiler ships a Makefile.toml and no GNU Makefile. When tests fail:

1. Check the error — is it a build error, a runtime assertion, or a proof failure?
2. For assertion failures: check felt arithmetic (modular wrapping), storage slot naming, and whether the call is legal in its runtime context (output_note::create is account-context-only; incr_nonce() is auth-procedure-only)
3. For unexpected behavior: compare your code against the closest working example in source repos

Never submit code that doesn't compile and pass tests. The verification loop is your quality guarantee.

3. Context Engineering with Source Repos

The basic skills (rust-sdk-patterns, rust-sdk-testing-patterns, miden-concepts, rust-sdk-pitfalls) cover standard patterns. For anything beyond those patterns, Miden's source repositories are the knowledge base.

How to use source repos effectively:

• Don't load entire repos into context. Use sub-agents to explore — they search, read relevant files, and summarize findings without filling the main conversation context.
• Read source files only when you need a specific answer (progressive disclosure)
• Look for working examples first, then adapt. Working code that compiles is more reliable than documentation.
• When you find a useful pattern in source, extract just what you need — the exact API call, the exact data layout, the exact test setup.
• Start API questions at compiler/sdk/sdk/MIGRATION.md. Its ## Unreleased section is the authoritative, hand-written list of what changed on the Rust contract surface, with before/after code for each break. compiler/sdk/CHANGELOG.md is the companion. For an exact signature, go to compiler/sdk/base-sys/src/bindings/*.rs.

Using sub-agents for exploration:

• Launch an explore sub-agent with a specific question: "Find how the basic-wallet component creates an output note and moves an asset into it (compiler/examples/basic-wallet/src/lib.rs)"
• The sub-agent searches, reads the relevant files, and returns a focused summary
• Your main context stays clean for implementation

4. Iterative Multi-Stage Development

Break complex applications into stages. Complete each before starting the next:

1. Design (Plan Mode) — Architecture, note flows, storage design
2. Implement accounts — Component structs, storage, methods
3. Implement notes — Note scripts, cross-component calls, input parsing
4. Implement tx scripts — Initialization, admin operations
5. Write tests — MockChain setup, multi-step execution, state verification
6. Integrate — Connect pieces, end-to-end test

When stuck at any stage: search the source repos for a similar working pattern. Adapt it, don't guess.

Which Version Is Which

These are five independent release lines. Keep the client, protocol, and VM types aligned:

Follow the local manifests: contract crates use miden = { version = "0.15" } and matching miden-sdk-build-script-support = { version = "0.15" }. The integration crate uses protocol/standards/testing 0.18.0, VM/package crates in the 0.36 series, and the released client crates 0.18.0 from crates.io. Read both integration/Cargo.toml and Cargo.lock before changing version requirements; the lockfile records the resolved crate versions.

Keep the build tool out of the integration crate's dependency graph. The current project builds contracts out of process with midenup / cargo-miden via build_project_in_dir(...), then tests those packages with the client, standards, and miden-testing libraries resolved in Cargo.lock.

Miden Source Repository Map

Clone these repos alongside your project for reference. Claude will explore them when needed for advanced patterns.

# Required: protocol layer, standard note types and account components (crate: miden-protocol)
git clone --branch v0.18.0 https://github.com/0xMiden/protocol.git ../protocol
 
# Required: client API for deployment and chain interaction (crate: miden-client)
git clone --branch v0.18.0 https://github.com/0xMiden/rust-sdk.git ../miden-client
 
# Required: the Rust SDK macros and compiler; select the revision matching your guest SDK.
git clone https://github.com/0xMiden/compiler.git ../compiler
 
# Optional: the VM, assembler, and package format, when you need MASM or `.masp` internals
git clone --branch v0.36.3 https://github.com/0xMiden/miden-vm.git ../miden-vm

--depth 1 is intentionally omitted so you can check out other refs later if needed. For exact client parity, use the release tag matching the client version recorded in the project's Cargo.lock.

compiler/ — The Rust-to-MASM Compiler and the Guest SDK

Contains the SDK that powers the #[component_storage], #[component], #[account_procedure], #[auth_script], #[account], #[note], #[note_script] and #[tx_script] macros.

• `compiler/examples/` — exactly 12 working example projects, and the most reliable reference for

"how do I write X":

There is no faucet example here. For faucet reference use protocol/crates/miden-standards/src/account/faucets/fungible/mod.rs (the FungibleFaucet component) or the compiler's own compiler/tests/integration/src/sdk/base/faucet.rs binding test.

• `compiler/sdk/` — the guest SDK and the authoritative API reference. Whitelisted

for exploration:

• compiler/sdk/sdk/MIGRATION.md — start here; the ## Unreleased section is the current contract-surface

change list with before/after code

• compiler/sdk/CHANGELOG.md
• compiler/sdk/base-sys/src/bindings/ — the exact signature of every kernel binding

(active_account.rs, native_account.rs, active_note.rs, input_note.rs, output_note.rs, note.rs, faucet.rs, tx.rs, types.rs)

• compiler/sdk/base/src/types/storage.rs — StorageValue / StorageMap / WordKey / WordValue
• compiler/sdk/base-macros/src/ — macro behaviour and, importantly, the exact error messages

(component_macro/mod.rs, component_macro/storage.rs, component_macro/sibling.rs, foreign_account.rs, note.rs, script.rs, wit_world.rs)

• `compiler/tests/integration-network/src/mockchain/` — end-to-end multi-contract MockChain flows

(counter contract under three auth components, FPI in many shapes, asset transfer), including the live storage-slot-name strings in compiler/tests/integration-network/src/mockchain/support/helpers.rs.

WARNING: Do NOT explore the compiler's own internals — compiler/codegen/, compiler/hir/, compiler/hir-analysis/, compiler/hir-transform/, compiler/frontend/, compiler/midenc-compile/, compiler/midenc-session/ — they are implementation details that will confuse the agent and lead to incorrect code. The one narrow exception is compiler/frontend/wasm/src/component/ when you need the exact wording of a call-boundary (16-felt) diagnostic.

Explore when: Writing any new contract type, checking an exact binding signature, or finding working code for a pattern not covered by skills.

protocol/ — Protocol Layer and Standard Library