The Developers' Guide to Liquid, One of the First Sidechains of Bitcoin by Blockstream

If you are going to work on software using Liquid, the sidechain of Bitcoin, there are several concepts you need to be familiar with. This article aims at developers and is based on a presentation I held for the Pixelmatic team.

Special thanks to Sosthene for proofreading my article and for his feedback! Follow him on Twitter.

Let's start now! And to discuss Liquid, we need to first discuss: Elements.

What Is Elements?

It is a fork of Bitcoin extended to be a sidechain platform with these features:

• Confidential Transactions
• Issued Assets
• Federated 2-Way Pegs
• Signed Blocks
• Additional opcodes

Source: https://elementsproject.org/

OK, whatever, but what’s Liquid?

Well, Liquid is an instance of Elements. Set as a sidechain of Bitcoin and maintained by Blockstream. Also:

• It is managed by a static federation of 15 members, but soon dynamic.
• It is configured to have a block time of 1 minute.
• And its main currency is L-BTC (Liquid Bitcoin), the result of the pegging of Bitcoin.

Source: liquid.net

What Are the Features of Liquid?

Let’s see a bit more details on the different features of Liquid/Elements.

📌 2-way pegging of Bitcoin

Peg-in BTC into the Liquid Sidechain

Pegging in BTC from the Bitcoin main net into the Liquid sidechain consists of depositing BTC into the Liquid Bitcoin wallet that is managed by the Federation. 102 confirmations on the Bitcoin mainnet are then required for you to claim your amount of L-BTC due, and the functionaries then grant you the corresponding amount on the Liquid sidechain.

Peg-out BTC from the Liquid Sidechain

Pegging out BTC from the Liquid sidechain back into the Bitcoin main net consists of receiving the BTC from an anonymous functionary from his wallet after being granted the amount by the federation. <br> 2 confirmations on Liquid are required for the operation to be allowed. Then the Federation will co-sign a transaction out of their 11 of 15 multisig wallets that are sending out the amount requested to one of the functionaries described anonymously. Finally, the functionary processes the transaction that will grant the BTC to the requester of the peg-out.

🙈 Confidential Transactions

• Amounts and assets are blinded using a blinding key, but UTXOs are visible
• There is a master blinding key that is generated from the wallet seed and derived as needed for each address:

blinding_private_key := HMAC_SHA256(key=master_blinding_key, msg=script_pubkey)

where script_pubkey corresponds to a specific non-confidential public address you want to make confidential

• That means that a Liquid wallet consists of two things: an extended private key and a master blinding key.

• Also, every confidential address is a non-confidential address blinded using the master blinding key. So the confidentiality is essentially a layer built on the top of classical HD wallets.

• Note that you can dump a specific blinding key to allow a tier to unblind it using the RPC unblindrawtransaction. And once in possession of the blinding key, any transaction happening with that specific address will be visible to the tier.

  FYI Blockstream Green has a feature to open esplora with the blinding keys to allow a tier to see a confidential transaction unblinded on the web.

White Paper: Blockstream

Specifications: Satoshi Labs

💰 Issued Assets

• One asset on Liquid/Elements has these attributes (all saved in the blockchain):
  • An asset ID (generated by Liquid)
  • A total supply
  • An optional reissuance key
  • An optional contract hash
• Reissuance keys are also an asset that comes with at least a total supply of 1 sat
• L-BTC is also an asset, a special one that can be pegged in and out: Details
• The bare minimum to issue an asset:

elements-cli issueasset 0.00000100 0

The above issues a confidential asset with a total supply of 100 Satoshis and no reissuance key.

• The contract defines metadata about the asset like its name, ticker, domain owner, precision, etc. Example the EXOeu token:

{
 "entity": {
  "domain": "exordium.co"
 },
 "issuer_pubkey": "030cff26f9c0d365f090e24917277e23269d7ef5d7f06dec9f09de9255b8950208",
 "name": "EXO Token Europe",
 "precision": 0,
 "ticker": "EXOeu",
 "version": 0
}

Reissuance

• To be able to reissue, you need only one token (satoshi) of the reissuance asset.
• If you have issued more than one reissuance asset, it means you can share that asset to others person. Then everybody who has one can reissue the asset. Though be cautious with that use-case because reissuance can be confidential, then it's nearly impossible to verify how much of the asset is in circulation.

Registration

• By default, assets are not registered on the Liquid Asset Registry.
• That gives you a chance to reissue another asset if you made a mistake before registering it.
• But once registered, it is irreversible and the tuple domain + ticker will be occupied forever.
• Details of the asset registration: https://docs.blockstream.com/liquid/developer-guide/proof-of-issuance.html

🪢 Federation

• The federation is composed of 15 functionaries
• They can propose blocks to be added to the blockchain in a round-robin fashion
• They co-sign blocks, a block needs 11 of 15 signatures to be valid
• They process peg-outs.
• When the federation will become dynamic, the total number of functionaries may vary dynamically

📃 Liquid RPC interface

Being a fork of Bitcoin, we find the same RPCs as its parent, plus some new ones like issueasset, blindrawtransaction, and more:

<div class="container h-sm pb-1"> <iframe src="https://elementsproject.org/en/doc/0.21.0.0/rpc/" class="w-full h-full"> </iframe> </div>

Source: elementsproject.org

🧰 The Liquid Ecosystem

For Users

White paper

• Liquid: https://blockstream.com/assets/downloads/pdf/liquid-whitepaper.pdf

Compatible Wallets

• Green: https://blockstream.com/green/
• Aqua: https://blockstream.com/aqua/
• SideSwap: https://sideswap.io/
• Coinos: https://coinos.io/
• Specter: https://specter.solutions/
• Marina: https://vulpem.com/marina.html

Centralized Exchanges

• Bitfinex: https://www.bitfinex.com/
• BTSE: https://www.btse.com/
• The Rock Trading: https://www.therocktrading.com/en/
• ...

DEX/Swap

• Sideshift<span>.</span>ai: https://sideshift.ai/
• SideSwap: https://sideswap.io/
• Bisq: https://bisq.network/
• coinos: https://coinos.io/
• TDEX: tdex.network
• Bitmatrix: beta.bitmatrix.app

Explorers

• blockstream<span>.</span>info: https://blockstream.info/liquid/
• liquid.network: https://liquid.network/

For Developers

Documentation

• About Elements: https://elementsproject.org/
• About Liquid Testnet: https://liquidtestnet.com/
• About Liquid: https://docs.blockstream.com/liquid/technical_overview.html

Node

• Elements: https://github.com/ElementsProject/elements

Cached API/Backend

• Blockstream ElectRS: https://github.com/Blockstream/electrs

Explorer

• Esplora: https://github.com/Blockstream/esplora
• Blockstream Registry: https://blockstream.info/liquid/assets

Libraries

• Vulpem Go Elements: https://github.com/vulpemventures/go-elements
• Vulpem LiquidJS: https://github.com/vulpemventures/liquidjs-lib
• Vulpem LDK: https://github.com/vulpemventures/ldk
• Blockstream GDK: https://github.com/Blockstream/gdk/
• LibWally: https://github.com/ElementsProject/libwally-core

Wallet Tools

• Mnemonic Code Converter: https://iancoleman.io/bip39/
• BIP32 Generator: http://bip32.org/

Environment stack

• Nigiri: https://github.com/vulpemventures/nigiri

Liquid Sidechain Available Environments

Alike Bitcoin, Liquid has multiple environments at your disposal.

You can set up in your elements.conf the chain you want to use.

Liquid Regtest (chain=liquidregtest)

• I am lying to you, actually. You can input any not known chain, and it will create an Elements environment, with the parameters of your choices. So liquidregtest is not a known chain, it will start a chain named with this name. But you could name it differently like andrewschain, ethereum, or whatever. Details: https://github.com/ElementsProject/elements#modes
• Regtest stands for regression test mode. It's a mode you use to do local development.
• When initializing your node, you can specify the number of free coins you will create and that will serve as your main currency (your own test Bitcoins).
• There are no pegging, mining, or federations in place. But you can generate blocks on demand.
• To simulate a production environment, you can set up a cron task to generate a block every minute.
• Everything you do stays local in your node.

Liquid Testnet (chain=liquidtestnet)

• It was recently deployed.
• There is no pegging, so if you need coins you can use the official faucet here: https://liquidtestnet.com/faucet.
• Like in production, the block time is 1 minute.
• To configure your Elements node for it, here are the instructions: https://docs.blockstream.com/liquid/node_setup.html#connecting-to-liquid-testnet
• It has an official explorer: https://blockstream.info/liquidtestnet/
• Unlike regtest, with testnet is public hence be aware of that.
• Also, testnet has an official asset registry as well: https://blockstream.info/liquidtestnet/assets

That can be helpful to debug issuance and registration of assets, a thing you cannot do with regtest.

Liquid Mainnet (chain=liquidv1)

• The production environment of Liquid.
• As mentioned before, the block time is 1 minute, and mainnet Bitcoin can be pegged in and out of it.

🎇 Conclusion: The Introduction to Liquid for Developers

With this knowledge, you should have enough to get started to work on Liquid.

To sum up, here are my advice, if you are willing to:

• add payment in L-BTC or another Liquid asset on your e-commerce website, look at BTCPay and WooCommerce with the Liquid+ plugin: https://github.com/ndeet/liquid-assets-for-woocommerce
• create a Liquid wallet, you can either look at the LDK made in JS so good for web apps, or GDK made in C++ and Rust good for desktop or native apps,
• issue an asset (either NFT or fungible tokens too), you can look at either Blockstream AMP or build a custom solution with liquidjs or go-elements
• create an NFT trading platform, you can fork off Raretoshi
• create a SWAP/DEFI platform, look at coinos open source projects: https://github.com/coinos/.

And to go deeper down the rabbit hole, you can start searching on these subjects:

• Multisignature wallets
• Taproot
• Partially signed transactions
• Atomic swap

Have fun!

Also published here.