Setting Up an RPC Node Server for Your DApp on XDC Network: A Comprehensive Guide

A dedicated RPC (Remote Procedure Call) on the XDC network refers to an RPC server that is exclusively used by a specific DApp or application rather than shared by multiple clients.

When a DApp or application needs to interact with the XDC network, it typically sends requests to an RPC server, communicating with a node on the network to execute the requested action or retrieve information. In a shared RPC server environment, multiple DApps or applications send requests to the same server, potentially causing congestion and slowdowns.

By contrast, a dedicated RPC server is set up specifically for a particular DApp or application, providing its own dedicated resources and eliminating the potential for congestion from other clients. This can result in faster response times and more reliable performance, which can be important for high-traffic or mission-critical applications.

Setting up a dedicated RPC server typically involves setting up a full node on the XDC network, configuring it to enable RPC communication, and opening the necessary ports to allow external access to the server. Once the server is set up, the DApp or application can configure its connection to the dedicated RPC server to begin interacting with the XDC network.

XDC Network is a high-performance blockchain designed for enterprise-grade applications. If you're building a decentralized application (DApp) on the XDC Network, you must set up a full node and a dedicated RPC server to interact with the network.

This comprehensive guide will walk you through a step-by-step process of setting up a full node and a dedicated RPC server for your DApp on the XDC Network.

Prerequisites

Before we get started, make sure you have the following prerequisites:

• A server or cloud instance with at least 16 GB of RAM and 500 GB of storage.
• Ubuntu 20.04 LTS operating system.
• Basic knowledge of the Linux command line.

Step 1 – Setting up the full node with the Bootstrap command

sudo su -c "bash <(wget -qO- https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/setup/bootstrap.sh)" root

Example:-

$ 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
Your running network is mainnet
Please enter your XinFin MasterNode Name :- Demo_Server
Your Masternode Name is Demo_Server

Step 2 – Setting up the full node with Docker

Clone repository

git clone https://github.com/XinFinOrg/XinFin-Node.git

Enter XinFin-Node directory

cd XinFin-Node

Install Docker & docker-compose

sudo ./setup/install_docker.sh

Configure the .env file

Create a .env file by using the sample — .env.example. Enter either your company or product name in the INSTANCE_NAME field, and your email address in the CONTACT_DETAILS field.

cd mainnet   # or testnet
cp env.example .env
nano .env

Start your Node

cd mainnet
sudo docker-compose -f docker-compose.yml up -d

Stop the node

To stop the node, or if you encounter any issues, use:

sudo docker-compose -f docker-compose.yml down

Attach XDC Console

cd mainnet
sudo bash xdc-attach.sh

Step 3 – Exposing RPC & WebSocket Ports in docker-compose.yml

⚠️ Security Update: The default RPC ports have been removed from docker-compose.yml for security reasons. Previously, RPC and WebSocket ports were exposed by default, which posed a risk for nodes that did not intend to act as public RPC endpoints. If you want to run a dedicated RPC node, you must now manually add the port mappings.

Why this change matters: Nodes that want to participate in the network (validators, masternodes) no longer inadvertently expose their RPC endpoints to the public internet. Only operators who explicitly want to serve RPC traffic need to open these ports — giving you full control over your node's exposure.

Default docker-compose.yml (port 30303 only)

The current default file only exposes the P2P communication port:

services:
  xinfinnetwork:
    container_name: xdcnetwork-mainnet-node
    image: xinfinorg/xdposchain:v2.6.8
    volumes:
      - "./xdcchain:/work/xdcchain"
      - "./genesis.json:/work/genesis.json"
      - "./start-node.sh:/work/start.sh"
      - "./bootnodes.list:/work/bootnodes.list"
      - "./.pwd:/work/.pwd"
      - "/etc/localtime:/etc/localtime:ro"
    restart: "always"
    env_file:
      - .env
    ports:
      - "30303:30303"

Updated docker-compose.yml (with RPC ports added)

To run a dedicated RPC node, add the following two lines under the ports section:

services:
  xinfinnetwork:
    container_name: xdcnetwork-mainnet-node
    image: xinfinorg/xdposchain:v2.6.8
    volumes:
      - "./xdcchain:/work/xdcchain"
      - "./genesis.json:/work/genesis.json"
      - "./start-node.sh:/work/start.sh"
      - "./bootnodes.list:/work/bootnodes.list"
      - "./.pwd:/work/.pwd"
      - "/etc/localtime:/etc/localtime:ro"
    restart: "always"
    env_file:
      - .env
    ports:
      - "30303:30303"
      - "8989:8545"     # RPC — external 8989 → internal 8545
      - "8888:8546"     # WS  — external 8888 → internal 8546

