From 75c309e6a478493482b8c9c8ce3216ae3b667078 Mon Sep 17 00:00:00 2001 From: Augusto Hack Date: Thu, 22 Feb 2024 14:48:54 +0100 Subject: [PATCH] pre-commit: update to match ci (#475) --- .github/workflows/ci.yml | 2 +- .pre-commit-config.yaml | 9 ++- Makefile | 2 +- docs/src/architecture.md | 16 ++-- docs/src/architecture/accounts.md | 6 +- docs/src/architecture/notes.md | 80 +++++++++---------- docs/src/architecture/transactions.md | 9 +-- docs/src/introduction.md | 18 ++--- docs/src/introduction/overview.md | 2 +- .../miden-node/miden-node-block-producer.md | 8 +- docs/src/miden-node/miden-node-rpc.md | 12 +-- docs/src/miden-node/miden-node-store.md | 12 +-- docs/src/roadmap.md | 2 +- .../src/transactions/transaction-execution.md | 12 +-- docs/src/transactions/transaction-kernel.md | 24 +++--- .../transactions/transaction-procedures.md | 21 +++-- miden-lib/asm/miden/kernels/tx/account.masm | 2 +- miden-lib/asm/miden/kernels/tx/epilogue.masm | 2 +- miden-lib/asm/note_scripts/P2ID.masm | 2 +- miden-lib/asm/note_scripts/SWAP.masm | 6 +- objects/src/accounts/mod.rs | 14 ++-- 21 files changed, 130 insertions(+), 131 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c4975cc0d..bd344a542 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -84,7 +84,7 @@ jobs: args: ${{matrix.args}} no-std: - name: build ${{matrix.toolchain}} no-std for wasm32-unknown-unknown + name: build ${{matrix.toolchain}} no-std for wasm32-unknown-unknown runs-on: ubuntu-latest strategy: fail-fast: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 74014b517..9248d33b9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -21,12 +21,12 @@ repos: # Allows cargo fmt to modify the source code prior to the commit - id: cargo name: Cargo fmt - args: ["+stable", "fmt", "--all"] + args: ["+nightly", "fmt", "--all"] stages: [commit] # Requires code to be properly formatted prior to pushing upstream - id: cargo name: Cargo fmt --check - args: ["+stable", "fmt", "--all", "--check"] + args: ["+nightly", "fmt", "--all", "--check"] stages: [push, manual] - id: cargo name: Cargo check --all-targets @@ -40,4 +40,7 @@ repos: # Unlike fmt, clippy will not be automatically applied - id: cargo name: Cargo clippy - args: ["+nightly", "clippy", "--workspace", "--", "--deny", "clippy::all", "--deny", "warnings"] + args: ["+nightly", "clippy", "--workspace", "--all-targets", "--", "--deny", "clippy::all", "--deny", "warnings"] + - id: cargo + name: Cargo clippy all-features + args: ["+nightly", "clippy", "--workspace", "--all-targets", "--all-features", "--", "--deny", "clippy::all", "--deny", "warnings"] diff --git a/Makefile b/Makefile index 2bc500c22..556eab2f7 100644 --- a/Makefile +++ b/Makefile @@ -12,4 +12,4 @@ test: fmt: cargo +nightly fix --allow-staged --allow-dirty --all-targets --all-features cargo +nightly fmt - cargo +nightly clippy --workspace --all-targets --all-features -- -D warnings \ No newline at end of file + cargo +nightly clippy --workspace --all-targets --all-features -- -D warnings diff --git a/docs/src/architecture.md b/docs/src/architecture.md index 89e9532aa..7abd7f288 100644 --- a/docs/src/architecture.md +++ b/docs/src/architecture.md @@ -23,9 +23,9 @@ In Miden, there are accounts and notes which can hold assets. Accounts consume a [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](./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 implementation thereof. At it's core, transaction execution happens in the transaction kernel program which is explained in depth. +[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 implementation thereof. At it's core, transaction execution happens in the transaction kernel program which is explained in depth. -#### Accounts produce and consume notes to communicate +#### Accounts produce and consume notes to communicate

@@ -39,7 +39,7 @@ The state model captures all individual states of all accounts and notes. Finall ### Execution model [Execution](./architecture/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. -#### Operators capture and progress state +#### Operators capture and progress state

@@ -49,13 +49,13 @@ The state model captures all individual states of all accounts and notes. Finall 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 execution. 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. + Polygon Miden’s architecture departs considerably from typical blockchain designs to support privacy and parallel transaction execution. 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. + 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 d488f3c56..d4a5254a0 100644 --- a/docs/src/architecture/accounts.md +++ b/docs/src/architecture/accounts.md @@ -17,7 +17,7 @@ In the above picture, you can see: * **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. +~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 Storage for user-defined data. `AccountStorage` is composed of two components. @@ -44,7 +44,7 @@ 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](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#note-scripts) and [transaction scripts](https://0xpolygonmiden.github.io/miden-base/transactions/transaction-kernel.html#the-transaction-script-processing). Users cannot call those functions directly. +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](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#note-scripts) and [transaction scripts](https://0xpolygonmiden.github.io/miden-base/transactions/transaction-kernel.html#the-transaction-script-processing). Users cannot call those functions directly. Functions exposed by the account have the following properties: @@ -55,7 +55,7 @@ Functions exposed by the account have the following properties: *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* #### Example Account Code -Currently, Miden provides two standard implementations for account code. +Currently, Miden provides two standard implementations for account code. ##### Basic user account (Regular updatable account) There is a standard for a basic user account. It exposes three functions via its interface. diff --git a/docs/src/architecture/notes.md b/docs/src/architecture/notes.md index dc0cd739c..622495eaa 100644 --- a/docs/src/architecture/notes.md +++ b/docs/src/architecture/notes.md @@ -1,8 +1,8 @@ # Notes -Miden aims to achieve parallel transaction execution and privacy. The UTXO-model combined with client-side proofs provide those features. That means, in Miden exist notes as a way of transferring assets between and to interact with accounts. Notes can be consumed and produced asynchronously and privately. The concept of notes is a key difference between Ethereum’s Account-based model and Polygon Miden, which uses a hybrid UTXO- and Account-based [state-model](state.md). +Miden aims to achieve parallel transaction execution and privacy. The UTXO-model combined with client-side proofs provide those features. That means, in Miden exist notes as a way of transferring assets between and to interact with accounts. Notes can be consumed and produced asynchronously and privately. The concept of notes is a key difference between Ethereum’s Account-based model and Polygon Miden, which uses a hybrid UTXO- and Account-based [state-model](state.md). # Note design -In Polygon Miden, accounts communicate with one another by producing and consuming notes. A note stores assets and a script that defines how this note can be consumed. +In Polygon Miden, accounts communicate with one another by producing and consuming notes. A note stores assets and a script that defines how this note can be consumed. The diagram below illustrates the contents of a note: @@ -13,25 +13,25 @@ The diagram below illustrates the contents of a note: As shown in the above picture: * **Assets →** serves as [asset](assets.md) container for a note. It can contain up to `256` assets stored in an array which can be reduced to a single hash. * **Script →** will be executed in the [transaction](https://0xpolygonmiden.github.io/miden-base/architecture/transactions.html) in which the note is consumed. The script defines the conditions for the consumption, if the script fails, the note cannot be consumed. -* **Inputs →** used for the note script execution. They can be accessed by the note script via [transaction kernel procedures](https://0xpolygonmiden.github.io/miden-base/transactions/transaction-procedures.html#note). The number is limited to 16 and they must be defined at note creation. +* **Inputs →** used for the note script execution. They can be accessed by the note script via [transaction kernel procedures](https://0xpolygonmiden.github.io/miden-base/transactions/transaction-procedures.html#note). The number is limited to 16 and they must be defined at note creation. * **Serial number →** a note's unique identifier to break linkability between [note hash](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#note-hash) and [nullifier](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#note-nullifier). Should be a random `Word` chosen by the user - if revealed, the nullifier might be computed easily. In addition, a note has **metadata** including the sender and the note tag. Those values are always public regardless of the [note storage mode](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#note-storage-mode). # Note's lifecycle -New notes are created by executing transactions. After verifying the transaction proof the operator adds either only the note hash (private notes) or the full note data (public notes) to the [Note DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#notes-database). Notes can be produced and consumed locally by users in local transactions or by the operator in a network transaction. Note consumption requires the transacting party to know the note data to compute the nullifier. After successful verification, the operator sets the corresponding entry in the Nullifier DB to "consumed". +New notes are created by executing transactions. After verifying the transaction proof the operator adds either only the note hash (private notes) or the full note data (public notes) to the [Note DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#notes-database). Notes can be produced and consumed locally by users in local transactions or by the operator in a network transaction. Note consumption requires the transacting party to know the note data to compute the nullifier. After successful verification, the operator sets the corresponding entry in the Nullifier DB to "consumed".

-The following sections will explain, how notes are created, stored, discovered and consumed. +The following sections will explain, how notes are created, stored, discovered and consumed. ## Note creation -Notes are created as outputs (`OutputNotes`) of Miden transactions. Operators record those notes to the [Note DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#note-database), after successful verification of the underlying transactions those notes can be consumed. +Notes are created as outputs (`OutputNotes`) of Miden transactions. Operators record those notes to the [Note DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#note-database), after successful verification of the underlying transactions those notes can be consumed. -## The note script -Every note has a script which gets executed at note consumption. It is always executed in the context of a single account, and thus, may invoke zero or more of the [account's functions](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#code). The script allows for more than just the transferring of assets, they could be of arbitrary complexity thanks to the Turing completeness of the Miden VM +## The note script +Every note has a script which gets executed at note consumption. It is always executed in the context of a single account, and thus, may invoke zero or more of the [account's functions](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#code). The script allows for more than just the transferring of assets, they could be of arbitrary complexity thanks to the Turing completeness of the Miden VM By design, every note script can be defined as a unique hash or the root of a [Miden program MAST](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/main.html). That also means every function is a commitment to the underlying code. That code cannot change unnoticed to the user because its hash would change. That way it is easy to recognize standardized notes and those which deviate. @@ -39,15 +39,15 @@ Note scripts are created together with their inputs, i.e., the creator of the no There exist [standard note scripts](https://github.com/0xPolygonMiden/miden-base/tree/main/miden-lib/asm/note_scripts) (P2ID, P2IDR, SWAP) that users can create and add to their notes using the [Miden client](../network/miden-clients.md) or by calling internal [Rust code](https://github.com/0xPolygonMiden/miden-base/blob/fa63b26d845f910d12bd5744f34a6e55c08d5cde/miden-lib/src/notes/mod.rs#L15-L66). -* P2ID and P2IDR scripts are used to send assets to a specific account ID. The scripts check at note consumption if the executing account ID equals the account ID that was set by the note creator as note inputs. The P2IDR script is reclaimable and thus after a certain block height can also be consumed by the sender itself. -* SWAP script is a simple way to swap assets. It adds an asset from the note into the consumer's vault and creates a new note consumable by the first note's issuer containing the requested asset. +* P2ID and P2IDR scripts are used to send assets to a specific account ID. The scripts check at note consumption if the executing account ID equals the account ID that was set by the note creator as note inputs. The P2IDR script is reclaimable and thus after a certain block height can also be consumed by the sender itself. +* SWAP script is a simple way to swap assets. It adds an asset from the note into the consumer's vault and creates a new note consumable by the first note's issuer containing the requested asset. ### Example note script Pay to ID (P2ID)
Want to know more how to ensure a note can only be consumed by a specified account? #### Goal of the P2ID script - The P2ID script defines a specific target account ID as the only account that can consume the note. Such notes ensure a targeted asset transfer. + The P2ID script defines a specific target account ID as the only account that can consume the note. Such notes ensure a targeted asset transfer. #### Imports and context The P2ID script uses procedures from the account, note and wallet API. @@ -83,33 +83,33 @@ There exist [standard note scripts](https://github.com/0xPolygonMiden/miden-base # drop the transaction script root dropw # => [] - + # load the note inputs to memory starting at address 0 push.0 exec.note::get_inputs # => [inputs_ptr] - + # read the target account id from the note inputs mem_load # => [target_account_id] - + exec.account::get_id # => [account_id, target_account_id, ...] - + # ensure account_id = target_account_id, fails otherwise assert_eq # => [...] - + exec.add_note_assets_to_account # => [...] end ``` Every note script starts with the note script root on top of the stack. After the `dropw`, the stack is cleared. Next, the script stored the note inputs at pos 0 in the [relative note context memory](https://0xpolygonmiden.github.io/miden-base/transactions/transaction-procedures.html#transaction-contexts) by `push.0 exec.note::get_inputs`. Then, `mem_load` loads a `Felt` from the specified memory address and puts it on top of the stack, in that cases the `target_account_id` defined by the creator of the note. Now, the note invokes `get_id` from the account API using `exec.account::get_id` - which is possible even in the note context. Because, there are two account IDs on top of the stack now, `assert_eq` fails if the two account IDs (target_account_id and executing_account_id) are not the same. That means, the script cannot be successfully executed if executed by any other account than the account specified by the note creator using the note inputs. - + If execution hasn't failed, the script invokes a helper procedure `exec.add_note_assets_to_account` to add the note's assets into the executing account's vault. #### Add assets - This procedure adds the assets held by the note into the account's vault. + This procedure adds the assets held by the note into the account's vault. ``` #! Helper procedure to add all assets of a note to an account. @@ -120,52 +120,52 @@ There exist [standard note scripts](https://github.com/0xPolygonMiden/miden-base proc.add_note_assets_to_account push.0 exec.note::get_assets # => [num_of_assets, 0 = ptr, ...] - + # compute the pointer at which we should stop iterating dup.1 add # => [end_ptr, ptr, ...] - + # pad the stack and move the pointer to the top padw movup.5 # => [ptr, 0, 0, 0, 0, end_ptr, ...] - + # compute the loop latch dup dup.6 neq # => [latch, ptr, 0, 0, 0, 0, end_ptr, ...] - + while.true # => [ptr, 0, 0, 0, 0, end_ptr, ...] - + # save the pointer so that we can use it later dup movdn.5 # => [ptr, 0, 0, 0, 0, ptr, end_ptr, ...] - + # load the asset and add it to the account mem_loadw call.wallet::receive_asset # => [ASSET, ptr, end_ptr, ...] - + # increment the pointer and compare it to the end_ptr movup.4 add.1 dup dup.6 neq # => [latch, ptr+1, ASSET, end_ptr, ...] end - + # clear the stack drop dropw drop end ``` - The procedure starts by calling `exec.note::get_assets`. As with the note's inputs before, this writes the assets of the note into memory starting at the specified address. Assets are stored in consecutive memory slots, so `dup.1 add` provides the last memory slot. - - In Miden, [assets](assets.md) are represented by `Words`, so we need to pad the stack with four `0`s to make room for an asset. Now, if there is at least one asset (checked by `dup dup.6 neq`), the loop starts. It first saves the pointer for later use (`dup movdn.5`), then loads the first asset `mem_loadw` on top of the stack. - - Now, the procedure calls the a function of the account interface `call.wallet::receive_asset` to put the asset into the account's vault. Due to different [contexts](https://0xpolygonmiden.github.io/miden-base/transactions/transaction-procedures.html#transaction-contexts), a note script cannot directly call an account function to add the asset. The account must expose this function in its [interface](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#example-account-code). - + The procedure starts by calling `exec.note::get_assets`. As with the note's inputs before, this writes the assets of the note into memory starting at the specified address. Assets are stored in consecutive memory slots, so `dup.1 add` provides the last memory slot. + + In Miden, [assets](assets.md) are represented by `Words`, so we need to pad the stack with four `0`s to make room for an asset. Now, if there is at least one asset (checked by `dup dup.6 neq`), the loop starts. It first saves the pointer for later use (`dup movdn.5`), then loads the first asset `mem_loadw` on top of the stack. + + Now, the procedure calls the a function of the account interface `call.wallet::receive_asset` to put the asset into the account's vault. Due to different [contexts](https://0xpolygonmiden.github.io/miden-base/transactions/transaction-procedures.html#transaction-contexts), a note script cannot directly call an account function to add the asset. The account must expose this function in its [interface](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#example-account-code). + Lastly, the pointer gets incremented, and if there is a second asset, the loop continues (`movup.4 add.1 dup dup.6 neq`). Finally, when all assets were put into the account's vault, the stack is cleared (`drop dropw drop`).
## Note storage mode -Similar to accounts, there are two storage modes for notes in Miden. Notes can be stored on-chain in the [Note DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#notes-database) with all data publicly visible for everyone. Alternatively, notes can be stored off-chain by committing only the note hash to the Note DB. +Similar to accounts, there are two storage modes for notes in Miden. Notes can be stored on-chain in the [Note DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#notes-database) with all data publicly visible for everyone. Alternatively, notes can be stored off-chain by committing only the note hash to the Note DB. Every note has a unique note hash. It is defined as follows: @@ -176,29 +176,29 @@ hash(hash(hash(hash(serial_num, [0; 4]), script_hash), input_hash), vault_hash) _Info: To compute a note's hash, we do not need to know the note's `serial_num`. Knowing the hash of the `serial_num` (as well as `script_hash`, `input_hash` and `note_vault`) is also sufficient. We compute the hash of `serial_num` as `hash(serial_num, [0; 4])` to simplify processing within the VM._ ## Note discovery -Note discovery describes the process of Miden clients finding notes they want to consume. There are two ways to receive new relevant notes - getting notes via an off-chain channel or querying the Miden operator to request newly recorded relevant notes. +Note discovery describes the process of Miden clients finding notes they want to consume. There are two ways to receive new relevant notes - getting notes via an off-chain channel or querying the Miden operator to request newly recorded relevant notes. The latter is done via note tags. Tags are part of the note's metadata and are represented by a `Felt`. The `SyncState` API of the [Miden node](../network/miden-node.md) requires the Miden client to provide a `note_tag` value which is used as a filter in the operator's response. Tags are useful for note discovery enabling an easy collection of all notes matching a certain tag. ## Note consumption -As with creation, notes can only be consumed in Miden transactions. If a valid transaction consuming an `InputNote` gets verified by the Miden node, the note's unique nullifier gets added to the [Nullifier DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#nullifier-database) and is therefore consumed. +As with creation, notes can only be consumed in Miden transactions. If a valid transaction consuming an `InputNote` gets verified by the Miden node, the note's unique nullifier gets added to the [Nullifier DB](https://0xpolygonmiden.github.io/miden-base/architecture/state.html#nullifier-database) and is therefore consumed. Notes can only be consumed if the note data is known to the consumer. The note data must be provided as input to the [transaction kernel](../transactions/transaction-kernel.md). That means, for privately stored notes, there must be some off-chain communication to transmit the note's data from the sender to the target. ### Note recipient to restrict note consumption -There are several ways to restrict the set of accounts that can consume a specific note. One way is to specifically define the target account ID as done in the P2ID and P2IDR note scripts. Another way is by using the concept of a `RECIPIENT`. Miden defines a `RECIPIENT` (represented as `Word`) as: +There are several ways to restrict the set of accounts that can consume a specific note. One way is to specifically define the target account ID as done in the P2ID and P2IDR note scripts. Another way is by using the concept of a `RECIPIENT`. Miden defines a `RECIPIENT` (represented as `Word`) as: ``` hash(hash(hash(serial_num, [0; 4]), script_hash), input_hash) -``` +``` -This concept restricts note consumption to those users who know the pre-image data of `RECIPIENT` - which might be a bigger set than a single account. +This concept restricts note consumption to those users who know the pre-image data of `RECIPIENT` - which might be a bigger set than a single account. -During the [transaction prologue](../transactions/transaction-kernel.md) the users needs to provide all the data to compute the note hash. That means, one can create notes that can only be consumed if the `serial_num` and other data is known. This information can be passed on off-chain by the sender to the consumer. This is only useful with private notes.For public notes, all note data is known, and anyone can compute the `RECIPIENT`. +During the [transaction prologue](../transactions/transaction-kernel.md) the users needs to provide all the data to compute the note hash. That means, one can create notes that can only be consumed if the `serial_num` and other data is known. This information can be passed on off-chain by the sender to the consumer. This is only useful with private notes.For public notes, all note data is known, and anyone can compute the `RECIPIENT`. You can see in the standard [SWAP note script](https://github.com/0xPolygonMiden/miden-base/blob/main/miden-lib/asm/note_scripts/SWAP.masm) how `RECIPIENT` is used. Here, using a single hash, is sufficient to ensure that the swapped asset and its note can only be consumed by the defined target. ### Note nullifier to ensure private consumption -The note's nullifier is computed as: +The note's nullifier is computed as: ``` hash(serial_num, script_hash, input_hash, vault_hash) diff --git a/docs/src/architecture/transactions.md b/docs/src/architecture/transactions.md index edd56f9fd..89af24715 100644 --- a/docs/src/architecture/transactions.md +++ b/docs/src/architecture/transactions.md @@ -1,5 +1,5 @@ # Transactions -Transactions in Miden can be understood as facilitating account state changes. Asset transfers between accounts are done by executing transactions. They take a single account and some [notes](notes.md) as input and output the same account at a new state together with some other notes. +Transactions in Miden can be understood as facilitating account state changes. Asset transfers between accounts are done by executing transactions. They take a single account and some [notes](notes.md) as input and output the same account at a new state together with some other notes. Miden aims for parallel and private transaction execution. Because a transaction is always performed against a single account, Miden obtains asynchronicity. And, because every transaction causes a provable state-change with a STARK proof, it provides privacy when executed locally. @@ -19,9 +19,9 @@ Transactions describe the state-transition of a single account that takes chain At its core, a transaction is an executable program - the transaction kernel program - that processes the provided inputs and creates the requested outputs. Because the program is executed by the Miden VM, a STARK-proof is generated for every transaction. -The next sections will explain the details of a Miden transaction +The next sections will explain the details of a Miden transaction -* Transaction [execution](../transactions/transaction-execution.md) +* Transaction [execution](../transactions/transaction-execution.md) * Transaction [kernel](../transactions/transaction-kernel.md) * Transaction [procedures](../transactions/transaction-procedures.md) * Transaction [modes](../transactions/transaction-modes.md) @@ -41,6 +41,3 @@ It is important to note that both transactions can be executed asynchronously: f * A note script may include a clause which allows the source account to consume the note after some time. Thus, if `account_b` does not consume the note after the specified time, the funds can be returned. This mechanism could be used to make sure funds sent to non-existent accounts are not lost. * Neither sender nor the recipient need to know who the other side is. From the sender's perspective they just need to create `note1` (and for this they need to know the assets to be transferred and the root of the note's script). They don't need any information on who will eventually consume the note. From the recipient's perspective, they just need to consume `note1`. They don't need to know who created it. * Both transactions can be executed "locally". For example, we could generate a zk-proof that `transaction1` was executed and submit it to the network. The network can verify the proof without the need for executing the transaction itself. The same can be done for `transaction2`. Moreover, we can mix and match. For example, `transaction1` can be executed locally, but `transaction2` can be executed on the network, or vice-versa. - - - diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 7eb9fd76d..b3cb60bff 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,5 +1,5 @@ # Polygon Miden -Miden is a zero-knowledge rollup for high-throughput and private applications. Miden allows users to prove state changes of local data where the network only tracks a commitment of it. This leads to privacy and high-throughput. We think, Privacy Scales Better. Users can also let the Operator prove public state changes as in other known rollups. +Miden is a zero-knowledge rollup for high-throughput and private applications. Miden allows users to prove state changes of local data where the network only tracks a commitment of it. This leads to privacy and high-throughput. We think, Privacy Scales Better. Users can also let the Operator prove public state changes as in other known rollups. Polygon Miden is a modular execution layer that extends Ethereum's capabilities using powerful features such as parallel transaction execution and client-side proving. With Miden, developers can create novel, high-throughput, privacy preserving dApps for DeFi, RWA and Autonomous Worlds using their favorite languages such as Rust and TypeScript. @@ -7,17 +7,17 @@ If you want to join the technical discussion, please check out * the [Discord](https://discord.gg/0xpolygondevs) * the [Repo](https://github.com/0xPolygonMiden) -* the [Roadmap](roadmap.md) +* the [Roadmap](roadmap.md) > *This documentation is still Work In Progress. Some topics have been discussed in greater depth, while others require additional clarification. Sections of this documentation might later be reorganized in order to achieve a better flow.* ## Status and features -Polygon Miden is currently on release v0.1. This is an early version of the protocol and its components. We expect to keep making even breaking changes to all components. +Polygon Miden is currently on release v0.1. This is an early version of the protocol and its components. We expect to keep making even breaking changes to all components. At this point, adventurous Pioneers can execute first transactions and send assets to each other. Polygon Miden doesn't offer all the features one would expect from a zkRollup, yet. During 2024, we expect to offer gradually more features. Eventually, developers should be able to code any application they want on Polygon Miden. ### Feature highlights -* **Private accounts**. The Miden Operator only tracks a commitment to any account data in the public database. Users can only execute smart contracts of which they know the interface. +* **Private accounts**. The Miden Operator only tracks a commitment to any account data in the public database. Users can only execute smart contracts of which they know the interface. * **Private notes**. Like private accounts, the Miden Operator only tracks a commitment to any notes in the public database. Users need to communicate note details to each other off-chain (via any side channel) in order to consume private notes in transactions. * **Local transaction execution**. The Miden Client allows for local transaction execution and proving. The Miden Operator verifies the proof and if valid, the state DBs are updated with the new data. * **Simple smart contracts**. Currently, there are three different smart contracts available. A basic wallet smart contracts to send and receive assets, and fungible and non-fungible faucets to mint and burn assets. All accounts are written in MASM. @@ -27,12 +27,12 @@ At this point, adventurous Pioneers can execute first transactions and send asse ### Planned features * **Public accounts**. Polygon Miden will support public smart contracts as know on Ethereum. Code and state of those accounts will be visible to the network and anyone can execute transactions against them. -* **Public notes**. As with public accounts, also public notes will be supported. That means, note data will be publicly stored by the Miden Operator. Note consumption will not be private. +* **Public notes**. As with public accounts, also public notes will be supported. That means, note data will be publicly stored by the Miden Operator. Note consumption will not be private. * **Customized smart contracts**. Accounts can expose any interface in the future. This is the Miden version of a smart contract. Account code can be arbitrary complex due to the underlying Turing-complete Miden VM. * **Customized note scripts**. Users will be able to write their own note scripts using the Miden Client. Note scripts are executed during note consumption and they can be arbitrary complex due to the underlying Turing-complete Miden VM. -* **Network transactions**. Transaction execution and proving can be outsourced to the network and to the Miden Operator. Those transactions will be necessary when it comes to public shared state, and they can be useful if the user's device is not powerful enough to prove transactions efficiently. -* **Rust compiler**. In order to write account code, note or transaction scripts, in Rust, there will be a Rust -> Miden Assembly compiler. -* **Block and epoch proofs**. The Miden Node will recursively verify transactions and in doing so build batches of transactions, blocks and epochs. +* **Network transactions**. Transaction execution and proving can be outsourced to the network and to the Miden Operator. Those transactions will be necessary when it comes to public shared state, and they can be useful if the user's device is not powerful enough to prove transactions efficiently. +* **Rust compiler**. In order to write account code, note or transaction scripts, in Rust, there will be a Rust -> Miden Assembly compiler. +* **Block and epoch proofs**. The Miden Node will recursively verify transactions and in doing so build batches of transactions, blocks and epochs. ## Benefits of Polygon Miden @@ -47,4 +47,4 @@ At this point, adventurous Pioneers can execute first transactions and send asse * dApps on Miden are safe to use due to account abstraction and compile-time safe Rust smart contracts ## License -Licensed under the [MIT license](http://opensource.org/licenses/MIT). \ No newline at end of file +Licensed under the [MIT license](http://opensource.org/licenses/MIT). diff --git a/docs/src/introduction/overview.md b/docs/src/introduction/overview.md index 866d28af6..2094d6b61 100644 --- a/docs/src/introduction/overview.md +++ b/docs/src/introduction/overview.md @@ -10,6 +10,6 @@ This documentation presents detailed guides on: **Architecture** describes Miden's unique state and execution model - an actor-based model with concurrent off-chain state. -**Network design** describes how the architecture is implemented into a zero-knowledge rollup. It describes the software components, RPC interfaces of the Miden Nodes and Cliets. +**Network design** describes how the architecture is implemented into a zero-knowledge rollup. It describes the software components, RPC interfaces of the Miden Nodes and Cliets. **Roadmap** shows the timeline for user facing features that users can expect. diff --git a/docs/src/miden-node/miden-node-block-producer.md b/docs/src/miden-node/miden-node-block-producer.md index 468c767a3..cdb1869a8 100644 --- a/docs/src/miden-node/miden-node-block-producer.md +++ b/docs/src/miden-node/miden-node-block-producer.md @@ -1,13 +1,13 @@ # Miden block producer -The **Block producer** receives transactions from the RPC component, processes them, creates block containing those transactions before sending created blocks to the store. +The **Block producer** receives transactions from the RPC component, processes them, creates block containing those transactions before sending created blocks to the store. -**Block Producer** is one of components of the Miden node. +**Block Producer** is one of components of the Miden node. ## Architecture `TODO` ## API -The **Block Producer** serves connections using the [gRPC protocol](https://grpc.io) on a port, set in the previously mentioned configuration file. The API cannot directly be called by the Miden Client. +The **Block Producer** serves connections using the [gRPC protocol](https://grpc.io) on a port, set in the previously mentioned configuration file. The API cannot directly be called by the Miden Client. Here is a brief description of supported methods. @@ -21,4 +21,4 @@ Submits proven transaction to the Miden network. **Returns** -This method doesn't return any data. \ No newline at end of file +This method doesn't return any data. diff --git a/docs/src/miden-node/miden-node-rpc.md b/docs/src/miden-node/miden-node-rpc.md index de929a5b3..83ccc8beb 100644 --- a/docs/src/miden-node/miden-node-rpc.md +++ b/docs/src/miden-node/miden-node-rpc.md @@ -1,5 +1,5 @@ # Miden node RPC -The **RPC** is an externally-facing component through which clients can interact with the node. It receives client requests (e.g., to synchronize with the latest state of the chain, or to submit transactions), performs basic validation, +The **RPC** is an externally-facing component through which clients can interact with the node. It receives client requests (e.g., to synchronize with the latest state of the chain, or to submit transactions), performs basic validation, and forwards the requests to the appropriate components. **RPC** is one of components of the Miden node. @@ -8,11 +8,11 @@ and forwards the requests to the appropriate components. `TODO` ## API -The **RPC** serves connections using the [gRPC protocol](https://grpc.io) on a port, set in the previously mentioned configuration file. +The **RPC** serves connections using the [gRPC protocol](https://grpc.io) on a port, set in the previously mentioned configuration file. Here is a brief description of supported methods. ### CheckNullifiers -Gets a list of proofs for given nullifier hashes, each proof as Sparse Merkle Trees +Gets a list of proofs for given nullifier hashes, each proof as Sparse Merkle Trees **Parameters:** @@ -37,10 +37,10 @@ Retrieves block header by given block number. Returns info which can be used by the client to sync up to the latest state of the chain for the objects (accounts, notes, nullifiers) the client is interested in. -This request returns the next block containing requested data. It also returns `chain_tip` which is the latest block number in the chain. +This request returns the next block containing requested data. It also returns `chain_tip` which is the latest block number in the chain. Client is expected to repeat these requests in a loop until `response.block_header.block_num == response.chain_tip`, at which point the client is fully synchronized with the chain. -Each request also returns info about new notes, nullifiers etc. created. It also returns Chain MMR delta that can be used to update the state of Chain MMR. +Each request also returns info about new notes, nullifiers etc. created. It also returns Chain MMR delta that can be used to update the state of Chain MMR. This includes both chain MMR peaks and chain MMR nodes. For preserving some degree of privacy, note tags and nullifiers filters contain only high part of hashes. Thus, returned data @@ -50,7 +50,7 @@ contains excessive notes and nullifiers, client can make additional filtering of * `block_num`: `uint32` – send updates to the client starting at this block. * `account_ids`: `[AccountId]` – accounts filter. -* `note_tags`: `[uint32]` – note tags filter. Corresponds to the high 16 bits of the real values. +* `note_tags`: `[uint32]` – note tags filter. Corresponds to the high 16 bits of the real values. * `nullifiers`: `[uint32]` – nullifiers filter. Corresponds to the high 16 bits of the real values. **Returns** diff --git a/docs/src/miden-node/miden-node-store.md b/docs/src/miden-node/miden-node-store.md index 0eeceeb46..aec140433 100644 --- a/docs/src/miden-node/miden-node-store.md +++ b/docs/src/miden-node/miden-node-store.md @@ -1,6 +1,6 @@ # Miden node store -The **Store** maintains the state of the chain. It serves as the "source of truth" for the chain - i.e., if it is not in -the store, the node does not consider it to be part of the chain. +The **Store** maintains the state of the chain. It serves as the "source of truth" for the chain - i.e., if it is not in +the store, the node does not consider it to be part of the chain. **Store** is one of components of the Miden node. ## Architecture @@ -56,7 +56,7 @@ Returns data needed by the block producer to construct and prove the next block. **Parameters** -* `account_ids`: `[AccountId]` – array of account IDs. +* `account_ids`: `[AccountId]` – array of account IDs. * `nullifiers`: `[Digest]` – array of nullifier hashes (not currently in use). **Returns** @@ -68,7 +68,7 @@ Returns data needed by the block producer to construct and prove the next block. ### GetTransactionInputs -Returns the data needed by the block producer to check validity of an incoming transaction. +Returns the data needed by the block producer to check validity of an incoming transaction. **Parameters** @@ -77,7 +77,7 @@ Returns the data needed by the block producer to check validity of an incoming t **Returns** -* `account_state`: `AccountTransactionInputRecord` – account's descriptors. +* `account_state`: `AccountTransactionInputRecord` – account's descriptors. * `nullifiers`: `[NullifierTransactionInputRecord]` – the block numbers at which corresponding nullifiers have been consumed, zero if not consumed. ### SyncState @@ -122,7 +122,7 @@ This request doesn't have any parameters. **Returns** -* `nullifiers`: `[NullifierLeaf]` – lists of all nullifiers of the current chain. +* `nullifiers`: `[NullifierLeaf]` – lists of all nullifiers of the current chain. ### ListAccounts diff --git a/docs/src/roadmap.md b/docs/src/roadmap.md index b15dbb96b..d18fccc62 100644 --- a/docs/src/roadmap.md +++ b/docs/src/roadmap.md @@ -1,3 +1,3 @@

-

\ No newline at end of file +

diff --git a/docs/src/transactions/transaction-execution.md b/docs/src/transactions/transaction-execution.md index fe11c5eed..3e15adeba 100644 --- a/docs/src/transactions/transaction-execution.md +++ b/docs/src/transactions/transaction-execution.md @@ -13,21 +13,21 @@ Transactions are being executed by the Miden Transaction Executor. Transaction e One of the main reasons for splitting execution and proving is that it allows to have "stateless provers" - i.e., the executed transaction contains all data needed to re-execute and prove a transaction (no database access is needed). This is very powerful and allows the distribution of proof generation much more easily. ## The Data Store and Transaction Inputs -The data store defines the interface that transaction objects use to fetch data required for transaction execution. It stores account, chain, and input note data required to execute a transaction against the account with the specified ID. +The data store defines the interface that transaction objects use to fetch data required for transaction execution. It stores account, chain, and input note data required to execute a transaction against the account with the specified ID. -Specifically, it must provide the following inputs to the transaction +Specifically, it must provide the following inputs to the transaction -- the `Account` including the [AccountID](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#account-id) and the [AccountCode](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#code) which will be executed during the transaction. +- the `Account` including the [AccountID](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#account-id) and the [AccountCode](https://0xpolygonmiden.github.io/miden-base/architecture/accounts.html#code) which will be executed during the transaction. - the `BlockHeader`, which contains metadata about the block, commitments to the current state of the chain and the hash of the proof that attests to the integrity of the chain. -- the `ChainMmr`, which allows for efficient authentication of consumed notes during transaction execution. Authentication is achieved by providing an inclusion proof for the consumed notes in the transaction against the `ChainMmr`-root associated with the latest block known at the time of transaction execution. +- the `ChainMmr`, which allows for efficient authentication of consumed notes during transaction execution. Authentication is achieved by providing an inclusion proof for the consumed notes in the transaction against the `ChainMmr`-root associated with the latest block known at the time of transaction execution. - the `InputNotes` that are being consumed in the transaction (InputNotes), including the corresponding note data, e.g. the [note script](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#script) and [serial number](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#serial-number). _Note: The `InputNotes` must all be already recorded on-chain in order for the transaction to succeed. And there is no Nullifier-check during a transaction. Nullifiers are being checked by the Miden Operator during transaction verification. So at the transaction level, there is "double spending"._ ## The Transaction Compiler -Every transaction must be executed within the Miden VM to generate a transaction proof. In Miden there is a proof for every transaction. The transaction compiler is responsible for building executable programs. The generated programs - MASM programs - can then be executed on the Miden VM which generates a zkProof. In addition to transaction compilation, the transaction compiler provides methods which can be used to compile Miden account code, note scripts, and transaction scripts. +Every transaction must be executed within the Miden VM to generate a transaction proof. In Miden there is a proof for every transaction. The transaction compiler is responsible for building executable programs. The generated programs - MASM programs - can then be executed on the Miden VM which generates a zkProof. In addition to transaction compilation, the transaction compiler provides methods which can be used to compile Miden account code, note scripts, and transaction scripts. -Compilation results in an executable MASM Program, including the provided account interface and notes, an optional transaction script and the [Transaction Kernel Program](transaction-kernel.md). The Transaction Kernel Program defines procedures and the memory layout for all parts of the transaction. A detailed description can be found in the next section. +Compilation results in an executable MASM Program, including the provided account interface and notes, an optional transaction script and the [Transaction Kernel Program](transaction-kernel.md). The Transaction Kernel Program defines procedures and the memory layout for all parts of the transaction. A detailed description can be found in the next section. Finally, after the transaction program has been compiled and the inputs including the advice provider were correctly populated, the transaction can be executed. diff --git a/docs/src/transactions/transaction-kernel.md b/docs/src/transactions/transaction-kernel.md index 94e0b79dc..68778c490 100644 --- a/docs/src/transactions/transaction-kernel.md +++ b/docs/src/transactions/transaction-kernel.md @@ -1,5 +1,5 @@ # The Transaction Kernel Program -The transaction kernel program is responsible to execute a Miden rollup transaction within the Miden VM. Therefore, it is written in [MASM](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/main.html) and it is defined as MASM [kernel](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/execution_contexts.html#kernels). The kernel provides context-sensitive security preventing unwanted read and write access. It defines a set of procedures which can be invoked from other [contexts](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/execution_contexts.html#execution-contexts) - e.g., notes - to be executed in the root context. +The transaction kernel program is responsible to execute a Miden rollup transaction within the Miden VM. Therefore, it is written in [MASM](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/main.html) and it is defined as MASM [kernel](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/execution_contexts.html#kernels). The kernel provides context-sensitive security preventing unwanted read and write access. It defines a set of procedures which can be invoked from other [contexts](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/execution_contexts.html#execution-contexts) - e.g., notes - to be executed in the root context. In general, the kernel's procedures must reflect everything users might want to do in executing transactions, from transferring assets to complex smart contract interactions with custom code. Learn more about available procedures and contexts [here](transaction-procedures.md). @@ -25,32 +25,32 @@ The transaction prologue is executed at the beginning of a transaction. It needs 2. Build a single vault ("tx vault") containing assets of all inputs (input notes and initial account state). 3. Verify that all input notes are present in the Note DB. -In other words, the prologue stores all provided information from the inputs and the advice provider into the appropriate memory slots. It then reads the data for account and notes from the advice provider, writes it to memory, hashes it, and verifies that the resulting hash matches the commitments provided via the stack. Finally, it creates a single vault for the assets that are involved. +In other words, the prologue stores all provided information from the inputs and the advice provider into the appropriate memory slots. It then reads the data for account and notes from the advice provider, writes it to memory, hashes it, and verifies that the resulting hash matches the commitments provided via the stack. Finally, it creates a single vault for the assets that are involved. -The memory layout looks as follows. The kernel context has access to all of those memory slots. +The memory layout looks as follows. The kernel context has access to all of those memory slots.

-The book keeping section is needed to keep track of variables which are used internally by the transaction kernel. +The book keeping section is needed to keep track of variables which are used internally by the transaction kernel. First, all **global inputs** are being stored in the pre-defined memory slots. Global inputs are being provided via the `operand_stack` to the VM at transaction execution. The include the block hash, the account ID, the initial account hash, and the Nullifier commitment. This is a sequential hash of all `(nullifier, ZERO)` pairs for the notes consumed in the transaction. Second, the **block data** is being processed. This involves reading the block data from the advice provider and storing it at the appropriate memory addresses. Block data is provided from the latest known block and consists of note, state and batch root, the block;s the previous hash and proof hash, as well as the block number. As the data is read from the advice provider, the block hash is computed. It is asserted that the computed block hash matches the block hash stored in the global inputs. -Third, the **chain data** is being processed in a similar way as the block data. In this case the chain root is being recomputed and compared against the chain root stored in the block data section. +Third, the **chain data** is being processed in a similar way as the block data. In this case the chain root is being recomputed and compared against the chain root stored in the block data section. Fourth, the **account data** is being processed. This involves reading the data from the advice provider and storing it at the appropriate memory addresses. The account data consists of roots of the account's vault, its storage and code. As the account data is read from the advice provider, the account hash is computed. If the account is new then the global initial account hash is updated and the new account is validated. If the account already exists then it is asserted that the computed account hash matches the account hash provided via global inputs. It is also asserted that the account id matches the account id provided via the global inputs (`operand_stack`). -Fifth, the **input notes** are being processed. This involves per note reading the data from the advice provider and storing it at the appropriate memory addresses. Next to the total number of consumed notes, input note data consists of its serial number, the roots of the script, inputs and asset vault, its metadata and all its assets. As each note is consumed its hash and nullifier is computed. The transaction Nullifier commitment is computed via a sequential hash of all `(nullifier, ZERO)` pairs for all consumed notes. This step involves authentication that the input note data provided via the advice provider is consistent with the chain history. +Fifth, the **input notes** are being processed. This involves per note reading the data from the advice provider and storing it at the appropriate memory addresses. Next to the total number of consumed notes, input note data consists of its serial number, the roots of the script, inputs and asset vault, its metadata and all its assets. As each note is consumed its hash and nullifier is computed. The transaction Nullifier commitment is computed via a sequential hash of all `(nullifier, ZERO)` pairs for all consumed notes. This step involves authentication that the input note data provided via the advice provider is consistent with the chain history. _Note: One needs to provide the note data to compute the Nullifier, e.g. the [note script](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#script) and the [serial number](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#serial-number). So one needs to know the note data to execute the prologue of a transaction. This is how the [note recipient](https://0xpolygonmiden.github.io/miden-base/architecture/notes.html#note-recipient) defines the set of users who can consume a specific note. The executing account needs to provide the pre-image data to the recipient at the time of execution._ -Lastly, if a transaction script is provided, its root is being stored at the pre-defined memory address. +Lastly, if a transaction script is provided, its root is being stored at the pre-defined memory address. ## The Note Processing -If there are input notes they are being consumed in a loop. For every note, the [MAST root](https://0xpolygonmiden.github.io/miden-vm/design/programs.html) of the note script is being loaded onto the stack. Then, by calling a [`dyncall`](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/code_organization.html?highlight=dyncall#dynamic-procedure-invocation) the note script is being executed in a new context to prevent unwanted memory access. +If there are input notes they are being consumed in a loop. For every note, the [MAST root](https://0xpolygonmiden.github.io/miden-vm/design/programs.html) of the note script is being loaded onto the stack. Then, by calling a [`dyncall`](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/code_organization.html?highlight=dyncall#dynamic-procedure-invocation) the note script is being executed in a new context to prevent unwanted memory access. ``` # loop while we have notes to consume @@ -75,7 +75,7 @@ If there are input notes they are being consumed in a loop. For every note, the end ``` -In processing a note, the creation of a new note might be triggered. If so, all necessary information about the new note is being stored in the *output note data* in memory. +In processing a note, the creation of a new note might be triggered. If so, all necessary information about the new note is being stored in the *output note data* in memory. _Note: The Miden Transaction Kernel Program prevents notes from having direct access to account storage. Notes can only call the account interface to trigger write operations in the account._ @@ -96,7 +96,7 @@ _Note: The executing account must expose the `auth_tx_rpo_falcon512` function in ## The Epilogue -The Epilogue finalizes the transaction. It +The Epilogue finalizes the transaction. It 1. computes the final account hash 2. if the account has changed, assert that the final account nonce is greater than the initial @@ -104,7 +104,7 @@ The Epilogue finalizes the transaction. It 3. computes the created notes commitment 4. asserts that the input and output vault roots are equal -There is an exception for special accounts, called faucets, which can mint or burn assets. In that case input and output vault roots are not equal. +There is an exception for special accounts, called faucets, which can mint or burn assets. In that case input and output vault roots are not equal. ## The Outputs -The transaction kernel program outputs the transaction script root, a commitment of all newly created outputs notes, and the account hash in its new state. +The transaction kernel program outputs the transaction script root, a commitment of all newly created outputs notes, and the account hash in its new state. diff --git a/docs/src/transactions/transaction-procedures.md b/docs/src/transactions/transaction-procedures.md index 3fe45f89d..da44b87a7 100644 --- a/docs/src/transactions/transaction-procedures.md +++ b/docs/src/transactions/transaction-procedures.md @@ -1,7 +1,7 @@ # Transaction Contexts Miden assembly program execution can span multiple isolated contexts. An execution context defines its own memory space which is not accessible from other execution contexts. Note scripts cannot directly write into account data. This should be possible if only if the account exposes respective functions. -The kernel program always starts executing in a root context. Thus, the prologue sets the memory for the root context. To move execution into a different context, we can invoke a procedure using the `call` or `dyncall` instruction. In fact, any time we invoke a procedure using the `call` instruction, the procedure is executed in a new context. +The kernel program always starts executing in a root context. Thus, the prologue sets the memory for the root context. To move execution into a different context, we can invoke a procedure using the `call` or `dyncall` instruction. In fact, any time we invoke a procedure using the `call` instruction, the procedure is executed in a new context. While executing in a note, account, or tx script context, we can request to execute some procedures in the kernel context, which is where all necessary information was stored during the prologue. Switching to the kernle context can be done via the `syscall` instruction. The set of procedures which can be invoked via the `syscall` instruction is limited by the [transaction kernel API](https://github.com/0xPolygonMiden/miden-base/blob/main/miden-lib/asm/kernels/transaction/api.masm). Once the procedure call via `syscall` returns, the execution moves back to the note, account, or tx script from which it was invoked. @@ -16,7 +16,7 @@ While executing in a note, account, or tx script context, we can request to exec \ \ -The above diagram shows different context switches in a simple transaction. In this example, an account consumes a [P2ID](https://github.com/0xPolygonMiden/miden-base/blob/main/miden-lib/asm/note_scripts/P2ID.masm) note and receives the asset into its vault. As with in any MASM program, the transaction kernel program starts in the root context. It executes the Prologue and stores all necessary information into the root memory. +The above diagram shows different context switches in a simple transaction. In this example, an account consumes a [P2ID](https://github.com/0xPolygonMiden/miden-base/blob/main/miden-lib/asm/note_scripts/P2ID.masm) note and receives the asset into its vault. As with in any MASM program, the transaction kernel program starts in the root context. It executes the Prologue and stores all necessary information into the root memory. The next step, note processing, starts with a `dyncall` and in doing so, invoking the note script. This command moves execution into a different context **(1)**. In this new context, the note has no access to the kernel memory. After a successful ID check, which changes back to the kernel context twice to get the note inputs and the account id, the script executes the `add_note_assets_to_account` procedure. @@ -25,7 +25,7 @@ The next step, note processing, starts with a `dyncall` and in doing so, invokin # matches target account ID specified by the note inputs. # ... begin - + ... exec.add_note_assets_to_account @@ -33,7 +33,7 @@ begin end ``` -The procedure cannot simply add assets to the account, because it is executed in a note context. Therefore, it needs to `call` the account interface. And in doing so, it moves execution into a second context - Account context - isolated from the note context **(2)**. +The procedure cannot simply add assets to the account, because it is executed in a note context. Therefore, it needs to `call` the account interface. And in doing so, it moves execution into a second context - Account context - isolated from the note context **(2)**. ``` #! Helper procedure to add all assets of a note to an account. @@ -53,7 +53,7 @@ proc.add_note_assets_to_account end ``` -The [wallet](https://github.com/0xPolygonMiden/miden-base/blob/main/miden-lib/asm/miden/contracts/wallets/basic.masm) smart contract provides an interface for accounts to recieve and send assets. In this new context, the wallet calls the `add_asset` procedure of the account API. +The [wallet](https://github.com/0xPolygonMiden/miden-base/blob/main/miden-lib/asm/miden/contracts/wallets/basic.masm) smart contract provides an interface for accounts to recieve and send assets. In this new context, the wallet calls the `add_asset` procedure of the account API. ``` export.receive_asset @@ -72,13 +72,13 @@ export.add_asset end ``` -Now, the asset can be safely added to the vault within the kernel context and the note successfully be processed. +Now, the asset can be safely added to the vault within the kernel context and the note successfully be processed. # Transaction Procedures -There are user-facing procedures and kernel procedures. Users don't directly invoke kernel procedures, but indirectly via account code, note or transaction scripts. In that case, kernel procedures can only be invoked by a `syscall` instruction which always executes in the kernel context. +There are user-facing procedures and kernel procedures. Users don't directly invoke kernel procedures, but indirectly via account code, note or transaction scripts. In that case, kernel procedures can only be invoked by a `syscall` instruction which always executes in the kernel context. ## User-facing Procedures (APIs) -These procedures can be used to create smart contract / account code, note scripts or account scripts. They basically serve as an API for the underlying kernel procedures. If a procedure can be called in the current context an `exec` is sufficient, otherwise if being the wrong context procedures must be invoked by `call`. Users will never need to invoke `syscall` procedures themselves. +These procedures can be used to create smart contract / account code, note scripts or account scripts. They basically serve as an API for the underlying kernel procedures. If a procedure can be called in the current context an `exec` is sufficient, otherwise if being the wrong context procedures must be invoked by `call`. Users will never need to invoke `syscall` procedures themselves. _Note: If capitalized, a variable represents a `Word`, e.g., `ACCT_HASH` consists of four `Felts`. If lowercase, the variable is represented by a single `Felt`._ @@ -144,6 +144,5 @@ To import the faucet procedures set `use.miden::faucet` at the beginning of the | `get_total_issuance` | `[]` | `[total_issuance]`| faucet |
ViewReturns the total issuance of the fungible faucet the transaction is being executed against. Panics if the transaction is not being executed against a fungible faucet. total_issuance is the total issuance of the fungible faucet the transaction is being executed against.
| -## Kernel Procedures -WIP - we will add those later. - +## Kernel Procedures +WIP - we will add those later. diff --git a/miden-lib/asm/miden/kernels/tx/account.masm b/miden-lib/asm/miden/kernels/tx/account.masm index f259cf491..63c97f946 100644 --- a/miden-lib/asm/miden/kernels/tx/account.masm +++ b/miden-lib/asm/miden/kernels/tx/account.masm @@ -350,7 +350,7 @@ export.set_item # instructions - see: https://github.com/0xPolygonMiden/miden-vm/issues/1122 # emit event to signal that an account storage item is being updated push.1 drop emit.ACCOUNT_STORAGE_SET_ITEM_EVENT - + # get the storage root exec.memory::get_acct_storage_root # => [R, index, V'] diff --git a/miden-lib/asm/miden/kernels/tx/epilogue.masm b/miden-lib/asm/miden/kernels/tx/epilogue.masm index 90b745300..0575b81d9 100644 --- a/miden-lib/asm/miden/kernels/tx/epilogue.masm +++ b/miden-lib/asm/miden/kernels/tx/epilogue.masm @@ -16,7 +16,7 @@ proc.copy_output_notes_to_advice_map # get the number of notes created by the transaction exec.memory::get_num_created_notes # => [num_notes, OUTPUT_NOTES_COMMITMENT, ...] - + # if there are created notes, add them to the advice map dup eq.0 if.true diff --git a/miden-lib/asm/note_scripts/P2ID.masm b/miden-lib/asm/note_scripts/P2ID.masm index 532c4fa7f..1a80e14af 100644 --- a/miden-lib/asm/note_scripts/P2ID.masm +++ b/miden-lib/asm/note_scripts/P2ID.masm @@ -64,7 +64,7 @@ begin # drop the note script root dropw # => [] - + # store the note inputs to memory starting at address 0 push.0 exec.note::get_inputs # => [num_inputs, inputs_ptr] diff --git a/miden-lib/asm/note_scripts/SWAP.masm b/miden-lib/asm/note_scripts/SWAP.masm index f4eb09da6..e844baf33 100644 --- a/miden-lib/asm/note_scripts/SWAP.masm +++ b/miden-lib/asm/note_scripts/SWAP.masm @@ -4,7 +4,7 @@ use.miden::contracts::wallets::basic->wallet # Swap script: adds an asset from the note into consumers account and # creates a note consumable by note issuer containing requested ASSET. # -# Requires that the account exposes: +# Requires that the account exposes: # # Inputs: [SCRIPT_ROOT] # Outputs: [] @@ -31,7 +31,7 @@ begin # load the asset and add it to the account mem_loadw call.wallet::receive_asset dropw - # => [] + # => [] # store note inputs into memory starting at address 0 push.0 exec.note::get_inputs @@ -57,4 +57,4 @@ begin # create a note using inputs call.wallet::send_asset dropw dropw # => [] -end \ No newline at end of file +end diff --git a/objects/src/accounts/mod.rs b/objects/src/accounts/mod.rs index 44174dcb9..365cdd1be 100644 --- a/objects/src/accounts/mod.rs +++ b/objects/src/accounts/mod.rs @@ -110,13 +110,13 @@ impl Account { ) } - /// Returns hash of this account as used for the initial account state hash in transaction - /// proofs. - /// - /// For existing accounts, this is exactly the same as [Account::hash()], however, for new - /// accounts this value is set to [ZERO; 4]. This is because when a transaction is executed - /// agains a new account, public input for the initial account state is set to [ZERO; 4] to - /// distinguish new accounts from existing accounts. The actual hash of the initial account + /// Returns hash of this account as used for the initial account state hash in transaction + /// proofs. + /// + /// For existing accounts, this is exactly the same as [Account::hash()], however, for new + /// accounts this value is set to [ZERO; 4]. This is because when a transaction is executed + /// agains a new account, public input for the initial account state is set to [ZERO; 4] to + /// distinguish new accounts from existing accounts. The actual hash of the initial account /// state (and the initial state itself), are provided to the VM via the advice provider. pub fn proof_init_hash(&self) -> Digest { if self.is_new() {