Merge branch 'km/miden_migration' of https://github.com/0xPolygon/pol…

…ygon-docs into dev

.vscode/settings.json

@@ -1,5 +1,7 @@
 {
     "cSpell.words": [
-        "Miden"
+        "Merkle",
+        "Miden",
+        "rollups"
     ]
 }

docs/miden/architecture/accounts.md

@@ -10,29 +10,33 @@ The diagram below illustrates basic components of an account. In Miden every acc
 
 In the above picture, you can see:
 
-* **Account ID →** a unique identifier of an account which does not change throughout its lifetime
-* **Storage →** user-defined data which can be stored in an account
-* **Nonce →** a counter which must be incremented whenever the account state changes
-* **Vault →** a collection of assets stored in an account
-* **Code →** a collection of functions which define the external interface for an account
+* **Account ID →** a unique identifier of an account which does not change throughout its lifetime.
+* **Storage →** user-defined data which can be stored in an account.
+* **Nonce →** a counter which must be incremented whenever the account state changes.
+* **Vault →** a collection of assets stored in an account.
+* **Code →** a collection of functions which define the external interface for an account.
 
 ### Account ID
-~63 bits (1 field element) long identifier for the account. The four most significant bits specify its [account type](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#account-types) - regular, immutable, faucet - and the [storage mode](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#account-storage-modes) - public or private. 
 
-### Account Storage
+~63 bits (1 field element) long identifier for the account. The four most significant bits specify its [account type](accounts.md#account-types) - regular, immutable, faucet - and the [storage mode](accounts.md#account-storage-modes) - public or private. 
+
+### Account storage
+
 Storage for user-defined data. `AccountStorage` is composed of two components.
 
 The first component is a simple sparse Merkle tree of depth `8` which is index addressable. This provides the user with `256` `Word` slots.
 
 Users requiring additional storage can use the second component a `MerkleStore`. It allows users to store any Merkle structures they need. The root of the Merkle structure can be stored as a leaf in a simple sparse Merkle tree. When `AccountStorage` is serialized it will check if any of the leafs in the simple sparse Merkle tree are Merkle roots of other Merkle structures. If any Merkle roots are found then the Merkle structures will be persisted in the `AccountStorage` `MerkleStore`.
 
 ### Nonce
+
 Counter which must be incremented whenever the account state changes. Nonce values must be strictly monotonically increasing and can be incremented by any value smaller than 2^{32} for every account update.
 
 ### Vault
+
 Asset container for an account.
 
-An account vault can contain an unlimited number of [assets](https://0xpolygonmiden.github.io/miden-base/architecture/assets.html). The assets are stored in a sparse
+An account vault can contain an unlimited number of [assets](assets.md). The assets are stored in a sparse
 Merkle tree as follows:
 
 * For fungible assets, the index of a node is defined by the issuing faucet ID, and the value
@@ -44,28 +48,31 @@ Merkle tree as follows:
 An account vault can be reduced to a single hash which is the root of the sparse Merkle tree.
 
 ### Code
+
 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.
 * 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.
 
-*Note: Since code in Miden is expresed as MAST, every function is a commitment to the underlying code. The code cannot change unnoticed to the user because its hash would change. Behind any MAST root there can only be `256` functions*
+!!! 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. Behind any MAST root there can only be `256` functions*
 
 ## Account creation
-For an account to exist it must be present in the [Account DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#account-database) kept by the Miden Node(s). However, new accounts can be created locally by users using a wallet.
 
-The process is as follows:
+For an account to exist it must be present in the [Account DB](state.md#account-database) kept by the Miden Node(s). However, new accounts can be created locally by users using a wallet.
 
-* Alice grinds a new Account ID (according to the account types) using a wallet
-* Alice's Miden Client requests the Miden Node to check if new Account ID already exists
-* Alice shares the new Account ID to Bob (eg. when Alice wants to receive funds)
-* Bob executes a transaction and creates a note that contains an asset for Alice
-* Alice consumes Bob's note to receive the asset in a transaction
-* Depending on the account storage mode (private vs. public) and transaction type (local vs. network) the Operator receives the new Account ID eventually and - if the transaction is correct - adds the ID to the Account DB
+The process is as follows:
 
+* Alice grinds a new Account ID (according to the account types) using a wallet.
+* Alice's Miden Client requests the Miden Node to check if new Account ID already exists.
+* Alice shares the new Account ID to Bob (eg. when Alice wants to receive funds).
+* Bob executes a transaction and creates a note that contains an asset for Alice.
+* Alice consumes Bob's note to receive the asset in a transaction.
+* Depending on the account storage mode (private vs. public) and transaction type (local vs. network) the Operator receives the new Account ID eventually and - if the transaction is correct - adds the ID to the Account DB.
 
 ## Account types
+
 There are four types of accounts in Miden:
 
 | | Regular updatable account | Regular immutable account | Faucet for fungible assets | Faucet for non-fungible assets |
@@ -75,7 +82,8 @@ There are four types of accounts in Miden:
 | **Most significant bits** | `00` | `01` | `10` | `11` |
 
 ## Account storage mode
-Account data - stored by the Miden Node - can be public, private, or encrypted. The third and fourth most significant bits of the account ID specifies whether the account data is public `00`, encrypted `01`, or private `11`.
+
+Account data - stored by the Miden node - can be public, private, or encrypted. The third and fourth most significant bits of the account ID specifies whether the account data is public `00`, encrypted `01`, or private `11`.
 
 * Accounts with **public state**, where the actual state is stored onchain. These would be similar to how accounts work in public blockchains. Smart contracts that depend on public shared state should be stored public on Miden, e.g., DEX contract.
 * Accounts with **private state**, where only the hash of the account is stored onchain. Users who want stay private and take care of their own data should choose this mode. The hash is defined as: `hash([account ID, 0, 0, nonce], [vault root], [storage root], [code root])`.

docs/miden/architecture/assets.md

@@ -17,7 +17,7 @@ Native assets are data structures that follow the Miden asset model (encoding, i
 
 ### Issuance
 
-Only specialized accounts called faucets can issue assets. Just like with regular accounts, anyone can create a faucet account. Faucets can issue only either fungible or non-fungible assets - but not both. The `faucet_id` identifies the faucet and is starts with a different sequence depending on the asset type, see [here](./accounts/#account-id). The faucet's code defines rules for how assets can be minted, who can mint them etc. Conceptually, faucet accounts on Miden are similar to ERC20 contracts on Ethereum. But, there is no ownership tracking in Miden faucets.
+Only specialized accounts called faucets can issue assets. Just like with regular accounts, anyone can create a faucet account. Faucets can issue only either fungible or non-fungible assets - but not both. The `faucet_id` identifies the faucet and is starts with a different sequence depending on the asset type, see [here](accounts.md/#account-id). The faucet's code defines rules for how assets can be minted, who can mint them etc. Conceptually, faucet accounts on Miden are similar to ERC20 contracts on Ethereum. But, there is no ownership tracking in Miden faucets.
 
 Faucets can create assets and immediately distribute them by producing notes. However, assets can also stay in the faucet after creation to be sent later, e.g., in a bundle. That way, one can mint a million NFTs locally in a single transaction and then send them out as needed in separate transactions in the future.
 
@@ -39,7 +39,7 @@ Examples of non-fungible assets are all NFTs, e.g., a DevCon ticket. The ticket'
 
 ### Storage
 
-[Accounts](./accounts) and [notes](./notes) contain asset vaults that are used to store assets. Accounts can keep unlimited assets in a [tiered sparse Merkle tree](../crypto-primitives/tsmt) called `account vault`. Notes can only store up to `255` distinct assets.
+[Accounts](accounts.md) and [notes](notes.md) contain asset vaults that are used to store assets. Accounts can keep unlimited assets in a [tiered sparse Merkle tree](../crypto-primitives/tsmt.md) called `account vault`. Notes can only store up to `255` distinct assets.
 
 <center>
 ![Asset storage](../../img/miden/architecture/asset/asset_storage.png){ width="50%" }

docs/miden/architecture/execution.md

@@ -8,7 +8,7 @@ Polygon Miden is an Ethereum rollup. It batches transactions - or more precisely
 
 Every transaction will result in a zkProof that attests to its correctness.
 
-As mentioned in [transactions](./transactions), there are two types of transactions: local and network. For every transaction there is a proof which is either created by the user in the Miden Client or by the Operator using the Miden Node.
+As mentioned in [transactions](transactions.md), there are two types of transactions: local and network. For every transaction there is a proof which is either created by the user in the Miden Client or by the Operator using the Miden Node.
 
 ## Transaction batching
 
@@ -37,6 +37,7 @@ A block produced by the Miden Node looks somewhat like this:
 * The block also contains full account and note data for public accounts and notes. For example, if account `123` is a public account which was updated, in the state updates section we'd have a records for it as `(123, 0x456..)`. The full new state of this account (which should hash to `0x456..`) would be included in a separate section.
 
 To verify that a block describes a valid state transition, we do the following:
+
 1. Compute hashes of public account and note states.
 2. Make sure these hashes match records in the *state updates* section.
 3. Verify the included ZKP against the following public inputs:

docs/miden/architecture/index.md

@@ -16,19 +16,19 @@ In Miden, there are accounts and notes which can hold assets. Accounts consume a
 
 ### Accounts
 
-[Accounts](./accounts) can hold assets and define rules how assets can be transferred. Accounts can represent users or autonomous smart contracts. This chapter describes the design, the storage types, and the creation of an account.
+[Accounts](accounts.md) can hold assets and define rules how assets can be transferred. Accounts can represent users or autonomous smart contracts. This chapter describes the design, the storage types, and the creation of an account.
 
 ### Notes
 
-[Notes](./notes) are messages that accounts send to each other. A note stores assets and a script that defines how this note can be consumed. This chapter describes the design, the storage types, and the creation of a note.
+[Notes](notes.md) are messages that accounts send to each other. A note stores assets and a script that defines how this note can be consumed. This chapter describes the design, the storage types, and the creation of a note.
 
 ### Assets
 
-[Assets](./assets) can be fungible and non-fungible. They are stored in the owner’s account itself or in a note. This chapter describes asset issuance, customization, and storage.
+[Assets](assets.md) can be fungible and non-fungible. They are stored in the owner’s account itself or in a note. This chapter describes asset issuance, customization, and storage.
 
 ### Transactions
 
-[Transactions](./transactions) describe production and consumption of notes by a single account. Executing a transaction always results in a STARK proof. This chapter describes the transaction design and the different transaction types.
+[Transactions](transactions.md) describe production and consumption of notes by a single account. Executing a transaction always results in a STARK proof. This chapter describes the transaction design and the different transaction types.
 
 ##### Accounts produce and consume notes to communicate 
 
@@ -37,13 +37,16 @@ In Miden, there are accounts and notes which can hold assets. Accounts consume a
 </center>
 
 ## State and Execution
+
 The state model captures all individual states of all accounts and notes. Finally, the execution model describes state progress in a sequence of blocks.
 
 ### State model
-[State](./state) describes everything that is the case at a certain point in time. Individual states of accounts or notes can be stored onchain and offchain. This chapter describes the three different state databases in Miden.
+
+[State](state.md) describes everything that is the case at a certain point in time. Individual states of accounts or notes can be stored onchain and offchain. This chapter describes the three different state databases in Miden.
 
 ### Execution model
-[Execution](./execution) describes how the state progresses - on an individual level via transactions and at the global level expressed as aggregated state updates in blocks. This chapter describes the execution model and how blocks are built.
+
+[Execution](execution.md) describes how the state progresses - on an individual level via transactions and at the global level expressed as aggregated state updates in blocks. This chapter describes the execution model and how blocks are built.
 
 ##### Operators capture and progress state 
 

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). 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/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.
 
 !!! 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.*
@@ -44,7 +44,7 @@ For every note the Miden operator stores metadata in the note DB. This metadata
 
 ## Note storage modes
 
-Similar to accounts, there are two storage modes for notes in Miden. Notes can be stored privately in the [Notes DB](./state/#note-database) with only the note hash. Or notes can be stored publicly with all data.
+Similar to accounts, there are two storage modes for notes in Miden. Notes can be stored privately in the [Notes DB](state.md/#note-database) with only the note hash. Or notes can be stored publicly with all data.
 
 Privately stored notes can only be consumed if the note data is known to the consumer. That means, there must be some off-chain communication to transmit the note's data from the sender to the recipient.
 
@@ -65,7 +65,7 @@ the VM.
 
 ## Note nullifier
 
-The nullifier is the note's index in the [Nullifier DB](./notes/#note-nullifier). The Nullifier DB stores the information whether a note was already consumed.
+The nullifier is the note's index in the [Nullifier DB](notes.md/#note-nullifier). The Nullifier DB stores the information whether a note was already consumed.
 
 The nullifier is computed as `hash(serial_num, script_hash, input_hash, vault_hash)`.
 
@@ -83,14 +83,14 @@ To know a note’s nullifier, one needs to know all details of the note. That me
 
 ## Note lifecycle
 
-For a note to exist it must be present in the [Notes DB](./state/#note-database) kept by the Miden node(s). New notes are being produced when executing a transaction. They can be produced locally by users in local transactions or by the operator in a network transaction.
+For a note to exist it must be present in the [Notes DB](state.md/#note-database) kept by the Miden node(s). New notes are being produced when executing a transaction. They can be produced locally by users in local transactions or by the operator in a network transaction.
 
-The lifcycle of a note is as follows:
+The life-cycle of a note is as follows:
 
-* A new note is produced when a transaction is executed - regardless of the transaction type
-* Operator will receive the note hash and if the note is public, it'll also receive the corresponding note's data
-* Operator verifies the correctness of the underlying transaction before adding the note hash to the Notes DB
-* The note can now be consumed in a seperate transaction - to consume the note, the note's data must be known
-* A note is consumed when the its nullifier in the [Nullifier DB](./state/#nullifier-database) is set to `1`
-* Operator will receive the note's nullifier together with a transaction proof
-* After successful verification, the Operator sets the corresponding entry in the Nullifier DB to `1`
+* A new note is produced when a transaction is executed - regardless of the transaction type.
+* Operator will receive the note hash and if the note is public, it'll also receive the corresponding note's data.
+* Operator verifies the correctness of the underlying transaction before adding the note hash to the Notes DB.
+* The note can now be consumed in a separate transaction - to consume the note, the note's data must be known.
+* A note is consumed when the its nullifier in the [Nullifier DB](state.md/#nullifier-database) is set to `1`.
+* Operator will receive the note's nullifier together with a transaction proof.
+* After successful verification, the Operator sets the corresponding entry in the Nullifier DB to `1`.