Add Build docs for Miden Assembly (MASM)
- 主要语言
- TypeScript
- 星标
- 10
- 派生
- 50
- 平均合并
- 22 天 23 小时
- 30 天内合并 PR
- 1
描述
## Context
The Build section currently has a Rust-first **Smart Contracts** path, while MASM appears mostly through tutorials, migration notes, playground links, and lower-level reference material. Developers who write account components, note scripts, transaction scripts, or custom libraries in MASM need a dedicated authoring path inside Smart Contracts.
This is also important for the planned Miden Standards docs: `miden-standards` is used both through Rust APIs and through direct MASM imports such as `miden::standards::*`. Standards docs should not carry the full burden of teaching MASM from scratch.
Related issues:
- `0xMiden/docs#287` tracks Build-facing docs for Miden standards.
- `0xMiden/docs#286` tracks renaming **Core Concepts** to **Reference**.
- `0xMiden/docs#289` tracks the Rust authoring path and compiler maturity warning.
## Recommendation
Add **Miden Assembly (MASM)** as a first-class authoring path under **Build → Smart Contracts**.
Framing:
- **Smart Contracts** is the domain.
- **Rust** and **MASM** are authoring paths for smart-contract code.
- MASM is also used for note scripts, transaction scripts, helper libraries, and direct standards imports, but these are still part of the smart-contract authoring workflow on Miden.
This should be a practical authoring guide, not a replacement for the VM/assembler reference. The Build section should answer: "How do I write, assemble, test, debug, and use MASM in Miden smart contracts and scripts?" Reference docs should answer: "What are the exact instructions, contexts, kernel APIs, and library procedure contracts?"
## Proposed information architecture
Recommended placement:
- `builder/smart-contracts/masm/index.md`
- `builder/smart-contracts/masm/project-structure.md`
- `builder/smart-contracts/masm/account-components.md`
- `builder/smart-contracts/masm/note-scripts.md`
- `builder/smart-contracts/masm/transaction-scripts.md`
- `builder/smart-contracts/masm/imports-and-libraries.md`
- `builder/smart-contracts/masm/stack-and-memory.md`
- `builder/smart-contracts/masm/testing-and-debugging.md`
- `builder/smart-contracts/masm/common-errors.md`
The broader Smart Contracts section can then expose three sibling authoring/building areas:
- Rust-authored smart contracts
- MASM-authored smart contracts and scripts
- Miden Standards, usable from both Rust and MASM
## Content to cover
Minimum first pass:
- What MASM is and when to write MASM directly instead of Rust.
- How Rust smart-contract authoring compiles down to MASM.
- How MASM code is organized as modules/libraries.
- How to import protocol and standards modules.
- How to write account components with account context constraints.
- How to write note scripts with `@note_script`.
- How to write transaction scripts.
- Stack discipline, word ordering, memory conventions, and common pitfalls.
- How to assemble and test MASM snippets locally.
- Debugging workflow and error interpretation.
- Cross-links to VM reference, protocol library reference, and Miden Standards docs.
## Relationship to Miden Standards docs
The Standards Build docs should show small MASM examples for standard imports and calls, but the MASM section should teach the underlying mechanics:
- module paths and imports
- stack inputs/outputs
- account/note/transaction contexts
- assembler project layout
- validation/debugging workflow
This keeps Standards docs focused on reusable building blocks and keeps MASM docs focused on the authoring model.
## Validation requirements
All MASM examples added to Build docs should be validated in a brand-new Docker environment before the PR is opened.
Expected validation path:
- Assemble MASM snippets against the appropriate protocol/standards library for the target version.
- Run any transaction/account/note script examples in the smallest available harness when assembly alone is not sufficient.
- Add or extend a docs-test harness so MASM snippets can be re-run in Docker.
- Run the docs build after ingestion and confirm no new broken links or anchors.
- Update versioned docs when examples describe v0.14 APIs or behavior.
## Scope
- Add the Build-facing MASM docs under Smart Contracts.
- Add sidebar entries and cross-links from Smart Contracts, Tutorials, Standards, Playground, and Migration pages.
- Keep examples executable and grounded in shipped APIs.
## Out of scope
- Replacing the VM instruction reference.
- Moving canonical protocol/standards reference docs into the docs repo.
- Documenting every protocol or standards procedure in the Build MASM guide.
贡献指南
评估
这个 Issue 还没有评估数据。