latest bunch of commits

Author: kmurphypolygon

docs/miden/architecture/accounts.md

@@ -1,12 +1,12 @@
-# Accounts
 Miden aims to support expressive smart contracts via a Turing-complete language. For smart contracts the go-to solution is account-based state. In Miden, an account is an entity which holds assets and defines rules of how these assets can be transferred. They are basic building blocks representing a user or an autonomous smart contract.
 
-## Account Design
+## Account design
+
 The diagram below illustrates basic components of an account. In Miden every account is a smart contract.
 
-<p align="center">
-    <img src="../diagrams/architecture/account/Account_Definition.png" style="width: 25%;">
-</p>
+<center>
+![Account definition](../../img/miden/architecture/account/account_definition.png){ width="30%" }
+</center>
 
 In the above picture, you can see:
 

docs/miden/architecture/architecture.md

@@ -1,49 +1,54 @@
-# Assets
 In Miden, users can create and trade arbitrary fungible and non-fungible assets.
 
 We differentiate between native and non-native assets in Miden. Native assets follow the Miden asset model. Non-native assets are all other data structures of value that can be exchanged.
 
 Recording of native assets in Polygon Miden suffices four goals:
 
-* Asset exchange should be parallelizable
-* Asset ownership should be private
-* Asset usage should be indeed censorship resistant
-* Fees can be paid using any asset
+* Asset exchange should be parallelizable.
+* Asset ownership should be private.
+* Asset usage should be indeed censorship resistant.
+* Fees can be paid using any asset.
 
 All native assets in Miden are stored directly in accounts, like Ether in Ethereum. Miden does not track ownership of assets using global hashmaps, e.g., ERC20 contracts. Storage of assets locally in accounts provides privacy and the ability for client-side proofs. That is because ownership changes always involve only one account and not the change of a global hashmap. Thus, they can happen in parallel. Additionally, asset exchange is censorship resistant at this level because there is no global contract the transfer must pass through. Finally, users can pay fees in any asset.
 
 ## Native assets
+
 Native assets are data structures that follow the Miden asset model (encoding, issuance, storing). All native assets are encoded using a single `Word` (4 field elements). The asset encodes both the ID of the issuing account and the asset details. Having the issuer's ID encoded in the asset makes it cost-efficient to determine the type of an asset inside and outside Miden VM. And, representing the asset in a `Word` means the representation is always a commitment to the asset data itself. That is particularly interesting for non-fungible assets.
 
 ### 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](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#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/#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.
 
-<p align="center">
-    <img src="../diagrams/architecture/asset/Asset_Issuance.png">
-</p>
+<center>
+![Asset issuance](../../img/miden/architecture/asset/asset_issuance.png){ width="50%" }
+</center>
 
 ### Fungible assets
+
 A fungible asset is encoded using the amount and the `faucet_id` of the faucet which issued the asset. The amount is guaranteed to be  $2^{63} - 1$ or smaller, the maximum supply for any fungible asset. Examples of fungible assets are ETH and stablecoins, e.g., DAI, USDT, and USDC.
 
 If the `faucet_id` of MATIC were to be `2`, 100 MATIC are encoded as `[100, 0, 0, 2]` - whereas the `0`s in the middle help to quickly distinguish between fungible and non-fungible assets.
 
 ### Non-fungible assets
+
 A non-fungible asset is encoded by hashing the asset data into a `Word` and then replacing the second element with the `faucet_id` of the issuing account. It looks like `[e0, faucet_id, e2, e3]`. Note that the second element is guaranteed to be non-Zero.
 
 Examples of non-fungible assets are all NFTs, e.g., a DevCon ticket. The ticket's data might be represented in a JSON string - which DevCon, the date, the initial price, etc. . Now, users can create a faucet for non-fungible DevCon tickets. This DevCon faucet would hash the JSON string into a `Word` to transform the ticket into an asset.
 
 ### Storage
