Open a channel between two nodes running on regtest using CLN

As in the previous episode, we are in lightning repository and to start two Lightning nodes running on the Bitcoin regtest chain we source the script contrib/startup_regtest.sh and use the provided command start_ln:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ source contrib/startup_regtest.sh
lightning-cli is /usr/bin/lightning-cli
lightningd is /usr/bin/lightningd
◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ start_ln 2
Bitcoin Core starting
awaiting bitcoind...
Making "default" bitcoind wallet.
[1] 12033
[2] 12067
Commands:
        l1-cli, l1-log,
        l2-cli, l2-log,
        bt-cli, stop_ln, fund_nodes

The regtest chain has been started and we created a Bitcoin wallet named default which has balance null as we can see by running the following command:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest -getinfo
Chain: regtest
Blocks: 1
Headers: 1
Verification progress: 100.0000%
Difficulty: 4.656542373906925e-10

Network: in 0, out 0, total 0
Version: 230000
Time offset (s): 0
Proxies: n/a
Min tx relay fee rate (BTC/kvB): 0.00001000

Wallet: default
Keypool size: 4000
Transaction fee rate (-paytxfee) (BTC/kvB): 0.00000000

Balance: 0.00000000

Warnings:

We also want to be sure that we are running two instances of the lightningd. To do so we run the following command that tells us that one instance of lightningd is running with the base directory being /tmp/l1-regtest/ and the other with the base directory being /tmp/l2-regtest:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ ps -ax | grep lightningd
12034 pts/1    S      0:00 lightningd --lightning-dir=/tmp/l1-regtest
12071 pts/1    S      0:00 lightningd --lightning-dir=/tmp/l2-regtest
12481 pts/1    S+     0:00 grep --color=auto lightningd

And as we are going to use the alias l1-cli in the rest of the video, it is better to know exactly what it is:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ alias l1-cli
alias l1-cli='lightning-cli --lightning-dir=/tmp/l1-regtest'

Now we connect the node l1 to the node l2 using the command connect (provide by the startup script) like this:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ connect 1 2
{
   "id": "031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435",
   "features": "08a000080269a2",
   "direction": "out",
   "address": {
      "type": "ipv4",
      "address": "127.0.0.1",
      "port": 7272
   }
}

The id we get in the previous output is the id of the node l2 as we can check by running the following command:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l2-cli getinfo | jq .id -r
031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435

Now let's make the sub-command fundchannel returns the error 301: There are not enough funds in the internal wallet (including fees) to create the transaction.

First we look at the man page of the sub-command listfunds of lightning-cli which returns all funds available either in unspent outputs (UTXOs) in the internal wallet or funds locked in currently open channels:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli help listfunds
LIGHTNING-LISTFUNDS(7)                                  LIGHTNING-LISTFUNDS(7)

NAME
       lightning-listfunds  --  Command showing all funds currently managed by
       the Core Lightning node

SYNOPSIS
       listfunds [spent]

DESCRIPTION
       The listfunds RPC command  displays  all  funds  available,  either  in
       unspent  outputs (UTXOs) in the internal wallet or funds locked in cur-
       rently open channels.

       spent is a boolean: if true, then the outputs will include  spent  out-
       puts in addition to the unspent ones. Default is false.

RETURN VALUE
       On success, an object is returned, containing:

       · outputs (array of objects):

         · txid (txid): the ID of the spendable transaction
         · output (u32): the index within txid

Now we check that the node l1 has no funds, neither in its internal wallet nor in an open channel:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli listfunds
{
   "outputs": [],
   "channels": []
}

Let's continue and look at the man page of the sub-command fundchannel. We see that the fundchannel takes at least two arguments:

1. the first one being the id of the peer we want to open a channel with. This id is obtained from the sub-command connect of lightning-cli.

2. The second is the amount that can be expressed either in sat, msat or btc. The value cannot be less than the dust limit, currently set to 546, nor more than 16777215 satoshi (unless large channels were negotiated with the peer).

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli help fundchannel
LIGHTNING-FUNDCHANNEL(7)                              LIGHTNING-FUNDCHANNEL(7)

NAME
       lightning-fundchannel -- Command for establishing a lightning channel

