mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 18:11:28 +01:00
236 lines
16 KiB
JSON
236 lines
16 KiB
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."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"example_usage": [
|
|
"The following is an example of a 3 hop onion:",
|
|
"",
|
|
"```json",
|
|
"[",
|
|
" {",
|
|
" \"pubkey\": \"022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59\",",
|
|
" \"payload\": \"11020203e904017b06080000670000010001\"",
|
|
" }, {",
|
|
" \"pubkey\": \"035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d\",",
|
|
" \"payload\": \"11020203e804017506080000670000030001\"",
|
|
" }, {",
|
|
" \"pubkey\": \"0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199\",",
|
|
" \"payload\": \"07020203e8040175\"",
|
|
" }",
|
|
"]",
|
|
"```",
|
|
"",
|
|
"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,",
|
|
" }, {",
|
|
" \"id\": \"035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d\",",
|
|
" \"channel\": \"103x1x1\",",
|
|
" \"direction\": 0,",
|
|
" \"msatoshi\": 1001,",
|
|
" \"amount_msat\": \"1001msat\",",
|
|
" \"delay\": 15,",
|
|
" }, {",
|
|
" \"id\": \"0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199\",",
|
|
" \"channel\": \"103x3x1\",",
|
|
" \"direction\": 0,",
|
|
" \"msatoshi\": 1000,",
|
|
" \"amount_msat\": \"1000msat\",",
|
|
" \"delay\": 9,",
|
|
" }",
|
|
"]",
|
|
"```",
|
|
"",
|
|
" - Notice that the payload in the *hops* parameter is the hex-encoded TLV of the parameters in the `getroute` response, with length prepended as a `bigsize_t`.",
|
|
" - Except for the pubkey, the values are shifted left by one, i.e., the 1st payload in `createonion` corresponds to the 2nd set of values 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 for details and rationale.",
|
|
"",
|
|
"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**."
|
|
],
|
|
"json_example": [
|
|
{
|
|
"request": {
|
|
"id": "example:createonion#1",
|
|
"method": "createonion",
|
|
"params": {
|
|
"hops": [
|
|
{
|
|
"pubkey": "0266e4598d1d3c415f572a8488830b60f7e744ed9235eb0b1ba93283b315c03518",
|
|
"payload": "e4000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
|
|
},
|
|
{
|
|
"pubkey": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c",
|
|
"payload": "e30000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
|
|
},
|
|
{
|
|
"pubkey": "027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007",
|
|
"payload": "e30000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
|
|
},
|
|
{
|
|
"pubkey": "032c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991",
|
|
"payload": "e30000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
|
|
},
|
|
{
|
|
"pubkey": "02edabbd16b41c8371b92ef2f04c1185b4f03b6dcd52ba9b78d9d7c89c8f221145",
|
|
"payload": "e30000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
|
|
}
|
|
],
|
|
"assocdata": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
|
|
"onion_size": 1301
|
|
}
|
|
},
|
|
"response": {
|
|
"onion": "00034c3f9e11d92555260db3ee4ba0378a645d01c2556451f4289a1d9b43c7afa9a4f9ecc7010dafb26787bb583c514c3b3990d40c8168b1046659d7bc2512d2f1ee0afd2b87c42de2b70102b649634d211b38049593dbb6ed8ee8f93f0b9ff23cd9654c1341137711ce67751d40867cc90c290a9446be2b8a5a43641d4549505b13e807b4240b5b82ffaf22cb534cff01be46db3985ac83b7db465fbd86d4c8d472f60678946c71eca97dd5db732fe5a6d3765e5a5afad72f035207173e7eaaa0da4f0a4540472c7dd269a030428ae586a61b2a70a428055c3848427d2a2e8bd521aadbaf79d56ea39df63c059772e026d57f0b6844c1ab99e936beadf42aaa78193b05f7380e242258deeaa90db316a943d311ef4f2a08f422422c9da454f9666742ad61c6ae003bce83cf6243adf64a728ea50bdaf129ab2ac70e1988a117609cbefc01c884f86b2494349d1067f5cf17760cdab6ae076631693147e8712412d4f0b17cf288b394fd9e29419156ee629966553c2e7598631cbf7493820388eef1ae9f4d2f9da88872e8afbbedb3b46cd7c461cbe4c5491dc6f4a68bc244584bc79b1bb227c869fae16dab4b16412523c984d3ed2b872f63b95a62f66563d2b03c3d1b5fff0290411b293569ce8435b96b447be776b49395a8d94f48cb2f7699a38e8de58d6fff04075d226dcac07668512b6d2c20d4c49d03ad300a52769e4ebbacf97378633126958df1817effc12fd679723123df244fd9b5421f8a2aedb9a8b6fb4049e3a7cae3985059081239bea38351f0c90ed5a0ff45cc492e6ab353e4c13d22ff48912d6ecfda711edfb88dc0767ecfc5dddf8fb0e112a538aeee55c0f73b3b8afc4f40ef3588eabde5b95344a4525adf67841dd67b1db10da180fb346e0bd2958f095d011827063c42361964f8ac2c356d2ec1868a9498dcd6b5915a4df4601c58fcbeb688e14de61300f13183c154b3320cc8e80042a46f22d796f56ff1fdd7e28440c05f14b960c1d0a7c627b09295112bcb635b0e2447a9374fafc4a23ceaf9de4d10b29b2f6cabd7f0c7706cf0404452681d7372d559b644627b2695960deb3b4ae57028e0164b29d5ef9e701d3122b6a5715c502e1dca5252e8c215ed754b01a193041ad9751ed2fff1b55991e256edd6099a38004a367ad097c7caf953da302201263715517f6d32cff57969be994df42fd6cadb649e3c738be798f779aaf4c07cada6bf1e4115b74e2670baf4b1592c70b10a6c043b6606b428b3f79545dc8e9783c876e5402909858f9c604963c37fbc477137c8908e6cfa11ece18c8784a6f25428a5ee1e91d0095fe310d6a91139a7c5c6624bbfcaa15ee847a25b06f57332917f68526a6317f575792e9bcba8576a96bc5859b1f2a00fd8ab08a5ac4ab71833b0b711d1f120cbdb374bcedcdcbeba3806644f5082ec737a945221f5d99562fcbb02a43beeafb16ceecd4e35f06a04c9ff9f4f33725ab62cf22c36650280e4cfb9e150a2c4ebee7785108522e8ecb4682d2d751168e7597299346c3a5e885e36eda66b9a1112997111135767972d771b02c1a36c1d1fb1ce539ecfb98e9e1d8f8fdbf89aec28ad34ff5c00c1a4a8c59848dc8b64c0e65f6f10122e60b4adc1cfc602f49d6cfbdd54be6b0951d3f9cafe8cdd0428f9ce6994844e92d8b72d44edda623bad428b398f88643c3904bda16dd15e886ca4ef6ea7f1450744ac38ffce902569d2e9026bcedd6d0ee54aceabda22bf2de72cba89e6c274064619e32a1192cf2d78b56cf497f7785a6d599de9f8383d1f66f47fc385dc569ee1f08ddbbc7f1aeb0a0126fc4020d948dda10255f11e776db7a037059a40fde38a2ee0c0ce49c7f3df175881bf12371fa72fec3fba657107892a97efe41dcc18aeecd99f3e46c33cf42c2a0ba8b75cf000",
|
|
"shared_secrets": [
|
|
"ccf2512684e2508cb4a842393757e6040b7d25e29d3a2031f29d00a000af6128",
|
|
"d4cec39fe6287d41165bf5c608b0c720a411208a83c64c805a012c86662a2e5a",
|
|
"91bc712ebd4a900e05830394ca8b1f1168777ecdd6996029d96ec8838b9903b9",
|
|
"93c373dcb14dc36ababa3e0c5c55869a667ca175e09913a98c3be67e6af97e16",
|
|
"b2642a5770a6b61ade071fdf69d3ea365cf48434fc2a2c399512778821a33e5c"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"request": {
|
|
"id": "example:createonion#2",
|
|
"method": "createonion",
|
|
"params": {
|
|
"hops": [
|
|
{
|
|
"pubkey": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
|
|
"payload": "0cfdb000084869207468657265"
|
|
}
|
|
],
|
|
"assocdata": "36bf44cc8d80498b95eb05e36ae5811206d3a1d8b5c8d59bbcad035d386a4de8"
|
|
}
|
|
},
|
|
"response": {
|
|
"onion": "0002cdce4bfaa9faa2c060afafe001b80bde07fc670e882c063a80b4738d5f78c9351825c6461cdfcd4fe4144d3b51f63da6351b28dd49c7bfdb0b4f7d8bda4ad0d99699eda39e551084c0a095746c358d1dc6d2eec8082f2aa2f69ae8f61b1f1437ae0ed673078fec6c0510a34058167ad1a34e819a3813d4cf27b2c4917a8c6ca3d70c3381a2a41b4c1b4540adf0e922e25f57d1cfc3064f29cfec4c17244160121975cab59b44c83b4a4905bf7ebfbd308de376334bf86d8aa92c674f7bcfec85680d73e9fee72642c98c603128e358c86e0bc88a60aaebc2637441a57261c61c6be145f00f2fc56164a6495f4b52d3172cb0ef52e91fa0d32a9ae2502d17433bda58d93fbc24a70ec6b5e740952a61404c7370eafe52599c7ee52e77b1cda87c46da98d2ff0d02fe09db5adcb2d2e9bcd083ef58392907b8a21681fa4ea1e4806b4676656457fea000fa504f9b4d159fe8b241266ac91dcc0351053c6dcc1493a6b02bed652cc8b92a8470c98924ebfde6ddc5cf7fd75f6e83a7350642053b70d4834179c30eb56d8c86656cda784daf3b6cd125779bec51099301e3f79f78d85d0454aef8bf5f9058491881b73e99b662b64080cd3eb16fd7f9d9640c18738736cfc15f391232b7df92f46ceb5abf08732ff833e9409ee541d7c926f7a0fe3e233d3eee4a63b65ab23b7c835b7cdd809ddfac8abb1df471fa66a54092815aa41e6fc1a026b86c5675d39c4e8c5c4b4acd48534165239f5634b9e828a7f9df94efcd2a39045efdee4d2f006a63ae828e6e90e3610c522085da6e0198141d6e501d83aba32057f4e59f9b7dfb0bf949c5ef91917cb54561d45a9e7ead049c57deb62d14ba6e18f5d7b0fb9f15e97bf5bd9f909f99c86c787357946654b87c489d34245d07fbb72119166e338b608a4178b452695235dd96bf7fd338e29a9f054ec1a63a442e12602d2329834297f6a197d8a377d608f402f0bcc936f45f33c8d2f9d40e5aef41816dd883add81ca20f1e0631457fe00aa2bd75c9165ffcd96c100c1db83a53aeee23d59f2a542ee3ba39ba62298ddfbd9ecfafd6b5d2121eb003ee23a2ebb8c6b6b687f42492c962510c5acf5231ff96635eba37354559ba39b042d9b6883cac662f418d7c62f9908b2a67964af5e5471804f7684e0d582b8bfec99816bb3442cca1d1fe4efd75d573ebf09fa9cad811063864fb14be4a7768ec2ddb118a77969e986c6584c4b20f8622941ca73d73562857d36e17a46a68d6e10147aaefff1ffb9809f0652a5f760148ed33550661b63c8176d5679e701c221d8a49d4062eb04010ea74cc1132fbeb8934c6e582ba2a16162b7e9171f95bce4ec3e339e70c781f95aaca406cd718b74397658fdefdd093486664be7ed13efa437012f1f57f9f1f4fb4eef7501ccf0e0ac4edc01fde138038c4dd65cb5c3291ad02a6728d6761b1afa35d49bd6ef117012bdd9bd6ee8a175620feb2249aa18d6175351b4bfc2b2b4fd57ff52f5969b109aa9b6cb2cde8f350917c0da2da1bc3d52eb0c7e6080b8f69c5783f2ed26feceb05ba4e7ed66676041d03d0acd3dd6343a85ac0b9c36f9640ddd0db884822f98dc42ea7911a6938dc14ba19d3d25a2b2f82794a2b5dd751dc856d7a9ccdb2d351a0b84e7030fa925ac949a37594f3aa2ba28ae5155b0aaac9c6820b8888d0b8a9db148513b9e3dbde68333ac30a0720289b6a0145d88629d49e76a6d3538330c5aececc9d54127b0a5a0e92d5a5a73beb71132c208b589cab61d53ed357c907929198c559426ae729b374a803dd3321a45ccca39efd39eddaba6e79a2f8911bdf74e18733dc7efc51132b5608d97fd2d0f22fa8961de04cdf6d0dbfbab21e362e7abaef3976f993088aa97ed3f1f4bcf3fffb012f583558bd2f15face9cba20b3e6754b70",
|
|
"shared_secrets": [
|
|
"3f53c03f98eb83db88ff97c2c4004051ce23265ed2414a7aebf7a3e7078839ab"
|
|
]
|
|
}
|
|
}
|
|
],
|
|
"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)"
|
|
]
|
|
}
|