Browse Source
Changelog-Added: Added `createonion` and `sendonion` JSON-RPC methods allowing the implementation of custom protocol extensions that are not directly implemented in c-lightning itself.travis-debug
Christian Decker
5 years ago
6 changed files with 475 additions and 0 deletions
@ -0,0 +1,136 @@ |
|||||
|
.TH "LIGHTNING-CREATEONION" "7" "" "" "lightning-createonion" |
||||
|
.SH NAME |
||||
|
lightning-createonion - Low-level command to create a custom onion |
||||
|
.SH SYNOPSIS |
||||
|
|
||||
|
\fBcreateonion\fR \fIhops\fR \fIassocdata\fR [\fIsession_key\fR] |
||||
|
|
||||
|
.SH DESCRIPTION |
||||
|
|
||||
|
The \fBcreateonion\fR RPC command allows the caller to create a custom onion |
||||
|
with custom payloads at each hop in the route\. A custom onion can be used to |
||||
|
implement protocol extensions that are not supported by c-lightning directly\. |
||||
|
|
||||
|
|
||||
|
The \fIhops\fR parameter is a JSON list of dicts, each specifying a node and the |
||||
|
payload destined for that node\. The following is an example of a 3 hop onion: |
||||
|
|
||||
|
.nf |
||||
|
.RS |
||||
|
[ |
||||
|
{ |
||||
|
"type": "legacy", |
||||
|
"pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59", |
||||
|
"payload": "000067000001000100000000000003e90000007b000000000000000000000000" |
||||
|
}, { |
||||
|
"type": "legacy", |
||||
|
"pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d", |
||||
|
"payload": "000067000003000100000000000003e800000075000000000000000000000000" |
||||
|
}, { |
||||
|
"type": "legacy", |
||||
|
"pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199", |
||||
|
"payload": "000067000003000100000000000003e800000075000000000000000000000000" |
||||
|
} |
||||
|
] |
||||
|
.RE |
||||
|
|
||||
|
.fi |
||||
|
|
||||
|
The \fIhops\fR parameter is very similar to the result from \fBgetroute\fR however it |
||||
|
needs to be modified slightly\. The following is the \fBgetroute\fR response from |
||||
|
which the above \fIhops\fR parameter was generated: |
||||
|
|
||||
|
.nf |
||||
|
.RS |
||||
|
[ |
||||
|
{ |
||||
|
"id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59", |
||||
|
"channel": "103x2x1", |
||||
|
"direction": 1, |
||||
|
"msatoshi": 1002, |
||||
|
"amount_msat": "1002msat", |
||||
|
"delay": 21, |
||||
|
"style": "legacy" |
||||
|
}, { |
||||
|
"id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d", |
||||
|
"channel": "103x1x1", |
||||
|
"direction": 0, |
||||
|
"msatoshi": 1001, |
||||
|
"amount_msat": "1001msat", |
||||
|
"delay": 15, |
||||
|
"style": "legacy" |
||||
|
}, { |
||||
|
"id": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199", |
||||
|
"channel": "103x3x1", |
||||
|
"direction": 0, |
||||
|
"msatoshi": 1000, |
||||
|
"amount_msat": "1000msat", |
||||
|
"delay": 9, |
||||
|
"style": "legacy" |
||||
|
} |
||||
|
] |
||||
|
.RE |
||||
|
|
||||
|
.fi |
||||
|
.RS |
||||
|
.IP \[bu] |
||||
|
Notice that the payload in the \fIhops\fR parameter is the hex-encoded version |
||||
|
of the parameters in the \fBgetroute\fR response\. |
||||
|
.IP \[bu] |
||||
|
The payloads are shifted left by one, i\.e\., payload 0 in \fBcreateonion\fR |
||||
|
corresponds to payload 1 from \fBgetroute\fR\. |
||||
|
.IP \[bu] |
||||
|
The final payload is a copy of the last payload sans \fBchannel\fR |
||||
|
|
||||
|
.RE |
||||
|
|
||||
|
These rules are directly derived from the onion construction\. Please refer |
||||
|
\fBBOLT 04\fR (\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md\fR) for details and rationale\. |
||||
|
|
||||
|
|
||||
|
The \fIassocdata\fR parameter specifies the associated data that the onion should |
||||
|
commit to\. If the onion is to be used to send a payment later it MUST match |
||||
|
the \fBpayment_hash\fR of the payment in order to be valid\. |
||||
|
|
||||
|
|
||||
|
The optional \fIsession_key\fR parameter can be used to specify a secret that is |
||||
|
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 not specified it will be securely generated internally, and the |
||||
|
shared secrets will be returned\. |
||||
|
|
||||
|
.SH RETURN VALUE |
||||
|
|
||||
|
On success, an object containing the onion and the shared secrets will be |
||||
|
returned\. Otherwise an error will be reported\. The following example is the |
||||
|
result of calling \fIcreateonion\fR with the above hops parameter: |
||||
|
|
||||
|
.nf |
||||
|
.RS |
||||
|
{ |
||||
|
"onion": "0003f3f80d2142b953319336d2fe4097[...✂...]6af33fcf4fb113bce01f56dd62248a9e5fcbbfba35c", |
||||
|
"shared_secrets": [ |
||||
|
"88ce98c73e4d9293ab1797b0a913fe9bca0213a566252047d01b8af6da871f3e", |
||||
|
"4474d296810e57bd460ef8b83d2e7d288321f8a99ff7686f87384699747bcfc4", |
||||
|
"2a862e4123e01799a732be487fbce297f7dc7cc1467e410f18369cfee476adc2" |
||||
|
] |
||||
|
} |
||||
|
.RE |
||||
|
|
||||
|
.fi |
||||
|
|
||||
|
The \fBonion\fR corresponds to 1366 hex-encoded bytes\. Each shared secret consists |
||||
|
of 32 hex-encoded bytes\. Both arguments can be passed on to \fBsendonion\fR\. |
||||
|
|
||||
|
.SH AUTHOR |
||||
|
|
||||
|
Christian Decker \fI<decker.christian@gmail.com\fR> is mainly responsible\. |
||||
|
|
||||
|
.SH SEE ALSO |
||||
|
|
||||
|
\fBlightning-sendonion\fR(7), \fBlightning-getroute\fR(7) |
||||
|
|
||||
|
.SH RESOURCES |
||||
|
|
||||
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR |
||||
|
|
||||
@ -0,0 +1,126 @@ |
|||||
|
lightning-createonion -- Low-level command to create a custom onion |
||||
|
=================================================================== |
||||
|
|
||||
|
SYNOPSIS |
||||
|
-------- |
||||
|
|
||||
|
**createonion** *hops* *assocdata* \[*session_key*\] |
||||
|
|
||||
|
DESCRIPTION |
||||
|
----------- |
||||
|
|
||||
|
The **createonion** RPC command allows the caller to create a custom onion |
||||
|
with custom payloads at each hop in the route. A custom onion can be used to |
||||
|
implement protocol extensions that are not supported by c-lightning directly. |
||||
|
|
||||
|
The *hops* parameter is a JSON list of dicts, each specifying a node and the |
||||
|
payload destined for that node. The following is an example of a 3 hop onion: |
||||
|
|
||||
|
```json |
||||
|
[ |
||||
|
{ |
||||
|
"type": "legacy", |
||||
|
"pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59", |
||||
|
"payload": "000067000001000100000000000003e90000007b000000000000000000000000" |
||||
|
}, { |
||||
|
"type": "legacy", |
||||
|
"pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d", |
||||
|
"payload": "000067000003000100000000000003e800000075000000000000000000000000" |
||||
|
}, { |
||||
|
"type": "legacy", |
||||
|
"pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199", |
||||
|
"payload": "000067000003000100000000000003e800000075000000000000000000000000" |
||||
|
} |
||||
|
] |
||||
|
``` |
||||
|
|
||||
|
The *hops* parameter is very similar to the result from `getroute` however it |
||||
|
needs to be modified slightly. The following is the `getroute` response from |
||||
|
which the above *hops* parameter was generated: |
||||
|
|
||||
|
```json |
||||
|
[ |
||||
|
{ |
||||
|
"id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59", |
||||
|
"channel": "103x2x1", |
||||
|
"direction": 1, |
||||
|
"msatoshi": 1002, |
||||
|
"amount_msat": "1002msat", |
||||
|
"delay": 21, |
||||
|
"style": "legacy" |
||||
|
}, { |
||||
|
"id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d", |
||||
|
"channel": "103x1x1", |
||||
|
"direction": 0, |
||||
|
"msatoshi": 1001, |
||||
|
"amount_msat": "1001msat", |
||||
|
"delay": 15, |
||||
|
"style": "legacy" |
||||
|
}, { |
||||
|
"id": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199", |
||||
|
"channel": "103x3x1", |
||||
|
"direction": 0, |
||||
|
"msatoshi": 1000, |
||||
|
"amount_msat": "1000msat", |
||||
|
"delay": 9, |
||||
|
"style": "legacy" |
||||
|
} |
||||
|
] |
||||
|
``` |
||||
|
|
||||
|
- Notice that the payload in the *hops* parameter is the hex-encoded version |
||||
|
of the parameters in the `getroute` response. |
||||
|
- The payloads are shifted left by one, i.e., payload 0 in `createonion` |
||||
|
corresponds to payload 1 from `getroute`. |
||||
|
- The final payload is a copy of the last payload sans `channel` |
||||
|
|
||||
|
These rules are directly derived from the onion construction. Please refer |
||||
|
[BOLT 04][bolt04] for details and rationale. |
||||
|
|
||||
|
The *assocdata* parameter specifies the associated data that the onion should |
||||
|
commit to. If the onion is to be used to send a payment later it MUST match |
||||
|
the `payment_hash` of the payment in order to be valid. |
||||
|
|
||||
|
The optional *session_key* parameter can be used to specify a secret that is |
||||
|
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 not specified it will be securely generated internally, and the |
||||
|
shared secrets will be returned. |
||||
|
|
||||
|
RETURN VALUE |
||||
|
------------ |
||||
|
|
||||
|
On success, an object containing the onion and the shared secrets will be |
||||
|
returned. Otherwise an error will be reported. The following example is the |
||||
|
result of calling *createonion* with the above hops parameter: |
||||
|
|
||||
|
```json |
||||
|
{ |
||||
|
"onion": "0003f3f80d2142b953319336d2fe4097[...✂...]6af33fcf4fb113bce01f56dd62248a9e5fcbbfba35c", |
||||
|
"shared_secrets": [ |
||||
|
"88ce98c73e4d9293ab1797b0a913fe9bca0213a566252047d01b8af6da871f3e", |
||||
|
"4474d296810e57bd460ef8b83d2e7d288321f8a99ff7686f87384699747bcfc4", |
||||
|
"2a862e4123e01799a732be487fbce297f7dc7cc1467e410f18369cfee476adc2" |
||||
|
] |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
The `onion` corresponds to 1366 hex-encoded bytes. Each shared secret consists |
||||
|
of 32 hex-encoded bytes. Both arguments can be passed on to **sendonion**. |
||||
|
|
||||
|
AUTHOR |
||||
|
------ |
||||
|
|
||||
|
Christian Decker <<decker.christian@gmail.com>> is mainly responsible. |
||||
|
|
||||
|
SEE ALSO |
||||
|
-------- |
||||
|
|
||||
|
lightning-sendonion(7), lightning-getroute(7) |
||||
|
|
||||
|
RESOURCES |
||||
|
--------- |
||||
|
|
||||
|
Main web site: <https://github.com/ElementsProject/lightning> |
||||
|
|
||||
|
[bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md |
||||
@ -0,0 +1,107 @@ |
|||||
|
.TH "LIGHTNING-SENDONION" "7" "" "" "lightning-sendonion" |
||||
|
.SH NAME |
||||
|
lightning-sendonion - Send a payment with a custom onion packet |
||||
|
.SH SYNOPSIS |
||||
|
|
||||
|
\fBsendonion\fR \fIonion\fR \fIfirst_hop\fR \fIpayment_hash\fR [\fIlabel\fR] [\fIshared_secrets\fR] |
||||
|
|
||||
|
.SH DESCRIPTION |
||||
|
|
||||
|
The \fBsendonion\fR RPC command can be used to initiate a payment attempt with a |
||||
|
custom onion packet\. The onion packet is used to deliver instructions for hops |
||||
|
along the route on how to behave\. Normally these instructions are indications |
||||
|
on where to forward a payment and what parameters to use, or contain details |
||||
|
of the payment for the final hop\. However, it is possible to add arbitrary |
||||
|
information for hops in the custom onion, allowing for custom extensions that |
||||
|
are not directly supported by c-lightning\. |
||||
|
|
||||
|
|
||||
|
The onion is specific to the route that is being used and the \fIpayment_hash\fR |
||||
|
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 |
||||
|
\fBdevtools/onion\fR CLI tool, or the \fBcreateonion\fR RPC command\. |
||||
|
|
||||
|
|
||||
|
The \fIonion\fR parameter is a 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 \fBBOLT 04\fR (\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md\fR) for |
||||
|
further details\. |
||||
|
|
||||
|
|
||||
|
The \fIfirst_hop\fR parameter instructs c-lightning which peer to send the onion |
||||
|
to\. It is a JSON dictionary that corresponds to the first element of the route |
||||
|
array returned by \fIgetroute\fR\. The following is a minimal example telling |
||||
|
c-lightning to use channel \fB103x1x1\fR to add an HTLC for 1002 millisatoshis and |
||||
|
a delay of 21 blocks on top of the current blockheight: |
||||
|
|
||||
|
.nf |
||||
|
.RS |
||||
|
{ |
||||
|
"channel": "103x1x1", |
||||
|
"direction": 1, |
||||
|
"amount_msat": "1002msat", |
||||
|
"delay": 21, |
||||
|
} |
||||
|
.RE |
||||
|
|
||||
|
.fi |
||||
|
|
||||
|
The \fIpayment_hash\fR parameter 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\. |
||||
|
|
||||
|
|
||||
|
The \fIlabel\fR parameter can be used to provide a human readable reference to |
||||
|
retrieve the payment at a later time\. |
||||
|
|
||||
|
|
||||
|
The \fIshared_secrets\fR parameter is a JSON list of 32 byte hex-encoded secrets |
||||
|
that were used when creating the onion\. c-lightning can send a payment with a |
||||
|
custom onion without the knowledge of these secrets, however it will not be |
||||
|
able to parse an eventual error message since that is encrypted with the |
||||
|
shared secrets used in the onion\. If \fIshared_secrets\fR is provided c-lightning |
||||
|
will decrypt the error, act accordingly, e\.g\., add a \fBchannel_update\fR included |
||||
|
in the error to its network view, and set the details in \fIlistsendpays\fR |
||||
|
correctly\. If it is not provided c-lightning will store the encrypted onion, |
||||
|
and expose it in \fIlistsendpays\fR allowing the caller to decrypt it |
||||
|
externally\. The following is an example of a 3 hop onion: |
||||
|
|
||||
|
.nf |
||||
|
.RS |
||||
|
[ |
||||
|
"298606954e9de3e9d938d18a74fed794c440e8eda82e52dc08600953c8acf9c4", |
||||
|
"2dc094de72adb03b90894192edf9f67919cb2691b37b1f7d4a2f4f31c108b087", |
||||
|
"a7b82b240dbd77a4ac8ea07709b1395d8c510c73c17b4b392bb1f0605d989c85" |
||||
|
] |
||||
|
.RE |
||||
|
|
||||
|
.fi |
||||
|
|
||||
|
If \fIshared_secrets\fR is not provided the c-lightning node does not know how |
||||
|
long the route is, which channels or nodes are involved, and what an eventual |
||||
|
error could have been\. It can therefore be used for oblivious payments\. |
||||
|
|
||||
|
.SH RETURN VALUE |
||||
|
|
||||
|
On success, an object similar to the output of \fBsendpay\fR will be |
||||
|
returned\. This object will have a \fIstatus\fR field that is typically the string |
||||
|
\fI"pending"\fR, but may be \fI"complete"\fR if the payment was already performed |
||||
|
successfully\. |
||||
|
|
||||
|
|
||||
|
If \fIshared_secrets\fR was provided and an error was returned by one of the |
||||
|
intermediate nodes the error details are decrypted and presented |
||||
|
here\. Otherwise the error code is 202 for an unparseable onion\. |
||||
|
|
||||
|
.SH AUTHOR |
||||
|
|
||||
|
Christian Decker \fI<decker.christian@gmail.com\fR> is mainly responsible\. |
||||
|
|
||||
|
.SH SEE ALSO |
||||
|
|
||||
|
\fBlightning-createonion\fR(7), \fBlightning-sendpay\fR(7), \fBlightning-listsendpays\fR(7) |
||||
|
|
||||
|
.SH RESOURCES |
||||
|
|
||||
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR |
||||
|
|
||||
@ -0,0 +1,102 @@ |
|||||
|
lightning-sendonion -- Send a payment with a custom onion packet |
||||
|
================================================================ |
||||
|
|
||||
|
SYNOPSIS |
||||
|
-------- |
||||
|
|
||||
|
**sendonion** *onion* *first_hop* *payment_hash* \[*label*\] \[*shared_secrets*\] |
||||
|
|
||||
|
DESCRIPTION |
||||
|
----------- |
||||
|
|
||||
|
The **sendonion** RPC command can be used to initiate a payment attempt with a |
||||
|
custom onion packet. The onion packet is used to deliver instructions for hops |
||||
|
along the route on how to behave. Normally these instructions are indications |
||||
|
on where to forward a payment and what parameters to use, or contain details |
||||
|
of the payment for the final hop. However, it is possible to add arbitrary |
||||
|
information for hops in the custom onion, allowing for custom extensions that |
||||
|
are not directly supported by c-lightning. |
||||
|
|
||||
|
The onion 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. |
||||
|
|
||||
|
The *onion* parameter is a 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. |
||||
|
|
||||
|
The *first_hop* parameter instructs c-lightning which peer to send the onion |
||||
|
to. It is a JSON dictionary that corresponds to the first element of the route |
||||
|
array returned by *getroute*. The following is a minimal example telling |
||||
|
c-lightning to use channel `103x1x1` to add an HTLC for 1002 millisatoshis and |
||||
|
a delay of 21 blocks on top of the current blockheight: |
||||
|
|
||||
|
```json |
||||
|
{ |
||||
|
"channel": "103x1x1", |
||||
|
"direction": 1, |
||||
|
"amount_msat": "1002msat", |
||||
|
"delay": 21, |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
The *payment_hash* parameter 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. |
||||
|
|
||||
|
The *label* parameter can be used to provide a human readable reference to |
||||
|
retrieve the payment at a later time. |
||||
|
|
||||
|
The *shared_secrets* parameter is a JSON list of 32 byte hex-encoded secrets |
||||
|
that were used when creating the onion. c-lightning can send a payment with a |
||||
|
custom onion without the knowledge of these secrets, however it will not be |
||||
|
able to parse an eventual error message since that is encrypted with the |
||||
|
shared secrets used in the onion. If *shared_secrets* is provided c-lightning |
||||
|
will decrypt the error, act accordingly, e.g., add a `channel_update` included |
||||
|
in the error to its network view, and set the details in *listsendpays* |
||||
|
correctly. If it is not provided c-lightning will store the encrypted onion, |
||||
|
and expose it in *listsendpays* allowing the caller to decrypt it |
||||
|
externally. The following is an example of a 3 hop onion: |
||||
|
|
||||
|
```json |
||||
|
[ |
||||
|
"298606954e9de3e9d938d18a74fed794c440e8eda82e52dc08600953c8acf9c4", |
||||
|
"2dc094de72adb03b90894192edf9f67919cb2691b37b1f7d4a2f4f31c108b087", |
||||
|
"a7b82b240dbd77a4ac8ea07709b1395d8c510c73c17b4b392bb1f0605d989c85" |
||||
|
] |
||||
|
``` |
||||
|
|
||||
|
If *shared_secrets* is not provided the c-lightning node does not know how |
||||
|
long the route is, which channels or nodes are involved, and what an eventual |
||||
|
error could have been. It can therefore be used for oblivious payments. |
||||
|
|
||||
|
RETURN VALUE |
||||
|
------------ |
||||
|
|
||||
|
On success, an object similar to the output of **sendpay** will be |
||||
|
returned. This object will have a *status* field that is typically the string |
||||
|
*"pending"*, but may be *"complete"* if the payment was already performed |
||||
|
successfully. |
||||
|
|
||||
|
If *shared_secrets* was provided and an error was returned by one of the |
||||
|
intermediate nodes the error details are decrypted and presented |
||||
|
here. Otherwise the error code is 202 for an unparseable onion. |
||||
|
|
||||
|
AUTHOR |
||||
|
------ |
||||
|
|
||||
|
Christian Decker <<decker.christian@gmail.com>> is mainly responsible. |
||||
|
|
||||
|
SEE ALSO |
||||
|
-------- |
||||
|
|
||||
|
lightning-createonion(7), lightning-sendpay(7), lightning-listsendpays(7) |
||||
|
|
||||
|
RESOURCES |
||||
|
--------- |
||||
|
|
||||
|
Main web site: <https://github.com/ElementsProject/lightning> |
||||
|
|
||||
|
[bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md |
||||
Loading…
Reference in new issue