SYNOPSIS
       fundchannel   id   amount   [feerate]   [announce]   [minconf]  [utxos]
       [push_msat] [close_to] [request_amt] [compact_lease]

DESCRIPTION
       The fundchannel RPC command opens a payment channel with a peer by com-
       mitting  a funding transaction to the blockchain as defined in BOLT #2.
       If not already connected, fundchannel  will  automatically  attempt  to
       connect  if  C-lightning  knows  a way to contact the node (either from
       normal gossip, or from a previous connect call).  This  auto-connection
       can  fail  if C-lightning does not know how to contact the target node;
       see lightning-connect(7).  Once the transaction  is  confirmed,  normal
       channel  operations  may  begin.  Readiness  is  indicated by listpeers
       reporting a state of CHANNELD_NORMAL for the channel.

       id is the peer id obtained from connect.

       amount is the amount in satoshis taken from the internal wallet to fund
       the  channel. The string all can be used to specify all available funds
       (or 16777215 satoshi if more is available and large channels  were  not
       negotiated  with  the  peer). Otherwise, it is in satoshi precision; it
       can be a whole number, a whole number ending in  sat,  a  whole  number
       ending  in  000msat,  or  a number with 1 to 8 decimal places ending in
       btc. The value cannot be less than the dust  limit,  currently  set  to
       546, nor more than 16777215 satoshi (unless large channels were negoti-
       ated with the peer).

       feerate is an optional feerate used for the opening transaction and  as
       initial  feerate for commitment and HTLC transactions. It can be one of
       the strings urgent (aim for next block), normal (next 4 blocks  or  so)
       or slow (next 100 blocks or so) to use lightningd's internal estimates:
       normal is the default.

       Otherwise, feerate is a number, with an optional  suffix:  perkw  means
       the  number  is interpreted as satoshi-per-kilosipa (weight), and perkb
       means it is interpreted bitcoind-style as  satoshi-per-kilobyte.  Omit-
       ting the suffix is equivalent to perkb.

       announce  is  an  optional  flag that triggers whether to announce this
       channel or not. Defaults to true. An unannounced channel is  considered
       private.

       minconf specifies the minimum number of confirmations that used outputs
       should have. Default is 1.

       utxos specifies the utxos to be used to fund the channel, as  an  array
       of "txid:vout".

       push_msat is the amount of millisatoshis to push to the channel peer at
       open. Note that this is a gift to the peer -- these satoshis are  added
       to  the  initial  balance  of the peer at channel start and are largely
       unrecoverable once pushed.

       close_to is a Bitcoin address to which the channel funds should be sent
       to   on   close.   Only   valid   if   both   peers   have   negotiated
       option_upfront_shutdown_script.  Returns close_to set to closing script
       iff is negotiated.

       request_amt  is  an  amount  of  liquidity you'd like to lease from the
       peer.  If peer supports option_will_fund, indicates to them to  include
       this much liquidity into the channel. Must also pass in compact_lease.

       compact_lease is a compact represenation of the peer's expected channel
       lease terms. If the peer's terms don't match this set, we will fail  to
       open the channel.

       This  example  shows  how to use lightning-cli to open new channel with
       peer 03f...fc1 from one whole utxo bcc1...39c:0 (you can use  listfunds
       command to get txid and vout):

       lightning-cli -k fundchannel id=03f...fc1 amount=all feerate=normal utxos='["bcc1...39c:0"]'

RETURN VALUE
       On success, an object is returned, containing:

       · tx (hex): The raw transaction which funded the channel
       · txid (txid): The txid of the transaction which funded the channel
       · outnum  (u32):  The  0-based output index showing which output funded
         the channel
       · channel_id (hex): The channel_id of the resulting channel (always  64
         characters)
       · close_to  (hex,  optional):  The  raw scriptPubkey which mutual close
         will go to; only present if close_to parameter was specified and peer
         supports option_upfront_shutdown_script
       · mindepth  (u32, optional): Number of confirmations before we consider
         the channel active.

       The following error codes may occur: - -1: Catchall nonspecific  error.
       -  300:  The  maximum allowed funding amount is exceeded.  - 301: There
       are not enough funds in the internal wallet (including fees) to  create
       the  transaction.   - 302: The output amount is too small, and would be
       considered dust.   -  303:  Broadcasting  of  the  funding  transaction
       failed, the internal call to bitcoin-cli returned with an error.

       Failure may also occur if lightningd and the peer cannot agree on chan-
       nel parameters (funding limits, channel reserves, fees, etc.).

