Xode is a blockchain platform with its own on-chain governance that aims to bring game development, decentralized finance, real-word assets and businesses to Web3 and Polkadot.

Xode Light Node

Xode Light Node is a lightweight, containerized NestJS-based node designed to serve as a WebSocket JSON-RPC gateway and HTTP API layer for Polkadot-compatible blockchain environments.

This node bridges communication between Smoldot (a light Polkadot client) and your frontend or backend applications, enabling efficient blockchain queries, transaction broadcasting, and real-time event subscriptions — all through a unified WebSocket endpoint.

It’s optimized for scalability, portability, and quick deployment in containerized or multi-environment setups (e.g., Kubernetes, Docker Compose, or standalone VPS hosting).

✨ Key Features

✅ Dual-port architecture – Exposes both HTTP (3000) and WebSocket (9944) endpoints.
✅ Lightweight image – Built on node:22-alpine, ensuring minimal memory footprint.
✅ Smoldot-powered gateway – Enables Polkadot/Substrate-compatible JSON-RPC connections.
✅ NestJS framework – Structured, modular, and maintainable backend foundation.
✅ Dockerized deployment – Easy to deploy, replicate, and manage across environments.
✅ Namespace-ready design – Supports multiple Polkadot networks through dynamic WebSocket namespaces.
✅ Developer-friendly – Fully compatible with polkadot-api, @polkadot/api, and JSON-RPC clients.

🌐 Supported Chains

The Xode-Light-Node currently supports two distinct namespaces for light node connectivity:

Chain	Namespace	WebSocket URL	Description
🪙 Xode Polkadot	/xode-polkadot	ws://localhost:9944/xode-polkadot	Connects to the Xode polkadot main network
🔶 Xode Paseo	/xode-paseo	ws://localhost:9944/xode-paseo	Connects to the Xode paseo test network

Each namespace operates independently, allowing multiple clients to interact with different chains simultaneously through the same node instance.

🧩 System Requirements

Before you start, ensure your system meets the following minimum requirements:

Component	Recommended
OS	Ubuntu 22.04+, macOS 13+, or Windows 10+
CPU	2 cores minimum
Memory	1 GB minimum (512 MB for light mode)
Docker	v20.10 or higher
Node.js	v22+ (if building manually)

⚙️ Setup Guide

This section will guide you through installation and deployment, from installing Docker to running your Xode-Light-Node container.

1️⃣ Install Docker

Docker allows you to run applications inside lightweight, isolated containers.
If you don’t have it yet, install it based on your OS:

🐧 Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable --now docker

🍎 macOS / Windows

Download Docker Desktop from the official page: 👉 https://www.docker.com/products/docker-desktop

Verify your installation:

docker --version

2️⃣ Download the Image

Once Docker is ready, pull the latest prebuilt image from Docker Hub:

docker pull oliverrigonan/xode-light-node:latest

This will download the most recent version of Xode Light Node published by Noah Oliver Rigonan.

3️⃣ Run the Container

Start the container by exposing both HTTP and WebSocket ports:

docker run -d \
  --name xode-light-node \
  -p 3000:3000 \
  -p 9944:9944 \
  oliverrigonan/xode-light-node:latest

✅ Expected Result:

• The HTTP API is available at → http://localhost:3000
• The WebSocket JSON-RPC Gateway is available at → ws://localhost:9944

To check logs:

docker logs -f xode-light-node

To stop the container:

docker stop xode-light-node

To restart it:

docker restart xode-light-node

4️⃣ (Optional) Run via Docker Compose

If you prefer a declarative approach, use the included docker-compose.yml:

version: '3.9'

services:
  app:
    image: oliverrigonan/xode-light-node:latest
    container_name: xode-light-node
    ports:
      - '3000:3000'
      - '9944:9944'
    restart: unless-stopped

Then run:

docker compose up -d

and stop it with:

docker compose down

🧪 Testing Your Setup

After starting your container, verify both endpoints are working correctly.

✅ Test the HTTP Server

curl http://localhost:3000

If everything is working, you should see a response from your NestJS server (e.g., "Xode Light Node is running!").

✅ Test the WebSocket Gateway

Install wscat (a WebSocket testing tool):

npm install -g wscat

Then connect to your gateway for Xode Polkadot or Xode Paseo:

🔹 Xode Polkadot

wscat -c ws://localhost:9944/xode-polkadot

🔸 Xode Paseo

wscat -c ws://localhost:9944/xode-paseo

Then your WebSocket gateway is successfully running!

🧠 Integration with Polkadot API

You can connect your front-end or service layer using the polkadot-api client.

Example (TypeScript / Angular)

import { createClient } from 'polkadot-api';
import { getWsProvider } from 'polkadot-api/ws-provider/web';
import { xodePolkadot } from '@polkadot-api/descriptors';

// Use xode-polkadot or xode-paseo depending on the network
const provider = getWsProvider('ws://localhost:9944/xode-polkadot');
const client = createClient(provider);
const chainApi = client.getTypedApi(xodePolkadot);

async function getChainName() {
  const specs = await client.getChainSpecData();
  console.log('Connected to chain:', specs.name);
}

getChainName();

To switch networks, simply replace:

getWsProvider('ws://localhost:9944/xode-polkadot');

with:

getWsProvider('ws://localhost:9944/xode-paseo');

🧰 Troubleshooting

Issue	Cause	Fix
Connection refused	Container not running	Run docker ps and ensure xode-light-node is active
Port already in use	3000 or 9944 occupied	Change host ports: -p 4000:3000 -p 9955:9944
WebSocket not reachable	Gateway bound to localhost	Ensure it's bound to 0.0.0.0 inside the container
Chain not found error	Invalid namespace	Confirm correct namespace in WebSocket URL (/xode-polkadot or /xode-paseo)

🪐 License

• MIT License © 2025 Noah Oliver Rigonan
• Free to use, modify, and distribute with attribution.