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_hash of 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 <[email protected]> is mainly responsible.

RESOURCES

Main web site: https://github.com/ElementsProject/lightning

BOLT 04

EXAMPLES

Example 1:

Request:

lightning-cli createonion -k "hops"='[{"pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59", "payload": "11020203e9040187060800006f0000010000"}, {"pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d", "payload": "11020203e804018106080000710000010001"}, {"pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199", "payload": "2b020203e80401810822810248b37c63b882804cf746c5b1d7595d26713d89a443ec5808a18ed2327a1903e8"}]' "assocdata"="e445ebcf339db3cba6184330ccc6e4a41e0bb38d237b93c1d2f71958d5a74e13"

{
  "id": "example:createonion#1",
  "method": "createonion",
  "params": {
    "hops": [
      {
        "pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
        "payload": "11020203e9040187060800006f0000010000"
      },
      {
        "pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
        "payload": "11020203e804018106080000710000010001"
      },
      {
        "pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
        "payload": "2b020203e80401810822810248b37c63b882804cf746c5b1d7595d26713d89a443ec5808a18ed2327a1903e8"
      }
    ],
    "assocdata": "e445ebcf339db3cba6184330ccc6e4a41e0bb38d237b93c1d2f71958d5a74e13"
  }
}

Response:

{
  "onion": "0003ccc1f8876af4810e23bd4cccd8f2f38ee5dc117f527c783fefa4e632f857c98d588d2e3150d16b78f9458777502e4829b490e8a2d560841eb0c2368311bf9bb4e8ded0356badafd915839409ad60866c24dd7580b468c14097575565ca95425b9f44211d9ad0305ddba2391a70892ac8c9fd7c3b67d0fe22faf5a0b6905ee2e22278fe224e89ea72c3fcc598b35afaa255123e61ae7a697703e3bb8aec4d36ea487df6ec27942aadff0527d178c897e75f1ee284995196b5ead963ee9d0df798c8265c00c5c73daac917d298cc17e5d813189321d914c45ef30170c4d617dae12bb3a760d1665705e61bb6c52789e15623cefc68d96b86a6f17159c4a86bb196c9f5e40a0744d08d6da0cfd587717b6d0d074d42ac0893fa6ae1497c84824f1d27670d4e201af5e9e5a3493b603cfc209bb0ee41b573ca647c5b9882272c972cd18f19fd895e8995097d86882a473f4d26118a7ed656c5ea04c2a183b05cc0191d07fab5e78edab4ab8ec58e05e03f32d150449c0c8e3505e46ae58e77c87616144873f72f4571b00ccf8e71bcdf33a7d32345aecb660970fa73c4844ab157aa322f140f5d47b66a0590273728ddb5b8a7f3577cff5a268935b93fe598d6df4413c67c45efa9461abaf3294070a484418aa28c03ac20d08856eb0c74dfca851e8ed110bdcacb2a2fb90954b04e99986fde0678846a709120b5d1eeab9cde8d9f27d77448f4591e00bf30d7580703e6c189c658746cf7a7cc1430ce41f84244612b438c3d895333848e5f55e99b2a9d28860863c11aaa8e3ef01ead7ba1545156c356424c33aeeaa2f1e2c290d1d8dd52cd7b8116159025aba26db6fb81ad7f9cc4554c6f9f13d16defe38918b32d62a0516521934a0009a8d37c9a84689bfd8fc1f0beceb92701dca11175e0099d7541698956ba5d93efff996f538ee47717ae6c5cda98111bc28c822e99cf8957b707de270f447b6e52d30bcf9b8a9befd8663bc54612b543d0e167da67e2f295207b70857d0a7cae8932d905db2f48c873dec20aeafa07e15fa98a088e529424c8b404f03ba0ee78a6639fde5cd37dee42877ff6489ce1de5a8992cae25dd20a6521955c19129fdcc0ea157913373bf47a8018a1dd825a2f8e26194d5008161360ae9b25fc701b2accbe88eb47eee6a50b7ee6d6e169e3905e03ca72e00eb6a51b7ed3d27501715428368662b822e2262749d3e7d3243c4fd3d825b3e72bebdeebf6e035f1ad6634523ab5dc0335611c19c9936d006f2e4cd8818eb4f8b4857c8f35d18a4891e35ff91e3b54b384398574d673fcc8da50b22b8f485a41223c97e3b8ee5b8e5ff9c00a2cbfe7360509d3fee9248b5eaa81bb83da3be45dfa8cbbbf5c52ba8749c9d6261d4239feea1e7ce85ad40ad0c66bbeb1c6898626ae4e710a66f9c39a5ee94581353b46e070cfcff9a14e3f9a6108d55bb92852eb3a50e89b1e45d31b760f2a4e263a6a876ad638b123ffee7a2b0b48e16175e3eb92bfaad4dbe0af8b2bc1c15fec5a9d92d3970c2ffab2ab8fa2c9de0bd276680a4284707cd8543a97bca2394e9514236129f1c50a932f7e9bfb98c2aaa6ffc9a4a30641061246de6edf0f711a8d25d59af42ee4445b22ce2f832f3ece52c18ca62d90c590729e04c47accaec95b556ee2541c84843c54a116f5cc45bc251a8023b695f0bf79c43a97bece8a761d387a466821984fb5ec438af20d14cebb7f0026988c81b5a1b895ef94df61aa509e53083b4306c42132b5ce302fd5a2fbb1cee30a7078ccaa3bdccf781b8c9d6ae016a5f8e5cb13f7ac1f3fd0d74a182c9abea67d346f0dfcfc211aaa7ff47196465398fce3e6e0f3b73a944a7f57a90cc6a8f1bfcd385f8312e23af6f508f4f8a976d750660ac3d63630555a3a2e7fe158a982aaf0278d9f8819e5cb",
  "shared_secrets": [
    "7d856ece68ddf5a89b909f888bc0c37207800a6cdba89db12a7cf7e7c26e5209",
    "d1dfacfabba80f07461b890fc660440a105460b687c21bf78f7e6050c2889a98",
    "46ff1895fde58206d5b437d39bb149995456ede6b9af75c0135210efbff23333"
  ]
}

Example 2: