BUIP018 (passed): Bitnodes Seeding and User-Configurable DNS Seeds


Nov 19, 2015
BUIP018: Bitnodes Seeding and User-Configurable DNS Seeds
Proposer: Simon Liu
Submitted on: 2 April 2016


Improve seeding so that a client can quickly and reliably find peers when trying to connect to the network. Currently Bitcoin relies on hard-coded DNS seed addresses and hard-coded IP addresses of nodes. It is not possible for users to change the DNS seeds unless they can compile the software themselves. Relying on hard-coded IP addresses is fragile.


This BUIP intends to:

1. Obtain peer addresses from the public Bitnodes API [1] operated by 21.co. The Bitnodes software itself is open-source [2]. Active peers are obtained from the Bitnodes Leaderboard [3].

2. Improve DNS seeding by:
(a) Enabling users to specify custom DNS seed hosts in bitcoin.conf and via command-line options. New options are 'bitnodes', 'forcebitnodes', 'usednsseed'.
(b) Update the default DNS seed addresses to represent a variety of community sources with reliable uptime (using data from bitcoinstats.com)

3. Remove mainnet usage of hard-coded node IP addresses as they are likely to be stale and no longer active.


Code is available for review: https://github.com/bitcartel/BitcoinUnlimited/commits/0.12bu.bitnodes

Pull request against BU 0.12: https://github.com/BitcoinUnlimited/BitcoinUnlimited/pull/30

The hard-coded DNS seeds have been updated to reflect a cross-section of the Bitcoin community, so that the client is no longer relying on just volunteer seeds (with variable uptime based on recent data from bitcoinstats.com): BTCC, Bitnodes, Pieter Wuille . More can be added over time, with a preference for individuals and institutions with the resources to maintain uptime of their Bitcoin related infrastructure [4].

By default, accessing the public API at bitnodes.21.co is enabled - just like DNS seeding which also remains enabled. Thus a client will bootstrap onto the network by obtaining peers from these two different approaches.

Example usage:

To disable Bitnodes:

bitcoind -bitnodes=0

To always query for peer addresses via Bitnodes API, even if many peers already known:

bitcoind -forcebitnodes=1

Use custom DNS seeds and over-ride client defaults:

bitcoind -usednsseed=seed.bitnodes.io -usednsseed=seed.btcc.com

To verify that hard-coded node addresses are no longer used, disable Bitnodes and DNS seeding. When launching Bitcoin for the first time (i.e. peers.dat does not exist) the client will never connect to the network.

bitcoind -dnsseed=0 -bitnodes=0


[1] https://bitnodes.21.co/api/
[2] https://github.com/ayeowch/bitnodes
[3] https://bitnodes.21.co/nodes/leaderboard/
[4] http://www.coindesk.com/press-releases/btcc-deploys-100-full-bitcoin-nodes-across-five-continents/
“Refactor hard-coded DNS seeds into configuration file” (Jan 2016) - https://bitco.in/forum/threads/refactor-hard-coded-dns-seeds-into-configuration-file.743/
Last edited:

Peter Tschipper

Active Member
Jan 8, 2016
I haven't looked over the fine details but I like the idea. Just need to make sure that if the public seed nodes such as bitnodes are down that we can still get seeds in some manner but it looks like you have that covered.
  • Like
Reactions: freetrader