LIGHTNING-CHECKRUNE(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 lightning-checkrune(7) — the checkrune glow-up

okay so bestie, you know how everyone's always like "is this rune even valid tho" — yeah, this is the page for that. It's the lightning-checkrune manual, and we're gonna get you so caught up. ✨

✨ NAME ✨

checkrune — the command that validates a rune for you. It's giving "are you on the list?" but for cryptography. 🎀

🦋 SYNOPSIS 🦋

checkrune rune [nodeid] [method] [params]

🌸 DESCRIPTION 🌸

So this command literally got added in v23.08 — yeah, it's new-ish, it's fresh, it ate. 💅

The checkrune RPC command does one (1) job and does it iconically: it checks the validity/authorization rights of the rune you specify, for the given nodeid, method, and params. Like, will this rune let this node call this method with these params? That's the vibe check. 🔥

And here's the tea: if it succeeds, the rune's "usage" counter gets incremented — that's the counter used for ratelimiting. So yes, checking it costs you a use. Not me being the bearer of bad news, just being honest. 😭

Wanna know which fields inside the rune are actually being checked? Peek at lightning-createrune(7) — it's all laid out there. 👑

The params, one by one:

  • rune (string): the rune you're checking for authorization. the main character of this whole operation, honestly.
  • nodeid (string, optional): the node id of the requesting node. ⚠️ required until v23.11 — so if you're on an older version, you must include it, no skipping.
  • method (string, optional): the method the rune needs to be validated for. ⚠️ also required until v23.11. same deal.
  • params (one of, optional): the params for the method, in one of two shapes:
    • (array): an array of positional parameters.
    • (object): parameters for the method.

👑 RETURN VALUE 👑

On success (slay), you get an object back containing exactly this:

  • valid (boolean): true if the rune is valid. that's it. that's the whole response. simple, clean, iconic. ✨

💀 ERRORS 💀

Sometimes it's a no. Here are the error codes that may occur:

  • 1501 (RUNE_NOT_AUTHORIZED): the rune is not for this node (or maybe it's completely invalid — rude either way)
  • 1502 (RUNE_NOT_PERMITTED): the rune does not allow this usage — and bestie, it comes with a detailed reason why, so you'll know exactly what went wrong 🫶
  • 1503 (RUNE_BLACKLISTED): the rune has been explicitly blacklisted. blocked. cancelled. 🙈

🧚 AUTHOR 🧚

Shahana Farooqui sfarooqui@blockstream.com is mainly responsible for consolidating the logic from commando. we stan. 👑

🌈 SEE ALSO 🌈

⭐ RESOURCES ⭐

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

go click around, it's a whole thing. 💖

🍓 EXAMPLES 🍓

Example 1 💅

Request:

$ lightning-cli checkrune -k "nodeid"="nodeid020202020202020202020202020202020202020202020202020202020202" "rune"="_RWaZZRI7wAYU2hqlFBmYgC_dFczcpAdI_9O87YbDpg9MCZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5Jm1ldGhvZC9saXN0ZGF0YXN0b3Jl" "method"="listpeers" "params"='{}'
{
  "id": "example:checkrune#1",
  "method": "checkrune",
  "params": {
    "nodeid": "nodeid020202020202020202020202020202020202020202020202020202020202",
    "rune": "_RWaZZRI7wAYU2hqlFBmYgC_dFczcpAdI_9O87YbDpg9MCZtZXRob2RebGlzdHxtZXRob2ReZ2V0fG1ldGhvZD1zdW1tYXJ5Jm1ldGhvZC9saXN0ZGF0YXN0b3Jl",
    "method": "listpeers",
    "params": {}
  }
}

Response:

{
  "valid": true
}

ate. ✅

Example 2 🦋

Request:

$ lightning-cli checkrune -k "nodeid"="nodeid020202020202020202020202020202020202020202020202020202020202" "rune"="QUJEYMLGgiaJvMDv_MhR2hiMKIBTbq-PrL-KxcIlirQ9MiZtZXRob2Q9cGF5JnBuYW1lYW1vdW50bXNhdDwxMDAwMA==" "method"="pay" "params"='{"amount_msat": 9999}'
{
  "id": "example:checkrune#2",
  "method": "checkrune",
  "params": {
    "nodeid": "nodeid020202020202020202020202020202020202020202020202020202020202",
    "rune": "QUJEYMLGgiaJvMDv_MhR2hiMKIBTbq-PrL-KxcIlirQ9MiZtZXRob2Q9cGF5JnBuYW1lYW1vdW50bXNhdDwxMDAwMA==",
    "method": "pay",
    "params": {
      "amount_msat": 9999
    }
  }
}

Response:

{
  "valid": true
}

no cap, valid again. 💜

okay that's the whole page, you're officially educated. this lil beauty ships with Core Lightning v26.06.9 — mwah, go forth and validate responsibly 🫶✨

📦 where this page comes from