diff --git a/website/docs/xdcchain/developers/node_operators/bootstrap.md b/website/docs/xdcchain/developers/node_operators/bootstrap.md new file mode 100644 index 00000000..a3362af8 --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/bootstrap.md @@ -0,0 +1,58 @@ +--- +title: Run XDC Nodes using Bootstrap Script +--- + +# Setup XDC Masternode using Bootstrap Script + +## For Mainnet + +**Bootstrap Command XinFin Node Setup:** + +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +``` + +**Examples:** +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "mainnet". +``` +$ sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +[sudo] password for user: +Please enter your XinFin Network (mainnet/testnet/devnet) :- mainnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "Demo_Server." +``` +Your running network is mainnet +Please enter your XinFin MasterNode Name :- Demo_Server +Your Masternode Name is Demo_Server + +``` + + +## For Testnet +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "testnet". +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +Please enter your XinFin Network (mainnet/testnet/devnet) :- testnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "test01" +``` +Your running network is testnet +Please enter your XinFin MasterNode Name :- test01 +Your Masternode Name is test01 +``` + +## For Devnet +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "devnet". +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +Please enter your XinFin Network (mainnet/testnet/devnet) :- devnet +Your running network is devnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "test01" +``` +Please enter your XinFin MasterNode Name :- test01 +Your Masternode Name is test01 +Generate new private key and wallet address. +If you have your own key, you can change after this and restart the node +Type 'Y' or 'y' to continue: +``` \ No newline at end of file diff --git a/website/docs/xdcchain/developers/node_operators/docker.md b/website/docs/xdcchain/developers/node_operators/docker.md new file mode 100644 index 00000000..666cfd7b --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/docker.md @@ -0,0 +1,176 @@ +--- +title: Setup XDC Masternode using Docker +--- + +# Setup XDC Masternode using Docker + +## Setting up XDC Network Masternode Docker version + +The server or VPS used for the masternode should be directly facing the internet with a public IP and without NAT. + + +**Operating System**: Ubuntu 20.04 64-bit or higher + +Should be facing internet directly with **public IP** & **without NAT** + +**Tools**: Docker, Docker Compose(1.27.4+) + +Setup (For Ubuntu 20.04 64-bit or higher Operating System) + +Follow the written steps starting from step 1, or you can watch the video tutorials: + + + +## Step 1: Clone repository +```bash +git clone https://github.com/XinFinOrg/XinFin-Node.git + +``` + +## Step 2: Change directory +Then we change the directory to XinFin-Node +```bash +cd XinFin-Node +``` + +## Step 3: Install docker +We need to install Docker and Docker-Compose by running the following command: +```bash +sudo ./setup/install_docker.sh +``` + +## Step 4: +Create a new .env file and copy the env.example file that exist in the mainnet directory. We will ensure we are in the "mainnet" directory by typing these commands. Once in edit mode for the .env file, name your masternode and use an email address in the respective fields +```bash +cd mainnet +cp env.example .env +nano .env + +``` +**For Testnet** +```bash +cd testnet +cp env.example .env +nano .env +``` + +## Step 5: Start your Node +**For Mainnet run the following commands:** +```bash +cd mainnet +bash docker-up.sh +``` +At this point you should be able to see your masternode on the list of nodes here or as shown below: + +![node-sync](../../img/node_sync.png) + +For Testnet run the following commands: +```bash +cd testnet +bash docker-up.sh +``` +You should be able to see your node listed on the [Apothem Network] page. Select **"Switch to LiveNet"** to check **LiveNetwork** Stats and Select **"Switch to TestNet"** for **TestNetwork**. + +Your coinbase address can be found in xdcchain/coinbase.txt file. + +For troubleshooting purposes, you can stop the node by using the following command on either Mainnet or Testnet: +```bash +bash docker-down.sh +``` + +**Downloading a Network Snapshot (Mainnet or Apothem)** + +The following steps are to expedite the syncing process of your node with the XDC Network. If you followed the steps above, your node will take 3-4 days to sync up with the network fully. You can reduce that time by downloading a network snapshot and bringing your node back up after the chain has been downloaded and unpacked. + + + +# Mainnet Snapshot + +**Bring down your node:** +```bash +bash docker-down.sh +``` +**Remove the old xdchain file from the server** +```bash +rm -rf xdcchain.tar +``` +**Download the snapshot** +```bash +wget https://download.xinfin.network/xdcchain.tar +``` +**Unpack the xdcchain.tar file** +```bash +tar -xvzf xdcchain.tar +``` +**The unpacking will take some time, and it will look like this:** + +![unpacking](../../img/unpacking.png) + +**The following command will move the xdcchain/XDC to xdcchain/XDC_backup** +```bash +mv xdcchain/XDC xdcchain/XDC_backup +mv XDC xdcchain +``` + +**Then we are going to remove the old "nodekey" file** +```bash +rm -rf xdcchain/XDC/nodekey +``` + +**The last step is to run the bash upgrade.sh command** +```bash +bash upgrade.sh +``` + +This command will bring your node up and it will start syncing to the network. Once up and running, your node will be synced to the network in just a few minutes. + +![node_upgrade](../../img/node_upgrade.png) + +# Apothem Snapshot + +**Bring down your node:** +```bash +bash docker-down.sh +``` + +**Remove the old xdchain file from the server** +```bash +rm -rf apothem.tar +``` + +**Download the snapshot** + +Full Node snapshot: +```bash +wget http://downloads.apothem.network/xdcchain.tar +``` + +Archive Node snapshot: +```bash +wget http://downloads.apothem.network/xdcchain_archive.tar +``` + +**Unpack the apothem.tar file** +```bash +tar -xvzf apothem.tar +``` + +**Move the xdcchain-testnet** +```bash +mv XDC xdcchain-testnet +``` + +**Bring up the node** +```bash +bash docker-up.sh +``` + + + + + + + + + + diff --git a/website/docs/xdcchain/developers/node_operators/dockerimg.md b/website/docs/xdcchain/developers/node_operators/dockerimg.md new file mode 100644 index 00000000..34dca647 --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/dockerimg.md @@ -0,0 +1,20 @@ +--- +title: Docker Image for the XDC Network +--- + +# Docker Image for the XDC Network + +## What is a Docker Image? + +A Docker image is a lightweight, stand-alone, executable package that includes everything needed to run an application, including code, runtime, libraries, and configurations. In the context of blockchain, Docker images simplify the deployment and management of nodes by enabling developers to encapsulate the entire blockchain environment into a single, replicable package. + +## Purpose of the XDC Network's Docker Image +For the XDC Network, the Docker image provides a standardized and efficient way for developers to deploy, manage, and update their XDC nodes. The XDC Docker image streamlines the node deployment process, reducing configuration errors and minimizing setup time. It allows developers to run nodes in isolated containers, ensuring a consistent environment across different infrastructures. + +## Key features of the XDC Docker image include: + +1. Ease of Deployment: Developers can deploy XDC nodes with just a few simple commands, reducing the complexity of setup. +2. Portability: Docker images are portable, meaning they can run consistently across various platforms, including local machines, cloud environments, and virtualized infrastructure. +3. Version Control: The XDC Docker image includes versioning, allowing developers to choose specific versions for compatibility testing or deployment. +4. Improved Security: Isolated environments reduce security risks as each container runs independently from the host system. + diff --git a/website/docs/xdcchain/developers/node_operators/masternode.md b/website/docs/xdcchain/developers/node_operators/masternode.md new file mode 100644 index 00000000..e6469ec8 --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/masternode.md @@ -0,0 +1,617 @@ +--- +title: Masternode +--- + +# Run a Node +Nodes are computers or servers that run an application software known as clients to perform essential tasks on a blockchain network. These tasks can include transactions, block creation, consensus, network security, and other operational tasks for the network. The tasks and functionalities a node execute depend on the type of node, with each node having different system requirements and deployment processes. This section will provide details and information on how to run and maintain nodes on the XDC Network. + +# Masternodes(Full Node) and Standby Masternodes +The XDC Network runs on a globally distributed system of masternodes that participate in a [XDC 2.0](https://xinfin.org/xdpos) consensus mechanism. To enhance network integrity and security, Masternodes are required to complete a KYC process and stake 10,000,000 XDC. Masternodes can be identified as “Validator” or “Standby” Masternodes. + +```mermaid +stateDiagram-v2 + [*] --> Standby: stake 10M XDC + [*] --> Validator: stake + KYC + elected + Standby --> Validator: replace offline validator + Validator --> Standby: demoted + Validator --> Slashed: sign conflicting block + Standby --> Slashed: malicious act + Slashed --> [*]: stake burned +``` + +Standby Masternodes (or “Standby Nodes”) are identical in form and function to Validators but do not participate in validating transactions and block creation. These nodes are on standby to fill the role of Validators that drop from network participation. + +# Difference between Full and Archive Node + +A full node on the XDC Network is a masternode (validator or standby) that contains the most recent 128 blocks, also known as "Prunned" nodes. + +![XDC Full Node](../../img/xdc-full-node.png) + +An Archive node on the XDC Network is a masternode or node that contains all the data since the Genesis block. + +![XDC Archive Node](../../img/xdc-archive-node.png) + +To host an XDC Masternode/Standby node, there are specific prerequisites that you need to meet in terms of hardware, software, and staking requirements. Below is a detailed list: + +## Hardware Requirements +To ensure smooth operation and optimal performance of the XDC Masternode, the following hardware specifications are recommended: + +- **Processor (CPU):** 6 Core +- **Memory (RAM):** Minimum 16 GB +- **Storage (SSD):** At least 1TB SSD or NVMe (solid-state drive) to accommodate blockchain data +- **Network:** Stable internet connection with at least 1 Gbps bandwidth (upstream and downstream) +- **Operating System:** Ubuntu 22.04 LTS (recommended) + +## Software Requirements +Ensure that you have the following software and dependencies installed on your server before proceeding with the XDC Masternode setup: + +- **Ubuntu OS (20.04/22.04 LTS)** +- **Docker:** A containerization tool for deploying and running the masternode environment +- **Golang (Go):** For XDC node compilation and execution +- **Git:** For cloning necessary repositories +- **Firewall:** Properly configured firewall rules (allowing ports such as 30303) + +## Staking Requirements +To host an XDC Masternode, a certain amount of XDC tokens must be staked. This ensures that the node operator has a vested interest in the security and performance of the network. + +- **XDC Token Stake:** A minimum of **10 million XDC** tokens is required to run a Masternode. These tokens must be locked in your Masternode wallet. + +## XDC Wallet Setup +You must set up an XDC wallet to manage your funds and staking: + +- **XDC Wallet Address:** A valid XDC wallet address is needed to stake and manage the **10 million XDC** tokens. +- **Backup:** Ensure that you have securely backed up your wallet’s private keys or seed phrase to avoid any loss of funds. + +## Securing Your XDC Network Node + +Before deploying your XDC Network Node, it is critical to secure the server, especially for validator or standby nodes that do not require RPC/WebSocket access. There are two deployment scenarios: + +* **RPC Node**: Exposes necessary ports to allow DApps and users to interact with the blockchain. +* **Validator/Standby Node**: Only communicates with the network and should block unnecessary ports for better security. + +This guide provides instructions for securing your server, changing the default SSH port, and enabling a firewall for validator/standby nodes. + +--- + +### Initial Server Setup + +1. **Log in to your server** using credentials provided by your cloud provider: + + ```bash + ssh user@your-server-ip + ``` + +2. **Update OS packages**: + + ```bash + sudo apt update -y && sudo apt upgrade -y && sudo apt autoremove -y + ``` + +--- + +### Setting Up SSH Key Authentication + +**Step 1: Generate SSH Key (on your local machine or computer. Not the server)** + +If you don’t already have an SSH key: + +```bash +ssh-keygen -t rsa -b 4096 -C "your_email@example.com" +``` + +* Save the key in the default path (usually `~/.ssh/id_rsa`) +* You may optionally add a passphrase or password (Recommended for highest safety) + +**Step 2: Upload the Public Key to the Server** + +```bash +ssh-copy-id -i ~/.ssh/id_rsa.pub user@your-server-ip +``` + +**Step 3: Test Login** + +```bash +ssh user@your-server-ip +``` + +**Optional: Disable Password Authentication** + +Edit the SSH config file: + +```bash +sudo nano /etc/ssh/sshd_config +``` + +Set the following: + +``` +PasswordAuthentication no +``` + +Restart the SSH service: + +```bash +sudo systemctl restart ssh +``` + +Keep your private key (`~/.ssh/id_rsa`) safe. You will need it for all future logins. +**Do not upload it to the server** + +--- + +### Locking Down Validator/Standby Nodes + +If your masternode is being used only for the purpose of maintaining the XDC blockchain and does not require RPC/WebSocket access, the following hardening steps are recommended: + +1. Change the default SSH port +2. Block all incoming traffic using a firewall +3. Open only the required ports (30303 for XDC P2P and your new SSH port) + +--- + +### Change the SSH Port + +1. Edit the SSH config file: + + ```bash + sudo nano /etc/ssh/sshd_config + ``` + +2. Find the line: + + ``` + #Port 22 + ``` + +3. Remove the `#` and change `22` to a new custom port (for example, 2222): + + ``` + Port 2222 + ``` + +4. Save and exit: + + * Press `CTRL+X`, then `Y`, then `ENTER` + +5. Restart the SSH service: + + ```bash + sudo systemctl restart ssh + ``` + +To connect from now on: + +```bash +ssh -p 2222 user@your-server-ip +``` + +--- + +### Configure UFW (Uncomplicated Firewall) + +1. **Install UFW**: + + ```bash + sudo apt install ufw + ``` + +2. **Set default policies**: + + ```bash + sudo ufw default deny incoming + sudo ufw default allow outgoing + ``` + +3. **Allow XDC P2P port**: + + ```bash + sudo ufw allow 30303 + ``` + +4. **Allow your SSH port** (replace `2222` with your actual port): + + ```bash + sudo ufw allow 2222 + ``` + +5. **Enable UFW**: + + ```bash + sudo ufw enable + ``` + +6. **Reboot the server**: + + ```bash + reboot + ``` + +--- + +### Testing Access + +After rebooting, reconnect to your server using the new SSH port: + +```bash +ssh -p 2222 user@your-server-ip +``` + +If you are unable to connect, use your VPS provider’s web console to access the server and make the necessary firewall or SSH configuration changes. + +--- + +Once your server is secured and accessible, proceed with the standard masternode setup below. + +# Setup XDC Masternode using Bootstrap Script + +## For Mainnet + +**Bootstrap Command for XDC Masternode Setup:** + +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +``` + +**Examples:** +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "mainnet". +``` +$ sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +[sudo] password for user: +Please enter your XinFin Network (mainnet/testnet/devnet) :- mainnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "Demo_Server." +``` +Your running network is mainnet +Please enter your XinFin MasterNode Name :- Demo_Server +Your Masternode Name is Demo_Server + +``` + +## For Testnet +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "testnet". +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +Please enter your XinFin Network (mainnet/testnet/devnet) :- testnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "test01" +``` +Your running network is testnet +Please enter your XinFin MasterNode Name :- test01 +Your Masternode Name is test01 +``` + +## For Devnet +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "devnet". +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +Please enter your XinFin Network (mainnet/testnet/devnet) :- devnet +Your running network is devnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "test01" +``` +Please enter your XinFin MasterNode Name :- test01 +Your Masternode Name is test01 +Generate new private key and wallet address. +If you have your own key, you can change after this and restart the node +Type 'Y' or 'y' to continue: +``` +--------------------------------------------------------------- + + +# How to Stake XDC on a Masternode/Standby node + +### Prerequisites +To stake XDC and run a masternode, you will need the following: + +- XDCPay, XinFin Web Wallet, or a hardware wallet (Trezor supported) +- 10,000,000 XDC (mainnet tokens) or test XDC (for the Apothem testnet) +- Your coinbase address (retrievable from your masternode) + +**Note:** You do not need 10,000,000 XDC to run a node solely for RPC queries or accessing live data from the blockchain. This guide covers staking for masternode candidates. + + +## Step-by-Step Process to Stake Your XDC Node + +### 1. Access the Staking Platform + +- Visit [XinFin Masternode](https://master.xinfin.network/) page. +- Select either the **Mainnet** (for real staking) or **Apothem** (for testnet staking). + +### 2. Log In to Your Wallet + +- Click on the **Login** button on the masternode page. +- You’ll be presented with multiple login options, including XDCPay, WalletConnect v2, Private Key/Mnemonic, Ledger Wallet or Trezor. +- For this guide, we'll use XDCPay: + - Open XDCPay and ensure you are connected to either the Mainnet or Apothem network. + - Log in to your wallet using XDCPay. + +### 3. Become a Masternode Candidate + +- Once logged in, click the **Become a Candidate** button on the dashboard. +- A new screen will appear where you will enter your KYC (Know Your Customer) information. +- KYC Process: + - Upload your required KYC documents (you can find downloadable templates linked in the form). + - Once uploaded, the system will show a "KYC True" status, indicating your KYC has been approved. + +### 4. Enter Your Coinbase Address + +- After completing KYC, input your **Coinbase address**. This address is specific to your masternode and can be retrieved by logging into your node. + +### 5. Confirm and Apply for Staking + +- Click on **Apply** to stake your XDC and become a masternode candidate. +- Your XDCPay wallet will prompt you to **sign the transaction**. Review the details and click Confirm. + +### 6. Transaction Confirmation + +- After confirming, your staking transaction will be processed. Once successful, you’ll receive a notification in the bottom-right corner of the screen. +- To verify the transaction, navigate to your XDCPay wallet, click on **Transactions**, and look for the **Propose** event. This event confirms your candidacy as a masternode. + +--------------------------------------------------------------- + +# Setup XDC Masternode/Standby node using Docker + +## Setting up XDC Network Masternode Docker version + +The server or VPS used for the masternode should be directly facing the internet with a public IP and without NAT. + + +**Operating System**: Ubuntu 20.04 64-bit or higher + +Should be facing internet directly with **public IP** & **without NAT** + +**Tools**: Docker, Docker Compose(1.27.4+) + +Setup (For Ubuntu 20.04 64-bit or higher Operating System) + +Follow the written steps starting from step 1, or you can watch the video tutorials: + + + +## Step 1: Clone repository +```bash +git clone https://github.com/XinFinOrg/XinFin-Node.git + +``` + +## Step 2: Change directory +Then we change the directory to XinFin-Node +```bash +cd XinFin-Node +``` + +## Step 3: Install docker +We need to install Docker and Docker-Compose by running the following command: +```bash +sudo ./setup/install_docker.sh +``` + +## Step 4: +Create a new .env file and copy the env.example file that exist in the mainnet directory. We will ensure we are in the "mainnet" directory by typing these commands. Once in edit mode for the .env file, name your masternode and use an email address in the respective fields +```bash +cd mainnet +cp env.example .env +nano .env + +``` +**For Testnet** +```bash +cd testnet +cp env.example .env +nano .env +``` + +## Step 5: Start your Node +**For Mainnet run the following commands:** +```bash +cd mainnet +sudo docker-compose -f docker-compose.yml up -d +``` +At this point you should be able to see your masternode on the list of nodes here or as shown below: + +![node-sync](../../img/node_sync.png) + +For Testnet run the following commands: +```bash +cd testnet +sudo docker-compose -f docker-compose.yml up -d +``` +You should be able to see your node listed on the [Apothem Network] page. Select **"Switch to LiveNet"** to check **LiveNetwork** Stats and Select **"Switch to TestNet"** for **TestNetwork**. + +Your coinbase address can be found in xdcchain/coinbase.txt file. + +For troubleshooting purposes, you can stop the node by using the following command on either Mainnet or Testnet: +```bash +sudo docker-compose -f docker-compose.yml down +``` + +--------------------------------------------------------------- + +# Setup XDC Masternode(Full Node)/Standby node using Snapshots + +### Prerequisites + +* A server or cloud instance (minimum 16 GB RAM, 1.5 TB storage) +* Ubuntuoperating system +* Basic Linux command-line knowledge + +### Setting up the Node Environment using Bootstrap + +Its the primary options for setting up your XDC Network node environment: using the bootstrap.sh script for a quick setup + +Using the Bootstrap Command for Quick Setup +This command automates the installation of necessary dependencies and sets up the basic node environment. + +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +``` + +**You will be prompted to enter:** + +- **XinFin Network (mainnet/testnet/devnet):** Type mainnet for the main XDC Network. + +- **XinFin MasterNode Name:** Provide a name for your node (e.g.,Rushabh-Snapshot-Node). + +- **Generate new private key and wallet address:** If you have your own key, you can change after this and restart the node: Enter y or Y and continue. + +![node-sync](../../img/installation.png) + +Once the installation on your Ubuntu server is complete, attach to the node using the following command to verify that the blockchain synchronization has begun + +``` +bash xdc-attach.sh +``` + +![node-sync](../../img/installation1.png) + +You can monitor the status of your node using the above command or by visiting the official stats page at https://xinfin.network/#stats Once you've confirmed that the node has begun syncing from the genesis block, stop the node by running: + +``` +bash docker-down.sh +``` +![node-sync](../../img/installation2.png) + +After stopping your node, proceed to delete the existing XDC directory to prepare for the snapshot data + +![node-sync](../../img/installation3.png) + +After deleting the XDC folder, you can now proceed to download and apply the latest snapshot. + +To download the XDC Network Mainnet snapshot, use the appropriate command based on the type of node you’re setting up: + +- **For a Full Node (latest state only):** https://rpc.xdc.network/snapshots/mainnet/full/ + +- **For an Archive Node (complete history):** https://rpc.xdc.network/snapshots/mainnet/archive/ + +**Note: Snapshots are updated approximately every 20 days at https://rpc.xdc.network/snapshots/** + +![node-sync](../../img/installation4.png) + +Once the xdc.tar file has been downloaded, extract the snapshot by running the following command: + +``` +tar -xvzf xdc.tar +``` + +This will unpack the archive and create the XDC directory containing the necessary blockchain data. + +![node-sync](../../img/installation5.png) + +### Once the XDC folder has been extracted, navigate into it and perform the following cleanup steps: + +**Delete the nodekey file:** + +``` +rm -rf nodekey +``` + +**Delete the transactions.rlp file:** + +``` +rm -rf transactions.rlp +``` +![node-sync](../../img/cleanup.png) + + +--------------------------------------------------------------- + +# Downloading a Network Snapshot (Mainnet or Apothem) + +The following steps are to expedite the syncing process of your node with the XDC Network. If you followed the steps above, your node will take 3-4 days to sync up with the network fully. You can reduce that time by downloading a network snapshot and bringing your node back up after the chain has been downloaded and unpacked. + + + +# Mainnet Snapshot + +**Bring down your node:** +```bash +sudo docker-compose -f docker-compose.yml down +``` +**Remove the old xdchain file from the server** +```bash +rm -rf xdcchain.tar +``` +**Download the snapshot** +```bash +wget https://download.xinfin.network/xdcchain.tar +``` +**Unpack the xdcchain.tar file** +```bash +tar -xvzf xdcchain.tar +``` +**The unpacking will take some time, and it will look like this:** + +![unpacking](../../img/unpacking.png) + +**The following command will move the xdcchain/XDC to xdcchain/XDC_backup** +```bash +mv xdcchain/XDC xdcchain/XDC_backup +mv XDC xdcchain +``` + +**Then we are going to remove the old "nodekey" file** +```bash +rm -rf xdcchain/XDC/nodekey +``` + +**The last step is to run the bash upgrade.sh command** +```bash +bash upgrade.sh +``` + +This command will bring your node up and it will start syncing to the network. Once up and running, your node will be synced to the network in just a few minutes. + +![node_upgrade](../../img/node_upgrade.png) + +# Apothem Snapshot + +**Bring down your node:** +```bash +sudo docker-compose -f docker-compose.yml down +``` + +**Remove the old xdchain file from the server** +```bash +rm -rf apothem.tar +``` + +**Download the snapshot** + +Full Node snapshot: +```bash +wget http://downloads.apothem.network/xdcchain.tar +``` + +Archive Node snapshot: +```bash +wget http://downloads.apothem.network/xdcchain_archive.tar +``` + +**Unpack the apothem.tar file** +```bash +tar -xvzf apothem.tar +``` + +**Move the xdcchain-testnet** +```bash +mv XDC xdcchain-testnet +``` + +**Bring up the node** +```bash +sudo docker-compose -f docker-compose.yml up -d +``` + + + diff --git a/website/docs/xdcchain/developers/node_operators/node_architecture.md b/website/docs/xdcchain/developers/node_operators/node_architecture.md new file mode 100644 index 00000000..78fc3322 --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/node_architecture.md @@ -0,0 +1,40 @@ +--- +title: XDC Node Architecture +--- + +# XDC Node Architecture + +The XDC Network is a hybrid blockchain platform designed to support both public and private states, offering enterprises the ability to conduct secure, scalable, and fast transactions. At the core of this network is its node architecture, which plays a crucial role in maintaining the network's integrity, security, and efficiency. This document provides a comprehensive overview of the XDC Node Architecture, detailing the various components and their functions. + +The XDC Network operates on a Delegated Proof of Stake (XDPoS) consensus mechanism, which ensures low energy consumption and high transaction throughput. The network is EVM-compatible, allowing it to support smart contracts and decentralized applications (dApps). + +## Node Types in XDC Network + +The XDC Network comprises several types of nodes, each serving a unique function within the ecosystem. These nodes are essential for network operations, including transaction validation, block creation, and consensus. + +**Masternodes (Validator Nodes):** + +- **Role:** Masternodes are responsible for validating transactions, proposing and finalizing blocks, and maintaining consensus within the network. +Requirements: To run a Masternode, operators must stake a 10 Million XDC, ensuring they have a vested interest in the network's security and performance. +Functionality: These nodes participate in the consensus mechanism, verifying transactions and adding them to the blockchain. They also play a role in voting on protocol upgrades and governance decisions. + +## Full Nodes: +- **Role:** Full Nodes store the entire blockchain ledger, validating blocks and transactions independently. +- **Requirements:** Operators of Full Nodes do not need to stake XDC but must maintain a certain level of computing resources to store and process the entire blockchain. +- **Functionality:** These nodes propagate transactions across the network, ensuring that all participants have access to the same data. Full Nodes contribute to network security by verifying the integrity of the blockchain. + +## Node Communication and Network Topology + +The XDC Network employs a peer-to-peer (P2P) communication model where nodes interact directly with each other to share information and propagate transactions. + +* **Gossip Protocol:** + - Nodes in the XDC Network use a gossip protocol to disseminate information about transactions and blocks. This protocol ensures that all nodes are kept up-to-date with the latest state of the blockchain, maintaining network consistency and reducing the likelihood of forks. + +* **Networking Layers:** + - **Overlay Network:** The XDC Network uses an overlay network to facilitate communication between nodes. This layer abstracts the underlying physical network, providing a virtual topology that is more manageable and secure. + - **Transport Layer:** The transport layer is responsible for ensuring reliable communication between nodes. It handles data transmission, error checking, and retransmission in case of data loss. + + + + + diff --git a/website/docs/xdcchain/developers/node_operators/one-click-installer.md b/website/docs/xdcchain/developers/node_operators/one-click-installer.md new file mode 100644 index 00000000..8cadf8cd --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/one-click-installer.md @@ -0,0 +1,54 @@ +--- +title: Run XDC Nodes using One-Click Installer +--- + +# Setup XDC Masternode using One-Click Installer + +### Method 1: Setup XinFin’s XDC Masternode One-click Installer ### + +To qualify for Masternode on XinFin Network, you need at least **10,000,000 XDC, for the long term.** + + +**Operating System**: + +* Apple Mac +* Windows +* Linux - Ubuntu + +## Step 1: +**Download [XDC One-Click Installer](https://xinfin.org/setup-masternode) (to setup Masternode) for Windows, Linux, and Mac OS and Install on your local machine.** + +## Step 2: +**Now Run the One Click Installer, Make sure you read the Terms properly then click on I Agree button.** + +* **"C:\Program Files\XinFin-Network"** this will be your destination folder and this **"C:\Users\...\AppData\Roaming\XDCChain"** will contain your Keystore folder. +* Make sure, you create a backup of your Keystore folder. +* Now click on "XinFin Network" One click installer. +* You can see the address of One Click Installer in left side, Also you can change the Network. +* For changing the Network, click on "Develop" then select "Network" (XinFin - Main Network/ XinFin Apothem Network) +* You can check the Node status under the **[stats.xinfin.network](http://stats.xinfin.network/)** + + +**Step 3: Create a wallet for Masternode** + +* Create your wallet address with Mnemonic Phrase or with Keystore. We always recommend to use Keystore for running a Masternode. +* Enter a strong password while creating the wallet. +* **Don't lose your Keystore file** +* **Don't share it with anyone** +* **Always take a backup of your Keystore file.** +* **If you lose it, all your funds will get locked.** +* After creating backup, Download your Keystore file. +* Now Access your wallet with Keystore and enter a valid password properly to access your wallet. +* If you are hosting a Masternode on Testnet then copy the Wallet address and paste it on **[XDC Faucet](https://faucet.apothem.network/)** for the Testnet XDC + + +**Step 4: Host your Masternode** + +* For hosting the Masternode, you need to copy the private key and login the Masternode. +* For uploading the KYC, click on the "Become a Masternode" +* Check the KYC criteria, the KYC file should be in pdf format only. +* Once you upload your KYC, you need to enter the "Coinbase Address" which is in One Click Installer after that click on Apply button. +* Now you will be notify with sucessful toaster i.e **"You have successfully applied for Masternode"** +* You can check all the status regarding your Masternode here: **[master.apothem.network](https://master.apothem.network/)**. + + diff --git a/website/docs/xdcchain/developers/node_operators/slashing.md b/website/docs/xdcchain/developers/node_operators/slashing.md new file mode 100644 index 00000000..047ffb50 --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/slashing.md @@ -0,0 +1,54 @@ +--- +title: XDC Network - Slashing Mechanism +--- + +# XDC Network - Slashing Mechanism + +The XDC Network, utilizing the XDPoS (Delegated Proof of Stake) consensus mechanism, ensures that its validators, known as masternodes, maintain optimal performance to keep the network stable and secure. One of the key features designed to ensure this reliability is the slashing mechanism, which acts as a corrective measure for underperforming masternodes. + +## Objective of the Slashing Mechanism + +The primary goal of the slashing mechanism is not to penalize or blame masternodes but to maintain a stable and high-performing network. It serves to mitigate issues arising from underperforming masternodes by holding them accountable while ensuring the overall system remains efficient. + +## How the XDC Network Slashing Mechanism Works +The slashing mechanism operates with a clear set of rules to manage masternode performance: + +### 1. Non-Participation in Block Signing: + +* If a masternode fails to sign any block during an entire epoch (a defined period within the consensus process), it will be slashed. +* The penalty for not participating in block creation during the epoch is exclusion from block production for the next four epochs. This temporary exclusion incentivizes masternodes to maintain uptime and perform their duties diligently. + +### 2. Handling Multiple Underperforming Masternodes: + +* If multiple masternodes are underperforming within the same epoch, they face similar slashing penalties. Masternodes that have been underperforming for the past four epochs will be kicked out of the active masternode list and are not eligible to create blocks. +* Consequently, the number of active masternodes responsible for block creation in the following epoch could drop below the full 108, which is the maximum number of validators. In such cases, the system dynamically adjusts, allowing active masternodes to proceed with block creation without waiting for the underperforming ones. + +### 3. Role After Being Slashed: + +* A slashed masternode can still participate in block verification and signing. This enables it to demonstrate liveness to the network by submitting signatures for new blocks. +* However, the slashed masternode is ineligible for rewards during the slashed period. It can continue verifying and signing blocks, but this participation only serves as a signal of its recovery and does not result in earning block rewards. + +## Properties of the XDC Network Slashing Mechanism** +### 1. Accountability: + +* The XDPoS consensus protocol ensures accountability by detecting masternodes that remain inactive for an entire epoch. A smart contract known as the Block Signer tracks the activity of each masternode. +* The Block Signer stores the signatures from all masternodes, making it easy to determine whether a masternode has been performing its duties. If a masternode has failed to provide the required number of signatures during an epoch, the slashing mechanism is triggered. + +### 2. Liveness: + +* A core feature of the slashing mechanism is to allow slashed masternodes to regain their status. After being excluded from the active masternode list for four epochs, the masternode can return to normal operations if it resumes block verification and signing during the slashed period. +* This property ensures that temporarily underperforming masternodes, which may have experienced technical issues such as power outages, can rejoin the network without permanent penalties. + +## Comparison to Other Slashing Mechanisms +The concept of slashing is not unique to the XDC Network and has been implemented in various other blockchain networks, such as Ethereum’s Casper FFG (Friendly Finality Gadget). Casper’s slashing mechanism is designed to prevent the "nothing-at-stake" problem, where validators can choose to support multiple forks of the blockchain. In Casper, if a validator is found to have validated conflicting forks, they are severely penalized by losing a significant portion, or even all, of their staked tokens. + +Unlike Casper’s more punitive approach aimed at preventing malicious behavior, the XDC Network’s slashing mechanism is designed to handle unintentional underperformance. Rather than harshly punishing validators for outages or system failures, XDC’s system focuses on ensuring network performance without creating fear of excessive penalties. The design philosophy behind XDC’s slashing mechanism is to avoid deterring participation by maintaining a fair yet firm system. + +## Benefits of the XDC Slashing Mechanism +* Network Stability: By detecting and penalizing underperforming masternodes, the XDC Network ensures that the overall system remains stable and efficient. +* Encouraging Performance: Masternodes are incentivized to maintain their performance to avoid being slashed and losing rewards. +* Reduced Risk for Validators: Validators are not permanently penalized for minor lapses, such as technical issues, which encourages wider participation in the network without fear of catastrophic loss. + + + + diff --git a/website/docs/xdcchain/developers/node_operators/validator-handbook.md b/website/docs/xdcchain/developers/node_operators/validator-handbook.md new file mode 100644 index 00000000..87394271 --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/validator-handbook.md @@ -0,0 +1,792 @@ +--- +title: "Validator Handbook — Complete Setup Guide +description: Comprehensive guide for running an XDC Network validator node. Hardware requirements, installation, key management, staking, monitoring, and troubleshooting." +--- + +# Validator Handbook: Complete Setup Guide + +This handbook covers everything you need to run a production XDC Network validator node — from hardware selection to monitoring and maintenance. + +**Prerequisites:** +- 10,000,000 XDC for staking (mainnet) +- Linux server administration experience +- Basic understanding of blockchain consensus + +--- + +## 1. Hardware Requirements + +### Minimum Specs (Testnet / Development) + +| Component | Minimum | Notes | +|-----------|---------|-------| +| CPU | 4 cores | x86_64 architecture | +| RAM | 16 GB | DDR4 or better | +| Storage | 1 TB SSD | SATA SSD acceptable | +| Network | 100 Mbps | Stable, low-latency | +| OS | Ubuntu 22.04 LTS | Other Linux distros may work | + +### Recommended Specs (Production Mainnet) + +| Component | Recommended | Notes | +|-----------|-------------|-------| +| CPU | 8+ cores | AMD EPYC or Intel Xeon | +| RAM | 32 GB | DDR4 ECC recommended | +| Storage | 2 TB NVMe | High IOPS for sync performance | +| Network | 1 Gbps | Dedicated, unmetered | +| OS | Ubuntu 22.04 LTS | LTS for long-term stability | + +### Archive Node Requirements + +Archive nodes store all historical state. Requirements are significantly higher: + +| Component | Requirement | +|-----------|-------------| +| CPU | 16+ cores | +| RAM | 64 GB | +| Storage | 5+ TB NVMe | +| Network | 1 Gbps | + +### Cloud Provider Options + +| Provider | Instance Type | Monthly Cost (est.) | Best For | +|----------|--------------|---------------------|----------| +| AWS | c6i.2xlarge | $200-300 | Enterprise, global | +| GCP | c2-standard-8 | $200-280 | Integration with GCP services | +| Azure | D8s_v5 | $200-300 | Enterprise Microsoft stack | +| Hetzner | AX102 | $100-150 | Cost-effective Europe | +| OVHcloud | Advance-2 | $120-180 | Cost-effective global | +| DigitalOcean | c-8 | $150-200 | Simple setup | + +> ⚠️ **Important:** The server must have a **public IP address** and **no NAT**. Validator nodes need direct internet connectivity. + +--- + +## 2. Server Preparation + +### 2.1 Initial OS Setup + +Log in to your server: + +```bash +ssh user@your-server-ip +``` + +Update all packages: + +```bash +sudo apt update -y && sudo apt upgrade -y && sudo apt autoremove -y +``` + +Install essential tools: + +```bash +sudo apt install -y curl wget git htop tmux ufw fail2ban +``` + +Set timezone to UTC: + +```bash +sudo timedatectl set-timezone UTC +``` + +### 2.2 Create Dedicated User + +Never run the node as root. Create a dedicated user: + +```bash +sudo adduser xdc-node +sudo usermod -aG sudo xdc-node +su - xdc-node +``` + +### 2.3 SSH Hardening + +Generate SSH key (on your local machine): + +```bash +ssh-keygen -t ed25519 -C "xdc-validator@yourdomain.com" +ssh-copy-id -i ~/.ssh/id_ed25519.pub xdc-node@your-server-ip +``` + +On the server, disable password authentication: + +```bash +sudo nano /etc/ssh/sshd_config +``` + +Set: + +``` +PasswordAuthentication no +PermitRootLogin no +MaxAuthTries 3 +ClientAliveInterval 300 +ClientAliveCountMax 2 +``` + +Restart SSH: + +```bash +sudo systemctl restart sshd +``` + +### 2.4 Firewall Configuration + +For validator nodes (no RPC needed): + +```bash +sudo ufw default deny incoming +sudo ufw default allow outgoing +sudo ufw allow 30303/tcp # XDC P2P +sudo ufw allow 30303/udp # XDC P2P +sudo ufw allow 2222/tcp # Your custom SSH port +sudo ufw enable +``` + +For RPC nodes (add these): + +```bash +sudo ufw allow 8545/tcp # HTTP RPC +sudo ufw allow 8546/tcp # WebSocket RPC +sudo ufw allow 8551/tcp # Engine API +``` + +Verify: + +```bash +sudo ufw status verbose +``` + +### 2.5 System Tuning + +Increase file descriptor limits: + +```bash +sudo nano /etc/security/limits.conf +``` + +Add: + +``` +*xdc-node soft nofile 65535 +*xdc-node hard nofile 65535 +``` + +Optimize network settings: + +```bash +sudo nano /etc/sysctl.conf +``` + +Add: + +``` +net.core.rmem_max = 134217728 +net.core.wmem_max = 134217728 +net.ipv4.tcp_rmem = 4096 87380 134217728 +net.ipv4.tcp_wmem = 4096 65536 134217728 +net.core.netdev_max_backlog = 30000 +net.ipv4.tcp_congestion_control = bbr +``` + +Apply: + +```bash +sudo sysctl -p +``` + +--- + +## 3. Node Installation + +### 3.1 Option A: Bootstrap Script (Recommended for Beginners) + +The bootstrap script automates installation: + +```bash +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +``` + +You will be prompted for: + +1. **Network:** Enter `mainnet`, `testnet`, or `devnet` +2. **Node Name:** Enter a descriptive name (e.g., `validator-us-east-01`) +3. **Key Generation:** Type `Y` to generate a new keypair + +The script will: +- Install Docker and Docker Compose +- Clone the XinFin-Node repository +- Generate a coinbase address +- Start syncing the blockchain + +**Verify sync status:** + +```bash +bash xdc-attach.sh +``` + +In the console, check: + +```javascript +eth.syncing +eth.blockNumber +``` + +If `eth.syncing` is `false`, your node is fully synced. + +### 3.2 Option B: Docker Setup (Recommended for Production) + +For more control over the environment: + +```bash +# Clone repository +git clone https://github.com/XinFinOrg/XinFin-Node.git +cd XinFin-Node + +# Install Docker +sudo ./setup/install_docker.sh + +# Configure environment +cd mainnet +cp env.example .env +nano .env +``` + +Edit `.env`: + +``` +NODE_NAME=validator-us-east-01 +CONTACT_EMAIL=ops@yourdomain.com +``` + +Start the node: + +```bash +cd mainnet +bash docker-up.sh +``` + +**Check logs:** + +```bash +docker-compose logs -f --tail=100 +``` + +### 3.3 Option C: Snapshot Sync (Fastest) + +To sync in hours instead of days: + +```bash +# Stop node +bash docker-down.sh + +# Remove old chain data +rm -rf xdcchain/XDC + +# Download snapshot (Full Node) +wget https://rpc.xdc.network/snapshots/mainnet/full/xdc.tar + +# Or Archive Node snapshot +# wget https://rpc.xdc.network/snapshots/mainnet/archive/xdc.tar + +# Extract +tar -xvzf xdc.tar + +# Clean up snapshot files +rm -rf xdcchain/XDC/nodekey +rm -rf xdcchain/XDC/transactions.rlp + +# Move extracted data +mv XDC xdcchain/ + +# Restart node +bash docker-up.sh +``` + +> 💡 **Tip:** Snapshots are updated approximately every 20 days at `https://rpc.xdc.network/snapshots/` + +--- + +## 4. Key Management + +### 4.1 Understanding Node Keys + +Your node generates several important files: + +| File | Location | Purpose | +|------|----------|---------| +| `coinbase.txt` | `xdcchain/coinbase.txt` | Validator address for staking | +| `nodekey` | `xdcchain/XDC/nodekey` | P2P network identity | +| `keystore/` | `xdcchain/keystore/` | Encrypted private keys | + +### 4.2 Backup Your Keys + +**Critical:** Back up these files immediately after generation. + +```bash +# Create backup directory +mkdir -p ~/xdc-backup/$(date +%Y%m%d) + +# Copy keys +cp xdcchain/coinbase.txt ~/xdc-backup/$(date +%Y%m%d)/ +cp xdcchain/XDC/nodekey ~/xdc-backup/$(date +%Y%m%d)/ +cp -r xdcchain/keystore ~/xdc-backup/$(date +%Y%m%d)/ + +# Secure the backup +chmod 600 ~/xdc-backup/$(date +%Y%m%d)/* +``` + +**Secure off-site backup:** + +```bash +# Encrypt backup +tar -czf - ~/xdc-backup/$(date +%Y%m%d) | gpg -c > xdc-backup-$(date +%Y%m%d).tar.gz.gpg + +# Transfer to secure storage (example: AWS S3) +aws s3 cp xdc-backup-$(date +%Y%m%d).tar.gz.gpg s3://your-secure-bucket/xdc-backups/ +``` + +> ⚠️ **Security:** Never store unencrypted keys on cloud storage. Always encrypt with GPG or similar before uploading. + +### 4.3 Restoring from Backup + +If you need to migrate to a new server: + +```bash +# Stop node +bash docker-down.sh + +# Restore keys +cp ~/xdc-backup/YYYYMMDD/coinbase.txt xdcchain/ +cp ~/xdc-backup/YYYYMMDD/nodekey xdcchain/XDC/ +cp -r ~/xdc-backup/YYYYMMDD/keystore xdcchain/ + +# Restart +bash docker-up.sh +``` + +### 4.4 Key Rotation + +To rotate your validator key (advanced): + +1. Generate new keypair on a secure offline machine +2. Update staking with new address +3. Wait for next epoch +4. Shut down old node after new node is active + +--- + +## 5. Staking Process + +### 5.1 Requirements + +- **10,000,000 XDC** in your wallet +- **KYC completion** (for mainnet) +- **Coinbase address** from your node + +### 5.2 Get Your Coinbase Address + +```bash +cat xdcchain/coinbase.txt +``` + +Or via RPC: + +```bash +curl -X POST http://localhost:8545 \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"eth_coinbase","params":[],"id":1}' +``` + +### 5.3 Complete KYC + +1. Visit [XinFin Masternode](https://master.xinfin.network/) +2. Connect your wallet (XDCPay, MetaMask, or Ledger) +3. Click **"Become a Candidate"** +4. Upload required KYC documents +5. Wait for approval (status shows "KYC True") + +### 5.4 Stake Your XDC + +1. On the masternode page, enter your **coinbase address** +2. Click **"Apply"** +3. Sign the transaction in your wallet +4. Wait for confirmation + +**Verify staking:** + +- Check your XDCPay transaction history for the **"Propose"** event +- View your node on [XinFin Network Stats](https://xinfin.network/#stats) + +### 5.5 Minimum Stake Details + +| Network | Minimum Stake | Lock Period | Rewards | +|---------|--------------|-------------|---------| +| Mainnet | 10,000,000 XDC | No fixed lock | Block rewards + transaction fees | +| Apothem (Testnet) | 10,000,000 test XDC | No fixed lock | Test rewards | + +--- + +## 6. Monitoring and Alerting + +### 6.1 Node Health Checks + +**Check if node is running:** + +```bash +docker ps | grep xinfin-node +``` + +**Check sync status:** + +```bash +bash xdc-attach.sh +> eth.syncing +``` + +- `false` = fully synced +- Object with `currentBlock` and `highestBlock` = still syncing + +**Check peer count:** + +```bash +curl -X POST http://localhost:8545 \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' +``` + +Healthy nodes should have 10+ peers. + +**Check block production (validators only):** + +Monitor your node on the [network stats page](https://xinfin.network/#stats). Your node name should appear in the validator list. + +### 6.2 Prometheus + Grafana Setup + +Install Prometheus: + +```bash +wget https://github.com/prometheus/prometheus/releases/download/v2.47.0/prometheus-2.47.0.linux-amd64.tar.gz +tar xvfz prometheus-2.47.0.linux-amd64.tar.gz +cd prometheus-2.47.0.linux-amd64 +``` + +Create `prometheus.yml`: + +```yaml +global: + scrape_interval: 15s + +scrape_configs: + - job_name: 'xdc-node' + static_configs: + - targets: ['localhost:6060'] + metrics_path: /debug/metrics/prometheus +``` + +Start Prometheus: + +```bash +./prometheus --config.file=prometheus.yml +``` + +Install Grafana: + +```bash +sudo apt-get install -y apt-transport-https software-properties-common +wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add - +echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee /etc/apt/sources.list.d/grafana.list +sudo apt-get update +sudo apt-get install grafana +sudo systemctl enable grafana-server +sudo systemctl start grafana-server +``` + +Access Grafana at `http://your-server-ip:3000` (default login: admin/admin). + +**Key metrics to monitor:** + +| Metric | Warning Threshold | Critical Threshold | +|--------|-------------------|-------------------| +| Peers | < 5 | < 2 | +| Block height (lag) | > 10 blocks | > 50 blocks | +| Disk usage | > 80% | > 95% | +| Memory usage | > 80% | > 95% | +| CPU usage | > 80% sustained | > 95% sustained | +| Missed blocks (validators) | > 1 per epoch | > 3 per epoch | + +### 6.3 Alert Rules (Prometheus) + +Create `alerts.yml`: + +```yaml +groups: + - name: xdc-node + rules: + - alert: XDCNodeDown + expr: up{job="xdc-node"} == 0 + for: 5m + labels: + severity: critical + annotations: + summary: "XDC node is down" + + - alert: XDCNodeLowPeers + expr: xdc_p2p_peers < 5 + for: 10m + labels: + severity: warning + annotations: + summary: "XDC node has low peer count" + + - alert: XDCNodeSyncingSlow + expr: xdc_highest_block - xdc_current_block > 100 + for: 30m + labels: + severity: warning + annotations: + summary: "XDC node is syncing slowly" + + - alert: XDCNodeDiskFull + expr: (node_filesystem_avail_bytes / node_filesystem_size_bytes) < 0.1 + for: 5m + labels: + severity: critical + annotations: + summary: "XDC node disk is almost full" +``` + +### 6.4 Log Monitoring + +Set up log rotation: + +```bash +sudo nano /etc/logrotate.d/xdc-node +``` + +Add: + +``` +/home/xdc-node/XinFin-Node/mainnet/xdcchain/logs/*.log { + daily + rotate 7 + compress + delaycompress + missingok + notifempty + create 0644 xdc-node xdc-node +} +``` + +Monitor logs in real-time: + +```bash +docker-compose logs -f --tail=100 | grep -E "ERROR|WARN|imported|sealed" +``` + +--- + +## 7. Security Hardening Checklist + +### Server Security + +- [ ] Dedicated non-root user for node operation +- [ ] SSH key authentication only (no passwords) +- [ ] Custom SSH port (not 22) +- [ ] Firewall enabled (UFW) with only required ports open +- [ ] Fail2ban installed and configured +- [ ] Automatic security updates enabled +- [ ] Server timezone set to UTC + +### Node Security + +- [ ] Node not exposed to public RPC (validator-only nodes) +- [ ] RPC authentication enabled if RPC is required +- [ ] TLS/SSL for RPC endpoints +- [ ] Regular key backups (encrypted, off-site) +- [ ] No private keys stored on the server unencrypted +- [ ] Docker containers running as non-root + +### Network Security + +- [ ] DDoS protection (Cloudflare or provider-level) +- [ ] VPN or private network for admin access +- [ ] No unnecessary services running +- [ ] Regular port scans to verify exposure + +### Operational Security + +- [ ] 2FA on all cloud provider accounts +- [ ] Separate wallets for staking vs operations +- [ ] Incident response plan documented +- [ ] Regular security audits scheduled +- [ ] Team access controls (no shared passwords) + +--- + +## 8. Maintenance Procedures + +### 8.1 Regular Health Checks + +**Daily:** +- Check node is running (`docker ps`) +- Verify sync status (`eth.syncing`) +- Review logs for errors + +**Weekly:** +- Check disk usage (`df -h`) +- Monitor peer count +- Review Grafana dashboards +- Verify backup integrity + +**Monthly:** +- Rotate logs +- Update OS packages +- Review security alerts +- Test backup restoration + +### 8.2 Upgrading the Node + +1. **Check for updates:** + +```bash +cd XinFin-Node +git fetch origin +git log HEAD..origin/master --oneline +``` + +2. **Backup before upgrade:** + +```bash +bash docker-down.sh +cp -r xdcchain ~/xdc-backup/pre-upgrade-$(date +%Y%m%d) +``` + +3. **Apply update:** + +```bash +git pull origin master +bash docker-up.sh +``` + +4. **Verify after upgrade:** + +```bash +bash xdc-attach.sh +> eth.syncing +> net.peerCount +``` + +### 8.3 Disaster Recovery + +**Scenario 1: Server Failure** + +1. Provision new server +2. Install Docker and dependencies +3. Restore keys from backup +4. Download latest snapshot +5. Start node and verify sync +6. Update staking with new IP if needed + +**Scenario 2: Corrupted Chain Data** + +```bash +bash docker-down.sh +rm -rf xdcchain/XDC +# Download fresh snapshot or sync from genesis +bash docker-up.sh +``` + +**Scenario 3: Lost Keys** + +If you lose your keys and have no backup: +1. Generate new keypair +2. Start new node +3. **You will lose your stake** — the 10M XDC is tied to the old address +4. This is why backups are critical + +--- + +## 9. Troubleshooting + +| Problem | Cause | Solution | +|---------|-------|----------| +| Node won't start | Port conflict | Check if port 30303 is in use: `sudo lsof -i :30303` | +| Syncing stuck | Corrupt database | Stop node, delete `xdcchain/XDC`, resync from snapshot | +| Low peer count | Firewall blocking | Verify UFW allows 30303/tcp and 30303/udp | +| Out of disk space | Chain growth | Expand disk or prune (full nodes keep 128 blocks) | +| High memory usage | Memory leak | Restart Docker container: `docker-compose restart` | +| KYC rejected | Invalid documents | Ensure documents are clear, valid, and match wallet holder | +| Staking tx failed | Insufficient gas | Ensure wallet has extra XDC for gas fees | +| Node not in validator list | Not enough stake | Verify 10M XDC staked and KYC approved | +| Missed blocks | Network latency | Check server network, consider changing datacenter | +| Slashed | Downtime | Ensure >99% uptime. Check monitoring alerts | +| RPC connection refused | Wrong port/config | Verify RPC port and that node is running | +| Docker container exits | Resource limits | Check `docker-compose logs` for OOM errors | + +### Common Log Messages + +**Normal:** +``` +INFO [01-01|00:00:00.000] Imported new chain segment +INFO [01-01|00:00:00.000] Commit new mining work +``` + +**Warnings:** +``` +WARN [01-01|00:00:00.000] Synchronisation failed, retrying +WARN [01-01|00:00:00.000] Snapshot extension registration failed +``` + +**Errors (investigate immediately):** +``` +ERROR [01-01|00:00:00.000] Failed to write block to disk +ERROR [01-01|00:00:00.000] Blockchain not empty, fast sync disabled +``` + +--- + +## 10. Economics and Rewards + +### Validator Rewards + +| Source | Description | Approximate Rate | +|--------|-------------|------------------| +| Block rewards | New XDC minted per block | Variable | +| Transaction fees | Fees from transactions in block | Variable | + +### Slashing Risks + +| Violation | Penalty | Recovery | +|-----------|---------|----------| +| Miss full epoch | Excluded for 4 epochs | Resume signing to rejoin | +| Extended downtime | Removal from active list | Re-apply after recovery | + +> 💡 **Note:** XDC slashing is non-punitive. You don't lose staked tokens — you just lose block rewards during exclusion periods. + +--- + +## 11. Support and Community + +| Resource | Link | Purpose | +|----------|------|---------| +| Validator Discord | [discord.gg/xdc](https://discord.gg/xdc) | Real-time support | +| XDC Forum | [www.xdc.dev](https://www.xdc.dev) | Technical discussions | +| Network Stats | [xinfin.network](https://xinfin.network) | Node monitoring | +| GitHub | [XinFinOrg/XinFin-Node](https://github.com/XinFinOrg/XinFin-Node) | Source code | +| Masternode Portal | [master.xinfin.network](https://master.xinfin.network) | Staking management | + +--- + +## 🚀 Next Steps + +1. **[Node Architecture →](./node_architecture.md)** — Understand XDC node types and consensus (⏱️ 15 min) +2. **[Slashing Mechanism →](./slashing.md)** — Learn about penalties and how to avoid them (⏱️ 10 min) +3. **[Docker Setup →](./docker.md)** — Detailed Docker deployment guide (⏱️ 30 min) +4. **[Bootstrap Setup →](./bootstrap.md)** — Quick setup with bootstrap script (⏱️ 20 min) + +Or explore: +- **[Wallet Configuration →](../wallet-configuration.md)** — Set up XDCPay for staking +- **[RPC Reference →](/api/json-rpc)** — Interact with your node programmatically +- **[Security Best Practices →](/security/security-practices)** — Secure your infrastructure diff --git a/website/docs/xdcchain/developers/node_operators/validator_node.md b/website/docs/xdcchain/developers/node_operators/validator_node.md new file mode 100644 index 00000000..92960804 --- /dev/null +++ b/website/docs/xdcchain/developers/node_operators/validator_node.md @@ -0,0 +1,85 @@ +--- +title: Validator/Standby Node +--- + +## Validator Masternode +Validator Masternodes operate and participate in XDC Network’s DPoS consensus engine, validating transactions and block creation. + +```mermaid +journey + title Validator Node Setup + section Prepare + Run bootstrap script: 5: Operator + Choose network: 5: Operator + section Configure + Set masternode name: 4: Operator + Generate private key: 5: Script + section Secure + Stake 10M XDC: 5: Operator + Harden firewall: 4: Operator + section Operate + Start validating: 5: Node + Monitor uptime: 5: Operator +``` + +## Standby Masternodes +Standby Masternodes (or “Standby Nodes”) are identical in form and function to Validators but do not participate in validating transactions and block creation. These nodes are on standby to fill the role of Validators that drop from network participation. + +# Setup XDC Validator/Standby Node using Bootstrap Script + +## For Mainnet + +**Bootstrap Command XDC Validator/Standby Node Setup:** + +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +``` + +**Examples:** +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "mainnet". +``` +$ sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +[sudo] password for user: +Please enter your XinFin Network (mainnet/testnet/devnet) :- mainnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "Demo_Server." +``` +Your running network is mainnet +Please enter your XinFin MasterNode Name :- Demo_Server +Your Masternode Name is Demo_Server + +``` + + +## For Testnet +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "testnet". +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +Please enter your XinFin Network (mainnet/testnet/devnet) :- testnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "test01" +``` +Your running network is testnet +Please enter your XinFin MasterNode Name :- test01 +Your Masternode Name is test01 +``` + +## For Devnet +After running the bootstrap command, the system will prompt you to specify the network. To connect to the Mainnet, simply enter "devnet". +``` +sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root +Please enter your XinFin Network (mainnet/testnet/devnet) :- devnet +Your running network is devnet +``` +Next, you will be asked to input your XinFin Masternode name. Enter your desired Masternode name, such as "test01" +``` +Please enter your XinFin MasterNode Name :- test01 +Your Masternode Name is test01 +Generate new private key and wallet address. +If you have your own key, you can change after this and restart the node +Type 'Y' or 'y' to continue: +``` + +# Setup XDC Masternode using One-Click Installer + +To Setup XDC Masternode using One-Click Installer, [refer](./masternode.md/#setup-xdc-masternode-using-one-click-installer) \ No newline at end of file diff --git a/website/docs/xdcchain/developers/onboarding.md b/website/docs/xdcchain/developers/onboarding.md new file mode 100644 index 00000000..3fe29daa --- /dev/null +++ b/website/docs/xdcchain/developers/onboarding.md @@ -0,0 +1,351 @@ +--- +title: "Developer Onboarding — Start Building on XDC +description: Unified developer onboarding portal for XDC Network. Wallet setup, testnet XDC, RPC configuration, and framework setup in one place." +--- + +Difficulty: Beginner | Time: ~10 minutes | Tools: MetaMask, Node.js 18+ + +# Developer Onboarding — Start Building on XDC + +Welcome to XDC Network. This portal contains everything you need to go from zero to deploying your first smart contract. No prior blockchain experience required. + +## 🚀 5-Minute Quickstart + +New to XDC? Deploy your first contract in 5 minutes using only a browser: + +**[Deploy Hello World with Remix →](./quick-guide.md)** + +No installation. No configuration. Just a browser and MetaMask. + +--- + +## 📋 Prerequisites Checklist + +Before building on XDC, complete these 4 steps: + +- [ ] **Wallet** — Install [MetaMask](#wallet-setup) or [Rabby](#alternative-wallets) +- [ ] **Network** — Add [XDC Apothem Testnet](#network-configuration) +- [ ] **Test Funds** — Get [1000 free XDC](#faucet) +- [ ] **Framework** — Choose [Hardhat](#development-frameworks), [Foundry](#development-frameworks), or [Remix](#development-frameworks) + +--- + +## Wallet Setup + +### MetaMask (Recommended) + +MetaMask is the most popular EVM wallet. It supports XDC natively. + +**Option 1: Automatic (Recommended)** + +1. Open MetaMask and click the network dropdown (top center) +2. Click **Add Network** +3. Search for **"XDC"** and select **XDC Mainnet** or **XDC Apothem Testnet** +4. Click **Approve** + +**Option 2: Manual Configuration** + +If automatic setup doesn't work, add manually: + +| Field | XDC Mainnet | XDC Apothem Testnet | +|-------|-------------|---------------------| +| Network Name | XDC Mainnet | XDC Apothem Testnet | +| RPC URL | `https://rpc.xinfin.network` | `https://rpc.apothem.network` | +| Chain ID | `50` | `51` | +| Currency Symbol | XDC | XDC | +| Block Explorer | `https://xdcscan.com` | `https://testnet.xdcscan.com` | + +> 💡 **Tip:** XDCScan shows addresses with `xdc` prefix (e.g., `xdc1234…`). MetaMask uses `0x` prefix (e.g., `0x1234…`). Both refer to the same account. + +**Download MetaMask:** [metamask.io/download](https://metamask.io/download/) + +### Alternative Wallets + +Any EVM-compatible wallet works with XDC: + +| Wallet | Type | Best For | +|--------|------|----------| +| [Rabby](https://rabby.io/) | Browser | Power users, security-focused | +| [Trust Wallet](https://trustwallet.com/) | Mobile | Mobile-first developers | +| [Coinbase Wallet](https://www.coinbase.com/wallet) | Mobile/Browser | Coinbase ecosystem users | +| [Frame](https://frame.sh/) | Desktop | Desktop-native experience | + +--- + +## Network Configuration + +### One-Click Network Add + +Click to add XDC networks to your wallet automatically: + +**[Add XDC Mainnet to MetaMask]** | **[Add XDC Apothem to MetaMask]** + +### Manual Configuration + +If one-click doesn't work, use the values from the [Wallet Setup](#wallet-setup) table above. + +### RPC Endpoints + +| Network | Primary RPC | Backup RPC | Chain ID | +|---------|-------------|------------|----------| +| Mainnet | `https://rpc.xinfin.network` | `https://erpc.xinfin.network` | 50 | +| Apothem | `https://rpc.apothem.network` | `https://erpc.apothem.network` | 51 | +| Devnet | `https://devnetrpc.xinfin.network` | — | 551 | + +**Test RPC connectivity:** + +```bash title="Terminal" +curl -X POST https://rpc.apothem.network \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' +``` + +**Expected output:** + +```json +{"jsonrpc":"2.0","id":1,"result":"0x1234abcd"} +``` + +--- + +## Faucet + +Get free test XDC for the Apothem Testnet: + +### Official Faucet + +**[faucet.apothem.network](https://faucet.apothem.network)** + +- Amount: 1000 XDC per request +- Limit: 1 request per day per address +- Time: Instant + +**Steps:** + +1. Copy your wallet address from MetaMask +2. Visit [faucet.apothem.network](https://faucet.apothem.network) +3. Paste your address and click **Request** +4. Wait 10–30 seconds — 1000 XDC appears in MetaMask + +### Alternative Faucets + +| Faucet | Amount | Speed | Notes | +|--------|--------|-------|-------| +| [BlocksScan](https://faucet.blocksscan.io/) | 1000 XDC | Instant | Community-maintained | +| [ChainTools](https://chains.tools/faucet) | 500 XDC | Instant | Multi-chain faucet | + +> ⚠️ **Mainnet XDC:** Testnet XDC has no value. For mainnet XDC, purchase from [exchanges](https://xinfin.org/xdc) or bridge from other chains. + +--- + +## Development Frameworks + +Choose your development environment: + +### Hardhat (Recommended for Beginners) + +JavaScript-based development environment. Best for: + +- JavaScript/TypeScript developers +- Teams using npm ecosystem +- Complex deployment scripts + +**Setup:** + +```bash title="Terminal" +mkdir xdc-project && cd xdc-project +npm init -y +npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox +npx hardhat init +# Select "Create a TypeScript project" +``` + +**Configure for XDC:** + +```typescript title="hardhat.config.ts" +import { HardhatUserConfig } from "hardhat/config"; +import "@nomicfoundation/hardhat-toolbox"; + +const config: HardhatUserConfig = { + solidity: "0.8.24", + networks: { + xdc: { + url: "https://rpc.xinfin.network", + chainId: 50, + accounts: [process.env.PRIVATE_KEY!] + }, + apothem: { + url: "https://rpc.apothem.network", + chainId: 51, + accounts: [process.env.PRIVATE_KEY!] + } + } +}; + +export default config; +``` + +**Deploy:** + +```bash title="Terminal" +npx hardhat run scripts/deploy.ts --network apothem +``` + +**[Full Hardhat Guide →](/smartcontract/hardhat)** + +--- + +### Foundry (Recommended for Advanced Users) + +Rust-based toolkit. Best for: + +- Speed (fastest compilation and tests) +- Solidity-native workflow +- Fuzzing and property-based testing + +**Setup:** + +```bash title="Terminal" +curl -L https://foundry.paradigm.xyz | bash +foundryup +forge init xdc-project +cd xdc-project +``` + +**Configure for XDC:** + +```toml title="foundry.toml" +[profile.default] +src = "src" +out = "out" +libs = ["lib"] + +[rpc_endpoints] +xdc = "https://rpc.xinfin.network" +apothem = "https://rpc.apothem.network" +``` + +**Deploy:** + +```bash title="Terminal" +forge script script/Counter.s.sol --rpc-url apothem --broadcast +``` + +**[Full Foundry Guide →](/smartcontract/foundry)** + +--- + +### Remix (Browser IDE — Zero Setup) + +Browser-based IDE. Best for: + +- Quick prototyping +- Learning Solidity +- No local installation + +**Open:** [remix.xinfin.network](https://remix.xinfin.network) + +**Deploy:** + +1. Write contract in browser +2. Select "Injected Provider — MetaMask" +3. Click Deploy + +**[Full Remix Guide →](/smartcontract/remix)** + +--- + +## 📊 Framework Comparison + +| Feature | Hardhat | Foundry | Remix | +|---------|---------|---------|-------| +| Setup time | 5 min | 5 min | 0 min | +| Language | JavaScript/TS | Solidity/Shell | Browser GUI | +| Test speed | Medium | Fast | N/A | +| Debugging | Excellent | Good | Basic | +| CI/CD | Excellent | Good | N/A | +| Best for | Teams, JS devs | Speed, testing | Learning, quick tests | + +--- + +## ✅ Verify Your Setup + +Run this checklist to confirm everything works: + +```bash title="Terminal" +# 1. Check Node.js version +node --version # Should be v18+ + +# 2. Check wallet balance +# Open MetaMask → Select XDC Apothem → Check balance > 0 + +# 3. Test RPC connection +curl -X POST https://rpc.apothem.network \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' + +# 4. Compile a contract (Hardhat) +npx hardhat compile + +# 5. Compile a contract (Foundry) +forge build +``` + +--- + +## 🆘 Troubleshooting + +| Problem | Solution | +|---------|----------| +| MetaMask won't connect | Ensure you're on XDC Apothem (Chain ID 51), not Ethereum | +| "Insufficient funds" | Get test XDC from [faucet](https://faucet.apothem.network) | +| Faucet says "limit reached" | Wait 24 hours or use [alternative faucet](https://faucet.blocksscan.io/) | +| RPC connection fails | Try backup RPC: `https://erpc.apothem.network` | +| `hardhat: command not found` | Use `npx hardhat` instead of global install | +| `forge: command not found` | Run `foundryup` to install | +| Compiler errors | Ensure Solidity version matches `pragma` statement | + +--- + +## 📚 Next Steps + +Choose your path: + +**[Deploy Your First Contract →](./quick-guide.md)]** +Browser-only, 5 minutes, no setup required. + +**[Smart Contract Lifecycle →](/smartcontract)]** +Complete guide: setup → write → test → deploy → verify → monitor → upgrade. + +**[JavaScript SDK →](/xdcchain/developers/sdks/javascript)]** +Build a frontend that interacts with your contract. + +**[Security Best Practices →](/security/security-practices)]** +Learn to protect your contracts before mainnet deployment. + +--- + +## 🌐 Community & Support + +| Resource | Link | +|----------|------| +| Developer Discord | [discord.gg/xdc](https://discord.gg/xdc) | +| Developer Forum | [www.xdc.dev](https://www.xdc.dev) | +| GitHub | [github.com/XinFinOrg](https://github.com/XinFinOrg) | +| StackOverflow | Tag `xdc` | +| Documentation | [docs.xdc.network](https://docs.xdc.network) | + +--- + +## Related Topics + +- **[Quick Start Guide →](./quick-guide.md)** — Deploy your first contract in 5 minutes +- **[Environment Setup →](/smartcontract/setup)** — Configure Hardhat/Foundry +- **[Wallet Configuration →](./wallet-configuration.md)** — Set up MetaMask or Trust Wallet +- **[RPC Endpoints →](./rpc.md)** — Connect to XDC networks +- **[XDC Chain Overview →](../index.md)** — Understand the network +- **[Smart Contract Hub →](/smartcontract)** — Full developer documentation + +--- + +*Ready to build? Start with the [5-Minute Quickstart →](./quick-guide.md)]*