From f51caf0002102bface5c78118c8f6df71a9325f5 Mon Sep 17 00:00:00 2001 From: chetan-zilliqa <66236813+chetan-zilliqa@users.noreply.github.com> Date: Wed, 11 Sep 2024 14:30:17 +0800 Subject: [PATCH] Fix conflicts (#36) --- .trunk/trunk.yaml | 1 + zq2/docs/nodes/checkpoint.md | 59 ++++++++++ zq2/docs/nodes/faq.md | 5 + zq2/docs/nodes/index.md | 7 ++ zq2/docs/nodes/prototestnetnodes.md | 166 ++++++++++++++++++++++++++++ zq2/mkdocs.in.yaml | 7 +- 6 files changed, 244 insertions(+), 1 deletion(-) create mode 100644 zq2/docs/nodes/checkpoint.md create mode 100644 zq2/docs/nodes/faq.md create mode 100644 zq2/docs/nodes/index.md create mode 100644 zq2/docs/nodes/prototestnetnodes.md diff --git a/.trunk/trunk.yaml b/.trunk/trunk.yaml index cf3889a..461c9dd 100644 --- a/.trunk/trunk.yaml +++ b/.trunk/trunk.yaml @@ -62,6 +62,7 @@ lint: - Dockerfile # Annoying, but trunk is now very opinionated on how you write dockerfiles. - zq2/docs/js/** # trunk does not know this is looking for metamask in the user's browser. - zq2/docs/index.md # contains legitimate empty links + - zq2/docs/nodes/** - .trunk/*out/** - cd/base/deployment.yaml - zq1/** # Legacy diff --git a/zq2/docs/nodes/checkpoint.md b/zq2/docs/nodes/checkpoint.md new file mode 100644 index 0000000..29d5f00 --- /dev/null +++ b/zq2/docs/nodes/checkpoint.md @@ -0,0 +1,59 @@ +--- +id: nodes/checkpoint +title: Checkpoint +--- + +Checkpoints in nodes serve as specific reference points within the blockchain, +allowing nodes to synchronize more efficiently when joining or rejoining the network. +Instead of processing the entire blockchain from the genesis block, nodes can start from +a known, validated state. Below is a detailed guide on how to set up checkpoints. + +## [Syncing a node from a checkpoint](#checkpoint-sync) +Assuming that you have already completed +[setup node](../nodes/prototestnetnodes.md#setting-up-your-environment-and-building-zq2-node) section. + +For prototestnet network, you should have `zq2-prototestnet.toml` and the `start_node.sh` +script, which is generated by the [setup node](../nodes/prototestnetnodes.md#setting-up-your-environment-and-building-zq2-node) guide. + +### Step by step guide to do checkpoint configuration + +1. Ensure that you are in directory `/my/dir/zq2` that you created before during the setup. +2. **Download the checkpoints file:** +Here are the steps for downloading the latest checkpoint file. + - Visit the public [checkpoint url](https://checkpoints.zq2-devnet.zilliqa.com/) , where you will see an XML file. + - The key tag indicates the name of the file. For eg: `000291600.dat` is one of the checkpoint file. + - Copy the topmost file name from the key tag. Note that the topmost file has the latest checkpoint data. + - If you are interesting in syncing from an older checkpoint, copy the file from the `previous/` directory. + - Replace in the URL with the corresponding block number to form `https://checkpoints.zq2-devnet.zilliqa.com/` + for latest file or `https://checkpoints.zq2-devnet.zilliqa.com/previous/` for an older file. + - A prompt will appear, allowing you to save the file.Copy the file into `/my/dir/zq2`, the directory you previously created for settting up the node. + +Additionally, to identify the latest checkpoint file, refer to the [explorer](https://explorer.zq2-prototestnet.zilliqa.com). +and select the file that corresponds to the block number closest to the current block number. +3. **Configure Checkpoints in zq2-prototestnet.toml file:** +Open the `zq2-prototestnet.toml` file and add the following lines to enable + checkpoint settings: +```toml +[nodes.load_checkpoint] +file = "xxxxx..." # File name of the checkpoint block. for eg: 3000.dat +hash = "xxxxx..." # Block hash corresponding to the file block (Remove '0x' prefix from hash if present) +``` +`file` : This parameter specifies the name of the checkpoint or block number file, which +can be obtained from the public GCS bucket. It’s recommended to download the latest checkpoint +file from this source. +`hash` : The hash is used to verify the validity of the state data and ensure that no +tampering has occurred. You can obtain the block hash corresponding to the checkpoint height from the +public [explorer](https://explorer.zq2-prototestnet.zilliqa.com/). For example, if the downloaded +checkpoint file is 3000, you can use the `eth_getBlockByNumber` API to query the block hash: +```bash +curl --request POST --url https://api.zq2-prototestnet.zilliqa.com/ \ +--header 'Content-Type: application/json' \ +--data '{"method":"eth_getBlockByNumber","params":["0xBB8",false],"id":1,"jsonrpc":"2.0"}' \ +| grep -o '"hash":"[^"]*"' | awk -F':' '{print $2}' | tr -d '"' +``` +Alternatively, you can retrieve the block hash directly from the public +[explorer](https://explorer.zq2-prototestnet.zilliqa.com/) by searching +for the block number. +By this stage, your checkpoints configuration should be set up in the `zq2-prototestnet.toml` file. +4. **Launch the node** +Now the node is ready to launch. Follow the instructions in the [Start the Node](../nodes/prototestnetnodes.md#start-the-node) section to start your node. diff --git a/zq2/docs/nodes/faq.md b/zq2/docs/nodes/faq.md new file mode 100644 index 0000000..aa1fb4f --- /dev/null +++ b/zq2/docs/nodes/faq.md @@ -0,0 +1,5 @@ +--- +id: nodes/faq +title: Nodes & Validators FAQ +--- +# Frequently Asked Questions on Nodes and Validator Documentation \ No newline at end of file diff --git a/zq2/docs/nodes/index.md b/zq2/docs/nodes/index.md new file mode 100644 index 0000000..e6defba --- /dev/null +++ b/zq2/docs/nodes/index.md @@ -0,0 +1,7 @@ +--- +id: nodes/overview +title: Overview of Nodes & Validators +--- + +# Zilliqa nodes and validator documentation +This section provides documentation on nodes and outlines the process of becoming a validator in the Zilliqa Proof of Stake network. \ No newline at end of file diff --git a/zq2/docs/nodes/prototestnetnodes.md b/zq2/docs/nodes/prototestnetnodes.md new file mode 100644 index 0000000..993bfb1 --- /dev/null +++ b/zq2/docs/nodes/prototestnetnodes.md @@ -0,0 +1,166 @@ +--- +id: nodes/prototestnetnodes +title: Prototestnet nodes +--- + +# Prototestnet Nodes + +The current proto-testnet version of Zilliqa 2.0 allows users to setup a node +and join the network. + +## Zilliqa 2.0 (proto-testnet) node Prerequisites + +### [Hardware requirements](#hardware-requirements) + +- **CPU**: + - 1 Core / 2 threads or more +- **RAM**: + - 8 GB or more +- **Disk**: + - 100 GB or more + +### [Virtual machines on Cloud Platforms](#virtual-machines-on-cloud-platforms) + +We are running our Zilliqa 2.0 Nodes on Google Cloud Platform, GCP, +GCE VM `e2-standard-2` instance with 256 GB SSD (`pd-ssd`). + +If you running on other cloud provider, please do select an instance with +similar specs. + +### [Software requirements](#software-requirements) + +1. Operating System: We build and run on Ubuntu 22.04LTS or above +2. Docker: 27.0.3+ + +### [Port-forwarding](#port-forwarding) + +The following TCP ports need to be open to the internet for both inbound and +outbound. + +_NOTE: We don't recommend to run Nodes behind a NAT, if you're doing so +and you are facing any traversal issue you might have to debug on your own._ + +#### Required + +3333/TCP - P2P protocol port: has to be opened on inbound and outbound to +public internet. + +#### Optional + +4201/TCP - JSONRPC over HTTP: API port, only necessary if you want your API to +be accessible via the internet. + +### [Setting Up Your Environment and Building ZQ2 Node](#setup-a-node) + +To run a Zilliqa 2.0 node and join the proto-testnet, we provide the `z2` +utility as part of the [zq2](https://github.com/Zilliqa/zq2/blob/main/) code +base. + +The `z2 join` command creates the node startup script and configuration +file that you can copy and paste on your Ubuntu VM, configured as per above specs, +and run. + +### Step by step guide + +1. Cargo and Rust: You need to have Cargo and Rust installed on your system. + You can install them using [rustup](https://rustup.rs/). Once rustup is installed, + you can update Rust to the latest stable version. +2. Install the following requirements: + ```bash + sudo add-apt-repository ppa:ethereum/ethereum && sudo apt update && \ + sudo apt install -y solc build-essential pkg-config libssl-dev cmake \ + protobuf-compiler + ``` +3. Pick a directory. You'll need quite a lot of space. Let's call it `/my/dir`. +4. Clone [zq2](https://github.com/zilliqa/zq2) sourcecode into that directory to get `/my/dir/zq2`. + +5. Build the code using `cargo build`. +6. Source the setenv file: + ```bash + source /my/dir/zq2/scripts/setenv + ``` + This will give you access to the `z2` tool (in `zq2/z2`). +7. Generate the startup script and the configuration file for your node by running: + ```bash + z2 join --chain zq2-prototestnet + ``` +8. Generate the node private key. + ```bash + openssl rand -hex 32 > node-private-key.txt + export PRIVATE_KEY=$(cat node-private-key.txt) + ``` + _NOTE: Please save the node key as described above. You may need it + in the future to restart the node to generate the BLS public + key of the node._ +9. Now it's time to decide how the node will synchronize with the network. +There are two methods for setting the synchronization rules for the node. + + - Start the node from the genesis. + + This method initializes the node from the genesis block, ensuring that the node processes + the entire blockchain history. However, this process is time-consuming, as the node must + download and validate every block from the genesis block to the latest block height. + Syncing the node to the latest block may take a considerable amount of time, + potentially up to several days to complete fully. If you opt for this method, you can + proceed directly to the [Start the node](#start-the-node) section. + + - Start the node from a checkpoint. + + Starting from a checkpoint is a significantly faster option. This method leverages a + predefined checkpoint block number, enabling the node to sync with the network in just + a few hours, depending on the checkpoint's block height. Before proceeding to + [start the node](#start-the-node) section, you'll need to configure + the necessary settings to start the node from a checkpoint. + Detailed instructions for this configuration are available in + [syncing-from-checkpoints](../nodes/checkpoint.md#syncing-a-node-from-a-checkpoint). + Once the checkpoint is set up, your node will be ready to start. + You can now follow the steps below. + +### [Start the node](#start-the-node) +* Start the node without Checkpoint: + ```bash + chmod +x start_node.sh && \ + ./start_node.sh -k $PRIVATE_KEY + ``` + +* Start the node with Checkpoint: + ```bash + chmod +x start_node.sh && \ + ./start_node.sh -k $PRIVATE_KEY -p + ``` +_NOTE: The `` file is the one you previously downloaded. Refer to [syncing-from-checkpoint](../nodes/checkpoint.md#syncing-a-node-from-a-checkpoint)_ + +Great! The node should now be syncing with the network. It may +take up to 1.5 hours for the node to fully sync. You can check the progress +of the node by running the following command, which should return the latest +block height after syncing. +```bash +curl --request POST \ + --url http://localhost:4201/ \ + --header 'Content-Type: application/json' \ + --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' +``` + +For additional details on `z2` and the `join` capability refer to: + +- +- + +### [Becoming a Validator](#becoming-a-validator) + +Under the consensus mechanism introduced in Zilliqa 2.0, nodes can stake ZIL to secure +the network and promote themselves as validator nodes. In return, they receive a +share of the block rewards. + +While becoming a validator on the Zilliqa 2.0 mainnet will be permissionless, +on the current proto-testnet you need to request the minimum required stake of +10 million ZIL in order for you to register as a validator. + +To register as a validator on the Jasper proto-testnet, please complete and +submit validator join form. + +Once you have sufficient $ZILs you can register your node as validator. + +Below is a guide on how to register a validator node for Zilliqa 2.0: + + diff --git a/zq2/mkdocs.in.yaml b/zq2/mkdocs.in.yaml index 387df07..be40588 100644 --- a/zq2/mkdocs.in.yaml +++ b/zq2/mkdocs.in.yaml @@ -3,6 +3,11 @@ nav: - Welcome: index.md - What's new in Zilliqa 2.0: changes.md - Endpoints, Block Explorer and Faucet: endpoints.md - - Nodes and Validators: nodes.md + - Nodes & Validators: + - Overview: + - nodes/index.md + - Prototestnet Nodes: nodes/prototestnetnodes.md + - Checkpoints: nodes/checkpoint.md + - FAQs: nodes/faq.md - Tools and SDKs: sdk.md - Support & Feedback: support.md