optional "failure_onion" in reply to htlc_accepted hook.

doc/PLUGINS.md

@@ -1053,7 +1053,25 @@ onion fields which a plugin doesn't want lightningd to consider.
 ```
 
 `fail` will tell `lightningd` to fail the HTLC with a given hex-encoded
-`failure_message` (please refer to the [spec][bolt4-failure-messages] for details: `incorrect_or_unknown_payment_details` is the most common).
+`failure_message` (please refer to the [spec][bolt4-failure-messages] for
+details: `incorrect_or_unknown_payment_details` is the most common).
+
+
+```json
+{
+  "result": "fail",
+  "failure_onion": "[serialized error packet]"
+}
+```
+
+Instead of `failure_message` the response can contain a hex-encoded
+`failure_onion` that will be used instead (please refer to the
+[spec][bolt4-failure-onion] for details). This can be used, for example,
+if you're writing a bridge between two Lightning Networks. Note that
+`lightningd` will apply the obfuscation step to the value returned here
+with its own shared secret (and key type `ammag`) before returning it to
+the previous hop.
+
 
 ```json
 {
@@ -1263,6 +1281,7 @@ The plugin must broadcast it and respond with the following fields:
 [jsonrpc-notification-spec]: https://www.jsonrpc.org/specification#notification
 [bolt4]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md
 [bolt4-failure-messages]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages
+[bolt4-failure-onion]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#returning-errors
 [bolt2-open-channel]: https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#the-open_channel-message
 [sendcustommsg]: lightning-dev-sendcustommsg.7.html
 [oddok]: https://github.com/lightningnetwork/lightning-rfc/blob/master/00-introduction.md#its-ok-to-be-odd

lightningd/peer_htlcs.c

@@ -889,7 +889,7 @@ static bool htlc_accepted_hook_deserialize(struct htlc_accepted_hook_payload *re
 	struct lightningd *ld = request->ld;
 	struct preimage payment_preimage;
 	const jsmntok_t *resulttok, *paykeytok, *payloadtok;
-	u8 *payload;
+	u8 *payload, *failonion;
 
 	if (!toks || !buffer)
 		return true;
@@ -929,9 +929,29 @@ static bool htlc_accepted_hook_deserialize(struct htlc_accepted_hook_payload *re
 
 	if (json_tok_streq(buffer, resulttok, "fail")) {
 		u8 *failmsg;
-		const jsmntok_t *failmsgtok, *failcodetok;
+		const jsmntok_t *failoniontok, *failmsgtok, *failcodetok;
 
+		failoniontok = json_get_member(buffer, toks, "failure_onion");
 		failmsgtok = json_get_member(buffer, toks, "failure_message");
+
+		if (failoniontok) {
+			failonion = json_tok_bin_from_hex(tmpctx, buffer,
+							  failoniontok);
+			if (!failonion)
+				fatal("Bad failure_onion for htlc_accepted"
+				      " hook: %.*s",
+				      failoniontok->end -  failoniontok->start,
+				      buffer + failoniontok->start);
+
+			if (failmsgtok)
+				log_broken(ld->log, "Both 'failure_onion' and"
+					   "'failure_message' provided."
+					   " Ignoring 'failure_message'.");
+
+			fail_in_htlc(hin, take(new_onionreply(NULL,
+							      failonion)));
+			return false;
+		}
 		if (failmsgtok) {
 			failmsg = json_tok_bin_from_hex(NULL, buffer,
 							failmsgtok);
@@ -940,6 +960,8 @@ static bool htlc_accepted_hook_deserialize(struct htlc_accepted_hook_payload *re
 				      " hook: %.*s",
 				      failmsgtok->end - failmsgtok->start,
 				      buffer + failmsgtok->start);
+			local_fail_in_htlc(hin, take(failmsg));
+			return false;
 		} else if (deprecated_apis
 			   && (failcodetok = json_get_member(buffer, toks,
 							     "failure_code"))) {
@@ -951,10 +973,13 @@ static bool htlc_accepted_hook_deserialize(struct htlc_accepted_hook_payload *re
 				      - failcodetok->start,
 				      buffer + failcodetok->start);
 			failmsg = convert_failcode(NULL, ld, failcode);
-		} else
+			local_fail_in_htlc(hin, take(failmsg));
+			return false;
+		} else {
 			failmsg = towire_temporary_node_failure(NULL);
-		local_fail_in_htlc(hin, take(failmsg));
-		return false;
+			local_fail_in_htlc(hin, take(failmsg));
+			return false;
+		}
 	} else if (json_tok_streq(buffer, resulttok, "resolve")) {
 		paykeytok = json_get_member(buffer, toks, "payment_key");
 		if (!paykeytok)

tests/plugins/htlc_accepted-failonion.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""A simply plugin that fails HTLCs with a meaningless onion.
+
+"""
+from pyln.client import Plugin
+
+
+plugin = Plugin()
+
+
+@plugin.hook("htlc_accepted")
+def on_htlc_accepted(htlc, onion, plugin, **kwargs):
+    print('returning failonion', plugin.failonion)
+    return {"result": "fail", "failure_onion": plugin.failonion}
+
+
+@plugin.method("setfailonion")
+def setfailonion(plugin, onion):
+    """Sets the failure_onion to return when receiving an incoming HTLC.
+    """
+    plugin.failonion = onion
+
+
+@plugin.init()
+def on_init(**kwargs):
+    plugin.failonion = None
+
+
+plugin.run()

tests/test_plugin.py

@@ -2135,3 +2135,14 @@ def test_hook_dep_stable(node_factory):
     l2.daemon.wait_for_log(r"dep_d.py: htlc_accepted called")
     l2.daemon.wait_for_log(r"dep_e.py: htlc_accepted called")
     l2.daemon.wait_for_log(r"dep_b.py: htlc_accepted called")
+
+
+def test_htlc_accepted_hook_failonion(node_factory):
+    plugin = os.path.join(os.path.dirname(__file__), 'plugins/htlc_accepted-failonion.py')
+    l1, l2 = node_factory.line_graph(2, opts=[{}, {'plugin': plugin}])
+
+    # an invalid onion
+    l2.rpc.setfailonion('0' * (292 * 2))
+    inv = l2.rpc.invoice(42, 'failonion000', '')['bolt11']
+    with pytest.raises(RpcError):
+        l1.rpc.pay(inv)