Skip to main content

Run a Logos Blockchain node on the public testnet from the CLI

Start a node and verify runtime and consensus signals.​

Version

This document is accurate for Testnet v0.2.1.

With this tutorial, you will install the Logos Blockchain node, connect to the public testnet, and verify that your node is running. The Logos Blockchain is the blockchain component of the Logos technology stack, providing a privacy-preserving and censorship-resistant framework for decentralised applications. This procedure is for node operators setting up a node for the first time.

Prerequisites
  • A supported OS:
    • Linux x86_64
    • macOS aarch64 (recent versions)
    • Raspberry Pi 5 with Raspberry Pi OS
  • glibc version 2.39 or later (Linux only)
  • On x86_64, a CPU with ADX instruction support: Intel Broadwell or later, or any AMD Zen. On virtual machines, configure the hypervisor to pass through host CPU features. Generic CPU models such as kvm64 and qemu64 hide ADX and cause the blockchain module to crash with signal 4.
  • 2 Core CPU, 2Ghz. Modern multi-core processor.
  • Minimal RAM (1 Gb).
  • SSD with 100+ GB free with ability to expand storage on demand.
  • Relatively reliable network connection. 1Mbps of free bandwidth.

What to expect​

  • You can install the node binary, generate a configuration, and join the public testnet.
  • You can verify that your node is syncing and connected to peers using the local API.
  • You can receive test tokens from the faucet and automatically participate in the consensus lottery once your stake matures.

Step 1: Install Logos core tools​

  1. Use the install-node-tools.sh helper script to install logoscore, lgpd, and lgpm into ./bin:

    curl -fsSL https://raw.githubusercontent.com/logos-co/logos-docs/main/resources/scripts/install-node-tools.sh | sh
    export PATH="$PWD/bin:$PATH"
    info

    On Linux, logoscore, lgpd, and lgpm ship as AppImages, which require FUSE. In environments without FUSE, such as Docker containers and minimal installations, the tools fail with No suitable fusermount binary found on the $PATH. Either install FUSE with apt install fuse3 or set export APPIMAGE_EXTRACT_AND_RUN=1 to run the tools without FUSE.

Step 2: Load the Logos Blockchain module​

Download the Logos Blockchain module with lgpd, then install it with lgpm before loading it with logoscore.

  1. Download the module. The root hash selects the exact published package identity for the pinned version:

    lgpd download blockchain_module --version 0.2.3 --output ./
    # writes ./blockchain_module-0.2.3.lgx

  2. Install the module:

    lgpm --modules-dir ./modules install --file blockchain_module-0.2.3.lgx

  3. Launch logoscore in daemon mode:

    logoscore -m ./modules -D &

  4. Confirm the daemon RPC server is up. The daemon needs a few seconds to start, so repeat this command until the daemon reports running:

    logoscore status

    Example response once the daemon is ready:

    {"daemon":{"pid":4720,"status":"running","version":"1.0.0"},"modules":[...]}

  5. Load the Logos Blockchain module:

    logoscore load-module blockchain_module
    • A load-module sent before the daemon is ready fails with an RPC or missing client config error. If that happens, check logoscore status again and retry.

Step 3: Configure and start the node​

The generate_user_config subcommand generates a user configuration that includes per-node settings such as keys, ports, and peer addresses, along with fresh cryptographic keys and an auto-detected public IP.

info

Make sure to use the current bootstrap peer addresses in the Logos Blockchain Node release notes for your selected release.

  1. Generate your user_config.yaml by running generate_user_config with the bootstrap peer addresses. For example, for release 0.2.3:

    logoscore call blockchain_module generate_user_config '{
        "initial_peers": [
            "/ip4/65.109.51.37/udp/3000/quic-v1/p2p/12D3KooWFrouXfmrR4nsLMtE7wu15DoMJ6VtoUtHinREZCvbWHar",
            "/ip4/65.109.51.37/udp/3001/quic-v1/p2p/12D3KooWJRGau8M1rjT7R5e4YYsgdFhsMX35nRDtMwCDjxQkXAHz",
            "/ip4/65.109.51.37/udp/3002/quic-v1/p2p/12D3KooWQXJavMDTRscjauFSgVAB1VLB6Rzpy2uY5SU9Tk7927tb",
            "/ip4/65.109.51.37/udp/50001/quic-v1/p2p/12D3KooWSQc7CcGtvWDPF1yCbBthFnQjprfCVHmfmNDUrSmqQsU1"
        ]
    }'
    • To change the API port, set api.backend.listen_address in user_config.yaml before starting. The default is 8080.

  2. Start the node:

    logoscore call blockchain_module start user_config.yaml ""
    info

    The Logos Blockchain node does not currently support dynamic wallet key management. To add new keys you must manually edit user_config.yaml and restart the node. If the node is restarted while bootstrapping, it does not save sync progress and restarts from the beginning.

Step 4: Verify that your node is running and connected to peers​

