09d52b3cb4
The only time underscores aren't special in Markdown is when they appear
in preformatted text. We have gotten away with not escaping underscores
where an asterisk-enclosed span or the paragraph ends before the next
underscore appears, but this is fragile and bad practice. Conversely,
there are many places where we have not escaped underscores but needed
to.
Escape all underscores that do not appear in preformatted blocks or
preformatted spans and are not themselves delineating emphasized spans.
The changes in this commit are exactly the result of executing the
following Bash code:
```bash
e=':x;' # begin loop
e+='s/^' # anchor match at beginning of line
e+='(' # begin capturing subexpression
e+='(' # begin list of alternatives
e+='[^`_\\]|' # any mundane character, or
e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or
e+='\b_|_\b|' # underscore at boundary, or
e+='\\.' # backslash-escaped character
e+=')*' # any number of the preceding alternatives
e+=')' # end capturing subexpression
e+='\B_\B/\1\\_/;' # escape non-formatting underscore
e+='tx' # repeat loop if we escaped an underscore
escape_underscores=(
sed
# use extended regular expressions
-E
# skip over indented blocks (following an empty line)
-e '/^$/{:i;n;/^( {4,}|\t)/bi}'
# skip over preformatted blocks
-e '/^\s*```/,/^\s*```/{p;d}'
# skip over generated sections
-e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}'
# escape underscores
-e "${e}"
)
"${escape_underscores[@]}" -i doc/*.[0-9].md
```
Changelog-None
4.3 KiB
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.
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": "11020203e904017b06080000670000010001"
}, {
"pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
"payload": "11020203e804017506080000670000030001"
}, {
"pubkey": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
"payload": "07020203e8040175"
}
]
The hops parameter is very similar to the result from getroute however it
needs to be modified slightly. The following is the getroute response from
which the above hops parameter was generated:
[
{
"id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
"channel": "103x2x1",
"direction": 1,
"msatoshi": 1002,
"amount_msat": "1002msat",
"delay": 21,
}, {
"id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
"channel": "103x1x1",
"direction": 0,
"msatoshi": 1001,
"amount_msat": "1001msat",
"delay": 15,
}, {
"id": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
"channel": "103x3x1",
"direction": 0,
"msatoshi": 1000,
"amount_msat": "1000msat",
"delay": 9,
}
]
- Notice that the payload in the hops parameter is the hex-encoded TLV
of the parameters in the
getrouteresponse, with length prepended as abigsize_t. - Except for the pubkey, the values are shifted left by one, i.e., the 1st
payload in
createonioncorresponds to the 2nd set of values fromgetroute. - 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 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 internally, and the shared secrets will be returned.
The optional onion_size parameter specifies 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:
- the shared secret with this hop (always 64 characters)
EXAMPLE
The following example is the result of calling createonion with the above hops parameter:
{
"onion": "0003f3f80d2142b953319336d2fe4097[...]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