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