Merge pull request #103 from 0xPolygon/km/miden_vm_tweaks

Miden VM tweaks

docs/miden/architecture/accounts.md

@@ -51,7 +51,7 @@ An account vault can be reduced to a single hash which is the root of the sparse
 
 Interface for accounts. In Miden every account is a smart contract. It has an interface that exposes functions that can be called by note scripts. Functions exposed by the account have the following properties:
 
-* Functions are actually roots of [Miden program MASTs](https://0xpolygonmiden.github.io/miden-vm/user-docs/assembly/main.html) (i.e., a 32-byte hash). Thus, function identifier is a commitment to the code which is executed when a function is invoked.
+* Functions are actually roots of [Miden program MASTs](https://0xpolygonmiden.github.io/miden-vm/specification/assembly/main.html) (i.e., a 32-byte hash). Thus, function identifier is a commitment to the code which is executed when a function is invoked.
 * Only account functions have mutable access to an account's storage and vault. Therefore, the only way to modify an account's internal state is through one of the account's functions.
 * Account functions can take parameters and can create new notes.
 

docs/miden/architecture/notes.md

@@ -21,7 +21,7 @@ Asset container for a note. A note vault can contain up to `255` assets stored i
 
 ### Script
 
-Unlike an account, a note has a single executable script. This script will be executed in a [transaction](transactions.md). This script is also the root of a [Miden program MAST](https://0xpolygonmiden.github.io/miden-vm/user-docs/assembly/main.html). A script is always executed in the context of a single account, and thus, may invoke account's functions. A note's script can call zero or more of an account's function.
+Unlike an account, a note has a single executable script. This script will be executed in a [transaction](transactions.md). This script is also the root of a [Miden program MAST](https://0xpolygonmiden.github.io/miden-vm/specification/assembly/main.html). A script is always executed in the context of a single account, and thus, may invoke account's functions. A note's script can call zero or more of an account's function.
 
 !!! note
     Since code in Miden is expressed as MAST, every function is a commitment to the underlying code. The code cannot change unnoticed to the user because its hash would change.*

docs/miden/index.md

@@ -75,7 +75,7 @@ hide:
          </a>
       </div>
       <div class="grid-item">
-         <a href="https://0xpolygonmiden.github.io/miden-vm/intro/main.html">
+         <a href="./vm/intro/">
             <div class="product-list-item-header">
                <div class="feature-card-heading">Miden VM</div>
             </div>

docs/miden/vm/design/chiplets/kernel_rom.md → docs/miden/vm/architecture/chiplets/kernel_rom.md

@@ -1,4 +1,4 @@
-The kernel ROM enables executing predefined kernel procedures. These procedures are always executed in the root context and can only be accessed by a `SYSCALL` operation. The chiplet tracks and enforces correctness of all kernel procedure calls as well as maintaining a list of all the procedures defined for the kernel, whether they are executed or not. More background about Miden VM execution contexts can be found [here](../../user-docs/assembly/execution-contexts.md).
+The kernel ROM enables executing predefined kernel procedures. These procedures are always executed in the root context and can only be accessed by a `SYSCALL` operation. The chiplet tracks and enforces correctness of all kernel procedure calls as well as maintaining a list of all the procedures defined for the kernel, whether they are executed or not. More background about Miden VM execution contexts can be found [here](../../specification/assembly/execution-contexts.md).
 
 ## Kernel ROM trace
 

docs/miden/vm/design/programs.md → docs/miden/vm/architecture/programs.md

@@ -35,7 +35,7 @@ A *dyn* block must always have one (dynamically-specified) child. Thus, it canno
 
 ### Call block
 
-A **call** block is used to describe a function call which is executed in a [user context](../user-docs/assembly/execution-contexts.md). When the VM encounters a *call* block, it creates a new user context, then executes a program which hashes to the target specified by the *call* block in the new context. Thus, in order to execute a *call* block, the VM must be aware of a program with the specified hash. Otherwise, the execution fails. At the end of the *call* block, execution returns to the previous context.
+A **call** block is used to describe a function call which is executed in a [user context](../specification/assembly/execution-contexts.md). When the VM encounters a *call* block, it creates a new user context, then executes a program which hashes to the target specified by the *call* block in the new context. Thus, in order to execute a *call* block, the VM must be aware of a program with the specified hash. Otherwise, the execution fails. At the end of the *call* block, execution returns to the previous context.
 
 
 When executing a *call* block, the VM does the following:
@@ -49,7 +49,7 @@ A *call* block does not have any children. Thus, it must be leaf node in the tre
 
 ### Syscall block
 
-A **syscall** block is used to describe a function call which is executed in the [root context](../user-docs/assembly/execution-contexts.md). When the VM encounters a *syscall* block, it returns to the root context, then executes a program which hashes to the target specified by the *syscall* block. Thus, in order to execute a *syscall* block, the VM must be aware of a program with the specified hash, and that program must belong to the kernel against which the code is compiled. Otherwise, the execution fails. At the end of the *syscall* block, execution returns to the previous context.
+A **syscall** block is used to describe a function call which is executed in the [root context](../specification/assembly/execution-contexts.md). When the VM encounters a *syscall* block, it returns to the root context, then executes a program which hashes to the target specified by the *syscall* block. Thus, in order to execute a *syscall* block, the VM must be aware of a program with the specified hash, and that program must belong to the kernel against which the code is compiled. Otherwise, the execution fails. At the end of the *syscall* block, execution returns to the previous context.
 
 When executing a *syscall* block, the VM does the following:
 1. Checks if a *syscall* is already being executed and fails if so.

docs/miden/vm/intro/overview.md

@@ -15,7 +15,7 @@ Miden VM comes with a default implementation of the host interface (with an in-m
 
 ## Writing programs
 
-Our goal is to make Miden VM an easy compilation target for high-level languages such as Rust, Move, Sway, and others. We believe it is important to let people write programs in the languages of their choice. However, compilers to help with this have not been developed yet. Thus, for now, the primary way to write programs for Miden VM is to use [Miden assembly](../user-docs/assembly/index.md).
+Our goal is to make Miden VM an easy compilation target for high-level languages such as Rust, Move, Sway, and others. We believe it is important to let people write programs in the languages of their choice. However, compilers to help with this have not been developed yet. Thus, for now, the primary way to write programs for Miden VM is to use [Miden assembly](../specification/assembly/index.md).
 
 While writing programs in assembly is far from ideal, Miden assembly does make this task a little bit easier by supporting high-level flow control structures and named procedures.
 
@@ -26,15 +26,15 @@ External inputs can be provided to Miden VM in two ways:
 1. Public inputs can be supplied to the VM by initializing the stack with desired values before a program starts executing. Any number of stack items can be initialized in this way, but providing a large number of public inputs will increase the cost for the verifier.
 2. Secret (or nondeterministic) inputs can be supplied to the VM via the [*advice provider*](#nondeterministic-inputs). There is no limit on how much data the advice provider can hold.
 
-After a program finishes executing, the elements remaining on the stack become the outputs of the program. Since these outputs will be public inputs for the verifier, having a large stack at the end of execution will increase cost to the verifier. Therefore, it's best to drop unneeded output values. We've provided the [`truncate_stack`](../user-docs/stdlib/sys.md) utility function in the standard library for this purpose.
+After a program finishes executing, the elements remaining on the stack become the outputs of the program. Since these outputs will be public inputs for the verifier, having a large stack at the end of execution will increase cost to the verifier. Therefore, it's best to drop unneeded output values. We've provided the [`truncate_stack`](../specification/stdlib/sys.md) utility function in the standard library for this purpose.
 
 The number of public inputs and outputs of a program can be reduced by making use of the advice stack and Merkle trees. Just 4 elements are sufficient to represent a root of a Merkle tree, which can be expanded into an arbitrary number of values.
 
-For example, if we wanted to provide a thousand public input values to the VM, we could put these values into a Merkle tree, initialize the stack with the root of this tree, initialize the advice provider with the tree itself, and then retrieve values from the tree during program execution using `mtree_get` instruction (described [here](../user-docs/assembly/cryptographic-operations.md#hashing-and-merkle-trees)).
+For example, if we wanted to provide a thousand public input values to the VM, we could put these values into a Merkle tree, initialize the stack with the root of this tree, initialize the advice provider with the tree itself, and then retrieve values from the tree during program execution using `mtree_get` instruction (described [here](../specification/assembly/cryptographic-operations.md#hashing-and-merkle-trees)).
 
 ### Stack depth restrictions
 
-For reasons explained [here](../design/stack/index.md), the VM imposes the restriction that the stack depth cannot be smaller than $16$. This has the following effects:
+For reasons explained [here](../architecture/stack/index.md), the VM imposes the restriction that the stack depth cannot be smaller than $16$. This has the following effects:
 
 - When initializing a program with fewer than $16$ inputs, the VM will pad the stack with zeros to ensure the depth is $16$ at the beginning of execution.
 - If an operation would result in the stack depth dropping below $16$, the VM will insert a zero at the deep end of the stack to make sure the depth stays at $16$.

docs/miden/vm/intro/usage.md

@@ -79,7 +79,7 @@ Currently, Miden VM can be executed with the following subcommands:
 * `run`: Executes a Miden assembly program and output the result, but will not generate a proof of execution.
 * `prove`: Executes a Miden assembly program, and will also generate a STARK proof of execution.
 * `verify`: Verifies a previously generated proof of execution for a given program.
-* `compile`: Compiles a Miden assembly program (i.e., build a program [MAST](../design/programs.md)) and outputs stats about the compilation process.
+* `compile`: Compiles a Miden assembly program (i.e., build a program [MAST](../architecture/programs.md)) and outputs stats about the compilation process.
 * `debug`: Instantiates a [Miden debugger](../tools/debugger.md) against the specified Miden assembly program and inputs.
 * `analyze`: Runs a Miden assembly program against specific inputs and will output stats about its execution.
 * `repl`: Initiates the [Miden REPL](../tools/repl.md) tool.
@@ -115,7 +115,7 @@ As described [here](overview.md#inputs-and-outputs) the Miden VM can consume pub
 !!! info
     Check out the [comparison example](https://github.com/0xPolygonMiden/examples/blob/main/examples/comparison.masm) to see how secret inputs work.
 
-After a program finishes executing, the elements that remain on the stack become the outputs of the program, along with the overflow addresses (`overflow_addrs`) that are required to reconstruct the [stack overflow table](../design/stack/index.md#overflow-table).
+After a program finishes executing, the elements that remain on the stack become the outputs of the program, along with the overflow addresses (`overflow_addrs`) that are required to reconstruct the [stack overflow table](../architecture/stack/index.md#overflow-table).
 
 ## Fibonacci example
 

docs/miden/vm/user-docs/assembly/code-organization.md → docs/miden/vm/specification/assembly/code-organization.md

@@ -48,7 +48,7 @@ end
 
 ### Dynamic procedure invocation
 
-It is also possible to invoke procedures dynamically - i.e., without specifying target procedure labels at compile time. There are two instructions, `dynexec` and `dyncall`, which can be used to execute dynamically-specified code targets. Both instructions expect [MAST root](../../design/programs.md) of the target to be provided via the stack. The difference between `dynexec` and `dyncall` is that `dyncall` will [change context](execution-contexts.md) before executing the dynamic code target, while `dynexec` will cause the code target to be executed in the current context.
+It is also possible to invoke procedures dynamically - i.e., without specifying target procedure labels at compile time. There are two instructions, `dynexec` and `dyncall`, which can be used to execute dynamically-specified code targets. Both instructions expect [MAST root](../../architecture/programs.md) of the target to be provided via the stack. The difference between `dynexec` and `dyncall` is that `dyncall` will [change context](execution-contexts.md) before executing the dynamic code target, while `dynexec` will cause the code target to be executed in the current context.
 
 Dynamic code execution in the same context is achieved by setting the top $4$ elements of the stack to the hash of the dynamic code block and then executing the following instruction:
 

docs/miden/vm/user-docs/assembly/execution-contexts.md → docs/miden/vm/specification/assembly/execution-contexts.md

@@ -5,7 +5,7 @@ All programs start executing in a *root* context. Thus, the main procedure of a
 While executing in a user context, we can request to execute some procedures in the root context. This can be done via the `syscall` instruction. The set of procedures which can be invoked via the `syscall` instruction is limited by the [kernel](#kernels) against which a program is compiled. Once the procedure called via `syscall` returns, the execution moves back to the user context from which it was invoked. The diagram below illustrates this graphically:
 
 <center>
-![context transitions](../../../../img/miden/vm/user-docs/assembly/execution_contexts/context_transitions.png)
+![context transitions](../../../../img/miden/vm/specification/assembly/execution_contexts/context_transitions.png)
 </center>
 
 ## Procedure invocation semantics
@@ -52,7 +52,7 @@ For user contexts we have the following:
 - The next $2^{30}$ words are reserved for memory locals of procedures executed in the same context (i.e., via the `exec` instruction).
 - The remaining address space has no special meaning.
 
-![user memory layout](../../../../img/miden/vm/user-docs/assembly/execution_contexts/user_mem_layout.png)
+![user memory layout](../../../../img/miden/vm/specification/assembly/execution_contexts/user_mem_layout.png)
 
 For the root context we have the following:
 
@@ -61,7 +61,7 @@ For the root context we have the following:
 - The next $2^{30}$ words are reserved for memory locals of procedures executed from within a `syscall`.
 - The remaining address space has no special meaning.
 
-![root memory layout](../../../../img/miden/vm/user-docs/assembly/execution_contexts/root_mem_layout.png)
+![root memory layout](../../../../img/miden/vm/specification/assembly/execution_contexts/root_mem_layout.png)
 
 For both types of contexts, writing directly into regions of memory reserved for procedure locals is not advisable. Instead, `loc_load`, `loc_store` and other similar dedicated instructions should be used to access procedure locals.
 

docs/miden/vm/user-docs/assembly/index.md → docs/miden/vm/specification/assembly/index.md

@@ -1,8 +1,8 @@
 Miden assembly is a simple, low-level language for writing programs for Miden VM. It stands just above raw Miden VM instruction set, and in fact, many instructions of Miden assembly map directly to raw instructions of Miden VM.
 
-Before Miden assembly can be executed on Miden VM, it needs to be compiled into a [Program MAST](../../design/programs.md) (Merkelized Abstract Syntax Tree) which is a binary tree of code blocks each containing raw Miden VM instructions.
+Before Miden assembly can be executed on Miden VM, it needs to be compiled into a [Program MAST](../../architecture/programs.md) (Merkelized Abstract Syntax Tree) which is a binary tree of code blocks each containing raw Miden VM instructions.
 
-![assembly_to_VM](../../../../img/miden/vm/user-docs/assembly/assembly_to_VM.png)
+![assembly_to_VM](../../../../img/miden/vm/specification/assembly/assembly_to_VM.png)
 
 As compared to raw Miden VM instructions, Miden assembly has several advantages:
 

docs/miden/vm/tools/repl.md

@@ -8,7 +8,7 @@ Miden REPL can be started via the CLI [repl](../intro/usage.md#cli-interface) co
 
 ## Miden assembly instruction
 
-All Miden instructions mentioned in the [Miden Assembly sections](../user-docs/assembly/index.md) are valid. One can either input instructions one by one or multiple instructions in one input.
+All Miden instructions mentioned in the [Miden Assembly sections](../specification/assembly/index.md) are valid. One can either input instructions one by one or multiple instructions in one input.
 
 For example, the below two commands will result in the same output.