core-lightning/doc/schemas/lightning-createonion.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "rpc": "createonion",
  "title": "Low-level command to create a custom onion",
  "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."
  ],
  "request": {
    "required": [
      "hops",
      "assocdata"
    ],
    "properties": {
      "hops": {
        "type": "array",
        "description": [
          "A JSON list of dicts, each specifying a node and the payload destined for that node."
        ],
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "pubkey",
            "payload"
          ],
          "properties": {
            "pubkey": {
              "type": "pubkey",
              "description": [
                "Node pubkey."
              ]
            },
            "payload": {
              "type": "hex",
              "description": [
                "Payload to be sent to the node."
              ]
            }
          }
        }
      },
      "assocdata": {
        "type": "hex",
        "description": [
          "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": {
        "type": "secret",
        "description": [
          "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": {
        "type": "u16",
        "description": [
          "A size different from the default payment onion (1300 bytes). May be used for custom protocols like trampoline routing."
        ]
      }
    }
  },
  "response": {
    "required": [
      "onion",
      "shared_secrets"
    ],
    "properties": {
      "onion": {
        "type": "hex",
        "description": [
          "The onion packet (*onion_size* bytes)."
        ]
      },
      "shared_secrets": {
        "type": "array",
        "description": [
          "One shared secret for each node in the *hops* parameter."
        ],
        "items": {
          "type": "secret",
          "description": [
            "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>",
    "",
    "[BOLT 04](https://github.com/lightning/bolts/blob/master/04-onion-routing.md)"
  ],
  "examples": [
    {
      "request": {
        "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"
        ]
      }
    },
    {
      "request": {
        "id": "example:createonion#2",
        "method": "createonion",
        "params": [
          [
            {
              "pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
              "payload": "11020203e9040187060800006f0000010000"
            },
            {
              "pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
              "payload": "11020203e804018106080000710000010001"
            },
            {
              "pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
              "payload": "2b020203e80401810822810248b37c63b882804cf746c5b1d7595d26713d89a443ec5808a18ed2327a1903e8"
            }
          ],
          "e445ebcf339db3cba6184330ccc6e4a41e0bb38d237b93c1d2f71958d5a74e13",
          "4141414141414141414141414141414141414141414141414141414141414141"
        ]
      },
      "response": {
        "onion": "0002eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f2836866191c78fd992bdb6323814526c8ea3ab57e22cd7739942f3a3f117d1191ed07d90599edc15c1d83a85b3f00350f4ec0f4b78894d38499e802a15843122723857ebddb629cf308d485de6bdbef80209059e3409ee47154e1b7e8f20d7ce02826c734601240c31ea9fa2c0caea8677b0db9e98835e762cb32e42da32f60bd000fe44350e8e87b69d83363c41d8d22f1639e8701901d74b64bf51f1c21cdc785b54dc5a6ba39fc75f956b60a372f6421a84f6001b294487baf1bb049b7bd901c5854c0999a82095874b02da90021a685f7c77f4b724a3d27489c091807b32bcdfb2c68f69b50c0b43c78288c333dbb007874f36fcf224fbc2ed89690f64a62b5ecfe6275750eb1a5575f689ca6d59c9a570689372db120cf6a29177caaace5ac671a3607d37a3048af18d1d736ac8a4dde8efc4884f8eab23cdc8cb15170471ee7b416b5cf089dee8ab8ac3eea6700a6040839c1e86f6d2b5acf9c7bac856cae96e9d1b7142f91ac4818cf0007a23100ae621470ac2552116f30948f21602237d12d29f58ca73f10f05b38f7b4b728fcfd8aafc1a82502aae3081c4bc8a77771aef16247bcf26d8569140441c405a3c21a649a8439797f45e7c37a2025318f4c88e3eba454fd4cc37e9978b59fa7b1e41af450523713fdad8070c7abdeea299474c99b2bde737e8c8ad79cb9fdd70a935ad29504d185bf100a339d203cd929030454a6450132255fea11ba0c6a520fa7cc3b8638f8032a61c492f7f9d1ec591a851f25df9238945ae467126b64019f21a71a2d3ef46cdd7b61773ad632dc77e0bda7d06b493efe940d9b975ebb85c423a83d24966f5e2ae2ec9c3b2257cc21a4989dd016d688865ba5245667c302e408dc56ffdf4282ad834f0c5af1ce49b3997fe397faf6874cac24ae346b4e72e468506c0e724efe6f805e0fd115de39b6fa29d05e11bbe2ec27548517f93ebd7b977b13237ab9c40ff5766f7263ea1f2eabba460600cd7da082fcf8d0a7bd37054abfd6040f886dde48cf600612b5b73a44026e79d46336de73f2ea5fbfc9603ccd89f6954e5093b6bfe556e6f67deb0878128049186f7ac6ef461a56c2bb4f24a9679fb386e06052c3da2f367f14bc41ec191f5b0b7b3ccad1f2cc58c863c49055c889b8b04b6b6cbaec50d0d103d4ea0da75952a730b07cea0da43914b5ab3f30b5104d9a75eb003da0b5b97bf9eb9081194cc5b50362041a972841bdafde31909929237ed5b94c88dd05126cdb3fd25add0c777c2ad021e1a0e7140d6c4c2005cb353a7a6a747ee75467c052f55faa485cbcf3758eafba7a8ef00d1481cc0f05af539116f443cb02a7b30a3de899dc66cb0781ccccf5c8d93b34be0665d11cbca55cd7a424b958124edf1289c7f4fc19c1be8fc7a861ce47c43a641bafdb195e1c74a1fbf69dbd518013f3dbf2860818b5a3e6f1dd36a5546bfd416e9714dec29818ecd1aeeb29c319b407c497621248d232680417486698a3e1262f03a8bc6441d1de40ae351dae4527a8efe25fc68a3f1571aa556edd6bfb9db7caba4d2c02bab003c43055f5d3ebf961735c3b1f4cd3e0a96038697a95cceac08c0aff084450cf571f81c95d468826aa4292997ccfeba32db77c4c22a9d3caa0a37a8a961ac2f2c8a6965687143bc93c620503839fd7bd7fc2e6d9c966586b713f824b8e9d3de55cb1b81f9204b92dfaa066920c0910e62e59650e904e05b94bde3e467d45719d6a3b85a71c8ff1dcca5a5f497928db5f64c55aad93513e87f4f0c93a6fa5a9afe929cf8223ea509f584913844044aa23a4afa4bc0ad975f4904aab5d77b5e51511460a3b7a982d3b0adcf3fd2ffc2494d16add2825a929fc7c4f0c97159e6fa6aba8569433",
        "shared_secrets": [
          "2d7581974cde41b42da1d0a3147704aae5a71e8987fa30dc920c8cdf784b661d",
          "bb599b824ce9e123c8cb27cd50a996e5035b8ae903356dcbff224496aab3a891",
          "7bc4f97c2d18d5372ef572334e31590ec36b33220d7a71fa4e0fe841174eaccb"
        ]
      }
    }
  ]
}