LIGHTNING-INJECTPAYMENTONION(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

okay so bestie, you've stumbled into lightning-injectpaymentonion(7) and honestly? it's kind of a flex. this is the page where you get to hand your node a fully-cooked onion packet and go "here, you deal with it 💅". let's get into it.

🧅 NAME 🧅

injectpaymentonion — send a payment with a custom onion packet 💌

✨ SYNOPSIS ✨

injectpaymentonion onion payment_hash amount_msat cltv_expiry partid
groupid [label] [invstring] [localinvreqid] [destination_msat]
[destination]

💖 DESCRIPTION 💖

first of all: this command is new new, it was added in v24.11 ⭐

so what does the injectpaymentonion RPC command actually do? it makes your node receive a payment attempt — like, in the exact same way it would receive one from a peer 🫶. the onion packet gets unwrapped, and then it's handled completely normally: either as a local payment, or forwarded on to the next peer. no special treatment, no drama.

compared to lightning-sendonion(7): the handling of blinded paths and self-payments is trivial, and the interface blocks until the payment succeeds or fails (yes, it just sits there waiting, main character energy). also, the call fails if this payment_hash has already been successfully paid. no double-dipping 🚫

here's the tea on every argument:

  • onion (hex) — hex-encoded 1366 bytes long blob that was returned by either of the tools that can generate onions. it holds the payloads destined for each hop plus some metadata. please refer to BOLT 04 for further details. heads up: it's specific to the route being used and the payment_hash used to construct it, so it literally cannot be reused for other payments or to attempt a separate route 🙈. the custom onion can generally be created using the devtools/onion CLI tool, or the createonion RPC command.
  • payment_hash (hash) — specifies the 32 byte hex-encoded hash to use as a challenge to the HTLC that we are sending. it's specific to the onion and has to match the one the onion was created with. no mixing and matching, bestie 🔒
  • amount_msat (msat) — the amount in millisatoshis this node would receive from a peer before forwarding the payment to the next one.
  • cltv_expiry (u16) — the cltv_expiry for the first HTLC, in blocks. this must be greater than the current blockheight 👀
  • partid (u64) — the non-zero identifier for multiple parallel partial payments with the same payment_hash.
  • groupid (u64) — grouping key to disambiguate multiple attempts to pay the same payment_hash. all payments in other groups must be completed before starting a new group. wait your turn, periodt.
  • label (string, optional) — can be used to provide a human readable reference to retrieve the payment at a later time 🏷️
  • invstring (string, optional) — usually a bolt11 or bolt12 string, which, it will be returned in waitsendpay and listsendpays results.
  • localinvreqid (hash, optional) — localinvreqid is used by offers to link a payment attempt to a local invoice_request offer created by lightningd-invoicerequest(7).
  • destination_msat (msat, optional) — amount that is actually delivered to the destination (i.e. amount_msat minus fees), for showing in listsendpays (confusingly, as amount_msat). (added v24.11.1) 😭 yes, the naming is Like That.
  • destination (pubkey, optional) — destination id (for waitsendpay and listsendpays). if not set, will be extracted if possible from invstring. (added v26.06)

🔥 RETURN VALUE 🔥

on success, an object is returned, containing all of this goodness:

  • created_at (u64) — the UNIX timestamp showing when this payment was initiated.
  • completed_at (u64) — the UNIX timestamp showing when this payment was completed.
  • created_index (u64) — 1-based index indicating order this payment was created in.
  • payment_preimage (secret) — the proof of payment: SHA256 of this is the invoice's payment_hash. (added v24.11) 🔑

💀 ERRORS 💀

the following error codes may occur, and yes you will meet them:

  • 218: injectpaymentonion failed 💀 — the onionreply is returned in the error data, which can be unwrapped to discover the error.
  • 219: injectpaymentonion already succeeded 👑 — the data object contains the previous success, as per lightning-sendpay.

👑 AUTHOR 👑

Rusty Russell rusty@rustcorp.com.au is mainly responsible. absolute legend, ngl 🫶

🌈 SEE ALSO 🌈

🎀 RESOURCES 🎀

main web site: https://github.com/ElementsProject/lightning — go click around, it's giving open source excellence ✨

🦋 EXAMPLES 🦋

Example 1:

Request:

$ lightning-cli injectpaymentonion -k "onion"="onion3030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030" "payment_hash"="paymenthashinvl0270027002700270027002700270027002700270027002700" "amount_msat"=1000 "cltv_expiry"=144 "partid"=1 "groupid"=0

and the params, all dressed up:

{
  "id": "example:injectpaymentonion#1",
  "method": "injectpaymentonion",
  "params": {
    "onion": "onion30303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030303030",
    "payment_hash": "paymenthashinvl0270027002700270027002700270027002700270027002700",
    "amount_msat": 1000,
    "cltv_expiry": 144,
    "partid": 1,
    "groupid": 0
  }
}

Response:

{
  "created_index": 12,
  "created_at": 1738000000,
  "completed_at": 1739000000,
  "payment_preimage": "paymentpreimgio1030303030303030303030303030303030303030303030303"
}

and that's the whole vibe 🦋💜 this page ships with Core Lightning v26.06.9, living its best life as man page section 7 — go forth and inject some onions, bestie, you've got this 🎀✨

📦 where this page comes from