SEE ALSO
       lightning-connect(7),  lightning-listfunds(),   lightning-listpeers(7),
       lightning-feerates(7), lightning-multifundchannel(7)

RESOURCES
       Main web site: https://github.com/ElementsProject/lightning

Core Lightning 0.12.1                                 LIGHTNING-FUNDCHANNEL(7)

As we are running the nodes regtest and we have access to both, we also can get the id of the node l2 using the sub-command getinfo like this:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l2-cli getinfo | jq .id -r031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435

Now as we have no funds in the internal wallet of the node l1 we can generate our first error 300 by trying to open a channel with the node l2 with a total amount of 1000 sat:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli fundchannel 031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435 1000
{
   "code": 301,
   "message": "Could not afford 1000sat using all 0 available UTXOs: 1054sat short"
}

To follow our tour of the sub-command fundchannel we need to fund the internal wallet of the node l1.

Since our Bitcoin default wallet is empty as we can see in the following snippet:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest -rpcwallet=default getbalance
0.00000000

we must generate a new address for our Bitcoin default wallet like this

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest -rpcwallet=default getnewaddress
bcrt1qq406v4xa9n8gg0htlvqe6fs3um7r4mpfv00vhh

and mine 100 blocks on regtest (in order to be able to spend the block reward of 50 bitcoins of the coinbase transaction from block 1):

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest generatetoaddress 100 bcrt1qq406v4xa9n8gg0htlvqe6fs3um7r4mpfv00vhh > /dev/null
◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest -rpcwallet=default getbalance
50.00000000

Now as we did in the LN Room #4, we generate a new bech32 address belonging to the wallet of the Lightning node l1 by running the following command:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli newaddr
{
   "bech32": "bcrt1qs2zpc3aqt9swws0e5mhhwzaxv7vuknq7r2y5p8"
}

Then we send 1 Bictoin to that address (and so to the wallet of the node l1) like this:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest -rpcwallet=default sendtoaddress bcrt1qs2zpc3aqt9swws0e5mhhwzaxv7vuknq7r2y5p8 1
fc12a30dfe0f10f57f960253c4eec5155d32381cea1020a50c144afecc68c97e

Now we check that the node l1 has no funds, neither in its internal wallet nor in an open channel:

If we check for the funds managed by the node l1, we that they are none:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli listfunds
{
   "outputs": [],
   "channels": []
}

This is normal because since we are running the chain regtest ourselves we have to mine 1 block to get that new transaction included in a block.

As we can see in the snippet below, we are still at the block 101.

Note: I don't know why the balance of the Bitcoin default wallet already takes into account the previous transaction in which we send 1 Bitcoin the wallet of the Lightning node l1! Please reach out to me if know why.

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest -getinfo
Chain: regtest
Blocks: 101
Headers: 101
Verification progress: 100.0000%
Difficulty: 4.656542373906925e-10

Network: in 0, out 0, total 0
Version: 230000
Time offset (s): 0
Proxies: n/a
Min tx relay fee rate (BTC/kvB): 0.00001000

Wallet: default
Keypool size: 4000
Transaction fee rate (-paytxfee) (BTC/kvB): 0.00000000

Balance: 48.99999859

Warnings:

So we continue by running the following command that mined 1 block on regtest and send the block reward to an address belonging to Bitcoin default wallet:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest generatetoaddress 1 bcrt1qq406v4xa9n8gg0htlvqe6fs3um7r4mpfv00vhh
[
  "5969c012ba56e4acd9111d504c142317397d42a37b65b2b761dcbb973d2520ff"
]

After waiting a few seconds (between 5 to 10), we observe that the internal wallet of the Lightning node l1 has been funded with 1 Bitcoin:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli listfunds
{
   "outputs": [
      {
         "txid": "fc12a30dfe0f10f57f960253c4eec5155d32381cea1020a50c144afecc68c97e",
         "output": 0,
         "amount_msat": 100000000000,
         "scriptpubkey": "001482841c47a05960e741f9a6ef770ba66799cb4c1e",
         "address": "bcrt1qs2zpc3aqt9swws0e5mhhwzaxv7vuknq7r2y5p8",
         "status": "confirmed",
         "blockheight": 102,
         "reserved": false
      }
   ],
   "channels": []
}

