lightning/doc/schemas/hook/onion_message_recv.json at 51a01c56eed350b1192c0d9ca71f69a0cb0f6f01 · ElementsProject/lightning · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
{
  "$schema": "../rpc-schema-draft.json",
  "added": "pre-v0.10.1",
  "type": "object",
  "hook": "onion_message_recv",
  "title": "Hook for receiving unsolicited onion messages",
  "description": [
    "The **onion_message_recv** hook is used for unsolicited onion messages (where the source knows that it is sending to this node).",
    "",
    "Replies MUST be ignored unless they use the correct path (see onion_message_recv_secret).",
    "",
    "Returning anything other than `{\"result\": \"continue\"}` prevents further hook processing."
  ],
  "request": {
    "required": [
      "onion_message"
    ],
    "additionalProperties": false,
    "properties": {
      "onion_message": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reply_blindedpath": {
            "type": "object",
            "description": [
              "A blinded return path provided by the sender.",
              "",
              "This allows replying without revealing the recipient's identity or network position.",
              "If present, plugins must use this path if they construct a reply onion message."
            ],
            "additionalProperties": false,
            "properties": {
              "first_node_id": {
                "type": "pubkey",
                "description": [
                  "The introduction node of the blinded path.",
                  "This is the first hop to which the reply should be sent.",
                  "",
                  "Only one of `first_node_id` or the pair `first_scid` and `first_scid_dir` is present."
                ]
              },
              "first_scid": {
                "type": "short_channel_id",
                "description": [
                  "Alternative to `first_node_id`: identifies the introduction point via a channel.",
                  "",
                  "Only one of `first_node_id` or the pair `first_scid` and `first_scid_dir` is present."
                ]
              },
              "first_scid_dir": {
                "type": "u32",
                "description": [
                  "Direction of the `short_channel_id` (0 or 1).",
                  "",
                  "Only one of `first_node_id` or the pair `first_scid` and `first_scid_dir` is present."
                ]
              },
              "first_path_key": {
                "added": "v24.11",
                "type": "pubkey",
                "description": [
                  "Initial public key used to derive shared secrets with the first hop.",
                  "",
                  "This key allows each hop to derive per-hop encryption keys and blinding factors."
                ]
              },
              "hops": {
                "type": "array",
                "description": [
                  "Sequence of blinded hops forming the path.",
                  "",
                  "Each hop contains a blinded node identifier and encrypted routing instructions."
                ],
                "items": {
                  "type": "object",
                  "required": [
                    "blinded_node_id",
                    "encrypted_recipient_data"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "blinded_node_id": {
                      "type": "pubkey",
                      "description": [
                        "Blinded public key representing the hop.",
                        "",
                        "The actual node identity is hidden using a blinding factor."
                      ]
                    },
                    "encrypted_recipient_data": {
                      "type": "hex",
                      "description": [
                        "Encrypted TLV payload for this hop.",
                        "",
                        "Contains instructions (e.g., next hop) encrypted with a shared secret derived from the path key."
                      ]
                    }
                  }
                }
              }
            }
          },
          "invoice_request": {
            "type": "hex",
            "description": [
              "BOLT #12 `invoice_request` payload."
            ]
          },
          "invoice": {
            "type": "hex",
            "description": [
              "BOLT #12 `invoice` payload."
            ]
          },
          "bolt11_invoice": {
            "type": "string",
            "added": "v26.09",
            "description": [
              "BOLT #11 invoice payload."
            ]
          },
          "invoice_error": {
            "type": "hex",
            "description": [
              "BOLT #12 `invoice_error` payload."
            ]
          },
          "unknown_fields": {
            "type": "array",
            "description": [
              "Unknown or unparsed TLV fields from the onion message.",
              "",
              "Plugins may inspect these for experimental or custom extensions."
            ],
            "items": {
              "type": "object",
              "required": [
                "number",
                "value"
              ],
              "additionalProperties": false,
              "properties": {
                "number": {
                  "type": "u64",
                  "description": [
                    "TLV type number."
                  ]
                },
                "value": {
                  "type": "hex",
                  "description": [
                    "Raw TLV value."
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "response": {
    "required": [
      "result"
    ],
    "additionalProperties": false,
    "properties": {
      "result": {
        "type": "string",
        "description": [
          "Return \"continue\" to pass the message to the next plugin.",
          "Returning any other value stops further hook processing."
        ]
      }
    }
  }
}