Wait for your node to finish syncing and reach Online mode before requesting tokens. Pipe the get_cryptarchia_info command through jq . to format JSON output.

  1. Check the consensus state. The logoscore call and the node's HTTP endpoint return the same data in slightly different shapes.

    logoscore call blockchain_module get_cryptarchia_info | jq -r .result.value | jq .

    Example response (the logoscore call returns a flat object with a mode field):

    {
      "lib": "3d0c...4e6d",
      "lib_slot": 0,
      "tip": "f44d...e2f5",
      "slot": 70899,
      "height": 120,
      "mode": "Bootstrapping"
    }

    Alternatively, send a request directly to your node port:

    curl -s http://localhost:8080/cryptarchia/info | jq .

    Example response (the HTTP endpoint nests the fields under cryptarchia_info, names the status field state, and adds a top-level phase):

    {
      "cryptarchia_info": {
        "lib": "3d0c...4e6d",
        "lib_slot": 0,
        "tip": "f44d...e2f5",
        "slot": 70899,
        "height": 120,
        "state": "Bootstrapping"
      },
      "phase": "ProlongedBootstrapPeriod"
    }
    • The status field (mode from the logoscore call, state from the HTTP endpoint) starts as Bootstrapping while syncing and transitions to Online once caught up.
    • Confirm slot and height are increasing. height counts confirmed blocks; slot counts elapsed time intervals, with a new block expected roughly every 10 seconds.

  2. Check peer connectivity:

    curl -s http://localhost:8080/network/info | jq .

    Example response:

    {
      "listen_addresses": ["/ip4/127.0.0.1/udp/3001/quic-v1"],
      "peer_id": "12D3...fuS2",
      "connected_peers": ["12D3...Mxu1", "12D3...sbD3"],
      "discovered_peers": ["12D3...Mxu1", "12D3...sbD3"],
      "n_peers": 16,
      "n_connections": 19,
      "n_discovered_peers": 18,
      "n_pending_connections": 0
    }
    • Confirm n_peers is greater than 0.

  3. After 30–60 seconds, run the get_cryptarchia_info command again and confirm slot and height have increased.

  4. Wait until mode transitions to Online before continuing. Bootstrapping should take approximately 1 hour.

Step 5: Request tokens from the faucet​

A faucet distributes free tokens on test networks so you can experiment without financial risk. Navigate to the public faucet site after your node reaches Online mode.

  1. Find the keys associated with your node:

    grep -A6 known_keys user_config.yaml

    Example output:

    known_keys:
        57364103d3ff29c35d2073cba0526ef729b8e08490bddfc6b74128b6613fe923: ...
        de3233cec107e6589f83d4f3094caa65c633b5b33601211353779dc01972ca14: ...
    voucher_master_key_id: de3233cec107e6589f83d4f3094caa65c633b5b33601211353779dc01972ca14

  2. Choose any key from known_keys, enter it in Destination Public Key (Hex) on the faucet site, and press Request Funds.

    Image of the faucet UI after requesting funds with a public key

    tip

    The faucet UI POSTs to https://testnet.blockchain.logos.co/web/faucet-backend/<your-chosen-key>. You can call that endpoint directly from a script or headless host:

    curl -X POST "https://testnet.blockchain.logos.co/web/faucet-backend/<your-chosen-key>"
    # {"status":"queued"}

  3. Wait 1 to 2 minutes, then check your balance. Replace <your-chosen-key> with the key you used:

    curl -s http://localhost:8080/wallet/<your-chosen-key>/balance | jq .

    Example response:

    {
      "tip": "5d16d4bd3712dc5869fc624e59774552b4fb0c974a6efa516563b3778bac9258",
      "balance": 1000,
      "address": "57364103d3ff29c35d2073cba0526ef729b8e08490bddfc6b74128b6613fe923"
    }
    • The faucet enforces a rate limit per key. A request made during the cooldown returns 429 with {"status":"cooldown","retry_after_secs":...}. Wait for the cooldown to pass, then retry.
info

Your tokens become eligible for consensus after 3.5 hours. Confirm that your node is participating by checking that mode remains Online and height continues to increase.

Block proposal is probabilistic. Your node will not propose on every slot; participation depends on your stake relative to total active stake in the network.

Troubleshooting the Logos Blockchain node​

logoscore call fails with RPC call failed?​

An error such as:

{"code":"RPC_FAILED","message":"callModuleMethod('blockchain_module','generate_user_config') RPC call failed.","status":"error"}

means the logoscore daemon isn't reachable, or the module isn't loaded. Run logoscore status to tell the cases apart: it reports the daemon state, running or not_running, and the status of each module, loaded, not_loaded, or crashed. Restart the daemon if needed, then load the module:

logoscore -m ./modules -D &
logoscore load-module blockchain_module

If the module shows not_loaded again after a successful load-module, or calls keep failing, check the daemon output for a module crash:

[critical] [logos] [blockchain_module] FATAL: module 'blockchain_module' crashed (signal 4).

signal 4 is an illegal-instruction fault. One known cause: the blockchain module requires a CPU with ADX support. Run grep -c adx /proc/cpuinfo to check. An output of 0 means the CPU, or the CPU model of the VM, lacks ADX. On physical hardware, the module needs an Intel Broadwell or later, or an AMD Zen CPU. On a virtual machine, set the CPU model to pass through host features, for example host in QEMU and Proxmox.

If the count is greater than 0, the crash has a different cause. Collect the complete FATAL lines from the daemon output, including the backtrace addresses, together with the last lines of the newest node log file in the directory where the daemon runs, and report them to the Logos team.

Loaded modules don't persist across daemon restarts, so always re-run load-module after restarting the daemon. A METHOD_FAILED error such as Call to blockchain_module.<method> failed. means the daemon is reachable but the call itself failed. The most common causes are a module that isn't loaded or a missing required argument, such as calling generate_user_config without the JSON initial_peers argument.

The testnet explorer shows an error when I click on a transaction?​

The testnet explorer does not support clicking on individual transactions. Searching by address is also not supported. Transaction hashes returned by the faucet may appear truncated and may not be immediately findable.

My wallet balance is not updating after requesting tokens?​

If the balance endpoint returns 404 with The requested address could not be found in the wallet, your node hasn't yet synced past the block containing the faucet transaction. Funded addresses aren't visible while the node is still Bootstrapping. Wait for the node to reach Online mode and check again.