Skip to content

Commit

Permalink
chore(docs): external node documentation final tweaks (matter-labs#1918)
Browse files Browse the repository at this point in the history 
Signed-off-by: tomg10 <[email protected]>
  • Loading branch information
@tomg10
tomg10 authored May 13, 2024
1 parent 668b464 commit a67325c
Show file tree
Hide file tree
Showing 7 changed files with 154 additions and 135 deletions.
28 changes: 17 additions & 11 deletions docs/guides/external-node/00_quick_start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

Install `docker compose` and `Docker`

## Running ZkSync external node locally
## Running zkSync node locally

To start a mainnet instance, run:

Expand Down Expand Up @@ -37,7 +37,7 @@ docker compose --file testnet-external-node-docker-compose.yml down --volumes
You can see the status of the node (after recovery) in
[local grafana dashboard](http://localhost:3000/d/0/external-node).

Those commands start external node locally inside docker.
Those commands start zkSync node locally inside docker.

The HTTP JSON-RPC API can be accessed on port `3060` and WebSocket API can be accessed on port `3061`.

Expand All @@ -52,17 +52,23 @@ The HTTP JSON-RPC API can be accessed on port `3060` and WebSocket API can be ac
### System Requirements

This configuration is approximate and should be considered as **minimal** requirements.
> [!NOTE]
>
> This configuration is only for nodes that use snapshots recovery (the default for docker-compose setup), for
> requirements for nodes running from DB dump see
> [03_running.md](https://github.com/matter-labs/zksync-era/blob/main/docs/guides/external-node/03_running.md). DB dumps
> are a way to start zkSync node with full historical transactions history
> [!NOTE]
>
> Those are requirements for a freshly started node and the the state grows about 1TB per month for mainnet
- 32-core CPU
- 64GB RAM
- SSD storage (NVME recommended):
- Sepolia Testnet - 10GB EN + 50GB PostgreSQL (at the time of writing, will grow over time, so should be constantly
monitored)
- Mainnet - 3TB EN + 7TB PostgreSQL (at the time of writing, will grow over time, so should be constantly monitored)
- 32 GB of RAM and a relatively modern CPU
- 30 GB of storage for testnet nodes
- 300 GB of storage for mainnet nodes
- 100 Mbps connection (1 Gbps+ recommended)

## Advanced setup

If you need monitoring, backups, to recover from DB dump/snapshot or a more customized PostgreSQL settings, etc, please
see: [ansible-en-role repo](https://github.com/matter-labs/ansible-en-role)
If you need monitoring, backups, to recover from DB dump or a more customized PostgreSQL settings, etc, please see:
[ansible-en-role repo](https://github.com/matter-labs/ansible-en-role)
102 changes: 51 additions & 51 deletions docs/guides/external-node/01_intro.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
# External Node Documentation
# ZkSync Node Documentation

This documentation explains the basics of the zkSync Era External Node.
This documentation explains the basics of the zkSync Node.

## Disclaimers

- The external node is in the alpha phase, and should be used with caution.
- The EN is a read-only replica of the main node. We are currently working on decentralizing our infrastructure by
creating a consensus node. The EN is not going to be the consensus 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. We are currently working on decentralizing our infrastructure
by creating a consensus node. The zkSync node is not going to be the consensus node.

## What is the external node
## What is the zkSync node

The external node (herein EN) is a read-replica of the main (centralized) node that can be run by external parties. It
functions by fetching data from the zkSync API and re-applying transactions locally, starting from the genesis block.
The EN 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.
The zkSync node is a read-replica of the main (centralized) node that can be run by external parties. It functions by
fetching data from the zkSync API 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:**

Expand All @@ -23,12 +23,12 @@ as the main node did in the past.

## High-level overview

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

- API server that provides the publicly available Web3 interface.
- Synchronization layer that interacts with the main node 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 EN state.
- Several checker modules that ensure the consistency of the zkSync node state.

With the EN, you are able to:

Expand All @@ -48,8 +48,8 @@ A more detailed overview of the EN's components is provided in the [components](

## API overview

API exposed by the EN 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 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.

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

Expand All @@ -59,42 +59,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` | 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 @@ -154,5 +154,5 @@ Always refer to the documentation linked above to see the list of stabilized met

### `en` namespace

This namespace contains methods that external nodes call on the main node while syncing. If this namespace is enabled,
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.
30 changes: 15 additions & 15 deletions docs/guides/external-node/02_configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# External Node Configuration
# ZkSync Node Configuration

This document outlines various configuration options for the EN. Currently, the EN requires the definition of numerous
environment variables. To streamline this process, we provide prepared configs for the zkSync Era - for both
This document outlines various configuration options for the EN. Currently, the zkSync node requires the definition of
numerous environment variables. To streamline this process, we provide prepared configs for the zkSync Era - for both
[mainnet](prepared_configs/mainnet-config.env) and [testnet](prepared_configs/testnet-sepolia-config.env). You can use
these files as a starting point and modify only the necessary sections.

Expand All @@ -10,7 +10,7 @@ default settings.**

## Database

The EN uses two databases: PostgreSQL and RocksDB.
The zkSync node uses two databases: PostgreSQL and RocksDB.

PostgreSQL serves as the main source of truth in the EN, so all the API requests fetch the state from there. The
PostgreSQL connection is configured by the `DATABASE_URL`. Additionally, the `DATABASE_POOL_SIZE` variable defines the
Expand All @@ -22,12 +22,12 @@ recommended to use an NVME SSD for RocksDB. RocksDB requires two variables to be

## L1 Web3 client

EN requires a connection to an Ethereum node. The corresponding env variable is `EN_ETH_CLIENT_URL`. Make sure to set
the URL corresponding to the correct L1 network (L1 mainnet for L2 mainnet and L1 sepolia for L2 testnet).
zkSync node requires a connection to an Ethereum node. The corresponding env variable is `EN_ETH_CLIENT_URL`. Make sure
to set the URL corresponding to the correct L1 network (L1 mainnet for L2 mainnet and L1 sepolia for L2 testnet).

Note: Currently, the EN makes 2 requests to the L1 per L1 batch, so the Web3 client usage for a synced node should not
be high. However, during the synchronization phase the new batches would be persisted on the EN quickly, so make sure
that the L1 client won't exceed any limits (e.g. in case you use Infura).
Note: Currently, the zkSync node makes 2 requests to the L1 per L1 batch, so the Web3 client usage for a synced node
should not be high. However, during the synchronization phase the new batches would be persisted on the zkSync node
quickly, so make sure that the L1 client won't exceed any limits (e.g. in case you use Infura).

## Exposed ports

Expand All @@ -50,22 +50,22 @@ the metrics, leave this port not configured, and the metrics won't be collected.

There are variables that allow you to fine-tune the limits of the RPC servers, such as limits on the number of returned
entries or the limit for the accepted transaction size. Provided files contain sane defaults that are recommended for
use, but these can be edited, e.g. to make the EN more/less restrictive.
use, but these can be edited, e.g. to make the zkSync node more/less restrictive.

## JSON-RPC API namespaces

There are 7 total supported API namespaces: `eth`, `net`, `web3`, `debug` - standard ones; `zks` - rollup-specific one;
`pubsub` - a.k.a. `eth_subscribe`; `en` - used by external nodes while syncing. You can configure what namespaces you
want to enable using `EN_API_NAMESPACES` and specifying namespace names in a comma-separated list. By default, all but
the `debug` namespace are enabled.
`pubsub` - a.k.a. `eth_subscribe`; `en` - used by zkSync nodes while syncing. You can configure what namespaces you want
to enable using `EN_API_NAMESPACES` and specifying namespace names in a comma-separated list. By default, all but the
`debug` namespace are enabled.

## Logging and observability

`MISC_LOG_FORMAT` defines the format in which logs are shown: `plain` corresponds to the human-readable format, while
the other option is `json` (recommended for deployments).

`RUST_LOG` variable allows you to set up the logs granularity (e.g. make the EN emit fewer logs). You can read about the
format [here](https://docs.rs/env_logger/0.10.0/env_logger/#enabling-logging).
`RUST_LOG` variable allows you to set up the logs granularity (e.g. make the zkSync node emit fewer logs). You can read
about the format [here](https://docs.rs/env_logger/0.10.0/env_logger/#enabling-logging).

`MISC_SENTRY_URL` and `MISC_OTLP_URL` variables can be configured to set up Sentry and OpenTelemetry exporters.

Expand Down
Loading

0 comments on commit a67325c

Please sign in to comment.