├── .gitattributes ├── .travis.yml ├── SECURITY.md ├── README.md ├── tools ├── spellcheck.sh ├── bolt3-bitcoind-test.sh └── extract-formats.py ├── bolt12 ├── format-string-test.json ├── signature-test.json └── offers-test.json ├── .copy-edit-stylesheet-checklist.md ├── bolt04 ├── onion-error-test.json ├── onion-test.json ├── route-blinding-test.json ├── blinded-onion-message-onion-test.json └── blinded-payment-onion-test.json ├── CoC.md ├── .aspell.en.pws ├── CONTRIBUTING.md ├── 10-dns-bootstrap.md ├── 09-features.md ├── bolt07 └── extended-queries.json ├── 00-introduction.md └── proposals └── route-blinding.md /.gitattributes: -------------------------------------------------------------------------------- 1 | *.md linguist-detectable 2 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: python 2 | addons: 3 | apt: 4 | packages: 5 | - aspell-en 6 | 7 | python: 8 | - "3.4" 9 | - "3.5" 10 | - "3.6" 11 | script: 12 | - (set -e; for i in 0?-*.md; do echo "Extracting $i"; python3 tools/extract-formats.py $i; done) 13 | - tools/spellcheck.sh --check *.md 14 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security 2 | 3 | Report security issues to the relevant Lightning implementation teams: 4 | 5 | - [Core Lightning](https://github.com/ElementsProject/lightning/blob/master/SECURITY.md) 6 | - [LND](https://github.com/lightningnetwork/lnd/blob/master/SECURITY.md) 7 | - [Eclair](https://github.com/ACINQ/eclair/blob/master/SECURITY.md) 8 | - [LDK](https://github.com/lightningdevkit/rust-lightning/blob/main/SECURITY.md) 9 | 10 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Lightning Network In-Progress Specifications 2 | 3 | The specifications are currently a work-in-progress and currently being 4 | drafted. 5 | 6 | Pull requests and comments welcome, seeking input from community stakeholders. 7 | 8 | Discussion available on [delving bitcoin](https://delvingbitcoin.org/tag/lightning). 9 | 10 | Previous discussions used the `lightning-dev` mailing list: an archive can be found [here](https://www.mail-archive.com/lightning-dev@lists.linuxfoundation.org/). 11 | 12 | ### [Start here for Table of Contents](00-introduction.md) 13 | 14 | ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY") 15 |
16 | This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). 17 | -------------------------------------------------------------------------------- /tools/spellcheck.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | # spellcheck.sh 3 | # by ZmnSCPxj 4 | # Simple script to spellcheck files. 5 | # 6 | # ZmnSCPxj puts this script into the public domain. 7 | 8 | set -e 9 | 10 | # Check if dirname works. 11 | if (test_dir=`dirname -- /` && test "X"$test_dir = "X/") 12 | then 13 | my_dirname=dirname 14 | else 15 | my_dirname=false 16 | fi 17 | 18 | # Find the path to this script. 19 | # We assume sed works on most systems, since it's very old. 20 | my_dir=`$my_dirname -- "$0" || 21 | echo X"$0" | 22 | sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ 23 | s//\1/ 24 | q 25 | } 26 | /^X\(\/\/\)[^/].*/{ 27 | s//\1/ 28 | q 29 | } 30 | /^X\(\/\/\)$/{ 31 | s//\1/ 32 | q 33 | } 34 | /^X\(\/\).*/{ 35 | s//\1/ 36 | q 37 | } 38 | s/.*/./; q'` 39 | 40 | # This script should be in the tools/ directory of the 41 | # repository. 42 | homedir="$my_dir"/.. 43 | 44 | if [ x"$1" = x"--check" ]; then 45 | CHECK=1 46 | shift 47 | fi 48 | 49 | for f 50 | do 51 | if [ -n "$CHECK" ]; then 52 | # Eliminate the following: 53 | # Inline references eg. [Use of segwit](#use-of-segwit) 54 | # Code blocks using ``` 55 | # quoted identifiers eg. `htlc_id` 56 | # field descriptions, eg. `* [`num_htlcs*64`:`htlc_signature]' 57 | # indented field names, eg. ' `num_htlcs`: 0' 58 | # lightning addresses, eg. `lnbc1qpvj6chq...` 59 | # BIP 173 addresses, eg. `bc1qpvj6chq...` 60 | # Short hex strings, eg '0x2bb038521914 12' 61 | # long hex strings 62 | # long base58 strings 63 | WORDS=$(sed -e 's/ [lL][nN]\([bB][cC]\|[tT][bB]\)[0-9munpxMUNP]*1[qpzry9x8gf2tvdw0s3jn54khce6mua7lQPZRY9X8GF2TVDW0S3JN54KHCE6MUA7L]\+//g' \ 64 | -e 's/\]([-#a-zA-Z0-9_.]*)//g' \ 65 | -e '/^```/,/^```/d' \ 66 | -e 's/`[a-zA-Z0-9_*.(),]*`//g' \ 67 | -e 's/0x[a-fA-F0-9 ]\+//g' \ 68 | -e 's/[a-fA-F0-9]\{20,\}//g' \ 69 | -e 's/^ .*_htlcs//g' \ 70 | -e 's/ ln\(bc\|tb\)[0-9munp]*1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]\+//g' \ 71 | -e 's/ \(bc\|tb\|bcrt\)1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]\+//g' \ 72 | -e 's/pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpquwpc4curk03c9wlrswe78q4eyqc7d8d0xqzpuyk0sg5g70me25alkluzd2x62aysf2pyy8edtjeevuv4p2d5p76r4zkmneet7uvyakky2zr4cusd45tftc9c5fh0nnqpnl2jfll544esqchsrny//' \ 73 | -e 's/[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]\{20,\}//g' < $f | tee /tmp/`basename $f`.aspell | aspell -l en_US --home-dir ${homedir} list) 74 | if [ -n "$WORDS" ]; then 75 | echo Misspelled words in $f: $WORDS >&2 76 | exit 1 77 | fi 78 | else 79 | aspell -l en_US --home-dir ${homedir} -c $f 80 | fi 81 | done 82 | -------------------------------------------------------------------------------- /bolt12/format-string-test.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "comment": "A complete string is valid", 4 | "valid": true, 5 | "string": "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg" 6 | }, 7 | { 8 | "comment": "Uppercase is valid", 9 | "valid": true, 10 | "string": "LNO1PQPS7SJQPGTYZM3QV4UXZMTSD3JJQER9WD3HY6TSW35K7MSJZFPY7NZ5YQCNYGRFDEJ82UM5WF5K2UCKYYPWA3EYT44H6TXTXQUQH7LZ5DJGE4AFGFJN7K4RGRKUAG0JSD5XVXG" 11 | }, 12 | { 13 | "comment": "+ can join anywhere", 14 | "valid": true, 15 | "string": "l+no1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg" 16 | }, 17 | { 18 | "comment": "Multiple + can join", 19 | "valid": true, 20 | "string": "lno1pqps7sjqpgt+yzm3qv4uxzmtsd3jjqer9wd3hy6tsw3+5k7msjzfpy7nz5yqcn+ygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd+5xvxg" 21 | }, 22 | { 23 | "comment": "+ can be followed by whitespace", 24 | "valid": true, 25 | "string": "lno1pqps7sjqpgt+ yzm3qv4uxzmtsd3jjqer9wd3hy6tsw3+ 5k7msjzfpy7nz5yqcn+\nygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd+\r\n 5xvxg" 26 | }, 27 | { 28 | "comment": "+ can be followed by whitespace, UPPERCASE", 29 | "valid": true, 30 | "string": "LNO1PQPS7SJQPGT+ YZM3QV4UXZMTSD3JJQER9WD3HY6TSW3+ 5K7MSJZFPY7NZ5YQCN+\nYGRFDEJ82UM5WF5K2UCKYYPWA3EYT44H6TXTXQUQH7LZ5DJGE4AFGFJN7K4RGRKUAG0JSD+\r\n 5XVXG" 31 | }, 32 | { 33 | "comment": "Mixed case is invalid", 34 | "valid": false, 35 | "string": "LnO1PqPs7sJqPgTyZm3qV4UxZmTsD3JjQeR9Wd3hY6TsW35k7mSjZfPy7nZ5YqCnYgRfDeJ82uM5Wf5k2uCkYyPwA3EyT44h6tXtXqUqH7Lz5dJgE4AfGfJn7k4rGrKuAg0jSd5xVxG" 36 | }, 37 | { 38 | "comment": "+ must be surrounded by bech32 characters", 39 | "valid": false, 40 | "string": "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg+" 41 | }, 42 | { 43 | "comment": "+ must be surrounded by bech32 characters", 44 | "valid": false, 45 | "string": "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg+ " 46 | }, 47 | { 48 | "comment": "+ must be surrounded by bech32 characters", 49 | "valid": false, 50 | "string": "+lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg" 51 | }, 52 | { 53 | "comment": "+ must be surrounded by bech32 characters", 54 | "valid": false, 55 | "string": "+ lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg" 56 | }, 57 | { 58 | "comment": "+ must be surrounded by bech32 characters", 59 | "valid": false, 60 | "string": "ln++o1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg" 61 | } 62 | ] 63 | -------------------------------------------------------------------------------- /.copy-edit-stylesheet-checklist.md: -------------------------------------------------------------------------------- 1 | # Basic checklist/stylesheet used for copy editing BOLTs 2 | 3 | Contributions should comply with this checklist/stylesheet to maintain correct, clear, consistent, and concise BOLTS. 4 | 5 | - spelling 6 | - run `tools/spellcheck.sh --check [0-9][0-9]-*.md` 7 | - update `.aspell.en.pws` with any missing words 8 | - typos 9 | - sentence structure 10 | - sentence fragments 11 | - run-on sentences 12 | - dangling, misplaced modifiers 13 | - consistent paragraph tense (e.g. past, present, future) 14 | - passive voice (e.g. avoid 'we') 15 | - use 'local/remote' terminology rather than 'us/them' or 'we/they' 16 | - exception: `Introduction` section 17 | - capitalization 18 | - table of contents 19 | - headers 20 | - capitalize list items containing complete sentences 21 | - commonly forgotten: 'Lightning', 'ID' 22 | - distinguish between network and currency unit 23 | - e.g. "The Bitcoin network transfers bitcoins." 24 | - punctuation 25 | - correct comma, colon, semi-colon, em-dash placement 26 | - for conjoined items, use comma before conjunction 27 | - e.g. 'this, that, and the other' 28 | - appropriate use of parenthesis 29 | - only use periods after list items if they contain complete sentences 30 | - exceptions: `Requirements` lists 31 | - abbreviations 32 | - e.g., i.e., etc., a.k.a. 33 | - formatting 34 | - single spaces between sentences 35 | - consistent use of _emphasis_, **strong**, `code`, CAPS, 'quotes' 36 | - single line separators between paragraphs and page elements 37 | - ensure correct header weights 38 | - numbers and calculations 39 | - spell out small (<10) amounts 40 | - type digits and enumerations 41 | - e.g. 'two 2-byte blocks set to 0s', 'one 4-byte block set to 1s', 'the other one is equal to 1' 42 | - exceptions, e.g. 'non-zero', '1 byte in length' 43 | - data measurements 44 | - type digits for quantities of information, use hyphen when unit is an adjective 45 | - e.g. 'a 32-bit block is 32 bits in length' 46 | - for typed calculations 47 | - space both sides of operators (except '^' and negative numbers) 48 | - e.g. 5 - 3^2 * 4 = -31 49 | - for calculation descriptions 50 | - write out operators 51 | - e.g. 1 less than 3 equals 2 52 | - list structure 53 | - 2 spaces before item 54 | - indent 2 spaces 55 | - `Requirements` sections 56 | - colon after conditions 57 | - comma before sub-items 58 | - period at branch ends 59 | - example: 60 | ``` 61 | A sending node: 62 | - MAY do this. 63 | - if this, AND this: 64 | - SHOULD do this. 65 | - otherwise: 66 | - MUST do this, 67 | - but MUST NOT...in this case. 68 | ``` 69 | - links 70 | - broken links 71 | - link text 72 | - correct anchors/urls 73 | - references 74 | - format e.g. [1](#reference-1) 75 | - tags 76 | - consistent usage, e.g. [TODO:], [FIXME:] 77 | -------------------------------------------------------------------------------- /bolt04/onion-error-test.json: -------------------------------------------------------------------------------- 1 | { 2 | "comment": "A simple error returned by node hops[4], the public/private keys and shared_secrets are identical to the ones used in `onion-test-v0.json`", 3 | "generate": { 4 | "session_key": "4141414141414141414141414141414141414141414141414141414141414141", 5 | "failure_message": "2002", 6 | "hops": [ 7 | { 8 | "version": 0, 9 | "pubkey": "02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619", 10 | "hop_shared_secret": "53eb63ea8a3fec3b3cd433b85cd62a4b145e1dda09391b348c4e1cd36a03ea66", 11 | "ammag_key": "3761ba4d3e726d8abb16cba5950ee976b84937b61b7ad09e741724d7dee12eb5" 12 | }, 13 | { 14 | "version": 0, 15 | "pubkey": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c", 16 | "hop_shared_secret": "a6519e98832a0b179f62123b3567c106db99ee37bef036e783263602f3488fae", 17 | "ammag_key": "59ee5867c5c151daa31e36ee42530f429c433836286e63744f2020b980302564" 18 | }, 19 | { 20 | "version": 0, 21 | "pubkey": "027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007", 22 | "hop_shared_secret": "3a6b412548762f0dbccce5c7ae7bb8147d1caf9b5471c34120b30bc9c04891cc", 23 | "ammag_key": "1bf08df8628d452141d56adfd1b25c1530d7921c23cecfc749ac03a9b694b0d3" 24 | }, 25 | { 26 | "version": 0, 27 | "pubkey": "032c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991", 28 | "hop_shared_secret": "21e13c2d7cfe7e18836df50872466117a295783ab8aab0e7ecc8c725503ad02d", 29 | "ammag_key": "cd9ac0e09064f039fa43a31dea05f5fe5f6443d40a98be4071af4a9d704be5ad" 30 | }, 31 | { 32 | "version": 0, 33 | "pubkey": "02edabbd16b41c8371b92ef2f04c1185b4f03b6dcd52ba9b78d9d7c89c8f221145", 34 | "hop_shared_secret": "b5756b9b542727dbafc6765a49488b023a725d631af688fc031217e90770c328", 35 | "um_key": "4da7f2923edce6c2d85987d1d9fa6d88023e6c3a9c3d20f07d3b10b61a78d646", 36 | "ammag_key": "2f36bb8822e1f0d04c27b7d8bb7d7dd586e032a3218b8d414afbba6f169a4d68", 37 | "payload": "0002200200fe0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", 38 | "comment": "hops[4] is the only node that needs a mu_key since it is the only node that computes an HMAC of the original error message, the payload is omits the HMAC." 39 | } 40 | ] 41 | }, 42 | "errorpacket": "9c5add3963fc7f6ed7f148623c84134b5647e1306419dbe2174e523fa9e2fbed3a06a19f899145610741c83ad40b7712aefaddec8c6baf7325d92ea4ca4d1df8bce517f7e54554608bf2bd8071a4f52a7a2f7ffbb1413edad81eeea5785aa9d990f2865dc23b4bc3c301a94eec4eabebca66be5cf638f693ec256aec514620cc28ee4a94bd9565bc4d4962b9d3641d4278fb319ed2b84de5b665f307a2db0f7fbb757366067d88c50f7e829138fde4f78d39b5b5802f1b92a8a820865af5cc79f9f30bc3f461c66af95d13e5e1f0381c184572a91dee1c849048a647a1158cf884064deddbf1b0b88dfe2f791428d0ba0f6fb2f04e14081f69165ae66d9297c118f0907705c9c4954a199bae0bb96fad763d690e7daa6cfda59ba7f2c8d11448b604d12d" 43 | } 44 | -------------------------------------------------------------------------------- /bolt04/onion-test.json: -------------------------------------------------------------------------------- 1 | { 2 | "comment": "A testcase for a variable length hop_payload. The third payload is 275 bytes long. All the payloads already have the variable length encoded.", 3 | "generate": { 4 | "session_key": "4141414141414141414141414141414141414141414141414141414141414141", 5 | "associated_data": "4242424242424242424242424242424242424242424242424242424242424242", 6 | "hops": [ 7 | { 8 | "pubkey": "02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619", 9 | "payload": "1202023a98040205dc06080000000000000001" 10 | }, 11 | { 12 | "pubkey": "0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c", 13 | "payload": "52020236b00402057806080000000000000002fd02013c0102030405060708090a0b0c0d0e0f0102030405060708090a0b0c0d0e0f0102030405060708090a0b0c0d0e0f0102030405060708090a0b0c0d0e0f" 14 | }, 15 | { 16 | "pubkey": "027f31ebc5462c1fdce1b737ecff52d37d75dea43ce11c74d25aa297165faa2007", 17 | "payload": "12020230d4040204e206080000000000000003" 18 | }, 19 | { 20 | "pubkey": "032c0b7cf95324a07d05398b240174dc0c2be444d96b159aa6c7f7b1e668680991", 21 | "payload": "1202022710040203e806080000000000000004" 22 | }, 23 | { 24 | "pubkey": "02edabbd16b41c8371b92ef2f04c1185b4f03b6dcd52ba9b78d9d7c89c8f221145", 25 | "payload": "fd011002022710040203e8082224a33562c54507a9334e79f0dc4f17d407e6d7c61f0e2f3d0d38599502f617042710fd012de02a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a" 26 | } 27 | ] 28 | }, 29 | "onion": "0002eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619f7f3416a5aa36dc7eeb3ec6d421e9615471ab870a33ac07fa5d5a51df0a8823aabe3fea3f90d387529d4f72837f9e687230371ccd8d263072206dbed0234f6505e21e282abd8c0e4f5b9ff8042800bbab065036eadd0149b37f27dde664725a49866e052e809d2b0198ab9610faa656bbf4ec516763a59f8f42c171b179166ba38958d4f51b39b3e98706e2d14a2dafd6a5df808093abfca5aeaaca16eded5db7d21fb0294dd1a163edf0fb445d5c8d7d688d6dd9c541762bf5a5123bf9939d957fe648416e88f1b0928bfa034982b22548e1a4d922690eecf546275afb233acf4323974680779f1a964cfe687456035cc0fba8a5428430b390f0057b6d1fe9a8875bfa89693eeb838ce59f09d207a503ee6f6299c92d6361bc335fcbf9b5cd44747aadce2ce6069cfdc3d671daef9f8ae590cf93d957c9e873e9a1bc62d9640dc8fc39c14902d49a1c80239b6c5b7fd91d05878cbf5ffc7db2569f47c43d6c0d27c438abff276e87364deb8858a37e5a62c446af95d8b786eaf0b5fcf78d98b41496794f8dcaac4eef34b2acfb94c7e8c32a9e9866a8fa0b6f2a06f00a1ccde569f97eec05c803ba7500acc96691d8898d73d8e6a47b8f43c3d5de74458d20eda61474c426359677001fbd75a74d7d5db6cb4feb83122f133206203e4e2d293f838bf8c8b3a29acb321315100b87e80e0edb272ee80fda944e3fb6084ed4d7f7c7d21c69d9da43d31a90b70693f9b0cc3eac74c11ab8ff655905688916cfa4ef0bd04135f2e50b7c689a21d04e8e981e74c6058188b9b1f9dfc3eec6838e9ffbcf22ce738d8a177c19318dffef090cee67e12de1a3e2a39f61247547ba5257489cbc11d7d91ed34617fcc42f7a9da2e3cf31a94a210a1018143173913c38f60e62b24bf0d7518f38b5bab3e6a1f8aeb35e31d6442c8abb5178efc892d2e787d79c6ad9e2fc271792983fa9955ac4d1d84a36c024071bc6e431b625519d556af38185601f70e29035ea6a09c8b676c9d88cf7e05e0f17098b584c4168735940263f940033a220f40be4c85344128b14beb9e75696db37014107801a59b13e89cd9d2258c169d523be6d31552c44c82ff4bb18ec9f099f3bf0e5b1bb2ba9a87d7e26f98d294927b600b5529c47e04d98956677cbcee8fa2b60f49776d8b8c367465b7c626da53700684fb6c918ead0eab8360e4f60edd25b4f43816a75ecf70f909301825b512469f8389d79402311d8aecb7b3ef8599e79485a4388d87744d899f7c47ee644361e17040a7958c8911be6f463ab6a9b2afacd688ec55ef517b38f1339efc54487232798bb25522ff4572ff68567fe830f92f7b8113efce3e98c3fffbaedce4fd8b50e41da97c0c08e423a72689cc68e68f752a5e3a9003e64e35c957ca2e1c48bb6f64b05f56b70b575ad2f278d57850a7ad568c24a4d32a3d74b29f03dc125488bc7c637da582357f40b0a52d16b3b40bb2c2315d03360bc24209e20972c200566bcf3bbe5c5b0aedd83132a8a4d5b4242ba370b6d67d9b67eb01052d132c7866b9cb502e44796d9d356e4e3cb47cc527322cd24976fe7c9257a2864151a38e568ef7a79f10d6ef27cc04ce382347a2488b1f404fdbf407fe1ca1c9d0d5649e34800e25e18951c98cae9f43555eef65fee1ea8f15828807366c3b612cd5753bf9fb8fced08855f742cddd6f765f74254f03186683d646e6f09ac2805586c7cf11998357cafc5df3f285329366f475130c928b2dceba4aa383758e7a9d20705c4bb9db619e2992f608a1ba65db254bb389468741d0502e2588aeb54390ac600c19af5c8e61383fc1bebe0029e4474051e4ef908828db9cca13277ef65db3fd47ccc2179126aaefb627719f421e20", 30 | "decode": [ 31 | "4141414141414141414141414141414141414141414141414141414141414141", 32 | "4242424242424242424242424242424242424242424242424242424242424242", 33 | "4343434343434343434343434343434343434343434343434343434343434343", 34 | "4444444444444444444444444444444444444444444444444444444444444444", 35 | "4545454545454545454545454545454545454545454545454545454545454545" 36 | ] 37 | } 38 | -------------------------------------------------------------------------------- /tools/bolt3-bitcoind-test.sh: -------------------------------------------------------------------------------- 1 | #! /bin/sh 2 | 3 | # To run all tests, try: 4 | # grep 'name: .*commitment tx' ../03-transactions.md | cut -d: -f2- | while read t; do ./bolt3-test-vector.sh $t || break; done 5 | 6 | TESTDIR=/tmp/bolt3-testdir.$$ 7 | BOLT3=../03-transactions.md 8 | 9 | set -e 10 | CLI="bitcoin-cli -datadir=$TESTDIR" 11 | TEST=$TESTDIR/test 12 | 13 | VERBOSE=: 14 | VERBOSEPIPE=: 15 | if [ x"$1" = x"--verbose" ]; then 16 | VERBOSE=echo 17 | VERBOSEPIPE=cat 18 | shift 19 | fi 20 | 21 | # FIXME: This doesn't work in 0.14 (see bitcoin-core commit 22 | # 7d4e9509ade0c258728011d8f6544ec3e75d63dc) 23 | #FEELESS_TXS_OK=${FEELESS_TXS_OK:-true} 24 | FEELESS_TXS_OK=${FEELESS_TXS_OK:-false} 25 | 26 | # Comment this out to postmortem 27 | trap "$CLI stop >/dev/null 2>&1 || true; sleep 1; rm -rf $TESTDIR" EXIT 28 | 29 | if [ $# -lt 1 ]; then 30 | echo Usage: $0 "[--verbose] ..." >&2 31 | exit 1 32 | fi 33 | 34 | # Usage 35 | extract_fields() 36 | { 37 | grep "^ $1:" $2 || true 38 | } 39 | 40 | # Usage 41 | extract_field() 42 | { 43 | if [ $(grep -c "^ $1:" $2) != 1 ]; then 44 | echo "Ambiguous field $1" >&2 45 | exit 1 46 | fi 47 | extract_fields "$@" | cut -d: -f2- 48 | } 49 | 50 | # Usage 51 | htlc_property() 52 | { 53 | extract_field "htlc $1 $2" $3 54 | } 55 | 56 | # Usage 57 | extract_test() 58 | { 59 | print=: 60 | found=false 61 | while read LINE; do 62 | case "$LINE" in 63 | "name: $1") 64 | print=echo 65 | $print " $LINE" 66 | found=true 67 | ;; 68 | "name:"*|"") 69 | print=true 70 | ;; 71 | *) 72 | $print " $LINE" 73 | ;; 74 | esac 75 | done < $BOLT3 76 | 77 | if ! $found; then 78 | echo "No test $1 found" >&2 79 | exit 1 80 | fi 81 | } 82 | 83 | mkdir $TESTDIR 84 | echo regtest=1 > $TESTDIR/bitcoin.conf 85 | echo rpcbind=127.0.0.1 >> $TESTDIR/bitcoin.conf 86 | echo rpcport=18333 >> $TESTDIR/bitcoin.conf 87 | echo rpcpassword=$(od -tx1 -A none -N20 < /dev/urandom | tr -d ' ') >> $TESTDIR/bitcoin.conf 88 | 89 | if $FEELESS_TXS_OK; then 90 | echo minrelaytxfee=0 >> $TESTDIR/bitcoin.conf 91 | else 92 | echo minrelaytxfee=0.00000001 >> $TESTDIR/bitcoin.conf 93 | fi 94 | 95 | $VERBOSE Starting bitcoind 96 | bitcoind -datadir=$TESTDIR & 97 | 98 | i=0 99 | while ! $CLI getinfo >/dev/null 2>&1; do 100 | sleep 0.1 101 | i=$(($i + 1)) 102 | if [ $i -ge 50 ]; then 103 | echo Bitcoind failed to start >&2 104 | exit 1 105 | fi 106 | done 107 | 108 | $VERBOSE Checking bitcoind genesis block matches BOLT3 109 | GENESIS=$($CLI getblock $($CLI getblockhash 0) false) 110 | 111 | if [ $GENESIS != $(extract_field 'Block 0 (genesis)' $BOLT3) ]; then 112 | echo Bad genesis block >&2 113 | exit 1 114 | fi 115 | 116 | $VERBOSE Submitting block '#1' from BOLT3 117 | $CLI submitblock $(extract_field 'Block 1' $BOLT3) 118 | # To activate segwit via BIP9, we need at least 432 blocks! Also lets us spend tx. 119 | 120 | $VERBOSE Activating SegWit 121 | $CLI generate 432 > /dev/null 122 | 123 | $VERBOSE Sending funding transaction from BOLT3 124 | TXID=$($CLI sendrawtransaction $(extract_field 'funding tx' $BOLT3)) 125 | if [ $TXID != $(extract_field '# txid' $BOLT3) ]; then 126 | echo Bad funding txid >&2 127 | exit 1 128 | fi 129 | 130 | echo -n Running \""$*"\":\ 131 | 132 | extract_test "$*" > $TEST 133 | if ! $FEELESS_TXS_OK && [ $(extract_field 'local_feerate_per_kw' $TEST) = 0 ] 134 | then 135 | echo SKIPPED 136 | $VERBOSE "Override by prepending FEELESS_TXS_OK=true to commandline" 137 | exit 0 138 | fi 139 | 140 | # In verbose mode, we need a CR here. 141 | $VERBOSE 142 | 143 | TX=$(extract_field 'output commit_tx' $TEST) 144 | $VERBOSE -n "Submitting commit_tx: " 145 | $CLI sendrawtransaction $TX | $VERBOSEPIPE 146 | 147 | # We can use success txs immediately 148 | extract_fields 'output htlc_success_tx [0-9]*' $TEST | while read TX; do 149 | $VERBOSE -n "Submitting ${TX%%:*}: " 150 | $CLI sendrawtransaction ${TX#*:} | $VERBOSEPIPE 151 | done 152 | 153 | # Timeout txs have to wait for timeout; fortunately they're in order. 154 | extract_fields 'output htlc_timeout_tx [0-9]*' $TEST | while read TX; do 155 | TITLE=${TX%%:*} 156 | HTLC=${TITLE##* } 157 | EXPIRY=$(htlc_property $HTLC expiry $BOLT3) 158 | # Should fail before expiry. 159 | $CLI generate $(($EXPIRY - 1 - $($CLI getblockcount) )) >/dev/null 160 | HEIGHT=$EXPIRY-1 161 | $VERBOSE -n "Submitting ${TX%%:*} TOO EARLY: " 162 | if $CLI sendrawtransaction ${TX#*:} > $TESTDIR/too-early 2>&1; then 163 | $VERBOSE $TESTDIR/too-early 164 | echo "Timeout worked at blockheight $($CLI getblockcount) not $EXPIRY" >&2 165 | exit 1 166 | fi 167 | tail -n1 $TESTDIR/too-early | $VERBOSEPIPE 168 | $CLI generate 1 >/dev/null 169 | $VERBOSE -n "Submitting ${TX%%:*}: " 170 | $CLI sendrawtransaction ${TX#*:} | $VERBOSEPIPE 171 | done 172 | 173 | echo Success 174 | exit 0 175 | -------------------------------------------------------------------------------- /CoC.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | The lightning spec community is open to pretty much anyone. To ensure that project forums are open and friendly, we count on maintainers and project representatives to behave in a way that is not disruptive to any one participant's well-being. 4 | 5 | Therefore, we came up with some easy to follow guidelines. 6 | * Be friendly. Interact in a way that fosters openness, inclusivity, and collaboration. 7 | * Be respectful. We may disagree, but disagreement is no excuse for rude behavior or personal attacks. 8 | * Be considerate. Provide and accept constructive criticism. 9 | 10 | Private or public harassment of any kind will not be tolerated. Since harassment can take many forms, here's a non-exhaustive list of what we consider unacceptable behavior: 11 | * Offensive language directed at individuals or groups of people 12 | * Bullying (verbal, physical, social, or cyber) 13 | * Interfering with someone's ability to contribute, like with excessive nitpicking 14 | * Continued one-on-one communication after a party has requested it cease 15 | * Stalking online or offline 16 | * Doxing or unauthorized publication of private information or communication 17 | * Unwelcomed sexual attention 18 | * Inappropriate visual displays such as sexually-oriented or offensive photography, cartoons, drawings, or gestures 19 | * Retaliation for reporting or threatening to report harassment 20 | 21 | Additionally, spam and other content which disrupts or prevents contributors from working is not acceptable. 22 | 23 | ## The Code of Conduct Team 24 | 25 | A small team of contributors has volunteered to enforce this Code of Conduct. If you feel like a community member has engaged in inappropriate behavior, please don't hesitate to contact one of the following contributors via email: 26 | * Vincenzo Palazzo - vincenzopalazzo on member.fsf.org 27 | * Rusty Russell - rusty on rustcorp.com.au 28 | 29 | ## The Code of Conduct Team’s Responsibilities 30 | 31 | Team members are tasked with acknowledging reports within 24 hours. They will review each incident and determine, to the best of their ability: 32 | * Does the event constitute a Code of Conduct violation? 33 | * Is the behavior on our list of inappropriate behavior? Is it borderline inappropriate? 34 | * Did the event occur in a space within our Code of Conduct's scope? 35 | * If the incident occurred outside community forums and the individual is seen as a project representative or identifies as a contributor, the incident may be in scope. 36 | * Additionally, an incident may be in scope if a community member's ability to contribute to the lightning spec is impacted. 37 | * Did this incident occur in a private conversation or in a public space? 38 | * Is the situation isolated or ongoing? 39 | * How is the reported person's behavior negatively impacting others? 40 | * Does the incident impact the ability of individuals to freely contribute to the lightning spec? 41 | * Does this incident include sexual harassment? 42 | * Does this pose a safety risk or severely negatively impact someone's mental health? 43 | * Is there a risk of this behavior being repeated? 44 | * Does the reported person understand why their behavior was inappropriate? 45 | 46 | If a report is insufficiently detailed or involves multiple parties, the Code of Conduct Team may seek additional information from witnesses or the accused. Neither party should contact the other to discuss the incident. Likewise, the team will do its best not to disclose who reported a given incident, either to the accused or generally, though we recognize that circumstantial disclosures to the accused might be unavoidable. 47 | 48 | The Code of Conduct Team aims to resolve all reports within one week. If a resolution is not possible within that time frame, the team will respond to the reporter(s) with an adjusted one. 49 | 50 | ## Possible responses to an incident include: 51 | 52 | ### Taking no further action: 53 | If the Code of Conduct Team determines that no action is needed, they will inform the reporter. 54 | 55 | ### Simple warning: 56 | This applies to disruptive behavior, but not insulting behavior. The Code of Conduct Team will contact the individual(s) and request that they stop. 57 | 58 | ### Final warning: 59 | If an incident or series of incidents creates sustained toxicity within the lightning spec community, the Code of Conduct Team will sternly warn the reported party and raise the possibility of further disciplinary action. In addition, they may request that the reported party: 60 | * Not use specific language 61 | * Not participate in specific types of discussions 62 | * Not send private messages to a community member 63 | * Not review a particular person's PRs on GitHub (but still allow them to privately share review comments with a maintainer) 64 | * Not lead sub-projects like code review sessions 65 | * Take a step away for a short period to cool off 66 | * Lose maintainer/merge access 67 | 68 | ### 2-3 months imposed break: 69 | If the Code of Conduct Team’s warning goes unheeded, the individual(s) may be asked to avoid participating with the lightning spec community on its preferred platforms for several months. After time has passed, the individual(s) will have the option of meeting with the team to discuss returning to the community. 70 | 71 | ### Extended or permanent ban: 72 | If a temporary break does not remedy a serious offense, the offender may be removed or banned from the Github repository. The Code of Conduct Team may also choose to un-ban a user for a first offense, depending on its severity and pending that the user has offered the offended party a genuine apology. 73 | -------------------------------------------------------------------------------- /.aspell.en.pws: -------------------------------------------------------------------------------- 1 | personal_ws-1.1 en 264 2 | bitfields 3 | checksums 4 | timestamps 5 | tlv 6 | tlvs 7 | subtype 8 | TLV 9 | py 10 | vsprintf 11 | glibc 12 | JSON 13 | Freenode 14 | nacks 15 | secp 16 | sig 17 | unguessable 18 | libsecp 19 | TCP 20 | DER 21 | micropayments 22 | nhops 23 | retransmitted 24 | dev 25 | tradeoff 26 | kiloweight 27 | mixHeader 28 | uint 29 | hopsData 30 | bitfield 31 | B'th 32 | decrypting 33 | rhokey 34 | rhoKey 35 | buf 36 | millisatoshis 37 | yToX 38 | funder's 39 | IRATEMONK 40 | wpkh 41 | nextHmac 42 | basepoint 43 | streamKey 44 | localpubkey 45 | paymentPath 46 | SPV 47 | HopData 48 | CSV 49 | xFFFFFFFFFF 50 | plaintext 51 | EQUALVERIFY 52 | AEAD 53 | secretkey 54 | TripleDH 55 | addr 56 | CHECKMULTISIG 57 | decryptWithAD 58 | routable 59 | epk 60 | scriptpubkey 61 | mukey 62 | muKey 63 | sharedSecretSize 64 | DUP 65 | sharedSecrets 66 | xFFFFFFFFFFFF 67 | cryptographic 68 | generateSharedSecret 69 | instantiations 70 | deterministically 71 | deduplication 72 | FIPS 73 | responder 74 | UTF 75 | blockchain 76 | Blockstream 77 | nSequence 78 | decrypt 79 | flen 80 | incrementing 81 | feerate 82 | affine 83 | CHECKSEQUENCEVERIFY 84 | nonces 85 | iff 86 | serializeCompressed 87 | prepended 88 | roasbeef 89 | multisig 90 | nodepk 91 | remotesig 92 | hopBlindingFactors 93 | ECDH 94 | addrlen 95 | assocData 96 | ActOne 97 | ammag 98 | computeBlindingFactor 99 | wsh 100 | multiScalarMult 101 | onionpacket 102 | OnionPacket 103 | ikm 104 | fillerSize 105 | txinput 106 | init 107 | reconnection 108 | milli 109 | revocationsig 110 | NOTIF 111 | generateHeaderPadding 112 | IPv 113 | ipv 114 | satoshi 115 | delayedsig 116 | hopDataSize 117 | I'th 118 | segwit 119 | RBF 120 | accepter 121 | accepter's 122 | subtype 123 | redeemScript 124 | scriptSig 125 | utxo 126 | scriptPubKey 127 | scriptPubKeys 128 | scriptlen 129 | sats 130 | htlc 131 | htlcs 132 | ChaCha 133 | len 134 | ciphertext 135 | endian 136 | C'mon 137 | NewOnionPacket 138 | keypair 139 | preimage 140 | MiTM 141 | mempool 142 | cltv 143 | localfeatures 144 | iteratively 145 | PrivateKey 146 | br 147 | millisatoshi 148 | trustless 149 | ee 150 | eg 151 | hopSize 152 | retransmit 153 | retransmittal 154 | deobfuscating 155 | onchain 156 | BADONION 157 | rightShift 158 | protocolName 159 | hopEphemeralPubKeys 160 | txid 161 | Fn 162 | PublicKey 163 | encryptWithAD 164 | liveness 165 | ie 166 | shakin 167 | txin 168 | globalfeatures 169 | calcMac 170 | privkey 171 | overpayment 172 | hopSharedSecrets 173 | TimeLocked 174 | timelocked 175 | lc 176 | btcec 177 | localsig 178 | responder's 179 | ripemd 180 | md 181 | ENDIF 182 | blockchains 183 | cleartext 184 | streamBytes 185 | WISTFULTOLL 186 | locktime 187 | xFFF 188 | localprivkey 189 | deserialized 190 | pubkey 191 | PubKey 192 | ok 193 | Retransmissions 194 | numHops 195 | failuremsg 196 | fundee 197 | byteslen 198 | shortid 199 | se 200 | rk 201 | micropayment 202 | rn 203 | testbit 204 | unparsable 205 | sk 206 | RoutingInfo 207 | funder 208 | Counterintuitively 209 | decrypts 210 | sn 211 | generateFiller 212 | unrevoked 213 | ss 214 | that'd 215 | ack 216 | deobfuscated 217 | gflen 218 | satoshis 219 | instantiation 220 | HeaderMAC 221 | blindGroupElement 222 | tx 223 | pubkeys 224 | CHECKLOCKTIMEVERIFY 225 | CLTV 226 | CLTVs 227 | generateCipherStream 228 | XK 229 | lflen 230 | deobfuscates 231 | generateKey 232 | alice 233 | revocationprivkey 234 | PKH 235 | remotepubkey 236 | HKDF 237 | ooo 238 | repo 239 | num 240 | numStreamBytes 241 | txout 242 | HTLCs 243 | HTLC's 244 | retransmission 245 | decrypted 246 | sessionKey 247 | sessionkey 248 | routingInfoSize 249 | hostname 250 | rgb 251 | ciphertexts 252 | wscript 253 | CHECKSIG 254 | pre 255 | numMaxHops 256 | HMACs 257 | hmac 258 | BIP 259 | hmacSize 260 | ratelimit 261 | talkin 262 | revocationpubkey 263 | msat 264 | func 265 | unencrypted 266 | coinbase 267 | priv 268 | sha 269 | TODO 270 | ChaChaPoly 271 | delayedpubkey 272 | Diffie 273 | IETF 274 | xFFFFFFFFFFF 275 | FIXME 276 | EphemeralKey 277 | bitcoin 278 | Bitcoin 279 | smartphone 280 | other's 281 | remote's 282 | multi 283 | bitcoin's 284 | IP 285 | aa 286 | df 287 | versa 288 | timestamp 289 | metadata 290 | Bitcoin's 291 | Versioning 292 | checksum 293 | expiries 294 | bech 295 | Bech 296 | nano 297 | pico 298 | mainnet 299 | testnet 300 | icecream 301 | extractable 302 | de 303 | anonymize 304 | Punycode 305 | rck 306 | sck 307 | zeroconf 308 | swiss 309 | lollypop 310 | UTC 311 | inline 312 | fundee's 313 | BOLTs 314 | DNS 315 | subdomain 316 | subdomains 317 | wildcard 318 | tuple 319 | tuples 320 | resolvers 321 | hostnames 322 | prepending 323 | A 324 | AAAA 325 | SRV 326 | TTL 327 | URI 328 | cli 329 | paymentkey 330 | htlcpubkey 331 | remotehtlcsig 332 | localhtlcsig 333 | basepoints 334 | Bitcoins 335 | bitcoins 336 | deobfuscate 337 | offerer 338 | offerer's 339 | incentivize 340 | redemptions 341 | vbytes 342 | BTC 343 | USD 344 | XSS 345 | SQL 346 | DOM 347 | Javascript 348 | javascript 349 | Implementers 350 | sanitization 351 | ek 352 | reblind 353 | ephemeralKey 354 | ephemeralPrivKey 355 | ephemeralPubKey 356 | ecdhResult 357 | scalarMult 358 | blindingFactor 359 | Mul 360 | unlinkable 361 | regtest 362 | ratelimiting 363 | zlib 364 | ZLIB 365 | APIs 366 | duplicative 367 | CRC 368 | DoS 369 | ECDSA 370 | TLV 371 | tlv 372 | namespace 373 | verifier 374 | verifiers 375 | EOF 376 | monotonicity 377 | optimizations 378 | structs 379 | CompactSize 380 | encodings 381 | remotekey 382 | bigsize 383 | BigSize 384 | namespaces 385 | tlvs 386 | fips 387 | rfc 388 | multipath 389 | mpp 390 | tlvs 391 | snprintf 392 | GitHub 393 | IRC 394 | bitmasks 395 | CSPRNG 396 | lexicographically 397 | MINIMALIF 398 | SIGHASH 399 | sighash 400 | ANYONECANPAY 401 | cpfp 402 | utxo 403 | txes 404 | csv 405 | CHECKSIGVERIFY 406 | IFDUP 407 | sats 408 | anysegwit 409 | quiesce 410 | quiescing 411 | SomeThing 412 | onionmsg 413 | unrequested 414 | Merkle 415 | whitespace 416 | TLVs 417 | LnLeaf 418 | LnNonce 419 | LnBranch 420 | payinfo 421 | griefing 422 | unspendable 423 | pkh 424 | kB 425 | unblind 426 | unblinded 427 | workflow 428 | PUSHDATA 429 | prev 430 | vout 431 | rbf 432 | standardness 433 | perkw 434 | prevtx 435 | ints 436 | replaceability 437 | disincentivize 438 | UTXOs 439 | -------------------------------------------------------------------------------- /tools/extract-formats.py: -------------------------------------------------------------------------------- 1 | #! /usr/bin/python3 2 | # Simple script to parse specs and produce CSV files. 3 | # Released by Rusty Russell under CC0: 4 | # https://creativecommons.org/publicdomain/zero/1.0/ 5 | 6 | # Outputs: 7 | # 8 | # Standard message types: 9 | # msgtype,, 10 | # msgdata,,,,[] 11 | # 12 | # TLV types: 13 | # tlvtype,,, 14 | # tlvdata,,,,,[] 15 | # 16 | # Subtypes: 17 | # subtype, 18 | # subtypedata,,,,[] 19 | 20 | from optparse import OptionParser 21 | import sys 22 | import re 23 | import fileinput 24 | 25 | # We allow either ordered or unordered lists. 26 | typeline = re.compile( 27 | r'(1\.|\*) type: (?P[-0-9A-Za-z_|]+) \(`(?P[A-Za-z0-9_]+)`\)( \(`?(?P