diff --git a/.cargo/mutants.toml b/.cargo/mutants.toml index 4bad4d5..612e094 100644 --- a/.cargo/mutants.toml +++ b/.cargo/mutants.toml @@ -1,17 +1,7 @@ -# The same runner as the `elo-test` gate. test_tool = "nextest" -# Above the limit on one test in `.config/nextest.toml`, with room for a test that starts just before -# another test fails. So nextest ends each run first. minimum_test_timeout = 80 -# Do not copy what git ignores to a build directory. Without this, each one gets all of -# `fuzz/target`. This also drops the committed seeds. Only `cfg(fuzzing)` code reads them, and a -# run does not build that code. gitignore = true -# The text of an error is for a person. A test of that text only repeats the literal, so this class -# needs no test. L3 reads the text of `RunError`. That test still runs, but this mutant does not. -# -# cargo-mutants does not apply this list to a `delete field` mutant, so that mutant needs a test. exclude_re = ['::fmt'] diff --git a/.config/ast-grep/comments/rule-tests/__snapshots__/no-bash-comments-snapshot.yml b/.config/ast-grep/comments/rule-tests/__snapshots__/no-bash-comments-snapshot.yml new file mode 100644 index 0000000..b4366ed --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/__snapshots__/no-bash-comments-snapshot.yml @@ -0,0 +1,32 @@ +id: no-bash-comments +snapshots: + "# a\necho": + labels: + - source: "# a" + style: primary + start: 0 + end: 3 + "#!/usr/bin/env bash": + labels: + - source: "#!/usr/bin/env bash" + style: primary + start: 0 + end: 19 + "''\n #! a\n''": + labels: + - source: "#! a" + style: primary + start: 5 + end: 9 + "''\n echo\n #!/bin/sh\n''": + labels: + - source: "#!/bin/sh" + style: primary + start: 12 + end: 21 + "echo a # b": + labels: + - source: "# b" + style: primary + start: 7 + end: 10 diff --git a/.config/ast-grep/comments/rule-tests/__snapshots__/no-nix-comments-snapshot.yml b/.config/ast-grep/comments/rule-tests/__snapshots__/no-nix-comments-snapshot.yml new file mode 100644 index 0000000..b1a927b --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/__snapshots__/no-nix-comments-snapshot.yml @@ -0,0 +1,20 @@ +id: no-nix-comments +snapshots: + "# a\n1": + labels: + - source: "# a" + style: primary + start: 0 + end: 3 + /* a */ 1: + labels: + - source: /* a */ + style: primary + start: 0 + end: 7 + "1 # a": + labels: + - source: "# a" + style: primary + start: 2 + end: 5 diff --git a/.config/ast-grep/comments/rule-tests/__snapshots__/no-nix-string-comments-snapshot.yml b/.config/ast-grep/comments/rule-tests/__snapshots__/no-nix-string-comments-snapshot.yml new file mode 100644 index 0000000..c0c9e5e --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/__snapshots__/no-nix-string-comments-snapshot.yml @@ -0,0 +1,69 @@ +id: no-nix-string-comments +snapshots: + "''\n # a\n echo\n''": + labels: + - source: |2 + + # a + echo + style: primary + start: 2 + end: 16 + - source: |- + '' + # a + echo + '' + style: secondary + start: 0 + end: 18 + "''\n echo\n #! a\n''": + labels: + - source: |2 + + echo + #! a + style: primary + start: 2 + end: 17 + - source: |- + '' + echo + #! a + '' + style: secondary + start: 0 + end: 19 + "''\n echo\n #a\n''": + labels: + - source: |2 + + echo + #a + style: primary + start: 2 + end: 15 + - source: |- + '' + echo + #a + '' + style: secondary + start: 0 + end: 17 + "''\n echo ${x}\n # a\n''": + labels: + - source: |2 + + # a + style: primary + start: 14 + end: 21 + - source: |- + '' + echo ${x} + # a + '' + style: secondary + start: 0 + end: 23 diff --git a/.config/ast-grep/comments/rule-tests/__snapshots__/no-rust-comments-snapshot.yml b/.config/ast-grep/comments/rule-tests/__snapshots__/no-rust-comments-snapshot.yml new file mode 100644 index 0000000..5abcffb --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/__snapshots__/no-rust-comments-snapshot.yml @@ -0,0 +1,39 @@ +id: no-rust-comments +snapshots: + "/* a */\nfn f() {}": + labels: + - source: /* a */ + style: primary + start: 0 + end: 7 + "// a\nfn f() {}": + labels: + - source: // a + style: primary + start: 0 + end: 4 + //! a: + labels: + - source: //! a + style: primary + start: 0 + end: 5 + "/// a\nfn f() {}": + labels: + - source: | + /// a + style: primary + start: 0 + end: 6 + "fn f() { g(/* a */) }": + labels: + - source: /* a */ + style: primary + start: 11 + end: 18 + "fn f() {} // a": + labels: + - source: // a + style: primary + start: 10 + end: 14 diff --git a/.config/ast-grep/comments/rule-tests/__snapshots__/no-rust-doc-attributes-snapshot.yml b/.config/ast-grep/comments/rule-tests/__snapshots__/no-rust-doc-attributes-snapshot.yml new file mode 100644 index 0000000..abb67f7 --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/__snapshots__/no-rust-doc-attributes-snapshot.yml @@ -0,0 +1,196 @@ +id: no-rust-doc-attributes +snapshots: + "#![cfg_attr(test, doc = \"a\")]": + labels: + - source: doc + style: primary + start: 18 + end: 21 + - source: cfg_attr + style: secondary + start: 3 + end: 11 + - source: (test, doc = "a") + style: secondary + start: 11 + end: 28 + - source: "=" + style: secondary + start: 22 + end: 23 + "#![doc = \"a\"]": + labels: + - source: doc = "a" + style: primary + start: 3 + end: 12 + - source: "\"a\"" + style: secondary + start: 9 + end: 12 + - source: doc + style: secondary + start: 3 + end: 6 + "#[cfg_attr(test, cfg_attr(unix, doc = \"a\"))]\nfn f() {}": + labels: + - source: doc + style: primary + start: 32 + end: 35 + - source: cfg_attr + style: secondary + start: 17 + end: 25 + - source: (unix, doc = "a") + style: secondary + start: 25 + end: 42 + - source: "=" + style: secondary + start: 36 + end: 37 + "#[cfg_attr(test, derive(Debug), doc = \"a\")]\nstruct S;": + labels: + - source: doc + style: primary + start: 32 + end: 35 + - source: cfg_attr + style: secondary + start: 2 + end: 10 + - source: (test, derive(Debug), doc = "a") + style: secondary + start: 10 + end: 42 + - source: "=" + style: secondary + start: 36 + end: 37 + "#[cfg_attr(test, doc = \"a\")]\nfn f() {}": + labels: + - source: doc + style: primary + start: 17 + end: 20 + - source: cfg_attr + style: secondary + start: 2 + end: 10 + - source: (test, doc = "a") + style: secondary + start: 10 + end: 27 + - source: "=" + style: secondary + start: 21 + end: 22 + "#[doc = \"a\"]\nfn f() {}": + labels: + - source: doc = "a" + style: primary + start: 2 + end: 11 + - source: "\"a\"" + style: secondary + start: 8 + end: 11 + - source: doc + style: secondary + start: 2 + end: 5 + "#[doc = concat!(\"a\", \"b\")]\nfn f() {}": + labels: + - source: doc = concat!("a", "b") + style: primary + start: 2 + end: 25 + - source: concat!("a", "b") + style: secondary + start: 8 + end: 25 + - source: doc + style: secondary + start: 2 + end: 5 + "#[doc = include_str!(\"a.md\")]\nfn f() {}": + labels: + - source: doc = include_str!("a.md") + style: primary + start: 2 + end: 28 + - source: include_str!("a.md") + style: secondary + start: 8 + end: 28 + - source: doc + style: secondary + start: 2 + end: 5 + "macro_rules! m { ($t:expr) => { #![doc = $t] }; }": + labels: + - source: doc + style: primary + start: 35 + end: 38 + - source: '#' + style: secondary + start: 32 + end: 33 + - source: "!" + style: secondary + start: 33 + end: 34 + - source: "[doc = $t]" + style: secondary + start: 34 + end: 44 + - source: "=" + style: secondary + start: 39 + end: 40 + - source: "[" + style: secondary + start: 34 + end: 35 + "macro_rules! m { ($t:expr) => { #[doc = $t] fn f() {} }; }": + labels: + - source: doc + style: primary + start: 34 + end: 37 + - source: '#' + style: secondary + start: 32 + end: 33 + - source: "[doc = $t]" + style: secondary + start: 33 + end: 43 + - source: "=" + style: secondary + start: 38 + end: 39 + - source: "[" + style: secondary + start: 33 + end: 34 + "macro_rules! m { () => { #[cfg_attr(test, doc = \"a\")] fn f() {} }; }": + labels: + - source: doc + style: primary + start: 42 + end: 45 + - source: cfg_attr + style: secondary + start: 27 + end: 35 + - source: (test, doc = "a") + style: secondary + start: 35 + end: 52 + - source: "=" + style: secondary + start: 46 + end: 47 diff --git a/.config/ast-grep/comments/rule-tests/__snapshots__/no-toml-comments-snapshot.yml b/.config/ast-grep/comments/rule-tests/__snapshots__/no-toml-comments-snapshot.yml new file mode 100644 index 0000000..868c0cc --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/__snapshots__/no-toml-comments-snapshot.yml @@ -0,0 +1,14 @@ +id: no-toml-comments +snapshots: + "# a\nkey = 1": + labels: + - source: "# a" + style: primary + start: 0 + end: 3 + "key = 1 # a": + labels: + - source: "# a" + style: primary + start: 8 + end: 11 diff --git a/.config/ast-grep/comments/rule-tests/__snapshots__/no-yaml-comments-snapshot.yml b/.config/ast-grep/comments/rule-tests/__snapshots__/no-yaml-comments-snapshot.yml new file mode 100644 index 0000000..9e1edb4 --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/__snapshots__/no-yaml-comments-snapshot.yml @@ -0,0 +1,14 @@ +id: no-yaml-comments +snapshots: + "# a\nkey: value": + labels: + - source: "# a" + style: primary + start: 0 + end: 3 + "key: value # a": + labels: + - source: "# a" + style: primary + start: 11 + end: 14 diff --git a/.config/ast-grep/comments/rule-tests/__snapshots__/no-yaml-run-comments-snapshot.yml b/.config/ast-grep/comments/rule-tests/__snapshots__/no-yaml-run-comments-snapshot.yml new file mode 100644 index 0000000..4a9a061 --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/__snapshots__/no-yaml-run-comments-snapshot.yml @@ -0,0 +1,83 @@ +id: no-yaml-run-comments +snapshots: + "run: |\n echo\n # a": + labels: + - source: |- + | + echo + # a + style: primary + start: 5 + end: 19 + - source: run + style: secondary + start: 0 + end: 3 + - source: |- + run: | + echo + # a + style: secondary + start: 0 + end: 19 + - source: |- + | + echo + # a + style: secondary + start: 5 + end: 19 + "run: |\n echo\n #! a": + labels: + - source: |- + | + echo + #! a + style: primary + start: 5 + end: 20 + - source: run + style: secondary + start: 0 + end: 3 + - source: |- + run: | + echo + #! a + style: secondary + start: 0 + end: 20 + - source: |- + | + echo + #! a + style: secondary + start: 5 + end: 20 + "steps:\n - run: >-\n echo\n # a": + labels: + - source: |- + >- + echo + # a + style: primary + start: 16 + end: 39 + - source: run + style: secondary + start: 11 + end: 14 + - source: |- + run: >- + echo + # a + style: secondary + start: 11 + end: 39 + - source: |- + >- + echo + # a + style: secondary + start: 16 + end: 39 diff --git a/.config/ast-grep/comments/rule-tests/no-bash-comments-test.yml b/.config/ast-grep/comments/rule-tests/no-bash-comments-test.yml new file mode 100644 index 0000000..3399f4c --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/no-bash-comments-test.yml @@ -0,0 +1,12 @@ +id: no-bash-comments +valid: + - 'echo "# a"' + - 'echo "${#a[@]}"' + - "echo a#b" + - "''\n #!/bin/sh\n echo\n''" +invalid: + - "# a\necho" + - "echo a # b" + - "#!/usr/bin/env bash" + - "''\n echo\n #!/bin/sh\n''" + - "''\n #! a\n''" diff --git a/.config/ast-grep/comments/rule-tests/no-nix-comments-test.yml b/.config/ast-grep/comments/rule-tests/no-nix-comments-test.yml new file mode 100644 index 0000000..1ba4caa --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/no-nix-comments-test.yml @@ -0,0 +1,8 @@ +id: no-nix-comments +valid: + - '"# a"' + - "''\n echo\n''" +invalid: + - "# a\n1" + - "/* a */ 1" + - "1 # a" diff --git a/.config/ast-grep/comments/rule-tests/no-nix-string-comments-test.yml b/.config/ast-grep/comments/rule-tests/no-nix-string-comments-test.yml new file mode 100644 index 0000000..acbc9ec --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/no-nix-string-comments-test.yml @@ -0,0 +1,11 @@ +id: no-nix-string-comments +valid: + - "''\n echo \"# a\"\n''" + - "''\n #[derive(Debug)]\n''" + - "''\n #!/bin/sh\n''" + - "''\n echo ${x}# a\n''" +invalid: + - "''\n # a\n echo\n''" + - "''\n echo\n #a\n''" + - "''\n echo ${x}\n # a\n''" + - "''\n echo\n #! a\n''" diff --git a/.config/ast-grep/comments/rule-tests/no-rust-comments-test.yml b/.config/ast-grep/comments/rule-tests/no-rust-comments-test.yml new file mode 100644 index 0000000..37a622f --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/no-rust-comments-test.yml @@ -0,0 +1,12 @@ +id: no-rust-comments +valid: + - 'fn f() -> &''static str { "// a" }' + - 'fn f() -> &''static str { "/* a */" }' + - "#[must_use]\nfn f() {}" +invalid: + - "// a\nfn f() {}" + - "/// a\nfn f() {}" + - "//! a" + - "/* a */\nfn f() {}" + - "fn f() {} // a" + - "fn f() { g(/* a */) }" diff --git a/.config/ast-grep/comments/rule-tests/no-rust-doc-attributes-test.yml b/.config/ast-grep/comments/rule-tests/no-rust-doc-attributes-test.yml new file mode 100644 index 0000000..42ac91a --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/no-rust-doc-attributes-test.yml @@ -0,0 +1,21 @@ +id: no-rust-doc-attributes +valid: + - "#[doc(hidden)]\npub fn f() {}" + - "#[must_use = \"a\"]\npub fn f() -> u8 { 1 }" + - "#[cfg_attr(test, doc(hidden))]\npub fn f() {}" + - "#[cfg_attr(test, derive(Debug))]\npub struct S;" + - "#[a(doc = \"a\")]\nfn f() {}" + - "m![doc = 1];" + - "macro_rules! m { () => { #[a(doc = \"a\")] fn f() {} }; }" +invalid: + - "#[doc = \"a\"]\nfn f() {}" + - "#![doc = \"a\"]" + - "#[doc = concat!(\"a\", \"b\")]\nfn f() {}" + - "#[doc = include_str!(\"a.md\")]\nfn f() {}" + - "#[cfg_attr(test, doc = \"a\")]\nfn f() {}" + - "#![cfg_attr(test, doc = \"a\")]" + - "#[cfg_attr(test, derive(Debug), doc = \"a\")]\nstruct S;" + - "#[cfg_attr(test, cfg_attr(unix, doc = \"a\"))]\nfn f() {}" + - "macro_rules! m { ($t:expr) => { #[doc = $t] fn f() {} }; }" + - "macro_rules! m { ($t:expr) => { #![doc = $t] }; }" + - "macro_rules! m { () => { #[cfg_attr(test, doc = \"a\")] fn f() {} }; }" diff --git a/.config/ast-grep/comments/rule-tests/no-toml-comments-test.yml b/.config/ast-grep/comments/rule-tests/no-toml-comments-test.yml new file mode 100644 index 0000000..1526bd0 --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/no-toml-comments-test.yml @@ -0,0 +1,7 @@ +id: no-toml-comments +valid: + - 'key = "# a"' + - "key = '# a'" +invalid: + - "# a\nkey = 1" + - "key = 1 # a" diff --git a/.config/ast-grep/comments/rule-tests/no-yaml-comments-test.yml b/.config/ast-grep/comments/rule-tests/no-yaml-comments-test.yml new file mode 100644 index 0000000..83d303c --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/no-yaml-comments-test.yml @@ -0,0 +1,7 @@ +id: no-yaml-comments +valid: + - 'key: "# a"' + - "key: |\n # a" +invalid: + - "# a\nkey: value" + - "key: value # a" diff --git a/.config/ast-grep/comments/rule-tests/no-yaml-run-comments-test.yml b/.config/ast-grep/comments/rule-tests/no-yaml-run-comments-test.yml new file mode 100644 index 0000000..4710ad9 --- /dev/null +++ b/.config/ast-grep/comments/rule-tests/no-yaml-run-comments-test.yml @@ -0,0 +1,10 @@ +id: no-yaml-run-comments +valid: + - "run: |\n echo \"# a\"" + - "run: |\n echo\n #[a]" + - "other: |\n echo\n # a" + - "run: |\n cat <-\n echo\n # a" + - "run: |\n echo\n #! a" diff --git a/.config/ast-grep/comments/rules/no-bash-comments.yml b/.config/ast-grep/comments/rules/no-bash-comments.yml new file mode 100644 index 0000000..5b33c97 --- /dev/null +++ b/.config/ast-grep/comments/rules/no-bash-comments.yml @@ -0,0 +1,15 @@ +id: no-bash-comments +language: bash +severity: error +message: >- + No comments. Say it in the code: a name, a type, a test. +rule: + kind: comment + not: + regex: ^#!/ + follows: + regex: ^''$ + not: + follows: + stopBy: end + regex: '[\s\S]' diff --git a/.config/ast-grep/comments/rules/no-nix-comments.yml b/.config/ast-grep/comments/rules/no-nix-comments.yml new file mode 100644 index 0000000..a6d412f --- /dev/null +++ b/.config/ast-grep/comments/rules/no-nix-comments.yml @@ -0,0 +1,7 @@ +id: no-nix-comments +language: nix +severity: error +message: >- + No comments. Say it in the code: a name, a type, a test. +rule: + kind: comment diff --git a/.config/ast-grep/comments/rules/no-nix-string-comments.yml b/.config/ast-grep/comments/rules/no-nix-string-comments.yml new file mode 100644 index 0000000..07ad194 --- /dev/null +++ b/.config/ast-grep/comments/rules/no-nix-string-comments.yml @@ -0,0 +1,10 @@ +id: no-nix-string-comments +language: nix +severity: error +message: >- + No comments, in a string's script or file either. Say it in the code: a name, a type, a test. +rule: + kind: string_fragment + regex: \n[ \t]*#([^\[!]|![^/]) + inside: + kind: indented_string_expression diff --git a/.config/ast-grep/comments/rules/no-rust-comments.yml b/.config/ast-grep/comments/rules/no-rust-comments.yml new file mode 100644 index 0000000..90b3bf9 --- /dev/null +++ b/.config/ast-grep/comments/rules/no-rust-comments.yml @@ -0,0 +1,9 @@ +id: no-rust-comments +language: rust +severity: error +message: >- + No comments. Say it in the code: a name, a type, a test. +rule: + any: + - kind: line_comment + - kind: block_comment diff --git a/.config/ast-grep/comments/rules/no-rust-doc-attributes.yml b/.config/ast-grep/comments/rules/no-rust-doc-attributes.yml new file mode 100644 index 0000000..8c28e44 --- /dev/null +++ b/.config/ast-grep/comments/rules/no-rust-doc-attributes.yml @@ -0,0 +1,38 @@ +id: no-rust-doc-attributes +language: rust +severity: error +message: >- + No documentation, as an attribute either. Say it in the code: a name, a type, a test. +rule: + any: + - kind: attribute + all: + - has: + field: value + regex: . + - has: + kind: identifier + regex: ^doc$ + - kind: identifier + regex: ^doc$ + precedes: + regex: ^=$ + inside: + kind: token_tree + follows: + kind: identifier + regex: ^cfg_attr$ + - kind: identifier + regex: ^doc$ + follows: + regex: ^\[$ + precedes: + regex: ^=$ + inside: + kind: token_tree + follows: + any: + - regex: ^#$ + - regex: ^!$ + follows: + regex: ^#$ diff --git a/.config/ast-grep/comments/rules/no-toml-comments.yml b/.config/ast-grep/comments/rules/no-toml-comments.yml new file mode 100644 index 0000000..4b76907 --- /dev/null +++ b/.config/ast-grep/comments/rules/no-toml-comments.yml @@ -0,0 +1,7 @@ +id: no-toml-comments +language: toml +severity: error +message: >- + No comments. Say it in the code: a name, a type, a test. +rule: + kind: comment diff --git a/.config/ast-grep/comments/rules/no-yaml-comments.yml b/.config/ast-grep/comments/rules/no-yaml-comments.yml new file mode 100644 index 0000000..e031395 --- /dev/null +++ b/.config/ast-grep/comments/rules/no-yaml-comments.yml @@ -0,0 +1,7 @@ +id: no-yaml-comments +language: yaml +severity: error +message: >- + No comments. Say it in the code: a name, a type, a test. +rule: + kind: comment diff --git a/.config/ast-grep/comments/rules/no-yaml-run-comments.yml b/.config/ast-grep/comments/rules/no-yaml-run-comments.yml new file mode 100644 index 0000000..3009b91 --- /dev/null +++ b/.config/ast-grep/comments/rules/no-yaml-run-comments.yml @@ -0,0 +1,15 @@ +id: no-yaml-run-comments +language: yaml +severity: error +message: >- + No comments, in a step's script either. Say it in the code: a name, a type, a test. +rule: + kind: block_scalar + regex: \n[ \t]*#([^\[!]|![^/]) + inside: + kind: block_node + inside: + kind: block_mapping_pair + has: + field: key + regex: ^run$ diff --git a/.config/nextest.toml b/.config/nextest.toml index c88570f..2be7aff 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -1,4 +1,2 @@ [profile.default] -# A test that reaches this limit fails, so a hang is a failed test and does not stop the job. The -# limit is above each wait in `tests/bitcoind.rs`, so those asserts still give their message. slow-timeout = { period = "35s", terminate-after = 1 } diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 5642b04..f07dd35 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -11,9 +11,6 @@ permissions: concurrency: group: ci-${{ github.ref }} - # A new push to a pull request cancels the older run. A push to main does - # not, so a run on main that started gets a result. A run that waits is - # still dropped when a newer one comes. cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: @@ -23,50 +20,45 @@ jobs: timeout-minutes: 20 strategy: fail-fast: false - # One job for each derivation, so the runners work in parallel. A single - # `nix flake check` puts every gate behind one log and one runner. matrix: - gate: [elo, elo-clippy, elo-test, elo-doctest, elo-fmt, elo-fuzz, elo-fuzz-image, elo-image] + gate: + - elo + - elo-clippy + - elo-test + - elo-fmt + - elo-comments + - elo-fuzz + - elo-fuzz-image + - elo-image steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - - uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 # v31.11.2 + - uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 - # flake.lock pins each tool, and rust-toolchain.toml pins the compiler. - # No installer step chooses a different version. - run: nix build --print-build-logs ".#${{ matrix.gate }}" - # Build the package and its dependencies a second time. Nix fails the - # step if an output is not the same bytes. `--rebuild` does not rebuild - # inputs, so the dependencies are named on their own. - if: matrix.gate == 'elo' run: nix build --print-build-logs --rebuild .#elo .#elo.cargoArtifacts - # Runs each mutant on the lines that a pull request changes. A push has no such diff. mutants: name: mutants if: github.event_name == 'pull_request' runs-on: ubuntu-24.04 timeout-minutes: 20 steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - # A pull request checks out its merge commit. Depth 2 also gets the parents of that - # commit, so the diff is what the merge adds to `main`. fetch-depth: 2 - - uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 # v31.11.2 + - uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 - # git quotes a non-ASCII path by default, and cargo-mutants cannot parse that quoting. - run: | git -c core.quotePath=false diff HEAD^1 HEAD > "$RUNNER_TEMP/pull-request.diff" nix develop --command cargo mutants --in-diff "$RUNNER_TEMP/pull-request.diff" --jobs 2 - # A long fuzz run takes this image. Only a push to main reaches this job, so a pull request - # cannot push an image. fuzz-image: name: fuzz image if: github.event_name == 'push' @@ -77,32 +69,24 @@ jobs: contents: read packages: write steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - - uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 # v31.11.2 + - uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 - run: nix build --print-build-logs .#elo-fuzz-image - # No build runs the entry point, so run a short session. A crash in it also stops the push, - # so `main` stays on the last image that ran. Each target takes at least 1 s, so 8 s leaves - # room for new targets. Not in a gate, because a gate must not depend on a random run. - run: | docker load --input result data="$(mktemp --directory)" docker run --rm --read-only --network none --user "$(id -u):$(id -g)" \ --volume "$data:/data" elo-fuzz:local 8 - # `sha-` first, so `main` never names an image that has no commit tag. - env: GHCR_TOKEN: ${{ github.token }} run: | echo "$GHCR_TOKEN" | docker login ghcr.io --username "$GITHUB_ACTOR" --password-stdin - # A re-run of an older run pushes its `sha-` tag again, but must not move `main` back. - # The concurrency group runs one push run at a time, so the run of a newer head waits and - # moves `main` after this one. No pipe, because the step has no `pipefail`, and a failed - # read must fail the step. head="$(git ls-remote --exit-code origin refs/heads/main)" tags="sha-$GITHUB_SHA" if test "${head%%[[:space:]]*}" = "$GITHUB_SHA"; then tags="$tags main"; fi @@ -111,7 +95,6 @@ jobs: docker push "ghcr.io/lorenzolfm/elo-fuzz:$tag" done - # A deployment of elo takes this image. As for `fuzz-image`, only a push to main reaches this job. image: name: image if: github.event_name == 'push' @@ -122,21 +105,16 @@ jobs: contents: read packages: write steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - - uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 # v31.11.2 + - uses: cachix/install-nix-action@448cde739abec1eaf0646249e3d25bb8d9bc7702 - run: nix build --print-build-logs .#elo-image - # No build runs the entry point, so the image syncs from a regtest bitcoind on the runner, - # with the bitcoind of `flake.lock`. Then the job stops the container. Exit 0 is the handler - # of elo, as PID 1. With no handler, the stop ends in SIGKILL: 137. - run: | docker load --input result - # The push tags the image `sha-`, so its label must name the same commit, and - # not `dirty`. revision='{{index .Config.Labels "org.opencontainers.image.revision"}}' test "$(docker inspect elo:local --format "$revision")" = "$GITHUB_SHA" datadir="$(mktemp --directory)" @@ -144,13 +122,10 @@ jobs: -datadir="$datadir" -daemonwait docker run --detach --name elo --read-only --cap-drop ALL \ --security-opt no-new-privileges --network host elo:local regtest 127.0.0.1 - # Height 0, the regtest genesis and its work. genesis=0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206 tip="level=info event=tip peer=127.0.0.1:18444 height=0" tip="$tip hash=$genesis work=$(printf '%064x' 2)" - # The wait and the check after it read the same line. has_tip() { docker logs elo | grep --fixed-strings --line-regexp --quiet "$tip"; } - # A container that stopped cannot print the line later, so the wait ends there too. for _ in $(seq 60); do has_tip && break test "$(docker inspect elo --format '{{.State.Running}}')" = true || break @@ -161,15 +136,10 @@ jobs: docker stop --timeout 10 elo test "$(docker inspect elo --format '{{.State.ExitCode}}')" = 0 - # `sha-` first, so `main` never names an image that has no commit tag. - env: GHCR_TOKEN: ${{ github.token }} run: | echo "$GHCR_TOKEN" | docker login ghcr.io --username "$GITHUB_ACTOR" --password-stdin - # A re-run of an older run pushes its `sha-` tag again, but must not move `main` back. - # The concurrency group runs one push run at a time, so the run of a newer head waits and - # moves `main` after this one. No pipe, because the step has no `pipefail`, and a failed - # read must fail the step. head="$(git ls-remote --exit-code origin refs/heads/main)" tags="sha-$GITHUB_SHA" if test "${head%%[[:space:]]*}" = "$GITHUB_SHA"; then tags="$tags main"; fi diff --git a/.gitignore b/.gitignore index a257cfb..40ea21b 100644 --- a/.gitignore +++ b/.gitignore @@ -5,5 +5,4 @@ /fuzz/target /fuzz/artifacts /mutants.out* -# The new inputs of a random run. Git still tracks each committed input. /fuzz/corpus/*/* diff --git a/Cargo.toml b/Cargo.toml index 2f6670e..b12c487 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,6 +13,5 @@ tokio = { version = "1.54.1", default-features = false, features = ["rt", "net", [dev-dependencies] tokio = { version = "1.54.1", default-features = false, features = ["test-util"] } -# The fuzz targets in `fuzz/` build with `--cfg fuzzing`. [lints.rust] unexpected_cfgs = { level = "warn", check-cfg = ['cfg(fuzzing)'] } diff --git a/README.md b/README.md index 0e8940d..2680fcd 100644 --- a/README.md +++ b/README.md @@ -110,7 +110,7 @@ Nix builds everything. `flake.lock` pins nixpkgs and the other inputs, and ```sh nix build # the binary, at ./result/bin/elo -nix flake check # every CI gate: build, clippy, tests, doctests, rustfmt, fuzz corpus +nix flake check # every CI gate: build, clippy, tests, rustfmt, no comments, fuzz corpus nix develop # a shell with the pinned toolchain (direnv: `direnv allow`) ``` diff --git a/flake.nix b/flake.nix index 5c77418..2afe9db 100644 --- a/flake.nix +++ b/flake.nix @@ -37,14 +37,6 @@ (crane.mkLib pkgs).overrideToolchain (p: p.rust-bin.fromRustupToolchainFile ./rust-toolchain.toml); - # The gates build with the toolchain file as it is written: minimal. The - # dev shell adds rust-src on top, because rust-analyzer reads the - # documentation of the standard library from those sources. No gate - # needs the sources, so they stay out of the build closure. - # - # `override` replaces the component list, it does not add to it. Read - # the list from the toolchain file, so the dev shell keeps clippy, - # rustfmt and rust-analyzer. toolchainFile = builtins.fromTOML (builtins.readFile ./rust-toolchain.toml); craneLibDev = (crane.mkLib pkgs).overrideToolchain (p: @@ -59,7 +51,6 @@ strictDeps = true; }; - # The fuzz gate replays the corpus, and the filter above drops those files. fuzzSrc = pkgs.lib.cleanSourceWith { src = ./.; filter = path: type: @@ -67,20 +58,67 @@ || pkgs.lib.hasInfix "/fuzz/corpus/" path; }; - # The L3 tests run elo against this bitcoind. They use bitcoin-cli from - # the same package to see when it is ready and to read its peer info. - # Its version is the one in their asserts. bitcoind = pkgs.lib.getExe' pkgs.bitcoind "bitcoind"; bitcoinCli = pkgs.lib.getExe' pkgs.bitcoind "bitcoin-cli"; - # Build only the dependencies, so a change to the crate's own code does - # not build them again. + comments = ./.config/ast-grep/comments; + commentGlobs = { + rust = ["*.rs"]; + nix = ["*.nix"]; + bash = ["*.sh" ".envrc" ".gitignore"]; + yaml = ["*.yml" "*.yaml"]; + toml = ["*.toml"]; + }; + commentFree = ["./Cargo.lock" "./fuzz/Cargo.lock" "./flake.lock" "./README.md" "./fuzz/corpus/*"]; + commentRead = pkgs.lib.concatStringsSep "|" ( + map (glob: + if pkgs.lib.hasPrefix "*" glob + then glob + else "*/${glob}") + (pkgs.lib.concatLists (builtins.attrValues commentGlobs)) + ++ commentFree + ); + runBlock = { + kind = "block_node"; + inside = { + kind = "block_mapping_pair"; + has = { + field = "key"; + regex = "^run$"; + }; + }; + }; + commentsConfig = pkgs.writeText "comments.json" (builtins.toJSON { + ruleDirs = ["${comments}/rules"]; + testConfigs = [{testDir = "${comments}/rule-tests";}]; + customLanguages.toml = { + libraryPath = "${pkgs.tree-sitter-grammars.tree-sitter-toml}/parser"; + extensions = ["toml"]; + }; + languageGlobs = commentGlobs; + languageInjections = [ + { + hostLanguage = "nix"; + rule = { + kind = "indented_string_expression"; + pattern = "$CONTENT"; + }; + injected = "bash"; + } + { + hostLanguage = "yaml"; + rule = { + kind = "block_scalar"; + pattern = "$CONTENT"; + inside = runBlock; + }; + injected = "bash"; + } + ]; + }); + cargoArtifacts = craneLib.buildDepsOnly commonArgs; - # The test gates run in the dev profile, as `cargo test` does in the - # dev shell. The release profile turns off overflow checks and - # `debug_assert!`. The dev profile needs its own build of the - # dependencies. devArgs = commonArgs // { @@ -92,7 +130,6 @@ // { inherit cargoArtifacts; - # The test gate runs the tests. Do not run them two times. doCheck = false; meta = { @@ -103,8 +140,6 @@ }; }); - # One derivation for each gate. CI builds them in parallel, and - # `nix flake check` runs all of them. gates = { inherit elo; @@ -118,75 +153,77 @@ // { BITCOIND = bitcoind; BITCOIN_CLI = bitcoinCli; - # The tests listen and connect on loopback. The macOS sandbox - # blocks that without this flag. __darwinAllowLocalNetworking = true; }); - # nextest does not run doctests. - elo-doctest = craneLib.cargoDocTest devArgs; - elo-fmt = craneLib.cargoFmt {inherit src;}; - # Builds each fuzz target and replays its committed corpus once, so an input - # that crashed elo cannot crash it again. CI does no random run. The compiler - # is stable and sanitizers need nightly, so the targets have no sanitizer. + elo-comments = + pkgs.runCommand "elo-comments" { + nativeBuildInputs = [pkgs.ast-grep]; + } '' + cd ${./.} + mapfile -d "" tree < <(find . -type f -print0) + wait $! + (( ''${#tree[@]} > 0 )) + unread() { + local file + for file in "$@"; do + case "$file" in + ${commentRead}) ;; + *) echo "$file" ;; + esac + done + } + test "$(unread ./a.rs ./a/.envrc ./Cargo.lock ./fuzz/corpus/a/b ./a.py ./a/Cargo.lock)" \ + = "$(printf '%s\n' ./a.py ./a/Cargo.lock)" + unread_files="$(unread "''${tree[@]}")" + if test -n "$unread_files"; then + echo "elo-comments: no rule reads these files: $unread_files" >&2 + exit 1 + fi + ast-grep test --config ${commentsConfig} --custom-languages allow + ast-grep scan --config ${commentsConfig} --custom-languages allow -- "''${tree[@]}" + touch "$out" + ''; + elo-fuzz = craneLib.mkCargoDerivation (commonArgs // { src = fuzzSrc; pnameSuffix = "-fuzz"; cargoArtifacts = null; doInstallCargoArtifacts = false; - # `fuzz/` is its own workspace, so it has its own lockfile. cargoVendorDir = craneLib.vendorMultipleCargoDeps { cargoLockList = [./Cargo.lock ./fuzz/Cargo.lock]; }; nativeBuildInputs = [pkgs.cargo-fuzz]; - # The last step runs the tests, which listen and connect on loopback. The macOS - # sandbox blocks that without this flag. __darwinAllowLocalNetworking = true; buildPhaseCargoCommand = '' - # The normal gates do not see these: `fuzz/` is outside their - # workspace, and they build without `--cfg fuzzing`. Clippy checks - # only the workspace it runs in, so it runs in both. cargo fmt --manifest-path fuzz/Cargo.toml --check RUSTFLAGS="--cfg fuzzing" cargo clippy --locked --all-targets -- --deny warnings RUSTFLAGS="--cfg fuzzing" cargo clippy --manifest-path fuzz/Cargo.toml \ --locked -- --deny warnings - # The log shows only the `cargo` commands, so a `test` that fails must say - # why. Without this, the log ends on the last `cargo` command, which passed. fail() { echo "elo-fuzz: $1" >&2; exit 1; } - # The committed corpus is at most 1 MiB, so a clone stays small. corpus_size="$(du --summarize --bytes fuzz/corpus | cut --fields=1)" test "$corpus_size" -le 1048576 || fail "the corpus is $corpus_size bytes, above 1 MiB" - # A session reads at most 4096 bytes of an input: the `-max_len` of `session.sh`. - # The replay below reads all of a seed, so a longer seed is not what passed here. long_seeds="$(find fuzz/corpus -type f -size +4096c)" test -z "$long_seeds" || fail "these seeds are above 4096 bytes: $long_seeds" - # The targets build elo with the versions that elo ships. `--locked` checks - # each lockfile alone, so it does not see an update of only one. With no - # packages in the list, the comparison passes. packages() { sed --quiet '/^name = /{N;s/\n/ /;p}' "$1" | sort; } test -n "$(packages Cargo.lock)" || fail "found no packages in Cargo.lock" comm -23 <(packages Cargo.lock) <(packages fuzz/Cargo.lock) | tee only-in-root test ! -s only-in-root || fail "fuzz/Cargo.lock does not have the packages above" - # With no targets, the loop runs zero times and the gate passes. targets="$(cargo fuzz list)" test -n "$targets" || fail "found no fuzz targets" - # A target has one name in its manifest entry, file, entry point and corpus. - # A copy that keeps an old name replays a corpus through another entry point, - # and the replay passes. test "$(ls fuzz/corpus | sort)" = "$(sort <<< "$targets")" \ || fail "the corpus directories are not the targets" test "$(ls fuzz/fuzz_targets | sed 's/\.rs$//' | sort)" = "$(sort <<< "$targets")" \ || fail "the files in fuzz_targets are not the targets" - # `packages` also prints each `[[bin]]`: its name and its path, on one line. manifest="$(packages fuzz/Cargo.toml)" for target in $targets; do grep --fixed-strings --line-regexp --quiet \ @@ -197,17 +234,12 @@ done for target in $targets; do - # `cargo fuzz run` makes a missing corpus, and an empty one passes. test -n "$(ls --almost-all "fuzz/corpus/$target")" || fail "target $target has no corpus" cargo fuzz run --sanitizer none "$target" -- -runs=0 done - # The tests of `SEED_ENDS` have `cfg(fuzzing)`, so only this gate runs them. After - # the replay, so a machine bug has its seed as the failing input. No filter, because - # a filter that matches no test exits 0. RUSTFLAGS="--cfg fuzzing" cargo test --locked --lib ''; - # The bytes that the replay ran, so the image holds what passed this gate. installPhaseCommand = '' mkdir --parents "$out/targets" cp --recursive fuzz/corpus "$out/corpus" @@ -224,14 +256,11 @@ text = builtins.readFile ./fuzz/session.sh; }; - # The targets and the corpus of the gate. Panic locations and line tables name each store - # path that the build read, so without this the image holds a compiler: 150 MB, not 42 MB. fuzzTargets = let kept = [pkgs.stdenv.cc.libc.out pkgs.stdenv.cc.cc.lib]; in pkgs.runCommand "elo-fuzz-targets" { nativeBuildInputs = [pkgs.removeReferencesTo]; - # This sees only a path that the loop below cannot find. The load check holds the rest. allowedReferences = kept; } '' cp --recursive --no-preserve=mode ${gates.elo-fuzz} "$out" @@ -244,18 +273,13 @@ esac done - # The loop removes each path outside `kept`, and a target can need one at run time. Then - # no reference is left to stop the build, so load each target. The last line of a target - # that does not load is the error of the loader. for target in "$out"/targets/*; do "$target" -help=1 2>&1 | tail --lines=1 done - # `session.sh` names these two targets. test -x "$out/targets/compact_size" test -x "$out/targets/machines" ''; - # A long run on a home machine. The session holds no secret and needs no network. elo-fuzz-image = pkgs.dockerTools.buildLayeredImage { name = "elo-fuzz"; tag = "local"; @@ -271,10 +295,6 @@ }; }; - # The daemon. The deployment gives the arguments of elo: the network and the peer. elo is - # PID 1. The kernel gives PID 1 no default action for a signal, so elo handles SIGTERM - # itself, and a stop ends it at once. elo starts no child process, so no init needs to - # reap one. The image needs no volume, no port and no writable path. elo-image = pkgs.dockerTools.buildLayeredImage { name = "elo"; tag = "local"; @@ -296,8 +316,6 @@ checks = gates; - # Give each gate a package name, so CI can build one gate with - # `nix build .#`. packages = gates // { diff --git a/fuzz/Cargo.toml b/fuzz/Cargo.toml index aba2582..911b7f9 100644 --- a/fuzz/Cargo.toml +++ b/fuzz/Cargo.toml @@ -46,5 +46,4 @@ test = false doc = false bench = false -# Its own workspace, so its dependencies stay out of the lockfile of elo. [workspace] diff --git a/fuzz/session.sh b/fuzz/session.sh index 92232ff..1dc82fc 100644 --- a/fuzz/session.sh +++ b/fuzz/session.sh @@ -1,27 +1,8 @@ -# One fuzz session, in the image of `elo-fuzz-image`. Usage: session -# -# At most two processes run, so a session holds at most two cores. One runs `machines` for the whole -# window, because it has the most states. The other runs each other target in turn. `compact_size` -# gets at most 60 s, because 84M runs in 30 s found a new input only at run 23. The other targets -# split the rest. No fork mode: a fork job deletes its panic text, and needs a writable /tmp. -# -# A crash ends its target for this session, so a session keeps at most one crash for each target. -# Then the session fails, so its Job fails and the alert on the last good session can fire. A crash -# file also fails each later session until a person removes it: a crash input does not join the -# corpus, so the next session can miss the bug and pass. -# -# /targets and /corpus are in the image. /data holds all that the session writes: -# /data/corpus// the new inputs of each session -# /data/crashes/--* each crash, with the name that libFuzzer gives it -# /data/logs/.log the libFuzzer log of the last session - fail() { echo "session: $1" >&2 exit 2 } -# The shell and libFuzzer must read the window as one number. libFuzzer stops at the first character -# that is not a digit and keeps an `int`, and 0 is no limit. So 0x20 and 2^32 each remove the limit. usage="usage: session , a decimal number above 0" test "$#" -eq 1 || fail "$usage" window_seconds="$1" @@ -43,7 +24,6 @@ for path in /targets/*; do done test "${#others[@]}" -gt 0 || fail "need a target other than machines and compact_size" -# Floor divisions, so the second process ends inside the window. A share of 0 s would be no limit. share_seconds=$((window_seconds / (${#others[@]} + 1))) test "$share_seconds" -gt 0 || fail "need at least $((${#others[@]} + 1)) seconds" compact_size_seconds=$((share_seconds < 60 ? share_seconds : 60)) @@ -51,26 +31,12 @@ other_seconds=$(((window_seconds - compact_size_seconds) / ${#others[@]})) mkdir --parents /data/corpus /data/crashes /data/logs || fail "cannot write to /data" -# libFuzzer keeps a corpus in memory, so a large one looks like a leak. A mounted directory can also -# have no quota. So a session does not start with more than 1 GiB of these files. A person prunes -# them. Only these three directories count, because the session does not write the rest of /data. data_size_kib="$(du --summarize --total --block-size=1K /data/corpus /data/crashes /data/logs | tail --lines=1 | cut --fields=1)" || fail "cannot read the size of /data" test "$data_size_kib" -le $((1024 * 1024)) || fail "its files take $data_size_kib KiB, above 1 GiB" -# Each target has a small chain and, by the check above, a small corpus, so 1 GiB is a leak. Above -# this limit an allocation fails at once, so it is a crash with a file that holds its input, also -# when the target does not touch the memory. `-rss_limit_mb` does not do this. It reads the RSS once -# each second, so a fast allocation reaches the limit of a container first and no file holds the -# input, and its `oom-` file can hold a later input. Two processes at this limit fit in 3 GiB. ulimit -v $((1024 * 1024)) || fail "cannot limit the address space" -# A script takes milliseconds, so 30 s is a hang, and that is a crash, with its own file. Each -# target reaches its limits from a short input, and with no `-max_len` the largest seed sets the -# length. -# A unit below the timeout is not a crash. By default libFuzzer writes a file for a unit of 10 s, -# and the session passes. So the limit for a slow unit is above the timeout, and it writes no file. -# A caller with `||` turns `errexit` off here, so each step that can fail says how `fuzz` ends. fuzz() { local target="$1" limit_seconds="$2" local log="/data/logs/$target.log" diff --git a/src/block.rs b/src/block.rs index 638d828..656ac9c 100644 --- a/src/block.rs +++ b/src/block.rs @@ -1,26 +1,18 @@ -//! Block headers. - use crate::serialize::{Decode, Encode}; -/// The size of an encoded header. pub(crate) const BLOCK_HEADER_SIZE: usize = 80; -/// A block header. Its hash names the block. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) struct BlockHeader { pub(crate) version: i32, - /// The hash of the header before it. All zeros in a genesis header. pub(crate) prev: bitcoin_hashes::sha256d::Hash, pub(crate) merkle_root: [u8; 32], - /// Seconds since the Unix epoch. pub(crate) time: u32, - /// The proof-of-work target, in compact form. pub(crate) bits: u32, pub(crate) nonce: u32, } impl BlockHeader { - /// The double SHA-256 of the encoded header. pub(crate) fn hash(&self) -> bitcoin_hashes::sha256d::Hash { let mut bytes = Vec::with_capacity(BLOCK_HEADER_SIZE); self.encode(&mut bytes); @@ -41,7 +33,6 @@ impl Encode for BlockHeader { } } -/// Each field is required. Bytes after `nonce` stay in `input`. impl Decode for BlockHeader { fn decode(input: &mut &[u8]) -> Result { let length_before = input.len(); @@ -69,9 +60,6 @@ mod tests { assert_eq!(*count, 2); let header = super::BlockHeader::decode(&mut input).unwrap(); - // The `prev` of block 1 is the regtest genesis hash, so a decoded hash keeps the wire - // order. The hash of block 1 cannot show this: a decode and an encode that both - // reverse the bytes give the same hash. assert_eq!( header.prev, crate::fixtures::hash_from_display_hex( @@ -84,8 +72,6 @@ mod tests { fn header_requires_nonce() { let payload = crate::fixtures::headers_payload(); let (_, headers) = payload.split_first().unwrap(); - // The bytes stop where `nonce` starts. A peer can send this, so `decode` must return - // the error of the field and not stop at its assert. let mut input = &headers[..super::BLOCK_HEADER_SIZE - size_of::()]; assert_eq!( super::BlockHeader::decode(&mut input), diff --git a/src/chain.rs b/src/chain.rs index 1fd98da..8d8c3f2 100644 --- a/src/chain.rs +++ b/src/chain.rs @@ -1,33 +1,17 @@ -//! The header chain. - -/// The most headers that a median time reads: the header below a new header, and the 10 below it. const MEDIAN_TIME_HEADERS_COUNT_MAX: usize = 11; -// This count has one middle, so only a chain below this height has two middle times. const _: () = assert!(!MEDIAN_TIME_HEADERS_COUNT_MAX.is_multiple_of(2)); -/// The most seconds that the time of a header may be after the local clock. pub(crate) const TIME_AHEAD_SECONDS_MAX: u64 = 2 * 60 * 60; -/// One linear chain of headers, from genesis to the tip. It is never empty, each header has proof -/// of work, and each header above genesis has the `bits` that the headers below it require and a -/// time above their median time. On testnet4, each first header of a period above genesis also has -/// a time at most 10 minutes below the header below it. When the chain took a header, its time was -/// at most `TIME_AHEAD_SECONDS_MAX` after the local clock. Each header has at least the lowest -/// `version` of its height on the network. #[derive(Debug)] pub struct Chain { - /// The network of the chain. Its rules bound the target of each header and, on testnet4, the - /// time of each first header of a period. network: crate::chainparams::Network, - /// The headers below the tip, from genesis. The index of a header is its height. below_tip: Vec, tip: crate::block::BlockHeader, - /// The sum of the work of each header, genesis too. work: crate::pow::Work, } -/// The height and the hash of the last header of a chain, and the work of the chain. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct Tip { height: usize, @@ -35,154 +19,75 @@ pub struct Tip { work: crate::pow::Work, } -/// The most headers at the top of a locator that are one height apart. Below them, each step down -/// is twice the step before it, and the last hash is genesis. pub(crate) const LOCATOR_DENSE_COUNT: usize = 12; -/// The most headers with the `bits` of the tip whose work a branch may be below the chain and -/// still go on: about one day of headers. pub(crate) const BRANCH_TIP_HEADERS_BEHIND_MAX: usize = 144; -/// What `Chain::extend_on_locator`, `Chain::extend_branch` or `Chain::extend_low_work_branch` did -/// with headers that passed each check. #[derive(Debug, PartialEq, Eq)] pub(crate) enum Extended { - /// The batch ends on the tip. The chain took it, or the batch had only headers of the chain up - /// to the tip. If the batch was on a header below the tip, the headers above that header are - /// gone. Taken, - /// The batch gives no more work than the chain, so the chain stays and the batch is dropped: - /// an empty batch, or a branch that the peer ends with at most the work of the chain. On the - /// same work, the chain that came first stays. Kept, - /// The batch was full, and its branch has at most the work of the chain. The peer can have more - /// of the branch, and the next batch goes on its last header. Branch(Branch), - /// The batch was full and had no headers of the chain, and its branch is below the chain by - /// more than the margin. The peer can have more of the branch, also with more work than the - /// chain, but the chain keeps no header of it, so the chain stays. A low-work sync from the - /// fork can get the branch. Its first download starts with `headers`, and then - /// `Chain::extend_low_work_branch` takes what it got. BelowMargin { - /// The fork, where the sync starts. `Chain::extend_low_work_branch` puts the headers of - /// the sync on it. start: SyncStart, - /// The work that the sync must reach: the lowest work up to the last header of a branch - /// that the margin keeps. It is above the work at the fork. branch_work_min: crate::pow::Work, - /// The batch, which passed each check of the chain. headers: crate::protocol::Headers, }, } -/// A header of the chain that a low-work sync starts on: the tip, or the fork of a branch below -/// the margin. It holds what the sync reads of the chain at that header. Only `Chain` makes one. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) struct SyncStart { network: crate::chainparams::Network, height: usize, hash: bitcoin_hashes::sha256d::Hash, bits: u32, - /// The work of the chain from genesis up to this header, with it. work: crate::pow::Work, - /// The median time of this header and the 10 headers below it. A header on it needs a time - /// above it. median_time_past: u32, - /// The work of the chain that made this start. A sync on a fork goes on the chain only if the - /// chain did not change, so the chain asserts that its work is the same. chain_work: crate::pow::Work, } -/// The headers that `Chain::extend_above` puts on a branch. #[derive(Debug)] enum Batch { - /// An answer to our `getheaders`. A full one gives the peer room for more headers after it. Answer(crate::protocol::Headers), - /// The headers that a low-work sync of a branch got, in order. They can be more than one batch. Released { headers: Vec, - /// True when the last batch of the sync was full, so the peer can have more headers after - /// them. full: bool, }, } -/// A branch that a peer sends in more than one batch. It is on a header of the chain below the -/// tip, the fork, and it has at most the work of the headers above the fork. Only `Chain` makes -/// one, and only for the chain that it is below. That chain must not change until the next batch, -/// because the work above the fork is the work of that chain. #[derive(Debug, PartialEq, Eq)] pub(crate) struct Branch { - /// The height of the fork. It is below the height of the tip. fork_height: usize, - /// What the branch has above the fork. above_fork: AboveFork, - /// The work of the chain that the branch is below. With the minimum work of the sync, it sets - /// the margin, so the next batch asserts that it is the same. chain_work: crate::pow::Work, } -/// What a `Branch` has above its fork. #[derive(Debug, PartialEq, Eq)] enum AboveFork { - /// No header yet: the peer sent none, or only headers of the chain up to the fork. The next - /// batch goes on the fork, and it can start with more headers of the chain. Empty { - /// The hash of the fork. fork_hash: bitcoin_hashes::sha256d::Hash, }, - /// At least one header, and the branch is in the margin: its chain from genesis has at least - /// the minimum work, and at least the work of the chain less the work of - /// `BRANCH_TIP_HEADERS_BEHIND_MAX` headers with the `bits` of the tip. The headers passed each - /// check on the chain up to the fork. Headers { - /// The headers of the branch, in order. None is a header of the chain, so the first is not - /// the header of the chain above the fork. headers: Vec, - /// The sum of the work of `headers`. work: crate::pow::Work, - /// The hash of the last of `headers`. last_hash: bitcoin_hashes::sha256d::Hash, - /// The highest bound on the time of a header that a check of the branch read. The local - /// clock can go back, so a later batch can have a lower bound. time_max: u64, }, } -/// Why `Chain::extend`, `Chain::extend_on_locator` or `Chain::extend_branch` refused a batch. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum ExtendError { - /// The `prev` of the first header is not the hash of the tip. Only `extend` refuses with this. - /// After the sync, an announcement off our tip gets it, and that makes our `getheaders` due. NotOnTip, - /// The `prev` of the first header is not the hash of a header of the locator of the chain. Only - /// `extend_on_locator` refuses with this. The tip is the first header of the locator. NotOnLocator, - /// The `prev` of a header is not the hash of the header before it. For the first header of a - /// batch on a branch, that is the last header of the branch. After headers of the chain at the - /// start of a batch, it is the last of them. NotContinuous, - /// The `bits` of a header are not a target in the range of the network, or the hash of the - /// header is above that target. ProofOfWork, - /// The `bits` of a header are not the `bits` that the headers below it require. On testnet4 the - /// answer also reads the time of the header. WrongBits, - /// The time of a header is at or below the median time of the headers below it. TimeTooOld, - /// On testnet4, the time of the first header of a period is more than 10 minutes below the - /// header below it. TimeTimewarpAttack, - /// The time of a header is more than `TIME_AHEAD_SECONDS_MAX` after the local clock. The same - /// header can pass at a later clock. TimeTooNew, - /// The `version` of a header is below the lowest version of its height on the network. VersionTooLow, } -/// The headers below one header of a batch, by height: the chain, then the part of the batch that -/// comes before that header. A batch is not on the chain until each of its headers passes, so the -/// rules read it through this. #[derive(Clone, Copy, Debug)] pub(crate) struct Ancestors<'a> { below_tip: &'a [crate::block::BlockHeader], @@ -191,10 +96,8 @@ pub(crate) struct Ancestors<'a> { } impl Chain { - /// A chain with only the genesis header of `network`. pub fn new(network: crate::chainparams::Network) -> Chain { let genesis = network.genesis(); - // A test holds that each genesis has proof of work, so peer bytes cannot reach this. let Some((_, work)) = crate::pow::proven(&genesis, network) else { panic!("the genesis of {network:?} has no proof of work"); }; @@ -206,16 +109,10 @@ impl Chain { } } - /// Drops each header above genesis. The network stays, so a chain never changes its network. pub(crate) fn restart(&mut self) { *self = Chain::new(self.network); } - /// Puts all of `headers` on the tip, in order, or none of them. An empty batch changes - /// nothing. The first header that fails gives the error. For one header, its `prev` is checked - /// first, then its proof of work, then its `bits`, then its time against the median time, then - /// its time against the timewarp rule, then its time against `clock`, then its `version`. - /// `clock` is the local clock, in seconds since the Unix epoch. pub(crate) fn extend( &mut self, headers: crate::protocol::Headers, @@ -231,12 +128,6 @@ impl Chain { self.extend_tip(headers, time_max(clock)) } - /// Puts `headers`, an answer to a `getheaders` with the locator of the chain, on the header of - /// the locator that the first `prev` names. On the tip, this is `extend`. A header below the - /// tip is a fork, and `extend_above` goes on from it with a branch that has no header yet. The - /// chain finds only a header of the locator by its hash, so a batch on another header below the - /// tip is refused. For a batch on a header below the tip, the chain must have at least - /// `work_min`. pub(crate) fn extend_on_locator( &mut self, headers: crate::protocol::Headers, @@ -261,11 +152,6 @@ impl Chain { self.extend_above(branch, Batch::Answer(headers), clock, work_min) } - /// Puts `headers`, an answer to a `getheaders` with only the last header of `branch`, on that - /// header, with `extend_above`. `branch` is what this chain returned for the batch before, and - /// the chain did not change since. An empty batch ends the branch. The branch has at most the - /// work of the chain, so the chain stays. The chain must have at least `work_min`, the minimum - /// of the batch before. pub(crate) fn extend_branch( &mut self, branch: Branch, @@ -276,12 +162,6 @@ impl Chain { self.extend_on_branch(branch, Batch::Answer(headers), clock, work_min) } - /// Puts `headers`, each header that a low-work sync got, in order, on `start`, the fork that - /// came with `Extended::BelowMargin`, with `extend_above`, as `extend_branch` puts one batch. - /// The chain did not change since. `full` is true when the last batch of the sync was full, so - /// the peer can have more of the branch. The chain must have at least `work_min`, as in - /// `extend_branch`. The sync ends when the headers reach the `branch_work_min` of - /// `Extended::BelowMargin`, so they are not below the margin. pub(crate) fn extend_low_work_branch( &mut self, start: SyncStart, @@ -290,16 +170,10 @@ impl Chain { clock: u64, work_min: crate::pow::Work, ) -> Result { - // The work at the fork is below the minimum of the sync, so the sync got at least one - // header. assert!(!headers.is_empty()); - // The sync starts on the fork, so a refusal of the first header because it is not on the - // fork would be our error. if let Some(first) = headers.first() { assert_eq!(first.prev, start.hash); } - // `extend_on_branch` holds that the fork is below the tip, and that the chain is the chain - // that made `start`. let branch = Branch { fork_height: start.height, above_fork: AboveFork::Empty { @@ -310,8 +184,6 @@ impl Chain { self.extend_on_branch(branch, Batch::Released { headers, full }, clock, work_min) } - /// Puts `batch` on the last header of `branch`, which this chain returned, with - /// `extend_above`. No headers end the branch, and the chain stays. fn extend_on_branch( &mut self, branch: Branch, @@ -319,9 +191,6 @@ impl Chain { clock: u64, work_min: crate::pow::Work, ) -> Result { - // The fork is still a header of the chain below the tip, at its height. The hash of a - // header holds each header below it, so the chain up to the fork is the chain that checked - // the branch. assert!(branch.fork_height < self.below_tip.len()); let fork_hash = self.header_at(branch.fork_height).hash(); match &branch.above_fork { @@ -330,9 +199,6 @@ impl Chain { assert_eq!(headers.first().map(|first| first.prev), Some(fork_hash)); } } - // The chain above the fork did not change either, and the minimum is the same. So the - // margin is the margin that the batch before passed, and `extend_above` can assert that a - // branch with a header of its own passes it again. assert_eq!(self.work, branch.chain_work); if batch.headers().is_empty() { return Ok(Extended::Kept); @@ -340,29 +206,6 @@ impl Chain { self.extend_above(branch, batch, clock, work_min) } - /// Goes on with `branch` and `batch`, headers that are not empty, on the last header of the - /// branch. When the branch has no header, the batch can start with headers of the chain above - /// the fork. These move the fork up, and they do not go into the branch. If they reach the tip, - /// the rest of the batch goes on the tip, as in `extend`. Else the rest goes through the checks - /// of `extend`, on the chain up to the fork and on the headers of the branch. - /// - /// Then the chain takes the branch if it has more work than the headers above the fork, and - /// drops those headers. Else a full batch makes the branch go on, but only if the margin keeps - /// it: the work up to the last header of the branch is at least the work of the chain less - /// `BRANCH_TIP_HEADERS_BEHIND_MAX` headers with the work of the tip, and at least `work_min`. - /// So a peer must pay for about the work of the chain above the fork before the chain keeps a - /// branch in memory. The chain keeps no header of a branch below the margin. A full batch of - /// only the branch gives the batch back, for a low-work sync from the fork. If the batch - /// started with headers of the chain, the peer sent less of the branch than a full batch, so - /// the branch goes on from the fork with no header, and the next batch has a full batch of it. - /// - /// The sum of the work above the fork stops when it passes the work of the branch plus the - /// margin. It reads at most the headers between the fork and the tip. It reads about one of - /// our headers for each header of the branch only when our headers have about the work of the - /// branch each. A run of our headers with less work each, such as the minimum-difficulty - /// headers of testnet4, makes it read more. Each header of the branch passed the proof of work - /// at its `bits`, so the peer pays for the work that each read stands for, except the reads of - /// the margin. fn extend_above( &mut self, branch: Branch, @@ -374,28 +217,21 @@ impl Chain { let Branch { mut fork_height, above_fork, - // `extend_branch` asserts it against the chain. chain_work: _, } = branch; let tip_height = self.below_tip.len(); - // Each caller returns on an empty batch, and a branch is below the tip. assert!(!batch.headers().is_empty()); assert!(fork_height < tip_height); let time_max = time_max(clock); - // The headers of the branch before the batch, their work, the highest bound on time that - // their checks read, and the count of headers of the chain at the start of the batch. let (branch_headers, work_branch_before, time_max_before, shared_count) = match above_fork { AboveFork::Headers { headers, work, - // The next batch goes on it, and `check` reads it from the headers. last_hash: _, time_max: time_max_before, } => (headers, work, time_max_before, 0), AboveFork::Empty { fork_hash: _ } => { - // The headers of the chain from the fork up are below the tip, so they are equal - // only to the headers of the chain. The compare needs no hash. let ours = self.below_tip[fork_height + 1..] .iter() .chain(std::iter::once(&self.tip)); @@ -405,8 +241,6 @@ impl Chain { .zip(ours) .take_while(|(theirs, ours)| theirs == ours) .count(); - // With no headers of the chain at the start, the fork stays below the tip and the - // batch is not empty, so this returns only after headers of the chain. fork_height += shared_count; let rest = &batch.headers()[shared_count..]; if fork_height == tip_height { @@ -422,7 +256,6 @@ impl Chain { } return Ok(Extended::Kept); } - // With no header before the batch, the bound of the batch is the highest. (Vec::new(), crate::pow::Work::ZERO, time_max, shared_count) } }; @@ -433,44 +266,29 @@ impl Chain { let (last_hash, work_batch) = self.check(fork_height, &headers, branch_count, time_max)?; let work_branch = work_branch_before.saturating_add(work_batch); let work_stop = work_branch.saturating_add(self.branch_margin(work_min)); - // The bound of this loop is the count of headers above the fork, and the work of the - // branch stops it early. See the doc of this function. let mut work_above_fork = crate::pow::Work::ZERO; for height in fork_height + 1..=tip_height { let header_work = self.stored_work(self.header_at(height)); work_above_fork = work_above_fork.saturating_add(header_work); if work_above_fork > work_stop { - // A branch with a header of its own passed the margin before, and its work only - // rises. So only a branch with no header of its own gets here. assert_eq!(branch_count, 0); return Ok(match (full, shared_count) { - // The peer has no more of the branch, which is below the margin, so it has - // less work than the chain. (false, _) => Extended::Kept, - // A full answer with no headers of the chain had the most of the branch that - // one batch can have, so it goes to a low-work sync from the fork. (true, 0) => match batch { Batch::Answer(answer) => Extended::BelowMargin { start: self.sync_start(fork_height), branch_work_min: self.branch_work_min(work_min), headers: answer, }, - // The headers of a low-work sync reach the `branch_work_min` of its - // `Extended::BelowMargin`, so the margin keeps them. Batch::Released { .. } => { panic!("a low-work sync of a branch ended below the margin") } }, - // After headers of the chain, a full batch had less of the branch than that, - // so the next batch goes on the fork. (true, _) => Extended::Branch(self.branch_on_fork(fork_height)), }); } } - // The fork is below the tip, so the loop read at least one header, and each has work. assert!(work_above_fork > crate::pow::Work::ZERO); - // A check can read a lower bound than a check of an earlier batch of the branch, so the - // store reads the highest. let time_max = time_max.max(time_max_before); if work_branch <= work_above_fork { if full { @@ -488,21 +306,17 @@ impl Chain { return Ok(Extended::Kept); } - // The sum of the chain holds the sum above the fork, so this does not go below zero. let work_at_fork = self.work.minus(work_above_fork); let count = headers.len(); self.tip = self.below_tip[fork_height]; self.below_tip.truncate(fork_height); self.work = work_at_fork; self.extend_store(headers, time_max, work_at_fork.saturating_add(work_branch)); - // The checks proved the last header of the branch, so this holds that the store took each - // one. The height holds that the fork stays once, and that no header above it stays. assert_eq!(self.tip.hash(), last_hash); assert_eq!(self.below_tip.len(), fork_height + count); Ok(Extended::Taken) } - /// Puts `headers`, a batch that is not empty, on the tip, or none of them. fn extend_tip( &mut self, headers: Vec, @@ -512,17 +326,11 @@ impl Chain { let count = headers.len(); let (last_hash, work_batch) = self.check(tip_height, &headers, 0, time_max)?; self.extend_store(headers, time_max, self.work.saturating_add(work_batch)); - // The checks proved the last header of the batch, so this holds that the store took each - // one, and the height holds that it took each one once. assert_eq!(self.tip.hash(), last_hash); assert_eq!(self.below_tip.len(), tip_height + count); Ok(()) } - /// How far the work up to the last header of a branch may be below the work of the chain for - /// the branch to go on: the work of `BRANCH_TIP_HEADERS_BEHIND_MAX` headers with the `bits` of - /// the tip, or the work of the chain above `work_min` if that is less. The chain must have at - /// least `work_min`. fn branch_margin(&self, work_min: crate::pow::Work) -> crate::pow::Work { assert!(self.work >= work_min); let tip_work = self.stored_work(&self.tip); @@ -533,31 +341,23 @@ impl Chain { behind_tip.min(self.work.minus(work_min)) } - /// The work that the chain of a branch from genesis must have to go on: the work of the chain - /// less `branch_margin`. It is at least `work_min`, which the chain must have. A low-work sync - /// of a branch below the margin ends when the branch reaches it. fn branch_work_min(&self, work_min: crate::pow::Work) -> crate::pow::Work { let branch_work_min = self.work.minus(self.branch_margin(work_min)); assert!(branch_work_min >= work_min); branch_work_min } - /// Where a low-work sync on the tip starts. pub(crate) fn sync_start_on_tip(&self) -> SyncStart { self.sync_start(self.below_tip.len()) } - /// The work of the chain from genesis up to the header at `height`, with it. This reads each - /// header above that header, so it reads none for the tip. fn work_at(&self, height: usize) -> crate::pow::Work { let work_above = (height + 1..=self.below_tip.len()) .map(|height| self.stored_work(self.header_at(height))) .fold(crate::pow::Work::ZERO, crate::pow::Work::saturating_add); - // The sum of the chain holds the sum above the header, so this does not go below zero. self.work.minus(work_above) } - /// Where a low-work sync on the header at `height` starts. fn sync_start(&self, height: usize) -> SyncStart { let header = self.header_at(height); let ancestors = Ancestors { @@ -576,7 +376,6 @@ impl Chain { } } - /// A branch with no header on the fork at `fork_height`, a header of the chain below the tip. fn branch_on_fork(&self, fork_height: usize) -> Branch { assert!(fork_height < self.below_tip.len()); Branch { @@ -588,10 +387,6 @@ impl Chain { } } - /// The hashes of the locator of the chain, from the tip down: the tip and the 11 headers below - /// it, then steps down that are twice the step before, then genesis. A peer answers with the - /// headers after the first of them on its chain, so the answer starts near the fork of its - /// chain and ours. pub(crate) fn locator(&self) -> Vec { let locator: Vec<_> = locator_heights(self.below_tip.len()) .map(|height| self.header_at(height).hash()) @@ -601,13 +396,6 @@ impl Chain { locator } - /// Checks `headers[from..]` as a batch on the header at `base_height`, with the headers below - /// it, and on `headers[..from]`, the headers of a branch on that header. The base is the tip - /// for `extend`, or a fork below it. The `prev` of the first header of the batch must be the - /// hash of the header below it: the last header of the branch, or the base. Returns the hash of - /// the last header, and the sum of the work of the batch. For one header, its `prev` is checked - /// first, then its proof of work, then its `bits`, then its time against the median time, then - /// its time against the timewarp rule, then its time against `time_max`, then its `version`. fn check( &self, base_height: usize, @@ -617,14 +405,11 @@ impl Chain { ) -> Result<(bitcoin_hashes::sha256d::Hash, crate::pow::Work), ExtendError> { let base = self.header_at(base_height); let below_base = &self.below_tip[..base_height]; - // Each caller has a batch that is not empty. assert!(from < headers.len()); let below_batch = match from.checked_sub(1) { Some(index) => &headers[index], None => base, }; - // The hash of a header checks its proof of work and the `prev` of the next header, so one - // pass hashes each header of the batch once, after the header below it. let mut prev = below_batch.hash(); let mut work = crate::pow::Work::ZERO; for (index, header) in headers.iter().enumerate().skip(from) { @@ -657,12 +442,10 @@ impl Chain { return Err(ExtendError::VersionTooLow); } } - // The batch has a first header, and each header that passes has work. assert!(work > crate::pow::Work::ZERO); Ok((prev, work)) } - /// The header at `height`, which must be at most the height of the tip. fn header_at(&self, height: usize) -> &crate::block::BlockHeader { match self.below_tip.get(height) { Some(header) => header, @@ -673,7 +456,6 @@ impl Chain { } } - /// The work of `header`, a header of the chain. The chain took it with a target, so it has one. fn stored_work(&self, header: &crate::block::BlockHeader) -> crate::pow::Work { match crate::pow::work(header.bits, self.network) { Some(work) => work, @@ -681,26 +463,14 @@ impl Chain { } } - /// Puts each of `headers` on the tip, in order, and `work` as the work of the chain. `check` - /// checked each header against the batch, and each assert here reads the chain. So with a check - /// that skips a header, this panics. `extend_tip` calls this on the tip. `extend_above` calls - /// this on a branch after it drops the headers above the fork, so the tip is then the fork. fn extend_store( &mut self, headers: Vec, time_max: u64, work: crate::pow::Work, ) { - // `extend_tip` and `extend_above` get a batch that is not empty, so each assert - // reads a new header. assert!(!headers.is_empty()); - // Each header has work, so the work of the chain rises. Only a sum above 256 bits can stay - // the same, and no hash can meet the targets that give it. On a branch, the work of the - // chain is the work at the fork before this, so this holds there too. assert!(work > self.work); - // `check` adds up the work of the batch, and this adds it up again from the stored - // headers. So a sum that reads the wrong header, or one header twice, fails at the end. It - // needs no hash. A header with no target gives no sum, and the assert fails too. let mut stored_work = Some(self.work); self.work = work; let genesis_time = self.network.genesis().time; @@ -710,16 +480,9 @@ impl Chain { stored_work = stored_work .zip(crate::pow::work(self.tip.bits, self.network)) .map(|(sum, header_work)| sum.saturating_add(header_work)); - // A median only rises, and the first one reads genesis. So no peer bytes reach this - // while the check on the median holds. assert!(self.tip.time > genesis_time); - // The bound is the same for each header, so this holds that the check read each one. assert!(u64::from(self.tip.time) <= time_max); - // The lowest version reads only the height, so this check of each header is cheap. It - // holds that `check` read each header. assert!(self.tip.version >= self.network.version_min(self.below_tip.len())); - // The first header of a period is rarely the last of a batch, so this reads each - // header. It reads the chain, and `check` reads the batch. assert!( self.tip.time >= crate::pow::timewarp_time_min(self.network, self.ancestors_of_tip()) @@ -727,9 +490,6 @@ impl Chain { } assert_eq!(stored_work, Some(self.work)); let ancestors = self.ancestors_of_tip(); - // The checks in `check` read the batch. These read the chain: the tip is on the header - // below it, it has proof of work, it has the `bits` that the headers below it require, and - // its time is above their median time. assert_eq!(self.tip.prev, ancestors.tip.hash()); assert!(crate::pow::proven(&self.tip, self.network).is_some()); assert_eq!( @@ -739,8 +499,6 @@ impl Chain { assert!(self.tip.time > ancestors.median_time_past()); } - /// The headers below the tip. A batch that is not empty puts the old tip below the new tip, so - /// only a chain above genesis calls this. fn ancestors_of_tip(&self) -> Ancestors<'_> { assert!(!self.below_tip.is_empty()); let last_index = self.below_tip.len() - 1; @@ -751,12 +509,10 @@ impl Chain { } } - /// The network of the chain. pub(crate) fn network(&self) -> crate::chainparams::Network { self.network } - /// The height and the hash of the last header, and the work of the chain. pub(crate) fn tip(&self) -> Tip { Tip { height: self.below_tip.len(), @@ -766,18 +522,10 @@ impl Chain { } } -/// The bound on the time of a header at the local clock `clock`, in seconds since the Unix epoch. -/// The clock can be `u64::MAX`, so the add saturates. The compare is in `u64`, so a bound above -/// `u32::MAX` takes each time. fn time_max(clock: u64) -> u64 { clock.saturating_add(TIME_AHEAD_SECONDS_MAX) } -/// The heights of the locator of a chain with its tip at `tip_height`, from the tip down. The first -/// `LOCATOR_DENSE_COUNT` are one height apart. Then each step is twice the step before it. The -/// last height is 0, genesis. So a locator has about 12 hashes plus the count of bits of the -/// height. The answer of a peer starts at the fork when the fork is at most 11 headers below the -/// tip. Else it starts at most about as far below the fork as the fork is below the tip. fn locator_heights(tip_height: usize) -> impl Iterator { let mut next = Some(tip_height); let mut step: usize = 1; @@ -785,16 +533,11 @@ fn locator_heights(tip_height: usize) -> impl Iterator { std::iter::from_fn(move || { let height = next?; count += 1; - // Each caller puts the locator in a `getheaders`, or reads a header for each hash of it. assert!(count <= crate::protocol::LOCATOR_HASHES_COUNT_MAX); next = (height > 0).then(|| height.saturating_sub(step)); - // The step is at least 1, so each height is below the height before it, and the iterator - // ends at genesis. if let Some(next) = next { assert!(next < height); } - // From the 11th hash on, the step doubles after the step down. So the 12th hash is one - // height below the 11th, and the 13th is two below the 12th. if count >= LOCATOR_DENSE_COUNT - 1 { step = step.saturating_mul(2); } @@ -803,10 +546,7 @@ fn locator_heights(tip_height: usize) -> impl Iterator { } impl<'a> Ancestors<'a> { - /// `tip` as the only header of a chain, and `batch` above it. Only the tests and the fuzz - /// script call this, so the rules of another module read these headers and cannot write them. #[cfg(any(test, fuzzing))] - // Only cargo-mutants reads this attribute. #[cfg_attr(false, mutants::skip)] pub(crate) fn on_tip( tip: &'a crate::block::BlockHeader, @@ -819,12 +559,10 @@ impl<'a> Ancestors<'a> { } } - /// The height of the header above these headers. It is at least 1, because a chain has genesis. pub(crate) fn height_above(self) -> usize { self.below_tip.len() + 1 + self.batch.len() } - /// The highest of these headers. There is always one, because `tip` is a header. pub(crate) fn last(self) -> &'a crate::block::BlockHeader { match self.batch { [.., last] => last, @@ -832,7 +570,6 @@ impl<'a> Ancestors<'a> { } } - /// The header at `height`, which must be below `height_above`. pub(crate) fn at(self, height: usize) -> &'a crate::block::BlockHeader { match height.checked_sub(self.below_tip.len()) { None => &self.below_tip[height], @@ -841,12 +578,6 @@ impl<'a> Ancestors<'a> { } } - /// The median of the times of the last `MEDIAN_TIME_HEADERS_COUNT_MAX` headers, or of each - /// header if there are fewer. Times can go back, so this sorts them. With an even count, which - /// only a chain below that height has, this is the higher of the two middle times. - /// - /// A peer picks each time, so no value may panic. A peer also runs this once for each header - /// of a batch. So it reads at most `MEDIAN_TIME_HEADERS_COUNT_MAX` headers and uses no heap. fn median_time_past(self) -> u32 { let height_above = self.height_above(); let times_count = height_above.min(MEDIAN_TIME_HEADERS_COUNT_MAX); @@ -854,27 +585,20 @@ impl<'a> Ancestors<'a> { let height_first = height_above - times_count; let mut times_buffer = [0; MEDIAN_TIME_HEADERS_COUNT_MAX]; let times = &mut times_buffer[..times_count]; - // Each place of `times` gets a time, so no zero of the buffer can reach the median. for (index, time) in times.iter_mut().enumerate() { *time = self.at(height_first + index).time; } - // This sort needs no heap, and two equal times are the same. times.sort_unstable(); - // Half of an odd count, rounded down, is its middle. An even count has two middles, and - // half of it is the higher. let middle_index = times_count / 2; times[middle_index] } } impl Tip { - /// The hash of the last header, in wire order. pub(crate) fn hash(&self) -> bitcoin_hashes::sha256d::Hash { self.hash } - /// The hash of the last header in display order, the reverse of the wire order, as 64 hex - /// digits. pub(crate) fn hash_display(&self) -> impl std::fmt::Display { let hash = self.hash; std::fmt::from_fn(move |f| { @@ -885,52 +609,42 @@ impl Tip { }) } - /// The height of the last header. pub(crate) fn height(&self) -> usize { self.height } - /// The work of the chain. pub(crate) fn work(&self) -> crate::pow::Work { self.work } } impl SyncStart { - /// The network of the chain. pub(crate) fn network(&self) -> crate::chainparams::Network { self.network } - /// The height of the header. pub(crate) fn height(&self) -> usize { self.height } - /// The hash of the header. pub(crate) fn hash(&self) -> bitcoin_hashes::sha256d::Hash { self.hash } - /// The `bits` of the header. pub(crate) fn bits(&self) -> u32 { self.bits } - /// The work of the chain from genesis up to the header, with it. pub(crate) fn work(&self) -> crate::pow::Work { self.work } - /// The median time of the header and the 10 headers below it, or of each header if there are - /// fewer. A header on it needs a time above it. pub(crate) fn median_time_past(&self) -> u32 { self.median_time_past } } impl Batch { - /// The headers, in order. fn headers(&self) -> &[crate::block::BlockHeader] { match self { Batch::Answer(answer) => answer.as_slice(), @@ -938,7 +652,6 @@ impl Batch { } } - /// True when the peer can have more headers after these. fn is_full(&self) -> bool { match self { Batch::Answer(answer) => answer.is_full(), @@ -948,8 +661,6 @@ impl Batch { } impl Branch { - /// The hash of the last header of the branch, or of the fork when there is none. The next - /// batch goes on it. pub(crate) fn last_hash(&self) -> bitcoin_hashes::sha256d::Hash { match &self.above_fork { AboveFork::Empty { fork_hash } => *fork_hash, @@ -986,27 +697,13 @@ impl std::fmt::Display for ExtendError { impl std::error::Error for ExtendError {} #[cfg(fuzzing)] -// Only cargo-mutants reads this attribute. Its test runs do not build this module. #[cfg_attr(false, mutants::skip)] pub(crate) mod fuzz { - /// The first headers of a batch that go through the check. A median reads at most - /// `MEDIAN_TIME_HEADERS_COUNT_MAX` times, so the first header with a time out of that window - /// reaches the last new path. The headers above it only give a run more windows of times. In a - /// batch that is longer than its input, the later headers have only zeros. A check of each - /// header costs 40% of the runs of the `headers` target. With this bound, the cost is inside the - /// noise of a run. const MEDIAN_CHECK_HEADERS_COUNT_MAX: usize = 4 * super::MEDIAN_TIME_HEADERS_COUNT_MAX; - /// The headers below the tip in the timewarp check. The rule reads only their count, and a - /// `static` means that a run copies nothing. static BELOW_TIP: [crate::block::BlockHeader; 2016] = [crate::chainparams::Network::Testnet4.genesis(); 2016]; - /// A peer picks each `time`, so `header` goes through the timewarp rule as the header below a - /// first header of a period, on each network. A batch has fewer headers than a period, so it - /// does not reach this height by itself. Each height next to the first header and each other - /// network has no bound. A person wrote the heights and the 600, and the answer is in wider - /// numbers, so a wrong constant or a subtract that wraps fails here. pub(crate) fn timewarp_time_min_check(header: &crate::block::BlockHeader) { let ancestors = |height_above: usize| super::Ancestors { below_tip: &BELOW_TIP[..height_above - 1], @@ -1034,11 +731,6 @@ pub(crate) mod fuzz { } } - /// A peer picks each `time` of `headers`, so the first headers go through the median time, as - /// the header above the ones before it. It must return for any value. This check does not sort: - /// of `times_count` times, only the time at index `times_count / 2` of the sorted times has - /// more than `times_count / 2` times at or below it, and at least - /// `times_count - times_count / 2` at or above it. pub(crate) fn median_time_past_check(headers: &[crate::block::BlockHeader]) { let genesis = crate::chainparams::Network::Regtest.genesis(); for index in 0..headers.len().min(MEDIAN_CHECK_HEADERS_COUNT_MAX) { @@ -1092,7 +784,6 @@ mod tests { let mut chain = super::Chain::new(crate::chainparams::Network::Regtest); let before = chain.tip(); - // The first header is on block 1, which the chain does not have. assert_eq!( chain.extend( crate::fixtures::headers_batch(&headers[1..]), @@ -1110,7 +801,6 @@ mod tests { let mut chain = super::Chain::new(crate::chainparams::Network::Regtest); let before = chain.tip(); - // Blocks 1 and 2 connect, but block 4 is not on block 2, so the chain takes none. assert_eq!( chain.extend( crate::fixtures::headers_batch(&headers), @@ -1124,8 +814,6 @@ mod tests { #[test] fn extend_refuses_a_batch_with_a_hash_above_its_target() { let mut headers = crate::fixtures::headers_on_genesis(2); - // A top byte of 0x80 or more is above each regtest target. The top byte of a hash is its - // last byte in wire order. headers[1].nonce = (0..=u32::MAX) .find(|nonce| { let header = crate::block::BlockHeader { @@ -1138,7 +826,6 @@ mod tests { let mut chain = super::Chain::new(crate::chainparams::Network::Regtest); let before = chain.tip(); - // The bad header is the last, and block 1 is good, so the chain takes none. assert_eq!( chain.extend( crate::fixtures::headers_batch(&headers), @@ -1151,8 +838,6 @@ mod tests { #[test] fn extend_refuses_a_target_above_the_limit_of_the_network() { - // This header would pass on regtest, because it has the `bits` of regtest and a hash below - // that target. let network = crate::chainparams::Network::Mainnet; let header = crate::pow::mined_for_regtest(crate::block::BlockHeader { prev: network.genesis().hash(), @@ -1171,7 +856,6 @@ mod tests { #[test] fn extend_checks_the_prev_of_a_header_before_its_proof_of_work() { - // `bits` of 0 are no target, so this header fails proof of work with any hash. let bad = crate::block::BlockHeader { prev: bitcoin_hashes::sha256d::Hash::from_byte_array([1; 32]), bits: 0, @@ -1196,8 +880,6 @@ mod tests { #[test] fn extend_refuses_a_batch_with_bits_that_are_not_required() { let mut headers = crate::fixtures::headers_on_genesis(2); - // These `bits` are in the range, and the mined hash is below their target, so only the rule - // of the network refuses them. headers[1] = crate::pow::mined_for_regtest(crate::block::BlockHeader { bits: 0x207f_fffe, ..headers[1] @@ -1205,7 +887,6 @@ mod tests { let mut chain = super::Chain::new(crate::chainparams::Network::Regtest); let before = chain.tip(); - // The bad header is the last, and block 1 is good, so the chain takes none. assert_eq!( chain.extend( crate::fixtures::headers_batch(&headers), @@ -1216,8 +897,6 @@ mod tests { assert_eq!(chain.tip(), before); } - /// A regtest header for each of `times`, each on the header before it, the first on `below`. - /// Each has `fixtures::HEADER_VERSION`, so `below` can be genesis. fn mined_on(below: crate::block::BlockHeader, times: &[u32]) -> Vec { let mut headers = Vec::with_capacity(times.len()); let mut prev = below.hash(); @@ -1234,30 +913,19 @@ mod tests { headers } - /// Each row mines the headers below, and splits them between the chain and the batch. On each - /// split, a batch with a time at the median or one second below it must leave the chain as it - /// was, and a batch with a time one second above the median must pass. #[test] fn extend_takes_a_time_only_above_the_median_time_of_the_headers_below() { let genesis = crate::chainparams::Network::Regtest.genesis(); - // The seconds after the genesis time of each header above genesis, and of their median - // time. A person wrote each median, from the times with genesis at 0. let cases: [(&str, &[u32], u32); 7] = [ ("only genesis", &[], 0), - // The lower of the two middle times is genesis. ("two times", &[100], 100), - // A time below the tip can pass. ("three times", &[100, 200], 100), - // With no sort, the same index gives 200 or 100. ("four times that go back", &[100, 200, 150], 150), - // With no sort, the same index gives 155. ( "eleven times that go back", &[100, 200, 150, 160, 155, 300, 156, 400, 157, 158], 157, ), - // The 5000 is the twelfth time below, so it is not read. With one more time or one less - // time, the median is 100. ( "more than eleven times", &[ @@ -1265,10 +933,6 @@ mod tests { ], 90, ), - // The 5000 and the 6000 are the twelfth and thirteenth times below, so they are not - // read. With two more times, the median is 100. The row above gives 90 there, because - // its two times are on each side of the median. This row gives 90 with four more - // times, and the row above does not. ( "more than thirteen times", &[ @@ -1282,11 +946,9 @@ mod tests { let below = mined_on(genesis, ×); let top = *below.last().unwrap_or(&genesis); let median_time = genesis.time + median_seconds; - // Each refused header is not the last, and the header on it has a legal time. let refused = [median_time, median_time - 1] .map(|time| mined_on(top, &[time, genesis.time + 9000])); let taken = mined_on(top, &[median_time + 1]); - // Each split reads the times from other parts of the chain and the batch. for chain_count in [0, below.len() / 2, below.len()] { let (on_chain, in_batch) = below.split_at(chain_count); let mut chain = super::Chain::new(crate::chainparams::Network::Regtest); @@ -1329,7 +991,6 @@ mod tests { #[test] fn extend_checks_the_bits_of_a_header_before_its_time() { - // The genesis time is the median time here, so these fail both checks. let genesis = crate::chainparams::Network::Regtest.genesis(); let header = crate::pow::mined_for_regtest(crate::block::BlockHeader { prev: genesis.hash(), @@ -1347,12 +1008,6 @@ mod tests { ); } - /// A chain with `real` at their heights and the last of them as the tip. Each other height has - /// the genesis header, so only what the `bits` rule reads is real. A test cannot mine a header - /// on these networks, so the tip must be a real header for the next real header to pass. The - /// median time here is the old genesis time, so a test on this chain holds nothing about it. - /// The work of the chain is the work of genesis, so a test reads only the work that a batch - /// adds. fn chain_with( network: crate::chainparams::Network, real: &[(usize, crate::block::BlockHeader)], @@ -1383,8 +1038,6 @@ mod tests { 199584, crate::fixtures::SIGNET_RETARGET, ), - // The last header has the limit, so only the `bits` of the first header give the - // answer. ( crate::chainparams::Network::Testnet4, 38304, @@ -1406,8 +1059,6 @@ mod tests { ); assert_eq!(chain.tip().height, last_height + 1, "{network:?}"); - // The same `next` has real proof of work, so with another first time only the rule - // refuses it. let other_first = crate::block::BlockHeader { time: first.time - 600, ..first @@ -1427,10 +1078,6 @@ mod tests { #[test] fn extend_refuses_a_batch_when_no_bits_can_pass() { - // Testnet4 changes the `bits` of the first header of a period. That header is not the tip, - // so the real `next` still chains and has proof of work, and the rule reads these `bits`. - // `0` is no target, and in the smallest time a target of 3 falls to zero. So the rule has - // no answer, and that must be a refusal, not a pass. let [first, last, next] = crate::fixtures::TESTNET4_RETARGET.map(crate::fixtures::header); for bits in [0, 0x0103_0000] { let first = crate::block::BlockHeader { @@ -1460,8 +1107,6 @@ mod tests { crate::fixtures::TESTNET4_RUN.map(crate::fixtures::header); let on_real = || chain_with(network, &[(40025, real)]); - // The last header goes back to the real `bits` through each part of what the rule reads: - // the batch, the tip and the headers below the tip. let batches: [&[&[crate::block::BlockHeader]]; 3] = [ &[&[late_1, late_2, late_3, back]], &[&[late_1, late_2], &[late_3, back]], @@ -1479,8 +1124,6 @@ mod tests { ); } assert_eq!(chain.tip().hash, back.hash()); - // The work of genesis, of three headers at the limit, and of one at the real `bits`. - // The sum is from big integers, not from this code. assert_eq!( chain.tip().work.to_string(), "000000000000000000000000000000000000000000000000030339533015bcbf" @@ -1488,9 +1131,6 @@ mod tests { } } - /// The first header of the period of `last`, in the chains of the timewarp tests. It is two - /// weeks below `last`, so a change of the target keeps the `bits`, on each network that changes - /// them. fn timewarp_first(last: crate::block::BlockHeader) -> crate::block::BlockHeader { crate::block::BlockHeader { time: last.time - 14 * 24 * 60 * 60, @@ -1498,9 +1138,6 @@ mod tests { } } - /// The first header of a period may go back to the bound. Each header of a batch has real proof - /// of work and each other rule takes it, so only this rule refuses it. Each batch reads the - /// header below through the tip and through the batch. #[test] fn extend_on_testnet4_bounds_the_time_of_the_first_header_of_a_period() { let [ @@ -1512,12 +1149,9 @@ mod tests { on_one_below, ] = crate::fixtures::TESTNET4_TIMEWARP.map(crate::fixtures::header); let network = crate::chainparams::Network::Testnet4; - // These are what the names say, so a wrong fixture cannot hold another bound. assert_eq!(last.time - at_bound.time, 600); assert_eq!(last.time - one_below.time, 601); assert!(last.time - far_below.time > 1_000_000); - // A read of the tip in place of the header below gives a bound below this time in the - // second split, so that read lets this header pass. assert!(below_last.time < one_below.time - 600); let first = timewarp_first(last); @@ -1527,7 +1161,6 @@ mod tests { ]; for (real, in_batch) in &splits { let height_tip = real.last().unwrap().0; - // In the first batch the refused header is not the last, and the header on it is legal. for refused in [vec![one_below, on_one_below], vec![far_below]] { let time = refused[0].time; let mut chain = chain_with(network, real); @@ -1558,16 +1191,11 @@ mod tests { } } - /// One header goes back past the bound in each row. Only the first header of a period on - /// testnet4 is refused. The rows are the heights on each side of one first header, the next - /// first header, and each other network at a first header. #[test] fn extend_refuses_a_time_far_back_only_at_the_start_of_a_period_on_testnet4() { let [_, last, _, one_below, ..] = crate::fixtures::TESTNET4_TIMEWARP.map(crate::fixtures::header); let first = timewarp_first(last); - // A test can mine on regtest, so this row needs no fixture, and the `bits` of the fixture - // are not the `bits` of regtest. let regtest_genesis = crate::chainparams::Network::Regtest.genesis(); let regtest_last = crate::block::BlockHeader { time: regtest_genesis.time + 9000, @@ -1628,7 +1256,6 @@ mod tests { #[test] fn extend_checks_the_median_time_before_the_timewarp_rule() { - // The headers below the tip have the time of the tip, so this header fails both rules. let [_, last, _, one_below, ..] = crate::fixtures::TESTNET4_TIMEWARP.map(crate::fixtures::header); let mut real = vec![(0, timewarp_first(last))]; @@ -1644,9 +1271,6 @@ mod tests { ); } - /// Each row has a clock and the time of one header. In one batch that header is the first and - /// the header on it has a legal time, and in the other it is the last. So only that header - /// decides. A refused batch must leave the chain as it was. #[test] fn extend_takes_a_time_only_up_to_two_hours_after_the_clock() { let genesis = crate::chainparams::Network::Regtest.genesis(); @@ -1656,7 +1280,6 @@ mod tests { ); let clock_after_genesis = 100; let clock = u64::from(genesis.time + clock_after_genesis); - // A person wrote the two hours. let at_bound = genesis.time + clock_after_genesis + 2 * 60 * 60; let cases: [(&str, u64, u32, Result<(), super::ExtendError>); 4] = [ ("at the bound", clock, at_bound, Ok(())), @@ -1672,7 +1295,6 @@ mod tests { u32::MAX, Err(super::ExtendError::TimeTooNew), ), - // A plain add of the two hours to this clock panics. ("the last clock", u64::MAX, u32::MAX, Ok(())), ]; for (name, clock, time, expected) in cases { @@ -1709,7 +1331,6 @@ mod tests { #[test] fn extend_checks_the_timewarp_rule_before_the_time_against_the_clock() { - // The clock is far below the time of this header, so it fails both rules. let [_, last, _, one_below, ..] = crate::fixtures::TESTNET4_TIMEWARP.map(crate::fixtures::header); let mut chain = chain_with( @@ -1723,16 +1344,11 @@ mod tests { ); } - /// Each row has the `version` of one header. In one batch that header is at height 1, the first - /// height with a lowest version, and the header on it is legal. In the other batch it is the - /// last, at height 3. So only that header decides. A refused batch must leave the chain as it - /// was. #[test] fn extend_takes_a_version_only_at_or_above_the_lowest_of_its_height() { let genesis = crate::chainparams::Network::Regtest.genesis(); let block_1 = mined_on(genesis, &[genesis.time + 1])[0]; let block_2 = mined_on(block_1, &[genesis.time + 2])[0]; - // A person wrote the 4. let cases: [(&str, i32, Result<(), super::ExtendError>); 3] = [ ("at the bound", 4, Ok(())), ( @@ -1740,7 +1356,6 @@ mod tests { 3, Err(super::ExtendError::VersionTooLow), ), - // The top bit is set. As a `u32`, this version is above the bound. ( "the lowest", i32::MIN, @@ -1786,15 +1401,10 @@ mod tests { } } - /// On mainnet, the lowest version rises at three heights. At each, a header one below the - /// height and a header at the height both have the version one below the new bound. So only - /// the height decides: the first passes, and a batch with both is refused. The second is in a - /// batch, so the height must also count the batch. #[test] fn extend_on_mainnet_raises_the_lowest_version_at_each_height() { let network = crate::chainparams::Network::Mainnet; let tip = crate::fixtures::header(crate::fixtures::MAINNET_VERSION_TIP); - // A person wrote each height and each version. let heights = [(227_931, 1), (363_725, 2), (388_381, 3)]; for ((height, version), [below, at]) in heights .into_iter() @@ -1802,7 +1412,6 @@ mod tests { { let below = crate::fixtures::header(below); let at = crate::fixtures::header(at); - // These are what the names say, so a wrong fixture cannot hold another bound. assert_eq!(below.prev, tip.hash()); assert_eq!(at.prev, below.hash()); assert_eq!(below.version, version); @@ -1832,7 +1441,6 @@ mod tests { #[test] fn extend_checks_the_time_against_the_clock_before_the_version() { - // The clock is far below the time of this header, so it fails both rules. let genesis = crate::chainparams::Network::Regtest.genesis(); let header = crate::pow::mined_for_regtest(crate::block::BlockHeader { version: 3, @@ -1858,7 +1466,6 @@ mod tests { assert_eq!(chain.tip(), before); } - /// A regtest chain of `headers` on genesis. fn regtest_with(headers: &[crate::block::BlockHeader]) -> super::Chain { let mut chain = super::Chain::new(crate::chainparams::Network::Regtest); for batch in crate::protocol::Headers::batches(headers.to_vec()) { @@ -1867,8 +1474,6 @@ mod tests { chain } - /// `chain` takes `headers` as an answer to its locator, at the clock of the fixtures, with no - /// minimum work. fn on_locator( chain: &mut super::Chain, headers: &[crate::block::BlockHeader], @@ -1880,7 +1485,6 @@ mod tests { ) } - /// `chain` takes `headers` as an answer on the last header of `branch`, as `on_locator` does. fn on_branch( chain: &mut super::Chain, branch: super::Branch, @@ -1894,7 +1498,6 @@ mod tests { ) } - /// The branch that `extended` goes on with. fn branch_of(extended: Result) -> super::Branch { match extended { Ok(super::Extended::Branch(branch)) => branch, @@ -1902,8 +1505,6 @@ mod tests { } } - /// Holds that `chain` gave `extended` for `batch`, a full batch of a branch below the margin - /// on genesis. Returns where the low-work sync of the branch starts, and its minimum. fn below_margin_on_genesis( chain: &super::Chain, extended: Result, @@ -1922,8 +1523,6 @@ mod tests { (start, branch_work_min) } - /// What a low-work sync reads of the chain at `start`: its height, hash, bits, work and median - /// time. The work of the chain that made it is not in it. fn read_start( start: super::SyncStart, ) -> ( @@ -1944,7 +1543,6 @@ mod tests { #[test] fn locator_has_12_heights_one_apart_then_steps_that_double_then_genesis() { - // A person wrote each list. for (tip_height, expected) in [ (0, &[0][..]), (1, &[1, 0][..]), @@ -1962,7 +1560,6 @@ mod tests { #[test] fn locator_of_the_highest_height_fits_in_a_getheaders() { - // 12 heights one apart, then one step for each bit of the height, then genesis. let count = super::locator_heights(usize::MAX).count(); assert!( count <= crate::protocol::LOCATOR_HASHES_COUNT_MAX, @@ -2005,8 +1602,6 @@ mod tests { #[test] fn extend_on_locator_takes_a_branch_only_with_more_work() { - // Our tip is block 3. On block 1, a branch of 1 has less work than blocks 2 and 3, a - // branch of 2 the same, and a branch of 3 more. Regtest headers have the same work each. let headers = crate::fixtures::headers_on_genesis(3); for (count, taken) in [(1, false), (2, false), (3, true)] { let branch = crate::fixtures::branch_on(&headers[0], count); @@ -2020,16 +1615,12 @@ mod tests { (super::Extended::Kept, headers.to_vec()) }; assert_eq!(on_locator(&mut chain, &branch), Ok(expected), "{count}"); - // The tip has the work of its chain from genesis, and the height of its branch. assert_eq!(chain.tip(), regtest_with(&ours).tip(), "{count}"); } } #[test] fn extend_on_locator_checks_a_branch_on_the_headers_below_its_first_header() { - // Our tip is block 3, and the median time of our chain is the time of block 2. The first - // header of the branch on block 1 has that time too. It is above the median time of the - // headers below it, genesis and block 1, so the chain takes the branch. let headers = crate::fixtures::headers_on_genesis(3); let branch = crate::fixtures::branch_on(&headers[0], 3); let mut chain = regtest_with(&headers); @@ -2039,7 +1630,6 @@ mod tests { #[test] fn extend_on_locator_refuses_a_batch_on_a_header_that_is_not_in_the_locator() { - // Our tip is block 14, so the locator has blocks 14 down to 3, then block 1, then genesis. let headers = crate::fixtures::headers_on_genesis(14); for (below, expected) in [ (&headers[0], Ok(super::Extended::Taken)), @@ -2054,7 +1644,6 @@ mod tests { #[test] fn extend_on_locator_refuses_a_branch_that_fails_a_check_and_keeps_the_chain() { - // The second header of the branch is not on the first. let headers = crate::fixtures::headers_on_genesis(3); let mut branch = crate::fixtures::branch_on(&headers[0], 3); branch.remove(1); @@ -2066,15 +1655,12 @@ mod tests { assert_eq!(chain.tip(), regtest_with(&headers).tip()); } - /// The regtest genesis. fn genesis() -> crate::block::BlockHeader { crate::chainparams::Network::Regtest.genesis() } #[test] fn extend_on_locator_goes_on_after_a_full_batch_of_our_headers_below_the_tip() { - // Our tip is block 2,001. The batch on genesis is our first 2,000 blocks, so the peer can - // have more after block 2,000, and the next batch goes on it. Our block 2,001 ends there. let headers = crate::fixtures::headers_on_genesis(2_001); let mut chain = regtest_with(&headers); let branch = branch_of(on_locator(&mut chain, &headers[..2_000])); @@ -2088,9 +1674,6 @@ mod tests { #[test] fn extend_on_locator_keeps_none_of_our_headers_in_a_branch() { - // Our tip is block 2,100. The full batch on genesis has our block 1, then a branch of 1,999 - // on it, which has less work than our 2,099 blocks above block 1. So the branch goes on - // from block 1. let headers = crate::fixtures::headers_on_genesis(2_100); let branch = crate::fixtures::branch_on(&headers[0], 1_999); let mut chain = regtest_with(&headers); @@ -2109,8 +1692,6 @@ mod tests { #[test] fn extend_branch_takes_a_branch_over_two_batches_whose_first_has_less_work_than_ours() { - // Our tip is block 2,100. A branch of 2,200 on genesis comes as a full batch of 2,000, - // which has less work than our 2,100 blocks, then a batch of 200. The two have more. let headers = crate::fixtures::headers_on_genesis(2_100); let branch = crate::fixtures::branch_on(&genesis(), 2_200); let mut chain = regtest_with(&headers); @@ -2125,9 +1706,6 @@ mod tests { #[test] fn extend_branch_keeps_the_chain_when_the_peer_ends_the_branch_with_no_more_work() { - // Our tip is block 2,100. After a full batch of 2,000 on genesis, a batch of 100 gives the - // branch the work of our chain, and an empty batch gives it less. Our chain came first, so - // it stays. let headers = crate::fixtures::headers_on_genesis(2_100); let branch = crate::fixtures::branch_on(&genesis(), 2_100); for rest in [&branch[2_000..], &[]] { @@ -2143,9 +1721,6 @@ mod tests { #[test] fn extend_branch_checks_a_batch_on_the_headers_of_the_branch_and_keeps_the_chain() { - // Our tip is block 2,100, and a full batch of a branch of 2,000 on genesis goes on. A batch - // after a gap is not on its last header. A header with the time of the median of the last - // 11 headers of the branch is too old. let headers = crate::fixtures::headers_on_genesis(2_100); let branch = crate::fixtures::branch_on(&genesis(), 2_200); let median = mined_on(branch[1_999], &[branch[1_994].time]); @@ -2162,10 +1737,6 @@ mod tests { #[test] fn extend_branch_takes_a_branch_whose_first_batch_passed_at_a_later_clock() { - // Our tip is block 2,001, and a full batch of a branch of 2,000 on genesis goes on. Then - // the clock goes back, and the bound on the time of a header is below the time of the last - // header of the branch. Two more headers have times below that bound and above the median, - // so the chain takes the branch. let headers = crate::fixtures::headers_on_genesis(2_001); let branch = crate::fixtures::branch_on(&genesis(), 2_000); let more = mined_on(branch[1_999], &[branch[1_996].time, branch[1_997].time]); @@ -2189,11 +1760,6 @@ mod tests { #[test] fn extend_on_locator_goes_on_with_a_full_branch_only_up_to_144_headers_of_the_tip_below() { - // A batch of a branch on genesis. Below our tip at block 2,144, a full batch of 2,000 has - // the work of 144 of our headers less, so it goes on. Below block 2,145, it has less, and - // the chain keeps no header of it, though the peer can have more of it. A low-work sync on - // genesis can get it, up to the work of the chain at block 2,001. A batch of 1,999 is not - // full, so the peer ends the branch there, with less work than ours. for (branch_count, count) in [(2_000, 2_144), (2_000, 2_145), (1_999, 2_145)] { let branch = crate::fixtures::branch_on(&genesis(), branch_count); let headers = crate::fixtures::headers_on_genesis(count); @@ -2220,10 +1786,6 @@ mod tests { #[test] fn extend_on_locator_goes_on_with_a_full_branch_only_at_the_minimum_work() { - // Our tip is block 2,100, so a full batch of a branch of 2,000 on genesis is within 144 - // headers of the tip. Its chain has the work of a chain of 2,000 blocks. So it goes on at - // that minimum. At the minimum of 2,001 blocks, the chain keeps no header of it, and a - // low-work sync must reach that minimum. let headers = crate::fixtures::headers_on_genesis(2_100); let branch = crate::fixtures::branch_on(&genesis(), 2_000); for (count, goes_on) in [(2_000, true), (2_001, false)] { @@ -2249,10 +1811,6 @@ mod tests { #[test] fn extend_on_locator_asks_again_from_the_fork_for_a_branch_below_the_margin_after_our_headers() { - // Our tip is block 2,300. The full batch on genesis has our first 1,000 blocks, then a - // branch of 1,000 on block 1,000. That is more than 144 headers below our 1,300 blocks - // above block 1,000, but a full batch of the branch can have more. So the next batch goes - // on block 1,000, with no header of the branch. A batch of 2,000 there has more work. let headers = crate::fixtures::headers_on_genesis(2_300); let branch = crate::fixtures::branch_on(&headers[999], 2_000); let mut chain = regtest_with(&headers); @@ -2269,9 +1827,6 @@ mod tests { #[test] fn low_work_sync_of_a_branch_starts_as_on_the_tip_of_the_chain_up_to_the_fork() { - // Our tip is block 2,200. The answer to our locator has our first 50 blocks and 1,950 of a - // branch on block 50, and the next batch is a full batch of the branch, below the margin. - // The chain up to block 50 has the same height, hash, bits, work and median time there. let headers = crate::fixtures::headers_on_genesis(2_200); let branch = crate::fixtures::branch_on(&headers[49], 2_000); let mut chain = regtest_with(&headers); @@ -2289,8 +1844,6 @@ mod tests { #[test] fn branch_work_min_is_our_work_less_144_tip_headers_and_at_least_the_minimum() { - // Our chain has genesis and 2,145 blocks, each with the work of genesis. So 144 blocks less - // is the work of the chain up to block 2,001. A minimum above that is the answer. let headers = crate::fixtures::headers_on_genesis(2_145); let chain = regtest_with(&headers); let work_at = |count: usize| regtest_with(&headers[..count]).tip().work(); @@ -2306,10 +1859,6 @@ mod tests { #[test] fn extend_low_work_branch_takes_the_headers_of_the_sync_only_with_more_work() { - // Our tip is block 2,145, and a full batch of a branch on genesis is below the margin. The - // sync of the branch gets more headers than one batch. With 2,300, the branch has more - // work. With 2,145, it has the same work, and the chain that came first stays. With 2,100 - // and a full last batch, the peer can have more of it. let headers = crate::fixtures::headers_on_genesis(2_145); for (count, full) in [ (2_300, false), diff --git a/src/chainparams.rs b/src/chainparams.rs index da4ac10..04ca36a 100644 --- a/src/chainparams.rs +++ b/src/chainparams.rs @@ -1,69 +1,53 @@ -//! The parameters of each network. - -/// A network elo can connect to. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Network { Mainnet, Testnet4, - /// The default signet. Signet, Regtest, } -/// The size of the magic that starts every message. pub(crate) const MAGIC_SIZE: usize = 4; -/// The merkle root of the genesis block of mainnet, signet and regtest. The three have the -/// same coinbase transaction. const GENESIS_MERKLE_ROOT: [u8; 32] = [ 0x3b, 0xa3, 0xed, 0xfd, 0x7a, 0x7b, 0x12, 0xb2, 0x7a, 0xc7, 0x2c, 0x3e, 0x67, 0x76, 0x8f, 0x61, 0x7f, 0xc8, 0x1b, 0xc3, 0x88, 0x8a, 0x51, 0x32, 0x3a, 0x9f, 0xb8, 0xaa, 0x4b, 0x1e, 0x5e, 0x4a, ]; -/// The merkle root of the genesis block of testnet4, which has its own coinbase transaction. const GENESIS_MERKLE_ROOT_TESTNET4: [u8; 32] = [ 0x4e, 0x7b, 0x2b, 0x91, 0x28, 0xfe, 0x02, 0x91, 0xdb, 0x06, 0x93, 0xaf, 0x2a, 0xe4, 0x18, 0xb7, 0x67, 0xe6, 0x57, 0xcd, 0x40, 0x7e, 0x80, 0xcb, 0x14, 0x34, 0x22, 0x1e, 0xae, 0xa7, 0xa0, 0x7a, ]; -/// The highest target of mainnet and testnet4, big-endian. const POW_LIMIT: [u8; 32] = [ 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, ]; -/// The highest target of signet, big-endian. const POW_LIMIT_SIGNET: [u8; 32] = [ 0x00, 0x00, 0x03, 0x77, 0xae, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, ]; -/// The highest target of regtest, big-endian. const POW_LIMIT_REGTEST: [u8; 32] = [ 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, ]; -/// The lowest work of a mainnet chain at the end of a sync, big-endian. It is the work of the real -/// chain at a height in the past, so a real chain has more. const CHAIN_WORK_MIN_MAINNET: [u8; 32] = [ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x12, 0x87, 0x50, 0xf8, 0x2f, 0x4c, 0x36, 0x61, 0x53, 0xa3, 0xa0, 0x30, ]; -/// The lowest work of a testnet4 chain at the end of a sync, big-endian. const CHAIN_WORK_MIN_TESTNET4: [u8; 32] = [ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0xa0, 0xfe, 0x15, 0xd0, 0x17, 0x7d, 0x08, 0x63, 0x04, ]; -/// The lowest work of a signet chain at the end of a sync, big-endian. const CHAIN_WORK_MIN_SIGNET: [u8; 32] = [ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0b, 0x46, 0x3e, 0xa0, 0xa4, 0xb8, ]; -// `NonZeroU16::new` runs at compile time here, so a port of 0 does not build. const PORT_MAINNET: std::num::NonZeroU16 = std::num::NonZeroU16::new(8333).expect("not 0"); const PORT_TESTNET4: std::num::NonZeroU16 = std::num::NonZeroU16::new(48333).expect("not 0"); const PORT_SIGNET: std::num::NonZeroU16 = std::num::NonZeroU16::new(38333).expect("not 0"); @@ -89,7 +73,6 @@ const SEEDS_SIGNET: [&str; 2] = [ ]; impl Network { - /// The bytes that start every message. pub(crate) const fn magic(self) -> [u8; MAGIC_SIZE] { match self { Network::Mainnet => [0xf9, 0xbe, 0xb4, 0xd9], @@ -99,7 +82,6 @@ impl Network { } } - /// The port that a node of the network listens on. pub const fn default_port(self) -> std::num::NonZeroU16 { match self { Network::Mainnet => PORT_MAINNET, @@ -109,9 +91,6 @@ impl Network { } } - /// The names of the DNS seeds of the network. A seed answers the lookup of its name with the - /// addresses of nodes of the network that it chose. Regtest has no real network, so it has no - /// seeds. pub(crate) const fn seeds(self) -> &'static [&'static str] { match self { Network::Mainnet => &SEEDS_MAINNET, @@ -121,7 +100,6 @@ impl Network { } } - /// The highest target that a header of the network may have, big-endian. pub(crate) const fn pow_limit(self) -> [u8; 32] { match self { Network::Mainnet | Network::Testnet4 => POW_LIMIT, @@ -130,10 +108,6 @@ impl Network { } } - /// The lowest work that a chain of the network must have when its sync ends, big-endian. A - /// peer can make a chain of cheap headers, or send only part of its chain. With less work than - /// the real chain had at a height in the past, the chain of the peer is not the chain of the - /// network. Regtest has no real chain, so its minimum is zero and each chain passes. pub(crate) const fn chain_work_min(self) -> [u8; 32] { match self { Network::Mainnet => CHAIN_WORK_MIN_MAINNET, @@ -143,10 +117,6 @@ impl Network { } } - /// The headers for each commitment of a low-work sync. Its first download keeps the - /// commitment, one bit, of one header in each run of this many headers, so its memory is about - /// the height of the chain over this count, in bits. Regtest has no real chain, so its count - /// only makes its tests cheap. pub(crate) const fn commitment_period(self) -> usize { match self { Network::Mainnet => 641, @@ -156,10 +126,6 @@ impl Network { } } - /// The headers that the second download of a low-work sync holds before it gives the first of - /// them to the chain. So each header that the chain gets has about this count over - /// `commitment_period` commitments above it, about 24. A peer that sends another chain the - /// second time passes each commitment by chance, with odds of one half. pub(crate) const fn redownload_buffer_size(self) -> usize { match self { Network::Mainnet => 15_218, @@ -169,17 +135,11 @@ impl Network { } } - /// The lowest `version` that a header at `height` may have. Three rules raise it, to 2, 3 and - /// 4, each from its own height. Below all three heights, each version passes, so the answer is - /// `i32::MIN`. On each network other than mainnet, the three heights are 1. So each header - /// above genesis needs 4, and genesis keeps its version of 1. pub(crate) const fn version_min(self, height: usize) -> i32 { let [version_2_height, version_3_height, version_4_height] = match self { Network::Mainnet => [227_931, 363_725, 388_381], Network::Testnet4 | Network::Signet | Network::Regtest => [1, 1, 1], }; - // The highest version comes first, so a height at or above two of the heights gets the - // higher version. if height >= version_4_height { 4 } else if height >= version_3_height { @@ -191,9 +151,7 @@ impl Network { } } - /// The first header of the chain. pub(crate) const fn genesis(self) -> crate::block::BlockHeader { - // No header comes before genesis. let prev = bitcoin_hashes::sha256d::Hash::from_byte_array([0; 32]); match self { Network::Mainnet => crate::block::BlockHeader { @@ -232,14 +190,11 @@ impl Network { } } -// A chain starts at genesis with no check, and each header of a chain has at least the lowest -// version of its height. So each genesis must have at least the lowest version of height 0. const _: () = assert!(Network::Mainnet.genesis().version >= Network::Mainnet.version_min(0)); const _: () = assert!(Network::Testnet4.genesis().version >= Network::Testnet4.version_min(0)); const _: () = assert!(Network::Signet.genesis().version >= Network::Signet.version_min(0)); const _: () = assert!(Network::Regtest.genesis().version >= Network::Regtest.version_min(0)); -// A low-work sync reads each height modulo the period. const _: () = assert!(Network::Mainnet.commitment_period() > 0); const _: () = assert!(Network::Testnet4.commitment_period() > 0); const _: () = assert!(Network::Signet.commitment_period() > 0); @@ -249,7 +204,6 @@ const _: () = assert!(Network::Regtest.commitment_period() > 0); mod tests { #[test] fn signet_magic_is_the_hash_of_the_default_challenge() { - // The default signet challenge. let challenge = crate::fixtures::hex(concat!( "512103ad5e0edad18cb1f0fc0d28a3d4f1f3e445640337489abb10404f2d1e086be4", "30210359ef5021964fe22d6f8e05b2463c9540ce96883fe3b278760f048f5189f2e6c452ae", @@ -261,7 +215,6 @@ mod tests { assert_eq!(super::Network::Signet.magic(), *hash.first_chunk().unwrap()); } - /// A person wrote each height and each version. Each height of mainnet has a row one below it. #[test] fn version_min_rises_at_each_height() { let cases = [ diff --git a/src/fixtures.rs b/src/fixtures.rs index 51dec75..a0dd360 100644 --- a/src/fixtures.rs +++ b/src/fixtures.rs @@ -1,51 +1,22 @@ -//! Frames that Bitcoin Core sent and real headers, for the tests. -//! -//! Captured on 2026-10-25 from `bitcoind -regtest` v31.1.0 (nixpkgs). A Python -//! script opened a v1 connection, sent a `version`, and read each frame Core -//! sent back until `verack`. -//! -//! The frames after the handshake were captured on 2026-10-26 the same way. The script also -//! sent its `verack` and answered the `ping`. Then `generatetodescriptor 1` mined block 1. -//! -//! The `headers` frame was captured on 2026-11-03 the same way, on a new chain. First -//! `generatetodescriptor 2` mined blocks 1 and 2. After the handshake, the script sent its -//! `verack` and a `getheaders` with genesis as the only locator hash. -//! -//! The `getheaders` frame was captured on 2026-11-03 from a new node with only genesis. The -//! script listened, and `addnode 127.0.0.1: onetry false` made Core connect to it with -//! v1. The script claimed `NODE_NETWORK` in its `version`, then sent its `verack`. Core sent -//! the `getheaders` after its `ping`. -//! -//! The real headers of the other networks were captured on 2026-11-06 from the API of -//! mempool.space. A script checked that each hash is the hash of the explorer and is at most its -//! target, and that each `prev` of a next height is the hash below it. - use crate::serialize::{Decode, Encode}; -/// The real header of mainnet at height 1. Its hash is -/// `00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048`. pub(crate) const MAINNET_BLOCK_1: &str = concat!( "010000006fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000", "982051fd1e4ba744bbbe680e1fee14677ba1a3c3540bf7b1cdb606e857233e0e", "61bc6649ffff001d01e36299", ); -/// Real headers of mainnet at the first change of its target: the first header of the period, the -/// last header of the period, and the next header. pub(crate) const MAINNET_RETARGET: [&str; 3] = [ - // Height 30240. concat!( "01000000e6bf7fd7f7790a63786faa878d0dc7fd8f2ff365732e45862c66075100000000", "700d342f65c7b6834dffb615358a1897016f0448913372190cbe3d27a4b53355", "b1512b4bffff001dbfb02519", ), - // Height 32255. concat!( "0100000049c1daab3b6536ff1b2633c3a316a6e06ec287676cdeec4ca7baae6b00000000", "ac10b36b8f354b3353207de15940a5edbc05bb8364af75b4b5409e7823f2b489", "23ec3a4bffff001dbd5fa412", ), - // Height 32256. concat!( "010000004b0360d834a330ec7833e30e1f523ee05a0793361e29a73421964f9800000000", "27b64a020af294e903feed93768705336a20090612a043f47af462a2f5e5b564", @@ -53,21 +24,17 @@ pub(crate) const MAINNET_RETARGET: [&str; 3] = [ ), ]; -/// Real headers of signet at a change of its target, in the same order. pub(crate) const SIGNET_RETARGET: [&str; 3] = [ - // Height 199584. concat!( "000000200b61bb8b36ad40ceea78544687903a9524f92bcc323cf6810f64dc7a35000000", "cce50bd7b2b2b377dc68951f0949e1b07aa6815da7ad2e323e8fc62af42d880e", "c2976866354e011e0fef3f00", ), - // Height 201599. concat!( "00000020e0b6148086d41986b33ed15c9207ded875683697d11d0ced283a15bf33000000", "2dd8f34d9c5ae2edff24ffe6fdfd4e55fcc3024c6167ccbb069d7e6c38457eed", "b94e7b66354e011ea0d60000", ), - // Height 201600. concat!( "00000020c0bd6f869a30e6d558b41ee8f54844e59714e340b6684574ca5935d974000000", "1bf0ef8a32407a2f59509bb8e159e4f163f40f94a9c519b424178e2a86ec0f4b", @@ -75,22 +42,17 @@ pub(crate) const SIGNET_RETARGET: [&str; 3] = [ ), ]; -/// Real headers of testnet4 at a change of its target, in the same order. The last header of the -/// period has the limit. pub(crate) const TESTNET4_RETARGET: [&str; 3] = [ - // Height 38304. concat!( "00600020a4d64c4535d2a737f425706bfb4a0c9f52d7a76ec5ec79b41e7a241c00000000", "b99b6fafb6db698ef72c8ae17342aebff5f0ddc0f286fe2423501d4cfa3f96db", "786fb26604fa5419aa34e108", ), - // Height 40319. concat!( "00000020e83bfb271fc94cb48f2c36a9210a221fe9129f463527e853ef748b2800000000", "6853ee76759f221c3d39b55a002002af5a133a0e9c81fd6bb1140e20d78f7fa4", "6749c366ffff001d6a2a2005", ), - // Height 40320. concat!( "0000c0201e5267e7ec4667f281a835b7e505ad93496475d661f301480a40d1ac00000000", "6a6f0580e2cf0fbc656a008c77dd0d49c362023400c471f96e7005203efd16c6", @@ -98,35 +60,27 @@ pub(crate) const TESTNET4_RETARGET: [&str; 3] = [ ), ]; -/// Five real headers of testnet4, from one period. The first has the real `bits`. The next three -/// are late, so they have the limit. The last is not late, because its time goes back, so it has -/// the real `bits` again. pub(crate) const TESTNET4_RUN: [&str; 5] = [ - // Height 40025. concat!( "0000dc216d0958dac42bbcadd080874bcadbf82a2bf5d471e4b959bd3400000000000000", "7396863d29deaf6fb0ac5f5af5d8e98b9fa2810716fbff15c2dbccbc9e425768", "8bf0c06604fa54194c40645f", ), - // Height 40026. concat!( "0000002031d230c6c901c3469f269ccf25ad8ce08c34e96c8cd295145100000000000000", "6649dc40961450e280de1923d61e0a21c41fbf38c8b592888b6bb3c5ac984654", "3ff5c066ffff001d4a3c0049", ), - // Height 40027. concat!( "00000020ac7be0202186a0ea4f47beefe9af0f01013df1e7965bd7103c6d130000000000", "4822df05bb5d3870089469c58b924c9bd994193a8b1556ddd9e0824204709e98", "f0f9c066ffff001d7a7d6401", ), - // Height 40028. concat!( "00000020788681150d8e65f1e65c4b7b9657af7366d21c597613a930ff53b94900000000", "c7d27773128946d83d4d41443d284df3a13b7a0212887cb1f625768eb832df5e", "a1fec066ffff001d2da93aba", ), - // Height 40029. concat!( "00c01122c4a8d8f4dff4af9bb9a64a5cb63e52cd8a978ef1283fb4518f9261a100000000", "76db80a56014e1f355a5feb695234cddc8987bfeaaeca35dac88af61c74cfa34", @@ -134,45 +88,32 @@ pub(crate) const TESTNET4_RUN: [&str; 5] = [ ), ]; -/// Made-up headers of testnet4 around the first header of a period, which no real chain has. A real -/// chain cannot hold a first header that the rule on its time refuses, and a test cannot mine at -/// this limit. So a script mined the last five once, on 2026-11-07, in about 60 s on 32 threads. -/// Each has the `bits` of the limit, a merkle root that is made up, and a version and a time that -/// are legal on a real chain. pub(crate) const TESTNET4_TIMEWARP: [&str; 6] = [ - // The header below the last header of the period. It has no proof of work, and its time is one - // second above the genesis time. concat!( "000000200000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000000", "056f3566ffff001d00000000", ), - // The last header of the period, on the header above. Its time is two weeks above the genesis - // time. concat!( "00000020d63865c0c977eb51da864c86dd3ddf2b907a23e55cc8fd6246d1e118a0603a7b", "0000000000000000000000000000000000000000000000000000000000000000", "04e44766ffff001d59bec392", ), - // A first header of the next period, 600 seconds below the last header. concat!( "0000002002ef6c700351a00f5afa2a1cf4c333bed29d117217d764cbb5b13bc700000000", "0200000000000000000000000000000000000000000000000000000000000000", "ace14766ffff001d540ba5d9", ), - // A first header of the next period, 601 seconds below the last header. concat!( "0000002002ef6c700351a00f5afa2a1cf4c333bed29d117217d764cbb5b13bc700000000", "0100000000000000000000000000000000000000000000000000000000000000", "abe14766ffff001d7ccbb794", ), - // A first header of the next period, one second above the genesis time. concat!( "0000002002ef6c700351a00f5afa2a1cf4c333bed29d117217d764cbb5b13bc700000000", "0000000000000000000000000000000000000000000000000000000000000000", "056f3566ffff001dd9769580", ), - // A header on the 601 seconds one, with the time of the last header. concat!( "00000020efab162c3e3a395a6dd031370d87d1b31ba9120c8d99bc5078d5d87500000000", "0000000000000000000000000000000000000000000000000000000000000000", @@ -180,29 +121,19 @@ pub(crate) const TESTNET4_TIMEWARP: [&str; 6] = [ ), ]; -/// Made-up headers of mainnet at each height where the lowest version rises, which no real chain -/// has: each real header near these heights already has the higher version. The tip is two below -/// each height. It has no proof of work, a version of 4, and a time one second above the genesis -/// time. Each pair is a header on the tip and a header on that header, one second apart. Both have -/// the version one below the bound of the higher height. A test cannot mine at this limit, so a -/// script mined the six once, on 2026-11-07, in about 3 min on 32 threads. Each has the `bits` of -/// the limit and a merkle root of zeros. pub(crate) const MAINNET_VERSION_TIP: &str = concat!( "040000000000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000000", "2aab5f49ffff001d00000000", ); -/// The pairs on `MAINNET_VERSION_TIP`, in the order of their heights. pub(crate) const MAINNET_VERSION_RISE: [[&str; 2]; 3] = [ [ - // Height 227930, version 1. concat!( "01000000311c94dcd9b9616ed0f17d035b4087bebd67463b9bfdd9f1a301759093b52ea7", "0000000000000000000000000000000000000000000000000000000000000000", "2bab5f49ffff001d1d0c43d1", ), - // Height 227931, version 1. concat!( "01000000cfd1b41513dc62aa325fbf3089f90528fd65c037e28ea87a1b15a2f100000000", "0000000000000000000000000000000000000000000000000000000000000000", @@ -210,13 +141,11 @@ pub(crate) const MAINNET_VERSION_RISE: [[&str; 2]; 3] = [ ), ], [ - // Height 363724, version 2. concat!( "02000000311c94dcd9b9616ed0f17d035b4087bebd67463b9bfdd9f1a301759093b52ea7", "0000000000000000000000000000000000000000000000000000000000000000", "2bab5f49ffff001db6a6079a", ), - // Height 363725, version 2. concat!( "020000002666940377a7a458eb0a8affcb6927e7f9b8f93f7f1fb1ae07f698e900000000", "0000000000000000000000000000000000000000000000000000000000000000", @@ -224,13 +153,11 @@ pub(crate) const MAINNET_VERSION_RISE: [[&str; 2]; 3] = [ ), ], [ - // Height 388380, version 3. concat!( "03000000311c94dcd9b9616ed0f17d035b4087bebd67463b9bfdd9f1a301759093b52ea7", "0000000000000000000000000000000000000000000000000000000000000000", "2bab5f49ffff001dfea525cc", ), - // Height 388381, version 3. concat!( "030000007f534b5ac5a6f5c787751a970dc067f080a748e628f8aaddf0e3293c00000000", "0000000000000000000000000000000000000000000000000000000000000000", @@ -239,7 +166,6 @@ pub(crate) const MAINNET_VERSION_RISE: [[&str; 2]; 3] = [ ], ]; -/// The `version`. On loopback, the IPs and ports of both addresses are zero. pub(crate) const VERSION_FRAME: &str = concat!( "fabfb5da76657273696f6e000000000066000000b34372e3", "80110100090c0000000000002358de6a00000000", @@ -248,36 +174,26 @@ pub(crate) const VERSION_FRAME: &str = concat!( "c9f081ae97771971102f5361746f7368693a33312e312e302f0000000001", ); -/// The `wtxidrelay`, which Core sends after its `version`. No payload. pub(crate) const WTXIDRELAY_FRAME: &str = "fabfb5da777478696472656c61790000000000005df6e0e2"; -/// The `sendaddrv2`, which Core sends after its `wtxidrelay`. No payload. pub(crate) const SENDADDRV2_FRAME: &str = "fabfb5da73656e646164647276320000000000005df6e0e2"; -/// The `verack`: a header and no payload. pub(crate) const VERACK_FRAME: &str = "fabfb5da76657261636b000000000000000000005df6e0e2"; -/// The `sendcmpct`, which Core sends after our `verack`: high bandwidth off, version 2. pub(crate) const SENDCMPCT_FRAME: &str = "fabfb5da73656e64636d70637400000009000000e92f5ef8000200000000000000"; -/// The `ping`, which Core sends after its `sendcmpct`. The nonce is random. pub(crate) const PING_FRAME: &str = "fabfb5da70696e670000000000000000080000006c3569e3d84520892932e934"; -/// The `feefilter`, which Core sends after its `ping`. Core was in IBD, so the fee rate is -/// its highest: 9,936,506 sat/kvB. pub(crate) const FEEFILTER_FRAME: &str = "fabfb5da66656566696c746572000000080000000a19f7997a9e970000000000"; -/// The `inv` for block 1, which Core sends when its tip changes. pub(crate) const BLOCK_INV_FRAME: &str = concat!( "fabfb5da696e7600000000000000000025000000dcc9e6bf", "0102000000faf4d233a8d1e92d0b03cd5dcc530307fdca5133639c54520be1a98d48ff6939", ); -/// The `headers` reply to a `getheaders` from genesis: blocks 1 and 2, each with a -/// transaction count of 0. pub(crate) const HEADERS_FRAME: &str = concat!( "fabfb5da686561646572730000000000a30000006ba96776", "02", @@ -291,16 +207,12 @@ pub(crate) const HEADERS_FRAME: &str = concat!( "00", ); -/// The hash of block 1 in `HEADERS_FRAME`, as `getblockhash 1` wrote it. pub(crate) const BLOCK_1_HASH: &str = "41650b9b585fd56a907a5286e7304582ee102c563563a9572bdf898c4f53d96f"; -/// The hash of block 2 in `HEADERS_FRAME`, as `getblockhash 2` wrote it. pub(crate) const BLOCK_2_HASH: &str = "29d4ecbe35de0c35851f0ae8bb5070fbc2273c65b1538591f3deb3179883456a"; -/// The `getheaders` that Core sends to a new peer: version 70016, the genesis hash as the only -/// locator hash, and a `hash_stop` of all zeros. pub(crate) const GETHEADERS_FRAME: &str = concat!( "fabfb5da6765746865616465727300004500000070e012a4", "80110100", @@ -309,21 +221,16 @@ pub(crate) const GETHEADERS_FRAME: &str = concat!( "0000000000000000000000000000000000000000000000000000000000000000", ); -/// The payload of `VERSION_FRAME`. pub(crate) fn version_payload() -> Vec { hex(VERSION_FRAME).split_off(crate::transport::MESSAGE_HEADER_SIZE) } -/// The payload of `HEADERS_FRAME`. pub(crate) fn headers_payload() -> Vec { hex(HEADERS_FRAME).split_off(crate::transport::MESSAGE_HEADER_SIZE) } -/// The `version` of each header that a test makes. It is the version of the blocks in -/// `HEADERS_FRAME`, and it is legal at each height of each network. pub(crate) const HEADER_VERSION: i32 = 0x2000_0000; -// The lowest version only rises with the height, so the bound at the top height is the highest. const _: () = assert!(HEADER_VERSION >= crate::chainparams::Network::Mainnet.version_min(usize::MAX)); const _: () = @@ -333,14 +240,10 @@ const _: () = const _: () = assert!(HEADER_VERSION >= crate::chainparams::Network::Regtest.version_min(usize::MAX)); -/// `count` headers, each on the header before it, the first on the regtest genesis header. Each -/// is the genesis header with its `version`, its `prev`, its `time` and its `nonce` changed. Each -/// time is one second above the header below it, so it is legal. pub(crate) fn headers_on_genesis(count: usize) -> Vec { headers_on(&crate::chainparams::Network::Regtest.genesis(), count) } -/// `headers_on_genesis`, with the first header on `below`. pub(crate) fn headers_on( below: &crate::block::BlockHeader, count: usize, @@ -359,8 +262,6 @@ pub(crate) fn headers_on( .collect() } -/// `headers_on`, with another merkle root in each header. So each header has another hash than the -/// header of `headers_on` at the same height, and a batch of these is a branch on `below`. pub(crate) fn branch_on( below: &crate::block::BlockHeader, count: usize, @@ -381,7 +282,6 @@ pub(crate) fn branch_on( .collect() } -/// A `headers` payload with `headers`, each with a transaction count of 0. pub(crate) fn headers_payload_with(headers: &[crate::block::BlockHeader]) -> Vec { let mut payload = Vec::new(); crate::serialize::write_compact_size(&mut payload, headers.len()); @@ -392,8 +292,6 @@ pub(crate) fn headers_payload_with(headers: &[crate::block::BlockHeader]) -> Vec payload } -/// An `inv` payload with an entry of each type in `types`. Each hash is 0xbb in each byte, so a -/// read of a type from a hash does not give 2, the type of a block. pub(crate) fn inv_payload(types: &[u32]) -> Vec { let mut payload = Vec::new(); crate::serialize::write_compact_size(&mut payload, types.len()); @@ -404,22 +302,16 @@ pub(crate) fn inv_payload(types: &[u32]) -> Vec { payload } -/// The local clock in each test that does not test it. It is the last second of a `u32` time, so -/// the chain takes each time. pub(crate) const CLOCK: u64 = u32::MAX as u64; -/// `headers` as a batch for the chain. It goes through `decode`, so `Headers` has no constructor -/// for the tests. pub(crate) fn headers_batch(headers: &[crate::block::BlockHeader]) -> crate::protocol::Headers { crate::protocol::Headers::decode(&mut headers_payload_with(headers).as_slice()).unwrap() } -/// A header from its 80 bytes in hex. pub(crate) fn header(s: &str) -> crate::block::BlockHeader { crate::block::BlockHeader::decode(&mut hex(s).as_slice()).unwrap() } -/// A hash in hex, in the order a display shows it: the reverse of the wire order. pub(crate) fn hash_from_display_hex(s: &str) -> bitcoin_hashes::sha256d::Hash { let mut bytes: [u8; 32] = hex(s).try_into().unwrap(); bytes.reverse(); diff --git a/src/headerssync.rs b/src/headerssync.rs index 997540e..069b7f3 100644 --- a/src/headerssync.rs +++ b/src/headerssync.rs @@ -1,57 +1,34 @@ -//! The sync of a chain of headers that starts below the minimum work. A peer can make cheap -//! headers for as long as it wants, so elo does not keep the headers of such a chain until the -//! chain shows the work. The first download, `Presync`, checks each header, keeps one commitment, -//! a salted bit of one header, for each period of headers, and drops the headers. When the work is -//! enough, the second download, `Redownload`, gets the same chain again and checks each -//! commitment. It gives a header to the chain only when enough commitments above that header -//! passed, or when the work is enough again. - -/// The most headers for each second of the median time. Each header needs a time above the median -/// time of the 11 headers below it, so at most 6 headers can have the same time. const HEADERS_PER_SECOND_MAX: u64 = 6; -/// The bits of one `u64` word of `Commitments`. const WORD_BITS: usize = 64; -/// The random numbers of one sync. The peer must not know them. With them, it could make a second -/// chain that matches the commitments of the first. It is not `Copy`, so a sync moves it, and no -/// other sync can read it. pub(crate) struct Salt { - /// The keys of the hash that gives each commitment. - pub(crate) keys: [u64; 2], - /// Picks the heights that have a commitment. Each value is legal. - pub(crate) offset: usize, + keys: [u64; 2], + offset: usize, +} + +impl Salt { + pub(crate) const fn new(keys: [u64; 2], offset: usize) -> Salt { + Salt { keys, offset } + } } -/// Writes no field. The `Debug` of a type that holds the salt, such as `net::Connection`, can go -/// into a line of the log, and the salt must stay secret. impl std::fmt::Debug for Salt { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("Salt").finish_non_exhaustive() } } -/// Why a sync refused a batch. Each one ends the sync. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum HeadersSyncError { - /// The `prev` of a header is not the hash of the header below it: the header of our chain - /// that the sync starts on, or the last header that the peer sent in this download. NotContinuous, - /// The `bits` of a header are not a target in the range of the network, or the hash of the - /// header is above that target. ProofOfWork, - /// The `bits` of a header are not a change that the network permits from the `bits` below it. BitsChange, - /// A header is above the highest height that a chain can have at the clock of the sync. TooLong, - /// A batch that is not full ended the chain, and the chain has less work than the minimum. WorkTooLow, - /// A header of the second download does not match the commitment that the first download - /// kept for its height, or the first download kept no more commitments. CommitmentMismatch, } -/// A header that the next header of the peer links to: its hash, its height and its `bits`. #[derive(Clone, Copy, Debug, PartialEq, Eq)] struct Link { hash: bitcoin_hashes::sha256d::Hash, @@ -59,82 +36,49 @@ struct Link { bits: u32, } -/// One commitment, one bit, for each header above `start_height` at a height of `offset` modulo -/// `period`, in the order of the heights. struct Commitments { keys: [u64; 2], period: usize, - /// Below `period`. offset: usize, - /// The height of the header of our chain that the sync starts on. The first height with a - /// commitment is above it, by at most `period`. start_height: usize, - /// Bit `index` is bit `index % WORD_BITS` of word `index / WORD_BITS`. words: Vec, count: usize, } -/// The first download of a sync. It keeps no header, only one commitment for each period of -/// headers. #[derive(Debug)] pub(crate) struct Presync { network: crate::chainparams::Network, - /// The header of our chain that the chain of the peer goes on: our tip, or a fork below it. start: Link, - /// The work of our chain up to `start`. start_work: crate::pow::Work, - /// The work that the chain of the peer must reach. It is above `start_work`. work_min: crate::pow::Work, - /// The highest height that a chain can have at the clock of the sync. height_max: usize, commitments: Commitments, - /// The last header that the peer sent, or `start`. last: Link, - /// `start_work` plus the work of each header that the peer sent. work: crate::pow::Work, } -/// What a batch of the first download gave. #[derive(Debug)] pub(crate) enum PresyncStep { - /// The batch was full and the work is below the minimum. The peer sends more on the last - /// header. More(Presync), - /// The work reached the minimum. The peer sends the chain again, on the start of the sync. Redownload(Redownload), } -/// The second download of a sync. It holds the headers that wait for more commitments above -/// them. #[derive(Debug)] pub(crate) struct Redownload { network: crate::chainparams::Network, work_min: crate::pow::Work, commitments: Commitments, - /// The headers that this download did not release yet, in order. The first is on the start - /// of the sync, or on the last header that it released. buffer: std::collections::VecDeque, - /// The last header of `buffer`, or the last header that this download released, or the start - /// of the sync. last: Link, - /// The work of our chain up to the start of the sync, plus the work of each header of this - /// download. work: crate::pow::Work, } -/// What a batch of the second download gave. It releases each header in it, in order, for the -/// chain: on the start of the sync, or on the headers that it released before. #[derive(Debug)] pub(crate) enum RedownloadStep { - /// The batch was full and the work is below the minimum. The peer sends more on the last - /// header. The box keeps the step small, because `Done` has only the headers. More(Box, Vec), - /// The work reached the minimum, so the chain gets each header that is left. The sync ends. Done(Vec), } -/// Writes only the fields that are not secret. The keys and the offset come from the salt, and the -/// commitments come from the keys. impl std::fmt::Debug for Commitments { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("Commitments") @@ -158,31 +102,23 @@ impl Commitments { } } - /// A header at `height` has a commitment. fn is_at(&self, height: usize) -> bool { height % self.period == self.offset } - /// The index of the commitment at `height`, which is above the start and has a commitment. - /// The heights with a commitment are `period` apart, and the first is at most `period` above - /// the start, so the index is the count of whole periods from the height above the start. fn index(&self, height: usize) -> usize { assert!(height > self.start_height); assert!(self.is_at(height)); (height - self.start_height - 1) / self.period } - /// The commitment of the header with `hash`: its salted hash is even. fn commitment(&self, hash: bitcoin_hashes::sha256d::Hash) -> bool { let [key_0, key_1] = self.keys; bitcoin_hashes::siphash24::Hash::hash_to_u64_with_keys(key_0, key_1, hash.as_byte_array()) .is_multiple_of(2) } - /// Keeps the commitment of the header at `height` with `hash`, after the others. fn push(&mut self, height: usize, hash: bitcoin_hashes::sha256d::Hash) { - // The heights come in order and none is skipped. This also bounds the memory: one - // commitment in each period above the start. assert_eq!(self.index(height), self.count); let bit_index = self.count % WORD_BITS; if bit_index == 0 { @@ -191,7 +127,6 @@ impl Commitments { if self.commitment(hash) && let [.., word] = self.words.as_mut_slice() { - // The bits go in order, so this bit and each bit above it are still clear. assert_eq!(*word >> bit_index, 0); *word |= 1 << bit_index; } @@ -199,10 +134,7 @@ impl Commitments { assert_eq!(self.words.len(), self.count.div_ceil(WORD_BITS)); } - /// The commitment at `height`, if the first download kept one there. fn get(&self, height: usize) -> Option { - // The pair of the assert in `push`. Without it, a word that is not there would read as - // "no more commitments", and the peer would get the error. assert_eq!(self.words.len(), self.count.div_ceil(WORD_BITS)); let index = self.index(height); if index < self.count { @@ -215,12 +147,6 @@ impl Commitments { } impl Presync { - /// The first download of the chain of the peer, on `start`, a header of our chain, until the - /// chain of the peer has `work_min`. The work of our chain up to `start` must be below - /// `work_min`. `clock` is the local clock, in seconds since the Unix epoch. A chain gets at - /// most `HEADERS_PER_SECOND_MAX` headers in each second from the median time of `start`, until - /// a header can be `TIME_AHEAD_SECONDS_MAX` after the clock. So the clock bounds the height, - /// and the height bounds the commitments. pub(crate) fn new( start: crate::chain::SyncStart, work_min: crate::pow::Work, @@ -234,9 +160,6 @@ impl Presync { height: start.height(), bits: start.bits(), }; - // A clock far after each real time saturates, and so does the height, so the bound - // refuses no chain. A clock below the median time gives zero seconds, and then the bound - // refuses each header. let seconds = clock .saturating_add(crate::chain::TIME_AHEAD_SECONDS_MAX) .saturating_sub(u64::from(start.median_time_past())); @@ -254,16 +177,10 @@ impl Presync { } } - /// The hash of the last header that the peer sent, or of the start of the sync. The next batch - /// goes on it. pub(crate) fn last_hash(&self) -> bitcoin_hashes::sha256d::Hash { self.last.hash } - /// Checks each of `headers`, in order, on the last header. For one header, its `prev` is - /// checked first, then its proof of work, then its `bits`, then its height. When the work - /// reaches the minimum, the next download starts after the batch. Else a batch that is not - /// full fails, an empty one too. pub(crate) fn receive( mut self, headers: crate::protocol::Headers, @@ -274,7 +191,6 @@ impl Presync { if link.height > self.height_max { return Err(HeadersSyncError::TooLong); } - // With the height bound above, `push` bounds the memory of the commitments. if self.commitments.is_at(link.height) { self.commitments.push(link.height, link.hash); } @@ -292,7 +208,6 @@ impl Presync { } impl Redownload { - /// The second download, on the start of the first, with its commitments. fn new(presync: Presync) -> Redownload { assert!(presync.work >= presync.work_min); Redownload { @@ -305,23 +220,10 @@ impl Redownload { } } - /// The hash of the last header of this download, or of the start of the sync. The next batch - /// goes on it. pub(crate) fn last_hash(&self) -> bitcoin_hashes::sha256d::Hash { self.last.hash } - /// Checks each of `headers`, in order, on the last header, as the first download did. Each - /// header at the height of a commitment must match it, until the work reaches the minimum. - /// From there the chain shows the work, so no header needs a commitment, and the peer can also - /// have new headers above the first chain. Then the chain gets each header and the sync ends. - /// Else the chain gets only the headers with more than `redownload_buffer_size` headers above - /// them, and a batch that is not full fails, an empty one too. - /// - /// This download has no height bound of its own. Below the minimum, the first height with a - /// commitment above the last commitment of the first download fails, because none is kept for - /// it. So the chain ends at most one period above that commitment, which is at most at - /// `height_max`. pub(crate) fn receive( mut self, headers: crate::protocol::Headers, @@ -330,21 +232,16 @@ impl Redownload { for header in headers.into_vec() { let (link, work) = checked(self.network, self.last, &header)?; self.work = self.work.saturating_add(work); - if self.work < self.work_min { - // The chain does not show the work yet, so it must be the chain of the first - // download. - if self.commitments.is_at(link.height) { - let kept = self.commitments.get(link.height); - if kept != Some(self.commitments.commitment(link.hash)) { - return Err(HeadersSyncError::CommitmentMismatch); - } + let first_download = self.work < self.work_min; + if first_download && self.commitments.is_at(link.height) { + let kept = self.commitments.get(link.height); + if kept != Some(self.commitments.commitment(link.hash)) { + return Err(HeadersSyncError::CommitmentMismatch); } } self.buffer.push_back(header); self.last = link; } - // `last` is the last header of `buffer`, with the height and the `bits` that the buffer - // does not keep. if let Some(buffer_last) = self.buffer.back() { assert_eq!(buffer_last.hash(), self.last.hash); } @@ -356,7 +253,6 @@ impl Redownload { .len() .saturating_sub(self.network.redownload_buffer_size()); let released = self.buffer.drain(..released_count).collect(); - // A batch has at most 2,000 headers, so this bounds the buffer between two batches. assert!(self.buffer.len() <= self.network.redownload_buffer_size()); Ok(RedownloadStep::More(Box::new(self), released)) } else { @@ -365,8 +261,6 @@ impl Redownload { } } -/// Checks `header` on `below`: its `prev`, then its proof of work, then its `bits`. Returns the -/// header as the link of the next one, and its work. fn checked( network: crate::chainparams::Network, below: Link, @@ -413,20 +307,10 @@ impl std::error::Error for HeadersSyncError {} #[cfg(test)] mod tests { - /// The `bits` of the regtest limit, which each header of a test has unless it says another. const LIMIT_BITS: u32 = 0x207f_ffff; - /// The offset modulo the regtest period of 275 is 15, so the first download keeps a commitment - /// at the heights 15, 290, 565, 840, 1115, 1390, 1665, 1940, 2215 and on. A person wrote - /// these. The offset is above the period, so the sync must take it modulo the period. It is - /// not `usize::MAX`, because that modulo 275 is 15 only where `usize` has 64 bits. - const SALT: super::Salt = super::Salt { - keys: [1, 2], - offset: 275 * 1_000 + 15, - }; + const SALT: super::Salt = super::Salt::new([1, 2], 275 * 1_000 + 15); - /// `count` regtest headers with `bits`, each on the header before it, the first on `below`. - /// `seed` is each byte of the merkle root, so two seeds give two chains. fn mined_on( below: &crate::block::BlockHeader, count: usize, @@ -455,13 +339,11 @@ mod tests { headers } - /// `count` regtest headers at the limit on genesis, with `seed`. fn chain_on_genesis(count: usize, seed: u8) -> Vec { let genesis = crate::chainparams::Network::Regtest.genesis(); mined_on(&genesis, count, LIMIT_BITS, seed) } - /// The work of regtest genesis and `headers` on it. fn work_on_genesis(headers: &[crate::block::BlockHeader]) -> crate::pow::Work { let genesis = crate::chainparams::Network::Regtest.genesis(); std::iter::once(&genesis) @@ -472,7 +354,6 @@ mod tests { .unwrap() } - /// A first download on regtest genesis that ends at `work_min`. fn presync(work_min: crate::pow::Work) -> super::Presync { let chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); super::Presync::new( @@ -483,7 +364,6 @@ mod tests { ) } - /// `presync` after it took each batch of `batches` and asked for more. fn more( mut presync: super::Presync, batches: &[&[crate::block::BlockHeader]], @@ -498,7 +378,6 @@ mod tests { presync } - /// The second download after the first took `batches`, the last of which reaches the minimum. fn redownload( work_min: crate::pow::Work, batches: &[&[crate::block::BlockHeader]], @@ -532,7 +411,6 @@ mod tests { let headers = chain_on_genesis(4_001, 0); let work_min = work_on_genesis(&headers).saturating_add(work_on_genesis(&[])); - // The second batch is on the last header of the first. let after_two_batches = more( presync(work_min), &[&headers[..2_000], &headers[2_000..4_000]], @@ -555,7 +433,6 @@ mod tests { let headers = chain_on_genesis(2_000, 0); let work_at = |count| work_on_genesis(&headers[..count]); - // A full batch exactly at the minimum, and one header below it. assert!(matches!( presync(work_at(2_000)).receive(batch(&headers)), Ok(super::PresyncStep::Redownload(_)) @@ -564,7 +441,6 @@ mod tests { presync(work_at(2_000).saturating_add(work_at(0))).receive(batch(&headers)), Ok(super::PresyncStep::More(_)) )); - // A batch that is not full still reaches the minimum. assert!(matches!( presync(work_at(1_000)).receive(batch(&headers[..1_000])), Ok(super::PresyncStep::Redownload(_)) @@ -603,7 +479,6 @@ mod tests { fn presync_refuses_a_header_without_proof_of_work() { let mut headers = chain_on_genesis(3, 0); let work_min = work_on_genesis(&headers).saturating_add(work_on_genesis(&[])); - // The first nonce after the mined one that gives a hash above the target. headers[2] = (headers[2].nonce + 1..) .map(|nonce| crate::block::BlockHeader { nonce, @@ -620,8 +495,6 @@ mod tests { ); } - /// On mainnet, a header inside a period keeps the `bits` of the header below it. Block 1 is - /// on genesis, so it keeps the `bits` of the tip of our chain. #[test] fn presync_reads_the_bits_of_the_tip_of_our_chain() { let block_1 = crate::fixtures::header(crate::fixtures::MAINNET_BLOCK_1); @@ -632,7 +505,6 @@ mod tests { ) ); let chain = crate::chain::Chain::new(crate::chainparams::Network::Mainnet); - // Block 1 has the work of genesis, so the minimum is one header above the batch. let genesis_work = chain.tip().work(); let work_min = genesis_work .saturating_add(genesis_work) @@ -644,16 +516,12 @@ mod tests { SALT, ); - // The batch is not full, so a header that passes ends below the minimum. assert_eq!( presync.receive(batch(&[block_1])).unwrap_err(), super::HeadersSyncError::WorkTooLow ); } - /// Our chain has 100 headers, each one second above the one below it, so its median time is - /// the genesis time plus 95. A clock 100 s above that, less the 2 h that a time may be ahead - /// of the clock, permits 600 headers above the tip, up to height 700. A person wrote these. #[test] fn presync_refuses_a_chain_higher_than_the_clock_permits() { let headers = chain_on_genesis(701, 0); @@ -667,7 +535,6 @@ mod tests { let presync_at = |clock| super::Presync::new(chain.sync_start_on_tip(), work_min, clock, SALT); - // The batch is not full, so a chain that is not too high ends below the minimum. assert_eq!( presync_at(clock) .receive(batch(&headers[100..700])) @@ -680,7 +547,6 @@ mod tests { .unwrap_err(), super::HeadersSyncError::TooLong ); - // A clock more than 2 h below the median time permits no header. assert_eq!( presync_at(0) .receive(batch(&headers[100..101])) @@ -689,9 +555,6 @@ mod tests { ); } - /// The chain reaches the minimum at height 9,500, so the first download takes 5 batches. The - /// second download holds 7,017 headers, so the fourth batch gives 983 headers to the chain. - /// The fifth reaches the minimum, so it gives the rest, also the 500 headers above it. #[test] fn redownload_gives_each_header_once_enough_headers_are_above_it() { let headers = chain_on_genesis(10_000, 0); @@ -717,8 +580,6 @@ mod tests { assert_eq!(released, headers); } - /// The second download, on a chain that reaches the minimum at height 4,000, after it took - /// the first full batch of `headers`. fn redownload_after_one_batch(headers: &[crate::block::BlockHeader]) -> super::Redownload { let redownload = redownload( work_on_genesis(headers), @@ -748,8 +609,6 @@ mod tests { let at_start = || redownload(work_min, &[&headers[..2_000], &headers[2_000..]]); let cases: [(&str, super::Redownload, &[crate::block::BlockHeader], _); 5] = [ - // The second download starts again on the tip of our chain, not on the last header - // of the first download. ( "on the last header of the first download", at_start(), @@ -788,15 +647,12 @@ mod tests { "{name}" ); } - // The same chain passes. assert!(matches!( redownload_after_one_batch(&headers).receive(batch(&headers[2_000..])), Ok(super::RedownloadStep::Done(_)) )); } - /// The other chain has another merkle root from height 1, so at some height with a commitment - /// it has another one. #[test] fn redownload_refuses_another_chain() { let headers = chain_on_genesis(2_000, 0); @@ -809,10 +665,6 @@ mod tests { ); } - /// The chain reaches the minimum at height 1,115, which has a commitment. Each second chain is - /// the first one up to 1,114, then another header at 1,115 and more on it. About half of the - /// headers at 1,115 have another commitment, so 8 chains read a commitment there with odds of - /// 255 in 256. #[test] fn redownload_reads_no_commitment_from_the_header_that_reaches_the_minimum() { let headers = chain_on_genesis(2_000, 0); @@ -832,10 +684,6 @@ mod tests { } } - /// The first chain has harder headers above height 1,940, its last commitment. Each has a work - /// of 15, where a header at the limit has 2, so the chain reaches the minimum at height 2,000. - /// The second chain is the first up to 1,940, then headers at the limit. So at height 2,215 it - /// is still below the minimum, and the first download kept no commitment for that height. #[test] fn redownload_refuses_a_chain_after_the_last_commitment() { let bits_hard = 0x2010_0000; @@ -845,8 +693,6 @@ mod tests { let first = [first.as_slice(), &first_hard].concat(); let second = [&first[..1_940], &second_easy].concat(); let work_min = work_on_genesis(&first); - // The second chain at 2,215 has 2 + 2,215 * 2 of work, and the first chain has - // 2 + 1,940 * 2 + 60 * 15 at 2,000. assert!(work_on_genesis(&second) < work_min); let after_one_batch = || { @@ -857,7 +703,6 @@ mod tests { *redownload }; - // Each header up to 2,214 passes, so the batch ends below the minimum. assert_eq!( after_one_batch() .receive(batch(&second[2_000..2_214])) @@ -872,10 +717,6 @@ mod tests { ); } - /// Our chain ends at height 15, which has a commitment. So the first commitment of the sync is - /// one whole period above the tip, at 290, and the first download keeps 7, up to 1,940. The - /// chain of the peer reaches the minimum at 2,015, so each download takes one batch. A person - /// wrote these. #[test] fn sync_on_a_tip_with_a_commitment_keeps_the_first_commitment_a_period_above() { let headers = chain_on_genesis(2_015, 0); diff --git a/src/lib.rs b/src/lib.rs index a6ce091..976e6c8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,5 +1,3 @@ -//! elo: a Bitcoin node daemon. - #![forbid(unsafe_code)] mod block; @@ -17,9 +15,6 @@ mod transport; #[cfg(test)] mod fixtures; -/// The entry points of the fuzz targets in `fuzz/`. Only a build with `--cfg fuzzing` has this -/// module, so a normal build has no more `pub` items. The code of each entry point is in a `fuzz` -/// child of the module that it checks, as a test is, so it sees the private items of that module. #[cfg(fuzzing)] pub mod fuzz { pub use crate::net::fuzz::frame; diff --git a/src/logging.rs b/src/logging.rs index 8ac1bd6..43492fb 100644 --- a/src/logging.rs +++ b/src/logging.rs @@ -1,80 +1,51 @@ -//! The log: one line for each event, in logfmt. Each line is `level= event=`, then -//! the fields of the event, each as `=`. A value that is empty, or that has a space, a -//! `=`, a `"` or a control character, is in quotes, with the escapes `\"`, `\\`, `\n`, `\r`, `\t` -//! and `\u00XX`. In a value with no quotes, a `\` is only a `\`. The line has no time, because the -//! collector of the log adds one. - use std::fmt::Write; -/// The most bytes of a value before its escapes. A longer value is cut, and ends with `...`. So -/// a peer that sends a long string cannot make a long line. The longest destination of the -/// command line fits, so the `destination` of an `end` line is never cut. const VALUE_LENGTH_MAX: usize = 260; const _: () = assert!(crate::net::DESTINATION_LENGTH_MAX <= VALUE_LENGTH_MAX); -/// What `...` adds to a value that is cut. const CUT_MARK: &str = "..."; -/// The most fields of a line, `level` and `event` too. A `version` line has the most. const FIELDS_COUNT_MAX: usize = 8; -/// The most bytes of a key. const KEY_LENGTH_MAX: usize = 16; -/// The most bytes that one escape writes for one byte of a value: `\u0001`. const ESCAPE_LENGTH_MAX: usize = 6; -/// The most bytes of a field: a space, the key, `=`, two quotes, the escaped value and the `...` -/// of a cut. The `...` needs no escape. const FIELD_LENGTH_MAX: usize = 1 + KEY_LENGTH_MAX + 1 + 2 + ESCAPE_LENGTH_MAX * VALUE_LENGTH_MAX + CUT_MARK.len(); -/// The most bytes of a line. The first field has no space before it, and the line has a newline -/// after it. const LINE_LENGTH_MAX: usize = FIELDS_COUNT_MAX * FIELD_LENGTH_MAX; -// Docker cuts a line of more than 16 KiB into parts, and a collector reads each part as a line. const _: () = assert!(LINE_LENGTH_MAX <= 16 * 1024); -/// An event that elo logs. The name of each event and the key of each field are an interface: -/// dashboards and alerts match on them, so a rename breaks them. `Event::name` and `Event::line` -/// are the one list of them. Only the fields here go into a line, so no secret, such as the salt -/// of a peer, can. A `reason` or a `signal` is any `Display`, so its text is what that `Display` -/// writes: a type that holds a secret has no `Display`, as the salt has none, and its `Debug` -/// writes no secret, so a `{:?}` in a `reason` cannot write it either. #[derive(Clone, Copy)] pub enum Event<'a> { - /// The handshake with `peer` is done, and it sent `version`. Version { peer: std::net::SocketAddr, version: &'a crate::protocol::Version, }, - /// The sync with `peer` ended, with our chain at `tip`. Tip { peer: std::net::SocketAddr, tip: &'a crate::chain::Tip, }, - /// The connection to `destination` ended for `reason`, and elo dials again after `wait`. - /// `destination` is what the dial looked up or dialed: the IP address or the name of the - /// command line, or a seed of the network. It has its own key, so `peer` is always the address - /// of a connection. End { destination: &'a crate::net::Destination, reason: &'a dyn std::fmt::Display, wait: std::time::Duration, }, - /// A fault of this host ends elo, with exit code 1. - Exit { reason: &'a dyn std::fmt::Display }, - /// `signal` stops elo, with exit code 0. - Stop { signal: &'a dyn std::fmt::Display }, - /// A bug ends elo, with exit code 101. `reason` is the place in the code and the message. - Panic { reason: &'a dyn std::fmt::Display }, + Exit { + reason: &'a dyn std::fmt::Display, + }, + Stop { + signal: &'a dyn std::fmt::Display, + }, + Panic { + reason: &'a dyn std::fmt::Display, + }, } impl Event<'_> { - /// Writes the line of the event, with its newline, to `out` in one write, and flushes `out`. - /// stdout is not always line buffered. pub fn write(&self, out: &mut impl std::io::Write) -> Result<(), std::io::Error> { out.write_all(self.line().as_bytes())?; out.flush() @@ -136,11 +107,8 @@ impl Event<'_> { #[derive(Clone, Copy)] enum Level { - /// What elo does when all goes well. Info, - /// A fault that elo gets past, such as a peer that drops. Warn, - /// A fault or a bug that ends elo. Error, } @@ -154,7 +122,6 @@ impl Level { } } -/// A line that `field` writes to, one field at a time. #[derive(Default)] struct Line { text: String, @@ -182,8 +149,6 @@ impl Line { self.text.push('='); let mut capped = Capped::default(); - // `Capped` never fails, so only a `Display` that fails by itself can fail here. That is a - // bug of the `Display`: `std` asks a `Display` to fail only when its writer fails. let written = write!(capped, "{value}"); assert!(written.is_ok(), "{key}: the value failed to write"); let Capped { @@ -206,9 +171,7 @@ impl Line { '\n' => self.text.push_str("\\n"), '\r' => self.text.push_str("\\r"), '\t' => self.text.push_str("\\t"), - // Each control character is below U+00A0. character if character.is_control() => { - // A write to a `String` never fails. let written = write!(self.text, "\\u{:04x}", u32::from(character)); assert!(written.is_ok()); } @@ -219,11 +182,7 @@ impl Line { } fn end(mut self) -> String { - // Each line has its level and its event. assert!(self.fields_count >= 2, "{}", self.fields_count); - // The escapes keep each newline out of a value, so a value from a peer cannot start a - // line of its own. The one newline is the end of the line. `Debug` escapes the text of - // the panic too, so a bug of the escapes cannot split a line of stderr either. assert!(!self.text.contains('\n'), "{:?}", self.text); self.text.push('\n'); assert!(self.text.len() <= LINE_LENGTH_MAX, "{}", self.text.len()); @@ -231,8 +190,6 @@ impl Line { } } -/// Whether `character` puts its value in quotes. Each control character has an escape in quotes, -/// and so do `"` and `\`. A `\` alone does not put a value in quotes. fn quotes(character: char) -> bool { match character { ' ' | '=' | '"' => true, @@ -240,8 +197,6 @@ fn quotes(character: char) -> bool { } } -/// The text of a value, up to `VALUE_LENGTH_MAX` bytes. At the first character that does not fit, -/// `cut` is set and the rest is dropped, so the text ends on a whole character. #[derive(Default)] struct Capped { text: String, @@ -277,7 +232,6 @@ mod tests { String::from_utf8(out).unwrap() } - /// The value of `text` in an `exit` line. fn value(text: &str) -> String { let line = line(super::Event::Exit { reason: &text }); let value = line @@ -373,12 +327,9 @@ mod tests { let long = "a".repeat(super::VALUE_LENGTH_MAX + 1); assert_eq!(value(&long), format!("{fits}...")); - // The last `é` needs 2 bytes, and only 1 is left. let first = "a".repeat(super::VALUE_LENGTH_MAX - 1); assert_eq!(value(&format!("{first}é")), format!("{first}...")); - // A `Display` that writes in parts: after the cut, a part that fits is dropped too, so the - // value is only the start of the text. let parts = line(super::Event::Exit { reason: &format_args!("{first}{}{}", 'é', 'b'), }); @@ -387,7 +338,6 @@ mod tests { #[test] fn the_longest_line_is_the_maximum() { - // Each byte is a control character, which needs the longest escape, and the value is cut. let value = "\u{1}".repeat(super::VALUE_LENGTH_MAX + 1); let mut line = super::Line::default(); for _ in 0..super::FIELDS_COUNT_MAX { diff --git a/src/main.rs b/src/main.rs index 6ce74a8..1eb53e7 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,27 +1,11 @@ -//! `elo [[:port]]`: dials one peer, does the handshake, and logs the peer's -//! `version`. The host is an IP address or a name. With no host, each dial takes a seed of the -//! network, at random. Before each dial, elo looks up the name or the seed, and dials its addresses -//! in a random order until one takes the connect. Then it syncs the header chain from the peer and -//! logs the tip. It asks the peer to announce each new header, takes it on the tip, and logs the -//! tip when it moves. It pings the peer and answers its `ping` messages until the connection ends. -//! Then it waits and dials again. The chain stays in memory, so the next connection syncs from its -//! tip. SIGTERM and SIGINT stop it at any of these steps. Each step writes a line of -//! `elo::logging` to stdout. - const USAGE: &str = "usage: elo [[:port]] regtest has no seeds, so it needs a peer"; -/// The exit code for bad usage. A stop by a signal exits with 0, and a panic with 101. Every -/// other exit is 1, because only a fault of this host ends elo. const EXIT_USAGE: u8 = 2; -/// How long elo waits after a connection ends before it dials again. So a peer that is down, or -/// that ends each connection at once, gets at most one try in each wait. const RECONNECT_WAIT: std::time::Duration = std::time::Duration::from_secs(5); fn main() -> std::process::ExitCode { - // First of all, so each panic writes a `panic` line, and not the text of the default hook, - // which is not a line of the log. A panic in this hook aborts elo. std::panic::set_hook(Box::new(|info| { let event = elo::logging::Event::Panic { reason: info }; if log(&event).is_err() { @@ -35,7 +19,6 @@ fn main() -> std::process::ExitCode { return std::process::ExitCode::from(EXIT_USAGE); }; - // The I/O driver also gives the signals. let runtime = match tokio::runtime::Builder::new_current_thread() .enable_io() .enable_time() @@ -45,46 +28,29 @@ fn main() -> std::process::ExitCode { Err(error) => return exit(&format_args!("runtime: {error}")), }; let code = runtime.block_on(run(network, source)); - // A lookup runs on a blocking thread of the runtime, and a stop or a lookup timeout does not - // end it. The drop of the runtime would wait for that thread, so the runtime does not wait. runtime.shutdown_background(); code } -/// Dials a destination of `source` again after each end that retries, until a signal or an end -/// that exits. async fn run( network: elo::chainparams::Network, source: elo::net::Source, ) -> std::process::ExitCode { - // Before the first dial, so a signal from here on stops elo. As PID 1 in a container, a - // process with no handler never sees a SIGTERM: the kernel drops it, and the stop ends in - // SIGKILL after its timeout. let mut signals = match Signals::new() { Ok(signals) => signals, Err(error) => return exit(&format_args!("signals: {error}")), }; - // One chain for each connection, so a connection ends with the headers of the last one, and - // a sync gets only the headers after its tip. let mut chain = elo::chain::Chain::new(network); - // The loop has no count bound, because elo keeps its one peer for as long as it runs. Only - // a signal or an end that a new connection cannot fix gets out. loop { let destination = source.destination(); - // The drop of the connection closes its socket. elo keeps nothing on disk, so the stop - // has nothing else to finish. let end = match signals.unless(dial(&destination, &mut chain)).await { Ok(Ok(end)) => end, Ok(Err(error)) => return exit_stdout(error), Err(signal) => return stop(signal), }; - // The event says if elo dials again, so a reader of the log does not need the list of - // ends that exit. if !end.retries() { return exit(&end); } - // The destination of the dial, and not the address of the connection: the next dial looks - // up a name again, and a seed shows which seed gave the peer. let logged = log(&elo::logging::Event::End { destination: &destination, reason: &end, @@ -99,16 +65,11 @@ async fn run( } } -/// Logs the `signal` that stops elo, and gives the exit code of a stop: 0. A failed write does -/// not change the exit code, because the signal asked for the stop. fn stop(signal: Signal) -> std::process::ExitCode { let _ = log(&elo::logging::Event::Stop { signal: &signal }); std::process::ExitCode::SUCCESS } -/// Logs the fault of this host that ends elo, and gives the exit code of a fault: 1. When stdout -/// fails, the line goes to stderr, so a fault of stdout has a line too. Nothing is left to tell of -/// a fault of stderr. fn exit(reason: &dyn std::fmt::Display) -> std::process::ExitCode { let event = elo::logging::Event::Exit { reason }; if log(&event).is_err() { @@ -117,9 +78,6 @@ fn exit(reason: &dyn std::fmt::Display) -> std::process::ExitCode { std::process::ExitCode::FAILURE } -/// Logs a failed write to stdout, which ends elo, to stderr only, and gives the exit code of a -/// fault: 1. The write that failed can leave part of its line on stdout, and a second write there -/// would join the `exit` line to that part. fn exit_stdout(error: std::io::Error) -> std::process::ExitCode { let reason = format_args!("stdout: {error}"); let event = elo::logging::Event::Exit { reason: &reason }; @@ -127,18 +85,13 @@ fn exit_stdout(error: std::io::Error) -> std::process::ExitCode { std::process::ExitCode::FAILURE } -/// Writes the line of `event` to stdout. `println!` panics when stdout fails, for example on a -/// full disk or a closed pipe. fn log(event: &elo::logging::Event<'_>) -> Result<(), std::io::Error> { event.write(&mut std::io::stdout().lock()) } -/// A signal that stops elo. #[derive(Clone, Copy, Debug)] enum Signal { - /// SIGTERM, from a container stop or a service manager. Terminate, - /// SIGINT, from Ctrl-C. Interrupt, } @@ -151,8 +104,6 @@ impl std::fmt::Display for Signal { } } -/// The handlers of the signals that stop elo. From their creation, these signals no longer end -/// the process by their default action, and each one waits here until `unless` takes it. struct Signals { terminate: tokio::signal::unix::Signal, interrupt: tokio::signal::unix::Signal, @@ -166,9 +117,6 @@ impl Signals { }) } - /// The output of `work`, or the first signal if it comes before. A signal wins over an - /// output that is ready at the same time. A signal that came before this call is taken - /// first. async fn unless(&mut self, work: impl Future) -> Result { let mut work = std::pin::pin!(work); std::future::poll_fn(|context| { @@ -180,15 +128,12 @@ impl Signals { .await } - /// The next signal. When none came, each handler holds the waker of `context`. fn poll_next(&mut self, context: &mut std::task::Context<'_>) -> std::task::Poll { for (handler, signal) in [ (&mut self.terminate, Signal::Terminate), (&mut self.interrupt, Signal::Interrupt), ] { if let std::task::Poll::Ready(received) = handler.poll_recv(context) { - // `None` is a runtime with no signal driver, which cannot be while this runs in - // it. As a signal, it would come again at each poll: a stop that no one sent. assert!(received.is_some(), "{signal}: the signal driver ended"); return std::task::Poll::Ready(signal); } @@ -197,20 +142,13 @@ impl Signals { } } -/// How one connection ended. A failed write to stdout is no end of a connection: it ends elo. #[derive(Debug)] enum End { - /// The lookup, the connect or the handshake failed. Handshake(elo::net::HandshakeError), - /// The connection ended in the sync or after it. Run(elo::net::RunError), } impl End { - /// Whether elo dials the peer again. Each end that the peer or the network causes retries, - /// also a peer that sent bytes that elo refuses: the user named that peer. A fault of this - /// host that a new connection cannot fix does not. The match names each variant, so - /// a new error does not compile until it has a side. fn retries(&self) -> bool { match self { End::Handshake(elo::net::HandshakeError::Salt(_)) => false, @@ -250,9 +188,6 @@ impl std::fmt::Display for End { } } -/// Dials `destination`, does the handshake and logs the `version` of the peer. Then syncs -/// `chain` and logs its tip, and logs it again each time an announcement of the peer moves it, -/// until the connection ends. `Err` is a failed write to stdout. async fn dial( destination: &elo::net::Destination, chain: &mut elo::chain::Chain, @@ -271,8 +206,6 @@ async fn dial( Ok(sync) => sync, Err(error) => return Ok(End::Run(error)), }; - // The loop has no count bound, because the peer announces headers for as long as it is - // connected. Only the end of the connection or a fault of stdout gets out. loop { log(&elo::logging::Event::Tip { peer: address, @@ -285,8 +218,6 @@ async fn dial( } } -/// The args after the program name. `None` is bad usage. With no peer, the source is the seeds -/// of the network, so a network with no seeds needs a peer. fn parse(args: &[std::ffi::OsString]) -> Option<(elo::chainparams::Network, elo::net::Source)> { let (network, peer) = match args { [network] => (network, None), @@ -307,16 +238,10 @@ fn parse(args: &[std::ffi::OsString]) -> Option<(elo::chainparams::Network, elo: Some((network, source)) } -/// `peer` as the destination of each dial, or `None` if it is no IP address and no name. -/// -/// An IPv6 address needs brackets even without a port, because `::1:8333` is an IPv6 address -/// and not `::1` with a port. fn destination(peer: &str, network: elo::chainparams::Network) -> Option { let destination = if let Some(address) = address(peer, network.default_port()) { - // Port 0, `0.0.0.0`, `[::]` and `[::ffff:0.0.0.0]` name no peer. elo::net::Destination::Address(elo::net::PeerAddress::new(address)?) } else { - // The parse of a `NonZeroU16` refuses port 0. let (host, port) = match peer.split_once(':') { Some((host, port)) => (host, port.parse().ok()?), None => (peer, network.default_port()), @@ -329,7 +254,6 @@ fn destination(peer: &str, network: elo::chainparams::Network) -> Option Option { if let Ok(address) = peer.parse() { return Some(address); @@ -348,8 +272,6 @@ mod tests { super::parse(&args) } - // The L3 tests also hold a closed connection, which retries, and a stdout fault, which - // exits. A stdout fault is no `End`, so it has no row here. #[test] fn a_fault_of_this_host_ends_elo_and_a_failed_connect_or_lookup_retries() { for (end, retries) in [ @@ -380,8 +302,6 @@ mod tests { } } - // An L3 test cannot make the runtime, the signal handlers or `/dev/urandom` fail, so this - // test holds the exit code of a fault of this host. It writes an `exit` line to stdout. #[test] fn a_fault_of_this_host_exits_with_1() { let code = super::exit(&"a test of the exit code"); diff --git a/src/net.rs b/src/net.rs index 3608755..ad92039 100644 --- a/src/net.rs +++ b/src/net.rs @@ -1,57 +1,33 @@ -//! The driver: it dials one peer and runs the handshake on the socket. Then it syncs our header -//! chain from the peer, pings the peer, and answers the messages after the handshake. The chain -//! is not part of the connection, so it outlives each connection. - use crate::serialize::Encode; use std::hash::{BuildHasher, Hasher}; use std::io::Read; use tokio::io::{AsyncReadExt, AsyncWriteExt}; -/// How long the TCP connect may take. const CONNECT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5); -/// How long the handshake may take, from the connect to their `verack`. const HANDSHAKE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(60); -/// How long each write after the handshake may take, because a write to a peer that does not -/// read can block forever. The ping timeout covers each read. const SEND_TIMEOUT: std::time::Duration = std::time::Duration::from_mins(20); -/// How long the lookup of a name may take. The resolver of the OS tries each name server again -/// after its own timeout, by default 5 s, two times for each of at most 3 servers. const LOOKUP_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); -/// The most addresses of a name that one dial tries. Each try takes at most `CONNECT_TIMEOUT`, so -/// this bounds the time of a dial. const ADDRESSES_COUNT_MAX: usize = 256; -/// The most addresses of a seed that one dial tries. A seed has many nodes, and the next dial asks -/// a seed again, so a seed whose answers are down costs at most this many tries. const SEED_ADDRESSES_COUNT_MAX: usize = 32; -/// The most bytes of a name, with no `.` at the end. const NAME_LENGTH_MAX: usize = 253; -/// The most bytes of one label of a name. const LABEL_LENGTH_MAX: usize = 63; -/// The most bytes of the text of a `Destination`: a name of `NAME_LENGTH_MAX` bytes, its `.` at -/// the end, and the longest port. An IP address with its port is shorter: at most 58 bytes, an -/// IPv6 address with a scope. pub(crate) const DESTINATION_LENGTH_MAX: usize = NAME_LENGTH_MAX + ".".len() + ":65535".len(); -/// Where the destination of each dial comes from: the peer that the command line names, or the -/// seeds of the network when it names none. #[derive(Debug, PartialEq, Eq)] pub enum Source { - /// The same destination for each dial. Destination(Destination), - /// A seed of the network for each dial, at random. Seeds(Seeds), } impl Source { - /// The destination of the next dial. pub fn destination(&self) -> std::borrow::Cow<'_, Destination> { match self { Source::Destination(destination) => std::borrow::Cow::Borrowed(destination), @@ -60,7 +36,6 @@ impl Source { } } -/// The seeds of a network that has seeds. Only `Seeds::new` makes one, so it has at least one. #[derive(Debug, PartialEq, Eq)] pub struct Seeds { first: &'static str, @@ -69,7 +44,6 @@ pub struct Seeds { } impl Seeds { - /// The seeds of `network`, or `None` if it has none. pub fn new(network: crate::chainparams::Network) -> Option { let (&first, rest) = network.seeds().split_first()?; Some(Seeds { @@ -79,8 +53,6 @@ impl Seeds { }) } - /// One of the seeds, at random, at the default port of the network. The choice needs no - /// secret, so it comes from the keys of `RandomState`: the seed with the lowest hash. fn choose(&self) -> Destination { let random = std::hash::RandomState::new(); let first = (random.hash_one(self.first), self.first); @@ -96,14 +68,10 @@ impl Seeds { } } -/// A seed of a network. Only `Seeds::choose` makes one, so it is on the list of its network. #[derive(Clone, Debug, PartialEq, Eq)] pub struct Seed(&'static str); impl Seed { - /// The name of the seed with the services that elo asks for. A seed answers - /// `x.` with only the nodes that offer each one of them. Some seeds have - /// no such names, and answer only the seed itself. fn services_name(&self) -> String { let services = crate::protocol::ServiceFlags::NETWORK_WITNESS; format!("x{services:x}.{}", self.0) @@ -116,19 +84,13 @@ impl std::fmt::Display for Seed { } } -/// What one dial looks up and connects to. #[derive(Clone, Debug, PartialEq, Eq)] pub enum Destination { - /// An IP address, which `handshake` dials with no lookup. Address(PeerAddress), - /// A name, which `handshake` looks up before each dial. Name { name: Name, port: std::num::NonZeroU16, }, - /// A seed, which `handshake` looks up with the services that elo asks for, and then without - /// them if that lookup fails or gives no address. Of its answers, it dials only the addresses - /// that the internet routes to. Seed { seed: Seed, port: std::num::NonZeroU16, @@ -145,15 +107,10 @@ impl std::fmt::Display for Destination { } } -/// An address that names a peer: its port is not 0, and its IP is not `0.0.0.0` or `::`. A -/// connect to those reaches this host. Only `PeerAddress::new` makes one, so each address that -/// `handshake` dials names a peer. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub struct PeerAddress(std::net::SocketAddr); impl PeerAddress { - /// `address` as the address of a peer, or `None` if it names no peer. An IPv4 address in - /// IPv6, such as `[::ffff:0.0.0.0]`, is checked as the IPv4 address. pub fn new(address: std::net::SocketAddr) -> Option { if address.port() == 0 || address.ip().to_canonical().is_unspecified() { return None; @@ -162,15 +119,10 @@ impl PeerAddress { } } -/// The name of a host. Only `Name::new` makes one, so each name has the form that it checks. #[derive(Clone, Debug, PartialEq, Eq)] pub struct Name(String); impl Name { - /// `host` as a name, or `None` if it is no name. A name has labels, split by `.`, of at most - /// `NAME_LENGTH_MAX` bytes in all, and can have one more `.` at the end, as a name with all - /// its labels. The last label is no number, so the resolver cannot read the name as an IPv4 - /// address. pub fn new(host: &str) -> Option { let labels = host.strip_suffix('.').unwrap_or(host); if labels.len() > NAME_LENGTH_MAX { @@ -193,10 +145,6 @@ impl std::fmt::Display for Name { } } -/// Whether the internet does not route to `ip`: this host, a private network, a link, or a range -/// for documentation or tests. A node on the internet cannot have such an address, so a seed that -/// gives one is wrong, or points elo at a host that is not on the network. An IPv4 address in IPv6 -/// is checked as the IPv4 address. A multicast address is not reserved, and its connect fails. fn is_reserved(ip: std::net::IpAddr) -> bool { match ip.to_canonical() { std::net::IpAddr::V4(ip) => { @@ -216,7 +164,6 @@ fn is_reserved(ip: std::net::IpAddr) -> bool { std::net::IpAddr::V6(ip) => { let [first, second, ..] = ip.segments(); let is_documentation = first == 0x2001 && second == 0x0db8; - // ORCHID, `2001:10::/28`, and ORCHIDv2, `2001:20::/28`: names that no route reaches. let is_orchid = first == 0x2001 && (second & 0xfff0 == 0x0010 || second & 0xfff0 == 0x0020); ip.is_unspecified() @@ -229,8 +176,6 @@ fn is_reserved(ip: std::net::IpAddr) -> bool { } } -/// Whether `label` is a label of a name: 1 to `LABEL_LENGTH_MAX` letters, digits and `-`, with no -/// `-` at the start or the end. fn is_label(label: &str) -> bool { if label.is_empty() { return false; @@ -246,10 +191,6 @@ fn is_label(label: &str) -> bool { .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-') } -/// Whether the IPv4 parse of the resolver reads `label` as a number: only digits, or `0x` and -/// only hex digits. That parse also reads the short forms, so `127.1`, `0x7f000001` and `127.0x1` -/// are each `127.0.0.1`. It needs each part to be a number, so a name whose last label is no -/// number goes to DNS. Octal, after a `0`, has only digits. fn is_number(label: &str) -> bool { let (digits, radix) = match label .strip_prefix("0x") @@ -261,15 +202,10 @@ fn is_number(label: &str) -> bool { digits.chars().all(|digit| digit.is_digit(radix)) } -/// Why the lookup of a name gave no address to dial. #[derive(Debug)] pub enum LookupError { - /// The resolver of the OS failed. Failed(std::io::Error), - /// The lookup of `host` took longer than `LOOKUP_TIMEOUT`. A dial to a seed has two lookups, - /// so the error names the one that did not end. Timeout { host: String }, - /// The lookup gave no address that `handshake` may dial. Empty, } @@ -287,12 +223,9 @@ impl std::fmt::Display for LookupError { } } -/// Why the TCP connect to one address failed. #[derive(Debug)] pub enum ConnectError { - /// The connect failed. Io(std::io::Error), - /// The connect took longer than `CONNECT_TIMEOUT`. Timeout, } @@ -305,29 +238,19 @@ impl std::fmt::Display for ConnectError { } } -/// Why the lookup, the connect or the handshake failed. #[derive(Debug)] pub enum HandshakeError { - /// The lookup of the name of the destination failed. Lookup(LookupError), - /// The TCP connect to each address of the destination failed. `address` is the last one, - /// `error` is its error, and `addresses_count` is how many addresses `handshake` tried. Connect { address: std::net::SocketAddr, addresses_count: usize, error: ConnectError, }, - /// The handshake took longer than `HANDSHAKE_TIMEOUT`. HandshakeTimeout, - /// A read or a write on the socket failed. Io(std::io::Error), - /// The peer closed the connection. Closed, - /// The peer sent a frame that elo refuses. Transport(crate::transport::Error), - /// elo refused the peer: a bad `version`, our own `version`, or too many messages. NetProcessing(crate::net_processing::HandshakeError), - /// The read of `RANDOM_SOURCE` for the salt of the peer failed. Salt(std::io::Error), } @@ -376,19 +299,12 @@ impl From for HandshakeError { } } -/// Why the connection ended after the handshake. #[derive(Debug)] pub enum RunError { - /// A write after the handshake took longer than `SEND_TIMEOUT`. SendTimeout, - /// A read or a write on the socket failed. Io(std::io::Error), - /// The peer closed the connection. Closed, - /// The peer sent a frame that elo refuses. Transport(crate::transport::Error), - /// elo refused the peer: a bad `ping`, `pong` or `headers`, or no `pong` or `headers` in - /// time. NetProcessing(crate::net_processing::PeerError), } @@ -418,40 +334,27 @@ impl From for RunError { } } -/// Why `Socket::receive` returned no message. Each one ends the connection, in the handshake -/// or after it. #[derive(Debug)] enum ReceiveError { - /// A read on the socket failed. Io(std::io::Error), - /// The peer closed the connection, inside a frame or between two frames. Closed, - /// The peer sent a frame that elo refuses. Transport(crate::transport::Error), } -/// One peer after the handshake: the socket and the machine for its messages, which borrows our -/// chain. Only `handshake` makes one, so `sync` cannot start before the handshake is complete. #[derive(Debug)] pub struct Connection<'a> { socket: Socket, peer: crate::net_processing::Peer<'a>, - /// The address of the peer that took the connect. address: std::net::SocketAddr, } -/// One peer after the header sync. Only `Connection::sync` makes one, so `next_tip` cannot start -/// before the sync ends. #[derive(Debug)] pub struct Synced<'a> { socket: Socket, peer: crate::net_processing::Peer<'a>, - /// The tip that the last call returned, or the sync if no call did. tip: crate::chain::Tip, } -/// The stream to one peer, its network, and the bytes of the frame that is not complete yet. -/// Only `receive` reads the stream, so each byte that comes goes into a frame. #[derive(Debug)] struct Socket { stream: tokio::net::TcpStream, @@ -459,17 +362,12 @@ struct Socket { frame: PartialFrame, } -/// The bytes of one frame, kept across waits. Each part has room for its exact size, and each -/// read goes into the bytes that the part still needs. So a read cannot take a byte of the -/// next frame. #[derive(Debug)] enum PartialFrame { - /// The header has not passed its checks. The bytes so far are `bytes[..filled]`. Header { bytes: [u8; crate::transport::MESSAGE_HEADER_SIZE], filled: usize, }, - /// The header passed its checks. The payload so far is `payload[..filled]`. Payload { header: crate::transport::MessageHeader, payload: Vec, @@ -477,13 +375,6 @@ enum PartialFrame { }, } -/// Looks up `destination` if it is a name or a seed. Then dials the first of its addresses that -/// takes the TCP connect, in a random order, on the network of `chain`, and runs the handshake. -/// Returns the connection for the messages after it, and their `version`. The sync of the -/// connection extends `chain` from its tip, so the next connection with the same chain does not -/// get those headers again. A chain below the minimum work starts again from genesis. A peer -/// whose chain does not have our tip answers from the highest header of our locator on its chain, -/// and a branch with more work takes the place of ours. pub async fn handshake<'a>( destination: &Destination, chain: &'a mut crate::chain::Chain, @@ -495,8 +386,6 @@ pub async fn handshake<'a>( handshake_stream(address, stream, chain).await } -/// The addresses that a dial to `destination` tries: its address, or the answers of its lookup in -/// the order of `name_order` or `seed_order`. async fn addresses(destination: &Destination) -> Result { match destination { Destination::Address(address) => Ok(Addresses { @@ -509,11 +398,7 @@ async fn addresses(destination: &Destination) -> Result let services = lookup(&services_name, *port).await; match services.and_then(seed_order) { Ok(addresses) => Ok(addresses), - // The resolver does not answer, so a lookup of the seed itself would only wait - // `LOOKUP_TIMEOUT` again. Err(error @ LookupError::Timeout { .. }) => Err(error), - // A seed with no such names fails the lookup. The error of the lookup of the seed - // itself is the one that the dial gives. Err(LookupError::Failed(_) | LookupError::Empty) => { seed_order(lookup(seed.0, *port).await?) } @@ -522,16 +407,12 @@ async fn addresses(destination: &Destination) -> Result } } -/// The addresses that one dial tries, in order: each one of `before`, then `last`. So a dial has -/// at least one address, with no check. #[derive(Debug)] struct Addresses { before: Vec, last: PeerAddress, } -/// The addresses of `host` at `port`, as the resolver of the OS gives them. The caller takes at -/// most its count max of them, so it does not copy the others. async fn lookup( host: &str, port: std::num::NonZeroU16, @@ -546,20 +427,13 @@ async fn lookup( } } -/// The `answers` of the lookup of a name that name a peer, at most `ADDRESSES_COUNT_MAX`, in the -/// order of `dial_order`. The person who names the host chose its addresses, so a name can be on -/// this host or on a private network. fn name_order( answers: impl IntoIterator, ) -> Result { - // Some resolvers give `0.0.0.0` or `::` for a name that they block. let answers = answers.into_iter().filter_map(PeerAddress::new); dial_order::(answers) } -/// The `answers` of the lookup of a seed that name a peer that the internet routes to, at most -/// `SEED_ADDRESSES_COUNT_MAX`, in the order of `dial_order`. The seed chose its answers, and not -/// the person who runs elo. fn seed_order( answers: impl IntoIterator, ) -> Result { @@ -570,17 +444,11 @@ fn seed_order( dial_order::(routable) } -/// At most `COUNT_MAX` of `answers`, each one time, in a random order. So each dial can start on -/// another address of a name that has many, such as a seed. The order needs no secret, so it comes -/// from the keys of `RandomState`. fn dial_order( answers: impl Iterator, ) -> Result { - // `connect_first` takes at most `ADDRESSES_COUNT_MAX`, so each cap fits in it. const { assert!(COUNT_MAX <= ADDRESSES_COUNT_MAX) }; let mut before: Vec = answers.take(COUNT_MAX).collect(); - // A hosts file can have the same name and address on two lines. A second try of an address - // costs up to `CONNECT_TIMEOUT` again. before.sort_unstable_by_key(|address| address.0); before.dedup(); let random = std::hash::RandomState::new(); @@ -588,19 +456,14 @@ fn dial_order( let Some(last) = before.pop() else { return Err(LookupError::Empty); }; - // `connect_first` checks only `ADDRESSES_COUNT_MAX`, so the cap of a seed is checked here. assert!(before.len() < COUNT_MAX, "{} {COUNT_MAX}", before.len()); Ok(Addresses { before, last }) } -/// The TCP connect to the first of `addresses` that takes it. Each try takes at most -/// `CONNECT_TIMEOUT`, and `ADDRESSES_COUNT_MAX` bounds the tries, so the time of a dial is -/// bounded. When each try fails, the error has the last address, its error, and the count. async fn connect_first( addresses: &Addresses, ) -> Result<(std::net::SocketAddr, tokio::net::TcpStream), HandshakeError> { let Addresses { before, last } = addresses; - // `dial_order` keeps at most `ADDRESSES_COUNT_MAX`, with `last`. assert!(before.len() < ADDRESSES_COUNT_MAX, "{}", before.len()); for &address in before { if let Ok(stream) = connect(address).await { @@ -617,7 +480,6 @@ async fn connect_first( } } -/// The TCP connect to `address`, within `CONNECT_TIMEOUT`. async fn connect(address: PeerAddress) -> Result { let connect = tokio::net::TcpStream::connect(address.0); match tokio::time::timeout(CONNECT_TIMEOUT, connect).await { @@ -627,7 +489,6 @@ async fn connect(address: PeerAddress) -> Result { - // The peer can send more frames in the same segment as its `verack`. Each read - // stops at the end of a frame, so they are still in the stream, and `sync` reads - // them next. let connection = Connection { socket, peer, @@ -693,25 +549,10 @@ async fn handshake_stream_exchange( } impl<'a> Connection<'a> { - /// The address of the peer: of the addresses of the destination, the one that took the - /// connect. pub fn address(&self) -> std::net::SocketAddr { self.address } - /// Runs one turn after the other until a batch that is not full ends the sync. Returns the - /// peer for `Synced::next_tip`, and the tip of our chain. The loop has no count bound, because - /// only the chain of the peer bounds the sync. A low-work sync gets the chain twice, and the - /// clock bounds the height of its first download. But above the minimum work the peer can send - /// headers for as long as it has them. It ends on an error: the peer closes, a read or a write - /// fails, a write takes longer than `SEND_TIMEOUT`, our `ping` gets no `pong` in time, or elo - /// refuses a frame or a message. It also ends when elo refuses a `headers`, none comes within - /// the headers timeout, or the sync ends on a chain below the minimum work. Each wait for a - /// message ends at the wake from `tick`, but the read takes a message that is already there, - /// also after the wake. `tick` checks the headers timeout only at the start of a turn. One turn - /// can write our `ping` and our `getheaders`, and then a `pong`, and each write can take up to - /// `SEND_TIMEOUT`. So the connection can end up to three times `SEND_TIMEOUT` after the tick - /// that sent our `getheaders`, with `SendTimeout`, `PingTimeout` or `HeadersTimeout`. pub async fn sync(self) -> Result<(Synced<'a>, crate::chain::Tip), RunError> { let Connection { mut socket, @@ -728,17 +569,6 @@ impl<'a> Connection<'a> { } impl<'a> Synced<'a> { - /// Runs one turn after the other until a batch that is not full ends a sync again on a new - /// tip: an announcement of the peer, or the last batch of the sync that a full announcement - /// starts. Returns the peer for the next call, and the new tip of our chain. An empty - /// announcement ends a sync on the same tip, and the loop goes on. So a peer cannot make the - /// caller print the tip again for each `headers`. The loop has no count bound, because a peer - /// sends messages for as long as it is connected. It ends on the errors of - /// `Connection::sync`. Each wait for a message ends at the wake from `tick`, each write ends - /// within `SEND_TIMEOUT`, and the frame length limit bounds each message. `tick` checks the - /// ping timeout only at the start of a turn. So a `pong` write that blocks while our `ping` is - /// outstanding can end the connection up to `SEND_TIMEOUT` after the ping timeout, with - /// `SendTimeout`. pub async fn next_tip(self) -> Result<(Synced<'a>, crate::chain::Tip), RunError> { let Synced { mut socket, @@ -750,9 +580,6 @@ impl<'a> Synced<'a> { (next, None) => peer = next, (next, Some(tip)) if tip == previous => peer = next, (peer, Some(tip)) => { - // On one connection, our chain takes a batch on its tip, or a branch with more - // work, which can be lower. So only the work goes up. It saturates at its - // maximum, so it can stay the same. assert!(tip.work() >= previous.work()); return Ok((Synced { socket, peer, tip }, tip)); } @@ -761,24 +588,15 @@ impl<'a> Synced<'a> { } } -/// Ticks `peer` and sends what the tick returns. Then waits for one message until the wake -/// from the tick, and gives the message to `peer`. Returns the peer for the next turn, which -/// ticks again, and the tip if the message ended the sync. So each wait has a wake from a tick -/// after the last message: a `pong` moves the wake to the next `ping`, and after a full batch -/// the next `getheaders` goes at once. async fn run_turn<'a>( socket: &mut Socket, peer: crate::net_processing::Peer<'a>, ) -> Result<(crate::net_processing::Peer<'a>, Option), RunError> { - // The wake goes to a tokio timer, so `now` comes from the same clock. Then a paused clock - // in a test also moves the time of the peer. let now = tokio::time::Instant::now().into_std(); let (peer, tick_outbound, wake) = peer.tick(now, nonce()).map_err(RunError::NetProcessing)?; for outbound in tick_outbound.into_outbounds() { run_send(socket, &outbound).await?; } - // The wait covers only the read, which is cancel safe, so the turn keeps the peer when the - // wait ends. A wait that ends at the wake loses no bytes: the next turn continues the frame. let receive = socket.receive(); match tokio::time::timeout_at(tokio::time::Instant::from_std(wake), receive).await { Ok(message) => run_exchange(socket, peer, &message?).await, @@ -786,40 +604,32 @@ async fn run_turn<'a>( } } -/// Gives `message` to `peer`, and sends the `pong` if there is one. Returns the peer for the -/// next turn, and the tip if the message ended the sync. async fn run_exchange<'a>( socket: &mut Socket, peer: crate::net_processing::Peer<'a>, message: &crate::transport::Message, ) -> Result<(crate::net_processing::Peer<'a>, Option), RunError> { - // The clock is read when the message is there, so a long wait for it does not age the clock. let (peer, received) = peer .receive(message, clock()) .map_err(RunError::NetProcessing)?; match received { crate::net_processing::Received::NoReply => { - // Each `ping` that the peer accepts gets a `pong`. assert_ne!(message.msg_type(), crate::protocol::PING); Ok((peer, None)) } crate::net_processing::Received::Pong(nonce) => { - // The peer replies only to a `ping`. assert_eq!(message.msg_type(), crate::protocol::PING); let pong = crate::net_processing::PeerOutbound::Pong(nonce); run_send(socket, &pong).await?; Ok((peer, None)) } crate::net_processing::Received::Synced(tip) => { - // Only a `headers` ends the sync. assert_eq!(message.msg_type(), crate::protocol::HEADERS); Ok((peer, Some(tip))) } } } -/// Writes `outbound` within `SEND_TIMEOUT`. A write that ends early can leave part of a frame -/// in the stream, so each error ends the connection. async fn run_send( socket: &mut Socket, outbound: &crate::net_processing::PeerOutbound, @@ -840,7 +650,6 @@ impl Socket { } } - /// Writes a message of the handshake. async fn send_handshake_outbound( &mut self, outbound: &crate::net_processing::HandshakeOutbound, @@ -855,7 +664,6 @@ impl Socket { } } - /// Writes a message after the handshake. async fn send_peer_outbound( &mut self, outbound: &crate::net_processing::PeerOutbound, @@ -879,7 +687,6 @@ impl Socket { self.send(msg_type, &payload).await } - /// Writes one frame with `msg_type` and `payload`. async fn send( &mut self, msg_type: crate::protocol::MessageType, @@ -889,18 +696,13 @@ impl Socket { self.stream.write_all(&frame).await } - /// Reads until one frame is complete, and returns its message. A wait that ends early, - /// for example at a timeout, loses no bytes: the next call continues the same frame. async fn receive(&mut self) -> Result { - // Each turn returns or reads at least one byte, and a frame has at most - // `MESSAGE_HEADER_SIZE` + `PAYLOAD_LENGTH_MAX` bytes. So the loop ends. loop { if let Some(message) = self .frame .cut(self.network) .map_err(ReceiveError::Transport)? { - // The next frame starts empty, so no byte of this frame goes into it. assert!(matches!(self.frame, PartialFrame::Header { filled: 0, .. })); return Ok(message); } @@ -908,17 +710,11 @@ impl Socket { } } - /// Reads at least one byte, and at most the bytes that the part still needs. A wait that - /// ends early reads nothing, because `read` is cancel safe. async fn read(&mut self) -> Result<(), ReceiveError> { let (missing, filled) = self.frame.missing(); - // `cut` takes each complete part, so this part still needs a byte. An empty slice - // would read nothing, and the zero would look like the end of the stream. assert!(!missing.is_empty()); - // A read returns at most the length of its slice, so it stops at the end of the part. let count = self.stream.read(missing).await.map_err(ReceiveError::Io)?; if count == 0 { - // The end of the stream, inside a frame or between two frames. return Err(ReceiveError::Closed); } *filled += count; @@ -934,7 +730,6 @@ impl PartialFrame { } } - /// The bytes that the part still needs, and the count of the bytes that it has. fn missing(&mut self) -> (&mut [u8], &mut usize) { match self { PartialFrame::Header { bytes, filled } => (&mut bytes[*filled..], filled), @@ -944,9 +739,6 @@ impl PartialFrame { } } - /// Takes each complete part. A complete header gets its checks and then room for its - /// payload. A complete payload gets its checksum and becomes the message, and the next - /// frame starts empty. fn cut( &mut self, network: crate::chainparams::Network, @@ -957,8 +749,6 @@ impl PartialFrame { } = self { let header = crate::transport::decode_header(network, bytes)?; - // The room is made only after the header passes its checks, so it is at most the - // length limit. let payload = vec![0; header.payload_length()]; *self = PartialFrame::Payload { header, @@ -982,16 +772,13 @@ impl PartialFrame { } } -/// The payload of a `ping` or a `pong`. fn nonce_payload(nonce: u64) -> Vec { let mut payload = Vec::with_capacity(size_of::()); nonce.encode(&mut payload); - // The payload is only the nonce, the `u64` that the peer decodes. assert_eq!(payload.len(), size_of::()); payload } -/// Seconds since the Unix epoch, or zero if the clock is before it. fn clock() -> u64 { match std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH) { Ok(elapsed) => elapsed.as_secs(), @@ -999,24 +786,22 @@ fn clock() -> u64 { } } -/// `clock` as the `timestamp` of our `version`, which is an `i64` on the wire. fn timestamp() -> i64 { i64::try_from(clock()).unwrap_or(i64::MAX) } -/// A SipHash with keys from the OS. The nonce in our `version` only detects a connection to -/// self, and the nonce in our `ping` only matches its `pong`. So neither needs to be secret. fn nonce() -> u64 { std::hash::RandomState::new().build_hasher().finish() } -/// The random source of the OS. const RANDOM_SOURCE: &str = "/dev/urandom"; -/// A salt for a low-work sync, each byte from `RANDOM_SOURCE`. The peer must not know it, and a -/// peer sees each nonce. `nonce` does not give that: the keys of `RandomState` come from the OS -/// once, and each later one is the last plus one. So the salt reads the OS for each value. fn salt() -> std::io::Result { + let (keys, offset) = salt_words()?; + Ok(crate::headerssync::Salt::new(keys, offset)) +} + +fn salt_words() -> std::io::Result<([u64; 2], usize)> { let mut source = std::fs::File::open(RANDOM_SOURCE)?; let mut key_0 = [0; size_of::()]; let mut key_1 = [0; size_of::()]; @@ -1024,58 +809,40 @@ fn salt() -> std::io::Result { source.read_exact(&mut key_0)?; source.read_exact(&mut key_1)?; source.read_exact(&mut offset)?; - Ok(crate::headerssync::Salt { - keys: [u64::from_le_bytes(key_0), u64::from_le_bytes(key_1)], - offset: usize::from_le_bytes(offset), - }) + Ok(( + [u64::from_le_bytes(key_0), u64::from_le_bytes(key_1)], + usize::from_le_bytes(offset), + )) } -/// The entry point of the `frame` fuzz target. #[cfg(fuzzing)] -// Only cargo-mutants reads this attribute. Its test runs do not build this module. #[cfg_attr(false, mutants::skip)] pub(crate) mod fuzz { - /// The network of the seeds. const NETWORK: crate::chainparams::Network = crate::chainparams::Network::Regtest; - /// The longest payload of the frame that `frame` writes. A run can set a larger `-max_len`, - /// and `encode` panics above the length limit. const WRITTEN_PAYLOAD_LENGTH_MAX: usize = 4096; - /// What `PartialFrame` takes from one stream. #[derive(Debug, PartialEq, Eq)] struct FrameRead { messages: Vec, end: FrameEnd, } - /// Why the reads of one stream stopped. #[derive(Debug, PartialEq, Eq)] enum FrameEnd { - /// The reads took each byte, and `PartialFrame` needs more. BytesEnded, - /// `PartialFrame` refused a frame, and no read took the last `unread_count` bytes. Refused { error: crate::transport::Error, unread_count: usize, }, } - /// Checks that each split of the same bytes gives the same `FrameRead`, that the messages - /// are the same bytes as the start of the stream, and that a frame from `encode` reads back - /// as its message. - /// - /// The first byte of `data` is the count of the size bytes after it. A size byte `s` is a - /// read of `s + 1` bytes. The rest of `data` is the stream. The committed corpus uses this - /// layout, so a change to the layout must rewrite the corpus. pub fn frame(data: &[u8]) { let Some((sizes_count, rest)) = data.split_first() else { return; }; let (sizes, stream) = rest.split_at(rest.len().min(usize::from(*sizes_count))); - // The largest reads and the smallest reads, so an input with no size bytes still compares - // two splits. let whole = frame_read(stream, std::iter::empty()); assert_eq!( frame_read(stream, std::iter::repeat(std::num::NonZeroUsize::MIN)), @@ -1086,7 +853,6 @@ pub(crate) mod fuzz { .map(|size_byte| std::num::NonZeroUsize::MIN.saturating_add(usize::from(*size_byte))); assert_eq!(frame_read(stream, read_sizes.clone()), whole); - // All the splits can be wrong in the same way, so compare with the stream too. let encoded: Vec = whole .messages .iter() @@ -1096,8 +862,6 @@ pub(crate) mod fuzz { .collect(); assert!(stream.starts_with(&encoded)); - // A reader that refuses each frame passes all the checks above, so read a frame that elo - // wrote. let payload = &stream[..stream.len().min(WRITTEN_PAYLOAD_LENGTH_MAX)]; let written = crate::transport::encode(NETWORK, crate::protocol::VERACK, payload); let read = frame_read(&written, read_sizes); @@ -1109,8 +873,6 @@ pub(crate) mod fuzz { assert_eq!(message.payload(), payload); } - /// Gives `stream` to a new `PartialFrame` as `Socket::receive` does, one read for each size - /// in `read_sizes`. A read takes all that it can when the sizes end. fn frame_read( stream: &[u8], mut read_sizes: impl Iterator, @@ -1118,8 +880,6 @@ pub(crate) mod fuzz { let mut frame = super::PartialFrame::new(); let mut messages = Vec::new(); let mut unread = stream; - // Each turn ends the loop, takes a message, or reads at least one byte. So the length of - // the stream bounds the loop. let end = loop { match frame.cut(NETWORK) { Ok(Some(message)) => { @@ -1129,7 +889,6 @@ pub(crate) mod fuzz { )); messages.push(message); } - // On the socket, a read of zero bytes means the same. Ok(None) if unread.is_empty() => break FrameEnd::BytesEnded, Ok(None) => { let (missing, filled) = frame.missing(); @@ -1176,26 +935,22 @@ mod tests { addresses.iter().copied().map(peer_address).collect() } - /// `addresses` in their order, with the last one as `last`. fn dial(addresses: &[std::net::SocketAddr]) -> super::Addresses { let mut before = peer_addresses(addresses); let last = before.pop().unwrap(); super::Addresses { before, last } } - /// The addresses of a dial, in their order. fn dialed(addresses: super::Addresses) -> Vec { let super::Addresses { mut before, last } = addresses; before.push(last); before } - /// Reads one frame on the peer's side of the socket. fn read_frame(stream: &mut std::net::TcpStream) -> Vec { read_frame_on(stream, crate::chainparams::Network::Regtest) } - /// `read_frame`, with the magic of `network`. fn read_frame_on( stream: &mut std::net::TcpStream, network: crate::chainparams::Network, @@ -1210,7 +965,6 @@ mod tests { frame } - /// Reads one frame on the peer's side of the socket, and returns its message. fn read_message(stream: &mut std::net::TcpStream) -> crate::transport::Message { let frame = read_frame(stream); let (header, payload) = frame.split_first_chunk().unwrap(); @@ -1219,8 +973,6 @@ mod tests { crate::transport::check_payload(header, payload.to_vec()).unwrap() } - /// Accepts the driver on `listener` and completes the handshake with Core's frames. A - /// driver that sends nothing more fails the test fast. fn accept_handshake(listener: &std::net::TcpListener) -> std::net::TcpStream { let (mut stream, _) = listener.accept().unwrap(); stream @@ -1237,14 +989,11 @@ mod tests { stream } - /// Our `ping`: its payload is only the nonce. fn assert_ping(message: &crate::transport::Message) { assert_eq!(message.msg_type(), crate::protocol::PING); assert_eq!(message.payload().len(), size_of::()); } - /// Reads our first `getheaders`. It asks for the headers after genesis, so it is - /// `GETHEADERS_FRAME`. fn read_first_get_headers(stream: &mut std::net::TcpStream) { assert_eq!( read_frame(stream), @@ -1252,14 +1001,12 @@ mod tests { ); } - /// Reads our `sendheaders`, which the first tick after the sync sends. fn read_send_headers(stream: &mut std::net::TcpStream) { let send_headers = read_message(stream); assert_eq!(send_headers.msg_type(), crate::protocol::SENDHEADERS); assert!(send_headers.payload().is_empty()); } - /// A `headers` with no header, which ends the sync at our tip. fn empty_headers_frame() -> Vec { crate::transport::encode( crate::chainparams::Network::Regtest, @@ -1271,13 +1018,10 @@ mod tests { #[test] fn their_version_gets_our_verack() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The peer sends Core's frames and keeps what the driver sends after their `version`. - // A peer may send its `verack` before ours comes, so the bitcoind test cannot see this. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || { let (mut stream, _) = listener.accept().unwrap(); - // A driver that sends no `verack` fails the test fast. stream .set_read_timeout(Some(std::time::Duration::from_secs(5))) .unwrap(); @@ -1301,8 +1045,6 @@ mod tests { #[test] fn our_version_has_the_local_clock_in_seconds() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // A peer reads this time only for its offset from its own clock, so the bitcoind test - // passes with each value. Only this test reads it. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || { @@ -1310,7 +1052,6 @@ mod tests { stream .set_read_timeout(Some(std::time::Duration::from_secs(5))) .unwrap(); - // The stream closes when this returns, so the handshake of the driver ends. read_message(&mut stream) }); @@ -1336,8 +1077,6 @@ mod tests { #[test] fn silent_peer_is_handshake_timeout() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The listener never accepts, so no `version` comes. The clock is paused after the - // connect. When no task can run, tokio moves the clock to the next timer. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let (result, elapsed) = block_on(async { @@ -1351,24 +1090,18 @@ mod tests { matches!(result, Err(super::HandshakeError::HandshakeTimeout)), "{result:?}" ); - // tokio rounds a deadline up to the next millisecond. assert_eq!(elapsed.as_secs(), super::HANDSHAKE_TIMEOUT.as_secs()); } #[test] fn silent_peer_after_our_getheaders_is_headers_timeout() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The peer completes the handshake, reads our `ping` and our `getheaders`, and then - // sends nothing. The clock is paused only after the handshake: while the peer thread - // answers, the runtime has no task to run, so a paused clock would jump to - // `HANDSHAKE_TIMEOUT`. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || { let mut stream = accept_handshake(&listener); assert_ping(&read_message(&mut stream)); read_first_get_headers(&mut stream); - // The socket stays open until the driver closes it. A close here would be `Closed`. let mut rest = Vec::new(); stream.read_to_end(&mut rest).unwrap(); rest @@ -1384,8 +1117,6 @@ mod tests { (result, start.elapsed()) }); let rest = peer_thread.join().unwrap(); - // The driver sends only what `tick` returns, so no second `getheaders` while the first - // is outstanding. assert!(rest.is_empty(), "{rest:?}"); assert!( matches!( @@ -1396,7 +1127,6 @@ mod tests { ), "{result:?}" ); - // 2 min, the headers timeout. tokio rounds a deadline up to the next millisecond. assert_eq!( elapsed.as_secs(), std::time::Duration::from_mins(2).as_secs() @@ -1406,9 +1136,6 @@ mod tests { #[test] fn header_far_after_the_local_clock_ends_the_connection() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The header has the last time of a `u32`. Until the year 2106, that is more than 2 h - // after the local clock in seconds, so only the driver decides here. A clock in - // milliseconds would take this header. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || { @@ -1428,7 +1155,6 @@ mod tests { &crate::fixtures::headers_payload_with(&[header]), ); stream.write_all(&frame).unwrap(); - // The driver closes the socket when it refuses the batch. let mut rest = Vec::new(); stream.read_to_end(&mut rest).unwrap(); }); @@ -1453,9 +1179,6 @@ mod tests { #[test] fn sync_that_ends_below_the_minimum_of_the_network_ends_the_connection() { - // Regtest has a minimum of zero, so only a test on another network shows that the driver - // gives the peer the minimum of its network. The empty batch ends the sync on genesis, - // which has less work than the signet minimum. let network = crate::chainparams::Network::Signet; let mut chain = crate::chain::Chain::new(network); let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); @@ -1467,8 +1190,6 @@ mod tests { .unwrap(); let frame = |msg_type, payload: &[u8]| crate::transport::encode(network, msg_type, payload); - // The reply to each frame of the driver. Our `ping` gets no `pong`, because the ping - // timeout is far after the end of the test. let replies = [ Some(frame( crate::protocol::VERSION, @@ -1488,7 +1209,6 @@ mod tests { stream.write_all(&reply).unwrap(); } } - // The driver closes the socket when the sync fails. let mut rest = Vec::new(); stream.read_to_end(&mut rest).unwrap(); msg_types @@ -1522,10 +1242,6 @@ mod tests { #[test] fn silent_peer_after_the_sync_is_ping_timeout() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The peer completes the handshake, ends the sync with an empty `headers`, and then - // sends nothing. The clock is paused only after the sync: while the peer thread - // answers, the runtime has no task to run, so a paused clock would jump to the headers - // timeout. The time starts before the sync, so it includes the send of our `ping`. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || { @@ -1534,7 +1250,6 @@ mod tests { read_first_get_headers(&mut stream); stream.write_all(&empty_headers_frame()).unwrap(); read_send_headers(&mut stream); - // The socket stays open until the driver closes it. A close here would be `Closed`. let mut rest = Vec::new(); stream.read_to_end(&mut rest).unwrap(); (ping, rest) @@ -1552,8 +1267,6 @@ mod tests { }); let (ping, rest) = peer_thread.join().unwrap(); assert_ping(&ping); - // The driver sends only what `tick` returns, so no second `ping` while the first is - // outstanding. assert!(rest.is_empty(), "{rest:?}"); assert!( matches!( @@ -1562,7 +1275,6 @@ mod tests { ), "{error:?}" ); - // 20 min, the ping timeout. tokio rounds a deadline up to the next millisecond. assert_eq!( elapsed.as_secs(), std::time::Duration::from_mins(20).as_secs() @@ -1572,8 +1284,6 @@ mod tests { #[test] fn empty_announcement_after_the_sync_does_not_give_the_tip_again() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The peer ends the sync on genesis, and then announces no header and then one. So the - // first call of `next_tip` gives the tip of the second announcement, not genesis again. let headers = crate::fixtures::headers_on_genesis(1); let announcement = crate::transport::encode( crate::chainparams::Network::Regtest, @@ -1591,7 +1301,6 @@ mod tests { let mut frames = empty_headers_frame(); frames.extend(announcement); stream.write_all(&frames).unwrap(); - // The driver closes the socket after `next_tip`. Nothing more goes before that. let mut rest = Vec::new(); stream.read_to_end(&mut rest).unwrap(); rest @@ -1615,11 +1324,6 @@ mod tests { #[test] fn pong_moves_the_next_ping_to_ping_interval_after_the_last() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The peer answers our first `ping` and not the second. So the connection ends at the - // ping timeout of the second `ping`, which goes at the ping interval after the first. - // A wake that stays at the timeout of the first `ping` sends the second one late. The - // `pong` comes before the empty `headers`, so the driver has it when the sync ends. The - // clock is paused only then, as in `silent_peer_after_the_sync_is_ping_timeout`. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || { @@ -1635,7 +1339,6 @@ mod tests { stream.write_all(&frames).unwrap(); read_send_headers(&mut stream); let second = read_message(&mut stream); - // The socket stays open until the driver closes it. A close here would be `Closed`. let mut rest = Vec::new(); stream.read_to_end(&mut rest).unwrap(); (first, second, rest) @@ -1663,8 +1366,6 @@ mod tests { ), "{error:?}" ); - // 2 min to the second `ping`, then 20 min to its timeout. tokio rounds a deadline up to - // the next millisecond. assert_eq!( elapsed.as_secs(), std::time::Duration::from_mins(2 + 20).as_secs() @@ -1674,8 +1375,6 @@ mod tests { #[test] fn peer_that_stops_reading_is_send_timeout() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The peer completes the handshake and then reads nothing. The test fills the kernel - // buffers before `run`, so the write of our first `ping` blocks. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || accept_handshake(&listener)); @@ -1684,8 +1383,6 @@ mod tests { let (connection, _theirs) = super::handshake(&destination(peer), &mut chain) .await .unwrap(); - // The peer thread ends when it has sent its `verack`, so this wait blocks nothing. - // The stream stays open, and nothing reads it. let _stream = peer_thread.join().unwrap(); let stream = &connection.socket.stream; stream.writable().await.unwrap(); @@ -1698,7 +1395,6 @@ mod tests { assert_eq!(full.kind(), std::io::ErrorKind::WouldBlock); tokio::time::pause(); let start = tokio::time::Instant::now(); - // A send with no timeout blocks forever. This timeout fails the test instead. let sync = connection.sync(); let result = tokio::time::timeout(std::time::Duration::from_mins(30), sync).await; (result, start.elapsed()) @@ -1707,15 +1403,12 @@ mod tests { matches!(result, Ok(Err(super::RunError::SendTimeout))), "{result:?}" ); - // tokio rounds a deadline up to the next millisecond. assert_eq!(elapsed.as_secs(), super::SEND_TIMEOUT.as_secs()); } #[test] fn peer_that_closes_inside_a_frame_is_closed() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The peer reads our `version`, sends all of Core's `version` but its last byte, and - // closes. A short read must not reach `check_payload`, which panics on it. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || { @@ -1735,11 +1428,6 @@ mod tests { #[test] fn frame_split_by_a_timeout_is_received_whole() { - // The peer sends the first half of Core's `version` and blocks. A `receive` under a - // timeout reads that half and times out. The peer then sends the rest, and the next - // `receive` must return the whole message, so the wait that ended kept the first half. - // The peer sends the rest only after the timeout: bytes on their way do not stop a - // paused clock, so the clock could jump before they come. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let (first_sent, first_sent_receiver) = std::sync::mpsc::channel(); @@ -1757,8 +1445,6 @@ mod tests { let (timeout, message) = block_on(async { let stream = tokio::net::TcpStream::connect(peer).await.unwrap(); let mut socket = super::Socket::new(stream, crate::chainparams::Network::Regtest); - // The runtime has no other task, so this wait blocks nothing. The clock is paused - // only when the first half is in the stream. first_sent_receiver.recv().unwrap(); tokio::time::pause(); let receive = socket.receive(); @@ -1777,14 +1463,10 @@ mod tests { #[test] fn ping_in_one_write_with_their_verack_gets_a_pong() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // The peer sends Core's `verack` and `ping` in one write, so both can be in the stream - // when the handshake ends. `sync` must still read the `ping` and answer it, after our - // own `ping` and `getheaders`. Then the peer closes. let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = listener.local_addr().unwrap(); let peer_thread = std::thread::spawn(move || { let (mut stream, _) = listener.accept().unwrap(); - // A driver that sends no `pong` fails the test fast. stream .set_read_timeout(Some(std::time::Duration::from_secs(5))) .unwrap(); @@ -1796,8 +1478,6 @@ mod tests { let mut frames = crate::fixtures::hex(crate::fixtures::VERACK_FRAME); frames.extend(crate::fixtures::hex(crate::fixtures::PING_FRAME)); stream.write_all(&frames).unwrap(); - // Our `ping` and `getheaders` go at the start of the first turn, before the driver - // reads. assert_ping(&read_message(&mut stream)); read_first_get_headers(&mut stream); read_frame(&mut stream) @@ -1810,7 +1490,6 @@ mod tests { connection.sync().await }); let pong = peer_thread.join().unwrap(); - // A `pong` has the payload of the `ping`, so only the message type differs. let mut expected = crate::fixtures::hex(crate::fixtures::PING_FRAME); let msg_type = crate::chainparams::MAGIC_SIZE..crate::chainparams::MAGIC_SIZE + "ping".len(); @@ -1823,7 +1502,6 @@ mod tests { #[test] fn refused_connect_is_connect_error() { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); - // Nothing listens on a port that was bound and then freed. let peer = std::net::TcpListener::bind("127.0.0.1:0") .unwrap() .local_addr() @@ -1851,8 +1529,6 @@ mod tests { fn connect_takes_the_first_address_that_takes_it() { let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let listening = listener.local_addr().unwrap(); - // Nothing listens on a port that was bound and then freed. The listener is open while - // the bind picks the port, so the two ports differ. let refused = std::net::TcpListener::bind("127.0.0.1:0") .unwrap() .local_addr() @@ -1865,8 +1541,6 @@ mod tests { #[test] fn connect_to_no_address_gives_the_last_one_and_the_count() { - // Both listeners are open while the binds pick the ports, so the two ports differ. - // Nothing listens on them after the drop. let first = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let last = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let addresses = [first.local_addr().unwrap(), last.local_addr().unwrap()]; @@ -1905,8 +1579,6 @@ mod tests { "{result:?}" ); - // One more than the count max, after the unspecified ones. Each port is new, so the - // ones that it keeps are the first ones. let answers: Vec = (1..=super::ADDRESSES_COUNT_MAX + 1) .map(|port| std::net::SocketAddr::from(([127, 0, 0, 1], u16::try_from(port).unwrap()))) .collect(); @@ -1926,7 +1598,6 @@ mod tests { assert_eq!(kept, peer_addresses(&[first, second])); } - // The resolver of the OS reads `localhost` from its hosts file, with no name server. #[test] fn lookup_gives_the_addresses_of_a_name_with_the_port() { let name = super::Name::new("localhost").unwrap(); @@ -1947,8 +1618,6 @@ mod tests { "{result:?}" ); - // One more than the count max, after one that the internet does not route to. Each port - // is new, so the ones that it keeps are the first ones. let answers: Vec = (1..=super::SEED_ADDRESSES_COUNT_MAX + 1) .map(|port| std::net::SocketAddr::from(([1, 1, 1, 1], u16::try_from(port).unwrap()))) .collect(); @@ -1965,8 +1634,6 @@ mod tests { fn routable_is_each_address_but_this_host_private_networks_links_and_test_ranges() { let v4 = |a, b, c, d| std::net::IpAddr::V4(std::net::Ipv4Addr::new(a, b, c, d)); let v6 = |text: &str| std::net::IpAddr::V6(text.parse().unwrap()); - // The first and the last address of each range that the internet does not route to, and - // the addresses next to them. for (ip, routable) in [ (v4(0, 0, 0, 1), false), (v4(0, 255, 255, 255), false), @@ -2069,7 +1736,6 @@ mod tests { let network = crate::chainparams::Network::Mainnet; let source = super::Source::Seeds(super::Seeds::new(network).unwrap()); let mut chosen = std::collections::BTreeSet::new(); - // 8 seeds: a run of 1000 choices misses one of them once in about 2^190 runs. for _ in 0..1000 { let super::Destination::Seed { seed, port } = source.destination().into_owned() else { panic!(); @@ -2095,13 +1761,10 @@ mod tests { #[test] fn each_salt_word_is_new() { - // A fixed salt, or one that reads a word twice, passes each other test, and a peer that - // knows the salt can make a chain that matches each bit. 6 random words are all different, - // but once in about 2^60 runs. let mut words = Vec::new(); - for salt in [super::salt().unwrap(), super::salt().unwrap()] { - words.extend(salt.keys); - words.push(u64::try_from(salt.offset).unwrap()); + for (keys, offset) in [super::salt_words().unwrap(), super::salt_words().unwrap()] { + words.extend(keys); + words.push(u64::try_from(offset).unwrap()); } let mut distinct = words.clone(); distinct.sort_unstable(); diff --git a/src/net_processing.rs b/src/net_processing.rs index d7bc27d..c6c8597 100644 --- a/src/net_processing.rs +++ b/src/net_processing.rs @@ -1,46 +1,26 @@ -//! The handshake: the `version` and `verack` messages before a peer is ready. Then the -//! messages after it: our `ping`, and the header sync. - use crate::serialize::{Decode, Encode}; -/// The lowest protocol version elo accepts from a peer. const PROTOCOL_VERSION_MIN: i32 = 70016; -// elo accepts its own `version`. const _: () = assert!(crate::protocol::PROTOCOL_VERSION >= PROTOCOL_VERSION_MIN); -/// The most messages a peer may send in a handshake, its `verack` included. A peer needs five -/// at most: `version`, `wtxidrelay`, `sendaddrv2`, `sendtxrcncl` and `verack`. The rest is room -/// for messages that later BIPs add. const MESSAGE_COUNT_MAX: u32 = 16; -/// How long after our last `ping` the next one goes, when its `pong` came. const PING_INTERVAL: std::time::Duration = std::time::Duration::from_mins(2); -/// How long our `ping` may wait for its `pong`. const PING_TIMEOUT: std::time::Duration = std::time::Duration::from_mins(20); -// `PingState::send` wakes `PING_TIMEOUT` after `now`. So the `wake > now` assert in `tick` -// holds for it. const _: () = assert!(!PING_TIMEOUT.is_zero()); -/// How long our `getheaders` may wait for its `headers`. const HEADERS_TIMEOUT: std::time::Duration = std::time::Duration::from_mins(2); -// `SyncState::tick` sends a `getheaders` and wakes `HEADERS_TIMEOUT` after `now`. So the -// `wake > now` assert in `tick` holds for it. const _: () = assert!(!HEADERS_TIMEOUT.is_zero()); -/// Why elo refuses the peer in the handshake. Each one ends the connection. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum HandshakeError { - /// Their `version` payload did not decode. Version(crate::serialize::Error), - /// Their protocol version is below `PROTOCOL_VERSION_MIN`. Obsolete(i32), - /// Their `version` has our nonce, so the socket is connected to itself. SelfConnection, - /// The peer sent `MESSAGE_COUNT_MAX` messages without its `verack`. TooManyMessages, } @@ -69,42 +49,22 @@ impl std::fmt::Display for HandshakeError { impl std::error::Error for HandshakeError {} -/// Why elo refuses the peer after the handshake. Each one ends the connection. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum PeerError { - /// Their `ping` payload did not decode. Ping(crate::serialize::Error), - /// Their `pong` payload did not decode. Pong(crate::serialize::Error), - /// Their `pong` came when no `ping` of ours was outstanding. UnsolicitedPong, - /// Their `pong` has a nonce that is not the nonce of our outstanding `ping`. PongNonce, - /// Our `ping` had no `pong` within `PING_TIMEOUT`. PingTimeout, - /// Their `inv` payload did not decode, or it has too many entries. Inv(crate::protocol::InvError), - /// Their `headers` payload did not decode, or it has too many headers or a transaction. Headers(crate::protocol::HeadersError), - /// Our chain refused their batch, or a header that the second download of a low-work sync - /// released. The error says why. Extend(crate::chain::ExtendError), - /// A low-work sync refused their batch. The error says why. HeadersSync(crate::headerssync::HeadersSyncError), - /// Their `headers` came while our `getheaders` was due, before the tick that sends it. The - /// driver ticks before each read, so only a peer machine without the driver sees this. UnsolicitedHeaders, - /// Our `getheaders` had no `headers` within `HEADERS_TIMEOUT`. HeadersTimeout, - /// Their sync ended, and our chain has less work than the minimum. ChainWorkTooLow, - /// A branch below the margin needs a low-work sync, and this connection had one. Each sync - /// needs a new salt, and a connection reads one. So the connection ends, and the next one - /// reads a new salt. SecondLowWorkSync, - /// Their `wtxidrelay` came after the handshake. LateWtxidRelay, - /// Their `sendaddrv2` came after the handshake. LateSendAddrV2, } @@ -140,8 +100,6 @@ impl std::fmt::Display for PeerError { impl std::error::Error for PeerError {} -/// The `version` that elo sends to `peer`. elo serves no blocks and relays nothing, so it -/// claims no services and asks for no transactions. fn our_version(peer: std::net::SocketAddr, timestamp: i64, nonce: u64) -> crate::protocol::Version { let unspecified = std::net::SocketAddr::from((std::net::Ipv6Addr::UNSPECIFIED, 0)); crate::protocol::Version { @@ -157,69 +115,44 @@ fn our_version(peer: std::net::SocketAddr, timestamp: i64, nonce: u64) -> crate: } } -/// Where the handshake is. Our `version` is sent in both states. #[derive(Debug)] enum State { - /// Their `version` has not come. AwaitingVersion, - /// Their `version` came and our `verack` is sent. Their `verack` has not come. AwaitingVerack(crate::protocol::Version), } -/// The handshake with one peer. It does no I/O: the driver gives it each message and sends -/// what it returns. #[derive(Debug)] pub(crate) struct Handshake<'a> { state: State, - /// Our chain, which the sync after the handshake extends. It outlives the connection, so the - /// next connection syncs from its tip. It is at genesis or has at least `work_min`. chain: &'a mut crate::chain::Chain, - /// The work that our chain must reach in the sync. work_min: crate::pow::Work, - /// The salt of a low-work sync. It must be secret. salt: crate::headerssync::Salt, - /// The nonce in our `version`. nonce: u64, - /// The messages that came, fewer than `MESSAGE_COUNT_MAX`. message_count: u32, } -/// A message that the handshake sends. #[derive(Debug)] pub(crate) enum HandshakeOutbound { - /// Our `version`, encoded. Version(Vec), - /// A `verack`, which has no payload. Verack, } -/// A message that elo sends after the handshake. #[derive(Debug)] pub(crate) enum PeerOutbound { - /// Our `ping` with a new nonce. Ping(u64), - /// A `pong` with the nonce of their `ping`. Pong(u64), - /// Our `sendheaders`, which has no payload. It asks the peer to announce each new header with a - /// `headers`. SendHeaders, - /// Our `getheaders` from the last header that the sync has. GetHeaders(crate::protocol::GetHeaders), } -/// What a tick sends. It has no `pong`, because only their `ping` gets one. #[derive(Debug)] pub(crate) struct TickOutbound { - /// The nonce of our `ping`, if one is due. ping: Option, - /// Whether our `sendheaders` is due. send_headers: bool, - /// Our `getheaders`, if one is due. get_headers: Option, } impl TickOutbound { - /// The messages to send, in order: our `ping`, our `sendheaders`, then our `getheaders`. pub(crate) fn into_outbounds(self) -> impl Iterator { let ping = self.ping.map(PeerOutbound::Ping); let send_headers = self.send_headers.then_some(PeerOutbound::SendHeaders); @@ -228,41 +161,21 @@ impl TickOutbound { } } -/// What the peer does after a message. It has no `ping` and no `getheaders`, because only a -/// tick sends them. #[derive(Debug)] pub(crate) enum Received { - /// Send nothing. The message was skipped, or it was a `pong` or a full batch that the peer - /// took. NoReply, - /// Send a `pong` with the nonce of their `ping`. Pong(u64), - /// Their batch was not full, so the sync ended, and our chain has at least the minimum work. - /// It holds the tip of our chain. After the sync, each batch that is not full gives this - /// again, an empty one too. Synced(crate::chain::Tip), } -/// What the handshake does after a message. #[derive(Debug)] pub(crate) enum Step<'a> { - /// Read the next message. Wait(Handshake<'a>), - /// Send the message, then read the next one. Reply(Handshake<'a>, HandshakeOutbound), - /// The handshake is complete. It holds the peer for the messages after it, and their - /// `version`. Done(Peer<'a>, crate::protocol::Version), } impl<'a> Handshake<'a> { - /// Returns our `version` to `peer` on the network of `chain`, to send first. The sync after the - /// handshake extends `chain` from its tip, and must end on a chain with at least `work_min`. A - /// chain below `work_min` starts again from genesis, because only a sync that reaches the - /// minimum keeps its headers. A low-work sync reads `salt`, which must be new and secret. The - /// first batch on a genesis below `work_min` can start one, and so can a full batch of a - /// branch below the margin. A connection has at most one, and the sync moves the salt into - /// it. pub(crate) fn start( peer: std::net::SocketAddr, timestamp: i64, @@ -274,15 +187,10 @@ impl<'a> Handshake<'a> { let ours = our_version(peer, timestamp, nonce); let mut payload = Vec::new(); ours.encode(&mut payload); - // The payload decodes to the same `version`, with no bytes left. let mut input = payload.as_slice(); assert_eq!(crate::protocol::Version::decode(&mut input), Ok(ours)); assert!(input.is_empty()); - // A chain below the minimum holds headers that no sync proved: a batch that ended a sync - // below the minimum, or the first headers that a low-work sync released before its - // connection ended. A peer can make such headers cheaply, so a kept chain could grow - // without a bound. if chain.tip().work() < work_min { chain.restart(); } @@ -303,9 +211,6 @@ impl<'a> Handshake<'a> { ) } - /// Before their `version`, each other message is skipped. After it, each message is - /// skipped until their `verack`, a second `version` too. Message `MESSAGE_COUNT_MAX` must - /// be their `verack`. pub(crate) fn receive( self, message: &crate::transport::Message, @@ -345,8 +250,6 @@ impl<'a> Handshake<'a> { assert_ne!(theirs.nonce, self.nonce); if message.msg_type() == crate::protocol::VERACK { - // `start` holds that a chain below the minimum is at genesis, and the - // handshake holds the only borrow of the chain. let (download, salt) = if self.chain.tip().work() < self.work_min { (Download::Genesis(self.salt), None) } else { @@ -378,7 +281,6 @@ impl<'a> Handshake<'a> { } } -/// The handshake after `message_count` messages, if the peer may send one more. fn next( state: State, chain: &mut crate::chain::Chain, @@ -401,8 +303,6 @@ fn next( } } -/// Every field up to `start_height` is required. The bytes after `relay` are ignored. A -/// `version` with our `nonce` is our own. fn receive_version( message: &crate::transport::Message, nonce: u64, @@ -420,133 +320,69 @@ fn receive_version( } } -/// The peer after the handshake. Only `Handshake` makes one, so no message reaches it before -/// the handshake is complete. It does no I/O, reads no clock and draws no random number: the -/// driver gives the handshake a salt, each message with the local clock, and the instant of each -/// tick with a nonce, and sends what it returns. #[derive(Debug)] pub(crate) struct Peer<'a> { ping: PingState, sync: SyncState, send_headers: SendHeadersState, - /// Our chain, from the handshake. The sync puts the headers of the peer on its tip. chain: &'a mut crate::chain::Chain, - /// The work that `chain` must reach in the sync. work_min: crate::pow::Work, - /// The salt of a low-work sync of a branch below the margin, until a sync takes it. While the - /// first batch on genesis can start a low-work sync, `Download::Genesis` holds it, and a batch - /// that starts none gives it back. A connection has at most one low-work sync, so after one - /// there is none. salt: Option, } -/// Where our `ping` is. At most one is outstanding. #[derive(Debug)] enum PingState { - /// No `ping` went yet. The next tick sends one. Unsent, - /// Our `ping` with `nonce` went at `sent`. Its `pong` has not come. Outstanding { nonce: u64, sent: std::time::Instant, }, - /// Our last `ping` went at `sent`. Its `pong` came. - Answered { sent: std::time::Instant }, + Answered { + sent: std::time::Instant, + }, } -/// Where the header sync is. At most one `getheaders` is outstanding. #[derive(Debug)] enum SyncState { - /// Our next `getheaders` for this download is due: none went yet, or the last batch did not - /// end the sync. The next tick sends it. Due(Download), - /// Our `getheaders` for `download` went at `sent`. Its `headers` has not come. Outstanding { download: Download, sent: std::time::Instant, }, - /// A batch ended the sync. Our chain has at least the minimum work. The peer has no header - /// after our tip, or it is on a branch that it ended with at most our work. No `getheaders` is - /// outstanding, so each `headers` is an announcement. One on our tip goes on it, and a full one - /// makes a `getheaders` due. One off our tip makes a `getheaders` due, and so does an `inv` of - /// a block. Synced, } -/// Where our `sendheaders` is. It goes once, in the first tick at `SyncState::Synced`. Before it, -/// the peer announces a new header with an `inv`, which makes our `getheaders` due. A `headers` -/// that came while our `getheaders` was outstanding would look like its answer. So it does not go -/// before the sync ends. After a full announcement, an announcement off our tip or an `inv` of a -/// block, our `getheaders` is outstanding again, and an announcement in that window looks like its -/// answer. A peer that announces a block with an `inv` sends no `headers` announcement before that -/// answer, because the answer gives it the header that the next announcement connects to. A peer -/// that announces a block off our tip can announce the next block in that window, on the block -/// before it. Then the announcement is not on our locator, so it ends the connection with -/// `NotOnLocator`. #[derive(Debug)] enum SendHeadersState { - /// It did not go yet. Unsent, - /// It went. Sent, } -/// Where the next batch of the sync goes. Only `Genesis`, `Chain` and `Branch` change our chain as -/// each batch comes. In a low-work sync our chain takes only the headers that the second download -/// releases. On genesis they go on the tip that the first download read. On a fork they go on the -/// fork as one branch, after the last batch. So no other path may change the chain before the sync -/// ends. A branch is on the chain as it was at its first batch, so nothing else may change the -/// chain while it goes on. The boxes keep `Genesis` and `Chain` small, because each download holds -/// its commitments and links, and a branch holds its headers. A sync above the minimum moves only -/// `Chain`, `Branch`, `BranchPresync` and `BranchRedownload`. #[derive(Debug)] enum Download { - /// On genesis, the only header of our chain, which is below the minimum work. A full batch - /// starts a low-work sync with the salt. Only the handshake makes this, so only the first - /// batch of a connection can start a low-work sync. Genesis(crate::headerssync::Salt), - /// On the tip of our chain, which has at least the minimum work. Chain, - /// The first download of a low-work sync, on its last header. Presync(Box), - /// The second download of a low-work sync, on its last header. Redownload(Box), - /// A branch below the tip of our chain, which has at least the minimum work, on its last - /// header. It has at most the work of our chain. Branch(Box), - /// The first download of a low-work sync of a branch below the margin, on its last header. BranchPresync(Box), - /// The second download of a low-work sync of a branch below the margin, on its last header. BranchRedownload(Box), } -/// The first download of a low-work sync of a branch below the margin. It starts on the fork of -/// the branch, and it must reach the `branch_work_min` of `Extended::BelowMargin`. Our chain has -/// at least the minimum work. #[derive(Debug)] struct BranchPresync { - /// The fork, from `Extended::BelowMargin`. start: crate::chain::SyncStart, presync: crate::headerssync::Presync, } -/// The second download of a low-work sync of a branch below the margin, and the headers that it -/// released. They wait for the last batch, and then they go on the fork as one branch. Below the -/// minimum of the sync, the second download takes only the chain of the first, up to one period -/// above its last commitment, and the clock bounds the height of the first. So that bounds these -/// headers, as it bounds the headers that a sync on genesis puts on our chain. #[derive(Debug)] struct BranchRedownload { - /// The fork, from `Extended::BelowMargin`. start: crate::chain::SyncStart, redownload: crate::headerssync::Redownload, - /// The headers that `redownload` released, in order. The first is on the fork. released: Vec, } impl Download { - /// The next batch goes on the tip of `chain`, which has at least `work_min`. Each - /// `Download::Chain` comes from here, so each one holds that work. fn on_tip(chain: &crate::chain::Chain, work_min: crate::pow::Work) -> Download { assert!(chain.tip().work() >= work_min); Download::Chain @@ -554,13 +390,6 @@ impl Download { } impl<'a> Peer<'a> { - /// A `ping` gets a `pong` with its nonce. A `pong` must answer our outstanding `ping`, and a - /// `headers` our outstanding `getheaders`, or come after the sync. After the sync, an `inv` of - /// a block or a `headers` off our tip makes our `getheaders` due. A `wtxidrelay` or a - /// `sendaddrv2` is an error: a peer turns these features on only between its `version` and its - /// `verack`. Each other message is skipped. Each result but an error returns the peer, because - /// an error ends the connection. `clock` is the local clock, in seconds since the Unix epoch, - /// and only a `headers` reads it. pub(crate) fn receive( self, message: &crate::transport::Message, @@ -568,7 +397,6 @@ impl<'a> Peer<'a> { ) -> Result<(Peer<'a>, Received), PeerError> { let msg_type = message.msg_type(); if msg_type == crate::protocol::PING { - // The bytes after the nonce are ignored. let mut input = message.payload(); let nonce = u64::decode(&mut input).map_err(PeerError::Ping)?; Ok((self, Received::Pong(nonce))) @@ -589,20 +417,12 @@ impl<'a> Peer<'a> { } } - /// After the sync, an `inv` of a block makes our `getheaders` due, from the tip of our chain. - /// The peer announces a block with an `inv` before it has our `sendheaders`, and when the - /// headers of the block do not connect to the last header that it sent us. Then each later - /// block comes as an `inv` too, until a `headers` answers our `getheaders` again. In a sync, - /// the `inv` came before the answer to our `getheaders`, so the answer has the block. The - /// payload is checked first, also then. The bytes after the last entry are ignored. fn receive_inv(self, message: &crate::transport::Message) -> Result, PeerError> { assert_eq!(message.msg_type(), crate::protocol::INV); let mut input = message.payload(); let inv = crate::protocol::Inv::decode(&mut input).map_err(PeerError::Inv)?; if inv.has_block() && matches!(self.sync, SyncState::Synced) { - // A sync ends only on a chain with at least the minimum work, so the next batch goes - // on our tip. Ok(Peer { sync: SyncState::Due(Download::on_tip(self.chain, self.work_min)), ..self @@ -612,8 +432,6 @@ impl<'a> Peer<'a> { } } - /// The `pong` must have the nonce of our outstanding `ping`. Then no `ping` is outstanding. - /// The bytes after the nonce are ignored. fn receive_pong(self, message: &crate::transport::Message) -> Result, PeerError> { assert_eq!(message.msg_type(), crate::protocol::PONG); @@ -634,28 +452,6 @@ impl<'a> Peer<'a> { } } - /// The `headers` must answer our outstanding `getheaders`, and the download of that - /// `getheaders` must take the batch at `clock`. Then no `getheaders` is outstanding. After the - /// sync, a `headers` announces new headers. One on the tip of our chain goes on it. A full one - /// makes the next batch due, and each other one ends a sync again. One off our tip makes our - /// `getheaders` due. Only an answer to our locator can move our tip to another branch, so an - /// announcement on a header below our tip does not. A `headers` is unsolicited only while our - /// `getheaders` is due and the tick has not sent it. The payload is checked first, also then. - /// The bytes after the last transaction count are ignored. - /// - /// A full batch on a genesis below the minimum work starts a low-work sync with the salt, and - /// the batch goes to its first download. Else our chain takes a batch on its tip, or a branch - /// with more work on a header of our locator, and then a full batch makes the next one due. A - /// full batch of a branch with no more work makes the next one due on its last header. A full - /// batch of a branch below the margin starts a low-work sync on its fork with the salt, and the - /// batch goes to its first download. A batch that is not full ends the sync, an empty one too, - /// and the sync must end on a chain with at least the minimum work. - /// - /// In a low-work sync, each download makes the next batch due, until the second download - /// reaches the minimum. On genesis, our chain takes each header that it releases, with the - /// checks of each batch. Then the sync goes on from the tip of our chain if the batch was full, - /// or ends. On a fork, the headers that it releases wait for its last batch, and then they go - /// on the fork as one batch of a branch. fn receive_headers( mut self, message: &crate::transport::Message, @@ -690,16 +486,6 @@ impl<'a> Peer<'a> { } } - /// Returns the peer, what to send, and when to tick next. A `ping` with `nonce` is due at - /// once after the handshake. Then it is due `PING_INTERVAL` after the last `ping` went, if - /// its `pong` came. A `getheaders` is due at once after the handshake, at once after each - /// batch that does not end the sync, and at once after an `inv` of a block or a `headers` off - /// our tip after the sync. The tick fails when our outstanding `ping` is `PING_TIMEOUT` old, or - /// our outstanding `getheaders` is `HEADERS_TIMEOUT` old. The `ping` is checked first. Each - /// deadline is due at its instant, not after it. The wake is the earliest deadline. The `now` - /// of a tick is not before the `now` of an earlier tick, because each deadline counts from an - /// earlier `now`. Our `sendheaders` goes in the first tick at `SyncState::Synced`, and has no - /// deadline. pub(crate) fn tick( self, now: std::time::Instant, @@ -721,9 +507,7 @@ impl<'a> Peer<'a> { (send_headers, _) => (send_headers, false), }; - // Each `getheaders` that is due goes in this tick. assert!(!matches!(sync, SyncState::Due(_))); - // A wake at or before `now` would make the driver tick again with no wait. assert!(wake > now); let outbound = TickOutbound { ping: ping_nonce, @@ -743,8 +527,6 @@ impl<'a> Peer<'a> { } impl PingState { - /// Returns the next state, the nonce of our `ping` if one is due, and its deadline: the - /// ping timeout, or the next `ping` if none is outstanding. fn tick( self, now: std::time::Instant, @@ -753,7 +535,6 @@ impl PingState { match self { PingState::Unsent => Ok(PingState::send(now, nonce)), PingState::Outstanding { sent, .. } => { - // `sent` is the `now` of an earlier tick. assert!(sent <= now); let timeout = sent + PING_TIMEOUT; if now < timeout { @@ -763,7 +544,6 @@ impl PingState { } } PingState::Answered { sent } => { - // `sent` is the `now` of an earlier tick. assert!(sent <= now); let due = sent + PING_INTERVAL; if now < due { @@ -775,7 +555,6 @@ impl PingState { } } - /// Our `ping` with `nonce` goes at `now`. Its deadline is its timeout. fn send(now: std::time::Instant, nonce: u64) -> (PingState, Option, std::time::Instant) { let ping = PingState::Outstanding { nonce, sent: now }; (ping, Some(nonce), now + PING_TIMEOUT) @@ -783,10 +562,6 @@ impl PingState { } impl SyncState { - /// Returns the next state, our `getheaders` if one is due, and the headers timeout if a - /// `getheaders` is outstanding. The `getheaders` has the locator of `chain`, or only the last - /// header of a download of a low-work sync or of a branch. The answer of a peer that left that - /// header is not on it, and that download refuses it. fn tick( self, now: std::time::Instant, @@ -818,7 +593,6 @@ impl SyncState { Ok((sync, Some(get_headers), Some(now + HEADERS_TIMEOUT))) } SyncState::Outstanding { sent, .. } => { - // `sent` is the `now` of an earlier tick. assert!(sent <= now); let timeout = sent + HEADERS_TIMEOUT; if now < timeout { @@ -828,8 +602,6 @@ impl SyncState { } } SyncState::Synced => { - // Only a sync that reaches the minimum work ends at `Synced`, and the work of a - // chain does not go down. assert!(chain.tip().work() >= work_min); Ok((self, None, None)) } @@ -837,8 +609,6 @@ impl SyncState { } } -/// Their answer to our `getheaders` for `download`, which must take it at `clock`. Returns where -/// the next batch goes, or `None` if the sync ended. A low-work sync of a branch takes `salt`. fn receive_answer( chain: &mut crate::chain::Chain, work_min: crate::pow::Work, @@ -913,8 +683,6 @@ fn receive_answer( } crate::headerssync::RedownloadStep::Done(released) => { extend_released(chain, released, clock)?; - // The second download gave each header that it checked, and it reached the - // minimum with them. let next = Download::on_tip(chain, work_min); Ok(full.then_some(next)) } @@ -923,11 +691,6 @@ fn receive_answer( } } -/// The first batch, on genesis, which is below `work_min`. A full batch starts a low-work sync -/// with `salt`. Our chain takes a batch that is not full, and it ends the sync, which must reach -/// `work_min`. That batch starts no low-work sync, so `salt` goes to `salt_left`, for a sync of a -/// branch. Returns where the next batch goes, or `None` if the sync ended. A saturated work means -/// "at least the highest number", so it reaches the minimum. fn receive_on_genesis( chain: &mut crate::chain::Chain, work_min: crate::pow::Work, @@ -936,20 +699,14 @@ fn receive_on_genesis( headers: crate::protocol::Headers, clock: u64, ) -> Result, PeerError> { - // Only the handshake makes `Download::Genesis`, only on a chain below the minimum, and `start` - // puts such a chain on genesis. assert_eq!(chain.tip().height(), 0); assert!(chain.tip().work() < work_min); if headers.is_full() { - // The peer can make cheap headers for as long as it wants, so the chain keeps none of - // them until the chain of the peer shows the minimum. let presync = crate::headerssync::Presync::new(chain.sync_start_on_tip(), work_min, clock, salt); let step = presync.receive(headers).map_err(PeerError::HeadersSync)?; return Ok(Some(presync_next(step))); } - // Our `getheaders` had the locator of the chain, which on genesis has only genesis. So no - // batch is a branch below our tip, and the chain keeps only an empty batch. let empty = headers.first().is_none(); match chain .extend_on_locator(headers, clock, work_min) @@ -961,7 +718,6 @@ fn receive_on_genesis( panic!("genesis has no header below it") } } - // Only `Download::Genesis` held the salt. assert!(salt_left.replace(salt).is_none()); if chain.tip().work() >= work_min { Ok(None) @@ -970,20 +726,6 @@ fn receive_on_genesis( } } -/// Where the next batch goes after `chain`, which has at least `work_min`, did `extended` at -/// `clock` with an answer to our `getheaders` for `Download::Chain` or `Download::Branch`, or with -/// the headers of a low-work sync of a branch. `full` is true when that answer was full. Returns -/// `None` if the sync ended. -/// -/// A peer whose chain does not hold our tip sends the headers after the highest header of our -/// locator that is on its chain: our tip is on another branch. The chain takes a branch with more -/// work, and then a full batch makes the next one due on our tip. A branch with at most the work of -/// our chain does not go on it. If its batch is full, the peer can have more of it, so the next one -/// is due on its last header. Else the peer has no more of it, and the sync ends on our tip. A full -/// batch of a branch below the margin starts a low-work sync on the fork with `salt`, as a full -/// batch on a genesis below the minimum does. If the connection had one, `salt` is gone, and the -/// connection ends. A peer can send our own headers as such a batch, so a batch that passes each -/// check does not take our tip away. fn chain_next( chain: &crate::chain::Chain, work_min: crate::pow::Work, @@ -994,20 +736,15 @@ fn chain_next( ) -> Result, PeerError> { match extended { crate::chain::Extended::Taken => { - // The chain had the minimum work before the batch, as `Download::Chain` and - // `Download::Branch` hold, and a batch that the chain takes gives it more work. let next = Download::on_tip(chain, work_min); Ok(full.then_some(next)) } crate::chain::Extended::Branch(branch) => { - // Only a full batch can have more of the branch after it. assert!(full); - // The chain stays, so it keeps the minimum work. assert!(chain.tip().work() >= work_min); Ok(Some(Download::Branch(Box::new(branch)))) } crate::chain::Extended::Kept => { - // The chain stays, so it keeps the minimum work. assert!(chain.tip().work() >= work_min); Ok(None) } @@ -1016,13 +753,9 @@ fn chain_next( branch_work_min, headers, } => { - // Only a full batch can have more of the branch after it. assert!(full); - // The chain stays, so it keeps the minimum work. assert!(chain.tip().work() >= work_min); let salt = salt.take().ok_or(PeerError::SecondLowWorkSync)?; - // The peer can make cheap headers on the fork for as long as it wants, so the chain - // keeps none of them until the branch shows the work of the margin. let presync = crate::headerssync::Presync::new(start, branch_work_min, clock, salt); let step = presync.receive(headers).map_err(PeerError::HeadersSync)?; Ok(Some(branch_presync_next(start, step))) @@ -1030,20 +763,6 @@ fn chain_next( } } -/// An announcement after the sync, on `chain`, which has at least `work_min`. One on the tip goes -/// on it. Returns where the next batch goes, or `None` if the batch was not full and so ended a -/// sync again. -/// -/// The peer announces headers on a header that it knows we have. After a reorg of the peer, that -/// header is below our tip. So one off our tip makes our `getheaders` due, and its answer gets the -/// headers after the highest header of our locator on the chain of the peer. Our chain looks for a -/// header below its tip only in an answer to our locator, so an announcement of headers that we -/// have, such as our tip again, is off our tip too. Only an announcement makes this `getheaders`, -/// and no `getheaders` is outstanding at an announcement. So the peer gets at most one message for -/// each message that it sends. -/// -/// `Chain::extend` checks the first `prev` before each other check, so its `NotOnTip` is the only -/// test of "off our tip". An empty announcement changes nothing, and it is not full. fn receive_announcement( chain: &mut crate::chain::Chain, work_min: crate::pow::Work, @@ -1053,34 +772,23 @@ fn receive_announcement( let full = headers.is_full(); match chain.extend(headers, clock) { Ok(()) => { - // The chain had the minimum work before the batch, as `SyncState::Synced` holds, and - // the work of a chain does not go down. The check goes also when the batch ends the - // sync, because then the chain stays at `SyncState::Synced`. let next = Download::on_tip(chain, work_min); Ok(full.then_some(next)) } - // A sync ends only on a chain with at least the minimum work, so the next batch goes on - // our tip. Err(crate::chain::ExtendError::NotOnTip) => Ok(Some(Download::on_tip(chain, work_min))), Err(error) => Err(PeerError::Extend(error)), } } -/// Puts each header that the second download of a low-work sync released on `chain`, in order, -/// through the checks of `Chain::extend`. fn extend_released( chain: &mut crate::chain::Chain, released: Vec, clock: u64, ) -> Result<(), PeerError> { - // The second download keeps at most `redownload_buffer_size` headers between two batches, and - // a batch adds at most `HEADERS_COUNT_MAX`. So this bounds the loop below. assert!( released.len() <= chain.network().redownload_buffer_size() + crate::protocol::HEADERS_COUNT_MAX ); - // The second download starts on the tip of the chain, and only it extends the chain in the - // sync. So a refusal of the first header with `NotOnTip` would be our error. if let Some(first) = released.first() { assert_eq!(first.prev, chain.tip().hash()); } @@ -1090,27 +798,18 @@ fn extend_released( Ok(()) } -/// Puts `more`, the headers that one batch of the second download of a low-work sync of a branch -/// released, after `released`, the headers that it released before, on `network`. They wait for -/// the last batch. fn keep_released( network: crate::chainparams::Network, released: &mut Vec, more: Vec, ) { - // As in `extend_released`: the second download keeps at most `redownload_buffer_size` headers - // between two batches, and a batch adds at most `HEADERS_COUNT_MAX`. assert!(more.len() <= network.redownload_buffer_size() + crate::protocol::HEADERS_COUNT_MAX); - // Each release goes on the release before it. `Chain::extend_low_work_branch` holds that the - // first one goes on the fork. if let (Some(last), Some(first)) = (released.last(), more.first()) { assert_eq!(first.prev, last.hash()); } released.extend(more); } -/// Where the next batch goes after a batch of the first download of a low-work sync of a branch -/// on `start`. fn branch_presync_next( start: crate::chain::SyncStart, step: crate::headerssync::PresyncStep, @@ -1129,7 +828,6 @@ fn branch_presync_next( } } -/// Where the next batch goes after a batch of the first download of a low-work sync on genesis. fn presync_next(step: crate::headerssync::PresyncStep) -> Download { match step { crate::headerssync::PresyncStep::More(presync) => Download::Presync(Box::new(presync)), @@ -1139,159 +837,96 @@ fn presync_next(step: crate::headerssync::PresyncStep) -> Download { } } -/// The entry point of the `machines` fuzz target. #[cfg(fuzzing)] -// Only cargo-mutants reads this attribute. Its test runs do not build this module. #[cfg_attr(false, mutants::skip)] pub(crate) mod fuzz { use crate::serialize::{Decode, Encode}; - /// The network of each frame. The machines do not read the magic, so one is enough. The network - /// of the machines comes from the script. const FRAME_NETWORK: crate::chainparams::Network = crate::chainparams::Network::Regtest; - /// The address of the peer in each `version` of a script. const PEER_ADDRESS: std::net::SocketAddr = std::net::SocketAddr::new(std::net::IpAddr::V4(std::net::Ipv4Addr::LOCALHOST), 18444); - // The models take each limit from the constant that the machines use, and the seeds hold each - // limit as a count of bytes and turns. So a new limit moves the models and not the seeds, and - // each row can still pass: `SEED_ENDS` does not see a `PING_INTERVAL` of 119 or 121 seconds. - // A new limit must rewrite the seeds at the limit. const _: () = assert!(super::PROTOCOL_VERSION_MIN == 70016); const _: () = assert!(super::MESSAGE_COUNT_MAX == 16); const _: () = assert!(super::PING_INTERVAL.as_secs() == 120); const _: () = assert!(super::PING_TIMEOUT.as_secs() == 1200); const _: () = assert!(super::HEADERS_TIMEOUT.as_secs() == 120); - /// The count of a full batch. It is a second copy of the limit in `protocol`, so a wrong value - /// of that limit makes the model and the machine disagree. const HEADERS_FULL_COUNT: usize = 2000; - /// The most headers that one script writes. A full batch costs about 7 ms and 160 KB of chain, - /// and a few bytes of a script ask for one. So this bounds the cost of a run. const SCRIPT_HEADERS_COUNT_MAX: usize = 6 * HEADERS_FULL_COUNT; - // A low-work sync gets the chain twice. The seeds need two full batches in each download, and - // then a batch that is not empty. Below this, those batches get shorter. A row fails, but a new - // end in that row hides the lost case. const _: () = assert!(SCRIPT_HEADERS_COUNT_MAX >= 4 * HEADERS_FULL_COUNT + 2); - // A low-work sync of a branch whose last batch is full, and that has at most our work, gives - // a branch that goes on. Its fork is below the margin, so at least 2,145 of our headers are - // above it. The second download needs two full batches, so we need 4,000. The first download - // then needs our 4,000 less the 144 of the margin, so the seed needs 11,856 headers. const _: () = assert!( SCRIPT_HEADERS_COUNT_MAX >= 2 * 2 * HEADERS_FULL_COUNT + (2 * HEADERS_FULL_COUNT - crate::chain::BRANCH_TIP_HEADERS_BEHIND_MAX) ); - // Below the minimum, the second download of a low-work sync on genesis is shorter than the - // first, so it gets fewer than half of the headers of a script. So it keeps at most its buffer - // size, and only its last batch releases headers on our chain. `PeerModel::receive_redownload` - // asserts this. A higher count must model the release of the other batches. A low-work sync - // of a branch keeps each header that it releases until its last batch, so its releases do not - // show. const _: () = assert!( SCRIPT_HEADERS_COUNT_MAX / 2 <= crate::chainparams::Network::Regtest.redownload_buffer_size() ); - // The seeds of branches hold these as counts of headers, as the seeds hold the limits above. const _: () = assert!(crate::chain::BRANCH_TIP_HEADERS_BEHIND_MAX == 144); const _: () = assert!(crate::chain::LOCATOR_DENSE_COUNT == 12); const _: () = assert!(crate::chainparams::Network::Regtest.commitment_period() == 275); - /// The headers above genesis in one step of the regtest minimum of a script. 16 steps are a full - /// batch, so the minimum can be inside a batch or at its end. A short batch has at most 252 - /// headers or 1,999, so a short batch on genesis reaches a minimum of at most 2 steps or 15. const SCRIPT_WORK_MIN_STEP: usize = HEADERS_FULL_COUNT / 16; const _: () = assert!(SCRIPT_WORK_MIN_STEP * 16 == HEADERS_FULL_COUNT); - /// The `bits` of each header that a script writes. They are above the limit of each other - /// network, so a script goes past its first header only on regtest. Regtest requires them at - /// each height, so no script ends at `WrongBits`. const SCRIPT_HEADER_BITS: u32 = crate::chainparams::Network::Regtest.genesis().bits; - /// The work of a header with `SCRIPT_HEADER_BITS`. A person wrote the 2. The model compares - /// the work of each tip with the machine, so another value fails each seed above genesis. const SCRIPT_HEADER_WORK: u128 = 2; - /// The `version` of each header that a script writes. It is the lowest version that regtest - /// takes at each height above genesis, so no script ends at `VersionTooLow`. A person wrote - /// the 4, so another lowest version stops the build at the asserts below. const SCRIPT_HEADER_VERSION: i32 = 4; - // The lowest version only rises with the height. So with the same bound at the first height - // above genesis and at the top height, the bound is the same at each height between them. const _: () = assert!(SCRIPT_HEADER_VERSION == crate::chainparams::Network::Regtest.version_min(1)); const _: () = assert!( SCRIPT_HEADER_VERSION == crate::chainparams::Network::Regtest.version_min(usize::MAX) ); - /// The time of a script header at `height`. Each time is one second above the time below it, - /// so it is above the times of all the headers below it, and each median of those times, also - /// on a branch. This reads no byte of the script, so the layout of the corpus stays. Regtest is - /// the only network where a script goes past its first header, so this starts from the regtest - /// genesis, and no script ends at `TimeTooOld`. A script writes each header on a header that it - /// wrote before, so the height is at most the count of headers that it wrote. The local clock - /// of a script is the time at that bound, so no script ends at `TimeTooNew`. fn script_header_time(height: usize) -> u32 { assert!((1..=SCRIPT_HEADERS_COUNT_MAX).contains(&height)); let seconds = u32::try_from(height).unwrap_or(u32::MAX); crate::chainparams::Network::Regtest.genesis().time + seconds } - /// The merkle root of each header of the branch with `tag`. A header on a header holds its - /// height, so its time, and with the root this is all that is not mined. So two headers on the - /// same header differ only when their branches differ. Branch 0 has the root of each header of - /// an old seed. fn script_merkle_root(tag: u32) -> [u8; 32] { let mut root = [0; 32]; root[..4].copy_from_slice(&tag.to_le_bytes()); root } - /// The salt of each low-work sync. The layout has no byte for it, so the layout of the corpus - /// stays. Each value is legal. - const SCRIPT_SALT: crate::headerssync::Salt = crate::headerssync::Salt { - keys: [0, 0], - offset: 0, - }; + const SCRIPT_KEYS: [u64; 2] = [0, 0]; + + const SCRIPT_OFFSET: usize = 0; + + const SCRIPT_SALT: crate::headerssync::Salt = + crate::headerssync::Salt::new(SCRIPT_KEYS, SCRIPT_OFFSET); - /// Spreads a byte over the places of a nonce. It is odd, so each byte gives another nonce. const NONCE_SPREAD: u64 = 0x0123_4567_89ab_cdef; const _: () = assert!(NONCE_SPREAD % 2 == 1); const _: () = assert!(NONCE_SPREAD != NONCE_SPREAD.swap_bytes()); - /// The bit of a nonce that a `pong` byte other than 0 flips. const fn pong_flip_bit(byte: u8) -> u8 { byte % 64 } - // Only `pong-high-bit` flips bit 63 and only `pong-low-bit` flips bit 0, and their rows do not - // hold the bit. A new layout that moves a bit keeps the end of the seed, so it must fail here - // until it rewrites the seed. const _: () = assert!(pong_flip_bit(63) == 63); const _: () = assert!(pong_flip_bit(64) == 0); - /// How a script ended. Only the tests read it, through its `Debug`. #[derive(Debug)] #[expect(dead_code)] enum ScriptEnd { - /// The bytes ended in the handshake. HandshakeOpen, HandshakeRefused(super::HandshakeError), - /// The bytes ended after the handshake. - PeerOpen { - height: usize, - synced: bool, - }, + PeerOpen { height: usize, synced: bool }, PeerRefused(super::PeerError), } - /// A seed, its bytes, and the `Debug` of its `ScriptEnd`. #[cfg(test)] macro_rules! seed { ($name:literal, $end:literal) => { @@ -1303,12 +938,6 @@ pub(crate) mod fuzz { }; } - /// Each committed seed. Each byte string is a legal script, so a seed in an old layout runs, - /// and the model and the machine agree. A new layout that moves the end of a seed fails here - /// until it also rewrites that seed and its row. - /// A new layout that keeps the end of each seed does not fail here. For example, with another - /// network order, each seed only runs another network and keeps its end. - // Without this, rustfmt stacks each row and the table is 223 lines. #[rustfmt::skip] #[cfg(test)] const SEED_ENDS: &[(&str, &[u8], &str)] = &[ @@ -1436,47 +1065,10 @@ pub(crate) mod fuzz { seed!("time-their-ping-does-not-move-ours", "PeerRefused(PingTimeout)"), ]; - /// Runs `Handshake` and `Peer` on the script in `data`, in the order of the driver: a tick - /// before each receive, and `now` never goes back. `HandshakeModel` and `PeerModel` write the - /// doc of each function a second time, and each result must be what they expect. Each error - /// ends the run, as it ends the connection. - /// - /// A script holds a network byte (`script_network_work_min`), a nonce byte for our `version`, - /// messages until the handshake ends, and then turns. A turn holds a nonce byte for the tick, a - /// message, and a byte for `now_next`. A read after the end of `data` gives 0. A message is a - /// kind byte, modulo 8, then: - /// - /// - 0: no message. - /// - 1: `version`. A byte to add to our nonce in the handshake, so 0 is our nonce, and an `i8` - /// to add to `PROTOCOL_VERSION_MIN`. - /// - 2: `verack`. - /// - 3: `ping`. A nonce byte. - /// - 4: `pong` with the nonce of our last `ping`. A byte: 0 keeps the nonce, and each other - /// byte `b` flips bit `b % 64`. - /// - 5: `headers`, each on the header below it, from the last header of the download. A count - /// byte: 253 is one above a full batch, 254 is one below it, 255 is a full batch, and each - /// other byte is the count. The script stops at `SCRIPT_HEADERS_COUNT_MAX` headers, so a - /// later batch can be shorter. Then a byte `b`: header `b - 1` has a wrong `prev`, 255 is the - /// last header, and 0 changes none. The script mines each header after it picks the `prev`, - /// so proof of work never decides between two ends on regtest. `script_header_time` gives - /// each time. On a header, the script writes the header that it wrote on it before, as a - /// peer sends its one chain. So a second download gets the headers of the first, and a batch - /// on a header of our chain starts with our headers. A kind byte `5 + 8 * (i + 1)` is a batch - /// on hash `i` of our locator, or on its last hash when `i` is past its end, so it can go on - /// a header below our tip. Its count byte and its `prev` byte come first, then a byte that - /// reads as the count byte: from that header of the batch on, the script writes a new - /// branch. Each old seed has kind byte 5, so it keeps its end. - /// - 6: `wtxidrelay`, which the handshake skips and the peer refuses. No kind is `sendaddrv2`, - /// because the peer refuses it the same way. - /// - 7: `inv` with one entry. A byte: its type, so 2 is a block. - /// - /// Then an `i8` to add to the length of the payload, so bytes come off its end or go after it. - /// The committed corpus uses this layout, so a change to the layout must rewrite the corpus. pub fn machines(data: &[u8]) { machines_run(data); } - /// Runs the script in `data`, and returns how it ended. fn machines_run(data: &[u8]) -> ScriptEnd { let mut script = Script { unread: data, @@ -1486,7 +1078,6 @@ pub(crate) mod fuzz { }; let (network, work_min, work_min_model) = script_network_work_min(script.byte()); let nonce = script.nonce(); - // The layout has no byte for it. A value from the script still shows a fixed timestamp. let timestamp = nonce.cast_signed(); let mut chain = crate::chain::Chain::new(network); let (handshake, outbound) = super::Handshake::start( @@ -1504,7 +1095,6 @@ pub(crate) mod fuzz { } } - /// The network of a script. Its genesis header starts the chain of the peer. fn script_network(byte: u8) -> crate::chainparams::Network { match byte % 4 { 0 => crate::chainparams::Network::Regtest, @@ -1514,17 +1104,6 @@ pub(crate) mod fuzz { } } - /// The network of a script, and the lowest work of a chain at the end of its sync: for the - /// machine, then for the model. Off regtest, it is the minimum of the network. A person wrote - /// each one, and each one is above the work of its genesis. Off regtest no script header - /// passes, so each sync that a script ends fails. On regtest, `byte / 4` is a count of steps of - /// `SCRIPT_WORK_MIN_STEP`, and the minimum is the work of a chain of script headers that many - /// steps above genesis. So a sync can end at it, one header below it, or one header above it. - /// With zero steps, it is the work of genesis, so each chain has it. No old seed has a first - /// byte above 3, so each old seed has zero steps, and keeps its end. - /// - /// The machine side adds the work of a script header once for each header. The model has its - /// own formula, so a wrong sum makes the two disagree. fn script_network_work_min(byte: u8) -> (crate::chainparams::Network, crate::pow::Work, u128) { let network = script_network(byte); let (work_min, work_min_model) = match network { @@ -1540,16 +1119,13 @@ pub(crate) mod fuzz { (crate::pow::chain_work_min(network), 0xb46_3ea0_a4b8) } crate::chainparams::Network::Regtest => { - // The byte divided by 4, so the loop below has at most 63 steps of headers. let step_count = byte / 4; - // Regtest genesis has the `bits` of each script header. let Some(header_work) = crate::pow::work(SCRIPT_HEADER_BITS, network) else { panic!("the script bits {SCRIPT_HEADER_BITS:#x} are not a regtest target"); }; let headers_count = usize::from(step_count) * SCRIPT_WORK_MIN_STEP; let work_min = (0..headers_count) .fold(header_work, |work, _| work.saturating_add(header_work)); - // Genesis and each script header have a work of 2. const { assert!(usize::BITS <= 64) }; let work_min_model = 2 + u128::from(step_count) * SCRIPT_WORK_MIN_STEP as u128 * 2; (work_min, work_min_model) @@ -1558,9 +1134,6 @@ pub(crate) mod fuzz { (network, work_min, work_min_model) } - /// Checks each field of `outbound`, our `version`. It claims no services and asks for no - /// transactions. The handshake compares their nonce with the nonce that it keeps, so `nonce` - /// must also be on the wire. fn machines_start_check(outbound: &super::HandshakeOutbound, timestamp: i64, nonce: u64) { let super::HandshakeOutbound::Version(payload) = outbound else { panic!("the handshake starts with {outbound:?}"); @@ -1589,15 +1162,11 @@ pub(crate) mod fuzz { assert!(!ours.relay); } - /// Gives each message of `script` to `handshake`. Returns the peer if the handshake ended - /// with one, or how the script ended. A message takes at least its kind byte, so the length - /// of the script bounds the loop. fn handshake_run<'a>( script: &mut Script, mut handshake: super::Handshake<'a>, nonce: u64, ) -> Result, ScriptEnd> { - // The handshake skips each `pong` and `headers`, so their base does not matter. let base = MessageBase { our_nonce: nonce, ping_nonce: 0, @@ -1636,8 +1205,6 @@ pub(crate) mod fuzz { Err(ScriptEnd::HandshakeOpen) } - /// Runs one turn after the other, as the driver does. Each turn takes at least one byte of - /// the script, so the length of the script bounds the loop. fn peer_run( script: &mut Script, mut peer: super::Peer<'_>, @@ -1645,7 +1212,6 @@ pub(crate) mod fuzz { work_min: u128, ) -> ScriptEnd { let mut now = std::time::Instant::now(); - // The layout has no byte for it, so the layout of the corpus stays. let clock = u64::from(script_header_time(SCRIPT_HEADERS_COUNT_MAX)); let mut model = PeerModel::new(now, network, work_min); while !script.unread.is_empty() { @@ -1657,14 +1223,12 @@ pub(crate) mod fuzz { Err(error) => return ScriptEnd::PeerRefused(error), }; peer = ticked; - // The peer skips each `version`, so its base does not matter. let base = MessageBase { our_nonce: 0, ping_nonce: model.ping_nonce, last: model.download_last(), locator_below: model.locator_below(), }; - // The wait of the driver can end with no message. if let Some(message) = script.message(&base) { peer = match peer_receive(peer, &mut model, &message, clock) { Ok(received) => received, @@ -1672,7 +1236,6 @@ pub(crate) mod fuzz { }; } now = now_next(script.byte(), now, wake); - // The chain holds only headers that the script wrote. assert!(model.height() <= script.headers_written_count); } ScriptEnd::PeerOpen { @@ -1681,8 +1244,6 @@ pub(crate) mod fuzz { } } - /// Ticks `peer`, and checks the result against `model`. Returns the peer and its wake, or the - /// error if the tick failed. fn peer_tick<'a>( peer: super::Peer<'a>, model: &mut PeerModel, @@ -1692,7 +1253,6 @@ pub(crate) mod fuzz { match (peer.tick(now, nonce), model.tick(now, nonce)) { (Ok((peer, outbound, wake)), Ok(expected)) => { assert_eq!(wake, expected.wake); - // The driver sends these, in this order. let mut outbounds = outbound.into_outbounds(); if expected.ping { match outbounds.next() { @@ -1728,8 +1288,6 @@ pub(crate) mod fuzz { } } - /// Checks that `get_headers` asks for the headers after the first hash of `locator` on the - /// chain of the peer, and for as many as a `headers` can carry. fn peer_get_headers_check( get_headers: crate::protocol::GetHeaders, locator: &[bitcoin_hashes::sha256d::Hash], @@ -1747,8 +1305,6 @@ pub(crate) mod fuzz { assert_eq!(encoded, expected); } - /// Gives `message` to `peer` at `clock`, and checks the result against `model`. Returns the - /// peer, or the error if it refused the message. fn peer_receive<'a>( peer: super::Peer<'a>, model: &mut PeerModel, @@ -1775,16 +1331,7 @@ pub(crate) mod fuzz { } } - /// The `now` of the next tick. A deadline is due at its instant, so a random time would almost - /// never test it. So each kind but the first steps relative to `wake`, the earliest deadline - /// from the last tick. `byte % 4` picks the kind, and `byte / 4` is a count of units: - /// - /// - 0: that many seconds after `now`, so a message that came before `wake`, or no time. - /// - 1: just before `wake`. - /// - 2: at `wake`. - /// - 3: that many minutes after `wake`, so a tick that came late. fn now_next(byte: u8, now: std::time::Instant, wake: std::time::Instant) -> std::time::Instant { - // `tick` asserts this. The next assert needs it for the second kind. assert!(now < wake); let unit_count = u64::from(byte / 4); let next = match byte % 4 { @@ -1793,26 +1340,19 @@ pub(crate) mod fuzz { 2 => wake, _ => wake + std::time::Duration::from_mins(unit_count), }; - // `tick` needs this for its deadlines. assert!(now <= next); next } - /// The bytes of a script that no read took yet. struct Script<'a> { unread: &'a [u8], - /// The headers that the script wrote, at most `SCRIPT_HEADERS_COUNT_MAX`. headers_written_count: usize, - /// The last header that the script wrote on each header, by the hash of that header. It - /// holds at most one entry for each header that the script wrote. written_on: std::collections::HashMap, - /// The tag of the last branch that the script started. Each new header gets it. branch_last: u32, } impl Script<'_> { - /// The next byte, or 0 after the end of the script. fn byte(&mut self) -> u8 { let (byte, rest) = self.unread.split_first().unwrap_or((&0, &[])); self.unread = rest; @@ -1823,13 +1363,10 @@ pub(crate) mod fuzz { i8::from_le_bytes([self.byte()]) } - /// One byte, spread over the places of the nonce. The same byte in each place reads the - /// same in both byte orders, and that hides a byte-order bug. fn nonce(&mut self) -> u64 { u64::from(self.byte()).wrapping_mul(NONCE_SPREAD) } - /// The next message, as the driver reads it. fn message(&mut self, base: &MessageBase) -> Option { let kind = self.byte(); let (msg_type, mut payload) = match kind % 8 { @@ -1854,7 +1391,6 @@ pub(crate) mod fuzz { let length = payload .len() .saturating_add_signed(isize::from(self.signed_byte())); - // Not zero, so a read of these bytes as a field gives a value that shows. payload.resize(length, 0xaa); Some(message_read(msg_type, &payload)) } @@ -1868,8 +1404,6 @@ pub(crate) mod fuzz { payload } - /// One entry, with its type from a byte. Its hash is not 0, so a read of the hash as a - /// type shows. fn inv_payload(&mut self) -> Vec { let mut payload = vec![1]; payload.extend_from_slice(&u32::from(self.byte()).to_le_bytes()); @@ -1887,23 +1421,16 @@ pub(crate) mod fuzz { theirs.to_le_bytes().to_vec() } - /// A batch on the header with `last_hash`, at `last_height`. Random bytes never match the - /// hash of the last header, so this builds each `prev`. Without this, each batch stops at - /// `NotOnLocator`. With `branches`, a byte picks the first header of a new branch. fn headers_payload( &mut self, (last_hash, last_height): (bitcoin_hashes::sha256d::Hash, usize), branches: bool, ) -> Vec { - // The last header is one that the script wrote, or genesis. So the heights of the - // batch are at most the count of headers that the script wrote. assert!(last_height <= self.headers_written_count); let count_asked = count_read(self.byte()); let count = count_asked.min(SCRIPT_HEADERS_COUNT_MAX - self.headers_written_count); assert!(self.headers_written_count + count <= SCRIPT_HEADERS_COUNT_MAX); - // The loop below takes its bound from this. assert!(count <= HEADERS_FULL_COUNT + 1); - // An index past the batch changes no header, so it is `None`. let wrong_prev_index = match self.byte() { 0 => None, 255 => count.checked_sub(1), @@ -1924,7 +1451,6 @@ pub(crate) mod fuzz { self.branch_last += 1; } let header = if Some(index) == wrong_prev_index { - // No batch goes on it, so the script keeps it nowhere. script_header_mined(hash_wrong(prev), height, self.branch_last) } else { match self.written_on.get(&prev) { @@ -1932,7 +1458,6 @@ pub(crate) mod fuzz { _ => { let header = script_header_mined(prev, height, self.branch_last); self.written_on.insert(prev, header); - // The script adds at most one entry for each header that it writes. assert!(self.written_on.len() <= self.headers_written_count); header } @@ -1946,8 +1471,6 @@ pub(crate) mod fuzz { } } - /// The count of a batch from `byte`: 253 is one above a full batch, 254 is one below it, 255 is - /// a full batch, and each other byte is the count. fn count_read(byte: u8) -> usize { match byte { 253 => HEADERS_FULL_COUNT + 1, @@ -1957,13 +1480,10 @@ pub(crate) mod fuzz { } } - /// The index in a batch of the header where a new branch starts, from `byte`. It reads as the - /// count byte, so 253 is past the last header of each batch, and starts no branch. fn branch_index_read(byte: u8) -> usize { count_read(byte) } - /// A script header on `prev`, at `height`, on the branch with `tag`. fn script_header_mined( prev: bitcoin_hashes::sha256d::Hash, height: usize, @@ -1979,22 +1499,14 @@ pub(crate) mod fuzz { }) } - /// What the messages of a script build on. struct MessageBase { - /// The nonce in our `version`. A `version` starts from it. our_nonce: u64, - /// The nonce of our last `ping`. A `pong` starts from it, so a `pong` can repeat. ping_nonce: u64, - /// The hash and the height of the last header of the download. A batch starts from it. last: (bitcoin_hashes::sha256d::Hash, usize), - /// The hash and the height of each other header of the locator of our next `getheaders`, - /// below `last`, in order. A batch can also start from one of them. locator_below: Vec<(bitcoin_hashes::sha256d::Hash, usize)>, } impl MessageBase { - /// The hash and the height of hash `index` of our locator, which starts with `last`, or of - /// its last hash when `index` is past its end. fn on_locator(&self, index: usize) -> (bitcoin_hashes::sha256d::Hash, usize) { let Some(below) = index.checked_sub(1) else { return self.last; @@ -2007,8 +1519,6 @@ pub(crate) mod fuzz { } } - /// `hash` with one bit of its last byte flipped, so a compare of only its start does not see - /// it. fn hash_wrong(hash: bitcoin_hashes::sha256d::Hash) -> bitcoin_hashes::sha256d::Hash { let mut bytes = hash.to_byte_array(); bytes[31] ^= 1; @@ -2017,8 +1527,6 @@ pub(crate) mod fuzz { wrong } - /// `check_payload` is the only constructor of a `Message`, so this reads a frame as the driver - /// does. fn message_read( msg_type: crate::protocol::MessageType, payload: &[u8], @@ -2039,15 +1547,12 @@ pub(crate) mod fuzz { } } - /// What `Handshake::receive` returns, by its doc. struct HandshakeModel { nonce: u64, - /// Their first `version`, once it came. theirs: Option, message_count: u32, } - /// What `Handshake::receive` returns, without the machine. #[derive(Debug)] enum HandshakeExpected { Wait, @@ -2062,7 +1567,6 @@ pub(crate) mod fuzz { ) -> Result { assert!(self.message_count < super::MESSAGE_COUNT_MAX); self.message_count += 1; - // The handshake keeps only a `version` that it accepts. if let Some(theirs) = &self.theirs { assert!(theirs.version >= super::PROTOCOL_VERSION_MIN); assert_ne!(theirs.nonce, self.nonce); @@ -2095,49 +1599,29 @@ pub(crate) mod fuzz { } } - /// What `Peer::tick` and `Peer::receive` return, by their docs. It holds deadlines and where - /// the next batch goes, not the states of the peer. So a change to those states needs a change - /// here only if it changes where a batch goes. struct PeerModel { - /// When our next `ping` is due, or when our outstanding one times out. ping_deadline: std::time::Instant, - /// The nonce of our last `ping`. No message comes before the first tick, which sends one. ping_nonce: u64, - /// The `pong` to our last `ping` has not come. ping_outstanding: bool, get_headers: GetHeadersModel, send_headers: SendHeadersModel, - /// The hash of each header of the chain, from genesis. The index of a hash is its height, - /// so the last hash is the tip. chain: Vec, network: crate::chainparams::Network, - /// The work that the chain must reach in the sync. work_min: u128, - /// No low-work sync started yet. A connection has at most one. salt_left: bool, download: DownloadModel, } - /// Where the next batch goes, as `Download` says. enum DownloadModel { - /// On the tip of the chain: `Genesis` and `Chain`. Chain, - /// A branch on the header of the chain at `fork`, below the tip, with the hash of each of - /// its headers above the fork, in order: `Branch`. Branch { fork: usize, hashes: Vec, }, - /// The first download of a low-work sync on the header of the chain at `start`, which must - /// reach `PeerModel::branch_work_min`. It holds the hash of each header that it took, in - /// order. On the tip, which is then genesis, it is `Presync`. Below the tip, it is - /// `BranchPresync`, and `start` is the fork of a branch below the margin. Presync { start: usize, hashes: Vec, }, - /// The second download: `Redownload` or `BranchRedownload`. It holds the hashes of the - /// first download, and the hash of each header that it took, in order. Redownload { start: usize, presync: Vec, @@ -2145,58 +1629,37 @@ pub(crate) mod fuzz { }, } - /// What the chain does with a batch that passed each check, as `crate::chain::Extended` says. - /// `crate::chain::Extended` gives `Branch` and `BelowMargin` only after a full batch. Here they - /// come after a batch of each length, and `PeerModel::chain_next` reads one after a batch that - /// is not full as `Kept`. enum ExtendedModel { Taken, Kept, - /// The branch on the header of the chain at `fork` goes on after a full batch, with the - /// hash of each of its headers above the fork. Branch { fork: usize, hashes: Vec, }, - /// After a full batch, a low-work sync on the header of the chain at `fork` can get the - /// branch. Its first download starts with the batch, whose hashes these are. BelowMargin { fork: usize, hashes: Vec, }, } - /// Why the model refuses a script header. #[derive(Debug)] enum HeaderFault { - /// The `prev` of a header is not the hash of the header below it. Prev, - /// Off regtest, no script header has proof of work. ProofOfWork, } - /// Where our `getheaders` is. enum GetHeadersModel { - /// The next tick sends one. Due, - /// One is outstanding, and it times out at this instant. Outstanding(std::time::Instant), - /// The sync ended. None goes until a full announcement, an announcement off the tip or an - /// `inv` of a block. Ended, } - /// Where our `sendheaders` is. #[derive(PartialEq)] enum SendHeadersModel { - /// It did not go yet. Unsent, - /// It went. Sent, } - /// What `Peer::tick` returns, without the peer. The tick nonce and `PeerModel::download_last` - /// give the contents of what it sends. #[derive(Debug)] struct TickExpected { ping: bool, @@ -2205,7 +1668,6 @@ pub(crate) mod fuzz { wake: std::time::Instant, } - /// What `Peer::receive` returns, without the peer. `PeerModel` holds the tip for `Synced`. #[derive(Debug)] enum ReceivedExpected { NoReply, @@ -2214,8 +1676,6 @@ pub(crate) mod fuzz { } impl PeerModel { - /// The model of a new peer on the genesis header of `network`, whose sync must reach - /// `work_min`. Its first tick is at `now`. fn new( now: std::time::Instant, network: crate::chainparams::Network, @@ -2235,13 +1695,10 @@ pub(crate) mod fuzz { } } - /// The hash of the tip of the chain. fn tip(&self) -> bitcoin_hashes::sha256d::Hash { self.chain[self.height()] } - /// The hash and the height of the last header of the download. Our `getheaders` goes from - /// it, and the next batch goes on it. fn download_last(&self) -> (bitcoin_hashes::sha256d::Hash, usize) { let (start, hashes) = match &self.download { DownloadModel::Chain => return (self.tip(), self.height()), @@ -2249,14 +1706,11 @@ pub(crate) mod fuzz { DownloadModel::Presync { start, hashes, .. } => (*start, hashes), DownloadModel::Redownload { start, buffer, .. } => (*start, buffer), }; - // The chain stays until the download ends, so its start is still a header of it. assert!(start <= self.height()); let last = hashes.last().copied().unwrap_or(self.chain[start]); (last, start + hashes.len()) } - /// The heights of the locator of the chain: the tip and the 11 headers below it, then a - /// step down that doubles each time, then genesis. fn locator_heights(&self) -> Vec { let mut heights = Vec::new(); let mut height = self.height(); @@ -2267,8 +1721,6 @@ pub(crate) mod fuzz { break; } height = height.saturating_sub(step); - // The step doubles after the step down from the 11th hash, so the 12th hash is - // still one height below the 11th. if heights.len() >= crate::chain::LOCATOR_DENSE_COUNT - 1 { step *= 2; } @@ -2276,10 +1728,6 @@ pub(crate) mod fuzz { heights } - /// The hash and the height of each header of the locator of our `getheaders` below its - /// first, the last header of the download. In a download that is not on the tip, the - /// locator has only that header. Else it is the locator of the chain, whose first height - /// is the tip. fn locator_below(&self) -> Vec<(bitcoin_hashes::sha256d::Hash, usize)> { if !matches!(self.download, DownloadModel::Chain) { return Vec::new(); @@ -2291,7 +1739,6 @@ pub(crate) mod fuzz { .collect() } - /// The locator of our `getheaders`. fn locator(&self) -> Vec { std::iter::once(self.download_last()) .chain(self.locator_below()) @@ -2308,7 +1755,6 @@ pub(crate) mod fuzz { now: std::time::Instant, nonce: u64, ) -> Result { - // The `ping` is checked first, as the doc of `Peer::tick` says. let ping = if now < self.ping_deadline { false } else if self.ping_outstanding { @@ -2323,7 +1769,6 @@ pub(crate) mod fuzz { GetHeadersModel::Ended => (false, None), }; - // Our `sendheaders` goes in the first tick after the sync ended. let send_headers = self.send_headers == SendHeadersModel::Unsent && matches!(self.get_headers, GetHeadersModel::Ended); @@ -2365,7 +1810,6 @@ pub(crate) mod fuzz { Err(super::PeerError::PongNonce) } else { self.ping_outstanding = false; - // The deadline was `sent + PING_TIMEOUT`. It is now `sent + PING_INTERVAL`. self.ping_deadline -= super::PING_TIMEOUT - super::PING_INTERVAL; Ok(ReceivedExpected::NoReply) } @@ -2373,7 +1817,6 @@ pub(crate) mod fuzz { self.receive_headers(message) } else if msg_type == crate::protocol::INV { let has_block = message_inv_has_block(message).map_err(super::PeerError::Inv)?; - // After the sync, the next batch goes on the tip of the chain. if has_block && matches!(self.get_headers, GetHeadersModel::Ended) { assert!(matches!(self.download, DownloadModel::Chain)); self.get_headers = GetHeadersModel::Due; @@ -2396,8 +1839,6 @@ pub(crate) mod fuzz { .map_err(super::PeerError::Headers)? .into_vec(); assert!(headers.len() <= HEADERS_FULL_COUNT); - // After the sync, each batch is an announcement. One off the tip makes our - // `getheaders` due from the tip, which has the minimum work. Each other one goes on it. match self.get_headers { GetHeadersModel::Outstanding(_) => {} GetHeadersModel::Ended => { @@ -2413,12 +1854,9 @@ pub(crate) mod fuzz { GetHeadersModel::Due => return Err(super::PeerError::UnsolicitedHeaders), } let full = headers.len() == HEADERS_FULL_COUNT; - // An error ends the run, so the download does not need to come back. let download = std::mem::replace(&mut self.download, DownloadModel::Chain); let next = match download { DownloadModel::Chain if full && self.work() < self.work_min => { - // Only genesis is below the minimum when a full batch comes: each other chain - // got there in a sync that reached it. assert_eq!(self.height(), 0); let hashes = script_hashes(self.network, self.tip(), &headers).map_err(sync_error)?; @@ -2429,7 +1867,6 @@ pub(crate) mod fuzz { self.chain_next(extended, full)? } DownloadModel::Branch { fork, hashes } => { - // An empty batch ends the branch. let extended = match headers.first() { None => ExtendedModel::Kept, Some(_) => { @@ -2466,8 +1903,6 @@ pub(crate) mod fuzz { } } - /// The chain takes the batch on its tip, or on the header of its locator that the first - /// `prev` names, with `extend_above`. Else the batch is not on the locator. fn extend_on_locator( &mut self, headers: &[crate::block::BlockHeader], @@ -2495,12 +1930,6 @@ pub(crate) mod fuzz { Ok(self.extend_above(fork, Vec::new(), batch)) } - /// The chain goes on with the branch on the header at `base` whose headers have `branch`, - /// and with `batch`, the hashes of headers that passed each check on its last header. With - /// no header of the branch yet, the batch can start with our headers, and the fork is the - /// last of these, or `base`. The chain takes a branch with more work than ours, and else - /// the branch goes on. Below the margin, a batch with none of our headers can go to a - /// low-work sync from the fork, and else the branch has no header. fn extend_above( &mut self, base: usize, @@ -2535,7 +1964,6 @@ pub(crate) mod fuzz { hashes.extend_from_slice(rest); let branch_work = self.work_at(fork + hashes.len()); if branch_work < self.branch_work_min() { - // A branch with a header of its own passed the margin, and its work only rises. assert_eq!(branch_count, 0); return if shared == 0 { ExtendedModel::BelowMargin { fork, hashes } @@ -2554,19 +1982,12 @@ pub(crate) mod fuzz { ExtendedModel::Taken } - /// The lowest work of the chain of a branch from genesis that goes on: our work less the - /// work of 144 script headers, or the minimum work if that is higher. A low-work sync must - /// reach it. On genesis, which is below the minimum, it is the minimum. The chain stays - /// until the sync ends, so it stays too. fn branch_work_min(&self) -> u128 { const { assert!(usize::BITS <= 64) }; let behind = SCRIPT_HEADER_WORK * crate::chain::BRANCH_TIP_HEADERS_BEHIND_MAX as u128; self.work().saturating_sub(behind).max(self.work_min) } - /// Where the next batch goes after the chain did `extended` with a batch that was `full`, - /// or with the headers of a low-work sync whose last batch was `full`. After a batch that - /// is not full, the peer has no more of a branch, so the chain keeps its tip. fn chain_next( &mut self, extended: ExtendedModel, @@ -2585,8 +2006,6 @@ pub(crate) mod fuzz { } } - /// A low-work sync on the header at `start` starts, and its first download takes `batch`, - /// the hashes of a batch that was `full`. A connection has at most one. fn presync_start( &mut self, start: usize, @@ -2597,15 +2016,10 @@ pub(crate) mod fuzz { return Err(super::PeerError::SecondLowWorkSync); } self.salt_left = false; - // The sync starts below its minimum, so it gets at least one header. assert!(self.work_at(start) < self.branch_work_min()); self.receive_presync(start, Vec::new(), batch, full) } - /// The first download takes `batch` after `hashes`. When the work reaches the minimum, - /// the second download is due on the start. Else a full batch makes the next one due, and a - /// batch that is not full fails. The clock of a script is far after the time of genesis, so - /// no script header is above the height bound. fn receive_presync( &self, start: usize, @@ -2629,13 +2043,6 @@ pub(crate) mod fuzz { } } - /// The second download takes the batch after `buffer`, header by header. Below the - /// minimum, a header at the height of a commitment must have the salted bit of the header - /// of the first download at that height. When the work reaches the minimum, the download - /// ends. On genesis, the chain takes each header of the download, and then the sync goes - /// on from the tip after a full batch, or ends. On a fork, the headers go on it with - /// `extend_above`. Else a full batch makes the next one due, and a batch that is not full - /// fails. fn receive_redownload( &mut self, start: usize, @@ -2643,7 +2050,6 @@ pub(crate) mod fuzz { mut buffer: Vec, headers: &[crate::block::BlockHeader], ) -> Result, super::PeerError> { - // The chain takes the headers only after the loop, so this stays in it. let work_min = self.branch_work_min(); let period = self.network.commitment_period(); let mut last = buffer.last().copied().unwrap_or(self.chain[start]); @@ -2652,10 +2058,8 @@ pub(crate) mod fuzz { buffer.push(hash); let height = start + buffer.len(); let below_minimum = self.work_at(height) < work_min; - let at_commitment = height % period == SCRIPT_SALT.offset % period; + let at_commitment = height % period == SCRIPT_OFFSET % period; if below_minimum && at_commitment { - // Each header of the second download has the work of each header of the - // first, so below the minimum the first download has a header at each height. let Some(first) = presync.get(buffer.len() - 1) else { panic!("the first download has no header at {height}"); }; @@ -2675,13 +2079,9 @@ pub(crate) mod fuzz { return Ok(full.then_some(DownloadModel::Chain)); } let extended = self.extend_above(start, Vec::new(), buffer); - // The headers reach the lowest work of a branch that goes on. assert!(!matches!(extended, ExtendedModel::BelowMargin { .. })); self.chain_next(extended, full) } else if full { - // Below the minimum, the second download is not longer than the first, so it has - // at most half of the headers of a script, on genesis or on a fork. - // `SCRIPT_HEADERS_COUNT_MAX` says why the batch releases no header on our chain. assert!(buffer.len() <= self.network.redownload_buffer_size()); Ok(Some(DownloadModel::Redownload { start, @@ -2695,20 +2095,14 @@ pub(crate) mod fuzz { } } - /// The height of the tip of the chain. fn height(&self) -> usize { self.chain.len() - 1 } - /// The work of the chain. fn work(&self) -> u128 { self.work_at(self.height()) } - /// The work of a chain of script headers to `height`. A person wrote the work of each - /// genesis. Each script header has the regtest limit, whose work is `SCRIPT_HEADER_WORK`, - /// and off regtest no script header passes. A height has at most 64 bits, so the work fits - /// a `u128` with no overflow. fn work_at(&self, height: usize) -> u128 { let genesis_work: u128 = match self.network { crate::chainparams::Network::Mainnet | crate::chainparams::Network::Testnet4 => { @@ -2722,10 +2116,6 @@ pub(crate) mod fuzz { } } - /// The hash of `header`, a script header, on the header with `below`. It fails at its `prev` - /// first, then at its proof of work. A script mines each header for regtest, and - /// `SCRIPT_HEADER_BITS` are above each other limit. So only regtest takes what a script - /// writes. A new script byte that writes other headers fails here, and must change this model. fn script_hash( network: crate::chainparams::Network, below: bitcoin_hashes::sha256d::Hash, @@ -2743,7 +2133,6 @@ pub(crate) mod fuzz { Ok(header.hash()) } - /// The hash of each of `headers`, each on the header below it, the first on `below_first`. fn script_hashes( network: crate::chainparams::Network, below_first: bitcoin_hashes::sha256d::Hash, @@ -2757,16 +2146,12 @@ pub(crate) mod fuzz { Ok(hashes) } - /// The salted bit that a low-work sync keeps of the header with `hash`: the SipHash of the - /// hash with the keys of `SCRIPT_SALT` is even. fn script_commitment(hash: bitcoin_hashes::sha256d::Hash) -> bool { - let [key_0, key_1] = SCRIPT_SALT.keys; + let [key_0, key_1] = SCRIPT_KEYS; bitcoin_hashes::siphash24::Hash::hash_to_u64_with_keys(key_0, key_1, hash.as_byte_array()) .is_multiple_of(2) } - /// The error of the chain that refuses a header. A batch that is not on the locator fails - /// before any header does. fn extend_error(fault: HeaderFault) -> super::PeerError { super::PeerError::Extend(match fault { HeaderFault::Prev => crate::chain::ExtendError::NotContinuous, @@ -2774,8 +2159,6 @@ pub(crate) mod fuzz { }) } - /// The error of a download of a low-work sync that refuses a header. It has no `NotOnLocator`: - /// the first header goes on the last header of the download. fn sync_error(fault: HeaderFault) -> super::PeerError { super::PeerError::HeadersSync(match fault { HeaderFault::Prev => crate::headerssync::HeadersSyncError::NotContinuous, @@ -2783,7 +2166,6 @@ pub(crate) mod fuzz { }) } - /// The first 8 bytes of the payload, little-endian. Each byte after them is ignored. fn message_nonce(message: &crate::transport::Message) -> Result { match message.payload().first_chunk() { Some(nonce) => Ok(u64::from_le_bytes(*nonce)), @@ -2791,9 +2173,6 @@ pub(crate) mod fuzz { } } - /// Whether the `inv` in `message` has an entry of a block. The count comes first, so a count - /// above the limit fails before the length of the entries does. Each entry is 4 bytes of type - /// and 32 of hash. fn message_inv_has_block( message: &crate::transport::Message, ) -> Result { @@ -2815,9 +2194,6 @@ pub(crate) mod fuzz { #[cfg(test)] mod tests { - /// A row with no seed stops the build, so only this sees a new seed. It reads the - /// directory, so it also fails on the new inputs of a random run. Only tracked files - /// reach the `elo-fuzz` gate. #[test] fn each_seed_has_a_row() { let directory = concat!(env!("CARGO_MANIFEST_DIR"), "/fuzz/corpus/machines"); @@ -2829,7 +2205,6 @@ pub(crate) mod fuzz { assert!(no_row.is_empty(), "seeds with no row: {no_row:?}"); } - /// This prints each wrong row, because a new layout moves the ends of many seeds. #[test] fn each_seed_ends_as_its_row_says() { let wrong: Vec<_> = super::SEED_ENDS @@ -2848,7 +2223,6 @@ pub(crate) mod fuzz { mod tests { use crate::serialize::Decode; - /// The message in a regtest frame, as the driver reads it. fn message(frame: &[u8]) -> crate::transport::Message { let (header, payload) = frame.split_first_chunk().unwrap(); let header = @@ -2860,7 +2234,6 @@ mod tests { message(&crate::fixtures::hex(frame)) } - /// A `version` with Core's payload after `change`. fn version_message(change: impl FnOnce(&mut Vec)) -> crate::transport::Message { let mut payload = crate::fixtures::version_payload(); change(&mut payload); @@ -2871,7 +2244,6 @@ mod tests { )) } - /// A `ping` with Core's payload after `change`. fn ping_message(change: impl FnOnce(&mut Vec)) -> crate::transport::Message { let mut payload = crate::fixtures::hex(crate::fixtures::PING_FRAME) .split_off(crate::transport::MESSAGE_HEADER_SIZE); @@ -2883,7 +2255,6 @@ mod tests { )) } - /// A `pong` with `payload`. fn pong_message(payload: &[u8]) -> crate::transport::Message { message(&crate::transport::encode( crate::chainparams::Network::Regtest, @@ -2892,12 +2263,10 @@ mod tests { )) } - /// A `pong` with `nonce`. fn pong(nonce: u64) -> crate::transport::Message { pong_message(&nonce.to_le_bytes()) } - /// A `headers` with `payload`. fn headers_payload_message(payload: &[u8]) -> crate::transport::Message { message(&crate::transport::encode( crate::chainparams::Network::Regtest, @@ -2906,12 +2275,10 @@ mod tests { )) } - /// An `inv` with an entry of each type in `types`. fn inv_message(types: &[u32]) -> crate::transport::Message { inv_payload_message(&crate::fixtures::inv_payload(types)) } - /// An `inv` with `payload`. fn inv_payload_message(payload: &[u8]) -> crate::transport::Message { message(&crate::transport::encode( crate::chainparams::Network::Regtest, @@ -2920,12 +2287,10 @@ mod tests { )) } - /// A `headers` with `headers`, each with a transaction count of 0. fn headers_message(headers: &[crate::block::BlockHeader]) -> crate::transport::Message { headers_payload_message(&crate::fixtures::headers_payload_with(headers)) } - /// The tip of a second regtest chain, after `headers`, in batches of 2,000. fn tip_after(headers: &[crate::block::BlockHeader]) -> crate::chain::Tip { let mut chain = crate::chain::Chain::new(crate::chainparams::Network::Regtest); for batch in headers.chunks(2_000) { @@ -2939,7 +2304,6 @@ mod tests { chain.tip() } - /// The peer after the first tick at `now` of a regtest peer whose sync must reach `work_min`. fn asked_with( chain: &mut crate::chain::Chain, work_min: crate::pow::Work, @@ -2949,8 +2313,6 @@ mod tests { asked_from(peer_with(handshake), now, 7) } - /// `peer` takes `headers` with no reply, and then a tick at `now` sends our next - /// `getheaders`. Returns the peer, and the hash that the `getheaders` asks after. fn batch_then_tick<'a>( peer: super::Peer<'a>, headers: &[crate::block::BlockHeader], @@ -2971,14 +2333,10 @@ mod tests { } } - /// The `getheaders` of a download of a low-work sync or of a branch, which asks for the headers - /// after `header` only. fn get_headers_after(header: &crate::block::BlockHeader) -> crate::protocol::GetHeaders { crate::protocol::GetHeaders::new(vec![header.hash()]) } - /// The `getheaders` of a regtest chain of `headers` on genesis, with the locator of that chain. - /// The tests of `chain` hold the heights of a locator. fn get_headers_on(headers: &[crate::block::BlockHeader]) -> crate::protocol::GetHeaders { let mut chain = regtest(); for batch in headers.chunks(crate::protocol::HEADERS_COUNT_MAX) { @@ -2992,19 +2350,15 @@ mod tests { crate::protocol::GetHeaders::new(chain.locator()) } - /// A chain with only the regtest genesis. fn regtest() -> crate::chain::Chain { crate::chain::Chain::new(crate::chainparams::Network::Regtest) } - /// The handshake with a peer on the network of `chain`, with the minimum work of the network. - /// The machines do not read the magic, so the frames of the tests can stay on regtest. fn start(chain: &mut crate::chain::Chain) -> super::Handshake<'_> { let work_min = crate::pow::chain_work_min(chain.network()); start_with(chain, work_min) } - /// `start`, with a sync that must reach `work_min`. fn start_with( chain: &mut crate::chain::Chain, work_min: crate::pow::Work, @@ -3029,12 +2383,10 @@ mod tests { } } - /// The peer as the handshake makes it on `chain`, after Core's `version` and `verack`. fn peer(chain: &mut crate::chain::Chain) -> super::Peer<'_> { peer_with(start(chain)) } - /// The peer that `handshake` makes after Core's `version` and `verack`. fn peer_with(handshake: super::Handshake<'_>) -> super::Peer<'_> { let (handshake, _) = reply(handshake.receive(&core_message(crate::fixtures::VERSION_FRAME))); @@ -3044,8 +2396,6 @@ mod tests { } } - /// The peer after its first tick at `now`, which sent our `ping` with `nonce` and our - /// `getheaders`. fn asked( chain: &mut crate::chain::Chain, now: std::time::Instant, @@ -3054,7 +2404,6 @@ mod tests { asked_from(peer(chain), now, nonce) } - /// `peer` after its first tick at `now`, as in `asked`. fn asked_from(peer: super::Peer<'_>, now: std::time::Instant, nonce: u64) -> super::Peer<'_> { match peer.tick(now, nonce) { Ok(( @@ -3070,7 +2419,6 @@ mod tests { } } - /// The first tick of `peer` at `now`. Returns the peer and our `getheaders`. fn first_get_headers( peer: super::Peer<'_>, now: std::time::Instant, @@ -3089,8 +2437,6 @@ mod tests { } } - /// The peer after `asked`, after an empty `headers` that ended the sync, and after a tick at - /// `now` that sent only our `sendheaders`. So only our `ping` with `nonce` is outstanding. fn pinged( chain: &mut crate::chain::Chain, now: std::time::Instant, @@ -3111,7 +2457,6 @@ mod tests { } } - /// `peer` takes `headers`, which end a sync. Returns the peer. fn synced<'a>(peer: super::Peer<'a>, headers: &[crate::block::BlockHeader]) -> super::Peer<'a> { match peer.receive(&headers_message(headers), crate::fixtures::CLOCK) { Ok((peer, super::Received::Synced(_))) => peer, @@ -3119,7 +2464,6 @@ mod tests { } } - /// A tick at `now` that sends nothing. Returns the peer and when to tick next. fn idle( peer: super::Peer<'_>, now: std::time::Instant, @@ -3138,7 +2482,6 @@ mod tests { } } - /// A message that the peer accepts with no reply. fn accept<'a>(peer: super::Peer<'a>, message: &crate::transport::Message) -> super::Peer<'a> { match peer.receive(message, crate::fixtures::CLOCK) { Ok((peer, super::Received::NoReply)) => peer, @@ -3148,12 +2491,7 @@ mod tests { const NANOSECOND: std::time::Duration = std::time::Duration::from_nanos(1); - /// The salt of each test. A low-work sync passes or fails the same with each salt, when the - /// peer sends the same chain twice. - const SALT: crate::headerssync::Salt = crate::headerssync::Salt { - keys: [1, 2], - offset: 3, - }; + const SALT: crate::headerssync::Salt = crate::headerssync::Salt::new([1, 2], 3); #[test] fn handshake_skips_until_their_version_and_then_until_their_verack() { @@ -3167,8 +2505,6 @@ mod tests { "{outbound:?}" ); - // A peer may send `wtxidrelay` and `sendaddrv2` before its `verack`. A second `version` is - // skipped without a decode, so an empty payload passes. for message in [ core_message(crate::fixtures::WTXIDRELAY_FRAME), core_message(crate::fixtures::SENDADDRV2_FRAME), @@ -3187,9 +2523,6 @@ mod tests { #[test] fn peer_without_its_verack_in_message_count_max_is_too_many_messages() { - // The peer sends `MESSAGE_COUNT_MAX` messages: their `version`, `wtxidrelay` frames - // and a last one. A `verack` as the last completes the handshake. One more - // `wtxidrelay` in its place is refused. let wtxidrelay = core_message(crate::fixtures::WTXIDRELAY_FRAME); fn before_the_last<'a>( chain: &'a mut crate::chain::Chain, @@ -3238,7 +2571,6 @@ mod tests { #[test] fn their_version_with_our_nonce_is_self_connection() { - // A socket that is connected to itself reads our `version` back. let peer = std::net::SocketAddr::from(([127, 0, 0, 1], 18444)); let mut chain = regtest(); let (handshake, outbound) = super::Handshake::start( @@ -3323,7 +2655,6 @@ mod tests { #[test] fn their_ping_gets_a_pong_while_our_ping_is_outstanding() { let mut chain = regtest(); - // Their `ping` does not touch ours: it still times out at `PING_TIMEOUT`. let start = std::time::Instant::now(); let outbound = pinged(&mut chain, start, 7).receive( &core_message(crate::fixtures::PING_FRAME), @@ -3356,14 +2687,12 @@ mod tests { ), "{outbounds:?}" ); - // The headers timeout comes before the ping timeout. assert_eq!(wake, start + super::HEADERS_TIMEOUT); } #[test] fn no_second_ping_while_one_is_outstanding() { let mut chain = regtest(); - // `PING_INTERVAL` after the send, a `ping` is due only if its `pong` came. let start = std::time::Instant::now(); let (_, wake) = idle(pinged(&mut chain, start, 7), start + super::PING_INTERVAL); assert_eq!(wake, start + super::PING_TIMEOUT); @@ -3372,7 +2701,6 @@ mod tests { #[test] fn next_ping_is_due_ping_interval_after_the_last_ping_went() { let mut chain = regtest(); - // The `pong` came at once: the next `ping` waits until `PING_INTERVAL` after ours went. let start = std::time::Instant::now(); let due = start + super::PING_INTERVAL; let peer = accept(pinged(&mut chain, start, 7), &pong(7)); @@ -3393,7 +2721,6 @@ mod tests { }; assert_eq!(wake, due + super::PING_TIMEOUT); - // The `pong` came after `PING_INTERVAL`: the next `ping` is due at once. let late = due + std::time::Duration::from_mins(1); let (peer, _) = idle(pinged(&mut chain, start, 7), late); let ticked = accept(peer, &pong(7)).tick(late, 8); @@ -3431,7 +2758,6 @@ mod tests { fn their_pong_needs_a_nonce_and_may_have_bytes_after_it() { let mut chain = regtest(); let start = std::time::Instant::now(); - // The payload is checked first, also when no `ping` is outstanding. let short = pong_message(&7_u64.to_le_bytes()[..size_of::() - 1]); for peer in [peer(&mut regtest()), pinged(&mut chain, start, 7)] { assert_eq!( @@ -3450,7 +2776,6 @@ mod tests { #[test] fn pong_without_our_ping_is_unsolicited_pong() { let mut chain = regtest(); - // Before our first `ping`, and after the `pong` to our last one. let start = std::time::Instant::now(); let answered = accept(pinged(&mut chain, start, 7), &pong(7)); for peer in [peer(&mut regtest()), answered] { @@ -3476,9 +2801,6 @@ mod tests { #[test] fn peer_skips_every_message_but_ping_pong_and_headers() { let mut chain = regtest(); - // Core sends `sendcmpct` and `feefilter` after the handshake, and a block `inv` for each - // new tip. elo answers no `getheaders`. The messages of the handshake are skipped too. A - // `version` is skipped without a decode, so an empty payload passes. for message in [ core_message(crate::fixtures::SENDCMPCT_FRAME), core_message(crate::fixtures::FEEFILTER_FRAME), @@ -3498,7 +2820,6 @@ mod tests { #[test] fn peer_refuses_wtxidrelay_and_sendaddrv2() { - // The handshake skips both. Only after their `verack` is each one an error. let mut chain = regtest(); for (frame, error) in [ ( @@ -3524,7 +2845,6 @@ mod tests { let headers = crate::fixtures::headers_on_genesis(2000); let peer = accept(asked(&mut chain, start, 7), &headers_message(&headers)); - // The headers timeout starts again with the new `getheaders`. let later = start + std::time::Duration::from_mins(1); let ticked = peer.tick(later, 8); let Ok(( @@ -3559,7 +2879,6 @@ mod tests { #[test] fn empty_batch_ends_the_sync_at_our_tip() { let mut chain = regtest(); - // The empty batch comes after a full batch, so our tip is not genesis. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(2000); let peer = accept(asked(&mut chain, start, 7), &headers_message(&headers)); @@ -3577,8 +2896,6 @@ mod tests { #[test] fn next_handshake_on_the_same_chain_syncs_from_its_tip() { - // The first sync ends with 3 headers on genesis. Then the peer is gone, as after the end - // of its connection, and the chain keeps the headers. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(3); let mut chain = regtest(); @@ -3591,7 +2908,6 @@ mod tests { ); } - // The chain has exactly the minimum, so the handshake keeps it. let work_min = chain.tip().work(); let peer = peer_with(start_with(&mut chain, work_min)); let (peer, get_headers) = first_get_headers(peer, start); @@ -3605,7 +2921,6 @@ mod tests { #[test] fn handshake_on_a_chain_below_the_minimum_starts_it_again_from_genesis() { - // No sync proved these headers: a peer can make them cheaply. let headers = crate::fixtures::headers_on_genesis(3); let mut chain = regtest(); chain @@ -3623,10 +2938,6 @@ mod tests { #[test] fn answer_on_a_header_below_our_tip_with_no_more_work_ends_the_sync_on_our_tip() { - // Our tip is block 3. A replay of our block 1 is on genesis, and our blocks 2 and 3 are on - // block 1, so each has less work than our chain or the same. A branch of 2 on block 1 has - // the same work, and the branch that came first stays. Each one ends the sync on our tip, - // and keeps the chain. let headers = crate::fixtures::headers_on_genesis(3); let branch = crate::fixtures::branch_on(&headers[0], 2); for batch in [&headers[..1], &headers[1..], &branch[..]] { @@ -3648,7 +2959,6 @@ mod tests { #[test] fn answer_with_a_branch_of_more_work_takes_the_place_of_our_branch() { - // Our tip is block 3. A branch of 3 on block 1 has more work than our blocks 2 and 3. let headers = crate::fixtures::headers_on_genesis(3); let branch = crate::fixtures::branch_on(&headers[0], 3); let mut chain = regtest(); @@ -3669,7 +2979,6 @@ mod tests { #[test] fn full_answer_with_a_branch_of_more_work_makes_the_next_getheaders_from_its_tip() { - // Our tip is block 3, and the full batch is a branch on genesis. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(3); let branch = @@ -3687,8 +2996,6 @@ mod tests { #[test] fn full_answer_of_our_headers_below_our_tip_makes_the_next_getheaders_from_its_last_header() { - // Our tip is block 2,001. A replay of our first 2,000 blocks is on genesis, so the peer can - // have a branch after block 2,000, and the next batch goes on it. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(2_001); let mut chain = regtest(); @@ -3701,15 +3008,6 @@ mod tests { assert_eq!(chain.tip(), tip_after(&headers)); } - /// Our chain of 2,200 blocks, a branch of `count` on block 50, and the peer after the answers - /// of the low-work sync of that branch, up to the last one. The answer to our locator is on - /// genesis: our first 50 blocks, then 1,950 of the branch. That is not a full batch of the - /// branch, so the next batch goes on block 50, and it is a full batch with less work than our - /// 2,150 blocks above block 50 by more than 144. So a low-work sync of the branch starts on - /// block 50, and its minimum is the work of 2,057 blocks: genesis, our first 50 blocks and 2,006 - /// of the branch. Each batch of the sync makes the next `getheaders` ask after its last header, - /// and the second download asks after block 50 first. Our chain stays until the last batch. - /// Each tick is at `start`. fn low_work_sync_on_block_50( chain: &mut crate::chain::Chain, count: usize, @@ -3742,8 +3040,6 @@ mod tests { #[test] fn low_work_sync_of_a_branch_below_the_margin_takes_it_only_with_more_work() { - // The branch has 2,300 or 2,100 blocks on block 50, so its chain has 2,350 blocks or 2,150, - // and ours has 2,200. The last batch of the sync is not full, so the sync ends. for (count, taken) in [(2_300, true), (2_100, false)] { let mut chain = regtest(); let (peer, theirs) = @@ -3760,11 +3056,6 @@ mod tests { #[test] fn low_work_sync_of_a_branch_keeps_the_headers_that_its_second_download_releases() { - // Our tip is block 9,500, and the branch has 9,600 on genesis. Its first batch is below the - // margin, so a low-work sync starts on genesis, and its minimum is the work of 9,357 - // blocks: genesis and 9,356 of the branch. Each download gets 4 full batches and then 1,600. - // The second download holds 7,017 headers, so its fourth batch releases 983. The chain - // takes the branch after the last batch, with each header that the download released. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(9_500); let branch = @@ -3799,9 +3090,6 @@ mod tests { #[test] fn second_low_work_sync_in_one_connection_ends_it() { - // The sync keeps our chain against the branch of 2,100 on block 50. Then the peer announces - // the last header of the branch, which is off our tip, so our `getheaders` with our locator - // is due. Its answer starts the sync of the branch again, and the salt is gone. let start = std::time::Instant::now(); let mut chain = regtest(); let (peer, theirs) = low_work_sync_on_block_50(&mut chain, 2_100, start); @@ -3828,10 +3116,6 @@ mod tests { #[test] fn first_batch_on_genesis_that_starts_no_low_work_sync_keeps_the_salt_for_a_branch() { - // The minimum is the work of 2 blocks, and the first batch of 1,000 is not full, so our - // chain takes it with no low-work sync. A full announcement takes our chain to block 3,000. - // The answer to our locator is a full batch of a branch on genesis, below the margin, so a - // low-work sync of the branch starts with the salt. let start = std::time::Instant::now(); let mut chain = regtest(); let headers = crate::fixtures::headers_on_genesis(3_000); @@ -3855,8 +3139,6 @@ mod tests { #[test] fn branch_over_two_batches_with_more_work_takes_the_place_of_our_chain() { - // Our tip is block 2,100. A branch of 2,200 on genesis comes as a full batch of 2,000, - // which has less work than our chain, then a batch of 200 on its last header. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(2_100); let branch = @@ -3877,14 +3159,9 @@ mod tests { #[test] fn refused_answer_keeps_the_chain() { - // A header on genesis with no proof of work, a batch on a header that is not in our - // locator, and a break in a batch on our tip. Our tip is block 14, so the locator has - // blocks 14 down to 3, then 1, then genesis. let headers = crate::fixtures::headers_on_genesis(14); let on_tip = crate::fixtures::headers_on(&headers[13], 1); let off_locator = crate::fixtures::branch_on(&headers[1], 20); - // A top byte of 0x80 or more is above each regtest target. The top byte of a hash is its - // last byte in wire order. let mut unproven = headers[0]; unproven.nonce = (0..=u32::MAX) .find(|nonce| { @@ -3920,10 +3197,6 @@ mod tests { #[test] fn announcement_off_our_tip_after_the_sync_makes_the_next_tick_send_getheaders_from_our_tip() { - // Our tip is block 1. The announcements: block 1 again, another block on genesis, and - // block 3, on block 2, which our chain does not have. An announcement does not answer our - // locator, so one on genesis does not start the chain again. Each one keeps the chain, - // and the answer to our `getheaders` puts blocks 2 and 3 on it. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(3); let other = crate::pow::mined_for_regtest(crate::block::BlockHeader { @@ -3947,8 +3220,6 @@ mod tests { #[test] fn sync_that_ends_below_the_minimum_work_ends_the_connection() { - // Genesis has less work than the minimum of each network but regtest, and the empty batch - // ends the sync on it. Regtest has a minimum of zero, so the same batch ends its sync. let start = std::time::Instant::now(); for (network, expected) in [ (crate::chainparams::Network::Mainnet, false), @@ -3970,7 +3241,6 @@ mod tests { #[test] fn sync_that_ends_at_the_minimum_work_ends_there() { let mut chain = regtest(); - // A short batch on our tip, so no low-work sync starts. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(2); let work_min = tip_after(&headers).work(); @@ -3985,8 +3255,6 @@ mod tests { #[test] fn full_batch_on_a_chain_at_the_minimum_work_goes_on_the_chain() { let mut chain = regtest(); - // The work of genesis is the minimum, so no low-work sync starts. Our chain takes the full - // batch, and the next one goes on it. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(2_002); let work_min = tip_after(&[]).work(); @@ -4006,16 +3274,11 @@ mod tests { #[test] fn full_batch_below_the_minimum_work_starts_a_sync_that_gets_the_chain_twice() { let mut chain = regtest(); - // The chain reaches the minimum at height 11,000, in the 6th batch. The second download - // holds 7,017 headers on regtest, so our chain gets the first 2,983 after its 5th batch, - // and the rest after its 6th. That batch is full, so the sync goes on from our tip. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(12_002); let work_min = tip_after(&headers[..11_000]).work(); let batches: Vec<_> = headers[..12_000].chunks(2_000).collect(); let mut peer = asked_with(&mut chain, work_min, start); - // The first download keeps no header, so each `getheaders` goes from its last header. The - // last batch reaches the minimum, so the second download starts on our tip. for (index, batch) in batches.iter().enumerate() { let get_headers; (peer, get_headers) = batch_then_tick(peer, batch, start); @@ -4025,7 +3288,6 @@ mod tests { }; assert_eq!(get_headers, expected, "first download, batch {index}"); } - // After the last batch, the sync goes on from our tip, with the locator of our chain. for (index, batch) in batches.iter().enumerate() { let get_headers; (peer, get_headers) = batch_then_tick(peer, batch, start); @@ -4045,7 +3307,6 @@ mod tests { #[test] fn low_work_sync_that_reaches_the_minimum_in_a_short_batch_ends_there() { let mut chain = regtest(); - // The work of the chain is the minimum. Both downloads take the short batch. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(3_500); let work_min = tip_after(&headers).work(); @@ -4066,8 +3327,6 @@ mod tests { #[test] fn low_work_sync_that_refuses_a_batch_ends_the_connection() { let mut chain = regtest(); - // The second batch of the first download is the first batch again, so it is not on the - // last header. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(2_000); let work_min = tip_after(&headers) @@ -4086,9 +3345,6 @@ mod tests { #[test] fn each_header_that_a_low_work_sync_releases_goes_through_the_checks_of_the_chain() { let mut chain = regtest(); - // Header 2,001 has version 1, below the lowest version of regtest. Only the chain checks - // the version, so both downloads take it, and the chain refuses the second batch that the - // second download released. let start = std::time::Instant::now(); let first = crate::fixtures::headers_on_genesis(2_000); let below = &first[1_999]; @@ -4100,8 +3356,6 @@ mod tests { }); let rest = crate::fixtures::headers_on(&old, 1_999); let second = [&[old][..], &rest].concat(); - // Each regtest header has the same work, so the work of 3,000 other headers is the work - // of this chain at that height. let work_min = tip_after(&crate::fixtures::headers_on_genesis(3_000)).work(); let (peer, _) = batch_then_tick(asked_with(&mut chain, work_min, start), &first, start); let (peer, _) = batch_then_tick(peer, &second, start); @@ -4118,7 +3372,6 @@ mod tests { #[test] fn no_getheaders_after_the_sync() { let mut chain = regtest(); - // After the sync, only our `ping` sets the wake, and no headers timeout is left. let start = std::time::Instant::now(); let later = start + std::time::Duration::from_mins(10); let (_, wake) = idle(pinged(&mut chain, start, 7), later); @@ -4142,7 +3395,6 @@ mod tests { let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(3); let mut peer = pinged(&mut chain, start, 7); - // One header, then two, then none. Each one gives the tip with no `getheaders`. for (announced, height) in [(&headers[..1], 1), (&headers[1..], 3), (&[][..], 3)] { let received = peer.receive(&headers_message(announced), crate::fixtures::CLOCK); let Ok((next, super::Received::Synced(tip))) = received else { @@ -4151,7 +3403,6 @@ mod tests { assert_eq!(tip, tip_after(&headers[..height])); peer = next; } - // Our `sendheaders` went once, and the ping timeout is the only wake. let later = start + std::time::Duration::from_mins(10); let (_, wake) = idle(peer, later); assert_eq!(wake, start + super::PING_TIMEOUT); @@ -4175,7 +3426,6 @@ mod tests { )) => peer, other => panic!("{other:?}"), }; - // A transaction and a block. The hash of the block is not one that elo reads. let peer = accept(peer, &inv_message(&[1, 2])); let later = start + std::time::Duration::from_mins(1); let peer = match peer.tick(later, 0) { @@ -4205,14 +3455,11 @@ mod tests { fn inv_in_the_sync_or_with_no_block_is_skipped() { let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(1); - // In the sync, the answer to our `getheaders` comes after the `inv`, so the `inv` makes - // nothing due, and the answer is not unsolicited. let mut chain = regtest(); let peer = accept(asked(&mut chain, start, 7), &inv_message(&[2])); synced(peer, &headers); assert_eq!(chain.tip(), tip_after(&headers)); - // After the sync, an `inv` of transactions makes nothing due. let mut chain = regtest(); let peer = accept(pinged(&mut chain, start, 7), &inv_message(&[1, 5])); let later = start + std::time::Duration::from_mins(1); @@ -4222,7 +3469,6 @@ mod tests { #[test] fn inv_that_does_not_decode_ends_the_connection() { - // In the sync too. The entry stops one byte before the end of its hash. let mut payload = crate::fixtures::inv_payload(&[2]); payload.pop(); let mut chain = regtest(); @@ -4256,7 +3502,6 @@ mod tests { #[test] fn their_headers_payload_is_checked_first() { let mut chain = regtest(); - // The payload has no count. It fails also when no `getheaders` is outstanding. let start = std::time::Instant::now(); for peer in [peer(&mut regtest()), asked(&mut chain, start, 7)] { assert_eq!( @@ -4271,9 +3516,6 @@ mod tests { #[test] fn headers_off_our_tip_in_answer_to_our_getheaders_end_the_connection() { - // The first header is on block 1, which our chain does not have. In the sync, and in the - // answer to the `getheaders` of an announcement off our tip, where the next announcement - // of the peer looks like the answer. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(2); let (mut asked_chain, mut announced_chain) = (regtest(), regtest()); @@ -4294,8 +3536,6 @@ mod tests { #[test] fn headers_too_far_after_our_clock_end_the_connection() { let mut chain = regtest(); - // The other tests pass a clock that takes each time. So only this one shows that the chain - // gets the clock of `receive`. let start = std::time::Instant::now(); let headers = crate::fixtures::headers_on_genesis(2); let clock = u64::from(headers[1].time) - 2 * 60 * 60 - 1; diff --git a/src/pow.rs b/src/pow.rs index f560a69..c77c9d6 100644 --- a/src/pow.rs +++ b/src/pow.rs @@ -1,43 +1,23 @@ -//! Proof of work. - -/// The headers of one period. The first header of a period has a height that is a multiple of this. const PERIOD_HEADERS_COUNT: usize = 2016; -/// The seconds that a period of headers should take: two weeks. const PERIOD_TIMESPAN_SECONDS: u32 = 14 * 24 * 60 * 60; -/// A period that takes less time counts as this, so a target falls by at most a factor of 4. const TIMESPAN_SECONDS_MIN: u32 = PERIOD_TIMESPAN_SECONDS / 4; -/// A period that takes more time counts as this, so a target rises by at most a factor of 4. const TIMESPAN_SECONDS_MAX: u32 = PERIOD_TIMESPAN_SECONDS * 4; -// The divide in the smallest time is exact, so the two factors are the same. const _: () = assert!(PERIOD_TIMESPAN_SECONDS.is_multiple_of(4)); -/// On testnet4, a header more than this many seconds after the header below it has the limit. const MIN_DIFFICULTY_GAP_SECONDS: u32 = 20 * 60; -/// On testnet4, the first header of a period may have a time at most this many seconds below the -/// header below it. const TIMEWARP_SECONDS_MAX: u32 = 10 * 60; -// Each time above genesis is above the genesis time, so with this a real chain does not reach a -// bound of zero. `Chain::extend` asserts the first half. const _: () = assert!(crate::chainparams::Network::Testnet4.genesis().time > TIMEWARP_SECONDS_MAX); -/// The highest hash that a header may have. The bytes are big-endian, so the order of two arrays is -/// the order of their numbers. Only `from_bits` makes one, so it is above zero and at most the -/// limit that `from_bits` got. #[derive(Clone, Copy, Debug, PartialEq, Eq)] struct Target([u8; 32]); impl Target { - /// Reads the compact form `bits`. Its first byte is the size of the number in bytes. Its other - /// three bytes are the first bytes of the number, so a number of fewer than three bytes uses - /// only the first of them. The first bit after the size byte is a sign. Returns nothing for a - /// number that is negative, is zero, does not fit in 32 bytes, or is above `limit`. A peer - /// picks `bits`, so no value may panic. fn from_bits(bits: u32, limit: [u8; 32]) -> Option { let [size, high, middle, low] = bits.to_be_bytes(); if high & 0x80 != 0 { @@ -46,14 +26,11 @@ impl Target { let mut target = [0; 32]; for (word_index, byte) in [high, middle, low].into_iter().enumerate() { match (target.len() + word_index).checked_sub(usize::from(size)) { - // An index past the end is after the last byte of the number, so the number does - // not use this byte. Some(target_index) => { if let Some(place) = target.get_mut(target_index) { *place = byte; } } - // Before the first byte of the target, only a zero fits. None if byte == 0 => {} None => return None, } @@ -61,7 +38,6 @@ impl Target { if target == [0; 32] { return None; } - // A size of 0 or above 34 keeps no byte of the word, so it gives a target of zero. assert!(size >= 1); assert!(usize::from(size) <= target.len() + 2); if target > limit { @@ -70,7 +46,6 @@ impl Target { Some(Target(target)) } - /// `hash` is in wire order: the reverse of the order of a target. fn is_met_by(self, hash: bitcoin_hashes::sha256d::Hash) -> bool { assert_ne!(self.0, [0; 32]); let mut hash_big_endian = hash.to_byte_array(); @@ -79,9 +54,6 @@ impl Target { } } -/// An amount of work: the count of hashes that a header, or a chain of headers, takes on average. -/// It is a number of 256 bits in two halves. The high half is the first field, so the order of two -/// amounts is the order of their fields. #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)] pub(crate) struct Work { high: u128, @@ -96,15 +68,9 @@ impl Work { low: u128::MAX, }; - /// The work of one header with `target`: 2^256 over `target + 1`, rounded down. 2^256 does not - /// fit in 256 bits. But it is the inverse of `target` plus `target + 1`, so the answer is the - /// inverse over `target + 1`, plus one. fn of(target: Target) -> Work { let target = Work::from_be_bytes(target.0); - // `from_bits` gives no target of zero, so the divisor is at least 2. assert_ne!(target, Work::ZERO); - // `from_bits` keeps at most three bytes of a number, so no target has all bits set, and - // the add does not saturate. assert_ne!(target, Work::MAX); let divisor = target.saturating_add(Work::ONE); let inverse = Work { @@ -112,14 +78,10 @@ impl Work { low: !target.low, }; let quotient = inverse.divided_by(divisor); - // The divisor is at least 2, so the quotient is below 2^255: its top bit is clear, and the - // add does not saturate. assert_eq!(quotient.high >> 127, 0); quotient.saturating_add(Work::ONE) } - /// `self` plus `other`, or the highest number if the sum does not fit. Each header of a real - /// chain has far less work than this, so only peer bytes that no hash can meet reach it. pub(crate) fn saturating_add(self, other: Work) -> Work { let (low, carry) = self.low.overflowing_add(other.low); let sum = match self @@ -130,14 +92,11 @@ impl Work { Some(high) => Work { high, low }, None => Work::MAX, }; - // A sum, saturated or not, is at least each part. `Chain::extend_store` reads this, when it - // asserts that the work of the chain rises. assert!(sum >= self); assert!(sum >= other); sum } - /// `self` minus `other`, which must be at most `self`. pub(crate) fn minus(self, other: Work) -> Work { assert!(other <= self); let (low, borrow) = self.low.overflowing_sub(other.low); @@ -147,12 +106,8 @@ impl Work { } } - /// `self` over `divisor`, rounded down, by long division in base 2. The first step puts the - /// highest bit of `divisor` under the highest bit of `self`, and each step gives one bit of the - /// answer. So a small answer takes few steps. fn divided_by(self, divisor: Work) -> Work { assert_ne!(divisor, Work::ZERO); - // `divisor` has a higher bit than `self`, so it is above `self`. let Some(shift) = divisor.leading_zeros().checked_sub(self.leading_zeros()) else { return Work::ZERO; }; @@ -168,12 +123,10 @@ impl Work { step_divisor = step_divisor.shifted_right_once(); } assert!(remainder < divisor); - // The divisor is at least 1. assert!(quotient <= self); quotient } - /// `self` times 2^`bits`, without the bits that pass 256. `bits` must be below 256. fn shifted_left(self, bits: u32) -> Work { assert!(bits < 256); if bits >= 128 { @@ -182,9 +135,7 @@ impl Work { low: 0, } } else { - // A shift of 128 does not fit a `u128`, so a shift of zero moves no bit up. let low_to_high = self.low.checked_shr(128 - bits).unwrap_or(0); - // The parts of each sum here share no bit, so the add is an or. Work { high: (self.high << bits) + low_to_high, low: self.low << bits, @@ -192,16 +143,13 @@ impl Work { } } - /// `self` over 2, rounded down. fn shifted_right_once(self) -> Work { - // The two parts of the sum share no bit, so the add is an or. Work { high: self.high >> 1, low: (self.low >> 1) + (self.high << 127), } } - /// The count of zero bits above the highest one bit. fn leading_zeros(self) -> u32 { if self.high == 0 { 128 + self.low.leading_zeros() @@ -210,11 +158,9 @@ impl Work { } } - /// The number of 32 big-endian bytes. fn from_be_bytes(bytes: [u8; 32]) -> Work { bytes.into_iter().fold(Work::ZERO, |number, byte| { let shifted = number.shifted_left(8); - // The shift leaves the low byte zero, so the add is an or. Work { low: shifted.low + u128::from(byte), ..shifted @@ -223,16 +169,12 @@ impl Work { } } -/// Writes the number as 64 hex digits, with the zeros at the start. impl std::fmt::Display for Work { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "{:032x}{:032x}", self.high, self.low) } } -/// The compact form of `number`, as `Target::from_bits` reads it. Only the first three bytes of the -/// number stay. A first byte with its top bit set would read as the sign, so it moves one byte -/// down and the size goes up by one. A number of zero gives zero, so `number` is no `Target`. fn to_bits(number: [u8; 32]) -> u32 { let mut size = 32_u8; let mut rest = number.as_slice(); @@ -254,12 +196,7 @@ fn to_bits(number: [u8; 32]) -> u32 { } } -/// `number` times `timespan_seconds`, over `PERIOD_TIMESPAN_SECONDS`, rounded down, and at most -/// `limit`. The multiply is first, so the divide sees all of the product. The answer can be zero, -/// so it is no `Target`. fn scaled_up_to(mut number: [u8; 32], timespan_seconds: u32, limit: [u8; 32]) -> [u8; 32] { - // `high` holds the bytes of the product above the 32. A byte times a `u32`, plus a `high` of at - // most that `u32`, fits in a `u64`. So no number and no time can overflow. let mut high = 0_u64; for byte in number.iter_mut().rev() { let value = u64::from(*byte) * u64::from(timespan_seconds) + high; @@ -267,16 +204,13 @@ fn scaled_up_to(mut number: [u8; 32], timespan_seconds: u32, limit: [u8; 32]) -> high = value >> 8; } let divisor = u64::from(PERIOD_TIMESPAN_SECONDS); - // The answer passes 32 bytes, so it is above each limit. if high >= divisor { return limit; } - // A remainder is below a `u32`, so with one more byte it fits in a `u64`. let mut remainder = high; for byte in &mut number { let value = (remainder << 8) + u64::from(*byte); let quotient = value / divisor; - // A remainder below `divisor` gives a quotient of one byte, so this drops no bit of it. assert!(quotient <= u64::from(u8::MAX)); [.., *byte] = quotient.to_be_bytes(); remainder = value % divisor; @@ -284,19 +218,8 @@ fn scaled_up_to(mut number: [u8; 32], timespan_seconds: u32, limit: [u8; 32]) -> number.min(limit) } -/// The `bits` of the next period. `bits` give the target to change, and `first_time` and -/// `last_time` are the times of the first and the last header of the period that ends. The target -/// changes by the time between them over `PERIOD_TIMESPAN_SECONDS`, by at most a factor of 4 in -/// each direction, and it stays at most `limit`. Returns nothing if `bits` are no target up to -/// `limit`, or if the answer is zero, which a target below 4 can reach. No header can pass in -/// either case, and each answer is a target. -/// -/// This takes `bits`, not a `Target`, and reads them with `limit`. So the limit that bounds the -/// target and the limit that caps the answer cannot differ. fn retargeted_bits(bits: u32, first_time: u32, last_time: u32, limit: [u8; 32]) -> Option { let target = Target::from_bits(bits, limit)?; - // A time before `first_time` counts as zero, so it takes the smallest time, as any short time - // does. let timespan_seconds = last_time .saturating_sub(first_time) .clamp(TIMESPAN_SECONDS_MIN, TIMESPAN_SECONDS_MAX); @@ -304,15 +227,10 @@ fn retargeted_bits(bits: u32, first_time: u32, last_time: u32, limit: [u8; 32]) if next == 0 { return None; } - // This reads the answer with `from_bits`, not with the code that wrote it. assert!(Target::from_bits(next, limit).is_some()); Some(next) } -/// The `bits` of the last header of this period that does not have the limit. If each one has the -/// limit, these are the limit. The header above `ancestors` must not start a period. The first -/// header of a period comes from the change of the target, so this does not read below it. So this -/// reads fewer than `PERIOD_HEADERS_COUNT` headers. fn last_real_bits(ancestors: crate::chain::Ancestors<'_>, limit_bits: u32) -> u32 { let height_above = ancestors.height_above(); assert!(!height_above.is_multiple_of(PERIOD_HEADERS_COUNT)); @@ -324,14 +242,6 @@ fn last_real_bits(ancestors: crate::chain::Ancestors<'_>, limit_bits: u32) -> u3 .unwrap_or(limit_bits) } -/// The `bits` that a header with `time` must have on `ancestors`. Returns nothing if a change of -/// the target has no answer, so no header can pass: a target below 4 fell to zero, or the `bits` -/// that change are no target up to the limit, and a chain does not hold such `bits`. Inside a -/// period this does not read `bits` as a target, so the answer is `bits` from below the header or -/// the limit. -/// -/// Regtest has one target. Each header of its chain has the `bits` of the limit, because its -/// genesis has them and no rule gives other `bits`. So it needs no period and no time. #[must_use = "a dropped answer lets each `bits` pass"] pub(crate) fn required_bits( network: crate::chainparams::Network, @@ -343,8 +253,6 @@ pub(crate) fn required_bits( let last = ancestors.last(); let period_ends = height_above.is_multiple_of(PERIOD_HEADERS_COUNT); match network { - // `extend` checks the `bits` of a header before the rule reads that header, so peer bytes - // cannot reach this assert. crate::chainparams::Network::Regtest => { assert_eq!(last.bits, to_bits(limit)); Some(last.bits) @@ -357,8 +265,6 @@ pub(crate) fn required_bits( Some(last.bits) } } - // The first header of a period cannot have the limit by a late time, so its `bits` are the - // real ones. The last header of a period can. crate::chainparams::Network::Testnet4 => { if period_ends { let first = ancestors.at(height_above - PERIOD_HEADERS_COUNT); @@ -372,17 +278,6 @@ pub(crate) fn required_bits( } } -/// The lowest time that a header may have on `ancestors`, by the timewarp rule. Zero is no bound, -/// because no time is below it. -/// -/// A change of the target reads the first and the last time of one period, so it does not see the -/// step from one period to the next. A chain could write a last time far ahead and then a first -/// time far back. Each period then looks long, so the target rises while the clock of the chain -/// stands still. This bounds that step. Only testnet4 has this rule. -/// -/// A peer picks each time, so no value may panic. A last time of at most `TIMEWARP_SECONDS_MAX` -/// gives zero, so each time passes. Each time above genesis is above the genesis time, so a real -/// chain does not reach zero. #[must_use = "a dropped answer lets each time pass"] pub(crate) fn timewarp_time_min( network: crate::chainparams::Network, @@ -399,7 +294,6 @@ pub(crate) fn timewarp_time_min( { let last_time = ancestors.last().time; let time_min = last_time.saturating_sub(TIMEWARP_SECONDS_MAX); - // A bound above the last time refuses a header that is not back at all. assert!(time_min <= last_time); time_min } else { @@ -409,14 +303,6 @@ pub(crate) fn timewarp_time_min( } } -/// `bits` may follow `bits_below` at `height` on `network`. This reads no time, so a check that -/// keeps no headers can run it. Inside a period the `bits` stay the same. At the first header of a -/// period, the target is at most 4 times above or below the target below it, and at most the -/// limit. A late header of testnet4 has the limit, so on testnet4 and on regtest each `bits` may -/// follow. `bits_below` must be a target up to the limit. -/// -/// A peer with little hash power gets more work from a few hard headers than from many easy ones. -/// So with no bound on each change, a cheap chain can show the minimum work in few headers. #[must_use = "a dropped answer lets each `bits` pass"] pub(crate) fn permits_bits_change( network: crate::chainparams::Network, @@ -435,19 +321,13 @@ pub(crate) fn permits_bits_change( let Some(target) = Target::from_bits(bits, limit) else { return false; }; - // The longest timespan gives the highest target, and the shortest gives the lowest. - // Each one goes through the compact form, as the change of a target does. let bound = |last_time| { retargeted_bits(bits_below, 0, last_time, limit) .and_then(|bits| Target::from_bits(bits, limit)) }; let highest = bound(u32::MAX); - // The highest change is at most the limit and never zero, so each target up to the - // limit has one. assert!(highest.is_some()); if highest.is_some_and(|highest| target.0 <= highest.0) { - // Only a target below 4 has a lowest change of zero, and then no target is below - // it. bound(0).is_none_or(|lowest| lowest.0 <= target.0) } else { false @@ -456,8 +336,6 @@ pub(crate) fn permits_bits_change( } } -/// The hash and the work of `header`, if its `bits` are a target in the range of `network` and the -/// hash is at most that target. #[must_use = "a dropped answer lets each header pass"] pub(crate) fn proven( header: &crate::block::BlockHeader, @@ -468,23 +346,15 @@ pub(crate) fn proven( target.is_met_by(hash).then(|| (hash, Work::of(target))) } -/// The work of a header with `bits`, if they are a target in the range of `network`. It reads no -/// hash, so it does not check proof of work: `proven` does. pub(crate) fn work(bits: u32, network: crate::chainparams::Network) -> Option { Target::from_bits(bits, network.pow_limit()).map(Work::of) } -/// The lowest work that a chain of `network` must have when its sync ends. pub(crate) fn chain_work_min(network: crate::chainparams::Network) -> Work { Work::from_be_bytes(network.chain_work_min()) } -/// `header` with the first `nonce` that gives a hash below the regtest target, whatever its `bits` -/// are. A top byte below 0x7f is below that target, so about every second nonce passes. The top -/// byte of a hash is its last byte in wire order. This does not call the check above, so a check -/// that reads the wrong byte refuses these headers. Only the tests and the fuzz script call this. #[cfg(any(test, fuzzing))] -// Only cargo-mutants reads this attribute. #[cfg_attr(false, mutants::skip)] pub(crate) fn mined_for_regtest(header: crate::block::BlockHeader) -> crate::block::BlockHeader { let mined = (0..=u32::MAX) @@ -497,13 +367,8 @@ pub(crate) fn mined_for_regtest(header: crate::block::BlockHeader) -> crate::blo } #[cfg(fuzzing)] -// Only cargo-mutants reads this attribute. Its test runs do not build this module. #[cfg_attr(false, mutants::skip)] pub(crate) mod fuzz { - /// A peer picks each field of `header`, so its `bits` and its times go through the change of a - /// target, whose asserts must hold for any value. A header has one time, and `nonce` gives a - /// second `u32` that a peer picks, so it is the first time. Regtest has the highest limit, so - /// only it reaches a product above 32 bytes. pub(crate) fn retarget_check(header: &crate::block::BlockHeader) { for network in [ crate::chainparams::Network::Mainnet, @@ -514,7 +379,6 @@ pub(crate) mod fuzz { let next = super::retargeted_bits(header.bits, header.nonce, header.time, limit); match super::Target::from_bits(header.bits, limit) { None => assert_eq!(next, None), - // Only a target below 4 can have no answer. Some(super::Target([high @ .., low])) => { assert!(next.is_some() || (high == [0; 31] && low < 4)); } @@ -522,22 +386,12 @@ pub(crate) mod fuzz { } } - /// A peer picks `bits`, so each target goes through the work of a header, whose asserts must - /// hold for any target. No limit bounds it here, so a small target reaches the longest division - /// and a target above half of 2^256 the shortest. pub(crate) fn work_check(header: &crate::block::BlockHeader) { if let Some(target) = super::Target::from_bits(header.bits, [0xff; 32]) { assert!(super::Work::of(target) >= super::Work::ONE); } } - /// A peer picks each `bits` and each `time` of `headers`, so each header goes through the rule - /// of each network, as the header above the ones before it. The rule must return for any value, - /// apart from one case: on regtest it asserts that the header below has the limit, because a - /// chain holds no other `bits`. So on regtest this stops at a header with other `bits`. A batch - /// has fewer headers than a period, so no period ends here, and a period that ends would fail - /// the assert on mainnet. These checks do not repeat the walk of testnet4: its answer must only - /// be the limit or `bits` from below the header. pub(crate) fn required_bits_check(headers: &[crate::block::BlockHeader]) { for network in [ crate::chainparams::Network::Mainnet, @@ -575,17 +429,14 @@ pub(crate) mod fuzz { #[cfg(test)] mod tests { - /// A target from its 32 bytes in hex. fn target(s: &str) -> super::Target { super::Target(crate::fixtures::hex(s).try_into().unwrap()) } #[test] fn from_bits_reads_the_compact_form() { - // The limit is above each target, so only the compact form can refuse. let limit = [0xff; 32]; let cases = [ - // A size of three bytes or fewer. The sign bit is not a bit of the number. ( 0x0112_3456, "0000000000000000000000000000000000000000000000000000000000000012", @@ -602,7 +453,6 @@ mod tests { 0x0312_3456, "0000000000000000000000000000000000000000000000000000000000123456", ), - // A size above three bytes. ( 0x0412_3456, "0000000000000000000000000000000000000000000000000000000012345600", @@ -615,7 +465,6 @@ mod tests { 0x2012_3456, "1234560000000000000000000000000000000000000000000000000000000000", ), - // At the top of the target: the size may pass 32 only by the zeros at the word's start. ( 0x2100_ffff, "ffff000000000000000000000000000000000000000000000000000000000000", @@ -636,30 +485,23 @@ mod tests { #[test] fn from_bits_refuses_zero_and_negative_and_what_does_not_fit() { - // The limit is above each target, so only the compact form can refuse. let limit = [0xff; 32]; let cases = [ - // Zero: the word is zero, or it has no byte that the size keeps. 0x0000_0000, 0x0012_3456, 0x0100_3456, 0x0200_0056, 0x0300_0000, 0x0400_0000, - // Zero with the sign bit. 0x0092_3456, 0x0180_3456, 0x0280_0056, 0x0380_0000, 0x0480_0000, - // Negative, with a number that is not zero. 0x01fe_dcba, 0x0492_3456, - // At the top of the target: another byte of the word is not zero, so only the fit - // refuses it. 0x2101_0001, 0x2200_0101, - // No byte of the word fits. 0x2300_0001, 0xff12_3456, ]; @@ -707,7 +549,6 @@ mod tests { 0x1d00_ffff, 0x1d01_0000, ), - // These `bits` are exactly the limit. ( crate::chainparams::Network::Signet, 0x1e03_77ae, @@ -732,7 +573,6 @@ mod tests { } } - /// 32 bytes from hex. fn number(s: &str) -> [u8; 32] { crate::fixtures::hex(s).try_into().unwrap() } @@ -744,7 +584,6 @@ mod tests { "0000000000000000000000000000000000000000000000000000000000000000", 0x0000_0000, ), - // One or two bytes: the bytes after the number are zero. ( "0000000000000000000000000000000000000000000000000000000000000012", 0x0112_0000, @@ -757,12 +596,10 @@ mod tests { "0000000000000000000000000000000000000000000000000000000000123456", 0x0312_3456, ), - // Only the first three bytes stay. ( "0000000000000000000000000000000000000000000000000000000012345678", 0x0412_3456, ), - // A first byte with its top bit set moves one byte down. ( "0000000000000000000000000000000000000000000000000000000000000080", 0x0200_8000, @@ -775,7 +612,6 @@ mod tests { "0000000000000000000000000000000000000000000000000000000092345678", 0x0500_9234, ), - // The whole width. ( "1234560000000000000000000000000000000000000000000000000000000000", 0x2012_3456, @@ -806,8 +642,6 @@ mod tests { } } - /// Each row has a name, `bits`, the first time, the last time and the answer on the mainnet - /// limit. fn assert_retargets(cases: &[(&str, u32, u32, u32, u32)]) { let limit = crate::chainparams::Network::Mainnet.pow_limit(); for &(name, bits, first_time, last_time, expected) in cases { @@ -821,8 +655,6 @@ mod tests { #[test] fn retargeted_bits_match_real_retargets() { - // These come from `pow_tests.cpp` of Bitcoin Core: real mainnet retargets, but the first - // time of the last row is not a real block time. assert_retargets(&[ ("no bound", 0x1d00_ffff, 1261130161, 1262152739, 0x1d00_d86a), ( @@ -852,7 +684,6 @@ mod tests { #[test] fn retargeted_bits_change_with_the_time_of_the_period() { assert_retargets(&[ - // At a bound, a second inside it changes the answer and a second outside it does not. ( "below a quarter", 0x1c7f_ffff, @@ -884,9 +715,7 @@ mod tests { 0x1b7f_fffc, ), ("the same", 0x1c04_0000, 1_000_000, 2_209_600, 0x1c04_0000), - // A time that goes back counts as a short time. ("back", 0x1c7f_ffff, 1_302_401, 1_000_000, 0x1c1f_ffff), - // The multiply is first: a divide first gives zero. ("one", 0x0101_0000, 1_000_000, 2_209_600, 0x0101_0000), ]); } @@ -906,7 +735,6 @@ mod tests { #[test] fn retargeted_bits_refuse_an_answer_of_zero() { let limit = crate::chainparams::Network::Mainnet.pow_limit(); - // The time is the smallest, so the answer is a quarter of the target, rounded down. for (bits, expected) in [(0x0103_0000, None), (0x0104_0000, Some(0x0101_0000))] { assert_eq!( super::retargeted_bits(bits, 1_000_000, 1_000_000, limit), @@ -918,8 +746,6 @@ mod tests { #[test] fn the_largest_change_of_a_limit_is_four_times_it() { - // These answers are from big integers, not from this code. The cap is above each one, so it - // hides no wrong answer. let mainnet = "00000003fffffffffffffffffffffffffffffffffffffffffffffffffffffffc"; for (network, expected) in [ (crate::chainparams::Network::Mainnet, mainnet), @@ -939,14 +765,10 @@ mod tests { #[test] fn retargeted_bits_keep_a_product_above_32_bytes() { - // These answers are from big integers, not from this code. let limit = crate::chainparams::Network::Regtest.pow_limit(); for (bits, last_time, expected) in [ - // The product passes 32 bytes, but the answer does not. (0x207f_ffff, 1_302_400, 0x201f_ffff), - // The answer also passes 32 bytes, so it takes the limit. (0x207f_ffff, 5_838_400, 0x207f_ffff), - // The answer is exactly 2^256: the smallest number above 32 bytes. (0x2040_0000, 5_838_400, 0x207f_ffff), ] { assert_eq!( @@ -957,7 +779,6 @@ mod tests { } } - /// `count` headers with `bits`, each 600 seconds after the header before it. fn headers(count: u32, bits: u32) -> Vec { (0..count) .map(|index| crate::block::BlockHeader { @@ -968,7 +789,6 @@ mod tests { .collect() } - /// `chain` as the headers below one header. The rule reads each part the same way. fn ancestors(chain: &[crate::block::BlockHeader]) -> crate::chain::Ancestors<'_> { let (tip, batch) = chain.split_first().unwrap(); crate::chain::Ancestors::on_tip(tip, batch) @@ -986,7 +806,6 @@ mod tests { for count in [1, 2015, 2017] { let mut chain = headers(count, REAL_BITS); chain.last_mut().unwrap().bits = LOW_BITS; - // A late time changes nothing on these networks. assert_eq!( super::required_bits(network, ancestors(&chain), u32::MAX), Some(LOW_BITS), @@ -998,9 +817,6 @@ mod tests { #[test] fn required_bits_read_the_end_of_a_period_in_a_batch() { - // A sync in full batches ends each batch at an even height, and the last header of a period - // has an odd height. So that header is always in the batch, and this reads it there. The - // answer is from big integers, not from this code. let chain = headers(2016, REAL_BITS); for network in [ crate::chainparams::Network::Mainnet, @@ -1024,7 +840,6 @@ mod tests { for (time, expected) in [ (last_time + 1201, limit_bits), (last_time + 1200, REAL_BITS), - // A time that goes back is not late. (last_time - 1, REAL_BITS), ] { assert_eq!( @@ -1039,7 +854,6 @@ mod tests { fn required_bits_on_testnet4_go_back_to_the_last_real_bits() { let network = crate::chainparams::Network::Testnet4; let limit_bits = network.genesis().bits; - // Each case gives the `bits` from height 0. The time is not late, so the rule goes back. let last_of_period = { let mut bits = vec![limit_bits; 2015]; bits[2014] = REAL_BITS; @@ -1074,7 +888,6 @@ mod tests { start_of_period_real, REAL_BITS, ), - // The real `bits` below the period do not count. ("not below the period", start_of_period_at_limit, limit_bits), ] { let chain: Vec<_> = bits @@ -1097,7 +910,6 @@ mod tests { fn required_bits_on_regtest_are_the_limit_at_each_height() { let network = crate::chainparams::Network::Regtest; let limit_bits = network.genesis().bits; - // A period ends at 2016, and the math that changes a target gives other `bits` there. for count in [1, 2015, 2016] { assert_eq!( super::required_bits(network, ancestors(&headers(count, limit_bits)), u32::MAX), @@ -1109,9 +921,6 @@ mod tests { #[test] fn timewarp_bound_stops_at_zero() { - // A real chain has no last time below 600, because each time above genesis is above the - // genesis time. So the rows of `Chain::extend` do not reach zero. A person wrote each - // answer. let mut chain = headers(2016, REAL_BITS); for (last_time, expected) in [ (0, 0), @@ -1132,30 +941,23 @@ mod tests { #[test] fn work_is_two_to_the_256_over_the_target_plus_one() { - // These answers are from big integers, not from this code. The limit is above each target. let limit = [0xff; 32]; for (bits, expected) in [ - // Mainnet and testnet4 genesis, signet genesis and regtest genesis. (0x1d00_ffff, "100010001"), (0x1e03_77ae, "49d414"), (0x207f_ffff, "2"), - // A real mainnet `bits` from 2026. (0x1703_4219, "4e9235f043634662e0cb"), - // A target of 1 gives the highest work: 256 steps of the division. ( 0x0101_0000, "8000000000000000000000000000000000000000000000000000000000000000", ), - // Each bit of the answer is in use, in both halves. ( 0x0300_8000, "1fffc0007fff0001fffc0007fff0001fffc0007fff0001fffc0007fff0001", ), (0x107f_ffff, "200000400000800001000002000003ffc"), - // At the edge of the two halves. (0x1100_8000, "1fffffffffffffffffffffffffffffffc"), (0x1101_0000, "ffffffffffffffffffffffffffffffff"), - // A target above half of 2^256 has the lowest work. (0x2100_ffff, "1"), ] { let target = super::Target::from_bits(bits, limit).unwrap(); @@ -1172,11 +974,8 @@ mod tests { let work = |high, low| super::Work { high, low }; for (left, right, expected) in [ (work(0, u128::MAX), work(0, 1), work(1, 0)), - // Exactly the highest number fits. (work(u128::MAX, 0), work(0, u128::MAX), super::Work::MAX), - // Only the carry passes 256 bits. (super::Work::MAX, work(0, 1), super::Work::MAX), - // Only the high halves pass 256 bits. (work(u128::MAX, 0), work(1, 0), super::Work::MAX), ] { assert_eq!(left.saturating_add(right), expected, "{left} {right}"); @@ -1185,8 +984,6 @@ mod tests { #[test] fn chain_work_min_is_the_minimum_of_its_network() { - // A person copied each minimum from the source of the network. Regtest has no real chain, - // so its minimum is zero. for (network, minimum) in [ ( crate::chainparams::Network::Mainnet, @@ -1213,8 +1010,6 @@ mod tests { #[test] fn each_genesis_has_proof_of_work() { - // Real headers, so this also shows the byte order of the hash: in wire order, each hash - // but the regtest one starts with bytes above its target. for network in [ crate::chainparams::Network::Mainnet, crate::chainparams::Network::Testnet4, @@ -1230,13 +1025,9 @@ mod tests { } } - /// A person wrote each answer from the rule: the bounds of a change are a target over 4 and - /// times 4, at most the limit, each one rounded down to its compact form. A script that ran - /// the same rule with big numbers gave the same answers. #[test] fn permits_bits_change_bounds_each_change_of_the_target() { let cases = [ - // Inside a period the `bits` stay the same. ( crate::chainparams::Network::Mainnet, 32_255, @@ -1265,7 +1056,6 @@ mod tests { 0x1e00_ddeb, false, ), - // The first change of the target of mainnet, at height 32256. ( crate::chainparams::Network::Mainnet, 32_256, @@ -1273,7 +1063,6 @@ mod tests { 0x1d00_d86a, true, ), - // The highest change of the limit is the limit, and the bits above it are no target. ( crate::chainparams::Network::Mainnet, 32_256, @@ -1281,7 +1070,6 @@ mod tests { 0x1d01_0000, false, ), - // The lowest change: the limit over 4, and one below it. ( crate::chainparams::Network::Mainnet, 32_256, @@ -1296,8 +1084,6 @@ mod tests { 0x1c3f_ffbf, false, ), - // Below the limit, the highest change is 4 times the target. Over 4, the target loses - // its low bits in the compact form. ( crate::chainparams::Network::Mainnet, 4_032, @@ -1326,7 +1112,6 @@ mod tests { 0x1b01_0131, false, ), - // A target of 3 over 4 is zero, so it has no lowest change. ( crate::chainparams::Network::Mainnet, 2_016, @@ -1348,7 +1133,6 @@ mod tests { 0x010d_0000, false, ), - // The lowest change of the signet limit. ( crate::chainparams::Network::Signet, 2_016, @@ -1363,7 +1147,6 @@ mod tests { 0x1e00_ddea, false, ), - // Testnet4 and regtest permit each change. ( crate::chainparams::Network::Testnet4, 1, diff --git a/src/protocol.rs b/src/protocol.rs index bfaf06e..0f3d87f 100644 --- a/src/protocol.rs +++ b/src/protocol.rs @@ -1,38 +1,25 @@ -//! Message types and payloads. - use crate::serialize::{Decode, Encode}; -/// The protocol version elo sends. pub(crate) const PROTOCOL_VERSION: i32 = 70016; -/// The most headers a `headers` may carry. A peer that sends fewer has no more to send. pub(crate) const HEADERS_COUNT_MAX: usize = 2000; -/// The most hashes in the locator of a `getheaders` that a peer takes. A peer drops a connection -/// that sends more. pub(crate) const LOCATOR_HASHES_COUNT_MAX: usize = 101; -/// The most entries an `inv` may carry. pub(crate) const INV_COUNT_MAX: usize = 50_000; -/// The type of an `inv` entry that announces a block. const INV_TYPE_BLOCK: u32 = 2; -/// The longest user agent a `version` may carry. const USER_AGENT_LENGTH_MAX: usize = 256; -/// The user agent elo sends (BIP14). const USER_AGENT_ELO: &str = concat!("/elo:", env!("CARGO_PKG_VERSION"), "/"); const _: () = assert!(USER_AGENT_ELO.len() <= USER_AGENT_LENGTH_MAX); -/// The size of a message type, with the padding. pub(crate) const MESSAGE_TYPE_SIZE: usize = 12; -/// The message type in a header: printable ASCII, then NUL padding. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) struct MessageType([u8; MESSAGE_TYPE_SIZE]); -// `from_name` runs at compile time here, so an invalid name does not build. pub(crate) const VERSION: MessageType = MessageType::from_name("version"); pub(crate) const VERACK: MessageType = MessageType::from_name("verack"); pub(crate) const PING: MessageType = MessageType::from_name("ping"); @@ -45,8 +32,6 @@ pub(crate) const SENDHEADERS: MessageType = MessageType::from_name("sendheaders" pub(crate) const INV: MessageType = MessageType::from_name("inv"); impl MessageType { - /// Pads `name` with NULs to `MESSAGE_TYPE_SIZE` bytes. Panics if the name - /// is longer or `new` rejects the padded bytes. const fn from_name(name: &str) -> Self { let name = name.as_bytes(); assert!(name.len() <= MESSAGE_TYPE_SIZE); @@ -59,7 +44,6 @@ impl MessageType { Self::new(bytes).expect("a printable ASCII name") } - /// `None` unless the bytes are printable ASCII followed only by NULs. pub(crate) const fn new(bytes: [u8; MESSAGE_TYPE_SIZE]) -> Option { let mut index = 0; while index < bytes.len() { @@ -81,21 +65,16 @@ impl MessageType { Some(Self(bytes)) } - /// All the bytes, with the padding. pub(crate) const fn as_bytes(&self) -> &[u8; MESSAGE_TYPE_SIZE] { &self.0 } } -/// The services a node offers. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct ServiceFlags(u64); impl ServiceFlags { - /// No services. pub(crate) const NONE: Self = Self(0); - /// A node that serves each block, `NODE_NETWORK` (bit 0), with the witness of each - /// transaction, `NODE_WITNESS` (bit 3). pub(crate) const NETWORK_WITNESS: Self = Self(0b1001); } @@ -117,7 +96,6 @@ impl Decode for ServiceFlags { } } -/// An address as a `version` carries it. An IPv4 address is IPv4-mapped. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) struct Address { services: ServiceFlags, @@ -139,7 +117,6 @@ impl Address { } } -/// The port is big-endian. impl Encode for Address { fn encode(&self, out: &mut Vec) { self.services.encode(out); @@ -158,12 +135,10 @@ impl Decode for Address { } } -/// Raw bytes, which need not be UTF-8. At most `USER_AGENT_LENGTH_MAX`. #[derive(Clone, Debug, PartialEq, Eq)] pub struct UserAgent(Vec); impl UserAgent { - /// The user agent that elo sends: `/elo:/`. pub(crate) fn elo() -> Self { Self(USER_AGENT_ELO.as_bytes().to_vec()) } @@ -173,8 +148,6 @@ impl UserAgent { } } -/// Escapes each byte that is not printable ASCII, so a peer cannot send control codes to a -/// terminal. impl std::fmt::Display for UserAgent { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "{}", self.0.escape_ascii()) @@ -209,7 +182,6 @@ impl Decode for UserAgent { } } -/// The `version` payload. #[derive(Clone, Debug, PartialEq, Eq)] pub struct Version { pub(crate) version: i32, @@ -224,7 +196,6 @@ pub struct Version { } impl Version { - /// The protocol version. pub fn version(&self) -> i32 { self.version } @@ -237,12 +208,10 @@ impl Version { &self.user_agent } - /// The height of the sender's best chain. pub fn start_height(&self) -> i32 { self.start_height } - /// Whether the sender wants to get transactions (BIP37). pub(crate) fn relay(&self) -> bool { self.relay } @@ -262,8 +231,6 @@ impl Encode for Version { } } -/// Every field up to `start_height` is required. A missing `relay` is true -/// (BIP37). Bytes after `relay` stay in `input`. impl Decode for Version { fn decode(input: &mut &[u8]) -> Result { Ok(Self { @@ -284,28 +251,19 @@ impl Decode for Version { } } -/// The `getheaders` payload. It asks for the headers after the first hash of its locator that is -/// on the chain of the peer. #[derive(Clone, Debug, PartialEq, Eq)] pub(crate) struct GetHeaders { - /// The hashes of the locator, from the highest header down. locator: Vec, } impl GetHeaders { - /// Asks for the headers after the first hash of `locator` that is on the chain of the peer: the - /// locator of our chain, or only the last header of a download of a low-work sync. `locator` - /// has from 1 to `LOCATOR_HASHES_COUNT_MAX` hashes, from the highest header down. pub(crate) fn new(locator: Vec) -> GetHeaders { - // A peer answers an empty locator with one header, and drops a long one. assert!(!locator.is_empty()); assert!(locator.len() <= LOCATOR_HASHES_COUNT_MAX); GetHeaders { locator } } } -/// The version is `PROTOCOL_VERSION`. `hash_stop` is all zeros, so the peer sends as many headers -/// as a `headers` can carry. impl Encode for GetHeaders { fn encode(&self, out: &mut Vec) { PROTOCOL_VERSION.encode(out); @@ -318,25 +276,17 @@ impl Encode for GetHeaders { } } -/// The `headers` payload: at most `HEADERS_COUNT_MAX` headers, each with a transaction count -/// of 0. #[derive(Clone, Debug, PartialEq, Eq)] pub(crate) struct Headers(Vec); -/// Why a `headers` payload was refused. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum HeadersError { - /// The payload did not decode. Payload(crate::serialize::Error), - /// The count is above `HEADERS_COUNT_MAX`. TooMany(usize), - /// A header has a transaction count that is not 0. TxCount(std::num::NonZeroUsize), } impl Headers { - /// Checks the count before it reads a header. Bytes after the last transaction count stay - /// in `input`. pub(crate) fn decode(input: &mut &[u8]) -> Result { let count = crate::serialize::read_compact_size(input).map_err(HeadersError::Payload)?; if count > HEADERS_COUNT_MAX { @@ -356,10 +306,6 @@ impl Headers { Ok(Self(headers)) } - /// `headers`, in order, in batches of `HEADERS_COUNT_MAX` and a last batch with the rest. No - /// headers give no batch. The second download of a low-work sync releases more headers than - /// one batch, and the chain takes only a batch. So `is_full` on one of these does not say that - /// the peer can have more. pub(crate) fn batches(headers: Vec) -> Vec { let batches: Vec = headers .chunks(HEADERS_COUNT_MAX) @@ -369,26 +315,20 @@ impl Headers { batches } - /// True for `HEADERS_COUNT_MAX` headers. Then the peer can have more. pub(crate) fn is_full(&self) -> bool { self.0.len() == HEADERS_COUNT_MAX } - /// The first header of the payload, if there is one. pub(crate) fn first(&self) -> Option<&crate::block::BlockHeader> { self.0.first() } - /// The headers, in the order of the payload. pub(crate) fn as_slice(&self) -> &[crate::block::BlockHeader] { - // As in `into_vec`. assert!(self.0.len() <= HEADERS_COUNT_MAX); &self.0 } - /// The headers, in the order of the payload. pub(crate) fn into_vec(self) -> Vec { - // `decode` refuses a longer batch. `Chain::extend` takes its loop bound from this `Vec`. assert!(self.0.len() <= HEADERS_COUNT_MAX); self.0 } @@ -410,25 +350,18 @@ impl std::fmt::Display for HeadersError { impl std::error::Error for HeadersError {} -/// The `inv` payload: at most `INV_COUNT_MAX` entries, each a type and a hash. elo keeps only -/// whether an entry announces a block. It keeps no hash, because it asks for the headers after -/// its tip, and not for one block. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) struct Inv { has_block: bool, } -/// Why an `inv` payload was refused. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum InvError { - /// The payload did not decode. Payload(crate::serialize::Error), - /// The count is above `INV_COUNT_MAX`. TooMany(usize), } impl Inv { - /// Checks the count before it reads an entry. Bytes after the last entry stay in `input`. pub(crate) fn decode(input: &mut &[u8]) -> Result { let count = crate::serialize::read_compact_size(input).map_err(InvError::Payload)?; if count > INV_COUNT_MAX { @@ -444,7 +377,6 @@ impl Inv { Ok(Self { has_block }) } - /// True if an entry announces a block. pub(crate) fn has_block(&self) -> bool { self.has_block } @@ -461,54 +393,35 @@ impl std::fmt::Display for InvError { impl std::error::Error for InvError {} -/// The entry points of the `version` and `headers` fuzz targets. #[cfg(fuzzing)] -// Only cargo-mutants reads this attribute. Its test runs do not build this module. #[cfg_attr(false, mutants::skip)] pub(crate) mod fuzz { use crate::serialize::{Decode, Encode}; - // The seeds hold these limits as bytes, and each check takes its limit from the same constant. - // So a new limit moves the checks and not the seeds, and the replay still passes. A new limit - // must rewrite the seeds at the limit. const _: () = assert!(super::HEADERS_COUNT_MAX == 2000); const _: () = assert!(super::USER_AGENT_LENGTH_MAX == 256); - /// The size of the `version` fields before the user agent. const VERSION_BEFORE_USER_AGENT_SIZE: usize = 80; - /// The size of the `version` fields after the user agent: `start_height` and `relay`. const VERSION_AFTER_USER_AGENT_SIZE: usize = size_of::() + size_of::(); - /// The size of the `version` fields other than the user agent. const VERSION_FIXED_SIZE: usize = VERSION_BEFORE_USER_AGENT_SIZE + VERSION_AFTER_USER_AGENT_SIZE; - /// The largest batch that `headers` writes: the first count above the limit. const HEADERS_WRITTEN_COUNT_MAX: usize = super::HEADERS_COUNT_MAX + 1; - /// Checks that a `version` from `data` encodes to the bytes that its decode took, and that a - /// payload from `data` reads back: with `relay`, without it, and with bytes after it. - /// - /// The first bytes of `data` fill the fields other than the user agent, with zeros after their - /// end. The rest of `data` is the user agent, up to its limit. The committed corpus uses this - /// layout, so a change to the layout must rewrite the corpus. pub fn version(data: &[u8]) { let mut input = data; if let Ok(version) = super::Version::decode(&mut input) { version_check(&version, &data[..data.len() - input.len()], input); } - // A decoder that refuses each payload passes the check above, so read a payload that is - // valid by its layout. let written = version_write(data); version_read_all(&written, &[]); version_read_all(&written[..written.len() - size_of::()], &[]); - // The bytes after `relay` stay in `input`. A later protocol version can add fields there. version_read_all(&written, data); } - /// The fields from `data`, in the order of the payload. fn version_write(data: &[u8]) -> Vec { let mut fixed = [0; VERSION_FIXED_SIZE]; for (fixed_byte, byte) in fixed.iter_mut().zip(data) { @@ -524,8 +437,6 @@ pub(crate) mod fuzz { written } - /// Checks that `payload` and then `after` decodes, and that the decode takes each byte of - /// `payload` and no byte of `after`. fn version_read_all(payload: &[u8], after: &[u8]) { let stream = [payload, after].concat(); let mut input = stream.as_slice(); @@ -536,9 +447,6 @@ pub(crate) mod fuzz { assert_eq!(input, after); } - /// Checks that `taken`, the bytes that a decode took, are what `version` encodes to. Only - /// `relay` can differ: a decode takes any byte as a bool, or no byte as true. Only the end of - /// the input can mean that `relay` is missing, so `rest` must then be empty. fn version_check(version: &super::Version, taken: &[u8], rest: &[u8]) { let mut encoded = Vec::new(); version.encode(&mut encoded); @@ -554,27 +462,17 @@ pub(crate) mod fuzz { } } - /// Checks that the headers from `data` encode to the bytes that their decode took, and that a - /// batch from `data` reads back, or is refused only if it has too many headers. - /// - /// The first two bytes of `data`, little-endian, give the count of the batch. So a short input - /// reaches the limit and the first count above it. The bytes after them fill the headers, with - /// zeros after their end. Bytes that the headers do not use come after the batch. The committed - /// corpus uses this layout, so a change to the layout must rewrite the corpus. pub fn headers(data: &[u8]) { let mut input = data; if let Ok(headers) = super::Headers::decode(&mut input) { headers_check(headers, &data[..data.len() - input.len()]); } - // A decoder that refuses each payload passes the check above, so read a batch that is - // valid by its layout. let [count_low, count_high, bytes @ ..] = data else { return; }; let count = usize::from(u16::from_le_bytes([*count_low, *count_high])) % (HEADERS_WRITTEN_COUNT_MAX + 1); - // The bytes that the headers do not use come after the batch, and stay in `input`. let header_bytes_size = bytes.len().min(count * crate::block::BLOCK_HEADER_SIZE); let (header_bytes, after) = bytes.split_at(header_bytes_size); let mut written = headers_write(count, header_bytes); @@ -595,8 +493,6 @@ pub(crate) mod fuzz { } } - /// `count` headers from `bytes`, with zeros after their end, each with a transaction count of - /// 0. fn headers_write(count: usize, bytes: &[u8]) -> Vec { assert!(count <= HEADERS_WRITTEN_COUNT_MAX); let mut bytes = bytes.iter().copied().chain(std::iter::repeat(0)); @@ -609,13 +505,6 @@ pub(crate) mod fuzz { written } - /// Checks that `taken`, the bytes that a decode took, are what the headers encode to, each - /// with a transaction count of 0. A peer picks each `bits`, so each one also goes through the - /// proof-of-work check, which must return for any value. Regtest has the highest limit, so the - /// most values reach the compare with the hash. The `machines` script mines each header, so - /// only this fuzz target reaches a hash above its proof-of-work target. A peer picks each - /// `time`, so each one also goes through the rule of `bits` and the timewarp rule, and the - /// first ones go through the median time. fn headers_check(headers: super::Headers, taken: &[u8]) { let headers = headers.into_vec(); let mut encoded = Vec::new(); @@ -628,9 +517,6 @@ pub(crate) mod fuzz { crate::chain::fuzz::timewarp_time_min_check(header); let network = crate::chainparams::Network::Regtest; if let Some((hash, _)) = crate::pow::proven(header, network) { - // The regtest limit starts with 0x7f, so no hash that passes has a higher top byte. - // The top byte of a hash is its last byte in wire order. This rule does not call - // the check, so a check that takes too many hashes fails here. assert!(hash.as_byte_array()[31] <= 0x7f); } } @@ -644,7 +530,6 @@ pub(crate) mod fuzz { mod tests { use crate::serialize::{Decode, Encode}; - /// The fields of `VERSION_FRAME`, read by hand. fn core_version() -> super::Version { let zero = super::Address { services: super::ServiceFlags(0), @@ -667,8 +552,6 @@ mod tests { } } - /// Core's payload with another user agent. It does not call `Version::encode`, - /// so the user agent can be longer than the limit. fn payload_with_user_agent(user_agent: &[u8]) -> Vec { let mut payload = crate::fixtures::version_payload(); let start_height_and_relay = @@ -701,7 +584,6 @@ mod tests { #[test] fn batches_cut_headers_at_2000_in_order() { - // The headers need no proof of work here, so each one is genesis with its own nonce. let genesis = crate::chainparams::Network::Regtest.genesis(); for (count, expected) in [ (0, &[][..]), @@ -736,7 +618,6 @@ mod tests { let mut input = message.payload(); let headers = super::Headers::decode(&mut input).unwrap(); - // Core has only blocks 1 and 2, so the batch is not full. assert!(!headers.is_full()); let hashes: Vec<_> = headers .into_vec() @@ -757,7 +638,6 @@ mod tests { fn headers_count_is_at_most_2000() { let core = crate::fixtures::headers_payload(); let (_, entries) = core.split_first().unwrap(); - // The 80 bytes of block 1 and its transaction count. let block_1 = &entries[..80 + 1]; let mut payload = Vec::new(); crate::serialize::write_compact_size(&mut payload, 2000); @@ -768,8 +648,6 @@ mod tests { assert!(headers.is_full()); assert_eq!(headers.into_vec().len(), 2000); - // No header follows the count. A decode that reads a header first fails with - // `UnexpectedEnd`. let mut payload = Vec::new(); crate::serialize::write_compact_size(&mut payload, 2001); assert_eq!( @@ -781,7 +659,6 @@ mod tests { #[test] fn headers_refuses_a_tx_count_that_is_not_0() { let mut payload = crate::fixtures::headers_payload(); - // The transaction count of block 1, after the count and the 80 bytes of the header. let tx_count = &mut payload[1 + 80]; assert_eq!(*tx_count, 0); *tx_count = 1; @@ -794,7 +671,6 @@ mod tests { #[test] fn headers_requires_each_tx_count() { let mut payload = crate::fixtures::headers_payload(); - // The bytes stop where the transaction count of block 2 starts. A peer can send this. payload.pop(); assert_eq!( super::Headers::decode(&mut payload.as_slice()), @@ -816,8 +692,6 @@ mod tests { #[test] fn inv_has_a_block_only_with_an_entry_of_type_2() { - // 1 is a transaction, 5 a witness transaction, and 0x4000_0002 a witness block, which a - // peer asks for in a `getdata` but does not announce. for (types, has_block) in [ (&[][..], false), (&[1, 5, 0x4000_0002][..], false), @@ -842,8 +716,6 @@ mod tests { .has_block() ); - // No entry follows the count. A decode that reads an entry first fails with - // `UnexpectedEnd`. let mut payload = Vec::new(); crate::serialize::write_compact_size(&mut payload, 50_001); assert_eq!( @@ -854,7 +726,6 @@ mod tests { #[test] fn inv_requires_each_byte_of_each_entry() { - // The bytes stop in the hash of the last entry, and then in its type. let mut payload = crate::fixtures::inv_payload(&[1, 2]); for cut in [1, 32 + 1] { payload.truncate(payload.len() - cut); @@ -965,7 +836,6 @@ mod tests { #[test] fn user_agent_display_escapes_control_bytes() { - // An ANSI escape that would turn the terminal text red. let user_agent = super::UserAgent::try_from(b"/evil:\x1b[31m/".to_vec()).unwrap(); assert_eq!(user_agent.to_string(), r"/evil:\x1b[31m/"); } diff --git a/src/serialize.rs b/src/serialize.rs index 5f45c75..2b67c37 100644 --- a/src/serialize.rs +++ b/src/serialize.rs @@ -1,21 +1,12 @@ -//! The wire encoding. - -/// The largest value a CompactSize may hold. const COMPACT_SIZE_MAX: u32 = 0x0200_0000; -// A CompactSize elo accepts fits in a `usize`. const _: () = assert!(usize::BITS >= u32::BITS); -/// Why a decode failed. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Error { - /// The input ended inside a field. UnexpectedEnd, - /// A CompactSize used more bytes than its value needs. NonCanonicalCompactSize, - /// A CompactSize above `COMPACT_SIZE_MAX`. CompactSizeTooLarge(u64), - /// A string longer than its limit. StringTooLong { length: usize, length_max: usize }, } @@ -36,12 +27,10 @@ impl std::fmt::Display for Error { impl std::error::Error for Error {} -/// Writes a value in the wire encoding. pub(crate) trait Encode { fn encode(&self, out: &mut Vec); } -/// Reads a value in the wire encoding, and moves `input` past it. pub(crate) trait Decode: Sized { fn decode(input: &mut &[u8]) -> Result; } @@ -78,7 +67,6 @@ macro_rules! little_endian { little_endian!(u8, u16, u32, u64, i32, i64); -/// The bytes in the order that SHA-256 writes them. A hash shows as hex in the reverse order. impl Encode for bitcoin_hashes::sha256d::Hash { fn encode(&self, out: &mut Vec) { self.as_byte_array().encode(out); @@ -97,16 +85,12 @@ impl Encode for bool { } } -/// Any byte other than zero is true. impl Decode for bool { fn decode(input: &mut &[u8]) -> Result { Ok(u8::decode(input)? != 0) } } -/// One, three or five bytes: the shortest form that holds `value`. -/// -/// Panics if `value` is above `COMPACT_SIZE_MAX`, because a peer refuses it. pub(crate) fn write_compact_size(out: &mut Vec, value: usize) { assert!(value <= COMPACT_SIZE_MAX as usize); @@ -130,8 +114,6 @@ pub(crate) fn write_compact_size(out: &mut Vec, value: usize) { } } -/// Refuses a form longer than the value needs, and a value above `COMPACT_SIZE_MAX`. So the -/// value fits in a `usize`. pub(crate) fn read_compact_size(input: &mut &[u8]) -> Result { let (value, value_min) = match u8::decode(input)? { 0xfd => (u64::from(u16::decode(input)?), 0xfd), @@ -149,13 +131,11 @@ pub(crate) fn read_compact_size(input: &mut &[u8]) -> Result { } } -/// A CompactSize length, then the bytes. pub(crate) fn write_string(out: &mut Vec, bytes: &[u8]) { write_compact_size(out, bytes.len()); out.extend_from_slice(bytes); } -/// Refuses a string longer than `length_max` bytes. pub(crate) fn read_limited_string(input: &mut &[u8], length_max: usize) -> Result, Error> { let length = read_compact_size(input)?; if length <= length_max { @@ -167,31 +147,19 @@ pub(crate) fn read_limited_string(input: &mut &[u8], length_max: usize) -> Resul } } -/// The entry point of the `compact_size` fuzz target. #[cfg(fuzzing)] -// Only cargo-mutants reads this attribute. Its test runs do not build this module. #[cfg_attr(false, mutants::skip)] pub(crate) mod fuzz { - // The seeds hold this limit as bytes, and the check takes its limit from the same constant. So - // a new limit moves the check and not the seeds, and the replay still passes. A new limit must - // rewrite the seeds at the limit. const _: () = assert!(super::COMPACT_SIZE_MAX == 0x0200_0000); - /// Checks that a value from a read writes back as the bytes that the read took, and that a - /// value from `data` reads back after a write. - /// - /// The value is the first four bytes of `data`, little-endian, with zeros after their end. The - /// committed corpus uses this layout, so a change to the layout must rewrite the corpus. pub fn compact_size(data: &[u8]) { let mut input = data; if let Ok(value) = super::read_compact_size(&mut input) { let mut written = Vec::new(); - // A write panics above `COMPACT_SIZE_MAX`, so a read cannot let such a value through. super::write_compact_size(&mut written, value); assert_eq!(written, data[..data.len() - input.len()]); } - // A reader that refuses each value passes the check above, so read a value that elo wrote. let mut value_bytes = [0; size_of::()]; for (value_byte, byte) in value_bytes.iter_mut().zip(data) { *value_byte = *byte; diff --git a/src/transport.rs b/src/transport.rs index ed16a44..d6d9d99 100644 --- a/src/transport.rs +++ b/src/transport.rs @@ -1,20 +1,14 @@ -//! The v1 message framing. - use crate::serialize::{Decode, Encode}; -/// The size of the checksum in a message header. const CHECKSUM_SIZE: usize = 4; -/// Magic, message type, length and checksum. pub(crate) const MESSAGE_HEADER_SIZE: usize = crate::chainparams::MAGIC_SIZE + crate::protocol::MESSAGE_TYPE_SIZE + size_of::() + CHECKSUM_SIZE; -/// The longest payload a peer may send. const PAYLOAD_LENGTH_MAX: u32 = 4_000_000; -/// Why a frame was refused. Each one ends the connection. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Error { WrongMagic([u8; crate::chainparams::MAGIC_SIZE]), @@ -43,28 +37,20 @@ impl std::fmt::Display for Error { impl std::error::Error for Error {} -/// A message header that passed the checks of `decode_header`. It does not keep -/// the magic. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(crate) struct MessageHeader { msg_type: crate::protocol::MessageType, - /// The length of the payload in bytes. length: u32, - /// The start of the sha256d of the payload. checksum: [u8; CHECKSUM_SIZE], } impl MessageHeader { - /// The number of payload bytes to read next, at most `PAYLOAD_LENGTH_MAX`. pub(crate) fn payload_length(&self) -> usize { - // `decode_header` and `encode` make the only headers, and both check the length. The - // driver sizes its payload buffer with this, so it checks again before the allocation. assert!(self.length <= PAYLOAD_LENGTH_MAX); usize::try_from(self.length).expect("PAYLOAD_LENGTH_MAX fits in a usize") } } -/// A payload whose checksum matched its header. Only `check_payload` makes one. #[derive(Clone, Debug, PartialEq, Eq)] pub(crate) struct Message { msg_type: crate::protocol::MessageType, @@ -76,13 +62,11 @@ impl Message { self.msg_type } - /// The whole payload of the frame, and nothing after it. pub(crate) fn payload(&self) -> &[u8] { &self.payload } } -/// Checks the magic, the message type and the length. pub(crate) fn decode_header( network: crate::chainparams::Network, bytes: &[u8; MESSAGE_HEADER_SIZE], @@ -113,9 +97,6 @@ pub(crate) fn decode_header( } } -/// Checks the payload against the checksum in its header. -/// -/// Panics if the payload is not `header.length` bytes. The caller reads exactly that many. pub(crate) fn check_payload(header: MessageHeader, payload: Vec) -> Result { assert!(header.length <= PAYLOAD_LENGTH_MAX); assert_eq!(u32::try_from(payload.len()), Ok(header.length)); @@ -130,9 +111,6 @@ pub(crate) fn check_payload(header: MessageHeader, payload: Vec) -> Result [u8; CHECKSUM_SIZE] { let hash = bitcoin_hashes::sha256d::Hash::hash(payload).to_byte_array(); *hash.first_chunk().expect("a sha256d is 32 bytes") @@ -171,7 +147,6 @@ mod tests { frame.split_first_chunk().unwrap() } - /// A regtest frame's header, decoded, and its payload. fn decode(frame: &[u8]) -> (super::MessageHeader, &[u8]) { let (header, payload) = split(frame); ( diff --git a/tests/bitcoind.rs b/tests/bitcoind.rs index 0d75ca8..12d660f 100644 --- a/tests/bitcoind.rs +++ b/tests/bitcoind.rs @@ -1,48 +1,31 @@ -//! elo against a real `bitcoind -regtest`. `BITCOIND` and `BITCOIN_CLI` hold the paths of the -//! binaries. - -/// How long `bitcoind` may take to answer RPC after its warmup. const READY_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); -/// How long `bitcoin-cli` may wait for the reply to one request. const RPC_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); -/// How long `getpeerinfo` may take to show what a test waits for. const PEER_INFO_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); -/// How long elo may take to log the end of a connection: after `bitcoind` closes it, or after -/// the start when the first write to stdout fails. const END_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); -/// How long elo may take to do the handshake again after the end of a connection. It waits 5 s -/// before it dials again. const RECONNECT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); -/// How long elo may take to sync the headers of `bitcoind` and log its tip. const SYNC_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); -/// How long elo may take to exit after a signal. Below the wait of 5 s before a dial, so a -/// signal in that wait must end it, and not the next dial. const STOP_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(2); -/// A directory that the drop removes. struct TempDir(std::path::PathBuf); impl Drop for TempDir { fn drop(&mut self) { - // A panic in a drop during a panic aborts the tests, so a failure is only printed. if let Err(error) = std::fs::remove_dir_all(&self.0) { eprintln!("remove {}: {error}", self.0.display()); } } } -/// A child process that the drop kills. struct Process(std::process::Child); impl Drop for Process { fn drop(&mut self) { - // A panic in a drop during a panic aborts the tests, so a failure is only printed. if let Err(error) = self.0.kill() { eprintln!("kill process {}: {error}", self.0.id()); } @@ -52,8 +35,6 @@ impl Drop for Process { } } -/// A `bitcoind -regtest` in its own datadir, with RPC on. The fields drop in order, so the -/// datadir goes after the kill. struct Bitcoind { process: Process, peer: std::net::SocketAddr, @@ -64,14 +45,9 @@ struct Bitcoind { impl Bitcoind { fn start() -> Self { let path = std::env::var_os("BITCOIND").expect("BITCOIND holds the path of bitcoind"); - // The tests run in parallel, and the OS can give the same free port to two of them. So - // each test holds this lock from the pick of its ports until its `bitcoind` listens on - // them. The OS does not give a port with a listener again. let lock = std::fs::File::create(std::env::temp_dir().join("elo-bitcoind.lock")).unwrap(); lock.lock().unwrap(); - // Two ports that were free a moment ago. Both listeners are open at the same time, so - // the ports differ. let peer_listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let rpc_listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let peer = peer_listener.local_addr().unwrap(); @@ -79,10 +55,6 @@ impl Bitcoind { drop(peer_listener); drop(rpc_listener); - // In the target directory, because nextest stops a test with a signal, and then no drop - // runs. A mutant run removes each target directory, and nothing removes the temp directory - // of `nix develop`. The lock stays in that temp directory: the two jobs of a mutant run - // have different target directories, and their tests also take ports. let datadir = TempDir( std::path::Path::new(env!("CARGO_TARGET_TMPDIR")).join(format!( "elo-bitcoind-{}-{}", @@ -97,13 +69,8 @@ impl Bitcoind { .arg(format!("-datadir={}", datadir.0.display())) .arg(format!("-bind={peer}")) .arg("-listenonion=0") - // bitcoind asks the router to map its port by default. A test must not. .arg("-natpmp=0") - // RPC uses cookie auth. The cookie is in the datadir, where `bitcoin-cli` reads it. .arg("-server=1") - // `-rpcbind` needs `-rpcallowip`, which adds nothing: loopback is always allowed. - // With one RPC address, a port that another process took makes `bitcoind` exit, as - // a taken P2P port does. .arg("-rpcallowip=127.0.0.1") .arg("-rpcbind=127.0.0.1") .arg(format!("-rpcport={rpc_port}")) @@ -122,9 +89,6 @@ impl Bitcoind { bitcoind } - /// Waits until an RPC call with the cookie in our datadir succeeds. Each call fails until - /// the warmup ends, and the warmup ends only after the P2P bind. So a success proves that - /// both ports belong to this `bitcoind`, and not to another process that took a port first. fn wait_until_ready(&mut self) { let start = std::time::Instant::now(); while !self.rpc(&["uptime"]).status.success() { @@ -134,7 +98,6 @@ impl Bitcoind { } } - /// Runs the RPC `command` with `bitcoin-cli` and returns its output. fn cli(&self, command: &[&str]) -> String { let output = self.rpc(command); let stderr = String::from_utf8_lossy(&output.stderr); @@ -142,7 +105,6 @@ impl Bitcoind { String::from_utf8(output.stdout).unwrap() } - /// One `bitcoin-cli` request, with no retry. It waits at most `RPC_TIMEOUT` for the reply. fn rpc(&self, command: &[&str]) -> std::process::Output { let path = std::env::var_os("BITCOIN_CLI").expect("BITCOIN_CLI holds the path of bitcoin-cli"); @@ -185,7 +147,6 @@ fn handshake_with_bitcoind_returns_its_version() { #[test] fn stdout_error_after_the_handshake_exits_with_1() { let bitcoind = Bitcoind::start(); - // The pipe has no reader, so the first write to stdout fails. let (reader, writer) = std::io::pipe().unwrap(); drop(reader); let mut elo = Process( @@ -199,13 +160,9 @@ fn stdout_error_after_the_handshake_exits_with_1() { ); let stderr = lines(elo.0.stderr.take().unwrap()); - // The test waits for the line with a deadline, and not for the exit: an elo that dials - // again does not exit, and the drop kills it. let end = stderr .recv_timeout(END_TIMEOUT) .expect("elo wrote no exit line"); - // An end that the peer causes dials again, so the exit comes from stdout. stdout failed, so - // the line is on stderr. assert!( end.starts_with("level=error event=exit reason=\"stdout: "), "{end}" @@ -216,7 +173,6 @@ fn stdout_error_after_the_handshake_exits_with_1() { #[test] fn ping_from_bitcoind_gets_a_pong() { let bitcoind = Bitcoind::start(); - // elo does not exit while the connection is up, so the drop kills it. let mut elo = Process( std::process::Command::new(env!("CARGO_BIN_EXE_elo")) .arg("regtest") @@ -226,8 +182,6 @@ fn ping_from_bitcoind_gets_a_pong() { .unwrap(), ); - // bitcoind pings right after the handshake. It shows a `pingtime` only after a `pong` with - // the nonce of its `ping`. elo is its only peer, so a match on the text is enough. let start = std::time::Instant::now(); while !bitcoind.cli(&["getpeerinfo"]).contains("\"pingtime\"") { assert_eq!(elo.0.try_wait().unwrap(), None, "elo exited"); @@ -244,9 +198,6 @@ fn our_ping_gets_a_pong_from_bitcoind() { let bitcoind = Bitcoind::start(); let elo = Elo::start(&bitcoind); - // elo pings right after the handshake, and bitcoind sends a `pong` only to a `ping`. The - // wait also needs our `pong` to the `ping` of bitcoind, the last message that elo sends. A - // close with bytes that bitcoind has not read is a reset, and not the end of the stream. let start = std::time::Instant::now(); loop { let peer_info = bitcoind.cli(&["getpeerinfo"]); @@ -258,8 +209,6 @@ fn our_ping_gets_a_pong_from_bitcoind() { { break; } - // An early end does not exit elo: it dials again, and then node 0 is gone. So the test - // fails here, with the reason of elo, and not on `disconnectnode`. let ends = elo.events("end"); assert!(ends.is_empty(), "elo ended the connection: {ends:?}"); assert!( @@ -269,9 +218,6 @@ fn our_ping_gets_a_pong_from_bitcoind() { std::thread::sleep(std::time::Duration::from_millis(100)); } - // elo is the only peer of bitcoind, so it is node 0. TCP delivers the `pong` before the - // close, so elo checks the `pong` first. A `pong` that elo refuses ends with its reason, - // and so does a second `pong` for a stray `ping`. bitcoind.cli(&["-named", "disconnectnode", "nodeid=0"]); let end = elo.event("end", END_TIMEOUT); assert_eq!( @@ -289,9 +235,6 @@ fn closed_connection_gets_a_new_handshake_and_sync() { let elo = Elo::start(&bitcoind); let tip = elo.event("tip", SYNC_TIMEOUT); - // elo is the only peer of bitcoind, so it is node 0. The test does not check the reason of - // the end: bitcoind can close with bytes from elo that it has not read, and then elo sees a - // reset. let close = std::time::Instant::now(); bitcoind.cli(&["-named", "disconnectnode", "nodeid=0"]); elo.event("end", END_TIMEOUT); @@ -301,7 +244,6 @@ fn closed_connection_gets_a_new_handshake_and_sync() { bitcoind.peer ); assert!(version.starts_with(&expected), "{version}"); - // The close comes after `close`, and the wait of 5 s comes after the close. let wait = close.elapsed(); assert!(wait >= std::time::Duration::from_secs(5), "{wait:?}"); assert_eq!(elo.event("tip", SYNC_TIMEOUT), tip); @@ -313,8 +255,6 @@ fn peer_with_a_name_gets_a_lookup_and_a_dial_to_its_address() { let named = format!("localhost:{}", bitcoind.peer.port()); let elo = Elo::start_on(&named); - // `localhost` can also have `::1`, where bitcoind does not listen. elo tries each address of - // the name in one dial, so the first dial gets to bitcoind, with no `end` before it. let version = elo.event("version", SYNC_TIMEOUT); let expected = format!( "level=info event=version peer={} version=70016 ", @@ -324,8 +264,6 @@ fn peer_with_a_name_gets_a_lookup_and_a_dial_to_its_address() { let ends = elo.events("end"); assert!(ends.is_empty(), "{ends:?}"); - // The `end` has the name, because the next dial looks it up again. elo is the only peer of - // bitcoind, so it is node 0. elo.event("tip", SYNC_TIMEOUT); bitcoind.cli(&["-named", "disconnectnode", "nodeid=0"]); let end = elo.event("end", END_TIMEOUT); @@ -338,7 +276,6 @@ fn peer_with_a_name_gets_a_lookup_and_a_dial_to_its_address() { #[test] fn signal_in_a_connection_exits_with_0() { let bitcoind = Bitcoind::start(); - // elo exits each time, so the next elo is again the only peer of bitcoind. for signal in ["TERM", "INT"] { let mut elo = Elo::start(&bitcoind); elo.event("tip", SYNC_TIMEOUT); @@ -357,7 +294,6 @@ fn signal_in_the_wait_before_a_dial_exits_with_0() { let mut elo = Elo::start(&bitcoind); elo.event("tip", SYNC_TIMEOUT); - // elo is the only peer of bitcoind, so it is node 0. elo logs the end, and then it waits 5 s. bitcoind.cli(&["-named", "disconnectnode", "nodeid=0"]); let end = elo.event("end", END_TIMEOUT); assert!(end.ends_with(" wait_ms=5000"), "{end}"); @@ -383,22 +319,12 @@ fn next_connection_syncs_from_our_tip_and_keeps_it_against_a_branch_with_the_sam let tip = elo.event("tip", SYNC_TIMEOUT); assert!(tip.starts_with(&ours), "{tip}"); - // elo is the only peer of bitcoind, so it is node 0. elo ends no connection of its own here, - // so the close does not race elo. The test does not check the reason of this end: bitcoind - // can close with bytes from elo that it has not read, and then elo sees a reset. bitcoind.cli(&["-named", "disconnectnode", "nodeid=0"]); elo.event("end", END_TIMEOUT); - // In the wait before the next dial, bitcoind leaves our tip for a block on genesis. The block - // pays another script, because the same script in the same second makes the block that - // bitcoind marked invalid. bitcoind.cli(&["invalidateblock", first.trim_end()]); bitcoind.cli(&["generatetodescriptor", "1", "raw(52)"]); - // The next connection asks with the locator of our chain: our tip, then genesis. bitcoind - // does not have our tip on its chain, so it sends its block after genesis. That branch has the - // work of ours, and our branch came first, so it stays. A chain from genesis would take the - // block of bitcoind. let tip = elo.event("tip", RECONNECT_TIMEOUT); assert!(tip.starts_with(&ours), "{tip}"); let ends = elo.events("end"); @@ -408,8 +334,6 @@ fn next_connection_syncs_from_our_tip_and_keeps_it_against_a_branch_with_the_sam #[test] fn branch_with_more_work_that_bitcoind_announces_takes_the_place_of_ours() { let bitcoind = Bitcoind::start(); - // Block 1, then a branch of 2 on genesis with another script, which bitcoind leaves for block - // 1 again. So elo syncs to block 1, and bitcoind has the branch. bitcoind.cli(&["generatetodescriptor", "1", "raw(51)"]); let first = bitcoind.cli(&["getbestblockhash"]); bitcoind.cli(&["invalidateblock", first.trim_end()]); @@ -427,13 +351,8 @@ fn branch_with_more_work_that_bitcoind_announces_takes_the_place_of_ours() { ); assert!(tip.starts_with(&expected), "{tip}"); - // bitcoind announces the branch with a `headers` only after our `sendheaders`. wait_for_send_headers(&bitcoind, &elo); - // bitcoind goes to the branch, which has more work, in one step. So one announcement has both - // blocks, on genesis. It is not on our tip, so elo asks with the locator of our chain: our tip, - // then genesis. bitcoind does not have our tip on its chain, so it answers with the branch - // after genesis, and our chain takes it on this connection. bitcoind.cli(&["reconsiderblock", branch.trim_end()]); let tip = elo.event("tip", SYNC_TIMEOUT); let chain_work = bitcoind.cli(&["getblockheader", best.trim_end()]); @@ -453,7 +372,6 @@ fn branch_with_more_work_that_bitcoind_announces_takes_the_place_of_ours() { #[test] fn sync_from_bitcoind_logs_its_tip() { let bitcoind = Bitcoind::start(); - // 2001 blocks: a full batch of 2000 headers, our next `getheaders`, and a batch of 1. bitcoind.cli(&["generatetodescriptor", "2001", "raw(51)"]); let best = bitcoind.cli(&["getbestblockhash"]); let elo = Elo::start(&bitcoind); @@ -473,19 +391,14 @@ fn sync_from_bitcoind_logs_its_tip() { #[test] fn block_that_bitcoind_mines_after_the_sync_logs_the_next_tip() { let bitcoind = Bitcoind::start(); - // bitcoind announces no block in its initial block download. On regtest, a block with a recent - // time ends it. bitcoind.cli(&["generatetodescriptor", "1", "raw(51)"]); let elo = Elo::start(&bitcoind); elo.event("tip", SYNC_TIMEOUT); - // Without our `sendheaders`, bitcoind announces the block with an `inv`. So the test waits - // until bitcoind has it, and then mines. wait_for_send_headers(&bitcoind, &elo); bitcoind.cli(&["generatetodescriptor", "1", "raw(51)"]); let best = bitcoind.cli(&["getbestblockhash"]); - // The `headers` of the announcement goes on our tip, as a batch of a sync. let tip = elo.event("tip", SYNC_TIMEOUT); let chain_work = bitcoind.cli(&["getblockheader", best.trim_end()]); let chain_work = string_field(&chain_work, "chainwork"); @@ -497,7 +410,6 @@ fn block_that_bitcoind_mines_after_the_sync_logs_the_next_tip() { best.trim_end() ) ); - // The same connection took it. let ends = elo.events("end"); assert!(ends.is_empty(), "elo ended the connection: {ends:?}"); } @@ -505,7 +417,6 @@ fn block_that_bitcoind_mines_after_the_sync_logs_the_next_tip() { #[test] fn reorg_that_bitcoind_announces_with_an_inv_makes_elo_ask_for_the_headers() { let bitcoind = Bitcoind::start(); - // Block 1, then a branch of 30 blocks on it, which bitcoind leaves. So elo syncs to block 1. bitcoind.cli(&["generatetodescriptor", "1", "raw(51)"]); bitcoind.cli(&["generatetodescriptor", "30", "raw(51)"]); let best = bitcoind.cli(&["getbestblockhash"]); @@ -517,7 +428,6 @@ fn reorg_that_bitcoind_announces_with_an_inv_makes_elo_ask_for_the_headers() { assert!(tip.starts_with(&expected), "{tip}"); wait_for_send_headers(&bitcoind, &elo); - // A second branch of 29 blocks on block 1, with another script. elo follows it to height 30. bitcoind.cli(&["generatetodescriptor", "29", "raw(52)"]); let ours = bitcoind.cli(&["getbestblockhash"]); let expected = format!( @@ -533,12 +443,6 @@ fn reorg_that_bitcoind_announces_with_an_inv_makes_elo_ask_for_the_headers() { ); } - // bitcoind goes back to the first branch, which has more work, in one step. It announces - // only the last 8 blocks of the step, and elo does not have the block below them. So the - // announcement is an `inv`, and so is each later one. Only our `getheaders` gets the chain. - // No hash of our locator below our tip is on the first branch but genesis, so the answer is - // on genesis. It has block 1 again, and the first branch. That has more work than ours, so our - // chain takes it on this connection. bitcoind.cli(&["reconsiderblock", second.trim_end()]); let tip = elo.event("tip", SYNC_TIMEOUT); let chain_work = bitcoind.cli(&["getblockheader", best.trim_end()]); @@ -558,9 +462,6 @@ fn reorg_that_bitcoind_announces_with_an_inv_makes_elo_ask_for_the_headers() { #[test] fn branch_that_bitcoind_sends_in_two_batches_takes_the_place_of_ours() { let bitcoind = Bitcoind::start(); - // Block 1 and 2,100 blocks on it, then a branch of 2,200 on block 1 with another script, which - // bitcoind leaves for the first branch again. So elo syncs to block 2,101, and bitcoind has - // the second branch. bitcoind.cli(&["generatetodescriptor", "2101", "raw(51)"]); let second = bitcoind.cli(&["getblockhash", "2"]); bitcoind.cli(&["invalidateblock", second.trim_end()]); @@ -575,11 +476,6 @@ fn branch_that_bitcoind_sends_in_two_batches_takes_the_place_of_ours() { assert!(tip.starts_with(&expected), "{tip}"); wait_for_send_headers(&bitcoind, &elo); - // bitcoind goes to the second branch, which has more work. elo asks with the locator of our - // chain, and no hash of it below our tip is on the second branch but genesis. So the answer - // is a full batch on genesis: our block 1, then 1,999 blocks of the branch. These have less - // work than our 2,100 blocks above block 1, so elo asks for the headers after the last of - // them. The next 201 give the branch more work, and our chain takes it on this connection. bitcoind.cli(&["reconsiderblock", branch.trim_end()]); let tip = elo.event("tip", SYNC_TIMEOUT); let chain_work = bitcoind.cli(&["getblockheader", best.trim_end()]); @@ -599,9 +495,6 @@ fn branch_that_bitcoind_sends_in_two_batches_takes_the_place_of_ours() { #[test] fn branch_below_the_margin_takes_the_place_of_ours_after_a_low_work_sync() { let bitcoind = Bitcoind::start(); - // Block 1 and 3,000 blocks on it, then a branch of 3,100 on block 1 with another script, which - // bitcoind leaves for the first branch again. So elo syncs to block 3,001, and bitcoind has - // the second branch. bitcoind.cli(&["generatetodescriptor", "3001", "raw(51)"]); let second = bitcoind.cli(&["getblockhash", "2"]); bitcoind.cli(&["invalidateblock", second.trim_end()]); @@ -616,11 +509,6 @@ fn branch_below_the_margin_takes_the_place_of_ours_after_a_low_work_sync() { assert!(tip.starts_with(&expected), "{tip}"); wait_for_send_headers(&bitcoind, &elo); - // bitcoind goes to the second branch, which has more work. The answer to our locator is our - // block 1 and 1,999 blocks of the branch, so the next batch goes on block 1. It has 2,000 - // blocks of the branch, and they have less work than our 3,000 blocks above block 1 by more - // than 144 blocks. So elo gets the branch twice in a low-work sync from block 1, and our - // chain takes it on this connection. bitcoind.cli(&["reconsiderblock", branch.trim_end()]); let tip = elo.event("tip", SYNC_TIMEOUT); let chain_work = bitcoind.cli(&["getblockheader", best.trim_end()]); @@ -637,8 +525,6 @@ fn branch_below_the_margin_takes_the_place_of_ours_after_a_low_work_sync() { assert!(ends.is_empty(), "elo ended the connection: {ends:?}"); } -/// Waits until `bitcoind` got our `sendheaders`, which elo sends after the sync. Then bitcoind -/// announces each new block on our tip with a `headers`. Panics if `elo` ends the connection. fn wait_for_send_headers(bitcoind: &Bitcoind, elo: &Elo) { let start = std::time::Instant::now(); loop { @@ -656,16 +542,11 @@ fn wait_for_send_headers(bitcoind: &Bitcoind, elo: &Elo) { } } -/// elo connected to a `bitcoind`, with the log lines of its stdout and the lines of its stderr. -/// elo does not exit while it can dial the peer, so the drop kills it. struct Elo { process: Process, stdout: std::sync::mpsc::Receiver, stderr: std::sync::mpsc::Receiver, - /// Each line of stdout that `event` or `events` read, in order. read: std::cell::RefCell>, - /// How many lines of `read` the calls of `event` went past. `events` can read lines after - /// them, and the next `event` starts at the first of those. passed: std::cell::Cell, } @@ -674,7 +555,6 @@ impl Elo { Self::start_on(&bitcoind.peer.to_string()) } - /// elo on regtest with `peer` as the peer of its command line. fn start_on(peer: &str) -> Self { let mut child = std::process::Command::new(env!("CARGO_BIN_EXE_elo")) .arg("regtest") @@ -694,9 +574,6 @@ impl Elo { } } - /// The next log line of the event `name`, after the line that the last `event` gave. It skips - /// the lines before it, also lines that `events` read, and panics if none comes within - /// `timeout`. fn event(&self, name: &str, timeout: std::time::Duration) -> String { let deadline = std::time::Instant::now() + timeout; loop { @@ -711,7 +588,6 @@ impl Elo { let left = deadline.saturating_duration_since(std::time::Instant::now()); match self.stdout.recv_timeout(left) { Ok(line) => self.read.borrow_mut().push(line), - // The thread ends only when the pipe ends, so elo exited, and its stderr ends. Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => { let stderr = self.stderr.iter().collect::>().join("\n"); panic!("elo exited: {:?} {stderr}", self.read.borrow()) @@ -725,7 +601,6 @@ impl Elo { } } - /// Each log line of the event `name` from the start of elo up to now. fn events(&self, name: &str) -> Vec { let mut read = self.read.borrow_mut(); read.extend(self.stdout.try_iter()); @@ -735,8 +610,6 @@ impl Elo { .collect() } - /// Sends the signal `name`, for example `TERM`, to elo. The `kill` of coreutils, because - /// `std` sends only SIGKILL. fn signal(&self, name: &str) { let status = std::process::Command::new("kill") .arg("-s") @@ -747,8 +620,6 @@ impl Elo { assert!(status.success(), "kill -s {name}: {status}"); } - /// The exit code of elo, which must exit within `STOP_TIMEOUT`. `None` is an end by a - /// signal. fn exit_code(&mut self) -> Option { let deadline = std::time::Instant::now() + STOP_TIMEOUT; loop { @@ -765,13 +636,10 @@ impl Elo { } } -/// The name of the event of a log `line`: its second field. fn event_name(line: &str) -> Option<&str> { line.split(' ').nth(1)?.strip_prefix("event=") } -/// Each line of `pipe`, from a thread. Each test waits for a line with a timeout, and elo does -/// not exit, so a read on the test thread can block forever. The channel ends when the pipe ends. fn lines(pipe: impl std::io::Read + Send + 'static) -> std::sync::mpsc::Receiver { let (sender, receiver) = std::sync::mpsc::channel(); std::thread::spawn(move || { @@ -784,15 +652,12 @@ fn lines(pipe: impl std::io::Read + Send + 'static) -> std::sync::mpsc::Receiver receiver } -/// The value of the string `field` in `object`, as `bitcoin-cli` writes it. fn string_field<'a>(object: &'a str, field: &str) -> &'a str { let key = format!("\"{field}\": \""); let (_, rest) = object.split_once(&key).unwrap(); rest.split_once('"').unwrap().0 } -/// The text of the `field` object in `getpeerinfo`, or nothing before elo connects. elo is the -/// only peer, and the object holds no other object, so it ends at its first `}`. fn object_text<'a>(peer_info: &'a str, field: &str) -> &'a str { let key = format!("\"{field}\": {{"); let Some((_, rest)) = peer_info.split_once(&key) else {