zcash-seeder
==============

Zcash-seeder is a crawler for the Zcash network, which exposes a list
of reliable nodes via a built-in DNS server.

Features:
* regularly revisits known nodes to check their availability
* bans nodes after enough failures, or bad behaviour
* accepts nodes down to v0.3.19 to request new IP addresses from,
  but only reports good post-v0.3.24 nodes.
* keeps statistics over (exponential) windows of 2 hours, 8 hours,
  1 day and 1 week, to base decisions on.
* very low memory (a few tens of megabytes) and cpu requirements.
* crawlers run in parallel (by default 24 threads simultaneously).
* supports crawling Tor onion addresses via SOCKS5 proxy.
* exposes Tor onion addresses via DNS TXT records.

REQUIREMENTS
------------

$ sudo apt-get install build-essential libboost-all-dev libssl-dev

USAGE
-----

Assuming you want to run a dns seed on dnsseed.example.com, you will
need an authorative NS record in example.com's domain record, pointing
to for example vps.example.com:

$ dig -t NS dnsseed.example.com

;; ANSWER SECTION
dnsseed.example.com.   86400    IN      NS     vps.example.com.

On the system vps.example.com, you can now run dnsseed:

./dnsseed -h dnsseed.example.com -n vps.example.com

If you want the DNS server to report SOA records, please provide an
e-mail address (with the @ part replaced by .) using -m.

SEED CONFIGURATION
------------------

The seeder needs initial "seed" nodes to bootstrap the crawling process. These can be
configured via command-line arguments or Docker environment variables.

Command-line usage:

   ./dnsseed -h dnsseed.example.com -n vps.example.com -s seed1.example.com,seed2.example.com

   -s <seeds>    Comma-separated list of mainnet seed hostnames (DNS A records)
   -u <seeds>    Comma-separated list of testnet seed hostnames (DNS A records)
   -r <onions>   Comma-separated list of mainnet onion addresses (addr.onion:port)
   -y <onions>   Comma-separated list of testnet onion addresses (addr.onion:port)
   -x <domains>  Comma-separated list of mainnet domains to query for DNS TXT records
   -z <domains>  Comma-separated list of testnet domains to query for DNS TXT records

Docker environment variables:

   - MAINNET_SEEDS: Comma-separated list of mainnet seed hostnames (e.g., "seed1.com,seed2.com")
   - TESTNET_SEEDS: Comma-separated list of testnet seed hostnames
   - MAINNET_ONION_SEEDS: Comma-separated list of mainnet onion addresses (e.g., "abc.onion:8234")
   - TESTNET_ONION_SEEDS: Comma-separated list of testnet onion addresses (e.g., "xyz.onion:18234")
   - MAINNET_TXT_SEEDS: Comma-separated list of domains to query for TXT records (e.g., "_seeds.example.com")
   - TESTNET_TXT_SEEDS: Comma-separated list of testnet TXT seed domains

The seeder will:
1. Perform DNS A record lookups on seed hostnames every 30 minutes
2. Query DNS TXT records from TXT seed domains for additional addresses
3. Connect to the resolved IP addresses on the default port
4. Request peer lists from those nodes to discover more peers
5. Build a database of active, healthy nodes

TXT records should contain addresses in format: "192.0.2.1:8234" or "abc.onion:8234"

If no seeds are specified, the seeder uses default seeds hardcoded in main.cpp.

TOR SUPPORT
-----------

The seeder supports crawling and serving Tor onion addresses. To enable this:

1. Run a Tor daemon on your system (typically listening on 127.0.0.1:9050)

2. Start the seeder with the -o flag to specify the Tor proxy:

   ./dnsseed -h dnsseed.example.com -n vps.example.com -o 127.0.0.1:9050

3. The seeder will:
   - Crawl .onion addresses discovered via peer exchange
   - Test connectivity to onion nodes through the Tor proxy
   - Apply the same quality metrics as clearnet nodes

4. Clients can query onion addresses via DNS TXT records:

   $ dig -t TXT dnsseed.example.com

   ;; ANSWER SECTION
   dnsseed.example.com. 3600 IN TXT "onion=abc123...xyz.onion:8234"
   dnsseed.example.com. 3600 IN TXT "onion=def456...uvw.onion:8234"

