Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       lightning-createonion - Low-level command to create a custom onion

SYNOPSIS
       createonion hops	assocdata [session_key]

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 c-
       lightning directly.

       The hops	parameter is a JSON list of dicts, each	specifying a node  and
       the  payload destined for that node. The	following is an	example	of a 3
       hop onion:

	      [
		  {
		      "pubkey":	"022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
		      "payload": "00000067000001000100000000000003e90000007b000000000000000000000000000000000000000000000000"
		  }, {
		      "pubkey":	"035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
		      "payload": "00000067000003000100000000000003e800000075000000000000000000000000000000000000000000000000"
		  }, {
		      "style": "legacy",
		      "pubkey":	"0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
		      "payload": "00000067000003000100000000000003e800000075000000000000000000000000000000000000000000000000"
		  }
	      ]

       The hops	parameter is very similar to the result	from getroute  however
       it  needs  to  be  modified slightly. The following is the getroute re-
       sponse from which the above hops	parameter was generated:

	      [
		  {
		      "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
		      "channel": "103x2x1",
		      "direction": 1,
		      "msatoshi": 1002,
		      "amount_msat": "1002msat",
		      "delay": 21,
		      "style": "legacy"
		  }, {
		      "id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
		      "channel": "103x1x1",
		      "direction": 0,
		      "msatoshi": 1001,
		      "amount_msat": "1001msat",
		      "delay": 15,
		      "style": "legacy"
		  }, {
		      "id": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
		      "channel": "103x3x1",
		      "direction": 0,
		      "msatoshi": 1000,
		      "amount_msat": "1000msat",
		      "delay": 9,
		      "style": "legacy"
		  }
	      ]

	      o	     Notice that the payload in	the hops parameter is the hex-
		     encoded  version  of  the	parameters in the getroute re-
		     sponse.

	      o	     The payloads are shifted left by one, i.e., payload 0  in
		     createonion corresponds to	payload	1 from getroute.

	      o	     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    (https://github.com/lightningnetwork/lightning-
       rfc/blob/master/04-onion-routing.md) for	details	and rationale.

       The assocdata parameter specifies 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.

       The optional session_key	parameter 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 in-
       ternally, and the shared	secrets	will be	returned.

RETURN VALUE
       On success, an object containing	the onion and the shared secrets  will
       be returned. Otherwise an error will be reported. The following example
       is the result of	calling	createonion with the above hops	parameter:

	      {
		  "onion": "0003f3f80d2142b953319336d2fe4097[...a...]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.

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

						      LIGHTNING-CREATEONION(7)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | AUTHOR | SEE ALSO | RESOURCES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lightning-createonion&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help