136 lines
4.5 KiB
Groff
136 lines
4.5 KiB
Groff
.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
|
|
[
|
|
{
|
|
"pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
|
|
"payload": "00000067000001000100000000000003e90000007b000000000000000000000000000000000000000000000000"
|
|
}, {
|
|
"pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
|
|
"payload": "00000067000003000100000000000003e800000075000000000000000000000000000000000000000000000000"
|
|
}, {
|
|
"style": "legacy",
|
|
"pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
|
|
"payload": "00000067000003000100000000000003e800000075000000000000000000000000000000000000000000000000"
|
|
}
|
|
]
|
|
.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
|
|
|
|
\" SHA256STAMP:287d404b94d0e85eedbc6138b8e7a204723df86ad6d5f984ccfcd03e718ec514
|