LIGHTNING-SETCHANNEL(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💅 setchannel — like, the manual page for `lightning-setchannel(7)` ✨

okay bestie, buckle up — this is lightning-setchannel(7) and it's genuinely one of the most useful little gremlins in the whole Lightning toolbox. it's the command that lets you go "actually, this channel charges these fees, thank you very much" 🎀

✨ NAME ✨

setchannel — the command for configuring fees and the HTLC range that get advertized for a channel. yes, that's how the original spells it, we love a quirky spelling era 🫶

🌸 SYNOPSIS 🌸

setchannel id [feebase] [feeppm] [htlcmin] [htlcmax] [enforcedelay]
           [ignorefeelimits]

everything in brackets is optional, everything else is not, no cap 💅

🦋 DESCRIPTION 🦋

so the setchannel RPC command sets channel-specific routing fees, plus htlc_minimum_msat or htlc_maximum_msat as defined in BOLT #7. iconic behavior honestly.

the channel has to be in normal or awaiting state, which you can verify by checking listpeers — it'll report a state of CHANNELD_NORMAL or CHANNELD_AWAITING_LOCKIN for the channel. no state, no service, sorry bestie 😭

these changes (for a public channel) will get broadcast to the rest of the network. though — heads up — many nodes limit the rate of such changes they'll accept: we allow 2 a day, with a few extra occasionally. so like, don't spam it, it's giving rate limit energy 🙈

id (string) — should contain a scid (short channel ID), channel id or peerid (pubkey) of the channel to be modified. If id is set to all, the updates are applied to all channels in states CHANNELD_NORMAL, CHANNELD_AWAITING_LOCKIN or DUALOPEND_AWAITING_LOCKIN. If id is a peerid, all channels with the +peer in those states are changed. (yes, all is the main character here 👑)
feebase (msat, optional) — value in millisatoshi that is added as base fee to any routed payment: if omitted, it is unchanged. It can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places ending in sat, or a number with 1 to 11 decimal places ending in btc. so many formats, pick your fighter 🍓
feeppm (u32, optional) — value that is added proportionally per-millionths to any routed payment volume in satoshi. For example, if ppm is 1,000 and 1,000,000 satoshi is being routed through the channel, an proportional fee of 1,000 satoshi is added, resulting in a 0.1% fee. math ate, honestly ✨
htlcmin (msat, optional) — value that limits how small an HTLC we will forward: if omitted, it is unchanged. It can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places ending in sat, or a number with 1 to 11 decimal places ending in btc. Note that the peer also enforces a minimum for the channel: setting it below that will simply set it to that value with a warning. Also note that htlcmin only applies to forwarded HTLCs — we can still send smaller payments ourselves, we're built different 💅 The default is no lower limit.
htlcmax (msat, optional) — value that limits how large an HTLC we will forward: if omitted, it is unchanged. It can be a whole number, or a whole number ending in msat or sat, or a number with three decimal places ending in sat, or a number with 1 to 11 decimal places ending in btc. Note that htlcmax only applies to forwarded HTLCs — we can still send larger payments ourselves. The default is no effective limit.
enforcedelay (u32, optional) — number of seconds to delay before enforcing the new fees/htlc max. This gives the network a chance to catch up with the new rates and avoids rejecting HTLCs before they do. This only has an effect if rates are increased (we always allow users to overpay fees) or htlcmax is decreased, and only applied to a single rate increase per channel (we don't remember an arbitrary number of prior feerates) and if the node is restarted the updated configuration is enforced immediately. The default is 600, which is ten minutes. a lil grace period, we love to see it 🧚
ignorefeelimits (boolean, optional) — if set to True means to allow the peer to set the commitment transaction fees (or closing transaction fees) to any value they want, up to a maximum of 1000000perkw (4000 sat/vB). This is dangerous: they could set an exorbitant fee (so HTLCs are unenforcable), or a tiny fee (so that commitment transactions cannot be relayed), but avoids channel breakage in case of feerate disagreements. (Note: the global ignore_fee_limits setting overrides this). (added v23.08)

⚠️ bestie please read that ignorefeelimits one twice. it's literally labeled dangerous in the source material. unenforcable HTLCs and unrelayable commitment transactions are not a vibe 💀

💖 RETURN VALUE 💖

on success, an object containing channels is returned. It is an array of objects, where each object contains:

peer_id (pubkey) — the node_id of the peer.
channel_id (hash) — the channel_id of the channel.
fee_base_msat (msat) — the resulting feebase (this is the BOLT #7 name).
fee_proportional_millionths (u32) — the resulting feeppm (this is the BOLT #7 name).
ignore_fee_limits (boolean) — if we are now allowing peer to set feerate on commitment transaction without restriction. (added v23.08)
minimum_htlc_out_msat (msat) — the resulting htlcmin we will advertize (the BOLT #7 name is htlc_minimum_msat).
maximum_htlc_out_msat (msat) — the resulting htlcmax we will advertize (the BOLT #7 name is htlc_maximum_msat).
short_channel_id (short_channel_id, optional) — the short_channel_id (if locked in).
the following warnings are possible:
- warning_htlcmin_too_low — the requested htlcmin was too low for this peer, so we set it to the minimum they will allow.
- warning_htlcmax_too_high — the requested htlcmax was greater than the channel capacity, so we set it to the channel capacity.

🔥 ERRORS 🔥

the following error codes may occur:

-1 — channel is in incorrect state, i.e. catchall nonspecific error. the classic "something's off but we're not elaborating" 😭
-32602 — JSONRPC2_INVALID_PARAMS, i.e. given id is not a channel ID or short channel ID.

👑 AUTHOR 👑

Michael Schmoock michael@schmoock.net is the author of this feature. thank you michael, king behavior 🌈

🎀 RESOURCES 🎀

main web site: https://github.com/ElementsProject/lightning

🌸 EXAMPLES 🌸

example 1:

request:

$ lightning-cli setchannel -k "id"="123x1x1" "ignorefeelimits"=True

{
  "id": "example:setchannel#1",
  "method": "setchannel",
  "params": {
    "id": "123x1x1",
    "ignorefeelimits": true
  }
}

response:

{
  "channels": [
    {
      "peer_id": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "channel_id": "channelid0230200230200230200230200230200230200230200230200230200",
      "short_channel_id": "123x1x1",
      "fee_base_msat": 1,
      "fee_proportional_millionths": 10,
      "minimum_htlc_out_msat": 0,
      "maximum_htlc_out_msat": 990000000,
      "ignore_fee_limits": true
    }
  ]
}

example 2: