Skip to content
This repository has been archived by the owner on Oct 3, 2024. It is now read-only.

Commit

Permalink
(WIP) feat(chore): zkSync node public release (#1059)
Browse files Browse the repository at this point in the history 
Co-authored-by: Dustin Brickwood <dustinbrickwood204@gmail.com>
Co-authored-by: agolajko <57454127+agolajko@users.noreply.github.com>
Co-authored-by: Nicolas Villanueva <nicolasvillanueva@msn.com>
  • Loading branch information
@githubdoramon @dutterbutter
@agolajko @MexicanAce
4 people authored May 13, 2024
1 parent 86a9ec9 commit 34c6c79
Show file tree
Hide file tree
Showing 8 changed files with 154 additions and 153 deletions.
8 changes: 4 additions & 4 deletions docs/infra/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@ head:
>
<img
src="/images/landing/lets-get-started.png"
alt="Running an external node"
alt="Running a zkSync node"
>
<div class="content">
<h3>Introduction</h3>
<p>Learn more about our external node.</p>
<p>Learn more about zkSync nodes.</p>
</div>
</RouterLink>
<RouterLink
Expand All @@ -44,8 +44,8 @@ head:
alt="Diverse Toolkit"
>
<div class="content">
<h3>External Node Components</h3>
<p>Overview of the EN's main components.</p>
<h3>zkSync Node Components</h3>
<p>Overview of the zkSync node's main components.</p>
</div>
</RouterLink>
</div>
Expand Down
76 changes: 38 additions & 38 deletions docs/infra/api-overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,49 +8,49 @@ head:
# API Overview

:::info
The API exposed by the EN is designed to be Web3-compliant. Any deviation from the Ethereum behavior is likely unintended, and we encourage users to report such discrepancies.
The API exposed by the zkSync node is designed to be Web3-compliant. Any deviation from the Ethereum behavior is likely unintended, and we encourage users to report such discrepancies.
:::

### `eth_` Namespace

Data getters in this namespace operate in the L2 domain. They deal with L2 block numbers, check balances in L2, and more.

| Method | Notes |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| `eth_blockNumber` | |
| `eth_chainId` | |
| `eth_call` | |
| `eth_estimateGas` | |
| `eth_gasPrice` | |
| `eth_newFilter` | Maximum amount of installed filters is configurable |
| `eth_newBlockFilter` | Same as above |
| `eth_newPendingTransactionsFilter` | Same as above |
| `eth_uninstallFilter` | |
| `eth_getLogs` | Maximum amount of returned entities can be configured |
| `eth_getFilterLogs` | Same as above |
| `eth_getFilterChanges` | Same as above |
| `eth_getBalance` | |
| `eth_getBlockByNumber` | |
| `eth_getBlockByHash` | |
| `eth_getBlockTransactionCountByNumber` | |
| `eth_getBlockTransactionCountByHash` | |
| `eth_getCode` | |
| `eth_getStorageAt` | |
| `eth_getTransactionCount` | |
| `eth_getTransactionByHash` | |
| `eth_getTransactionByBlockHashAndIndex` | |
| `eth_getTransactionByBlockNumberAndIndex` | |
| `eth_getTransactionReceipt` | |
| `eth_protocolVersion` | |
| `eth_sendRawTransaction` | |
| `eth_syncing` | EN is considered synced if it's less than 11 blocks behind the main node. |
| `eth_coinbase` | Always returns a zero address |
| `eth_accounts` | Always returns an empty list |
| `eth_getCompilers` | Always returns an empty list |
| `eth_hashrate` | Always returns zero |
| `eth_getUncleCountByBlockHash` | Always returns zero |
| `eth_getUncleCountByBlockNumber` | Always returns zero |
| `eth_mining` | Always returns false |
| Method | Notes |
| ----------------------------------------- | ---------------------------------------------------------------------------------- |
| `eth_blockNumber` | |
| `eth_chainId` | |
| `eth_call` | |
| `eth_estimateGas` | |
| `eth_gasPrice` | |
| `eth_newFilter` | Maximum amount of installed filters is configurable |
| `eth_newBlockFilter` | Same as above |
| `eth_newPendingTransactionsFilter` | Same as above |
| `eth_uninstallFilter` | |
| `eth_getLogs` | Maximum amount of returned entities can be configured |
| `eth_getFilterLogs` | Same as above |
| `eth_getFilterChanges` | Same as above |
| `eth_getBalance` | |
| `eth_getBlockByNumber` | |
| `eth_getBlockByHash` | |
| `eth_getBlockTransactionCountByNumber` | |
| `eth_getBlockTransactionCountByHash` | |
| `eth_getCode` | |
| `eth_getStorageAt` | |
| `eth_getTransactionCount` | |
| `eth_getTransactionByHash` | |
| `eth_getTransactionByBlockHashAndIndex` | |
| `eth_getTransactionByBlockNumberAndIndex` | |
| `eth_getTransactionReceipt` | |
| `eth_protocolVersion` | |
| `eth_sendRawTransaction` | |
| `eth_syncing` | zkSync node is considered synced if it's less than 11 blocks behind the main node. |
| `eth_coinbase` | Always returns a zero address |
| `eth_accounts` | Always returns an empty list |
| `eth_getCompilers` | Always returns an empty list |
| `eth_hashrate` | Always returns zero |
| `eth_getUncleCountByBlockHash` | Always returns zero |
| `eth_getUncleCountByBlockNumber` | Always returns zero |
| `eth_mining` | Always returns false |

### **PubSub**

Expand Down Expand Up @@ -113,4 +113,4 @@ This namespace holds rollup-specific extensions to the Web3 API. Only the method

### `en` Namespace

This namespace includes methods that external nodes call on the main node during syncing. If this namespace is active, other ENs can sync using this node.
This namespace includes methods that zkSync nodes call on the main node during syncing. If this namespace is active, other zkSync nodes can sync using this node.
38 changes: 19 additions & 19 deletions docs/infra/component-breakdown.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,32 @@ head:
content: Component Breakdown | zkSync Docs
---

# EN components
# zkSync node components

This section contains an overview of the EN's main components.
This section contains an overview of the zkSync node's main components.

## API

The EN can serve both the HTTP and the WS Web3 API, as well as PubSub. Whenever possible, it provides data based on the
The zkSync node can serve both the HTTP and the WS Web3 API, as well as PubSub. Whenever possible, it provides data based on the
local state, with a few exceptions:

- Submitting transactions: Since it is a read replica, submitted transactions are proxied to the main node, and the
response is returned from the main node.
- Querying transactions: The EN is not aware of the main node's mempool, and it does not sync rejected transactions.
Therefore, if a local lookup for a transaction or its receipt fails, the EN will attempt the same query on the main
- Querying transactions: The zkSync node is not aware of the main node's mempool, and it does not sync rejected transactions.
Therefore, if a local lookup for a transaction or its receipt fails, the zkSync node will attempt the same query on the main
node.

Apart from these cases, the API does not depend on the main node. Even if the main node is temporarily unavailable, the
EN can continue to serve the state it has locally.
zkSync node can continue to serve the state it has locally.

## Fetcher

The Fetcher component is responsible for maintaining synchronization between the EN and the main node. Its primary task
The Fetcher component is responsible for maintaining synchronization between the zkSync node and the main node. Its primary task
is to fetch new blocks in order to update the local chain state. However, its responsibilities extend beyond that. For
instance, the Fetcher is also responsible for keeping track of L1 batch statuses. This involves monitoring whether
locally applied batches have been committed, proven, or executed on L1.

It is worth noting that in addition to fetching the _state_, the EN also retrieves the L1 gas price from the main node
It is worth noting that in addition to fetching the _state_, the zkSync node also retrieves the L1 gas price from the main node
for the purpose of estimating fees for L2 transactions (since this also happens based on the local state). This
information is necessary to ensure that gas estimations are performed in the exact same manner as the main node, thereby
reducing the chances of a transaction not being included in a block.
Expand All @@ -39,10 +39,10 @@ reducing the chances of a transaction not being included in a block.

The State Keeper component serves as the "sequencer" part of the node. It shares most of its functionality with the main
node, with one key distinction. The main node retrieves transactions from the mempool and has the authority to decide
when a specific L2 block or L1 batch should be sealed. On the other hand, the EN retrieves transactions from the queue
when a specific L2 block or L1 batch should be sealed. On the other hand, the zkSync node retrieves transactions from the queue
populated by the Fetcher and seals the corresponding blocks/batches based on the data obtained from the Fetcher queue.

The actual execution of batches takes place within the VM, which is identical in both the Main and External nodes.
The actual execution of batches takes place within the VM, which is identical in any zkSync node.

## Reorg Detector

Expand All @@ -52,33 +52,33 @@ due to significant issues: e.g. a bug in the sequencer implementation preventing
finality, the zkSync operator can perform a rollback, reverting one or more batches and restoring the blockchain state
to a previous point. Finalized batches cannot be reverted at all.

However, even though such situations are rare, the EN must handle them correctly.
However, even though such situations are rare, the zkSync node must handle them correctly.

To address this, the EN incorporates a Reorg Detector component. This module keeps track of all L1 batches that have not
To address this, the zkSync node incorporates a Reorg Detector component. This module keeps track of all L1 batches that have not
yet been finalized. It compares the locally obtained state root hashes with those provided by the main node's API. If
the root hashes for the latest available L1 batch do not match, the Reorg Detector searches for the specific L1 batch
responsible for the divergence. Subsequently, it rolls back the local state and restarts the node. Upon restart, the EN
responsible for the divergence. Subsequently, it rolls back the local state and restarts the node. Upon restart, the zkSync node
resumes normal operation.

[finality]: https://docs.zksync.io/zk-stack/concepts/finality.html

## Consistency Checker

The main node API serves as the primary source of information for the EN. However, relying solely on the API may not
The main node API serves as the primary source of information for the zkSync node. However, relying solely on the API may not
provide sufficient security since the API data could potentially be incorrect due to various reasons. The primary source
of truth for the rollup system is the L1 smart contract. Therefore, to enhance the security of the EN, each L1 batch
of truth for the rollup system is the L1 smart contract. Therefore, to enhance the security of the zkSync node, each L1 batch
undergoes cross-checking against the L1 smart contract by a component called the Consistency Checker.

When the Consistency Checker detects that a particular batch has been sent to L1, it recalculates a portion of the input
known as the "block commitment" for the L1 transaction. The block commitment contains crucial data such as the state
root and batch number, and is the same commitment that is used for generating a proof for the batch. The Consistency
Checker then compares the locally obtained commitment with the actual commitment sent to L1. If the data does not match,
it indicates a potential bug in either the main node or external node implementation or that the main node API has
provided incorrect data. In either case, the state of the EN cannot be trusted, and the EN enters a crash loop until the
it indicates a potential bug in either the main zkSync node or full node implementation or that the main node API has
provided incorrect data. In either case, the state of the zkSync node cannot be trusted, and the zkSync full node enters a crash loop until the
issue is resolved.

## Health check server

The EN also exposes an additional server that returns HTTP 200 response when the EN is operating normally, and HTTP 503
response when some of the health checks don't pass (e.g. when the EN is not fully initialized yet). This server can be
The zkSync node also exposes an additional server that returns HTTP 200 response when the zkSync node is operating normally, and HTTP 503
response when some of the health checks don't pass (e.g. when the zkSync node is not fully initialized yet). This server can be
used, for example, to implement the readiness probe in an orchestration solution you use.
Loading

0 comments on commit 34c6c79

Please sign in to comment.