DA Lightclient

Introduction

We're using DA Node, DA Lightclient Node, and DA Lightclient interchangeably in this doc.

Lumia chain builds on the concept of lightclients introduced by the AvailDA team. Lumia uses them as part of the infrastructure to enable seamless cross-chain interaction and liquidity interoperability.

As part of the goal to reach "stage 2", Lumia is putting emphasis on decentralization and community participation.

What does it mean?

November 2024, Lumia held a "Node sale" event. Participants who have purchased a node license NFT can become a DA Lightclient operator. These node licenses grant the holders the right participate in running of the Lumia chain — spin up and operate a DA Lightclient and earn a portion of the LUMIA rewards allocated to the DA nodes cluster.

For a general understanding of the Lumia's lightclient , read Lumia DA Lightclient Nodes.

For a general understanding of the underlying Avail technology, read Avail DA.

How to Run a DA Lightclient

The following provides step-by-step instructions on how to set up, run, and monitor DA Lightclient.

The repository (repo), holding the application, is lumia-lightclient.

Prerequisites

Ensure the following are installed on your system:

• Docker: we recommend Docker Desktop (Windows, Linux, macOS).

• Docker Compose: comes with Docker Desktop; alternatively, can be installed separately.

• Git.

Setting Up DA Lightclient

Step 1: Clone the repo

1. In the terminal, navigate to a directory of your choice, then clone the repo:

   git clone https://github.com/orionprotocol/lumia-lightclient

2. Navigate to the directory of the newly cloned repo:

   cd lumia-lightclient

Step 2: Create config.yaml

1. In the directory of the newly cloned repo, create a file named config.yaml:

   touch config.yaml

2. Copy-paste the following configuration into it:

   log_level = "info"
   http_server_host = "0.0.0.0"
   http_server_port = 7008
   port = 37100            # Unique P2P port
   webrtc_port = 37101     # Unique WebRTC port
   full_node_ws = ["wss://turing-rpc.avail.so/ws"]
   app_id = 206
   confidence = 92.0
   avail_path = "avail_path_node"
   # Bootstrap peer with updated port of the first node
   bootstraps = ["/ip4/127.0.0.1/tcp/37000/p2p/12D3KooWMm1c4pzeLPGkkCJMAgFbsfQ8xmVDusg272icWsaNHWzN"]

   Ensure the file is saved in the same directory as docker-compose.yml.

Running DA Lightclient

Step 1: Build and Start the Docker Container

To build and start the application in a docker container, from the directory of the newly cloned repo, run:

sudo docker compose up --build -d

Step 2: Verify the Application and Record Your peer_id

1. Once the application starts:

   1. Before proceeding, ensure you have waited at least 2 minutes after starting your Docker container.

   2. Verify its functionality by opening http://localhost:3008/status in your browser or using a tool like curl to access it. You'll see a response; a typical response might look like this:

      {
        "status": {
          "success": false,
          "message": "connect ECONNREFUSED 172.23.0.3:7008",
          "errorDetails": "No details available"
        },
        "nodePeerData": {
          "peer_id": "12D3KooWJ2vPjeRRvGV64VVTUgjHEsrC3jdjEgmFS1BNeewmrtsY",
          "listeners": {
            "local": ["/ip4/127.0.0.1/tcp/37100"],
            "external": [],
            "public": []
          },
          "operation_mode": "client",
          "routing_table_peers_count": 0,
          "routing_table_external_peers_count": 0
        },
        "nodeApiIdData": {
          "modes": ["light", "app"],
          "app_id": 206,
          "genesis_hash": "0xd3d2f3a349...",
          "blocks": {
            "latest": 1235113,
            "available": {
              "first": 1235110,
              "last": 1235112
            },
            "app_data": {
              "first": 1235110,
              "last": 1235112
            }
          }
        }
      }

   3. In this status response, find and record the peer_id value. This ID is essential for adding the node to the Lumia DA Tracker and must be recorded accurately for further configuration.

Adding Your DA Lighclient into the System

To add your DA Lightlclient to the system:

1. Visit Lumia DA Tracker.
2. In the top-right corner, click Add Node.

3. Connect the wallet that holds your Node Sale NFT.

4. In the newly opened dialogue named Add New Validator Node:

   1. Enter the NFT Token ID from your wallet (we aim to auto-populate this in the future).

   2. Enter you PeerId (peer_id) from the DA Lightclient that you've started.

   3. Click Add Node to finalize.

Now that your node is added to the system, it starts accruing rewards per hour as long as your uptime remains above 95%. You can claim your rewards directly to your connected wallet on Lumia Network once a month.

Monitoring Your DA Lightclient

Regularly check on your DA Lightlient to ensure it runs smoothly and keeps earning you LUMIA.

Check Logs

To monitor logs for debugging or status updates, use:

sudo docker compose logs -f

Access the API

• Endpoint: http://localhost:3008/status
• Method: GET

• Example response structure:

  • Status: Details about the service's health and connection state.

  • Node Peer Data: Information about the node’s peer configuration and connectivity.

  • Node API ID Data: Blockchain details such as genesis_hash, latest block, and app_data.

Troubleshooting

If your DA Lightclient is down, here are some common cases and solutions for them.

1. Connection Refused

Verify the service bound to port 7008 is running and accessible:

curl http://localhost:7008/v2/status

Check the container's networking:

docker network inspect <network-name>

2. Port Conflicts

Ensure ports 7008, 37100, and 37101 are not being used by other services.

3. Debugging Logs

View detailed logs to diagnose other issues:

sudo docker logs <container-name>

4. Validate Configuration

Ensure the config.yaml is formatted correctly and placed in the correct directory. Read Setting Up DA Lightclient for details.

Further Help

If you encounter issues or need further assistance, feel free to reach out to us on Discord.