💡 Port mapping format is HOST_PORT:CONTAINER_PORT. Ports 8545 and 8546 are the internal RPC and WebSocket ports inside the container. Mapping them to 8989 and 8888 exposes them on the host for your DApp to connect to.

After editing, restart your node to apply the changes:

sudo docker-compose -f docker-compose.yml down
sudo docker-compose -f docker-compose.yml up -d

Step 4 – Configuring RPC Settings in the .env File

Opening the ports in docker-compose.yml is only half the job. You also need to enable RPC and WebSocket inside the .env file and configure which origins are permitted to connect.

Full .env reference for an RPC node

INSTANCE_NAME=XF_MasterNode          # Your node display name
CONTACT_DETAILS=YOUR_EMAIL_ADDRESS    # Your contact email
SYNC_MODE=full
GC_MODE=full                          # Change to "archive" for an archive node
NETWORK=mainnet
PRIVATE_KEY=your_private_key_here
LOG_LEVEL=2

# API settings (RPC & WebSocket)
ENABLE_RPC=true                       # Default is false — must set to true
ENABLE_WS=true                        # Default is false — must set to true
API=db,eth,net,txpool,web3,XDPoS
ALLOWED_ORIGINS=*
RPC_VHOSTS=*
RPC_PORT=8545
WS_PORT=8546

Key changes required:

• Set ENABLE_RPC=true (the default is false)
• Set ENABLE_WS=true (the default is false)
• For production, replace ALLOWED_ORIGINS=* with your DApp's specific domain (e.g. https://yourdapp.com) to restrict access and protect your node's resources.

Running an Archive Node

If your DApp needs to query historical blockchain state — such as past balances or historical contract reads — you need an archive node. Change one value in your .env:

GC_MODE=archive     # Changed from "full" to "archive"

⚠️ Storage Warning: Archive nodes store the complete history of every blockchain state change. Plan for 2 TB or more of disk storage for a mainnet archive node — significantly more than the 500 GB required for a full node.

Step 5 – Speed Up Syncing with XDC Network Snapshots

Syncing a full node from genesis can take days or even weeks depending on your hardware and network speed. To get your RPC node operational much faster, the XDC Network provides pre-built snapshots — compressed archives of the blockchain data up to a recent block height. Using a snapshot can reduce sync time from days to just a few hours.

What is a snapshot?

A snapshot is a point-in-time archive of the XDC blockchain's data directory. Instead of downloading and verifying every block from the beginning, your node downloads this archive, extracts it, and only syncs the remaining blocks from the snapshot's cutoff point to the current chain tip.

Where to download snapshots

The latest snapshots are available at: https://rpc.xdc.network/snapshots/

Always download the most recent snapshot available to minimise the remaining sync time after extraction.

Step-by-step: applying a snapshot

1. Stop your running node:

sudo docker-compose -f docker-compose.yml down

2. Download the latest snapshot (check https://rpc.xdc.network/snapshots/ for the most current file):

wget https://rpc.xdc.network/snapshots/mainnet/full/mainnet_full_latest.tar

💡 Tip: Use wget -c to enable resume support in case your download is interrupted:

wget -c https://rpc.xdc.network/snapshots/mainnet/full/mainnet_full_latest.tar

3. Extract the archive (this may take time depending on file size and disk speed):

tar -xvzf xdcchain.tar

4. Replace the existing chain data with the snapshot:

rm -rf xdcchain/XDC
mv XDC xdcchain/XDC

5. Restart your node:

sudo docker-compose -f docker-compose.yml up -d

6. Monitor sync progress on the stats page: https://stats1.xinfin.network

Verifying your node is fully synced

Attach to the XDC console and check the sync status:

sudo bash xdc-attach.sh

Then run inside the console:

xdc.syncing

If it returns false, your node is fully synced. If it returns a sync object showing currentBlock and highestBlock, your node is still catching up. Once xdc.syncing returns false, your dedicated RPC endpoint is ready to serve your DApp.

Accessing your Dedicated RPC & WebSocket Endpoints

Once your node is fully synced, you can access your dedicated endpoints at:

• RPC: http://(your server IP):8989
• WebSocket: ws://(your server IP):8888

These URLs allow you to communicate with the XDC network and interact with your DApp or application.

Enabling the 0x prefix RPC Endpoint

To enable the 0x prefix RPC Endpoint, add the flag --enable-0x-prefix to your startnode.sh script. This will allow the RPC Endpoint to recognise and process 0x-prefixed addresses.

Quick Reference