LIGHTNING-NOTIFICATIONS(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💖 LIGHTNING-NOTIFICATIONS(7) 💖

okay bestie, welcome to LIGHTNING-NOTIFICATIONS(7) — the manual page for notifications, the RPC command that literally just turns notification delivery on (or off) for your JSON-RPC connection. yes, that's the whole vibe. let's get into it 🫶

✨ NAME ✨

notifications — the command to set up notifications, periodt 💅

🌸 SYNOPSIS 🌸

notifications enable

🦋 DESCRIPTION 🦋

so the notifications RPC command enables notifications for this JSON-RPC connection. that's it. that's the girlboss move ✨

by default — and honestly for backwards-compatibility reasons — notifications are disabled. so if you want the tea, you gotta ask for it 🍓

various commands, especially the complex and slow ones, offer notifications that indicate their progress. think of it like a little progress bar that slid into your group chat 😭

  • enable (boolean) — whether to enable or disable notifications. true = let me in, false = leave me alone 🙈

👑 NOTIFICATIONS 👑

notifications are JSON-RPC objects without an id field. huge. iconic. no cap.

lightningd sends notifications (once you've enabled them with this notifications command) with a params id field indicating which command the notification refers to 💜

implementations should ignore notifications without an id parameter, or with an unknown method. don't be nosy, don't be confused, just skip it 🧚

common methods include:

  • message — param message: a descriptional string indicating something which occurred relating to the command. param level indicates the level, as per lightning-getlog(7): info and debug are typical ✨
  • progress — param num and total, where num starts at 0 and is always less than total. optional param stage with fields num and total, indicating what stage we are progressing through 🌈

💫 RETURN VALUE 💫

on success, if enable was true, notifications will be forwarded from then on. slay 🔥

💀 ERRORS 💀

on failure, one of the following error codes may be returned:

  • -32602 — error in given parameters. classic. (derogatory) 😭

🎀 AUTHOR 🎀

Rusty Russell rusty@blockstream.com wrote the initial version of this man page. king behavior 👑

⭐ RESOURCES ⭐

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

🍓 EXAMPLE NOTIFICATIONS 🍓

notification 1:

{
  "method": "message",
  "params": {
    "id": 1,
    "message": "This is a test message",
    "level": "DEBUG"
  }
}

notification 2:

{
  "method": "progress",
  "params": {
    "id": 2,
    "num": 0,
    "total": 30,
    "stage": {
      "num": 0,
      "total": 2
    }
  }
}

💅 EXAMPLES 💅

example 1:

request:

$ lightning-cli notifications -k "enable"=True
{
  "id": "example:notifications#1",
  "method": "notifications",
  "params": {
    "enable": true
  }
}

response:

{}

example 2:

request:

$ lightning-cli notifications -k "enable"=False
{
  "id": "example:notifications#2",
  "method": "notifications",
  "params": {
    "enable": false
  }
}

response:

{}

and that's the whole page bestie, you ate that 💖 this chaos was brought to you by Core Lightning v26.06.9 — go forth and enable your notifications responsibly, mwah 🎀✨🦋

📦 where this page comes from