Let's remember that 546 sats is the minimum amount necessary to open a channel. So trying to open a channel with only 100 sats, as we do by running the following command, return an error:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli fundchannel 031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435 100
{
   "code": -32602,
   "message": "destinations: output would be dust: invalid token '{\"id\":\"031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435\",\"amount\":100}'"
}

Note: I don't know why the code error is not 302 as stated in the man page of the sub-command fundchannel. Please reach out to me if know why.

Let's remember that 16777215 sats is the maximum amount allowed to open a channel (in the case of non large channels, which is our case). So trying to open a channel with only 50000000 sats, as we do by running the following command, return the error 300:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli fundchannel 031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435 50000000
{
   "code": 300,
   "message": "Amount exceeded 16777215sat",
   "data": {
      "id": "031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435",
      "method": "fundchannel_start"
   }
}

Finally in that section, we open a channel from the node l1 to the node l2 with an amount of 1000000 sats by running the following command:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli fundchannel 031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435 1000000
{
   "tx": "020000000001017ec968ccfe4a140ca52010ea1c38325d15c5eec45302967ff5100ffe0da312fc0000000000fdffffff02269ee60500000000160014122a5be939582f3a68f9f8095e15bf32ef523a3740420f000000000022002077aea0a7e4512bb35ceddad8d8d35970c05fc8a586753ceffe5aeda8395a392302473044022010f41ae0d115e66d40c2a4cb4c237dcb3835c7d6065dfece9652cfca298f3713022004f89857cc5ed9113fae8a2dab049f46c8d5dd32ac31a4a8ee820d57e9d467420121031d8c26b84645d1a39a67bd5ae7b431a21a5ae8f02fe752c202b0c5c44a35a1f466000000",
   "txid": "b79411632b73b1cd17ef176c890f96117ebdd17cb3008cf6fe33fb40779630ca",
   "channel_id": "ca30967740fb33fef68c00b37cd1bd7e11960f896c17ef17cdb1732b631194b6",
   "outnum": 1
}

Since that transaction has not been including in a block on regtest yet, it appears as unconfirmed in the outputs of the node l1 and the channel state with the funding transaction being that unconfirmed transaction is CHANNELD_AWAITING_LOCKIN:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli listfunds
{
   "outputs": [
      {
         "txid": "b79411632b73b1cd17ef176c890f96117ebdd17cb3008cf6fe33fb40779630ca",
         "output": 0,
         "amount_msat": 98999846000,
         "scriptpubkey": "0014122a5be939582f3a68f9f8095e15bf32ef523a37",
         "address": "bcrt1qzg49h6fetqhn568elqy4u9dlxth4yw3hsr334m",
         "status": "unconfirmed",
         "reserved": false
      },
      {
         "txid": "fc12a30dfe0f10f57f960253c4eec5155d32381cea1020a50c144afecc68c97e",
         "output": 0,
         "amount_msat": 100000000000,
         "scriptpubkey": "001482841c47a05960e741f9a6ef770ba66799cb4c1e",
         "address": "bcrt1qs2zpc3aqt9swws0e5mhhwzaxv7vuknq7r2y5p8",
         "status": "confirmed",
         "blockheight": 102,
         "reserved": true,
         "reserved_to_block": 2118
      }
   ],
   "channels": [
      {
         "peer_id": "031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435",
         "connected": true,
         "state": "CHANNELD_AWAITING_LOCKIN",
         "our_amount_msat": 1000000000,
         "amount_msat": 1000000000,
         "funding_txid": "b79411632b73b1cd17ef176c890f96117ebdd17cb3008cf6fe33fb40779630ca",
         "funding_output": 1
      }
   ]
}

Looking the man page of the sub-command fundchannel, we can see that if we don't specify the minconf argument specifying the minimum number of confirmations that used outputs should have, the default value is 1.

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli help fundchannel
LIGHTNING-FUNDCHANNEL(7)                              LIGHTNING-FUNDCHANNEL(7)

