0xMiden / 0xMiden/docs

Add Build docs for Miden Assembly (MASM)

Abierto
#288 0 comentarios 0 reacciones 0 asignados Ver en GitHub
documentation enhancement
Lenguaje dominante
TypeScript
Estrellas
10
Forks
50
Merge medio
22 d 23 h
PR fusionados (30 d)
1

Descripción

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

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

The issue proposes adding new documentation pages under `builder/smart-contracts/masm/`. Start by exploring the existing docs repository structure to understand the layout and style. The first step is to create the index.md file and outline the proposed sections. Validate MASM examples in a Docker environment as specified. Ensure new pages are linked in the sidebar and cross-referenced from existing tutorials and reference material.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
markdown, typescript
Área
documentation
Tipo de issue
Documentación
Dificultad
3/5
Tiempo estimado
1-2 días
Estado de actividad
Estancado
Claridad
Bien especificado
Aptitud para principiantes
65/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.