IPv6 Support in Tapyrus-Core — Comprehensive Update Plan

[Naviabheeman]

What is already correct (no changes needed)

CNetAddr/CService/CSubNet primitives store all addresses in 16-byte IPv6 space and implement the full set of RFC classification predicates. SplitHostPort correctly parses [::1]:port bracket notation.
LookupHost/Lookup/LookupIntern use AF_UNSPEC with getaddrinfo, resolving both A and AAAA records.
CreateSocket derives AF_INET6 from GetSockAddr().
BindListenPort creates AF_INET6 sockets and sets IPV6_V6ONLY.
CConnman::InitBinds without explicit -bind creates both IN6ADDR_ANY and INADDR_ANY sockets.
getifaddrs discovery handles both address families.
GetReachabilityFrom scores NET_IPV6 correctly.
The HTTP server default already binds ::1 alongside 127.0.0.1. rpcallowip and ban subnets work via CSubNet which is family-agnostic. The SeedSpec6 format in chainparams is IPv6-capable (seeds are simply absent, which is a deployment decision, not a code gap).

---

Goal 1 — P2P layer: listen, connect, address relay, banning

Status: Socket creation, binding, and accept paths are correct. Two edge cases need fixing.

Tasks:

1. scopeId serialization (src/netaddress.h:94): The scopeId field for link-local addresses (fe80::/10) is not serialized. It is lost when an address is written to peers.dat or sent in a P2P addr message. Either serialize it alongside the 16-byte ip[] array, or document explicitly that link-local addresses are unsupported and add an IsLocal() guard before storing them in addrman.
2. Verify -bind [::]:port dual-listen: InitBinds creates separate IN6ADDR_ANY (with IPV6_V6ONLY) and INADDR_ANY sockets. Trace and confirm there is no early-exit that silently skips the IPv4 bind after IPv6 succeeds (BF_REPORT_ERROR logic at net.cpp:2269).
3. Verify -externalip [2001:db8::1]: The address goes through Lookup() → CService → AddLocal(). Confirm the resulting local address is advertised correctly in VERSION and addr self-announce messages.
4. Verify subnet ban end-to-end: setban "2001:db8::/48" → LookupSubNet → CSubNet → CBanDB → reload. Confirm a peer from 2001:db8::1 is rejected at AcceptConnection.
5. Check addrman group assignment for IPv6 (src/netaddress.cpp:GetGroup): IPv6 uses a /32 group key. Verify there is no off-by-one in GetNewBucket that could cause IPv6 entries to collide with IPv4 entries or with each other.

---

Goal 2 — Persistence: peers.dat and banlist.dat

Status: 16-byte serialization correctly covers IPv6. scopeId is the one known gap (handled in Goal 1). Addrman bucket arithmetic needs a targeted audit.

Tasks:

1. Audit CAddrMan::Serialize/Unserialize: Confirm no version gate silently downgrades or drops IPv6 CNetAddr entries when loading an older-format peers.dat.
2. Audit GetNewBucket for IPv6: The bucket calculation uses GetGroup() which returns the /32 prefix for native IPv6. Verify this does not produce a collision with the IPv4-mapped range (::FFFF:x.x.x.x/32), causing IPv4 and IPv6 entries to share a bucket unintentionally.
3. Ban persistence for IPv6 subnets: CSubNet with a 128-bit netmask serializes all 16 bytes of both network.ip and the mask array. Confirm a /48 ban survives a shutdown/restart cycle by tracing the read path in CBanDB::Read.

---

Goal 3 — Config and startup

Status: Parsing is correct. Help text and one UPnP case need attention.

Tasks:

1. Help text: The -addnode, -connect, -whitelist, and -externalip help strings do not show IPv6 bracket syntax. Add [host]:port examples to each.
2. RPC help text: -rpcbind, -rpcallowip, and -rpcconnect similarly. Add [::1]:8332 and 2001:db8::/32 examples.
3. UPnP and IPv6 external IP: UPnP IGD does not provide IPv6 external address discovery. Add an explicit early-return with a log message when UPnP runs and the node is IPv6-only (i.e., NET_IPV4 is unreachable), so the user gets a clear diagnostic instead of silent failure.

---

Goal 4 — ZMQ

Status: Works if the user provides correct tcp://[::1]:port syntax, but IPv6 is entirely undocumented and the ZMQ_IPV6 socket option is never set, which causes silent bind failure on some libzmq builds.

Tasks:

