.TH "LIGHTNING-CREATEONION" "7" "" "" "lightning-createonion"
.SH NAME
lightning-createonion - Low-level command to create a custom onion
.SH SYNOPSIS

\fBcreateonion\fR \fIhops\fR \fIassocdata\fR [\fIsession_key\fR] [\fIonion_size\fR]

.SH DESCRIPTION

The \fBcreateonion\fR 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 \fIhops\fR 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:

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

.fi

The \fIhops\fR parameter is very similar to the result from \fBgetroute\fR however it
needs to be modified slightly\. The following is the \fBgetroute\fR response from
which the above \fIhops\fR parameter was generated:

.nf
.RS
[
    {
        "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"
    }
]
.RE

.fi
.RS
.IP \[bu]
Notice that the payload in the \fIhops\fR parameter is the hex-encoded version
of the parameters in the \fBgetroute\fR response\.
.IP \[bu]
Except for the pubkey, the values are shifted left by one, i\.e\., the 1st
payload in \fBcreateonion\fR corresponds to the 2nd set of values from \fBgetroute\fR\.
.IP \[bu]
The final payload is a copy of the last payload sans \fBchannel\fR

.RE

These rules are directly derived from the onion construction\. Please refer
\fBBOLT 04\fR (\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md\fR) for details and rationale\.


The \fIassocdata\fR 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 \fBpayment_hash\fR of the payment in order to be valid\.


The optional \fIsession_key\fR 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 internally, and the
shared secrets will be returned\.


The optional \fIonion_size\fR parameter specifies a size different from the default
payment onion (1300 bytes)\. May be used for custom protocols like trampoline
routing\.

.SH RETURN VALUE

On success, an object is returned, containing:

.RS
.IP \[bu]
\fBonion\fR (hex): the onion packet (\fIonion_size\fR bytes)
.IP \[bu]
\fBshared_secrets\fR (array of hexs): one shared secret for each node in the \fIhops\fR parameter:
.RS
.IP \[bu]
the shared secret with this hop (always 64 characters)

.RE


.RE
.SH EXAMPLE

The following example is the result of calling \fIcreateonion\fR with the
above hops parameter:

.nf
.RS
{
    "onion": "0003f3f80d2142b953319336d2fe4097[...✂...]6af33fcf4fb113bce01f56dd62248a9e5fcbbfba35c",
    "shared_secrets": [
        "88ce98c73e4d9293ab1797b0a913fe9bca0213a566252047d01b8af6da871f3e",
        "4474d296810e57bd460ef8b83d2e7d288321f8a99ff7686f87384699747bcfc4",
        "2a862e4123e01799a732be487fbce297f7dc7cc1467e410f18369cfee476adc2"
    ]
}
.RE

.fi

The \fBonion\fR corresponds to 1366 hex-encoded bytes\. Each shared secret consists
of 32 hex-encoded bytes\. Both arguments can be passed on to \fBsendonion\fR\.

.SH AUTHOR

Christian Decker \fI<decker.christian@gmail.com\fR> is mainly responsible\.

.SH SEE ALSO

\fBlightning-sendonion\fR(7), \fBlightning-getroute\fR(7)

.SH RESOURCES

Main web site: \fIhttps://github.com/ElementsProject/lightning\fR

\" SHA256STAMP:c21aa197637bea17068072cd5907ad3302b48586067a8a5a8d748fd8e7e0a668