zksync-era integration docs #211
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oppen
reviewed
Aug 22, 2024
Oppen
reviewed
Aug 22, 2024
docs/zksync-era-integration.md
Outdated
|
|
||
| - **Operator/Sequencer**: the server that initializes the vm, injects the Bootloader bytecode, receives transactions and pushes them into the vm(bootloader memory to be more specific) and start batches and seals them. | ||
| - **Bootloader**: a system contract that receives an array of transactions which are processed, validated, executed, and then, the final state is published in the l1. | ||
| - **era_vm**: the virtual machine where the Bootloader(and so all the transactions bytecode) gets executed. |
There was a problem hiding this comment.
Suggested change
| - **era_vm**: the virtual machine where the Bootloader(and so all the transactions bytecode) gets executed. | |
| - **era_vm**: the virtual machine where the Bootloader (and so all the transactions bytecode) gets executed. |
docs/zksync-era-integration.md
Outdated
|
|
||
| The initial validation of the batch is necessary, since, as we'll see below, the Bootloader starts with its memory pre-filled with any data the operator wants. That is why it needs to validate its correctness. | ||
|
|
||
| For more details, you can see the [main loop](https://github.com/matter-labs/era-contracts/blob/main/system-contracts/Bootloader/bootloader.yul#L3962-L3965) or the [full contract code](https://github.com/matter-labs/era-contracts/blob/main/system-contracts/bootloader/bootloader.yu). |
There was a problem hiding this comment.
Suggested change
| For more details, you can see the [main loop](https://github.com/matter-labs/era-contracts/blob/main/system-contracts/Bootloader/bootloader.yul#L3962-L3965) or the [full contract code](https://github.com/matter-labs/era-contracts/blob/main/system-contracts/bootloader/bootloader.yu). | |
| For more details, you can see the [main loop](https://github.com/matter-labs/era-contracts/blob/main/system-contracts/bootloader/bootloader.yul#L3962-L3965) or the [full contract code](https://github.com/matter-labs/era-contracts/blob/main/system-contracts/bootloader/bootloader.yul). |
docs/zksync-era-integration.md
Outdated
|
|
||
| 2. There isn't any consensus or spec about how storage should be implemented. We came up with this API because it is what we thought was more convenient for the requirement. But, for example, the vm1 implements a query logic, where the operator will react based on the provided params. | ||
|
|
||
| [Here](https://github.com/lambdaclass/zksync-era/blob/era_vm_integration_v2/core/lib/multivm/src/versions/era_vm/vm.rs#L726) you can take a look a the implementation of this trait in detail. |
There was a problem hiding this comment.
Suggested change
| [Here](https://github.com/lambdaclass/zksync-era/blob/era_vm_integration_v2/core/lib/multivm/src/versions/era_vm/vm.rs#L726) you can take a look a the implementation of this trait in detail. | |
| [Here](https://github.com/lambdaclass/zksync-era/blob/era_vm_integration_v2/core/lib/multivm/src/versions/era_vm/vm.rs#L726) you can take a look at the implementation of this trait in detail. |
Comment on lines
+117
to
+119
| ### Rollbacks and snapshots | ||
|
|
||
| In the `era_vm`, when a transaction encounters a panic or reverts, the vm needs to roll back the changes, restoring only a part of the [state](https://github.com/lambdaclass/era_vm/blob/main/src/state.rs#L43-L60) to its previous frame. Remember that frames are created under `near_call` and `far_call` opcodes. Currently, rollbacks are perform using snapshots which are just copies of the current state. If a rollback is necessary, the state is restored from these snapshots. |
There was a problem hiding this comment.
This section may be better suited here.
There was a problem hiding this comment.
The idea was to recall the idea of rollbacks in era_vm to emphasize the difference with bootloader rollbacks.
jrchatruc
reviewed
Aug 26, 2024
docs/zksync-era-integration.md
Outdated
|
|
||
| ## Introduction | ||
|
|
||
| So far we have been talking only about the `era_vm`. But you should know that the vm is only a small part of the zk stack. The zk stack is composed of many critical components. In this section, we are only going to be interested in one particular component: the **nodes**, which can further be decomposed into the following units: |
There was a problem hiding this comment.
we are only going to be interested in one particular component: the nodes, which can further be decomposed into the following units:
The word node is a bit overloaded, I would rephrase this as saying the component we are interested in is the Operator/Sequencer, explain what it is and talk about both the bootloader and the VM that it uses
jrchatruc
reviewed
Aug 26, 2024
docs/zksync-era-integration.md
Outdated
|
|
||
| The Bootloader is a special system contract whose hash resides on L1, but its code isn't stored on either L1 or L2. Instead, it’s compiled from `.yul` to `era_vm` assembly using `zksolc` when the operator first initializes the VM (more on that below). | ||
|
|
||
| The Bootloader, unlike Ethereum, takes an array of transactions(a batch) and executes all of them in one run (unless specified not to, that is, if the execution mode of the vm is set to OneTx). This approach allows the transaction batch to be posted on the l1 as just a single one, making the processing on Ethereum cheaper, since taxes and gas can be distributed among all the transactions within the posted batch. |
There was a problem hiding this comment.
The Bootloader, unlike Ethereum
I would remove the unlike Ethereum part here since it's a little confusing, Ethereum also executes batches (blocks) of transactions even though it does not have the concept of a bootloader.
since taxes and gas can be distributed among all the transactions within the posted batch.
since gas can be distributed among all the transactions within the posted batch and and data publishing costs can be reduced by posting only state diffs
jrchatruc
reviewed
Aug 26, 2024
docs/zksync-era-integration.md
Outdated
| At the most basic level, the Bootloader performs the following steps: | ||
|
|
||
| 1. Reads the initial batch information and makes a call to the SystemContext contract to validate the batch. | ||
| 2. Loops through all transactions and executes them until the `execute` flag is set to $0$, at that point, it jumps to step 3. <!-- Here we could also add that the transaction gets processed based on where it came from (l1 or l2) --> |
There was a problem hiding this comment.
Let's add a small comment about this, doesn't need to explain how l1/l2 transactions differ from each other but at least mention them
jrchatruc
reviewed
Aug 26, 2024
docs/zksync-era-integration.md
Outdated
|
|
||
| ## Operator/sequencer | ||
|
|
||
| Currently, the operator is a centralized server (there are plans to make a decentralized consensus for operators) which can be thought of as the node entry point, its responsibilities are: |
There was a problem hiding this comment.
which can be thought of as the node entry point
Again, I would remove this since the word node is too overloaded (right now the word node and operator` are usually interchangeable actually)
jrchatruc
reviewed
Aug 26, 2024
docs/zksync-era-integration.md
Outdated
|
|
||
| This storage is saved in the VM state as a pointer. Here’s a brief explanation of each function: | ||
|
|
||
| - **decommit**: given a hash it returns a contract bytecode from the database. |
There was a problem hiding this comment.
given a hash it returns a contract bytecode from the database.
given a contract hash it returns its corresponding bytecode (if it exists) from the database
jrchatruc
reviewed
Aug 26, 2024
docs/zksync-era-integration.md
Outdated
| } | ||
| ``` | ||
|
|
||
| This allows us to query a key that belongs to the current executing address. |
There was a problem hiding this comment.
This allows us to query a key that belongs to the current executing address.
This allows us to query a storage key belonging to any desired contract through its address
jrchatruc
reviewed
Aug 26, 2024
docs/zksync-era-integration.md
Outdated
| - **refunds**: A list of refund amounts that have been calculated during execution. | ||
| - **read_storage_slots**: A set of storage keys that have been read during execution, used to calculate gas fees and refunds. | ||
| - **written_storage_slots**: A set of storage keys that have been written to during execution, used to calculate gas fees and refunds. | ||
| - **decommitted_hashes**: Stores the hashes that have been the decommited through the whole execution. When decommiting a hash in a `far_call` or `decommit`, we check if the has been already decommited, if true then the decommit is free of charge. |
There was a problem hiding this comment.
Stores the hashes that have been the decommited through the whole execution.
Stores the hashes that have been decommited through the whole execution.
we check if the has been already decommited,
we check if it has already been decommited,
jrchatruc
reviewed
Aug 26, 2024
docs/zksync-era-integration.md
Outdated
|
|
||
| This allows us to query a key that belongs to the current executing address. | ||
|
|
||
| 2. There isn't any consensus or spec about how storage should be implemented. We came up with this API because it is what we thought was more convenient for the requirement. But, for example, the vm1 implements a query logic, where the operator will react based on the provided params. |
There was a problem hiding this comment.
But, for example, the vm1 implements a query logic, where the operator will react based on the provided params.
Can we give a concrete example of what this looks like?
|
Ergs comparison results: |
gianbelinche
approved these changes
Aug 30, 2024
jrchatruc
approved these changes
Sep 3, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds documentation about the integration with zksync-era.