Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(en): make documentation more chain agnostic #3376

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

feat(en): make documentation more chain agnostic #3376

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
77c151c
EN documentation improvements
tomg10 Dec 10, 2024
80a14f1
fmt
tomg10 Dec 10, 2024
2f6be27
improvement
tomg10 Dec 11, 2024
1a778ba
improvements
tomg10 Dec 11, 2024
7daa0e7
improvements
tomg10 Dec 11, 2024
58965fc
Merge branch 'main' into en-documentation-improvements
tomg10 Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion core/lib/snapshots_applier/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Library responsible for recovering Postgres from a protocol-level snapshot.

## Recovery workflow

_(See [node docs](../../../docs/guides/external-node/07_snapshots_recovery.md) for a high-level snapshot recovery
_(See [node docs](../../../docs/src/guides/external-node/07_snapshots_recovery.md) for a high-level snapshot recovery
overview and [snapshot creator docs](../../bin/snapshots_creator/README.md) for the snapshot format details)_

1. Recovery is started by querying the main node and determining the snapshot parameters. By default, recovery is
Expand Down
2 changes: 1 addition & 1 deletion core/node/consensus/src/en.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ impl EN {
tracing::warn!("\
WARNING: this node is using ZKsync API synchronization, which will be deprecated soon. \
Please follow this instruction to switch to p2p synchronization: \
https://github.com/matter-labs/zksync-era/blob/main/docs/guides/external-node/10_decentralization.md");
https://github.com/matter-labs/zksync-era/blob/main/docs/src/guides/external-node/10_decentralization.md");
let res: ctx::Result<()> = scope::run!(ctx, |ctx, s| async {
// Update sync state in the background.
s.spawn_bg(self.fetch_state_loop(ctx));
Expand Down
2 changes: 1 addition & 1 deletion core/node/db_pruner/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ There are two types of objects that are not fully cleaned:

## Pruning workflow

_(See [node docs](../../../docs/guides/external-node/08_pruning.md) for a high-level pruning overview)_
_(See [node docs](../../../docs/src/guides/external-node/08_pruning.md) for a high-level pruning overview)_

There are two phases of pruning an L1 batch, soft pruning and hard pruning. Every batch that would have its records
removed if first _soft-pruned_. Soft-pruned batches cannot safely be used. One minute (this is configurable) after soft
Expand Down
2 changes: 1 addition & 1 deletion core/node/node_storage_init/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# `zksync_node_storage_init`

A set of actions to ensure that any ZKsync node has initialized storage and can start running.
A set of actions to ensure that any Node has initialized storage and can start running.

This includes genesis, but not limited to it, and may involve other steps.
6 changes: 3 additions & 3 deletions docs/src/announcements/attester_commitee.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Overview

The Attester committee is a subset of ZKSync nodes. After each l1 batch execution, participating nodes sign its
execution result and send back to the network.
The Attester committee is a subset of Nodes. After each l1 batch execution, participating nodes sign its execution
result and send back to the network.

The ultimate goal is to make L1 commit operation contingent on such signatures. This will improve the security and
finality guarantees: having these signatures on L1 shows that additional actors executed the corresponding blocks - and
Expand Down Expand Up @@ -36,7 +36,7 @@ Participants can leave the committee at any time.
The only action that is required to participate is to share your attester public key with the Main Node operator (by
opening an issue in this repo or using any other communication channel). You can find it in the comment in the
`consensus_secrets.yaml` file (that was - in most cases - generated by the tool described
[here](https://github.com/matter-labs/zksync-era/blob/main/docs/guides/external-node/10_decentralization.md#generating-secrets))
[here](https://github.com/matter-labs/zksync-era/blob/main/docs/src/guides/external-node/10_decentralization.md#generating-secrets))

> [!WARNING]
>
Expand Down
17 changes: 15 additions & 2 deletions docs/src/guides/external-node/00_quick_start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,15 @@ Install `docker compose` and `Docker`

## Running ZKsync node locally

These commands start ZKsync node locally inside docker.
These commands start ZKsync Node locally inside docker.

For adjusting the Dockerfiles to use them with other chains setup using ZK Stack, see
[setup_for_other_chains](11_setup_for_other_chains.md)

> [!NOTE]
>
> If you want to run Node for a chain different than ZKsync ERA, you can ask the company hosting the chains for the
> ready docker-compose files.

To start a mainnet instance, run:

Expand Down Expand Up @@ -58,11 +66,16 @@ The HTTP JSON-RPC API can be accessed on port `3060` and WebSocket API can be ac
> setup).
>
> For requirements for nodes running from DB dump see the [running](03_running.md) section. DB dumps are a way to start
> ZKsync node with full historical transactions history.
> Node with full historical transactions history.
>
> For nodes with pruning disabled, expect the storage requirements on mainnet to grow at 1TB per month. If you want to
> stop historical DB pruning you can read more about this in the [pruning](08_pruning.md) section.

> [!NOTE]
>
> For chains other than ZKSync Era, the system requirements can be slightly lower (CPU and RAM) or even much lower
> (storage), depending on the chain.

- 32 GB of RAM and a relatively modern CPU
- 50 GB of storage for testnet nodes
- 500 GB of storage for mainnet nodes
Expand Down
119 changes: 58 additions & 61 deletions docs/src/guides/external-node/01_intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,36 @@
# ZkSync Node Documentation
# Node Documentation

This documentation explains the basics of the ZKsync Node.
The Node (sometimes referred to as External Node or EN) is a read-only replica of the main node.

## Disclaimers
## What is the Node

- The ZKsync node is in the alpha phase, and should be used with caution.
- The ZKsync node is a read-only replica of the main node.
The Node is a read-replica of the main (centralized) node that can be run by external parties. It functions by receiving
blocks from the given ZK Stack chain and re-applying transactions locally, starting from the genesis block. The Node
shares most of its codebase with the main node. Consequently, when it re-applies transactions, it does so exactly as the
main node did in the past.

## What is the ZKsync node
**It has three modes of initialization:**

The ZKsync node is a read-replica of the main (centralized) node that can be run by external parties. It functions by
receiving blocks from the ZKsync network and re-applying transactions locally, starting from the genesis block. The
ZKsync node shares most of its codebase with the main node. Consequently, when it re-applies transactions, it does so
exactly as the main node did in the past.

**It has two modes of initialization:**

- recovery from a DB dump, in Ethereum terms this corresponds to archival node
- recovery from genesis (Not supported on ZKsync Era), in Ethereum terms this corresponds to archival node, this option
is slower than recovery from DB dump, but is the easiest way to spin up new Node.
- recovery from a DB dump, in Ethereum terms this corresponds to archival node.
- recovery from a snapshot, in Ethereum terms this corresponds to light node, such nodes will only have access to
transactions data from after the node was initialized. The database can be pruned on such nodes.

## High-level overview

At a high level, the ZKsync node can be seen as an application that has the following modules:
At a high level, the Node can be seen as an application that has the following modules:

- API server that provides the publicly available Web3 interface.
- Consensus layer that interacts with the peer network and retrieves transactions and blocks to re-execute.
- Consensus layer (ZKsync Era only for now) that interacts with the peer network and retrieves transactions and blocks
to re-execute.
- Sequencer component that actually executes and persists transactions received from the synchronization layer.
- Several checker modules that ensure the consistency of the ZKsync node state.
- Several checker modules that ensure the consistency of the Node state.

With the EN, you are able to:

- Locally recreate and verify the ZKsync Era mainnet/testnet state.
- Interact with the recreated state in a trustless way (in a sense that the validity is locally verified, and you should
not rely on a third-party API ZKsync Era provides).
- Locally recreate and verify a ZK Stack chain's, for example ZKsync Era's mainnet/testnet state.
- Interact with the recreated state in a trustless way. The validity is locally verified.
- Use the Web3 API without having to query the main node.
- Send L2 transactions (that will be proxied to the main node).

Expand All @@ -43,12 +40,12 @@ With the EN, you _can not_:
- Generate proofs.
- Submit data to L1.

A more detailed overview of the EN's components is provided in the [components](06_components.md) section.
A more detailed overview of the Node's components is provided in the [components](06_components.md) section.

## API overview

API exposed by the ZKsync node strives to be Web3-compliant. If some method is exposed but behaves differently compared
to Ethereum, it should be considered a bug. Please [report][contact_us] such cases.
API exposed by the Node strives to be Web3-compliant. If some method is exposed but behaves differently compared to
Ethereum, it should be considered a bug. Please [report][contact_us] such cases.

[contact_us]: https://zksync.io/contact

Expand All @@ -58,42 +55,42 @@ Data getters in this namespace operate in the L2 space: require/return L2 block

Available methods:

| 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 |
| 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` | 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 @@ -153,5 +150,5 @@ Always refer to the documentation linked above to see the list of stabilized met

### `en` namespace

This namespace contains methods that ZKsync nodes call on the main node while syncing. If this namespace is enabled,
other ENs can sync from this node.
This namespace contains methods that Nodes call on the main node while syncing. If this namespace is enabled, other ENs
can sync from this node.
Loading
Loading