home | help 
LIGHTNING-CREATEONION(7)				LIGHTNING-CREATEONION(7)

NAME
     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 im-
     plement  protocol	extensions  that are not supported by Core Lightning di-
     rectly.

     *	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 pay-
	ment_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 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"
       ]
     }

Core Lightning v26.06.1 				LIGHTNING-CREATEONION(7)
home | help