Skip to content

feat: with no peer, dial a seed of the network at random, and only its answers that the internet routes to (#44) - #90

Merged
lorenzolfm merged 6 commits into
mainfrom
seeds
Nov 14, 2026
Merged

lorenzolfm merged 6 commits into
mainfrom
seeds

Conversation

@lorenzolfm

@lorenzolfm lorenzolfm commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Part of #44. Slice 2: the seeds of the network when the command line names no peer.

What

  • The peer is optional: elo <network> [<ip|name>[:port]]. With no peer, each dial uses a seed of the network.
  • chainparams::Network::seeds gives the DNS seeds of each network: 8 for mainnet, 2 for testnet4, 2 for signet. Regtest has none, so elo regtest with no peer is bad usage (exit 2). The usage text says so.
  • net::Source is what the command line names: Destination(Destination), the same for each dial, or Seeds(Seeds). Source::destination gives the destination of the next dial. Only Seeds::new makes a Seeds, and it refuses a network with no seeds, so a Seeds has at least one seed.
  • For each dial, Seeds chooses one seed at random: the seed with the lowest hash under a new RandomState.
  • Destination::Seed { seed, port } is a third kind of destination. Only Seeds makes a Seed, so it is on the list of its network. The dial looks up x9.<seed>: the nodes with NODE_NETWORK and NODE_WITNESS. If that lookup fails or gives no address to dial, it looks up the seed itself. If that lookup times out, the dial ends.
  • Of the answers of a seed, elo dials only the addresses that the internet routes to (not is_reserved), and at most 32 of them. These do not pass: 0.0.0.0/8, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10, 198.18.0.0/15, the 3 IPv4 documentation ranges, 255.255.255.255, ::, ::1, fc00::/7, fe80::/10, 2001:db8::/32, 2001:10::/28 and 2001:20::/28. An IPv4 address in IPv6 is checked as the IPv4 address. A name that you type keeps the filter of feat: take a name as the peer, look it up before each dial, and dial its addresses in a random order until one takes the connect (#44) #89 only: no 0.0.0.0 or ::.
  • dial_order::<COUNT_MAX> takes PeerAddress values. The count max is a const parameter, and const { assert!(COUNT_MAX <= ADDRESSES_COUNT_MAX) } checks it when it compiles. After the pop, it asserts before.len() < COUNT_MAX, because connect_first checks only ADDRESSES_COUNT_MAX. name_order (cap 256) and seed_order (cap 32, routable only) do the filter before it.
  • The end line has the destination of the dial. For a seed it is the seed, such as destination=seed.bitcoin.sipa.be.:8333.
  • LookupError::Timeout { host } names the host that timed out: the lookup of x9.<seed> took longer than 30 s. The destination of the end line is the seed itself, so without the host a timeout of x9.<seed> looks like a timeout of the seed.
  • protocol::ServiceFlags::NETWORK_WITNESS (0x9).
  • README: the usage, the seeds, the destination of a seed. A separate commit fixes the README: a log value is at most 260 bytes, not 256.
  • Tests:
    • no_peer_is_the_seeds_of_the_network, and ["regtest"] and ["testnet3"] rows in the usage test.
    • each_network_but_regtest_has_seeds_that_are_names_at_its_default_port: each seed and each x9.<seed> is a Name, so it fits in a log value.
    • a_seeds_source_chooses_each_seed_of_the_network: 1000 choices reach each of the 8 mainnet seeds.
    • routable_is_each_address_but_this_host_private_networks_links_and_test_ranges: the first and last address of each range, and the addresses next to them.
    • seed_order_keeps_at_most_the_seed_count_max_of_the_routable_answers.
  • Proof:
    • 217 tests pass in a netns, 15 of them L3. nix flake check passes.
    • cargo mutants --in-diff on the last 2 commits: 9 mutants, 4 caught, 5 unviable.
    • cargo mutants --in-diff on the first feat commit: 67 mutants, 49 caught, 15 unviable, 3 missed. The 3 do not change what elo does. < to > or <= in Seeds::choose takes the seed with the highest hash, which is just as random, and two equal hashes do not occur. 1 | 1 << 3 to 1 ^ 1 << 3 is also 9, so the value is now 0b1001.
    • 4 hand mutants, and a test catches each one: no routability filter, the first seed each time, a cap of 256 for a seed, and no x9.. No test catches a dial without the second lookup (see "Not confident").
    • Real dials with no peer: mainnet 3 of 3 and signet 2 of 2 got a version. Testnet4 8 of 8: 4 peers came from x9.seed.testnet4.bitcoin.sprovoost.nl., and 4 came from seed.testnet4.wiz.biz. through the second lookup.
    • Real testnet4 sync with no peer, for 15 min (on the build before the second lookup): it synced from genesis to 161322 from a peer of x9.seed.testnet4.bitcoin.sprovoost.nl., and logged 4 more tips after that. Its first dial got x9.seed.testnet4.wiz.biz., which failed with Name or service not known. That failure is the reason for the second lookup.
    • elo regtest with no peer prints the usage and exits with 2.

Why

One seed for each dial, at random. Each seed gets the same part of the dials, also a seed that gives few answers. A seed that gives many answers gets no more. One lookup for each dial sends the fewest DNS questions. A dial that fails goes to another seed after 5 s, with the retry of #42. Rejected: a lookup of all the seeds, with the answers mixed. Then a seed that gives more answers chooses more of the peers. Mixing seeds and trust in a seed are still open on #44.

x9.<seed>, then the seed itself. A seed answers x9.<seed> with nodes that serve each block and its witness data. Block download (#62) needs those nodes. A timeout gets no second lookup: the resolver does not answer, so the second lookup would only wait 30 s again. seed.testnet4.wiz.biz. has no x<bits>. names: x1, x5, x8, x9, xd and x809 give no address, and the seed itself gives 22. Without the second lookup, half of the testnet4 dials fail. A node from the second lookup can have other services. The header sync needs none, because elo asks only for headers.

Only the answers that the internet routes to. The person who runs elo did not choose the answers of a seed. A seed can give the address of a host on the network of elo, such as a router or a service on 127.0.0.1. The ranges are the ones that Bitcoin nodes refuse as addresses of peers. For a name that you type, the address can be on this host or on your network, so that filter does not apply. fe80::/10 is a little wider than fe80::/64. The rest of fe80::/10 is not routable either. Multicast and 240.0.0.0/4 pass, and their connect fails.

At most 32 addresses of a seed. A seed whose answers are down costs at most 32 connect timeouts, 160 s, before the next seed. With 256, that is about 21 min. One DNS answer over UDP has room for about 30 addresses.

Source, and not a third case in Destination alone. A Destination is what one dial looks up, and the end line shows it. With seeds, each dial has another one. Source holds the choice, and Destination::Seed holds the seed of one dial. So the end line shows which seed gave the peer, or which seed failed. Rejected: destination=seeds. Then the log does not show a seed that is down.

A Seeds has at least one seed. Seeds::new refuses regtest, and parse gives bad usage for it. So no dial can choose from an empty list, and the choice needs no check. Rejected: the dummy seed of regtest. A lookup that always fails would retry each 5 s forever.

No new dependency. The random choice uses RandomState, as the order of the addresses does.

Not confident:

…cap of a seed in `dial_order` (#44)

- A timeout of the `x9.<seed>` lookup ends the dial. The resolver does not answer, so a lookup of the seed itself only waits `LOOKUP_TIMEOUT` again. A failed lookup or no address still looks up the seed itself. The match names each `LookupError`, so a new error needs a choice here.
- The doc of `Destination::Seed` and the README say that a failed lookup also gives the lookup of the seed itself. Before, they said only "no address".
- `lookup` gives the iterator of the resolver, and not a `Vec`. `name_order` and `seed_order` take at most their count max of it, so a lookup with many answers does not copy them all.
- `dial_order` asserts `before.len() < count_max` after the `pop`. `connect_first` checks only `ADDRESSES_COUNT_MAX`, so before, no check held the cap of 32 for a seed.
- `is_routable` is now `is_reserved`, with no `!` on its 8 and 6 terms. `seed_order` keeps an address that is not reserved. `is_benchmarking` uses a range, as `is_shared` does.
…iler checks it against `ADDRESSES_COUNT_MAX` (#44)

- `dial_order::<COUNT_MAX>` takes the cap as a const parameter. Its only values are `ADDRESSES_COUNT_MAX` and `SEED_ADDRESSES_COUNT_MAX`, so a run-time `assert!` on the argument checked a fact that the build knows.
- `const { assert!(COUNT_MAX <= ADDRESSES_COUNT_MAX) }` checks each cap when it compiles. A cap of 257 does not compile.
- The `const _` assert on `SEED_ADDRESSES_COUNT_MAX` goes: the check in `dial_order` holds each cap that a caller uses.
- The assert of `before.len() < COUNT_MAX` after the `pop` stays.
…a seed shows which of its two lookups did not end (#44)

- `LookupError::Timeout` has the `host` that `lookup` looked up. Its text is `the lookup of <host> took longer than 30 s`.
- A dial to a seed looks up `x9.<seed>`, and then the seed itself. Before, a timeout of each one gave the same `reason`, and the `destination` of the `end` line is the seed itself. So a timeout of `x9.<seed>` looked like a timeout of the seed, which can answer.
- The seed arm of `addresses` gives the timeout of `x9.<seed>` as it is, with no copy of the variant.
- Rejected: a `ServicesTimeout` variant only for `x9.<seed>`. The match on the result of `seed_order` then needs an arm for a variant that `lookup` never gives.
…rison is left that a mutant can flip with no change of the choice (#44)
@lorenzolfm
lorenzolfm merged commit c67f38e into main Nov 14, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant