Docs editorial, three more docs (#554)

* three more docs

* update after review

* last updates

docs/architecture/accounts.md

@@ -167,7 +167,7 @@ There are four types of accounts in Miden:
 ## Account storage modes
 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])`.
+* Accounts with **public state**, where the actual state is stored on-chain. 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 on-chain. 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])`.
 
-In the future we will also support **encrypted state** which will be onchain but encrypted. * Depending on the account storage mode (private vs. encrypted 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
+In the future we will also support **encrypted state** which will be on-chain but encrypted. * Depending on the account storage mode (private vs. encrypted 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

docs/architecture/assets.md

@@ -1,22 +1,27 @@
-# 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:
+Native assets in Polygon Miden have 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 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.
+All native assets in Miden are stored directly in accounts, like Ether in Ethereum. Miden does not track asset ownership using global hashmaps, e.g., ERC20 contracts. Local asset storage in accounts provides privacy and the ability for client-side proofs. That is because ownership changes are reflected only on an account and not in an ERC20 account (global hashmap). Thus, these changes 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.
+
+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 determining the type of an asset, inside and outside Miden VM, cost-efficient. And, representing the asset in a `word` means the representation is 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. As with regular accounts, anyone can create a faucet account. Faucets can issue either fungible or non-fungible assets - but not both. 
+
+The `faucet_id` identifies the faucet and starts with a different sequence depending on the asset type, see the [account id discussion](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. However, 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.
 
@@ -25,17 +30,20 @@ Faucets can create assets and immediately distribute them by producing notes. Ho
 </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.
+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 is `2`, 100 MATIC are encoded as `[100, 0, 0, 2]`; the `0`s in the middle 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.
+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: For example `[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 representing 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 Sparse Merkle Tree 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 sparse Merkle tree called `account vault`. Notes can store up to `255` distinct assets.
 
 <center>
 ![Architecture core concepts](../img/architecture/asset/asset-storage.png)
@@ -44,10 +52,11 @@ Examples of non-fungible assets are all NFTs, e.g., a DevCon ticket. The ticket'
 The information on which and how many assets are owned can be private depending on the account's or note's storage mode. 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.
+For example, developers can replicate the Ethereum 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.
 
 Furthermore, a complete account can be treated as a programmable asset because ownership of accounts is transferrable. An account could be a "crypto kitty" with specific attributes and rules, and people can trade these "crypto kitties" by transferring accounts between each other.
 
-We can also think of an account representing a car. The owner of the car can change so the car account - granting access to the physical car - can be treated as an asset. In this car account, there could be rules defining who is allowed to drive the car and when.
+We can also think of an account representing a car. The owner of the car can change so the car account - granting access to the physical car - can be treated as an asset. In this car account, there could be rules defining who is allowed to drive the car and when.

docs/architecture/execution.md

@@ -1,40 +1,50 @@
-# 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 - that occur in the same time period into a block. 
+
+The Miden execution model describes how state progresses on an individual level via transactions and at the global level expressed as aggregated state updates in blocks.
 
 <center>
 ![Architecture core concepts](../img/architecture/execution/execution.png)
 </center>
 
-## Transaction Execution
+## Transaction execution
+
+Every transaction results in a ZK proof that attests to its correctness.
+
+As mentioned in [transaction modes](transactions/modes.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.
 
-Every transaction will result in a ZK proof that attests to its correctness.
+## Transaction batching
 
-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.
+To reduce the required space on the Ethereum blockchain, transaction proofs are aggregated into batches. This can happen in parallel on different machines that need to verify several proofs using the Miden VM and thus creating a proof. 
 
-## 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).
+Verifying a STARK proof within the VM is relatively efficient but it is still costly; we aim for 2<sup>16</sup> cycles.
 
-## 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.
+## Block production
+
+Several batch proofs are aggregated into one block. This cannot 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.
 
-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.
+Miden has a centralized operator running a Miden node. Eventually, this will be a decentralized function.
+
+Users send either transaction proofs (using local execution) or transaction data (for network execution) to the Miden node. Then, the Miden node uses 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.
+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:
+A block produced by the Miden node looks something like this:
 
 <center>
 ![Architecture core concepts](../img/architecture/execution/block.png){ width="80%" }
 </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.
+!!! tip "Block contents"
+      * **state updates** only contain the hashes of changes. For example, for each updated account, we record a tuple `([account id], [new account hash])`.
+      * **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 the output also included state updates.
+      * The block also contains full account and note data for public accounts and notes. For example, if account `123` is an updated public account which, in the **state updates** section we'd see 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.
+
+### Verifying valid block state
 
 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:
@@ -44,10 +54,15 @@ 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:
+### Syncing to current state from genesis
+
+The block 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 ZK proofs in the downloaded blocks. This is 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.
 
-Overall, state sync is dominated by the time needed to download the data.
+Overall, state sync is dominated by the time needed to download the data.

docs/architecture/overview.md

@@ -34,7 +34,7 @@ In Miden, there are accounts and notes which can hold assets. Accounts consume a
 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.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.
+[State](state.md) describes everything that is the case at a certain point in time. Individual states of accounts or notes can be stored on-chain and off-chain. This chapter describes the three different state databases in Miden.
 
 ### Execution model
 [Execution](execution.md) describes how the state progresses as aggregated state updates in batches, blocks, and epochs. This chapter describes the execution model and how blocks are built.