0xMiden / 0xMiden/docs

Add Build docs for Miden Assembly (MASM)

Đang mở
#288 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
documentation enhancement
Ngôn ngữ chính
TypeScript
Star
10
Fork
50
Merge trung bình
22 ngày 23 giờ
Pull request đã merge (30 ngày)
1

Mô tả

## 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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.