TXT records contain onion addresses in the format: onion=<address>:<port>

ONION NODE BOOTSTRAPPING
------------------------

You can bootstrap onion node discovery in several ways:

1. Via command-line arguments:

   ./dnsseed -h dnsseed.example.com -n vps.example.com \
     -o 127.0.0.1:9050 \
     -r abc123...xyz.onion:8234,def456...uvw.onion:8234

2. Via Docker environment variables:

   - MAINNET_ONION_SEEDS=abc123...xyz.onion:8234,def456...uvw.onion:8234
   - TOR_PROXY=tor:9050

3. Via manual code addition in main.cpp (ThreadSeeder function):

   db.Add(CService("abc123...xyz.onion", 8234), true);

Once the seeder connects to any onion node, it will automatically discover more onion
peers through the peer exchange protocol. The initial seeds just help bootstrap the
discovery process.

DOCKER SETUP (RECOMMENDED)
--------------------------

The easiest way to run both mainnet and testnet seeders is using docker-compose.
This provides a complete plug-and-play setup with:
- Unbound DNS server (handles both mainnet and testnet queries on port 53)
- Mainnet seeder (crawls mainnet nodes)
- Testnet seeder (crawls testnet nodes)
- Tor proxy (enables onion node support)

Quick start:

   1. Copy docker-compose.yml-orig to docker-compose.yml
   2. Edit the environment variables (hostnames, email, seeds)
   3. Run: docker-compose up -d

The setup includes Unbound as a DNS frontend that automatically routes:
- Queries for dnsseed.junomoneta.io → mainnet seeder
- Queries for dnsseed.testnet.junomoneta.io → testnet seeder

This allows both networks to share port 53 on the same server without conflicts.

Configuration via environment variables in docker-compose.yml:
   - SEED_HOSTNAME: Your DNS seed hostname (e.g., dnsseed.junomoneta.io)
   - NODE_HOSTNAME: Your server hostname (e.g., mainnet.junomoneta.io)
   - EMAIL: Contact email (use dots instead of @)
   - TOR_PROXY: Tor SOCKS5 proxy address (default: tor:9050)
   - NETWORK: "mainnet" or "testnet"
   - MAINNET_SEEDS: Comma-separated list of mainnet seed hostnames to bootstrap from
   - TESTNET_SEEDS: Comma-separated list of testnet seed hostnames to bootstrap from
   - MAINNET_ONION_SEEDS: Comma-separated list of mainnet onion addresses (addr.onion:port)
   - TESTNET_ONION_SEEDS: Comma-separated list of testnet onion addresses (addr.onion:port)

The included unbound.conf configures zone forwarding automatically.

DNS Records Required:
   In your DNS provider (e.g., Cloudflare), add NS records:

   dnsseed.junomoneta.io.         IN  NS  ns.yourserver.com.
   dnsseed.testnet.junomoneta.io. IN  NS  ns.yourserver.com.
   ns.yourserver.com.             IN  A   <your-server-public-ip>

Testing:
   From another machine, test the DNS setup:

   dig @<your-server-ip> dnsseed.junomoneta.io
   dig @<your-server-ip> dnsseed.testnet.junomoneta.io

COMPILING
---------
Compiling will require boost and ssl.  On debian systems, these are provided
by `libboost-dev` and `libssl-dev` respectively.

$ make

This will produce the `dnsseed` binary.


RUNNING AS NON-ROOT
-------------------

Typically, you'll need root privileges to listen to port 53 (name service).

One solution is using an iptables rule (Linux only) to redirect it to
a non-privileged port:

$ iptables -t nat -A PREROUTING -p udp --dport 53 -j REDIRECT --to-port 5353

If properly configured, this will allow you to run dnsseed in userspace, using
the -p 5353 option.

Another solution is allowing a binary to bind to ports < 1024 with setcap (IPv6 access-safe)

$ setcap 'cap_net_bind_service=+ep' /path/to/dnsseed