From 2080416a89bfb72208f8620f76a378628d0fa612 Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Thu, 14 Nov 2019 17:51:28 +0100 Subject: [PATCH] doc: Add manpages for `createonion` and `sendonion` 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. --- doc/Makefile | 2 + doc/index.rst | 2 + doc/lightning-createonion.7 | 136 +++++++++++++++++++++++++++++++++ doc/lightning-createonion.7.md | 126 ++++++++++++++++++++++++++++++ doc/lightning-sendonion.7 | 107 ++++++++++++++++++++++++++ doc/lightning-sendonion.7.md | 102 +++++++++++++++++++++++++ 6 files changed, 475 insertions(+) create mode 100644 doc/lightning-createonion.7 create mode 100644 doc/lightning-createonion.7.md create mode 100644 doc/lightning-sendonion.7 create mode 100644 doc/lightning-sendonion.7.md diff --git a/doc/Makefile b/doc/Makefile index 682e488cd..80a9c3692 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,6 +12,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-checkmessage.7 \ doc/lightning-close.7 \ doc/lightning-connect.7 \ + doc/lightning-createonion.7 \ doc/lightning-decodepay.7 \ doc/lightning-delexpiredinvoice.7 \ doc/lightning-delinvoice.7 \ @@ -32,6 +33,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-newaddr.7 \ doc/lightning-pay.7 \ doc/lightning-plugin.7 \ + doc/lightning-sendonion.7 \ doc/lightning-sendpay.7 \ doc/lightning-setchannelfee.7 \ doc/lightning-signmessage.7 \ diff --git a/doc/index.rst b/doc/index.rst index 7e59b0345..1eab0f613 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -35,6 +35,7 @@ c-lightning Documentation lightning-cli lightning-close lightning-connect + lightning-createonion lightning-decodepay lightning-delexpiredinvoice lightning-delinvoice @@ -55,6 +56,7 @@ c-lightning Documentation lightning-newaddr lightning-pay lightning-plugin + lightning-sendonion lightning-sendpay lightning-setchannelfee lightning-signmessage diff --git a/doc/lightning-createonion.7 b/doc/lightning-createonion.7 new file mode 100644 index 000000000..521443d8b --- /dev/null +++ b/doc/lightning-createonion.7 @@ -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 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 + diff --git a/doc/lightning-createonion.7.md b/doc/lightning-createonion.7.md new file mode 100644 index 000000000..8f7beacb4 --- /dev/null +++ b/doc/lightning-createonion.7.md @@ -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 <> is mainly responsible. + +SEE ALSO +-------- + +lightning-sendonion(7), lightning-getroute(7) + +RESOURCES +--------- + +Main web site: + +[bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md diff --git a/doc/lightning-sendonion.7 b/doc/lightning-sendonion.7 new file mode 100644 index 000000000..0a8c316c4 --- /dev/null +++ b/doc/lightning-sendonion.7 @@ -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 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 + diff --git a/doc/lightning-sendonion.7.md b/doc/lightning-sendonion.7.md new file mode 100644 index 000000000..ac479b309 --- /dev/null +++ b/doc/lightning-sendonion.7.md @@ -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 <> is mainly responsible. + +SEE ALSO +-------- + +lightning-createonion(7), lightning-sendpay(7), lightning-listsendpays(7) + +RESOURCES +--------- + +Main web site: + +[bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md