Context
The public docs mention standard account components, standard notes, and policies in scattered places, but there is no dedicated Build guide for the reusable functionality exposed by miden-standards.
This matters because app developers need a practical map of the standard building blocks before they decide whether to compose them, extend them, or write custom Rust/MASM account logic.
Related context:
0xMiden/project-template is a Rust-first Miden smart contract template: contracts/ contains Rust account components, note scripts, and transaction scripts; integration/ contains MockChain tests and client-side scripts.
0xMiden/docs#288 tracks Miden Assembly (MASM) as a dedicated authoring path under Build → Smart Contracts.
0xMiden/docs#289 tracks the Rust authoring path and compiler maturity warning.
0xMiden/docs#286 tracks renaming Core Concepts to Reference so spec/reference material has a clearer home.
0xMiden/protocol#2835 starts separating protocol docs from standards reference material in the protocol repo.
0xMiden/docs#267 used the older "standard crates" framing. This issue is the actionable Builder-side issue for miden-standards.
Information architecture decision
Add a task-oriented Miden Standards section under Build → Smart Contracts.
Use Miden Standards or Standards as the visible label rather than Standard Libraries. "Standard Libraries" is easy to confuse with Rust's standard library or the MASM core/stdlib surface, while this section is specifically about interoperable account components, note types, faucet policies, and helpers from miden-standards.
The target Smart Contracts IA should treat these as sibling paths:
Smart Contracts
- Overview
- Rust
- Miden Assembly
- Miden Standards
Framing:
- Smart Contracts is the domain.
- Rust and Miden Assembly are authoring paths.
- Miden Standards are reusable building blocks used from both authoring paths.
Do not put Standards under Rust or MASM, and do not add a separate generic Building Blocks section for this pass. The shared conceptual model belongs in the Smart Contracts overview and Reference/Core Concepts pages; Builder pages should stay task-oriented.
Proposed Standards pages
Minimum shippable first pass:
builder/smart-contracts/standards/index.md
- What
miden-standards is.
- How standards relate to accounts, notes, transaction scripts, Rust APIs, and MASM modules.
- When to use a standard component or note instead of writing custom logic.
- Relationship to the future Reference/Protocol/Standards pages.
builder/smart-contracts/standards/account-components.md
- Basic wallet component.
- Authentication components.
- Access-control components.
- Faucet components.
- How components affect account interfaces and note compatibility.
- Include both Rust composition examples and MASM import/call pointers where relevant.
builder/smart-contracts/standards/standard-notes.md
- P2ID / P2IDE.
- SWAP / PSWAP where available for the target version.
- MINT / BURN notes.
- Standard note attachments and network-account target patterns where relevant.
- Show Rust note constructors and link to the MASM modules/procedures behind the note scripts.
builder/smart-contracts/standards/faucets-and-policies.md
- Fungible faucet standards.
- Mint, burn, send, and receive policies where available for the target version.
- Owner-controlled vs auth-controlled / authority-controlled models.
- Practical guidance on choosing a policy model.
Follow-up pages can split out multisig/guardian auth, token metadata, direct MASM import patterns, and deeper interface details if the first pass gets too large.
Versioning notes
next and v0.14 differ materially.
- v0.14 standards include
BasicFungibleFaucet, NetworkFungibleFaucet, Ownable2Step, single-sig/multisig auth, mint policies, and standard notes P2ID/P2IDE/SWAP/MINT/BURN.
next adds/reworks parts of the surface, including unified FungibleFaucet, RBAC/authority, network-account auth, richer token policies, and PSWAP.
Update versioned docs only with content that is valid for the versioned release. Do not backport next-only APIs into v0.14 pages unless they are clearly marked as unavailable there.
Content principles
- Build docs should answer: "How do I use this safely in an app?"
- Keep Rust and MASM entry points close when they describe the same standard, but do not make the Standards section teach all of Rust or all of MASM.
- Do not duplicate full spec tables in Build. Link to protocol-owned standards reference once it exists.
- Prefer short working examples over prose-only explanations.
- Call out version-specific differences explicitly.
Validation requirements
Every Rust and MASM example added to the Build docs should be validated in a brand-new Docker environment before the PR is opened.
Expected validation path:
- Compile Rust examples against the target published crate versions for versioned v0.14 docs.
- Compile Rust examples against the appropriate local or
next sources for current/unstable docs when APIs differ.
- Assemble MASM examples against the appropriate protocol/standards library for the target version.
- Add or extend a docs-test harness so Rust snippets can be re-run with
cargo check and MASM snippets can be re-run with the assembler in Docker.
- Run the docs build after ingestion and confirm no new broken links or anchors.
Scope
- Add the Build-facing Standards docs under Smart Contracts.
- Add sidebar entries and cross-links from existing Smart Contracts, Accounts, Notes, Rust, MASM, and tutorial pages.
- Update the Smart Contracts landing copy so it no longer implies the whole section is Rust-only.
- Update versioned docs if the content describes v0.14 APIs.
- Keep examples small, executable, and grounded in shipped APIs.
Out of scope
- Moving canonical standards reference docs from
protocol into docs.
- Renaming Core Concepts / Reference navigation; tracked separately in
0xMiden/docs#286.
- Building the full Rust authoring path; tracked separately in
0xMiden/docs#289.
- Building the full MASM authoring path; tracked separately in
0xMiden/docs#288.
- Documenting every internal MASM procedure in Build pages.
Context
The public docs mention standard account components, standard notes, and policies in scattered places, but there is no dedicated Build guide for the reusable functionality exposed by
miden-standards.This matters because app developers need a practical map of the standard building blocks before they decide whether to compose them, extend them, or write custom Rust/MASM account logic.
Related context:
0xMiden/project-templateis a Rust-first Miden smart contract template:contracts/contains Rust account components, note scripts, and transaction scripts;integration/contains MockChain tests and client-side scripts.0xMiden/docs#288tracks Miden Assembly (MASM) as a dedicated authoring path under Build → Smart Contracts.0xMiden/docs#289tracks the Rust authoring path and compiler maturity warning.0xMiden/docs#286tracks renaming Core Concepts to Reference so spec/reference material has a clearer home.0xMiden/protocol#2835starts separating protocol docs from standards reference material in the protocol repo.0xMiden/docs#267used the older "standard crates" framing. This issue is the actionable Builder-side issue formiden-standards.Information architecture decision
Add a task-oriented Miden Standards section under Build → Smart Contracts.
Use Miden Standards or Standards as the visible label rather than Standard Libraries. "Standard Libraries" is easy to confuse with Rust's standard library or the MASM core/stdlib surface, while this section is specifically about interoperable account components, note types, faucet policies, and helpers from
miden-standards.The target Smart Contracts IA should treat these as sibling paths:
Framing:
Do not put Standards under Rust or MASM, and do not add a separate generic Building Blocks section for this pass. The shared conceptual model belongs in the Smart Contracts overview and Reference/Core Concepts pages; Builder pages should stay task-oriented.
Proposed Standards pages
Minimum shippable first pass:
builder/smart-contracts/standards/index.mdmiden-standardsis.builder/smart-contracts/standards/account-components.mdbuilder/smart-contracts/standards/standard-notes.mdbuilder/smart-contracts/standards/faucets-and-policies.mdFollow-up pages can split out multisig/guardian auth, token metadata, direct MASM import patterns, and deeper interface details if the first pass gets too large.
Versioning notes
nextand v0.14 differ materially.BasicFungibleFaucet,NetworkFungibleFaucet,Ownable2Step, single-sig/multisig auth, mint policies, and standard notes P2ID/P2IDE/SWAP/MINT/BURN.nextadds/reworks parts of the surface, including unifiedFungibleFaucet, RBAC/authority, network-account auth, richer token policies, and PSWAP.Update versioned docs only with content that is valid for the versioned release. Do not backport
next-only APIs into v0.14 pages unless they are clearly marked as unavailable there.Content principles
Validation requirements
Every Rust and MASM example added to the Build docs should be validated in a brand-new Docker environment before the PR is opened.
Expected validation path:
nextsources for current/unstable docs when APIs differ.cargo checkand MASM snippets can be re-run with the assembler in Docker.Scope
Out of scope
protocolintodocs.0xMiden/docs#286.0xMiden/docs#289.0xMiden/docs#288.