NAME

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.:

• 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.:

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

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"


  ]
}