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

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "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"
    ],
    "additionalProperties": false,
    "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"
    ],
    "additionalProperties": false,
    "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": "nodeid020202020202020202020202020202020202020202020202020202020202",
              "payload": "payload010101010101010101010101010"
            },
            {
              "pubkey": "nodeid030303030303030303030303030303030303030303030303030303030303",
              "payload": "payload020202020202020202020202020"
            },
            {
              "pubkey": "nodeid040404040404040404040404040404040404040404040404040404040404",
              "payload": "payload030303030303030303030303030"
            }
          ],
          "assocdata": "assocdata0010101010101010101010101010101010101010101010101010101"
        }
      },
      "response": {
        "onion": "onion10101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010",
        "shared_secrets": [
          "sharedsecret1010101010101010101010101010101010101010101010101010",
          "sharedsecret1111111111111111111111111111111111111111111111111111",
          "sharedsecret1212121212121212121212121212121212121212121212121212"
        ]
      }
    },
    {
      "request": {
        "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"
        ]
      }
    }
  ]
}