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.​

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.

There is currently no 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.

Before you start, ensure you have:

  • Linux x86_64, macOS, or a Raspberry Pi 5 with Raspberry Pi OS installed
  • glibc version 2.39 or later (Linux only)
  • At least 64 GB of storage

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"

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:

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

  2. Install the module:

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

  3. Launch logoscore in daemon mode and load the Logos Blockchain module:

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

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.0:

    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.
    info

To migrate an existing version 0.1.2 blockchain config to version 0.2.0, run the migrate_user_config_0_1_2 command of the blockchain module and stop the module before restarting it in the next step:

logoscore call blockchain_module migrate_user_config_0_1_2 \
    user_config.yaml \
    old_user_config.yaml \
    my_keystore.yaml

logoscore call blockchain_module stop

:::

  1. Start the node:

    logoscore call blockchain_module start user_config.yaml ""

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:

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

    # Alternatively, send a request directly to your node port
    curl -s http://localhost:8080/cryptarchia/info | jq .

    Example response:

    {
      "lib": "3d0c...4e6d",
      "lib_slot": 0,
      "tip": "f44d...e2f5",
      "slot": 70899,
      "height": 120,
      "mode": "Bootstrapping"
    }
    • mode 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",
      "n_peers": 16,
      "n_connections": 19,
      "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 -A3 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

  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"
    }
    • Only one faucet transaction can be included per block. During high demand, your transaction may be dropped; retry the request and wait 1 to 2 minutes before checking again.
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​

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?​

Only one faucet transaction can be included per block. During high demand, your transaction may be dropped. Retry the request and wait 1 to 2 minutes before checking your balance again.