1. Set ZMQ_IPV6 socket option (src/zmq/zmqpublishnotifier.cpp:81): Call zmq_setsockopt(psocket, ZMQ_IPV6, 1, sizeof(int)) immediately before zmq_bind. Without this, libzmq may reject tcp://[::1]:port or fall back to IPv4-only even when an IPv6 address is specified.
2. Document endpoint syntax: Add tcp://[::1]:28332 as an example in the -zmqpub* help strings in src/init.cpp.

---

Goal 5 — HTTP/RPC server

Status: Default binds already include ::1. The libevent layer handles evhttp_bind_socket_with_handle("::1", port) correctly in libevent ≥ 2.1.x. One asymmetry and one platform limitation exist.

Tasks:

1. Verify evhttp IPv6 with the minimum supported libevent version: evhttp_bind_socket_with_handle with a bare "::1" string (not bracketed) relies on libevent calling getaddrinfo internally. Confirm this works with the actual minimum libevent version in depends/packages/libevent.mk. If the minimum is below 2.1.x, replace the call with manual socket creation + evhttp_accept_socket.
2. Loopback allow-list asymmetry (src/httpserver.cpp:173): IPv4 loopback allows the entire 127.0.0.0/8 range; IPv6 loopback allows only ::1/128. This is more restrictive but asymmetric. Document the behaviour in a comment; adjust if needed.
3. all_interfaces() in test framework (test/functional/test_framework/netutil.py:89): Uses SIOCGIFCONF which returns IPv4 interface addresses only. IPv6 non-loopback interface discovery requires getifaddrs or parsing /proc/net/if_inet6 on Linux. Fix for non-loopback IPv6 RPC bind tests in Goal 7.

---

Goal 6 — Tor

Status: Two blocking bugs and one deprecation to fix.

Tasks:

1. ADD_ONION hardcoded IPv4 target (src/torcontrol.cpp:553): The hidden service target is hardcoded as 127.0.0.1:. If the node only listens on IPv6 loopback (::1), Tor cannot forward inbound hidden-service traffic. Change to detect the actual bound address (or use [::1]: when the node is IPv6-only) and format accordingly.
2. Tor v2 → v3 migration (src/torcontrol.cpp:549): NEW:RSA1024 requests a v2 onion service. Tor removed v2 support in 0.4.6 (2021). Change to NEW:ED25519-V3 and update the address encoding and parsing to handle 56-character v3 .onion addresses instead of 16-character v2. This is not strictly IPv6 but blocks Tor from working at all on modern Tor daemons.
3. Tor proxy on IPv6 loopback: -proxy [::1]:9050 (Tor SOCKS5 on IPv6 loopback) passes through SplitHostPort and CreateSocket correctly. Verify auth_cb in torcontrol.cpp also uses the configured proxy address rather than hardcoding 127.0.0.1:9050 for the Tor control connection.

---

Goal 7 — Functional and regression tests (IPv4 + IPv6 combination testing)

Tasks:

1. P2P IPv6 connectivity test (new): Start two nodes with -bind [::1]: and connect them. Confirm handshake completes, blocks propagate, and getpeerinfo shows an IPv6 peer address. Guard with test_ipv6_local().
2. Dual-stack P2P test (new): Start a node bound to both 127.0.0.1:<p> and [::1]:<p>. Connect one peer via each. Confirm both appear in getpeerinfo with correct address families simultaneously.
3. IPv6 addr relay test (test/functional/p2p_addr_relay.py): The test only sends 123.123.x.x IPv4 addresses. Add a parallel case that sends 2001:db8::x IPv6 addresses via addr message and verifies they are stored in addrman and relayed to a third peer.
4. IPv6 ban test (new or extend rpc_ban.py): Call setban "::1/128", confirm a connection from [::1] is refused. Call setban "2001:db8::/32", confirm the subnet is persisted in banlist.dat and reloaded after restart.
5. ZMQ IPv6 endpoint test (new): Bind a ZMQ publisher to tcp://[::1]:, subscribe from the same address, mine a block, and confirm the hashblock notification arrives. Guard with test_ipv6_local().
6. HTTP/RPC IPv6 test (extend rpc_bind.py): Add a case that binds only to [::1], confirms RPC calls succeed via [::1], and confirms 127.0.0.1 is refused. Fix all_interfaces() to use /proc/net/if_inet6 or getifaddrs so non-loopback IPv6 interfaces are discoverable on Linux.
7. addrman IPv6 round-trip test (new, src/test/addrman_tests.cpp): Insert an IPv6 CAddress (e.g. 2001:db8::1) as both address and source, serialize addrman to a stream, deserialize it, and confirm the entry is present with the correct address. This closes the only gap in the addrman unit tests.
8. peers.dat round-trip with IPv6 (new, src/test/addrman_tests.cpp or separate): Write addrman containing IPv6 entries to a temporary file via CAddrDB::Write, read it back via CAddrDB::Read, and confirm all entries are intact.

