Liquid is built using the open-source Elements code base.

The following guide shows you how to set up and run an Elements node.

The Elements code defaults to using the live Liquid network (liquidv1) but you should note that you can develop by setting chain=elementsregtest in your config file or access the Liquid test network using chain=liquidtestnet. You can also manually set config values using the test net config file template here and receive test network L-BTC from this faucet.

This guide focuses on elementsregtest but please be aware that the test net for Liquid is public and applications like the Blockstream Explorer, Blockstream Green, and Blockstream AMP also have test net instances. Liquid test net does not have a parent chain and therefore peg in or peg out cannot be used.

Installing and configuring Liquid

As Liquid is built using Elements, we’ll download the application from the Elements repository, execute commands against elementsd (daemon) using elements-cli (client), and edit things like the elements.conf config file.

In this section we will look at how to install and run a full Liquid client node and use the configuration file to switch the node between:

• Connecting to the live Liquid network.
• Running in a local test/development mode (elementsregtest, which is similar to Bitcoin’s regtest).

When run against the live Liquid network, our node will be able to connect to other Liquid network peers, allowing it to receive, validate and relay transactions and blocks.

In local test/development mode, our node will start its own copy of a new Liquid blockchain. The live and test chains will be stored in different folders on your machine, so they will never conflict with each other and the wallets will remain separate. This allows us to perform actions like sending funds, issuing assets, and generating blocks without fear of losing real funds.

When connected to the live network, our node will act as a “client” node. Other nodes on the network, called Functionary nodes, are responsible for securing the transfer of Bitcoin in to and out of the Liquid network and also for the creation of blocks through the block signing process. The blocks these Functionary nodes create are then relayed to other network participants. When our node runs in local test mode, we will be able to generate blocks ourselves, making the development and testing process a lot simpler. You can read more about the different types of Liquid nodes and the roles they play on the network in the Technical Overview.

To set a Liquid node up we need to:

• Download/install the Liquid binaries.
• Configure our node using a configuration file.

Before we begin, it is worth giving a brief overview of the applications we will be downloading and using.

Liquid Daemon (elementsd)

A Liquid node that runs as a background service. It can also processes requests made from other applications using Remote Procedure Call (RPC). It cannot be run at the same time as elements-qt if they share the same data directory, which they will by default.

Liquid Core/QT (elements-qt)

A desktop application (GUI/front-end) that serves as a Liquid node. It can also process requests using Remote Procedure Call (RPC). It cannot be run at the same time as elements if they share the same data directory, which they will by default.

Liquid Client (elements-cli)

A client application that allows you to make calls to elementsd or elements-qt by issuing RPC commands.

Liquid will, by default, try and connect to a local Bitcoin node in order to validate transactions where bitcoin are moved into the Liquid network (called a peg-in). We will assume that you have already installed and set up a Bitcoin node before moving on with installing Liquid. This requirement can be switched off by setting validatepegin=0 within the Liquid configuration (elements.conf) file, but we advise against disabling peg-in validation unless you are aware of the implications, running in a testing environment, or are not dealing with large amounts of funds.

Installation

The applications listed above can be downloaded from the Elements Github repository as either an installation/setup package or as the contents of a compressed file.

📘

A note before running Elements

After you have followed the install instructions below (you will find variants for Linux, Windows, and MacOS) do not run the software until you have followed the instructions in the Configuration section

Some releases are "code only" releases. If you only want to use the binaries, select the most recent release that has associated binary installation files:

There are a number of Linux distributions supported.
For example; Ubuntu users can choose the "elements-<version>-x86_64-linux-gnu.tar.gz" file,
whereas Raspberry Pi users should choose the "elements-<version>-arm-linux-gnueabihf.tar.gz" file.

Windows users should choose the "elements-<version>-win64-setup-unsigned.exe" file
if you are happy to run an unsigned setup on your Windows x64 machine.
If you need a 32bit variant or a version without an installer, you should chose the
appropriate file from the list.

Mac users should choose the "elements-<version>-osx-unsigned.dmg" dmg image file,
or download the binaries themselves.

After installation, you are now ready to move on to configuring your node.

Configuration

This guide assumes you are already running a Bitcoin full node. To allow Liquid Core to communicate with your Bitcoin node, certain parameters must be set in your Bitcoin configuration file, and then possibly included in the Liquid configuration file.

bitcoin.conf

We will first make sure that our Bitcoin node is set up to allow our Liquid node to communicate with it.

Include the following in your bitcoin.conf file if it is not already present:

server=1

