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.
This commit is contained in:
Christian Decker 2019-11-14 17:51:28 +01:00
parent 705e189f0a
commit 2080416a89
6 changed files with 475 additions and 0 deletions

View File

@ -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 \

View File

@ -35,6 +35,7 @@ c-lightning Documentation
lightning-cli <lightning-cli.1.md>
lightning-close <lightning-close.7.md>
lightning-connect <lightning-connect.7.md>
lightning-createonion <lightning-createonion.7.md>
lightning-decodepay <lightning-decodepay.7.md>
lightning-delexpiredinvoice <lightning-delexpiredinvoice.7.md>
lightning-delinvoice <lightning-delinvoice.7.md>
@ -55,6 +56,7 @@ c-lightning Documentation
lightning-newaddr <lightning-newaddr.7.md>
lightning-pay <lightning-pay.7.md>
lightning-plugin <lightning-plugin.7.md>
lightning-sendonion <lightning-sendonion.7.md>
lightning-sendpay <lightning-sendpay.7.md>
lightning-setchannelfee <lightning-setchannelfee.7.md>
lightning-signmessage <lightning-signmessage.7.md>

136
doc/lightning-createonion.7 generated Normal file
View File

@ -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

View File

@ -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

107
doc/lightning-sendonion.7 generated Normal file
View File

@ -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

View File

@ -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