[azuchi]

Scope revision — remove Tor (Goal 6), add missing IPv6 gaps

After auditing the plan against the current tree (master post PR #429), here are the changes I'd like to make.

Rationale for dropping Goal 6

Tor v2 → v3 migration is unrelated to IPv6 and drags in a large prerequisite: BIP155 (addrv2) support. The legacy addr message (CNetAddr::SerializationOp in src/netaddress.h:94-97) uses a fixed 16-byte IP field, which is exactly the width of an IPv6 address, so IPv6 rides on the legacy format losslessly. Tor v3, however, uses a 32-byte Ed25519 public key that will not fit — advertising v3 onions to peers requires BIP155.

Mixing that into an IPv6 support plan makes both harder to review. Better to keep this issue IPv6-only and track Tor v2→v3 (plus the BIP155 decision) in its own issue.

Remove

• Delete Goal 6 (Tor) entirely — three tasks (ADD_ONION hardcoded loopback, NEW:RSA1024 → NEW:ED25519-V3 migration, auth_cb proxy address).

Add — missing IPv6-specific gaps

Goal 3 (Config and startup):

• 3.4. Dual-stack default bind verification. src/net.cpp:2118-2124 sets IPV6_V6ONLY on every v6 listen socket. Trace CConnman::InitBinds with -listen=1 and no explicit -bind to confirm that both IN6ADDR_ANY and INADDR_ANY sockets are created (task 1.2 covers the error-path check; 3.4 covers the default-config path). Also document that Tapyrus has no explicit -noipv6 / SetLimited(NET_IPV6) — only -onlynet=ipv4 (src/init.cpp:1347-1369) — so users wanting IPv4-only must use that switch.
• 3.5. -addseeder operational note. Federation operators who publish -addseeder=<host> must add AAAA records for IPv6 clients. The resolver path (src/netbase.cpp:92-101 uses AF_UNSPEC getaddrinfo) already returns both A and AAAA, so no code change is needed — this is a doc/operations note only.

Goal 7 (Functional and regression tests):

• 7.9. Enable IPv6 in CI runners. GitHub Actions Ubuntu runners disable IPv6 loopback by default. Add the equivalent of sysctl -w net.ipv6.conf.all.disable_ipv6=0 (or the workflow-level equivalent) to .github/workflows/daily-test.yml (and any other workflow that runs functional tests). Without this, every new test guarded by test_ipv6_local() (7.1, 7.2, 7.5, 7.6) will silently SkipTest in CI and produce false green. test_ipv6_local() is already defined in test/functional/test_framework/netutil.py:145-158 and used by rpc_bind.py:70, feature_proxy.py:49.
• 7.10. mininode.py AF_INET6 support. Before writing 7.1 (P2P IPv6 connectivity) and 7.2 (dual-stack P2P), verify test/functional/test_framework/mininode.py::listen() (~lines 481-497) and create_connection correctly pass family=AF_INET6 when the target is a bracketed IPv6 address. Extend if needed. This is a test-framework prerequisite that will otherwise block 7.1/7.2.

Follow-up issue (recommended, not part of this scope)

Open a new issue "Migrate Tor support from v2 to v3" covering:

• Tor v2 removal from the Tor daemon (0.4.6, 2021) has already broken NEW:RSA1024 at src/torcontrol.cpp:549 — Tapyrus's Tor integration is currently non-functional on any modern Tor daemon regardless of IPv6.
• Fix ADD_ONION target hardcoded to 127.0.0.1:<port> (src/torcontrol.cpp:553), fix auth_cb proxy address (src/torcontrol.cpp), and switch to NEW:ED25519-V3 with 56-char v3 .onion parsing.
• Decide whether to implement BIP155 (addrv2) to relay v3 onions across the P2P network, or restrict Tor to local hidden service only (no addr relay). This is the primary design decision for that issue.

Informational (no action)

• getnodeaddresses RPC is absent in Tapyrus (present upstream). Unrelated to IPv6, but Goal 5's RPC surface is narrower than upstream — worth noting so reviewers do not expect it.
• No I2P or CJDNS support (enum Network in src/netaddress.h:18-27 has only IPv4/IPv6/onion). Correctly out of scope for an IPv6-focused plan.