diff --git a/docs/src/architecture.md b/docs/src/architecture.md index 9b35c120f..d443772da 100644 --- a/docs/src/architecture.md +++ b/docs/src/architecture.md @@ -5,30 +5,48 @@ The architecture reflects the design goals for the rollup: * **High throughput** * **Privacy** -* **Asset Safety** +* **Asset safety** -On Miden, developers can build dApps currently infeasible anywhere else. +## Inspired by the Actor model +The [Actor Model](https://en.wikipedia.org/wiki/Actor_model) inspired Miden to achieve concurrent and local state changes. In the model, actors are little state machines with inboxes, meaning each actor is responsible for their own state. Actors can send and receive messages to communicate with other actors. Messages can be read asynchronously. -## Actor Model -The [Actor Model](https://en.wikipedia.org/wiki/Actor_model) inspires Miden to achieve concurrent and local state changes. Actors are little state machines with inboxes, meaning each actor is responsible for their state. Actors can send and receive messages to communicate with other actors. Messages can be read asynchronously. +## Core Concepts in Miden +In Miden, there are accounts and notes which can hold assets. Accounts consume and produce notes in transactions. Transactions describe account state changes of single accounts. The state model captures all individual states of all accounts and notes. Finally, the execution model describes state progress in a sequence of blocks. -## Concepts in Miden -There are accounts and notes which can hold assets. Accounts consume and produce notes in transactions. Transactions are account state changes of single accounts. The state model captures all individual states of all accounts and notes. Finally, the execution model describes state progress in a sequence of blocks. +

+ +

### Accounts -Accounts can hold assets and define rules how those 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](./architecture/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 are messages carrying assets that accounts can 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](./architecture/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 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](./architecture/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 describe production or consumption of notes by a single account. For every transaction there is always a STARK proof in Miden. This chapter describes the transaction design and the different transaction modes. +[Transactions](./architecture/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. -### State Model -State describes everything that is the case at a certain point in time. Individual state of accounts or notes can be stored onchain and offchain to provide privacy. This chapter describes the three different state databases in Miden. +### State model +[State](./architecture/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 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 model +[Execution](./architecture/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. + +# Architecture tradeoffs +
+ Want to know more on why we designed Miden as is? + + ### Polygon Miden's architecture + Polygon Miden’s architecture departs considerably from typical blockchain designs to support privacy and parallel transaction exection. In traditional blockchains state and transactions must be transparent to be verifiable. This is necessary for block production and execution. User generated zero-knowledge proofs allow state transitions, e.g. transactions, to be verifiable without being transparent. + + ### Actor-based execution model + The actor model inspires Polygon Miden’s execution model. This is a well-known design paradigm in concurrent systems. In the actor model, actors are state machines responsible for maintaining their own state. In the context of Polygon Miden, each account is an actor. Actors communicate with each other by exchanging messages asynchronously. One actor can send a message to another, but it is up to the recipient to apply the requested change to their state. + + Polygon Miden’s architecture takes the actor model further and combines it with zero-knowledge proofs. Now, actors not only maintain and update their own state, but they can also prove the validity of their own state transitions to the rest of the network. This ability to independently prove state transitions enables local smart contract execution, private smart contracts, and much more. And it is quite unique in the rollup space. Normally only centralized entities - sequencer or prover - create zero-knowledge proofs, not the users. + + ### Hybrid state model + The actor-based execution model requires a radically different approach to recording the system's state. Actors and the messages they exchange must be treated as first-class citizens. Polygon Miden addresses this by combining the state models of account-based systems like Ethereum and UTXO-based systems like Bitcoin and Zcash. +
\ No newline at end of file diff --git a/docs/src/architecture/accounts.md b/docs/src/architecture/accounts.md index 258900522..6ca32d8a8 100644 --- a/docs/src/architecture/accounts.md +++ b/docs/src/architecture/accounts.md @@ -5,40 +5,26 @@ Miden aims to support expressive smart contracts via a Turing-complete language. The diagram below illustrates basic components of an account. In Miden every account is a smart contract.

- +

In the above picture, you can see: * **Account ID →** a unique identifier of an account which does not change throughout its lifetime -* **Storage →** a user-defined data which can be stored in an account -* **Nonce →** a counter which must be incremented whenever account state changes +* **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 an external interface for an account +* **Code →** a collection of functions which define the external interface for an account ### Account ID -~63 bits (1 Felt) long identifier for the account. The first three significant bits specify its type and the [storage mode](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#account-storage-modes). There are four types of accounts in Miden: - -| | Regular updatable account | Regular immutable account | Faucet for fungible assets | Faucet for non-fungible assets | -|---|---|---|---|---| -| **Description** | Will be used by most users for a wallet. Code specification and changes possible. | Will be used by most smart contracts. Once deployed code cannot be changed | Users can issue fungible assets and customize them. | Users can issue non-fungible assets and customize them. | -| **Code updatability** | yes | no | no | no | -| **Most significant bits** | `00` | `01` | `10` | `11` | - -#### Example account ID (big-endian) - -

- -

- -*Note: Miden uses little-endian by default, but big_endian for better readability in the picture above.* +~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 -User-defined data that can be stored in an account. `AccountStorage` is composed of two components. +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 the simple sparse Merkle tree. When `AccountStorage` is serialized it will check to see 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`. +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. @@ -60,8 +46,8 @@ An account vault can be reduced to a single hash which is the root of the sparse ### 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., 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 account's functions. +* 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* @@ -76,11 +62,22 @@ The process is as follows: * 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 new Account ID eventually and - if transaction is correct - adds the ID to the Account DB +* 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: -## Account storage modes +| | Regular updatable account | Regular immutable account | Faucet for fungible assets | Faucet for non-fungible assets | +|---|---|---|---|---| +| **Description** | For most users, e.g. a wallet. Code changes allowed, including public API. | For most smart contracts. Once deployed code is immutable. | Users can issue fungible assets and customize them. | Users can issue non-fungible assets and customize them. | +| **Code updatability** | yes | no | no | no | +| **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`. * 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. -* Account with **encrypted state**, where the account data is stored onchain but in encrypted text. It provides liveness guarantee of the protocol for the account in question. * 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])`. + +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 diff --git a/docs/src/diagrams/architecture/account/Account_ID.png b/docs/src/diagrams/architecture/account/Account_ID.png deleted file mode 100644 index 6db4f40bb..000000000 Binary files a/docs/src/diagrams/architecture/account/Account_ID.png and /dev/null differ diff --git a/docs/src/diagrams/architecture/miden_architecture.gif b/docs/src/diagrams/architecture/miden_architecture.gif new file mode 100644 index 000000000..50e5ff97a Binary files /dev/null and b/docs/src/diagrams/architecture/miden_architecture.gif differ