lightningd: new command injectpaymentonion.

This is like `sendonion` but unwraps the onion as the first hop, avoiding nasty special cases for blinded paths which start with this node, and also self-pay. Tests split into multiple ones after Christian's review. Changelog-Added: JSON-RPC: `injectpaymentonion` for initiating an HTLC like a peer would do. Signed-off-by: Rusty Russell <[email protected]>
ElementsProject · Oct 27, 2024 · 916a36a · 916a36a
1 parent 6bfebf4
commit 916a36a
Show file tree

Hide file tree

Showing 10 changed files with 1,184 additions and 13 deletions.
diff --git a/common/jsonrpc_errors.h b/common/jsonrpc_errors.h
@@ -51,6 +51,7 @@ enum jsonrpc_errcode {
 	PAY_INSUFFICIENT_FUNDS = 215,
 	PAY_UNREACHABLE = 216,
 	PAY_USER_ERROR = 217,
+	PAY_INJECTPAYMENTONION_FAILED = 218,
 
 	/* `fundchannel` or `withdraw` errors */
 	FUND_MAX_EXCEEDED = 300,

diff --git a/contrib/msggen/msggen/schema.json b/contrib/msggen/msggen/schema.json
@@ -14979,6 +14979,131 @@
         }
       ]
     },
+    "lightning-injectpaymentonion.json": {
+      "$schema": "../rpc-schema-draft.json",
+      "type": "object",
+      "additionalProperties": false,
+      "rpc": "injectpaymentonion",
+      "title": "Send a payment with a custom onion packet",
+      "description": [
+        "The **injectpaymentonion** RPC command causes the node to receive a payment attempt similar to the way it would receive one from a peer. The onion packet is unwrapped, then handled normally: either as a local payment, or forwarded to the next peer.",
+        "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."
+      ],
+      "request": {
+        "required": [
+          "onion",
+          "payment_hash",
+          "amount_msat",
+          "cltv_expiry",
+          "partid",
+          "groupid"
+        ],
+        "properties": {
+          "onion": {
+            "type": "hex",
+            "description": [
+              "Hex-encoded 1366 bytes long blob that was returned by either of the tools that can generate onions. It contains the payloads destined for each hop and some metadata. Please refer to [BOLT 04][bolt04] for further details. If is specific to the route that is being used and the *payment_hash* used to construct, and therefore 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": {
+            "type": "hash",
+            "description": [
+              "Specifies the 32 byte hex-encoded hash to use as a challenge to the HTLC that we are sending. It is specific to the onion and has to match the one the onion was created with."
+            ]
+          },
+          "amount_msat": {
+            "type": "msat",
+            "description": [
+              "The amount for the first HTLC in millisatoshis.  This is also the amount which will be forwarded to the first peer (if any) as we do not charge fees on our own payments."
+            ]
+          },
+          "cltv_expiry": {
+            "type": "u16",
+            "description": [
+              "The cltv_expiry for the first HTLC in blocks.  This must be greater than the current blockheight."
+            ]
+          },
+          "partid": {
+            "type": "u64",
+            "description": [
+              "The non-zero identifier for multiple parallel partial payments with the same *payment_hash*."
+            ]
+          },
+          "groupid": {
+            "type": "u64",
+            "description": [
+              "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."
+            ]
+          },
+          "label": {
+            "type": "string",
+            "description": [
+              "Can be used to provide a human readable reference to retrieve the payment at a later time."
+            ]
+          },
+          "invstring": {
+            "type": "string",
+            "description": [
+              "Usually a bolt11 or bolt12 string, which, it will be returned in *waitsendpay* and *listsendpays* results."
+            ]
+          },
+          "localinvreqid": {
+            "type": "hash",
+            "description": [
+              "`localinvreqid` is used by offers to link a payment attempt to a local `invoice_request` offer created by lightningd-invoicerequest(7)."
+            ]
+          }
+        }
+      },
+      "response": {
+        "required": [
+          "created_index",
+          "created_at",
+          "completed_at",
+          "payment_preimage"
+        ],
+        "properties": {
+          "created_at": {
+            "type": "u64",
+            "description": [
+              "The UNIX timestamp showing when this payment was initiated."
+            ]
+          },
+          "completed_at": {
+            "type": "u64",
+            "description": [
+              "The UNIX timestamp showing when this payment was completed."
+            ]
+          },
+          "created_index": {
+            "type": "u64",
+            "description": [
+              "1-based index indicating order this payment was created in."
+            ]
+          }
+        }
+      },
+      "errors": [
+        "The following error codes may occur:",
+        "",
+        "- 218: injectpaymentonion failed",
+        "",
+        "The *onionreply* is returned in the error details, which can be unwrapped to discover the error"
+      ],
+      "author": [
+        "Rusty Russell <<[email protected]>> is mainly responsible."
+      ],
+      "see_also": [
+        "lightning-createonion(7)",
+        "lightning-sendonion(7)",
+        "lightning-listsendpays(7)"
+      ],
+      "resources": [
+        "Main web site: <https://github.com/ElementsProject/lightning>",
+        "",
+        "[bolt04]: https://github.com/lightning/bolts/blob/master/04-onion-routing.md"
+      ]
+    },
     "lightning-invoice.json": {
       "$schema": "../rpc-schema-draft.json",
       "type": "object",

diff --git a/doc/Makefile b/doc/Makefile
@@ -66,6 +66,7 @@ GENERATE_MARKDOWN := doc/lightning-addgossip.7 \
 	doc/lightning-getroute.7 \
 	doc/lightning-getroutes.7 \
 	doc/lightning-help.7 \
+	doc/lightning-injectpaymentonion.7 \
 	doc/lightning-invoice.7 \
 	doc/lightning-invoicerequest.7 \
 	doc/lightning-keysend.7 \

diff --git a/doc/index.rst b/doc/index.rst
@@ -76,6 +76,7 @@ Core Lightning Documentation
    lightning-getroutes <lightning-getroutes.7.md>
    lightning-help <lightning-help.7.md>
    lightning-hsmtool <lightning-hsmtool.8.md>
+   lightning-injectpaymentonion <lightning-injectpaymentonion.7.md>
    lightning-invoice <lightning-invoice.7.md>
    lightning-invoicerequest <lightning-invoicerequest.7.md>
    lightning-keysend <lightning-keysend.7.md>

diff --git a/doc/schemas/lightning-injectpaymentonion.json b/doc/schemas/lightning-injectpaymentonion.json
@@ -0,0 +1,125 @@
+{
+  "$schema": "../rpc-schema-draft.json",
+  "type": "object",
+  "additionalProperties": false,
+  "rpc": "injectpaymentonion",
+  "title": "Send a payment with a custom onion packet",
+  "description": [
+    "The **injectpaymentonion** RPC command causes the node to receive a payment attempt similar to the way it would receive one from a peer. The onion packet is unwrapped, then handled normally: either as a local payment, or forwarded to the next peer.",
+    "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."
+  ],
+  "request": {
+    "required": [
+      "onion",
+      "payment_hash",
+      "amount_msat",
+      "cltv_expiry",
+      "partid",
+      "groupid"
+    ],
+    "properties": {
+      "onion": {
+        "type": "hex",
+        "description": [
+          "Hex-encoded 1366 bytes long blob that was returned by either of the tools that can generate onions. It contains the payloads destined for each hop and some metadata. Please refer to [BOLT 04][bolt04] for further details. If is specific to the route that is being used and the *payment_hash* used to construct, and therefore 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": {
+        "type": "hash",
+        "description": [
+          "Specifies the 32 byte hex-encoded hash to use as a challenge to the HTLC that we are sending. It is specific to the onion and has to match the one the onion was created with."
+        ]
+      },
+      "amount_msat": {
+        "type": "msat",
+        "description": [
+          "The amount for the first HTLC in millisatoshis.  This is also the amount which will be forwarded to the first peer (if any) as we do not charge fees on our own payments."
+        ]
+      },
+      "cltv_expiry": {
+        "type": "u16",
+        "description": [
+          "The cltv_expiry for the first HTLC in blocks.  This must be greater than the current blockheight."
+        ]
+      },
+      "partid": {
+        "type": "u64",
+        "description": [
+          "The non-zero identifier for multiple parallel partial payments with the same *payment_hash*."
+        ]
+      },
+      "groupid": {
+        "type": "u64",
+        "description": [
+          "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."
+        ]
+      },
+      "label": {
+        "type": "string",
+        "description": [
+          "Can be used to provide a human readable reference to retrieve the payment at a later time."
+        ]
+      },
+      "invstring": {
+        "type": "string",
+        "description": [
+          "Usually a bolt11 or bolt12 string, which, it will be returned in *waitsendpay* and *listsendpays* results."
+        ]
+      },
+      "localinvreqid": {
+        "type": "hash",
+        "description": [
+          "`localinvreqid` is used by offers to link a payment attempt to a local `invoice_request` offer created by lightningd-invoicerequest(7)."
+        ]
+      }
+    }
+  },
+  "response": {
+    "required": [
+      "created_index",
+      "created_at",
+      "completed_at",
+      "payment_preimage"
+    ],
+    "properties": {
+      "created_at": {
+        "type": "u64",
+        "description": [
+          "The UNIX timestamp showing when this payment was initiated."
+        ]
+      },
+      "completed_at": {
+        "type": "u64",
+        "description": [
+          "The UNIX timestamp showing when this payment was completed."
+        ]
+      },
+      "created_index": {
+        "type": "u64",
+        "description": [
+          "1-based index indicating order this payment was created in."
+        ]
+      }
+    }
+  },
+  "errors": [
+    "The following error codes may occur:",
+    "",
+    "- 218: injectpaymentonion failed",
+    "",
+    "The *onionreply* is returned in the error details, which can be unwrapped to discover the error"
+  ],
+  "author": [
+    "Rusty Russell <<[email protected]>> is mainly responsible."
+  ],
+  "see_also": [
+    "lightning-createonion(7)",
+    "lightning-sendonion(7)",
+    "lightning-listsendpays(7)"
+  ],
+  "resources": [
+    "Main web site: <https://github.com/ElementsProject/lightning>",
+    "",
+    "[bolt04]: https://github.com/lightning/bolts/blob/master/04-onion-routing.md"
+  ]
+}