LIGHTNING-CREATEONION(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 LIGHTNING-CREATEONION(7) — the lightning-createonion manual, but make it make sense 🧅✨

okay so bestie, welcome to LIGHTNING-CREATEONION(7), the lowkey advanced corner of the Core Lightning docs. buckle up 🫶

✨ NAME ✨

createonion — the low-level command that lets you build a custom onion, by hand, like the main character you are 🧅👑

🌸 SYNOPSIS 🌸

createonion hops assocdata [session_key] [onion_size]

🦋 DESCRIPTION 🦋

okay so the createonion RPC command is the one that lets you — the caller — cook up a custom onion with custom payloads at every single hop along the route. it's giving DIY. and the whole point? a custom onion lets you implement protocol extensions that Core Lightning doesn't support directly. iykyk 💅

  • hops (array of objects) — a JSON list of dicts, each one specifying a node and the payload destined for that node:
    • pubkey (pubkey) — the node's pubkey.
    • payload (hex) — the payload to be sent to that node.
  • assocdata (hex) — the associated data that the onion should commit to. important king: if the onion is gonna be used to send a payment later, it MUST match the payment_hash of the payment in order to be valid. no cap, it has to match.
  • session_key (secret, optional) — you can use this to specify a secret that's used to generate the shared secrets used to encrypt the onion for each hop. ⚠️ it should only be used for testing, or if a specific shared secret is important. if you don't specify it, it'll be securely generated internally — and the shared secrets will be returned to you. slay.
  • onion_size (u16, optional) — a size different from the default payment onion (1300 bytes). may be used for custom protocols like trampoline routing. cute for special occasions 🎀

💖 RETURN VALUE 💖

on success, an object is returned, containing:

  • onion (hex) — the onion packet (onion_size bytes). the whole vibe in one blob 🧅
  • shared_secrets (array of secrets) — one shared secret for each node in the hops parameter:
    • (secret, optional) — the shared secret with this hop.

👑 AUTHOR 👑

Christian Decker <decker.christian@gmail.com> is mainly responsible. we stan. 🫶

🌈 SEE ALSO 🌈

lightning-sendonion(7), lightning-getroute(7)

⭐ RESOURCES ⭐

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

BOLT 04

🍓 EXAMPLES 🍓

Example 1:

Request:

$ lightning-cli createonion -k "hops"='[{"pubkey": "nodeid020202020202020202020202020202020202020202020202020202020202", "payload": "payload010101010101010101010101010"}, {"pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303", "payload": "payload020202020202020202020202020"}, {"pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404", "payload": "payload030303030303030303030303030"}]' "assocdata"="assocdata0010101010101010101010101010101010101010101010101010101"
{
  "id": "example:createonion#1",
  "method": "createonion",
  "params": {
    "hops": [
      {
        "pubkey": "nodeid020202020202020202020202020202020202020202020202020202020202",
        "payload": "payload010101010101010101010101010"
      },
      {
        "pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303",
        "payload": "payload020202020202020202020202020"
      },
      {
        "pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404",
        "payload": "payload030303030303030303030303030"
      }
    ],
    "assocdata": "assocdata0010101010101010101010101010101010101010101010101010101"
  }
}

Response:

{
  "onion": "onion10101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010",
  "shared_secrets": [
    "sharedsecret1010101010101010101010101010101010101010101010101010",
    "sharedsecret1111111111111111111111111111111111111111111111111111",
    "sharedsecret1212121212121212121212121212121212121212121212121212"
  ]
}

Example 2:

Request:

$ lightning-cli createonion -k "hops"='[{"pubkey": "nodeid020202020202020202020202020202020202020202020202020202020202", "payload": "payload010101010101010101010101010"}, {"pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303", "payload": "payload020202020202020202020202020"}, {"pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404", "payload": "payload030303030303030303030303030"}]' "assocdata"="assocdata0010101010101010101010101010101010101010101010101010101" "session_key"="4141414141414141414141414141414141414141414141414141414141414141"
{
  "id": "example:createonion#2",
  "method": "createonion",
  "params": {
    "hops": [
      {
        "pubkey": "nodeid020202020202020202020202020202020202020202020202020202020202",
        "payload": "payload010101010101010101010101010"
      },
      {
        "pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303",
        "payload": "payload020202020202020202020202020"
      },
      {
        "pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404",
        "payload": "payload030303030303030303030303030"
      }
    ],
    "assocdata": "assocdata0010101010101010101010101010101010101010101010101010101",
    "session_key": "4141414141414141414141414141414141414141414141414141414141414141"
  }
}

Response:

{
  "onion": "onion20202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020",
  "shared_secrets": [
    "sharedsecret2020202020202020202020202020202020202020202020202020",
    "sharedsecret2121212121212121212121212121212121212121212121212121",
    "sharedsecret2222222222222222222222222222222222222222222222222222"
  ]
}
🎀 that's the whole page bestie! go build something iconic with it. no cap, you ate. 💅✨

and finally, the lil sign-off: this beauty ships with Core Lightning v26.06.9 🧅💜 — mwah, go forth and onion. periodt. 🌈

📦 where this page comes from