-[Accounts](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html) and [notes](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html) contain asset vaults that are used to store assets. Accounts can keep unlimited assets in a [tiered sparse Merkle tree](https://0xpolygonmiden.github.io/miden-base/crypto-primitives/tsmt.html) called `account vault`. Notes can only store up to `255` distinct assets.
 
-<p align="center">
-    <img src="../diagrams/architecture/asset/Asset_Storage.png">
-</p>
+[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.
+
+<center>
+![Asset storage](../../img/miden/architecture/asset/asset_storage.png){ width="50%" }
+</center>
 
 The information on which and how many assets are owned can be private depending on the account's storage mode or the note. This is true for any native asset in Miden.
 
 ## Non-native assets
+
 Miden is flexible enough to create other types of assets as well.
 
 For example, developers can fully replicate Ethereum's ERC20 model, where ownership of fungible assets is recorded in a single account. To transact, users must send a note to that account to change the global hashmap.

docs/miden/architecture/assets.md

@@ -1,39 +1,40 @@
-# Execution Model
+Polygon Miden is an Ethereum rollup. It batches transactions - or more precisely, proofs thereof - that happen together in the same time period into a block. The execution model describes how the state progresses on an individual level via transactions and at the global level expressed as aggregated state updates in blocks.
 
-Polygon Miden is an Ethereum Rollup. It batches transactions - or more precisely, proofs thereof - that happen together in the same time period into a block. The Execution Model describes how the state progresses on **an individual level via transactions** and **at the global level expressed as aggregated state updates in blocks**.
+<center>
+![Execution](../../img/miden/architecture/execution/execution.png){ width="80%" }
+</center>
 
-<p align="center">
-  <img src="../diagrams/architecture/execution/Execution.png">
-</p>
+## Transaction execution
 
-## Transaction Execution
+Every transaction will result in a zkProof that attests to its correctness.
 
-Every transaction will result in a ZK proof 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](https://0xpolygonmiden.github.io/miden-base/architecture/transactions.html#local-vs-network-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.
+## Transaction batching
 
-## Transaction Batching
 To reduce the required space on the Ethereum blockchain, transaction proofs are aggregated into batches. This can happen in parallel by different machines that need to verify several proofs using the Miden VM and thus creating a proof. Verifying a STARK proof within the VM is relatively efficient but it is still a pretty costly operation (we aim for 2<sup>16</sup> cycles).
 
-## Block Production
+## Block production
+
 Several batch proofs are being aggregated together into one block. This can not happen in parallel and must be done by the Miden Operator running the Miden Node. The idea is the same, using recursive verification.
 
 ## State progress
-At the beginning, Miden will have a centralized Operator running a Miden Node.
+
+At the beginning, Miden will have a centralized operator running a Miden node.
 
 Users will send either transaction proofs (using local execution) or transaction data (for network execution) to the Miden Node. Later on, the Miden Node will use recursive verification to aggregate transaction proofs into batches.
 
 Batch proofs are aggregated into blocks by the Miden Node. The blocks are then sent to Ethereum, and once a block is added to the L1 chain, the rollup chain is believed to have progressed to the next state.
 
 A block produced by the Miden Node looks somewhat like this:
 
-<p align="center">
-  <img src="../diagrams/architecture/execution/Block.png">
-</p>
+<center>
+![Block](../../img/miden/architecture/execution/block.png)
+</center>
 
-* **state updates** contain only the hashes of changes. For example, for each account which was updated, we record a tuple `([account id], [new account hash])`.
-* The included **zk proof** attests that given a state commitment from the previous block, there was a sequence of valid transactions executed that resulted in the new state commitment, and also output included state updates.
-* 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.
+* State updates contain only the hashes of changes. For example, for each account which was updated, we record a tuple `([account id], [new account hash])`.
+* The included zkProof attests that given a state commitment from the previous block, there was a sequence of valid transactions executed that resulted in the new state commitment, and also output included state updates.
+* 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.
@@ -46,8 +47,9 @@ To verify that a block describes a valid state transition, we do the following:
 The above can be performed by a verifier contract on Ethereum L1.
 
 This structure has another nice property. It is very easy for a new node to sync up to the current state from genesis. The new node would need to do the following:
+
 1. Download only the first part of the blocks (i.e., without full account/note states) starting at the genesis up until the latest block.
-2. Verify all ZKPs in the downloaded blocks. This will be super quick (exponentially faster than re-executing original transactions) and can also be done in parallel.
+2. Verify all zkProofs in the downloaded blocks. This will be super quick (exponentially faster than re-executing original transactions) and can also be done in parallel.
 3. Download the current states of account, note, and nullifier databases.
 4. Verify that the downloaded current state matches the state commitment in the latest block.