From 53a36ba32d81b4f787ca69ca704d4d98eafb744c Mon Sep 17 00:00:00 2001 From: Grzegorz Prusak Date: Thu, 14 Nov 2024 15:18:40 +0100 Subject: [PATCH 1/7] playbook --- docs/guides/advanced/16_decentralization.md | 95 +++++++++++++++++++ docs/guides/advanced/README.md | 1 + .../external-node/10_decentralization.md | 2 +- 3 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 docs/guides/advanced/16_decentralization.md diff --git a/docs/guides/advanced/16_decentralization.md b/docs/guides/advanced/16_decentralization.md new file mode 100644 index 000000000000..58db415bc5df --- /dev/null +++ b/docs/guides/advanced/16_decentralization.md @@ -0,0 +1,95 @@ +# Decentralization + +To enable support for synchronization over p2p network, the main node needs to have +the "consensus" component configured and enabled. + +## Generating the consensus secrets + +Run the following to generate consensus secrets: + +``` +docker run --entrypoint /usr/bin/zksync_external_node "matterlabs/external-node:2.0-v25.1.0" generate-secrets > consensus_secrets.yaml +chmod 600 consensus_secrets.yaml +``` + +## Preparing the consensus config + +Create `consensus_config.yaml` file with the following content (remember to replace the placeholders): + +```yaml +server_addr: '0.0.0.0:3054' +public_addr: + # Address under which the node is accessible to the other nodes. + # It can be a public domain, like `example.com:3054`, in case the main node is accessible from the internet, + # or it can be a kubernetes cluster domain, like `server-v2-core..svc.cluster.local:3054` in + # case the main node should be only accessible within the cluster. +debug_page_addr: '0.0.0.0:5000' +max_payload_size: 3200000 +gossip_dynamic_inbound_limit: 10 +genesis_spec: + chain_id: # chain id + protocol_version: 1 # consensus protocol version + validators: + - key: validator:public:??? # public key of the main node (copy this PUBLIC key from consensus_secrets.yaml) + weight: 1 + leader: validator:public:??? # same as above - main node will be the only validator and the only leader. + +## Providing the configuration to the `zksync_server`. + +There are 2 ways (hopefully not for long) to provide configuration to `zksync_server` binary: + +In file-based configuration system, the consensus config is embedded in the [general config](https://github.com/matter-labs/zksync-era/blob/1edcabe0c6a02d5b6700c29c0d9f6220ec6fb03c/core/lib/config/src/configs/general.rs#L58), +and the consensus secrets are embedded in the [secrets config](https://github.com/matter-labs/zksync-era/blob/main/core/bin/zksync_server/src/main.rs). +Paste the content of the generated `consensus_secrets.yaml` file to the `secrets` config, and prepared config to the `general` config. + +In env-var-based configuration system, the consensus config and consensus secrets files are passed as standalone files. +The paths to these files need to be passed as env vars `CONSENSUS_CONFIG_PATH` and `CONSENSUS_SECRETS_PATH`. + +## Gitops repo config + +If you are using the matterlabs gitops repo to configure the main node, it is even more complicated becase the `consensus_config.yaml` file +is rendered from a helm chart. See the [example](https://github.com/matter-labs/gitops-kubernetes/blob/main/apps/environments/mainnet2/server-v2/server-v2-core.yaml), +to see where you have to paste the content of the `consensus_config.yaml` file. + +You need to embed the `consenus_secrets.yaml` file into a kubernetes config: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: consensus-secrets +type: Opaque +stringData: + .consensus_secrets.yaml: +``` + +You need to add the following sections to your kubernetes config for the core server: + +```yaml +spec: + values: + persistence: + consensus-secrets-volume: + name: consensus-secrets # this is the name of the secret kubernetes object we defined above + enabled: true + type: secret + mountPath: "/etc/consensus_secrets/" + args: + - --components=state_keeper,consensus + service: + main: + ports: + consensus: + enabled: true + port: 3054 + configMap: + consensus: + enabled: true + data: + consensus_config.yaml: + env: + - name: CONSENSUS_CONFIG_PATH + value: /etc/consensus_config.yaml # this is the location rendered by the helm chart, you can't change it + - name: CONSENSUS_SECRETS_PATH + value: /etc/consensus_secrets/.consensus_secrets.yaml + diff --git a/docs/guides/advanced/README.md b/docs/guides/advanced/README.md index 5a3673b558ad..2456e980638b 100644 --- a/docs/guides/advanced/README.md +++ b/docs/guides/advanced/README.md @@ -20,6 +20,7 @@ way. - [ZK intuition](./13_zk_intuition.md) - [ZK deeper overview](./14_zk_deeper_overview.md) - [Prover keys](./15_prover_keys.md) +- [Decentralization](./16_decentralization.md) Additionally, there are a few articles that cover specific topics that may be useful for developers actively working on `zksync-era` repo. diff --git a/docs/guides/external-node/10_decentralization.md b/docs/guides/external-node/10_decentralization.md index 41f59486bef6..f2b1782c2d72 100644 --- a/docs/guides/external-node/10_decentralization.md +++ b/docs/guides/external-node/10_decentralization.md @@ -28,7 +28,7 @@ Each participant node of the gossipnet has to have an identity (a public/secret the first time, generate the secrets by running: ``` -docker run --entrypoint /usr/bin/zksync_external_node "matterlabs/external-node:2.0-v24.12.0" generate-secrets > consensus_secrets.yaml +docker run --entrypoint /usr/bin/zksync_external_node "matterlabs/external-node:2.0-v25.1.0" generate-secrets > consensus_secrets.yaml chmod 600 consensus_secrets.yaml ``` From 8a2f21cb36d4c8b46f9ef8c3f6da0480cf796b8c Mon Sep 17 00:00:00 2001 From: Grzegorz Prusak Date: Thu, 14 Nov 2024 15:20:21 +0100 Subject: [PATCH 2/7] fmt --- docs/guides/advanced/16_decentralization.md | 60 ++++++++++----------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/guides/advanced/16_decentralization.md b/docs/guides/advanced/16_decentralization.md index 58db415bc5df..e06ee7fc3f37 100644 --- a/docs/guides/advanced/16_decentralization.md +++ b/docs/guides/advanced/16_decentralization.md @@ -1,7 +1,7 @@ # Decentralization -To enable support for synchronization over p2p network, the main node needs to have -the "consensus" component configured and enabled. +To enable support for synchronization over p2p network, the main node needs to have the "consensus" component configured +and enabled. ## Generating the consensus secrets @@ -16,7 +16,7 @@ chmod 600 consensus_secrets.yaml Create `consensus_config.yaml` file with the following content (remember to replace the placeholders): -```yaml +````yaml server_addr: '0.0.0.0:3054' public_addr: # Address under which the node is accessible to the other nodes. @@ -61,35 +61,35 @@ metadata: type: Opaque stringData: .consensus_secrets.yaml: -``` +```` You need to add the following sections to your kubernetes config for the core server: ```yaml spec: - values: - persistence: - consensus-secrets-volume: - name: consensus-secrets # this is the name of the secret kubernetes object we defined above - enabled: true - type: secret - mountPath: "/etc/consensus_secrets/" - args: - - --components=state_keeper,consensus - service: - main: - ports: - consensus: - enabled: true - port: 3054 - configMap: - consensus: - enabled: true - data: - consensus_config.yaml: - env: - - name: CONSENSUS_CONFIG_PATH - value: /etc/consensus_config.yaml # this is the location rendered by the helm chart, you can't change it - - name: CONSENSUS_SECRETS_PATH - value: /etc/consensus_secrets/.consensus_secrets.yaml - + values: + persistence: + consensus-secrets-volume: + name: consensus-secrets # this is the name of the secret kubernetes object we defined above + enabled: true + type: secret + mountPath: '/etc/consensus_secrets/' + args: + - --components=state_keeper,consensus + service: + main: + ports: + consensus: + enabled: true + port: 3054 + configMap: + consensus: + enabled: true + data: + consensus_config.yaml: + env: + - name: CONSENSUS_CONFIG_PATH + value: /etc/consensus_config.yaml # this is the location rendered by the helm chart, you can't change it + - name: CONSENSUS_SECRETS_PATH + value: /etc/consensus_secrets/.consensus_secrets.yaml +``` From 92446c9943aaf6c33e575e877c6f5206443f3ce0 Mon Sep 17 00:00:00 2001 From: Grzegorz Prusak Date: Thu, 14 Nov 2024 15:25:28 +0100 Subject: [PATCH 3/7] more info --- docs/guides/advanced/16_decentralization.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/guides/advanced/16_decentralization.md b/docs/guides/advanced/16_decentralization.md index e06ee7fc3f37..8d7bf67e5323 100644 --- a/docs/guides/advanced/16_decentralization.md +++ b/docs/guides/advanced/16_decentralization.md @@ -1,7 +1,7 @@ # Decentralization To enable support for synchronization over p2p network, the main node needs to have the "consensus" component configured -and enabled. +and enabled as follows: ## Generating the consensus secrets @@ -36,14 +36,16 @@ genesis_spec: ## Providing the configuration to the `zksync_server`. -There are 2 ways (hopefully not for long) to provide configuration to `zksync_server` binary: +To enable consensus component for the main node you need to append `--components=,consensus` to the `zksync_server` command line arguments. +In addition to that, you need to provide the configuration (from the files `consensus_config.yaml` and `consensus_secrets.yaml` that we have just prepared) to the `zksync_server` binary. +There are 2 ways (hopefully not for long) to achieve that: -In file-based configuration system, the consensus config is embedded in the [general config](https://github.com/matter-labs/zksync-era/blob/1edcabe0c6a02d5b6700c29c0d9f6220ec6fb03c/core/lib/config/src/configs/general.rs#L58), -and the consensus secrets are embedded in the [secrets config](https://github.com/matter-labs/zksync-era/blob/main/core/bin/zksync_server/src/main.rs). -Paste the content of the generated `consensus_secrets.yaml` file to the `secrets` config, and prepared config to the `general` config. +* In file-based configuration system, the consensus config is embedded in the [general config](https://github.com/matter-labs/zksync-era/blob/1edcabe0c6a02d5b6700c29c0d9f6220ec6fb03c/core/lib/config/src/configs/general.rs#L58), + and the consensus secrets are embedded in the [secrets config](https://github.com/matter-labs/zksync-era/blob/main/core/bin/zksync_server/src/main.rs). + Paste the content of the generated `consensus_secrets.yaml` file to the `secrets` config, and prepared config to the `general` config. -In env-var-based configuration system, the consensus config and consensus secrets files are passed as standalone files. -The paths to these files need to be passed as env vars `CONSENSUS_CONFIG_PATH` and `CONSENSUS_SECRETS_PATH`. +* In env-var-based configuration system, the consensus config and consensus secrets files are passed as standalone files. + The paths to these files need to be passed as env vars `CONSENSUS_CONFIG_PATH` and `CONSENSUS_SECRETS_PATH`. ## Gitops repo config From cbb5edfcbb273468114c4c17325d98e0d71ad55e Mon Sep 17 00:00:00 2001 From: Grzegorz Prusak Date: Thu, 14 Nov 2024 15:26:53 +0100 Subject: [PATCH 4/7] typo --- docs/guides/advanced/16_decentralization.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/advanced/16_decentralization.md b/docs/guides/advanced/16_decentralization.md index 8d7bf67e5323..6ee4da8ea0e8 100644 --- a/docs/guides/advanced/16_decentralization.md +++ b/docs/guides/advanced/16_decentralization.md @@ -33,6 +33,7 @@ genesis_spec: - key: validator:public:??? # public key of the main node (copy this PUBLIC key from consensus_secrets.yaml) weight: 1 leader: validator:public:??? # same as above - main node will be the only validator and the only leader. +``` ## Providing the configuration to the `zksync_server`. From 09b6e05870b75005a541114dae3d8097013ade59 Mon Sep 17 00:00:00 2001 From: Grzegorz Prusak Date: Thu, 14 Nov 2024 15:28:02 +0100 Subject: [PATCH 5/7] again --- docs/guides/advanced/16_decentralization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/advanced/16_decentralization.md b/docs/guides/advanced/16_decentralization.md index 6ee4da8ea0e8..d8f70831943c 100644 --- a/docs/guides/advanced/16_decentralization.md +++ b/docs/guides/advanced/16_decentralization.md @@ -16,7 +16,7 @@ chmod 600 consensus_secrets.yaml Create `consensus_config.yaml` file with the following content (remember to replace the placeholders): -````yaml +```yaml server_addr: '0.0.0.0:3054' public_addr: # Address under which the node is accessible to the other nodes. From 03caeb576fad8cfa0fa08e1ac2391fb8270b12d4 Mon Sep 17 00:00:00 2001 From: Grzegorz Prusak Date: Fri, 15 Nov 2024 09:53:58 +0100 Subject: [PATCH 6/7] fmt --- docs/guides/advanced/16_decentralization.md | 44 ++++++++++++--------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/docs/guides/advanced/16_decentralization.md b/docs/guides/advanced/16_decentralization.md index d8f70831943c..6adb61145f4d 100644 --- a/docs/guides/advanced/16_decentralization.md +++ b/docs/guides/advanced/16_decentralization.md @@ -19,10 +19,10 @@ Create `consensus_config.yaml` file with the following content (remember to repl ```yaml server_addr: '0.0.0.0:3054' public_addr: - # Address under which the node is accessible to the other nodes. - # It can be a public domain, like `example.com:3054`, in case the main node is accessible from the internet, - # or it can be a kubernetes cluster domain, like `server-v2-core..svc.cluster.local:3054` in - # case the main node should be only accessible within the cluster. + # Address under which the node is accessible to the other nodes. + # It can be a public domain, like `example.com:3054`, in case the main node is accessible from the internet, + # or it can be a kubernetes cluster domain, like `server-v2-core..svc.cluster.local:3054` in + # case the main node should be only accessible within the cluster. debug_page_addr: '0.0.0.0:5000' max_payload_size: 3200000 gossip_dynamic_inbound_limit: 10 @@ -30,28 +30,34 @@ genesis_spec: chain_id: # chain id protocol_version: 1 # consensus protocol version validators: - - key: validator:public:??? # public key of the main node (copy this PUBLIC key from consensus_secrets.yaml) - weight: 1 + - key: validator:public:??? # public key of the main node (copy this PUBLIC key from consensus_secrets.yaml) + weight: 1 leader: validator:public:??? # same as above - main node will be the only validator and the only leader. ``` ## Providing the configuration to the `zksync_server`. -To enable consensus component for the main node you need to append `--components=,consensus` to the `zksync_server` command line arguments. -In addition to that, you need to provide the configuration (from the files `consensus_config.yaml` and `consensus_secrets.yaml` that we have just prepared) to the `zksync_server` binary. -There are 2 ways (hopefully not for long) to achieve that: +To enable consensus component for the main node you need to append +`--components=,consensus` to the `zksync_server` command line arguments. +In addition to that, you need to provide the configuration (from the files `consensus_config.yaml` and +`consensus_secrets.yaml` that we have just prepared) to the `zksync_server` binary. There are 2 ways (hopefully not for +long) to achieve that: -* In file-based configuration system, the consensus config is embedded in the [general config](https://github.com/matter-labs/zksync-era/blob/1edcabe0c6a02d5b6700c29c0d9f6220ec6fb03c/core/lib/config/src/configs/general.rs#L58), - and the consensus secrets are embedded in the [secrets config](https://github.com/matter-labs/zksync-era/blob/main/core/bin/zksync_server/src/main.rs). - Paste the content of the generated `consensus_secrets.yaml` file to the `secrets` config, and prepared config to the `general` config. +- In file-based configuration system, the consensus config is embedded in the + [general config](https://github.com/matter-labs/zksync-era/blob/1edcabe0c6a02d5b6700c29c0d9f6220ec6fb03c/core/lib/config/src/configs/general.rs#L58), + and the consensus secrets are embedded in the + [secrets config](https://github.com/matter-labs/zksync-era/blob/main/core/bin/zksync_server/src/main.rs). Paste the + content of the generated `consensus_secrets.yaml` file to the `secrets` config, and prepared config to the `general` + config. -* In env-var-based configuration system, the consensus config and consensus secrets files are passed as standalone files. - The paths to these files need to be passed as env vars `CONSENSUS_CONFIG_PATH` and `CONSENSUS_SECRETS_PATH`. +- In env-var-based configuration system, the consensus config and consensus secrets files are passed as standalone + files. The paths to these files need to be passed as env vars `CONSENSUS_CONFIG_PATH` and `CONSENSUS_SECRETS_PATH`. ## Gitops repo config -If you are using the matterlabs gitops repo to configure the main node, it is even more complicated becase the `consensus_config.yaml` file -is rendered from a helm chart. See the [example](https://github.com/matter-labs/gitops-kubernetes/blob/main/apps/environments/mainnet2/server-v2/server-v2-core.yaml), +If you are using the matterlabs gitops repo to configure the main node, it is even more complicated becase the +`consensus_config.yaml` file is rendered from a helm chart. See the +[example](https://github.com/matter-labs/gitops-kubernetes/blob/main/apps/environments/mainnet2/server-v2/server-v2-core.yaml), to see where you have to paste the content of the `consensus_config.yaml` file. You need to embed the `consenus_secrets.yaml` file into a kubernetes config: @@ -60,11 +66,11 @@ You need to embed the `consenus_secrets.yaml` file into a kubernetes config: apiVersion: v1 kind: Secret metadata: - name: consensus-secrets + name: consensus-secrets type: Opaque stringData: - .consensus_secrets.yaml: -```` + .consensus_secrets.yaml: +``` You need to add the following sections to your kubernetes config for the core server: From 4fa9aeb61e0775e48711868d5fe2e3a7cfb166d7 Mon Sep 17 00:00:00 2001 From: Grzegorz Prusak Date: Fri, 15 Nov 2024 10:11:38 +0100 Subject: [PATCH 7/7] lint --- docs/src/guides/advanced/16_decentralization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/guides/advanced/16_decentralization.md b/docs/src/guides/advanced/16_decentralization.md index 6adb61145f4d..6037235ea064 100644 --- a/docs/src/guides/advanced/16_decentralization.md +++ b/docs/src/guides/advanced/16_decentralization.md @@ -35,7 +35,7 @@ genesis_spec: leader: validator:public:??? # same as above - main node will be the only validator and the only leader. ``` -## Providing the configuration to the `zksync_server`. +## Providing the configuration to the `zksync_server` To enable consensus component for the main node you need to append `--components=,consensus` to the `zksync_server` command line arguments.