Documentation

[rodrigo-pino]

VM Docs

There is a great lack of documentation regarding Virtual Machines. The Whitepaper focus mostly on describing the state transitions but doesn't explain in great details other very important aspects such as builtins and hints. This causes that for proper developing of a VM devs have to scavenge for information on other implementations. Let's try to write a general documentation to alleviate this.

Check the current online docs here.

Tools for Docs

To achieve this we will be building on top of Docosaurus to write our documentation, visit their docs to know a little more about it. Also the use of grammarly is encouraged to avoid making common mistakes, it is free and can be installed as a plugin in your IDE of choice. Finally, ChatGPT can be helpful to enhance what you wrote and detect more common grammar mistakes but don't use to write your content though, it will be boringly written and probably inaccurate as well.

The Docs

We are going to divide the docs between two main sections: the fundamentals and everything else that surrounds it. I think it's best if the writing has a balanced focus between something easy to understand and math rigor.

The Fundamentals section will be structured as follows:

• [x] #328
  • Basically an introduction to the section. A small summary of what we'll see.
• [ ] VM Layout
  • Explain registers and memory. Also explain how are they relocated in proof mode.
  • There ample source material for this on the whitepaper. Let's perhaps explain it
• [ ] Basic Instructions
  • Explain each one of them
  • How they modify ap, and fp etc.
  • How does subtraction and addition work
• [x] #326
  • Explain each one of them
  • How bulitins perform complex operations at the cost of extra constraints when proving
• [ ] #327
  • Explain them
  • Why hints are only ran on sequencer/prover and not on the verifier

The Extras section will contain the following sections:

• [ ] Cairo Runner:
  • The runner is basically the glue between VM and compiled file
  • Explain what it does
• [ ] Resources:
  • Explain how execution are limited by resources and how they are implemented
  • How resources protects Starknet

You can edit this section by going to "docs/docs", where you'll find the following project structure. Each file has a section associated with it, pick anyone you want.

docs/docs
├── intro.md
├── vm-extras
│   ├── resources.md
│   └── runner.md
└── vm-fundamentals
    ├── builtins.md
    ├── hints.md
    ├── instructions.md
    ├── intro.md
    └── layout.md

Discussion

If you think there some important info missing, or perhaps the documentation would be better structured in another way, please let us know and feel free to make a PR to address it!