Skip to content

Add Build docs for Miden standards #287

@BrianSeong99

Description

@BrianSeong99

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions