# DeepDive into Liquid: Part I - Overview, Installation, and Peg-In

This is a multipart DeepDive that will focus on the [Liquid Sidechain](https://liquid.net). It will be released in 3 Parts:
* Part I (this): Overview, Installation, and first Peg-In
* Part II: Asset Creation and Configuration
* Part III: Advanced Topics and Peg-out

## Overview ##

Liquid is a federated BTC sidechain (Layer-2). The federation which controls the network are known as 'Functionaries'. Currently, there are 15 such Functionaries[^1] who are geographically dispered to help isolate the network from both physical and regulatory disruption. 

Functionaries do the block signing for the network, which happens in a round-robin style arrangement - and consensus requires 11-of-15 to be available and in agreement.

A unique aspect of this federation is that functionary membership is dynamic - using a protocol known as *DynaFed* - this allows members to be rotated out/in depending on circumstance. In order to support a large number of signers, the functionaries use a signature scheme known as [ROAST](https://eprint.iacr.org/2022/550.pdf) (Robust Asynchronous Schnorr Threshold Signatures). As stated:

    "It guarantees that a quorum of honest signers, e.g., the Liquid functionaries, 
    can always obtain a valid signature even in the presence of disruptive signers 
    when network connections have arbitrarily high latency. Our empirical performance 
    evaluation shows that ROAST scales well to large signer groups, e.g., a 67-of-100 
    setup with the coordinator and signers on different continents. Even with 33 malicious 
    signers that try to block signing attempts (e.g. by sending invalid responses or by not 
    responding at all), the 67 honest signers can successfully produce a signature within 
    a few seconds."

Obviously this along with the inclusion of *DynaFed* (a recent addition to the network), seems to indicate that they plan to increase the total federation functionaries from 15 to more in the future. 

**Functionaries Sign, not Mine**

A key aspect of Liquid is *there is no mining*. The core asset, L-BTC, is only created when BTC pegs-into the network, so unlike Bitcoin, mining is not used to create issuance of new coins. The total amount L-BTC can be verified along with the equivalent amount of BTC, which are held in a public multisig address. This ensures that there is no inflation possible of L-BTC, since it will balance 1:1 with the pegged BTC.

By default, all Liquid transactions use *Confidential Transactions*, so both the type of assets and amounts transacted are hidden, *even to functionaries*. However, Functionaries can still see the from / to addresses involved - they only don't know *what* is being transferred. 

**Liquid Ecosystem and Roles**

Here are some charts showing current ecosystem members and the roles various members can fulfill. In total there are currently 66 Liquid Members (not all Members are Functionaries).

![](1-liquid-member-logos.png)
![](2-liquid-roles.png)

### Assets

Liquid supports Asset Issuance. Any full-node can issue their own Assets (only requirement is to have needed L-BTC to pay for signing fees). These assets fall into the following categories / use-cases:

    * Tokens (e.g. arbitrary token issue, stablecoin, etc)
    * Swaps (e.g. atomic swap of Token A for Token B)
    * Options / Smart Contracts / Covenants (e.g. swap Token A for B if condition ABC is met)
    * Securities (e.g. issue dividends to Token A holders after X time)
    * Restricted Assets (e.g. prohibit holder of Token A from transfer without approval)

### Additional Opcodes

At its core, Liquid is basically "BTC plus special OPCODES less Mining". In order to support the Smart Contracts and Covenants seen above, Liquid reintroduces some safe but disabled opcodes, including string concatenation (CAT), substrings, integer shifts, and several bitwise operations ([see here for more](https://github.com/ElementsProject/elements/blob/master/doc/tapscript_opcodes.md?ref=blog.blockstream.com)).

Additionally a new DETERMINISTICRANDOM operation which produces a random number within a range from a seed. Also included is CHECKSIGFROMSTACK (CSFS) operation, which verifies a signature against a message on the stack, rather than the spending transaction itself.

These new opcodes have several use cases, including covenant-style controls, double-spent protection bonds, lotteries, merkle tree constructions to allow 1-of-N multisig with huge N (thousands), and probabilistic payments.

# Installation of Elements Node

Liquid uses a variation of BTC Core program known as Elements, much of the setup and use are very similar to bitcoin. Please note that Elements **requires a fully functioning bitcoind node** (it is a sidechain, after all). Thus for this demonstration, I am using my Umbrel since it makes installing Bitcoin and Elements quite simple. 

*If you are intending to run Liquid on a bare-metal setup, please refer to this [getting started guide](https://elementsproject.org/elements-code-tutorial/working-environment) to setup your environment. Setting up a core-bitcoin install is outside the scope of this DeepDive*

### Running Elements on Umbrel
* Meet requirements (1TB disk for BTC / 25GB disk for Liquid / >8GB RAM[^2]) 
* A running and fully-synced Bitcoin 'App'
* Install Elements 'App'

... Go take a several hour break while it downloads ...

* Navigate to Elements 'App' web interface on Umbrel and copy `rpcuser` and `rpcpassword` values

![](3-umbrel-elements.png)
  
* Save the above values as bash variables for use later
  - `$ export E_RPCUSER=elements`
  - `$ export E_RPCPASS=XXXXXXXXXXXXXXXXXXXXXXX`
* You should now be able to issue commands against the elements daemon
  - `$ sudo ./scripts/app compose elements exec node elements-cli -rpcuser=$E_RPCUSER -rpcpassword=$E_RPCPASS getblockcount`
  
    25846 (It doesn't matter what the number returned is as long as no error.)
* Create a default wallet
  - `$ sudo ./scripts/app compose elements exec node elements-cli -rpcuser=$E_RPCUSER -rpcpassword=$E_RPCPASS createwallet ""`
* Check balance info (should show 0 balance with no errors)
  - `$ sudo ./scripts/app compose elements exec node elements-cli -rpcuser=$E_RPCUSER -rpcpassword=$E_RPCPASS getwalletinfo`

# First Peg-In
Now let's peg-in some bitcoin in order to receive L-BTC within our Liquid wallet. (*NOTE: There are online services that automate this entire process and make it much simpler. In general services like [Sideswap](https://sideswap.io/peg-in-out/) make this process much easier*)

* Generate a new peg-in address
  - `$ sudo ./scripts/app compose elements exec node elements-cli -rpcuser=$E_RPCUSER -rpcpassword=$E_RPCPASS getpeginaddress`
    
      {
       "mainchain_address": "bc1qXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
       "claim_script": "001489b0XXXXXXXXXXXXXXXXXXXXXXXXX"
      }

* Save the `claim_script` above in a variable for use later
  - `$ export E_CLAIMSCR="001489b0XXXXXXXXXXXXXXXXXXXXXXXXX"`
* Send some btc to the `mainchain_address` listed above (I'm sending 150000 sats)
* Copy the BTC transaction ID and save to variable
  - `$ export B_TRANSID="bb1d0903XXXXXXXXXXXXXXXXXXXXXXXXXXX"`
* Wait for the confirmation[^4]
* On your BITCOIN node, run the following command
  - `$ sudo ./scripts/app compose bitcoin exec bitcoind bitcoin-cli getrawtransaction $B_TRANSID`
     
     020000000173f50....

* Save that output to bash variable
  - `$ export B_RAWTRANS='020000000173f50....`
* On your BITCOIN node, get output proof
  - `$ sudo ./scripts/app compose bitcoin exec bitcoind bitcoin-cli gettxoutproof '["<transaction_id_paste>"]'`
     
     00406426ea774aff7437de482c73f2ac8......

* Save output proof in bash variable
  - `$ export B_OUTPROOF='00406426ea774aff7437de482c73f2ac8....'`
* Now back on the elements node, we can claim the L-BTC
  - `$ sudo ./scripts/app compose elements exec node elements-cli -rpcuser=$E_RPCUSER -rpcpassword=$E_RPCPASS claimpegin $B_RAWTRANS $B_OUTPROOF $E_CLAIMSCR`
* Issue a getwallet info on Elements and you should see an unconfirmed balance
  - `$ sudo ./scripts/app compose elements exec node elements-cli -rpcuser=$E_RPCUSER -rpcpassword=$E_RPCPASS getwalletinfo`
    
    "unconfirmed_balance": {
      "bitcoin": 0.00149952
     }[^5],

* After 1 confirmations (approx 2 mins) the balance should be confirmed
  - `$ sudo ./scripts/app compose elements exec node elements-cli -rpcuser=$E_RPCUSER -rpcpassword=$E_RPCPASS getwalletinfo`

    "balance": {
    "bitcoin": 0.00149952}[^6]

## Wrap Up and Preview for Part II. 

This was just the basics, in this DeepDive we got our Elements node running and pegged-in our initial BTC balance. 

In Part II is where the fun begins, we will transfer (and see Confidential Transactions in practice), issue Assets, and get the assets in the registry.


**Footnotes:**

[^1]: As of 1-21-2024. There are 66 members who can perform other functions on network, but only Functionaries can sign

[^2]: RAM usage is higher for Liquid than for BTC alone due to Confidential Transactions processing

[^3]: It may be possible to run the `elements-cli` command without installing it separately, however I could not find it in the container. Anyway, the download of elements node is quite small and it communicates via localport on Umbrel, so this works fine.

[^4]: Requires 102 confirmations. Services like sideswap will release after 2 confs for small amounts  

[^5]: Balance less the 48sat transaction fee

[^6]: yes, the label is still called 'bitcoin' but can be changed if that annoys you :)



