└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # CLN Cheatsheet :zap: :desktop_computer: 2 | 3 | ## Table of contents 4 | 5 | 1. [Node administration](#node-administration) 6 | 1. [Start your CLN node](#start-your-cln-node-daemon) 7 | 2. [Show your node's info](#show-your-nodes-info) 8 | 3. [Backups](#backups) 9 | 4. [Stop your CLN node](#stop-your-cln-node) 10 | 2. [On-chain wallet management](#on-chain-wallet-management) 11 | 1. [Generate a new on-chain address](#generate-a-new-on-chain-address-for-your-cln-wallet) 12 | 2. [Send an on-chain payment](#spend-bitcoin-from-your-on-chain-cln-wallet) 13 | 3. [Spend bitcoin from your on-chain CLN wallet to many outputs in a single transaction](#spend-bitcoin-from-your-on-chain-cln-wallet-to-many-outputs-in-a-single-transaction) 14 | 4. [List details of your on-chain transactions](#list-details-of-your-on-chain-transactions) 15 | 5. [Spend specific UTXOs](#spend-specific-utxos) 16 | 3. [Channel management](#channel-management) 17 | 1. [Connect to a Lightning peer](#connect-to-a-lightning-peer) 18 | 2. [Disconnect from a Lightning peer](#disconnect-from-a-lightning-peer) 19 | 3. [Force disconnect from a Lightning peer](#force-disconnect-from-a-lightning-peer) 20 | 4. [Open a channel to a connected peer](#open-a-channel-to-a-connected-peer) 21 | 5. [Open multiple channels in one transaction](#open-multiple-channels-in-one-transaction) 22 | 6. [Open a dual funded channel](#open-a-dual-funded-channel) 23 | 7. [Close a channel](#close-a-channel) 24 | 4. [Lightning Payments](#lightning-payments) 25 | 1. [Pay an invoice](#pay-an-invoice) 26 | 2. [Pay an invoice using a specific route](#pay-an-invoice-using-a-specific-route) 27 | 3. [Decode an invoice](#decode-an-invoice) 28 | 4. [Create an invoice](#create-an-invoice) 29 | 5. [List invoices created by your node](#list-invoices-created-by-your-node) 30 | 6. [Create a BOLT12 offer](#create-a-bolt12-offer) 31 | 7. [List your offers](#list-your-offers) 32 | 8. [Find a route from your node to a fellow Lightning peer](#find-a-route-from-your-node-to-a-fellow-lightning-peer) 33 | 5. [Swaps](#swaps) 34 | 1. [Installing Peerswap](#installing-peerswap) 35 | 2. [Swap out](#swap-out) 36 | 3. [Swap in](#swap-in) 37 | 4. [Check L-BTC balance](#check-l-btc-balance) 38 | 5. [List peers running PeerSwap](#list-peers-running-peerswap) 39 | 6. [Add peer to swap whitelist](#add-peer-to-swap-whitelist) 40 | 6. [Bookkeeping](#bookkeeping) 41 | 1. [Show all accounts and their balances](#show-all-accounts-and-their-balances) 42 | 2. [Dump all raw events, including on-chain fee updates](#dump-all-raw-events-including-on-chain-fee-updates) 43 | 3. [Show the on-chain footprint of an account](#show-the-on-chain-footprint-of-an-account) 44 | 4. [List every event that impacts income](#list-every-event-that-impacts-income) 45 | 5. [Dump income events into a CSV](#dump-income-events-into-a-csv) 46 | 6. [List stats on channel earnings](#list-stats-on-channel-earnings) 47 | 7. [Tips and Tricks](#tips-and-tricks) 48 | 1. [List all outgoing satoshis currently in channels](#list-all-outgoing-satoshis-currently-in-channels) 49 | 2. [List the total of your node's on-chain wallet outputs](#list-the-total-of-your-nodes-on-chain-wallet-outputs) 50 | 3. [Show the routing fees your node has earned](#show-the-routing-fees-your-node-has-earned) 51 | 4. [Calculate successful and failed payment forwards from last 100k attempts](#calculate-successful-and-failed-payment-forwards-from-last-100k-attempts) 52 | 5. [Calculate successful and failed payment forwards from last 10k attempts](#calculate-successful-and-failed-payment-forwards-from-last-10k-attempts) 53 | 6. [List PeerSwap channels and their balance scores](#list-peerswap-channels-and-their-balance-scores) 54 | 55 | 56 | ## Node administration 57 | ### Start your CLN node daemon 58 | `--network` specifies which network your CLN will be running on. Options are `mainnet`, `testnet`, `regtest`, `signet`. This can also be configured in your node's `config` file. 59 | ``` 60 | lightningd --network 61 | ``` 62 | 63 | ### Show your node's info 64 | Display an overview of your node, including public key, alias, number of channels and peers, the address you're announcing to the Lightning network, and more. 65 | 66 | ``` 67 | lightning-cli getinfo 68 | ``` 69 | Example output: 70 | ```json 71 | { 72 | "id": "0288c9aae9cabe5bbb100789b56f5f91706457612d9bd447a838eec209a3c24afe", 73 | "alias": "YELLOWIRON", 74 | "color": "0288c9", 75 | "num_peers": 2, 76 | "num_pending_channels": 0, 77 | "num_active_channels": 2, 78 | "num_inactive_channels": 0, 79 | "address": [], 80 | "binding": [ 81 | { 82 | "type": "ipv4", 83 | "address": "0.0.0.0", 84 | "port": 9736 85 | } 86 | ], 87 | "version": "v0.11.0.1-385-gbed0075", 88 | "blockheight": 100830, 89 | "network": "signet", 90 | "msatoshi_fees_collected": 0, 91 | "fees_collected_msat": "0msat", 92 | "lightning-dir": "/home/user/.lightning/signet", 93 | "our_features": { 94 | "init": "088000080a69a2", 95 | "node": "888000080a69a2", 96 | "channel": "", 97 | "invoice": "02000000024100" 98 | } 99 | } 100 | 101 | ``` 102 | ### Backups 103 | >**Warning** 104 | > Improperly backing up your CLN data could be **catastrophic**. Make sure you have at least a basic form of backups. 105 | 106 | It's critical for the `lightningd.sqlite3` database in your CLN data directory to be continually backed up as it contains the most up to date state for your payment channels. Restoring a backup with old incorrect state will cause problems. `hsm_secret` can be safely backed up once. 107 | 108 | CLN provides extensive [documentation]([https://github.com/ElementsProject/lightning/blob/master/doc/BACKUP.md](https://docs.corelightning.org/docs/backup-and-recovery)) for backing up critical data that your node creates. 109 | 110 | ### Stop your CLN node 111 | Shut your node down for maintenance or other tasks. 112 | ``` 113 | lightning-cli stop 114 | ``` 115 | 116 | ## On-chain wallet management 117 | ### Generate a new on-chain address for your CLN wallet 118 | Use this to receive bitcoins that you can use later on for opening payment channels. Address type can be `p2sh-segwit`, `bech32`, or `all` which generates both at once. 119 | ``` 120 | lightning-cli newaddr
121 | ``` 122 | 123 | ### Spend bitcoin from your on-chain CLN wallet 124 | Use this when you're ready to send bitcoin back to cold storage or if you need to send a payment on-chain. 125 | ``` 126 | lightning-cli withdraw 127 | ``` 128 | Example: 129 | ``` 130 | lightning-cli withdraw tb1q75ggprm38sl6p8x532p8jcce9fxm442axs54dy 100000 131 | ``` 132 | 133 | ### Spend bitcoin from your on-chain CLN wallet to many outputs in a single transaction 134 | Instead of making multiple individual transactions, use this to create a transaction paying many different addresses at once. 135 | ``` 136 | lightning-cli multiwithdraw {address1: amount},{address2: amount}, ... 137 | ``` 138 | Example: 139 | ``` 140 | lightning-cli multiwithdraw "[{\"tb1q75ggprm38sl6p8x532p8jcce9fxm442axs54dy\": 1000000}, {\"tb1qykpzvmukjlew3v3u5z5q346xkvetkpmx4ne3pq\": 2000000}]" 141 | ``` 142 | 143 | ### List details of your on-chain transactions 144 | 145 | ``` 146 | lightning-cli listtransactions 147 | ``` 148 | 149 | ### Spend specific UTXOs 150 | 151 | ``` 152 | lightning-cli withdraw -k destination=
satoshi= feerate=perkb minconf=0 utxos='["txid:index"]' 153 | ``` 154 | Example: 155 | ``` 156 | lightning-cli withdraw -k destination=bc1q7tfayt5urfy9sulu9wcjn3hm4tj0vxsntupz3a satoshi=1000000 feerate=80000perkb minconf=0 utxos='["9245a9fc09ada2b1709d6f83ed2fa0875c91996a4c81eb6a03e84946f13c1042:0"]' 157 | ``` 158 | 159 | ## Channel management 160 | ### Connect to a Lightning peer 161 | Connect your CLN node to a Lightning peer to begin downloading gossip data and in preparation of opening a payment channel. 162 | ``` 163 | lightning-cli connect 164 | ``` 165 | Example: 166 | ``` 167 | lightning-cli connect 0288c9aae9cabe5bbb100789b56f5f91706457612d9bd447a838eec209a3c24afe 168 | ``` 169 | 170 | ### Disconnect from a Lightning peer 171 | ``` 172 | lightning-cli disconnect 173 | ``` 174 | 175 | ### Force disconnect from a Lightning peer 176 | Occasionally you may need to force your CLN node to disconnect from a peer due to a bug between Lightning implementations or other reasons. Simply pass `true` to the `disconnect` after the node id to force a disconnect. CLN will then automatically try to reconnect. 177 | 178 | ``` 179 | lightning-cli disconnect true 180 | ``` 181 | 182 | ### Open a channel to a connected peer 183 | ``` 184 | lightning-cli fundchannel 185 | ``` 186 | 187 | ### Open multiple channels in one transaction 188 | ``` 189 | lightning-cli multifundchannel 190 | ``` 191 | 192 | ### Open a dual funded channel 193 | >**Note**: This requires `--experimental-dual-fund` to be enabled. 194 | > Learn more about [dual funded channels](https://medium.com/blockstream/setting-up-liquidity-ads-in-c-lightning-54e4c59c091d). 195 | 196 | First your need to find nodes that offer dual funding 197 | ``` 198 | lightning-cli listnodes | jq '.nodes[] | select(.option_will_fund != null)' 199 | ``` 200 | 201 | Open a dual funded channel of total size Z, where we contribute amount X and the remote peer amount Y. The channel open operation is a collaborative transactions between both peers (aka coinjoin). The amount we contribute will be our initial Outbound liquidity (=spending capacity) of the channel, while the requested amount from the peer will be our Inbound liquidity (=receiving capacity). 202 | ``` 203 | lightning-cli fundchannel -k id= amount= request_amt= compact_lease= 204 | ``` 205 | 206 | We can also open a dual funded channel by selecting whole utxos, to avoid having any change outputs. 207 | ``` 208 | lightning-cli fundchannel -k id= amount=all request_amt= compact_lease= utxos='["c8afe317789f3ecbd52893d2ac08be7499486df5a03c95ad063e395e931eb50a:1", ":"]' 209 | ``` 210 | 211 | ### Close a channel 212 | Attempt to coordinate a mutual channel close with the specified peer. 213 | ``` 214 | lightning-cli close 215 | ``` 216 | 217 | ### Force close a channel 218 | >**Warning**: Force closing a channel will lock up your on-chain funds for a period of time. 219 | 220 | Broadcast a unilateral close transaction on-chain. The third argument is the number of seconds your CLN node will wait before force closing. The default is two days (172800 seconds). 221 | ``` 222 | lightning-cli close 223 | ``` 224 | **When will funds be available after a unilateral close?** credit: Warren Togami 225 | 226 | Say your peer has been offline for 2+ weeks and you want to unilateral close the channel. The CSV timeout after which the funds are available to claim is typically 144 blocks for CLN. LND can be up to 2016 blocks depending on the channel capacity. 227 | 228 | ``` 229 | $ lightning-cli listpeers 230 | # Find the txid of the unilateral close transaction then scroll down a bit. 231 | 232 | "status": [ 233 | "CHANNELD_NORMAL:Reconnected, and reestablished.", 234 | "ONCHAIN:Tracking our own unilateral close", 235 | "ONCHAIN:3 outputs unresolved: in 139 blocks will spend DELAYED_OUTPUT_TO_US (53206ed042255fb0fae53c1fd0805832ff80869383cbddec1074965eaf3d7888:0) using OUR_DELAYED_RETURN_TO_WALLET" 236 | ], 237 | ``` 238 | 239 | ## Lightning Payments 240 | ### Pay an invoice 241 | >**Note**: If `--experimental-offers` is enabled, `pay` can also pay BOLT12 offers 242 | 243 | Attempt to pay a BOLT11 invoice. 244 | ``` 245 | lightning-cli pay 246 | ``` 247 | 248 | ### Pay an invoice using a specific route 249 | ``` 250 | lightning-cli sendpay 251 | ``` 252 | 253 | ### Decode an invoice 254 | ``` 255 | lightning-cli decode 256 | ``` 257 | 258 | ### Create an invoice 259 | ``` 260 | lightning-cli invoice 261 | ``` 262 | 263 | ### List invoices created by your node 264 | This is useful for keeping track of the invoices you've created and seeing which ones have been paid or not. 265 | ``` 266 | lightning-cli listinvoices 267 | ``` 268 | 269 | ### Create a BOLT12 offer 270 | BOLT12 is a proposed new method for payments on the Lightning network that provides a list of improvements over BOLT11 invoices. Read more at bolt12.org 271 | ``` 272 | lightning-cli offer 273 | ``` 274 | 275 | ### List your offers 276 | ``` 277 | lightning-cli listoffers 278 | ``` 279 | 280 | ### Find a route from your node to a fellow Lightning peer 281 | ``` 282 | lightning-cli getroute 283 | ``` 284 | ## Swaps 285 | Lightning payment channels periodically need to be rebalanced in order for payments to route successfully. There are a few ways to balance a channel ranging from circular payments within the Lightning network itself, to swapping on-chain bitcoin with off-chain Lightning bitcoin, or even swapping off-chain Lightning bitcoin with off-chain Liquid bitcoin (L-BTC) on the Liquid Network. 286 | 287 | [PeerSwap](https://peerswap.dev) is a CLN plugin and LND daemon that enables swapping. 288 | 289 | ### Installing PeerSwap 290 | PeerSwap is available for both CLN and LND implementations. Follow the install guide for [CLN](https://github.com/ElementsProject/peerswap/blob/master/docs/setup_cln.md) or [LND](https://github.com/ElementsProject/peerswap/blob/master/docs/setup_lnd.md). 291 | 292 | ### Swap out 293 | Swap outs push sats to your peer, who in turn sends onchain coins back. This results in more inbound liquidity for that channel. 294 | ``` 295 | $ lightning-cli peerswap-swap-out 296 | ``` 297 | 298 | ### Swap in 299 | Swap ins push sats to your side of the channel, and you send onchain coins in exchange. This results in more outbound liquidity for that channel. 300 | ``` 301 | $ lightning-cli peerswap-swap-in 302 | ``` 303 | 304 | ### Check L-BTC balance 305 | ``` 306 | $ lightning-cli peerswap-lbtc-getbalance 307 | ``` 308 | 309 | ### List peers running PeerSwap 310 | ``` 311 | $ lightning-cli peerswap-listpeers 312 | ``` 313 | 314 | ### Add peer to swap whitelist 315 | ``` 316 | $ lightning-cli peerswap-addpeer 317 | ``` 318 | 319 | 320 | ## Bookkeeping 321 | New in [CLN v0.12.0](https://blog.blockstream.com/core-lightning-v0-12-0/) is the `bookkeeper` plugin. This new plugin helps you keep track of how your satoshis are shuffled around in your open channels. Useful for accounting! The `bookkeeper` plugin refers to channels as "accounts" and forwarded payments, channel open / close activity, etc. are referred to as "events". 322 | 323 | ### Show all accounts and their balances 324 | ``` 325 | lightning-cli bkpr-listbalances 326 | ``` 327 | 328 | ### Dump all raw events, including on-chain fee updates 329 | ``` 330 | lightning-cli bkpr-listaccountevents 331 | ``` 332 | 333 | ### Show the on-chain footprint of an account 334 | ``` 335 | lightning-cli bkpr-inspect 336 | ``` 337 | 338 | ### List every event that impacts income 339 | ``` 340 | lightning-cli bkpr-listincome 341 | ``` 342 | 343 | ### Dump income events into a CSV 344 | ``` 345 | lightning-cli bkpr-dumpincomecsv 346 | ``` 347 | 348 | ### List stats on channel earnings 349 | ``` 350 | lightning-cli bkpr-channelsapy 351 | ``` 352 | 353 | 354 | ## Tips and Tricks 355 | 356 | ### List all outgoing satoshis currently in channels 357 | ``` 358 | lightning-cli listfunds | jq '[.channels[].our_amount_msat] | add / 1000' 359 | ``` 360 | 361 | ### List the total of your node's on-chain wallet outputs 362 | ``` 363 | lightning-cli listfunds | jq '[.outputs[].amount_msat] | add / 1000' 364 | ``` 365 | 366 | ### Show the routing fees your node has earned 367 | ``` 368 | lightning-cli getinfo | jq '.fees_collected_msat / 1000' 369 | ``` 370 | 371 | ### Calculate successful and failed payment forwards from last 100k attempts 372 | Credit: fiatjaf 373 | ``` 374 | lightning-cli listforwards | jq '.forwards[-100000:] | map(.status) | reduce .[] as $status ({}; .[$status] = (.[$status] // 0) + 1)' 375 | 376 | ``` 377 | 378 | ### Calculate successful and failed payment forwards from last 10k attempts 379 | Credit: fiatjaf 380 | ``` 381 | lightning-cli listforwards | jq '.forwards[-10000:] | map(.status) | reduce .[] as $status ({}; .[$status] = (.[$status] // 0) + 1)' 382 | ``` 383 | ### List PeerSwap channels and their balance scores 384 | Credit: tsjk 385 | ``` 386 | lightning-cli peerswap-listpeers | jq -r '[.[].channels[] | .balance_score += 100 * (1 - (2 * (.5 - (.local_balance / (.local_balance + .remote_balance))) | fabs))] | sort_by(.balance_score)' 387 | ``` 388 | --------------------------------------------------------------------------------