lukechilds
/
lightning
mirror of https://github.com/lukechilds/lightning.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
8930 Commits
55 Branches
107 Tags
38 MiB
Tree: 313976e2f4
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '313976e2f4'
${ noResults }
lightning/doc/lightning-createonion.7.md

126 lines
4.1 KiB
Raw Normal View History

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.
5 years ago
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",
common: make sphinx code ignorant of payload format. Now "raw_payload" is always the complete string (including realm or length bytes at the front). This has several effects: 1. We can receive an decrypt an onion which is grossly malformed. 2. We can still hand this to the htlc_accepted hook. 3. We then fail it unless the htlc_accepted accepts it manually. 4. The createonion API now takes the raw payload, and does not know anything about "style". The only caveat is that the sphinx code needs to know the payload length: we have a call for that, which simply tells it to copy the entire onion (and treat us as the final node) if it's invalid. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
5 years ago
"payload": "00000067000001000100000000000003e90000007b000000000000000000000000000000000000000000000000"
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.
5 years ago
}, {
"pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
common: make sphinx code ignorant of payload format. Now "raw_payload" is always the complete string (including realm or length bytes at the front). This has several effects: 1. We can receive an decrypt an onion which is grossly malformed. 2. We can still hand this to the htlc_accepted hook. 3. We then fail it unless the htlc_accepted accepts it manually. 4. The createonion API now takes the raw payload, and does not know anything about "style". The only caveat is that the sphinx code needs to know the payload length: we have a call for that, which simply tells it to copy the entire onion (and treat us as the final node) if it's invalid. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
5 years ago
"payload": "00000067000003000100000000000003e800000075000000000000000000000000000000000000000000000000"
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.
5 years ago
}, {
json-rpc: Rename onion payload type to style Suggested-by: Rusty Russell <@rustyrussell>
5 years ago
"style": "legacy",
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.
5 years ago
"pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
common: make sphinx code ignorant of payload format. Now "raw_payload" is always the complete string (including realm or length bytes at the front). This has several effects: 1. We can receive an decrypt an onion which is grossly malformed. 2. We can still hand this to the htlc_accepted hook. 3. We then fail it unless the htlc_accepted accepts it manually. 4. The createonion API now takes the raw payload, and does not know anything about "style". The only caveat is that the sphinx code needs to know the payload length: we have a call for that, which simply tells it to copy the entire onion (and treat us as the final node) if it's invalid. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
5 years ago
"payload": "00000067000003000100000000000003e800000075000000000000000000000000000000000000000000000000"
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.
5 years ago
}
]
```
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
doc: force refresh of all manpages. The idea is that you regenerate the man pages in the same commit you alter them: that&#39;s how we know whether to try regenerating them or not (git doesn&#39;t store timestamps, so it can&#39;t really tell). Travis will now check this, so force them all to sync to this commit. Signed-off-by: Rusty Russell &lt;rusty@rustcorp.com.au&gt;
4 years ago