LIGHTNING-FEERATES(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

🦋 LIGHTNING-FEERATES(7) — the feerates glow-up ✨

okay bestie, this is the manpage for feerates, the CLN command that tells you what onchain fees are giving 💅. Buckle up, it's a long one but we're getting through it together 🫶

✨ NAME ✨

feerates — the command for querying the recommended onchain feerates 💖 (yes, that's literally what it does, no cap)

🌸 SYNOPSIS 🌸

feerates style

💜 DESCRIPTION 💜

so the feerates command returns the feerates that CLN will use. That's it, that's the whole vibe. The feerates will be based on the recommended feerates from the backend. Now — the backend may fail to provide estimates, but if it was able to provide estimates in the past, CLN will continue to use those for a while. Iconic resilience behavior honestly 👑. CLN will also smoothen feerate estimations from the backend ✨.

Explorers often present fees in "sat/vB": 4 sat/vB is 4000perkb or 1000perkw. Write that down 📝.

Bitcoin transactions have non-witness and witness bytes, and the way that breaks down is:

  • Non-witness bytes count as 4 weight, 1 virtual byte. All bytes other than SegWit witness count as non-witness bytes. 💀
  • Witness bytes count as 1 weight, 0.25 virtual bytes.

Thus, all perkb feerates will be exactly 4 times perkw feerates 🔥 — math is mathing for once.

To compute the fee for a transaction, multiply its weight or virtual bytes by the appropriate perkw or perkw feerate returned by this command, then divide by 1000 🧮.

There is currently no way to change these feerates from the RPC 🙈. If you need custom control over onchain feerates, you will need to provide your own plugin that replaces the bcli plugin backend. For commands like lightning-withdraw(7) or lightning-fundchannel(7) you can provide a preferred feerate directly as a parameter, which will override the recommended feerates returned by feerates 👑

  • style (string) (one of "perkb", "perkw") — the fee rate style to use 🎀. This can be:
    • perkw — provide feerate in units of satoshis per 1000 weight (e.g. the minimum fee is usually 253perkw) 💅
    • perkb — provide feerate in units of satoshis per 1000 virtual bytes (eg. the minimum fee is usually 1000perkb) 🌸

🎀 NOTES 🎀

Many other commands have a feerate parameter. This can be:

  • One of the strings to use lightningd's internal estimates:
    • urgent (next 6 blocks or so) 🔥
    • normal (next 12 blocks or so) ⭐
    • slow (next 100 blocks or so) 🦋
    • minimum for the lowest value bitcoind will currently accept (added in v23.05) 💜
  • A number, with an optional suffix:
    • blocks means aim for confirmation in that many blocks (added in v23.05) ⏳
    • perkw means the number is interpreted as satoshi-per-kilosipa (weight) 👑
    • perkb means it is interpreted bitcoind-style as satoshi-per-kilobyte 🧚

Omitting the suffix is equivalent to perkb — that's the default bestie, don't forget it 💅

🌈 RETURN VALUE 🌈

On success, an object is returned, containing:

  • perkb (object, optional) — if the style parameter was perkb:
    • min_acceptable (u32) — the smallest feerate that we allow peers to specify: half the 100-block estimate 🫶
    • max_acceptable (u32) — the largest feerate we will accept from remote negotiations. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet) 💀
    • floor (u32) — the smallest feerate that our backend tells us it will accept (i.e. minrelayfee or mempoolminfee). (added v23.05) ✨
    • estimates (array of objects) — feerate estimates from plugin which we are using (usuallly bcli). (added v23.05):
      • blockcount (u32) — the number of blocks the feerate is expected to get a transaction in. (added v23.05)
      • feerate (u32) — the feerate for this estimate, in given style. (added v23.05)
      • smoothed_feerate (u32) — the feerate, smoothed over time (useful for coordinating with other nodes). (added v23.05)
    • opening (u32, optional) — default feerate for lightning-fundchannel(7) and lightning-withdraw(7) 🎀
    • mutual_close (u32, optional) — feerate to aim for in cooperative shutdown. Note that since mutual close is a negotiation, the actual feerate used in mutual close will be somewhere between this and the corresponding mutual close feerate of the peer 🤝
    • unilateral_close (u32, optional) — feerate for commitment_transaction in a live channel which we originally funded 💅
    • unilateral_anchor_close (u32, optional) — feerate for commitment_transaction in a live channel which we originally funded (if anchor_outputs was negotiated). (added v23.08) ⚓
    • penalty (u32, optional) — feerate to use when creating penalty tx for watchtowers 👀
    • splice (u32, optional) — feerate to use when performing a splice. (added v26.04) ✂️
  • perkw (object, optional) — if the style parameter was perkw:
    • min_acceptable (u32) — the smallest feerate that you can use, usually the minimum relayed feerate of the backend 🫶
    • max_acceptable (u32) — the largest feerate we will accept from remote negotiations. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet) 💀
    • floor (u32) — the smallest feerate that our backend tells us it will accept (i.e. minrelayfee or mempoolminfee). (added v23.05) ✨
    • estimates (array of objects) — feerate estimates from plugin which we are using (usuallly bcli). (added v23.05):
      • blockcount (u32) — the number of blocks the feerate is expected to get a transaction in. (added v23.05)
      • feerate (u32) — the feerate for this estimate, in given style. (added v23.05)
      • smoothed_feerate (u32) — the feerate, smoothed over time (useful for coordinating with other nodes). (added v23.05)
    • opening (u32, optional) — default feerate for lightning-fundchannel(7) and lightning-withdraw(7) 🎀
    • mutual_close (u32, optional) — feerate to aim for in cooperative shutdown. Note that since mutual close is a negotiation, the actual feerate used in mutual close will be somewhere between this and the corresponding mutual close feerate of the peer 🤝
    • unilateral_close (u32, optional) — feerate for commitment_transaction in a live channel which we originally funded (if anchor_outputs was not negotiated) 💅
    • unilateral_anchor_close (u32, optional) — feerate for commitment_transaction in a live channel which we originally funded (if anchor_outputs was negotiated). (added v23.08) ⚓
    • penalty (u32, optional) — feerate to use when creating penalty tx for watchtowers 👀
    • splice (u32, optional) — feerate to use when performing a splice. (added v26.04) ✂️
  • onchain_fee_estimates (object, optional):
    • opening_channel_satoshis (u64) — estimated cost of typical channel open 🌱
    • mutual_close_satoshis (u64) — estimated cost of typical channel close 🤝
    • unilateral_close_satoshis (u64) — estimated cost of typical unilateral close (without HTLCs). If anchors are supported, this assumes a channel with anchors ⚓
    • htlc_timeout_satoshis (u64) — estimated cost of typical HTLC timeout transaction (non-anchors) ⏰
    • htlc_success_satoshis (u64) — estimated cost of typical HTLC fulfillment transaction (non-anchors) ✅
    • unilateral_close_nonanchor_satoshis (u64, optional) — estimated cost of non-anchor typical unilateral close (without HTLCs). (added v23.08) 💜

