mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-01-04 04:54:47 +01:00
b9ac032329
The idea is that you regenerate the man pages in the same commit you alter them: that's how we know whether to try regenerating them or not (git doesn't store timestamps, so it can't really tell). Travis will now check this, so force them all to sync to this commit. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
126 lines
4.1 KiB
Markdown
126 lines
4.1 KiB
Markdown
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
|
|
[
|
|
{
|
|
"pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
|
|
"payload": "00000067000001000100000000000003e90000007b000000000000000000000000000000000000000000000000"
|
|
}, {
|
|
"pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
|
|
"payload": "00000067000003000100000000000003e800000075000000000000000000000000000000000000000000000000"
|
|
}, {
|
|
"style": "legacy",
|
|
"pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
|
|
"payload": "00000067000003000100000000000003e800000075000000000000000000000000000000000000000000000000"
|
|
}
|
|
]
|
|
```
|
|
|
|
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
|
|
|