This will ensure that your Bitcoin node creates a ‘cookie’ file within the data directory it is using on start up. The cookie file allows other applications to locally authenticate against your Bitcoin node, as long as they know where it is located. Using a cookie file is the prefered way of authenticating against a Bitcoin node. We will later tell our Liquid node the location of this file so that it can authenticate against the Bitcoin node.

Alternatively, you can also use RPC parameters (rpcuser, rpcport, and rpcpassword) specified in the bitcoin.conf file as the authentication method. If you want to use the RPC parameter method of allowing access, then also set the following within bitcoin.conf.

Note that the first value will start your Bitcoin node in “regtest” mode so that you can develop against it - you can omit it if you want to start the node on the live Bitcoin network:

regtest=1  
regtest.rpcport=18888  
regtest.port=18889  
rpcuser=<your user>  
rpcpassword=<your password>

You may also want to include the prune parameter in your Bitcoin node settings. Pruned mode reduces disk space requirements but will will not change the initial amount of time required for download and validation of the chain.

elements.conf

The elementsd, elements-qt and elements-cli applications will all use a configuration file named elements.conf. The elements.conf file tells elementsd and elements-qt which network to connect to and can set a number of different behaviors within the applications. It also tells them what credentials must be provided in order to accept an RPC request. The elements-cli application uses the configuration file to obtain the correct credentials in order to communicate with elementsd or elements-qt using RPC.

When you later start either of the three applications you can provide a datadir path. The path you provide tells the applications which directory to use to:

• Obtain RPC authentication data (user, password, port).
• Store blockchain and wallet data.
• Store log files etc.

If you want to use a different data directory that the defaults referenced below, for example an external hard drive, you can follow this guide.

The elements.conf configuration file is located in the following places by default. If you do not see the Liquid directory and the elements.config file you should create them now. Otherwise, open the elements.conf file for editing. You can find the file in the paths below, depending on the operating system you are using:

~/.elements/

%homepath%\\AppData\\Roaming\\Elements

As the Library file is hidden, you can access it by opening Finder,
selecting "Go" then "Go to Folder" from the menu and then entering
the path as "~/Library". From there you can go into the
"Application Support" folder and create the "Elements" folder.
Once you have created the Elements folder, you can run the following
from the Terminal app to create the Liquid config file:

touch "Library/Application Support/Elements/elements.conf"

📘

After changing elements.conf

After making any changes to elements.conf in the future, you will need to restart your Liquid node so that they take effect.

If your Bitcoin node is installed in the default location, Liquid should automatically find it when you later start it. If you use a non-default location for your Bitcoin node, you will also have to add the following parameter to your elements.conf file, pointing to the cookie file created by your Bitcoin node:

mainchainrpccookiefile=\<location_of_your_bitcoin_cookie_file>

If you want to use the RPC parameter method of allowing access to your Bitcoin node then also set the following within elements.conf, using the same user, password, and port that you set in bitcoin.conf:

mainchainrpcport=<18888_for_example>
mainchainrpcuser=<your_bitcoin_rpc_user_here>
mainchainrpcpassword=<your_bitcoin_rpc_password_here>

If you want to allow your Liquid node to accept RPC requests then also set the following. Note that these values will start your Liquid node in test/development mode. To start in live Liquid network mode, set the chain value to liquidv1 or remove the chain setting completely:

chain=elementsregtest
rpcuser=<your_liquid_rpc_user_here>
rpcpassword=<your_liquid_rpc_password_here>
elementsregtest.rpcport=<18884_for_example>
elementsregtest.port=<18886_for_example>

📘

Switching chains

To switch between live, public test net, and local development modes you will need to change the chain value between liquidv1, liquidtestnet, and elementsregtest. You must restart your node for these to take effect if you change them in the future. Be sure to also change the mode your Bitcoin node runs in if you do this. Please note that Liquid test net does not have a parent chain and therefore peg in or peg out cannot be used.

If you do not wish to validate peg-ins against your Bitcoin node, you can set the validatepegin parameter to a value of 0. This can be done either in the elements.conf file, or passed in as a command line parameter.

validatepegin=0

With this setting, you do not need to run a Bitcoin node as Liquid will not attempt to connect to one on startup.

📘

Warning

We advise against disabling peg-in validation unless you are aware of the implications , running in a testing environment, or are not dealing with large amounts of funds.

Running your Liquid Node

Once you have completed the steps in the Configuration section you will be able to start Liquid GUI or Liquid Daemon.

You will be able to run each of the applications from the command line
within the folder you extracted them to. For example:

./elementsd

or

./elements-qt

and

./elements-cli

Depending on your system set up, you may have to change the permissions
on the files before they will run.