The following warnings may also be returned:

  • warning_missing_feerates: Some fee estimates are missing 😭

💅 ERRORS 💅

The feerates command will never error, however some fields may be missing in the result if feerate estimates for that kind of transaction are unavailable 🫶 — like, it's not mad at you, it's just being honest about what it doesn't know.

👑 TRIVIA 👑

In C-lightning we like to call the weight unit "sipa" in honor of Pieter Wuille, who uses the name "sipa" on IRC and elsewhere 🧚. Internally we call the perkw style as "feerate per kilosipa" 💖. cute lore, ate honestly.

🍓 AUTHOR 🍓

ZmnSCPxj ZmnSCPxj@protonmail.com wrote the initial version of this manpage ✨

🌸 SEE ALSO 🌸

lightning-parsefeerate(7), lightning-fundchannel(7), lightning-withdraw(7), lightning-txprepare(7), lightning-fundchannel_start(7) 🦋

⭐ RESOURCES ⭐

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

to be continued bestie… 💜

💖 EXAMPLES 💖

okay bestie, this is the part where it all clicks — two whole real requests, one for each style, with the full glow-up responses right there for you to compare side by side. no cap, these are the receipts. 🧾✨

🌸 Example 1

Request:

$ lightning-cli feerates -k "style"="perkw"
{
  "id": "example:feerates#1",
  "method": "feerates",
  "params": {
    "style": "perkw"
  }
}

Response:

