# C-lightning on the RaspiBlitz FAQ - [C-lightning official documentation](#c-lightning-official-documentation) - [Commands and aliases](#commands-and-aliases) - [Directories](#directories) - [Config file](#config-file) - [Default values](#default-values) - [All possible config settings](#all-possible-config-settings) - [Plug-ins](#plug-ins) - [General info](#general-info) - [Directories](#directories-1) - [Implemented plugins](#implemented-plugins) - [Add a custom plugin](#add-a-custom-plugin) - [CLBOSS](#clboss) - [Feeadjuster](#feeadjuster) - [Dual funded channels](#dual-funded-channels) - [Reading](#reading) - [Setting up](#setting-up) - [Open a dual funded channel](#open-a-dual-funded-channel) - [Fundchannel syntax](#fundchannel-syntax) - [Offers](#offers) - [About the feature bits](#about-the-feature-bits) - [Testnets](#testnets) - [Backups](#backups) - [Seed](#seed) - [Channel database](#channel-database) - [Recovery](#recovery) - [Script file help list](#script-file-help-list) ## C-lightning official documentation * https://lightning.readthedocs.io/ * the lightningd is built by deafult with ## Commands and aliases * Check if the C-lightning daemon is running: ``` sudo systemctl status lightningd ``` * Follow it's system output for debugging: ``` sudo journalctl -fu lightningd ``` * The logs can be accessed in the menu `SYSTEM` - `CLLOG` or with the alias: `cllog` * The frequently used commands are shortened with alisases. Check them with the command `alias`: ``` alias cl='sudo -u bitcoin /usr/local/bin/lightning-cli --conf=/home/bitcoin/.lightning/config' alias clconf='sudo nano /home/bitcoin/.lightning/config' alias cllog='sudo tail -n 30 -f /home/bitcoin/.lightning/bitcoin/cl.log' ``` ## Directories * All data is stored on the disk in: `/mnt/hdd/app-data/.lightningd` * and symlinked to: `/home/bitcoin/.lightningd` ## Config file * Edit in the menu `SYSTEM` - `CLNCONF` or use the alias `clconf` ### Default values * on the RaspiBlitz for mainnet ``` network=bitcoin announce-addr=127.0.0.1:9736 log-file=cl.log log-level=info plugin-dir=/home/bitcoin/cln-plugins-enabled # Tor settings proxy=127.0.0.1:9050 bind-addr=127.0.0.1:9736 addr=statictor:127.0.0.1:9051/torport=9736 always-use-proxy=true ``` ### All possible config settings * can be shown by running: `lightningd --help` * Place the settings in the config file without the `--` and restart lightningd ``` Usage: lightningd A bitcoin lightning daemon (default values shown for network: bitcoin). --conf= Specify configuration file --lightning-dir= Set base directory: network-specific subdirectory is under here (default: "/home/admin/.lightning") --network Select the network parameters (bitcoin, testnet, signet, regtest, litecoin or litecoin-testnet) (default: bitcoin) --mainnet Alias for --network=bitcoin --testnet Alias for --network=testnet --signet Alias for --network=signet --allow-deprecated-apis Enable deprecated options, JSONRPC commands, fields, etc. (default: true) --rpc-file Set JSON-RPC socket (or /dev/tty) (default: "lightning-rpc") --plugin Add a plugin to be run (can be used multiple times) --plugin-dir Add a directory to load plugins from (can be used multiple times) --clear-plugins Remove all plugins added before this option --disable-plugin Disable a particular plugin by filename/name --important-plugin Add an important plugin to be run (can be used multiple times). Die if the plugin dies. --always-use-proxy Use the proxy always (default: false) --daemon Run in the background, suppress stdout/stderr --wallet Location of the wallet database. --large-channels|--wumbo Allow channels larger than 0.16777215 BTC --experimental-dual-fund experimental: Advertise dual-funding and allow peers to establish channels via v2 channel open protocol. --experimental-onion-messages EXPERIMENTAL: enable send, receive and relay of onion messages --experimental-offers EXPERIMENTAL: enable send and receive of offers (also sets experimental-onion-messages) --experimental-shutdown-wrong-funding EXPERIMENTAL: allow shutdown with alternate txids --help|-h Print this message. --rgb RRGGBB hex color for node --alias Up to 32-byte alias for node --pid-file= Specify pid file (default: "/home/admin/.lightning/lightningd-bitcoin.pid") --ignore-fee-limits (DANGEROUS) allow peer to set any feerate (default: false) --watchtime-blocks Blocks before peer can unilaterally spend funds (default: 144) --max-locktime-blocks Maximum blocks funds may be locked for (default: 2016) --funding-confirms Confirmations required for funding transaction (default: 3) --cltv-delta Number of blocks for cltv_expiry_delta (default: 34) --cltv-final Number of blocks for final cltv_expiry (default: 18) --commit-time= Time after changes before sending out COMMIT (default: 10) --fee-base Millisatoshi minimum to charge for HTLC (default: 1000) --rescan Number of blocks to rescan from the current head, or absolute blockheight if negative (default: 15) --fee-per-satoshi Microsatoshi fee for every satoshi in HTLC (default: 10) --max-concurrent-htlcs Number of HTLCs one channel can handle concurrently. Should be between 1 and 483 (default: 30) --min-capacity-sat Minimum capacity in satoshis for accepting channels (default: 10000) --addr Set an IP address (v4 or v6) to listen on and announce to the network for incoming connections --bind-addr Set an IP address (v4 or v6) to listen on, but not announce --announce-addr Set an IP address (v4 or v6) or .onion v3 to announce, but not listen on --offline Start in offline-mode (do not automatically reconnect and do not accept incoming connections) --autolisten If true, listen on default port and announce if it seems to be a public interface (default: true) --proxy Set a socks v5 proxy IP address and port --tor-service-password Set a Tor hidden service password --experimental-accept-extra-tlv-types Comma separated list of extra TLV types to accept. --disable-dns Disable DNS lookups of peers --encrypted-hsm Set the password to encrypt hsm_secret with. If no password is passed through command line, you will be prompted to enter it. --rpc-file-mode Set the file mode (permissions) for the JSON-RPC socket (default: "0600") --force-feerates Set testnet/regtest feerates in sats perkw, opening/mutual_close/unlateral_close/delayed_to_us/htlc_resolution/penalty: if fewer specified, last number applies to remainder --subdaemon Arg specified as SUBDAEMON:PATH. Specifies an alternate subdaemon binary. If the supplied path is relative the subdaemon binary is found in the working directory. This option may be specified multiple times. For example, --subdaemon=hsmd:remote_signer would use a hypothetical remote signing subdaemon. --log-level log level (io, debug, info, unusual, broken) [:prefix] (default: info) --log-timestamps prefix log messages with timestamp (default: true) --log-prefix log prefix (default: lightningd) --log-file= log to file instead of stdout --version|-V Print version and exit --autocleaninvoice-cycle Perform cleanup of expired invoices every given seconds, or do not autoclean if 0 --autocleaninvoice-expired-by If expired invoice autoclean enabled, invoices that have expired for at least this given seconds are cleaned --fetchinvoice-noconnect Don't try to connect directly to fetch an invoice. --bitcoin-datadir -datadir arg for bitcoin-cli --bitcoin-cli bitcoin-cli pathname --bitcoin-rpcuser bitcoind RPC username --bitcoin-rpcpassword bitcoind RPC password --bitcoin-rpcconnect bitcoind RPC host to connect to --bitcoin-rpcport bitcoind RPC host's port --bitcoin-retry-timeout how long to keep retrying to contact bitcoind before fatally exiting --commit-fee Percentage of fee to request for their commitment --funder-policy Policy to use for dual-funding requests. [match, available, fixed] --funder-policy-mod Percent to apply policy at (match/available); or amount to fund (fixed) --funder-min-their-funding Minimum funding peer must open with to activate our policy --funder-max-their-funding Maximum funding peer may open with to activate our policy --funder-per-channel-min Minimum funding we'll add to a channel. If we can't meet this, we don't fund --funder-per-channel-max Maximum funding we'll add to a channel. We cap all contributions to this --funder-reserve-tank Amount of funds we'll always leave available. --funder-fuzz-percent Percent to fuzz the policy contribution by. Defaults to 5%. Max is 100% --funder-fund-probability Percent of requests to consider. Defaults to 100%. Setting to 0% will disable dual-funding --funder-lease-requests-only Only fund lease requests. Defaults to true if channel lease rates are being advertised --lease-fee-base-msat Channel lease rates, base fee for leased funds, in satoshi. --lease-fee-basis Channel lease rates, basis charged for leased funds (per 10,000 satoshi.) --lease-funding-weight Channel lease rates, weight we'll ask opening peer to pay for in funding transaction --channel-fee-max-base-msat Channel lease rates, maximum channel fee base we'll charge for funds routed through a leased channel. --channel-fee-max-proportional-thousandths Channel lease rates, maximum proportional fee (in thousandths, or ppt) we'll charge for funds routed through a leased channel. Note: 1ppt = 1,000ppm --disable-mpp Disable multi-part payments. ``` ## Plug-ins ### General info * https://lightning.readthedocs.io/PLUGINS.html#a-day-in-the-life-of-a-plugin * https://github.com/lightningd/plugins/ ### Directories * The plugins are installed to: `/home/bitcoin/cl-plugins-available` * and symlinked to: `/home/bitcoin/cl-plugins-enabled` * All plugins in the `/home/bitcoin/cl-plugins-enabled` directory are loaded automatically as set in the config file: `/home/bitcoin/.lightningd/config` ### Implemented plugins * summary * sparko * clboss ### Add a custom plugin * The easiest way is to place the plugin in the `/home/bitcoin/cl-plugins-enabled` directory and start with ``` lightnign-cli plugin start /home/bitcoin/cl-plugins-enabled/PLUGIN_NAME ``` or restart C-ligthning with: ``` sudo systemctl restart lightningd ``` to have it loaded automatically. From that directory it will load auomatically after restarts. To just load it run it once store in: `/home/bitcoin/cl-plugins-available/` ### CLBOSS A plugin for automatic LN node management. CLBOSS only requires to have funds deposited to the onchain wallet of C-lightning. The recommended amount to start is ~ 10 million satoshis (0.1 BTC). It does automatically: * generate outbound capacity - opens channels * generate inbound capacity - submarine swaps through the boltz.exchange API * aware of onchain fees and mempool through c-lightning and makes transactions when fees are low * manages rebalancing - performs probing * closes bad channels (inactive or low traffic) - this function needs to activated manually Overall it is a tool which makes users able to send and receive lightning payments with minimal interaction, basically setting up a routing node by itself. The transactions made by CLBOSS does cost money and running it requires a fair amount of trust in the (fully open-source - MIT) code. Neither the CLBOSS nor the RaspiBlitz developers can take resposibility for lost sats, use at your own discretion! * Activate it in the menu - `SETTINGS` - `-CL CLBOSS` * Discussion: https://github.com/rootzoll/raspiblitz/issues/2490 * Advanced usage https://github.com/ZmnSCPxj/clboss#clboss-status * Stopping CLBOSS will leave the node in the last state. No channels will be closed or funds removed when CLBOSS is uninstalled. ### Feeadjuster * Install: * to set the default fees in the config add: ``` fee-base=BASEFEE_IN_MILLISATS fee-per-satoshi=PPM_FEE_IN_SATS ``` * more options for the feeadjuster to be set in the c-lightning config can be seen in the [code](https://github.com/lightningd/plugins/blob/c16c564c2c5549b8f7236815490260c49e9e9bf4/feeadjuster/feeadjuster.py#L318): ``` plugin.add_option( "feeadjuster-deactivate-fuzz", False, "Deactivate update threshold randomization and hysterisis.", "flag" ) plugin.add_option( "feeadjuster-deactivate-fee-update", False, "Deactivate automatic fee updates for forward events.", "flag" ) plugin.add_option( "feeadjuster-threshold", "0.05", "Relative channel balance delta at which to trigger an update. Default 0.05 means 5%. " "Note: it's also fuzzed by 1.5%", "string" ) plugin.add_option( "feeadjuster-threshold-abs", "0.001btc", "Absolute channel balance delta at which to always trigger an update. " "Note: it's also fuzzed by 1.5%", "string" ) plugin.add_option( "feeadjuster-enough-liquidity", "0msat", "Beyond this liquidity do not adjust fees. " "This also modifies the fee curve to achieve having this amount of liquidity. " "Default: '0msat' (turned off).", "string" ) plugin.add_option( "feeadjuster-adjustment-method", "default", "Adjustment method to calculate channel fee" "Can be 'default', 'soft' for less difference or 'hard' for higher difference" "string" ) plugin.add_option( "feeadjuster-imbalance", "0.5", "Ratio at which channel imbalance the feeadjuster should start acting. " "Default: 0.5 (always). Set higher or lower values to limit feeadjuster's " "activity to more imbalanced channels. " "E.g. 0.3 for '70/30'% or 0.6 for '40/60'%.", "string" ) plugin.add_option( "feeadjuster-feestrategy", "global", "Sets the per channel fee selection strategy. " "Can be 'global' to use global config or default values, " "or 'median' to use the median fees from peers of peer " "Default: 'global'.", "string" ``` * start the feeadjuster ``` cl plugin start /home/bitcoin/cl-plugins-available/plugins/feeadjuster/feeadjuster.py ``` * stop (best to run only periodically) ``` cl plugin stop /home/bitcoin/cl-plugins-available/plugins/feeadjuster/feeadjuster.py ``` * Can use menu - `CL` - `SUEZ` to visualize the channel balances and fee settings * check the list of base fees ``` cl listpeers | grep fee_base_msat ``` * check the list of proportional fees ``` cl listpeers | grep fee_proportional_millionths ``` * set the fees to the defaults ``` cl setchannelfee all ``` ### Dual funded channels #### Reading * https://medium.com/blockstream/c-lightning-opens-first-dual-funded-mainnet-lightning-channel-ada6b32a527c * https://medium.com/blockstream/setting-up-liquidity-ads-in-c-lightning-54e4c59c091d * https://twitter.com/niftynei/status/1389328732377255938 * lightning-rfc PR: https://github.com/lightningnetwork/lightning-rfc/pull/851/files * represented by the feature bits 28/29 #### Setting up * activate the feature on your node: Type: `clconf` or use the menu `SYSTEM` - `CLCONF`. Add the line: ``` experimental-dual-fund ``` Save and restart C-lightning. * set up a liquidity ad: ``` lightning-cli funderupdate -k policy=match policy_mod=100 ``` or set in the config for example - see the meaning of each line in https://medium.com/blockstream/setting-up-liquidity-ads-in-c-lightning-54e4c59c091d : ``` experimental-dual-fund funder-policy=match funder-policy-mod=100 lease-fee-base-msat=500sat lease-fee-basis=50 channel-fee-max-base-msat=100sat channel-fee-max-proportional-thousandths=2 ``` * check the settings used currently on your node: ``` lightning-cli funderupdate ``` * check your advertised settings (needs some minutes to appear): ``` lightning-cli listnodes $(lightning-cli getinfo | jq .id) ``` #### Open a dual funded channel * check if a node has onchain liquidity on offer: ``` lightning-cli listnodes nodeid ``` Example: ``` lightning-cli listnodes 02cca6c5c966fcf61d121e3a70e03a1cd9eeeea024b26ea666ce974d43b242e636 ``` * list all nodes known in the graph with active offers: ``` lightning-cli listnodes | grep option_will_fund -B20 -A7 ``` * note the node `id` and `compact_lease` * connect to the node ``` lightning-cli connect nodeID@IP_or.onion ``` #### Fundchannel syntax * the amount is the own funds in the wallet contributed use equal amounts to have a balanced channel from start the amounts can be specified in `sat` or `btc` ``` lightning-cli fundchannel -k id=NODE_ID amount=OWN_AMOUNTsat request_amt=PEER_CONTRIBUTION_AMOUNTsat compact_lease=COMPACT_LEASE ``` It can fail if the offer changed or there are not enough funds available on either side. * open a dual funded channel with a chosen utxo and miner feerate list the utxo-s with `lightning-cli listfunds`, can list multiple the feerate is in `perkb` by default, e.g. use 1000 for 1 sat/byte ``` lightning-cli fundchannel feerate=PERKB_FEERATE utxos='["TRANSACTION_ID:INDDEX_NUMBER"]' -kid=NODE_ID amount=OWN_AMOUNTsat request_amt=PEER_CONTRIBUTION_AMOUNTsat compact_lease=COMPACT_LEASE ``` ### Offers * Details at bolt12.org * Create an offer to receive payments: https://lightning.readthedocs.io/lightning-offer.7.html ``` lightning-cli offer amount description [vendor] [label] [quantity_min] [quantity_max] [absolute_expiry] [recurrence] [recurrence_base] [recurrence_paywindow] [recurrence_limit] [single_use] ``` * Example: Create a reusable offer which can be paid with any amount for LN tips using a fixed string. ``` lightning-cli offer any tip ``` * Create an offer to send payments: https://lightning.readthedocs.io/lightning-offerout.7.html ``` lightning-cli offerout amount description [vendor] [label] [absolute_expiry] [refund_for] ``` * Fetch an invoice to pay an offer: https://lightning.readthedocs.io/lightning-fetchinvoice.7.html Will need at least one peer which supports onion the messages. For example: ``` lightning-cli connect 024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605@128.199.202.168:9735 ``` * Then use the command to fetch the BOLT12 invoice: ``` lightning-cli fetchinvoice offer [msatoshi] [quantity] [recurrence_counter] [recurrence_start] [recurrence_label] [timeout] [payer_note] ``` * decode a BOLT12 invoice: ``` lightning-cli decode bolt12_invoice ``` * pay a a BOLT12 invoice: Will need to pay through a peer which supports the onion messages which means you need at least one channel with such a node. ``` lightning-cli pay bolt12_invoice ``` * see if there is a new invoice is paid with: ``` lightning-cli listinvoices ``` The `pay_index` will increase as the offer gets reused. ### About the feature bits * https://bitcoin.stackexchange.com/questions/107484/how-can-i-decode-the-feature-string-of-a-lightning-node-with-bolt-9 * Convert the hex number from `lightning-cli listpeers` to binary: https://www.binaryhexconverter.com/hex-to-binary-converter and count the position of the bits from the right. ## Testnets * for testnet and signet there are prefixes `t` and `s` used for the aliases, daemons and their own plugin directory names. * Testnet ``` # alias: tcl | tclconf | tcllog # daemon service name: tlightningd # config file: /home/bitcoin/.lightningd/testnet/config # plugin directory: /home/bitcoin/tcl-plugins-enabled ``` * Signet ``` # aliases: scl | sclconf | scllog # daemon service name: slightningd # config file: /home/bitcoin/.lightningd/signet/config # plugin directory: /home/bitcoin/scl-plugins-enabled ``` ## Backups * https://lightning.readthedocs.io/FAQ.html#how-to-backup-my-wallet * General details: https://lightning.readthedocs.io/BACKUP.html ### Seed - ### Channel database * ### Recovery * https://lightning.readthedocs.io/FAQ.html#database-corruption-channel-state-lost * https://lightning.readthedocs.io/FAQ.html#loss ## Script file help list ``` # generate a list of help texts on a RaspiBlitz: cd /home/admin/config.scripts/ ls cl*.sh > clScriptList.txt sed -i "s#cl#./cl#g" clScriptList.txt sed -i "s#.sh#.sh -h#g" clScriptList.txt bash -x clScriptList.txt rm clScriptList.txt ``` ``` + ./cl.backup.sh -h --------------------------------------------------- CL RESCUE FILE (tar.gz of complete cl directory) --------------------------------------------------- cl.backup.sh cl-export cl.backup.sh cl-export-gui cl.backup.sh cl-import [file] cl.backup.sh cl-import-gui [setup|production] [?resultfile] --------------------------------------------------- SEED WORDS --------------------------------------------------- cl.backup.sh seed-export-gui [lndseeddata] cl.backup.sh seed-import-gui [resultfile] + ./cl.hsmtool.sh -h Create new wallet or import seed Unlock/lock, encrypt, decrypt, set autounlock or change password for the hsm_secret Usage: Create new wallet: cl.hsmtool.sh [new] [mainnet|testnet|signet] [?seedPassword] cl.hsmtool.sh [new-force] [mainnet|testnet|signet] [?seedPassword] There will be no seedPassword(passphrase) used by default new-force will delete any old wallet and will work without dialog cl.hsmtool.sh [seed] [mainnet|testnet|signet] ["space-separated-seed-words"] [?seedPassword] cl.hsmtool.sh [seed-force] [mainnet|testnet|signet] ["space-separated-seed-words"] [?seedPassword] The new hsm_secret will be not encrypted if no NewPassword is given seed-force will delete any old wallet and will work without dialog cl.hsmtool.sh [unlock|lock] cl.hsmtool.sh [encrypt|decrypt] cl.hsmtool.sh [autounlock-on|autounlock-off] cl.hsmtool.sh [change-password] + ./cl.install-service.sh -h Script to set up or update the C-lightning systemd service Usage: /home/admin/config.scripts/cl.install-service.sh + ./cl.install.sh -h C-lightning install script The default version is: v0.10.1 Setting up on mainnet unless otherwise specified mainnet / testnet / signet instances can run parallel Usage: cl.install.sh on cl.install.sh off cl.install.sh [update |testPR ] cl.install.sh display-seed + ./cl-plugin.backup.sh -h Install the backup plugin for C-lightning Replicates the lightningd.sqlite3 database on the SDcard Usage: cl-plugin.backup.sh [on|off] [testnet|mainnet|signet] cl-plugin.backup.sh [restore] [testnet|mainnet|signet] [force] cl-plugin.backup.sh [backup-compact] [testnet|mainnet|signet] https://github.com/lightningd/plugins/tree/master/backup + ./cl-plugin.clboss.sh -h Install or remove the CLBOSS C-lightning plugin version: v0.10 Usage: cl-plugin.clboss.sh [on|off] [testnet|mainnet|signet] + ./cl-plugin.sparko.sh -h Install, remove, connect or get info about the Sparko plugin for C-lightning version: v2.7 Usage: cl-plugin.sparko.sh [on|off|menu|connect] [testnet|mainnet|signet] + ./cl-plugin.standard-python.sh -h Install and show the output of the chosen plugin for C-lightning Usage: cl-plugin.standard-python.sh on [plugin-name] [testnet|mainnet|signet] [runonce] tested plugins: summary | helpme | feeadjuster find more at: https://github.com/lightningd/plugins + ./cl-plugin.summary.sh -h Install and show the output if the summary plugin for C-lightning Usage: cl-plugin.summary.sh [testnet|mainnet|signet] [runonce] + ./cl.rest.sh -h C-lightning-REST install script The default version is: v0.5.1 mainnet | testnet | signet instances can run parallel The same macaroon and certs will be used for the parallel networks Usage: cl.rest.sh [on|off|connect] + ./cl.setname.sh -h Config script to set the alias of the C-lightning node cl.setname.sh [mainnet|testnet|signet] [?newName] ```