Running Your Elements Node

Most exchange integrations can run entirely against public Esplora and Waterfalls infrastructure with LWK. But there are good reasons to run your own Elements node (the software that powers Liquid):

• Independence: no dependency on third party APIs
• Privacy: your queries don't leak to anyone else
• Peg-in validation: required if you want to validate Bitcoin peg-ins yourself
• Self sovereignty: you verify the state of the Liquid chain with your own rules

This page walks you through setting up a Liquid full node.

What is an Elements node?

The Liquid Network runs on software called Elements Core. It's an open source blockchain platform derived from Bitcoin Core, with added features for sidechain operation, Confidential Transactions, multi asset support, additional opcodes, Simplicity smart contracts, and federated block signing.

Elements Core ships three binaries you'll see throughout this page:

When you run Elements Core pointed at the Liquid Network, you get a Liquid full node:

• It connects to other Liquid peers on the network
• It downloads and validates the full Liquid blockchain
• It verifies every block and transaction against the consensus rules
• It maintains a UTXO set and the complete transaction history
• It exposes an RPC interface (elements-cli) for local interaction

Unlike Bitcoin, Liquid uses a federated block signing scheme rather than Proof-of-Work, so your node doesn't mine. It validates and relays blocks produced by the federation, and can be used to send and receive transactions.

What you need

Minimum requirements for a Liquid mainnet full node:

A Raspberry Pi 4 (8 GB) can run a Liquid node, which is useful for hobbyists or lightweight setups.

Install Elements Core

Download the latest release from the Elements GitHub releases page.

Linux (Ubuntu / Debian)

wget https://github.com/ElementsProject/elements/releases/download/elements-23.3.0/elements-23.3.0-x86_64-linux-gnu.tar.gz
tar xzf elements-23.3.0-x86_64-linux-gnu.tar.gz
cd elements-23.3.0
sudo install -m 0755 -o root -g root -t /usr/local/bin bin/*

macOS

brew install elements

Or download the DMG from the releases page.

Verify the install

elementsd --version
elements-cli --version

Configure the node

Create a config file at ~/.elements/elements.conf:

# Connect to Liquid mainnet (default)
chain=liquidv1

# Run as a daemon
daemon=1

# RPC settings for local applications
rpcuser=youruser
rpcpassword=yourstrongpassword
rpcallowip=127.0.0.1
rpcbind=127.0.0.1

# Keep the full blockchain (set to 1 for pruning, saves disk)
txindex=1

# Network settings
listen=1
maxconnections=40

# For testnet, uncomment:
# chain=liquidtestnet

# For memory constrained systems consider
# trim_headers=1

For testnet, use a separate data directory:

elementsd -datadir=~/.elements-testnet -chain=liquidtestnet -daemon

Start the node

elementsd

The daemon starts in the background. The initial sync will download and validate the entire Liquid blockchain. This takes a few hours on mainnet.

Monitor sync progress:

elements-cli getblockchaininfo

Look for the verificationprogress field. When it reaches 1.00000000, you're fully synced.

Interact with the node

Once synced, you can query the node using elements-cli:

# Get the current block height
elements-cli getblockcount

# Get info about a transaction
elements-cli getrawtransaction <txid> true

# List wallets
elements-cli listwallets

# Get the node's status
elements-cli getblockchaininfo

You can also use the JSON-RPC interface directly from your application:

curl --user youruser:yourstrongpassword \
  --data-binary '{"jsonrpc":"1.0","id":"test","method":"getblockcount","params":[]}' \
  -H 'content-type: text/plain;' \
  http://127.0.0.1:7041/

Enable peg-in validation

If you want your node to validate Bitcoin peg ins (recommended if you accept peg ins on your exchange), you need to also run a Bitcoin full node and point your Elements node at it.

Add to elements.conf:

# Validate peg-ins by connecting to a Bitcoin node
validatepegin=1 # this is the default

# Elements will use cookie authentication (preferred) if on the same machine as bitcoind
# Otherwise specify your bitcoind RPC details
#mainchainrpchost=127.0.0.1
#mainchainrpcport=8332
#mainchainrpcuser=bitcoinuser
#mainchainrpcpassword=bitcoinpassword

This requires a synced Bitcoin Core node running on the same host (or reachable via RPC). Without peg-in validation, your node trusts other peers for Bitcoin peg-in status.

See Blockstream's official guide on enabling peg-in validation for details.

Using the node with LWK

Once your node is running, you can use it as a backend for LWK instead of public Esplora. LWK supports Elements RPC directly, so your wallet operations can all go through your own node.

This gives you full independence: wallet operations, chain queries, and broadcasts all happen through infrastructure you control.

Resources

• Elements Project homepage
• Blockstream: Set Up a Liquid Node
• The Bitcoin Manual: Run a Liquid Node
• Elements GitHub
• Liquid Technical Overview

Next steps

• Peg in and Peg out: move BTC between Bitcoin and Liquid