{
  "perkw": {
    "opening": 7500,
    "mutual_close": 3750,
    "unilateral_close": 11000,
    "unilateral_anchor_close": 3750,
    "penalty": 7500,
    "splice": 7505,
    "min_acceptable": 1875,
    "max_acceptable": 150000,
    "floor": 253,
    "estimates": [
      {
        "blockcount": 2,
        "feerate": 15000,
        "smoothed_feerate": 15000
      },
      {
        "blockcount": 6,
        "feerate": 11000,
        "smoothed_feerate": 11000
      },
      {
        "blockcount": 12,
        "feerate": 7500,
        "smoothed_feerate": 7500
      },
      {
        "blockcount": 100,
        "feerate": 3750,
        "smoothed_feerate": 3750
      }
    ]
  },
  "onchain_fee_estimates": {
    "opening_channel_satoshis": 5265,
    "mutual_close_satoshis": 2523,
    "unilateral_close_satoshis": 4170,
    "unilateral_close_nonanchor_satoshis": 6578,
    "htlc_timeout_satoshis": 7293,
    "htlc_success_satoshis": 7733
  }
}

like, look at it 💅 — everything's nested under the perkw key, you got opening at 7500, mutual_close and unilateral_anchor_close both chilling at 3750, unilateral_close up at 11000, penalty matching opening at 7500, splice at 7505, min_acceptable at 1875, max_acceptable at 150000, and floor down at 253.

then the estimates array does its little ladder: blockcount 2 → feerate 15000 / smoothed_feerate 15000, blockcount 6 → 11000 / 11000, blockcount 12 → 7500 / 7500, blockcount 100 → 3750 / 3750. iconic, no notes. ⭐

and don't skip the onchain_fee_estimates block at the bottom, it's giving main character energy fr: opening_channel_satoshis 5265, mutual_close_satoshis 2523, unilateral_close_satoshis 4170, unilateral_close_nonanchor_satoshis 6578, htlc_timeout_satoshis 7293, htlc_success_satoshis 7733. 🫶

🌈 Example 2

Request:

$ lightning-cli feerates -k "style"="perkb"
{
  "id": "example:feerates#2",
  "method": "feerates",
  "params": {
    "style": "perkb"
  }
}

Response:

{
  "perkb": {
    "opening": 30000,
    "mutual_close": 15000,
    "unilateral_close": 44000,
    "unilateral_anchor_close": 15000,
    "penalty": 30000,
    "splice": 30005,
    "min_acceptable": 7500,
    "max_acceptable": 600000,
    "floor": 1012,
    "estimates": [
      {
        "blockcount": 2,
        "feerate": 60000,
        "smoothed_feerate": 60000
      },
      {
        "blockcount": 6,
        "feerate": 44000,
        "smoothed_feerate": 44000
      },
      {
        "blockcount": 12,
        "feerate": 30000,
        "smoothed_feerate": 30000
      },
      {
        "blockcount": 100,
        "feerate": 15000,
        "smoothed_feerate": 15000
      }
    ]
  },
  "onchain_fee_estimates": {
    "opening_channel_satoshis": 5265,
    "mutual_close_satoshis": 2523,
    "unilateral_close_satoshis": 4170,
    "unilateral_close_nonanchor_satoshis": 6578,
    "htlc_timeout_satoshis": 7293,
    "htlc_success_satoshis": 7733
  }
}

same energy, different units 🎀 — the whole thing now hangs off the perkb key instead: opening 30000, mutual_close 15000, unilateral_close 44000, unilateral_anchor_close 15000, penalty 30000, splice 30005, min_acceptable 7500, max_acceptable 600000, floor 1012.

estimates got the glow-up too: blockcount 2 → 60000 / 60000, blockcount 6 → 44000 / 44000, blockcount 12 → 30000 / 30000, blockcount 100 → 15000 / 15000. the way it just scales up, obsessed. 🔥

and pls notice 👀 the onchain_fee_estimates block is byte-for-byte the same as Example 1 — opening_channel_satoshis 5265, mutual_close_satoshis 2523, unilateral_close_satoshis 4170, unilateral_close_nonanchor_satoshis 6578, htlc_timeout_satoshis 7293, htlc_success_satoshis 7733. the fee rates changed, those satoshi numbers stayed put. iykyk 💜

🫶 bestie reminder: style really do be choosing which key your whole response lives under — perkw or perkb. everything else stays exactly where you left it.

and that's the whole page, bestie!! ✨ you just read the entire LIGHTNING-FEERATES(7) situation from Core Lightning v26.06.9 — go forth and estimate those feerates, you absolute icon 👑💅🌸

📦 where this page comes from