NAME
       lightning-fundchannel -- Command for establishing a lightning channel

SYNOPSIS
       fundchannel   id   amount   [feerate]   [announce]   [minconf]  [utxos]
       [push_msat] [close_to] [request_amt] [compact_lease]

DESCRIPTION
       The fundchannel RPC command opens a payment channel with a peer by com-
       mitting  a funding transaction to the blockchain as defined in BOLT #2.
       If not already connected, fundchannel  will  automatically  attempt  to
       connect  if  C-lightning  knows  a way to contact the node (either from
       normal gossip, or from a previous connect call).  This  auto-connection
       can  fail  if C-lightning does not know how to contact the target node;
       see lightning-connect(7).  Once the transaction  is  confirmed,  normal
       channel  operations  may  begin.  Readiness  is  indicated by listpeers
       reporting a state of CHANNELD_NORMAL for the channel.

       id is the peer id obtained from connect.

       amount is the amount in satoshis taken from the internal wallet to fund
       the  channel. The string all can be used to specify all available funds
       (or 16777215 satoshi if more is available and large channels  were  not
       negotiated  with  the  peer). Otherwise, it is in satoshi precision; it
       can be a whole number, a whole number ending in  sat,  a  whole  number
       ending  in  000msat,  or  a number with 1 to 8 decimal places ending in
       btc. The value cannot be less than the dust  limit,  currently  set  to
       546, nor more than 16777215 satoshi (unless large channels were negoti-
       ated with the peer).

       feerate is an optional feerate used for the opening transaction and  as
       initial  feerate for commitment and HTLC transactions. It can be one of
       the strings urgent (aim for next block), normal (next 4 blocks  or  so)
       or slow (next 100 blocks or so) to use lightningd's internal estimates:
       normal is the default.

       Otherwise, feerate is a number, with an optional  suffix:  perkw  means
       the  number  is interpreted as satoshi-per-kilosipa (weight), and perkb
       means it is interpreted bitcoind-style as  satoshi-per-kilobyte.  Omit-
       ting the suffix is equivalent to perkb.

       announce  is  an  optional  flag that triggers whether to announce this
       channel or not. Defaults to true. An unannounced channel is  considered
       private.

       minconf specifies the minimum number of confirmations that used outputs
       should have. Default is 1.

So we just have to mine 1 block on regtest to get our transaction confirmed and the channel opened as we can see by running the following commands. The status of the output passed from unconfirmed to confirmed and the state of the channel passed from CHANNELD_AWAITING_LOCKIN to CHANNELD_NORMAL:

◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ bitcoin-cli -regtest generatetoaddress 1 bcrt1qq406v4xa9n8gg0htlvqe6fs3um7r4mpfv00vhh
[
  "68f286d7d1d8400adedbed69aede247dd9e3563141eba48ad99ea1b84dafdc9c"
]
◉ tony@tony:~/lnroom/lightning:[git»(HEAD detached at v0.12.1)]
$ l1-cli listfunds
{
   "outputs": [
      {
         "txid": "b79411632b73b1cd17ef176c890f96117ebdd17cb3008cf6fe33fb40779630ca",
         "output": 0,
         "amount_msat": 98999846000,
         "scriptpubkey": "0014122a5be939582f3a68f9f8095e15bf32ef523a37",
         "address": "bcrt1qzg49h6fetqhn568elqy4u9dlxth4yw3hsr334m",
         "status": "confirmed",
         "blockheight": 103,
         "reserved": false
      }
   ],
   "channels": [
      {
         "peer_id": "031b91258c2e469dc6cbc5e3f1b80a6de8b131a67bbafc661de6192d32ca16a435",
         "connected": true,
         "state": "CHANNELD_NORMAL",
         "short_channel_id": "103x1x1",
         "our_amount_msat": 1000000000,
         "amount_msat": 1000000000,
         "funding_txid": "b79411632b73b1cd17ef176c890f96117ebdd17cb3008cf6fe33fb40779630ca",
         "funding_output": 1
      }
   ]
}

This is what I wanted to do today with you. We've seen how to open a channel between 2 nodes running on regtest with CLN. In order to learn about the system we misused it to make it returns error messages.

I hope you enjoyed the video.

See you next time.