docs(consensus): Restored decentralization instructions (#3254)

## What ❔

Restored previously deleted intructions on how to enable p2p syncing. It
should remain until we deprecate JSON RPC syncing.

core/node/consensus/src/en.rs

@@ -179,7 +179,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/09_decentralization.md");
+            https://github.com/matter-labs/zksync-era/blob/main/docs/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));

docs/announcements/attester_commitee.md

@@ -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/09_decentralization.md#generating-secrets))
+[here](https://github.com/matter-labs/zksync-era/blob/main/docs/guides/external-node/10_decentralization.md#generating-secrets))
 
 > [!WARNING]
 >

docs/guides/external-node/10_decentralization.md

@@ -0,0 +1,91 @@
+# Decentralization
+
+In the default setup, the ZKsync node will fetch data from the ZKsync API endpoint maintained by Matter Labs. To reduce
+the reliance on this centralized endpoint we have developed a decentralized p2p networking stack (aka gossipnet) which
+will eventually be used instead of ZKsync API for synchronizing data.
+
+On the gossipnet, the data integrity will be protected by the BFT (byzantine fault-tolerant) consensus algorithm
+(currently data is signed just by the main node though).
+
+## Enabling gossipnet on your node
+
+> [!NOTE]
+>
+> Because the data transmitted over the gossipnet is signed by the main node (and eventually by the consensus quorum),
+> the signatures need to be backfilled to the node's local storage the first time you switch from centralized (ZKsync
+> API based) synchronization to the decentralized (gossipnet based) synchronization (this is a one-time thing). With the
+> current implementation it may take a couple of hours and gets faster the more nodes you add to the
+> `gossip_static_outbound` list (see below). We are working to remove this inconvenience.
+
+> [!NOTE]
+>
+> The minimal supported server version for this is
+> [24.11.0](https://github.com/matter-labs/zksync-era/releases/tag/core-v24.11.0)
+
+### Generating secrets
+
+Each participant node of the gossipnet has to have an identity (a public/secret key pair). When running your node for
+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
+chmod 600 consensus_secrets.yaml
+```
+
+> [!NOTE]
+>
+> NEVER reveal the secret keys used by your node. Otherwise, someone can impersonate your node on the gossipnet. If you
+> suspect that your secret key has been leaked, you can generate fresh keys using the same tool.
+>
+> If you want someone else to connect to your node, give them your PUBLIC key instead. Both public and secret keys are
+> present in the `consensus_secrets.yaml` (public keys are in comments).
+
+### Preparing configuration file
+
+Copy the template of the consensus configuration file (for
+[mainnet](https://github.com/matter-labs/zksync-era/blob/main/docs/guides/external-node/prepared_configs/mainnet_consensus_config.yaml)
+or
+[testnet](https://github.com/matter-labs/zksync-era/blob/main/docs/guides/external-node/prepared_configs/testnet_consensus_config.yaml)
+).
+
+> [!NOTE]
+>
+> You need to fill in the `public_addr` field. This is the address that will (not implemented yet) be advertised over
+> gossipnet to other nodes, so that they can establish connections to your node. If you don't want to expose your node
+> to the public internet, you can use IP in your local network.
+
+Currently the config contains the following fields (refer to config
+[schema](https://github.com/matter-labs/zksync-era/blob/990676c5f84afd2ff8cd337f495c82e8d1f305a4/core/lib/protobuf_config/src/proto/core/consensus.proto#L66)
+for more details):
+
+- `server_addr` - local TCP socket address that the node should listen on for incoming connections. Note that this is an
+  additional TCP port that will be opened by the node.
+- `public_addr` - the public address of your node that will be advertised over the gossipnet.
+- `max_payload_size` - limit (in bytes) on the sized of the ZKsync ERA block received from the gossipnet. This protects
+  your node from getting DoS`ed by too large network messages. Use the value from the template.
+- `gossip_dynamic_inbound_limit` - maximal number of unauthenticated concurrent inbound connections that can be
+  established to your node. This is a DDoS protection measure.
+- `gossip_static_outbound` - list of trusted peers that your node should always try to connect to. The template contains
+  the nodes maintained by Matterlabs, but you can add more if you know any. Note that the list contains both the network
+  address AND the public key of the node - this prevents spoofing attacks.
+
+### Setting environment variables
+
+Uncomment (or add) the following lines in your `.env` config:
+
+```
+EN_CONSENSUS_CONFIG_PATH=...
+EN_CONSENSUS_SECRETS_PATH=...
+```
+
+These variables should point to your consensus config and secrets files that we have just created. Tweak the paths to
+the files if you have placed them differently.
+
+### Add `--enable-consensus` flag to your entry point command
+
+For the consensus configuration to take effect you have to add `--enable-consensus` flag to the command line when
+running the node, for example:
+
+```
+docker run "matterlabs/external-node:2.0-v24.12.0" <all the other flags> --enable-consensus
+```

docs/guides/external-node/prepared_configs/mainnet-config.env

@@ -70,7 +70,7 @@ RUST_LOG=zksync_core=debug,zksync_dal=info,zksync_eth_client=info,zksync_merkle_
 RUST_BACKTRACE=full
 RUST_LIB_BACKTRACE=1
 
-# Settings related to gossip network, see `09_decentralization.md`
+# Settings related to gossip network, see `10_decentralization.md`
 #EN_CONSENSUS_CONFIG_PATH=./mainnet_consensus_config.yaml
 #EN_CONSENSUS_SECRETS_PATH=./consensus_secrets.yaml
 

docs/guides/external-node/prepared_configs/testnet-sepolia-config.env

@@ -70,7 +70,7 @@ RUST_LOG=zksync_core=debug,zksync_dal=info,zksync_eth_client=info,zksync_merkle_
 RUST_BACKTRACE=full
 RUST_LIB_BACKTRACE=1
 
-# Settings related to gossip network, see `09_decentralization.md`
+# Settings related to gossip network, see `10_decentralization.md`
 #EN_CONSENSUS_CONFIG_PATH=./testnet_consensus_config.yaml
 #EN_CONSENSUS_SECRETS_PATH=./consensus_secrets.yaml