You can run Liquid as a normal desktop application. It is worth noting that the
actual application will appear in your installed apps list as "Elements Core".

If you installed Liquid from the "dmg" image, you can run it as a normal
desktop application. It is worth noting that the actual application will
appear in your installed apps list as "Elements Core".

What next?

You should now be set up to start using your node.

You can connect it to the live Liquid network by setting chain=liquidv1 and letting it sync its local copy of the Liquid blockchain.

You might also want to switch your Liquid node to test/development mode using chain=elementsregtest and start the developer guide and app examples sections of the Elements Project website if you want to.

Please note that you can develop using chain=elementsregtest or access the Liquid test network using chain=liquidtestnet. You can also set config values using the template here and receive test net L-BTC from this faucet. This guide focuses on elementsregtest but please be aware that there is a public testnet for Liquid which application like the Blockstream Explorer, Blockstream Green, and Blockstream AMP can also be connected to. Liquid Testnet does not have a parent chain and therefore peg in or peg out cannot be used.

Enabling Peg-in Validation

This section will show you how to enable your Liquid node to validate peg-ins against a Bitcoin node. This is not mandatory, but it an important part of Liquid network security.

If you have not already installed and synced a Bitcoin node on your machine, you should follow the instructions on https://bitcoincore.org/en/download.

When you have a fully synced Bitcoin node running on your machine, you need to enable it to process requests from other applications, such as Liquid. To do this we need to add a line to the bitcoin.conf config file.

Changes to bitcoin.conf

Shutdown your Bitcoin node first before proceeding.

Edit the Bitcoin configuration file (bitcoin.conf) remembering to replace the references to elements with bitcoin. Use the following paths to locate and open the bitcoin.conf file, depending on your operating system:

~/.bitcoin/

%homepath%AppDataRoaming/Bitcoin

Library/Application Support/Bitcoin

When you have located and opened the bitcoin.conf file, add the following line to it: server=1 If you use a non-default location for your Bitcoin node, you will also have to add the following parameter to your elements.conf file, so that Liquid knows the location of the cookie file created by your Bitcoin node:

mainchainrpccookiefile=<location_of_your_bitcoin_datadir>

Save and close the file and restart your Bitcoin node.

Changes to elements.conf

Open the Liquid config file using the following paths to locate and open the elements.conf file, depending on your operating system:

~/.elements/

%homepath%AppDataRoaming/Elements

Library/Application Support/Elements

If your elements.conf file contains an entry of validatepegin=0, replace the 0 with a 1, and save and close the file. If your elements.conf file contains no value for validatepegin at all, you can close the file, no changes are needed.

Your Liquid node is now set up to validate peg-ins!

👍

Liquid Test Net

Please note that you can develop using chain=elementsregtest or access the Liquid test network using chain=liquidtestnet. You can also set config values using the template here and recive test net L-BTC from this faucet. This guide focuses on elementsregtest but please be aware that there is a public test network for Liquid which application like the Blockstream Explorer, Blockstream Green, and Blockstream AMP can also be connected to. Liquid Testnet does not have a parent chain and therefore peg in or peg out cannot be used.

Development tutorial and examples

For examples of how to issue assets, reissue, burn, set up a stand alone blockchain and sign blocks etc, you can use the Elements Project Website Tutorial. As Liquid is built using Elements anything that works on Elements will work on Liquid, as a Liquid node is an Elements node that uses default network settings.

The Elements Project website also contains the RPC specification and code examples in:

Python, C#, Node.js, Go, Ruby, Java, Perl.

You will also find more advanced examples that show how to:

• Manually create a transaction.

• Manually issuing an asset.

• Use asset contract hash and asset registration.

• Issue an asset to a multi-sig address.

• Spend and reissue from a multi-sig.

• Issue an asset using the issueasset command’s contract hash argument to enable registration with the Blockstream Liquid Asset Registry.

• Verify an output’s asset and amount values using the blinding factors.

Other development language tools

GDK (Blockstream Green Development Kit)

You can interact with the Liquid network using Blockstream's Green Development Kit.

LDK (Liquid Development Kit)

Vulpem Ventures' LDK - “Liquid Development Kit provides abstractions to speed-up implementation of elements-based wallets for browsers and NodeJS”.

LiquidJS

Vulpem Ventures' LiquidJS - “A fork of bitcoinjs/bitcoinjs-lib containing modifications that are necessary for support of elements-based blockchains”

Support

Don’t hesitate to contact the Liquid support team at [email protected]. We are happy to help you with any problems, ranging for example from being stuck during installation over integration with your existing infrastructure to bugs in the software. In any case, we would love to know your comments and ideas on how we can improve Liquid together!