Skip to content

page.mdx

Latest commit

 

History

History
321 lines (218 loc) · 9.03 KB

page.mdx

File metadata and controls

321 lines (218 loc) · 9.03 KB
description Advanced topics for operating a Celestia light node.

import { Steps, Callout, Tabs } from 'nextra/components'

Advanced

This page collects advanced topics for Celestia light nodes. For setup and blob posting, see Getting started.

Start light node with consensus endpoint authentication

If the consensus node gRPC endpoint you connect to requires authentication, pass a directory containing xtoken.json:

celestia light start \
  --core.ip snowy-methodical-leaf.celestia-mainnet.quiknode.pro \
  --core.tls \
  --core.xtoken.path /path-to-directory \
  --core.port 9090

Where /path-to-directory contains xtoken.json (recommended: chmod 600):

{
  "x-token": "<YOUR-SECRET-X-TOKEN>"
}

Run the light node with a custom key

To use a non-default key, make sure the key exists in your node store and pass --keyring.keyname on start:

For key creation, backup, import/recover, and Docker setups, see [Create a wallet with celestia-node](/operate/keys-wallets/celestia-node-key).

<Tabs items={['Mainnet Beta', 'Mocha', 'Arabica']}> <Tabs.Tab> bash celestia light start --core.ip <URI> --core.port <port> \ --keyring.keyname <name-of-custom-key> </Tabs.Tab> <Tabs.Tab> bash celestia light start --core.ip <URI> --core.port <port> \ --keyring.keyname <name-of-custom-key> --p2p.network mocha </Tabs.Tab> <Tabs.Tab> bash celestia light start --core.ip <URI> --core.port <port> \ --keyring.keyname <name-of-custom-key> --p2p.network arabica </Tabs.Tab>

Run the light node with SystemD

Follow the tutorial for running Celestia Node as a background process with SystemD: /operate/maintenance/systemd#celestia-light-node.

Fast sync with a trusted hash

Setting and syncing to a trusted height and hash means your light node will not sample the entire chain from genesis. This is useful when you want to sync your light node quickly.

This adds the trust assumption that you trust the source of the height and hash.

Celestia also supports initializing from a trusted hash via trusted hash recovery.

Get a trusted height and hash

This example uses the P-OPS Mocha endpoint:

read -r TRUSTED_HEIGHT TRUSTED_HASH <<<"$(curl -s https://rpc-mocha.pops.one/header | jq -r '.result.header | "\(.height) \(.last_block_id.hash)"')" && export TRUSTED_HEIGHT TRUSTED_HASH

Set SyncFromHeight and SyncFromHash

Edit your config file at ~/.celestia-light-{{constants['mochaChainId']}}/config.toml and set:

SyncFromHeight = 123456
SyncFromHash = "E8BD0C48260C496BB7A4D8D1E7BDBF1F26A2FE3CF5714DECE1741B2FFB3C095C"

Ensure SyncFromHash has no 0x prefix.

Start the node

celestia light start --p2p.network mocha --core.ip rpc-mocha.pops.one --core.port 9090

High throughput transaction submission

Celestia supports three transaction submission modes that affect how transactions are queued and submitted, impacting throughput and ordering guarantees. These modes are controlled by the TxWorkerAccounts setting in your light node's config.toml file.

Default mode (TxWorkerAccounts = 0)

This is the default behavior. Transactions are submitted immediately without a queue.

Characteristics:

  • Transactions enter the mempool immediately
  • No queuing or waiting for confirmations
  • Potential sequence number conflicts if submitting multiple transactions quickly
  • Same behavior as versions prior to v0.28.2

Queued mode (TxWorkerAccounts = 1)

Enable synchronous, ordered submission by setting TxWorkerAccounts to 1 in your config.toml.

Open your config file

nano ~/.celestia-light-{{constants['mochaChainId']}}/config.toml

Set TxWorkerAccounts to 1

Find the [SubmitClient] section and add or update:

[SubmitClient]
TxWorkerAccounts = 1

Restart your node

celestia light start --p2p.network mocha --core.ip rpc-mocha.pops.one --core.port 9090

Characteristics:

  • Each transaction queues until the previous one is confirmed
  • Preserves strict ordering of transactions based on submission time
  • Avoids sequence mismatch errors
  • Throughput: approximately 1 PayForBlobs transaction every other block

Use case: Applications requiring strict transaction ordering

Parallel mode (TxWorkerAccounts > 1)

For high-throughput applications that don't require sequential ordering, enable parallel submission by setting TxWorkerAccounts to a value greater than 1.

Open your config file

nano ~/.celestia-light-{{constants['mochaChainId']}}/config.toml

Set TxWorkerAccounts to desired number of lanes

Find the [SubmitClient] section and add or update:

[SubmitClient]
TxWorkerAccounts = 8

Restart your node

celestia light start --p2p.network mocha --core.ip rpc-mocha.pops.one --core.port 9090

How it works:

  • Creates TxWorkerAccounts parallel submission lanes
  • Each lane is a subaccount automatically created and funded from your default account
  • Example: TxWorkerAccounts = 8 creates 7 subaccounts + 1 default account = 8 parallel lanes
  • Enables at least 8 PayForBlobs transactions per block

Characteristics:

  • Transactions can be submitted concurrently across multiple lanes
  • Does NOT guarantee transaction ordering
  • Blobs may be included in blocks in a different order than submitted
  • Higher throughput for applications that can handle unordered transactions

Use case: High-throughput, unordered workflows

**Important:** When retrieving blobs submitted in parallel mode, you must track the height, namespace, and commitment for each blob submission, as you won't know which subaccount was used.

Subaccount management:

  • Subaccounts are automatically created and funded from your default account
  • They are named parallel-worker-1, parallel-worker-2, etc. in your keyring
  • Subaccounts are reused across node restarts if TxWorkerAccounts value remains the same
  • If you decrease TxWorkerAccounts, only the first N workers are used
  • If you increase TxWorkerAccounts, additional workers are created

Comparison table

Mode TxWorkerAccounts Ordering Throughput Use case
Default 0 Not guaranteed Immediate Simple applications, single transactions
Queued 1 Guaranteed ~1 tx per block Applications requiring strict ordering
Parallel >1 Not guaranteed ≥N txs per block High-throughput, unordered workflows

Node store contents

The node store is created during celestia light init and lives under ~/.celestia-<node-type>-<network>.

For example, a Mocha light node store at ~/.celestia-light-{{constants['mochaChainId']}} contains:

  • config.toml: Node configuration settings
  • data/: Database files
  • keys/: Node identity and account keys

Get your auth token

Your auth token is useful when you want to interact with your Celestia light node from another machine or a client application. Generate an admin token with:

celestia light auth admin --p2p.network mocha

Each time you run this, you will receive a new token. It's not possible to revoke tokens once they are issued.

Use celestia light auth --help to learn more about the available options.

Find your node ID

Your node ID is your libp2p peer ID. You’ll need it when creating multiaddrs (for example, .../p2p/<node-ID>).

While your node is running, run:

celestia p2p info

See also p2p.Info in the Node API p2p section.

Migrate node ID to another server

If you want the new machine to keep the same node identity, back up the identity material from your node store (for example, the keys/ directory under ~/.celestia-light-<network>/) and restore it on the new machine before starting the node.

Pruning windows

If you need data older than your current pruning windows, use SyncFromHeight/SyncFromHash to re-sync from an earlier point in time.

Advanced key management with cel-key

For key management beyond the built-in capabilities of the light node, use the separate cel-key utility. This dedicated tool allows you to create, import, and manage keys, and to select which key your node uses.

See Create a wallet with celestia-node.