lightning-createonion -- Low-level command to create a custom onion
SYNOPSIS
createonion hops assocdata [session_key] [onion_size]
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 Core Lightning directly.
- hops (array of objects): A JSON list of dicts, each specifying a node and the payload destined for that node.:
- pubkey (pubkey): Node pubkey.
- payload (hex): Payload to be sent to the node.
- assocdata (hex): 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_hashof the payment in order to be valid. - session_key (secret, optional): 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.
- onion_size (u16, optional): A size different from the default payment onion (1300 bytes). May be used for custom protocols like trampoline routing.
RETURN VALUE
On success, an object is returned, containing:
- onion (hex): The onion packet (onion_size bytes).
- shared_secrets (array of secrets): One shared secret for each node in the hops parameter.:
- (secret, optional): The shared secret with this hop.
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
EXAMPLES
Example 1:
Request:
lightning-cli createonion -k "hops"='[{"pubkey": "nodeid020202020202020202020202020202020202020202020202020202020202", "payload": "payload010101010101010101010101010"}, {"pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303", "payload": "payload020202020202020202020202020"}, {"pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404", "payload": "payload030303030303030303030303030"}]' "assocdata"="assocdata0010101010101010101010101010101010101010101010101010101"
{
"id": "example:createonion#1",
"method": "createonion",
"params": {
"hops": [
{
"pubkey": "nodeid020202020202020202020202020202020202020202020202020202020202",
"payload": "payload010101010101010101010101010"
},
{
"pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303",
"payload": "payload020202020202020202020202020"
},
{
"pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404",
"payload": "payload030303030303030303030303030"
}
],
"assocdata": "assocdata0010101010101010101010101010101010101010101010101010101"
}
}
Response:
{
"onion": "onion10101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010",
"shared_secrets": [
"sharedsecret1010101010101010101010101010101010101010101010101010",
"sharedsecret1111111111111111111111111111111111111111111111111111",
"sharedsecret1212121212121212121212121212121212121212121212121212"
]
}
Example 2:
Request:
lightning-cli createonion -k "hops"='[{"pubkey": "nodeid020202020202020202020202020202020202020202020202020202020202", "payload": "payload010101010101010101010101010"}, {"pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303", "payload": "payload020202020202020202020202020"}, {"pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404", "payload": "payload030303030303030303030303030"}]' "assocdata"="assocdata0010101010101010101010101010101010101010101010101010101" "session_key"="4141414141414141414141414141414141414141414141414141414141414141"
{
"id": "example:createonion#2",
"method": "createonion",
"params": {
"hops": [
{
"pubkey": "nodeid020202020202020202020202020202020202020202020202020202020202",
"payload": "payload010101010101010101010101010"
},
{
"pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303",
"payload": "payload020202020202020202020202020"
},
{
"pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404",
"payload": "payload030303030303030303030303030"
}
],
"assocdata": "assocdata0010101010101010101010101010101010101010101010101010101",
"session_key": "4141414141414141414141414141414141414141414141414141414141414141"
}
}
Response:
{
"onion": "onion20202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020",
"shared_secrets": [
"sharedsecret2020202020202020202020202020202020202020202020202020",
"sharedsecret2121212121212121212121212121212121212121212121212121",
"sharedsecret2222222222222222222222222222222222222222222222222222"
]
}