[Feature] Support domain names in node.backup.members and seed.node.ip.list

[Sunny6889]

Problem Statement

Currently, node.backup.members and seed.node.ip.list in the node configuration only accept raw IP addresses. This creates operational friction in dynamic or cloud-native deployments where:

• Infrastructure IP addresses change frequently (auto-scaling groups, cloud instances, Kubernetes pods)
• Operators prefer to manage a small set of stable DNS records rather than updating config files across many nodes whenever IPs rotate
• High-availability backup setups require the member list to stay accurate even as IPs change at runtime

Neither field documents or handles hostname inputs — any domain name silently fails to resolve, causing nodes to be silently dropped from the member/seed list.

Who benefits: Node operators running large-scale deployments, SR infrastructure teams, and any operator managing nodes on infrastructure with dynamic IP allocation.

Proposed Solution

Extend the parsers for both node.backup.members and seed.node.ip.list to accept hostname entries in addition to raw IPv4/IPv6 addresses.

Domain resolution should reuse the DNS resolution pattern from the libp2p library (see tronprotocol/libp2p#130) — specifically the dnsjava SimpleResolver with explicit per-query timeout — rather than re-implementing resolution logic. Note: libp2p's existing lookUpTxt queries TXT records for node discovery; for resolving hostnames to IPs (A/AAAA records) a parallel lookUpA function following the same pattern is needed.

The two fields have different reliability requirements and therefore adopt different resolution strategies:

Field	Resolution timing	Startup failure on DNS error	Periodic re-resolution
node.backup.members	Synchronous, blocks startup until done	Fatal if entry fails	Yes (fixed interval constant in BackupManager)
seed.node.ip.list	Asynchronous, does not block startup	Warning per entry, startup continues	No (p2p handles dynamic expansion)

Specification

Configuration Changes

node.backup.members — extend to accept hostnames (no port, since the backup port is global). No new config options are added; the re-resolution interval is a fixed constant inside BackupManager:

node.backup {
  port = 10001
  priority = 8
  keepAliveInterval = 3000

  // support both peer's ip or domain list, but only fill one of them
  members = [
    // "192.168.1.10",            <- IP, used as-is
    // "backup-node.example.com"  <- domain, resolved at startup and refreshed periodically
  ]
}

seed.node.ip.list — extend to accept host:port where host may be a domain name. No new config options are added; resolution is asynchronous and best-effort:

seed.node = {
  // List of seed nodes. Entries may be IP:port or domain:port.
  ip.list = [
    "52.8.46.215:18888",           // IP:port — used as-is
    "seed1.tron.network:18888"     // domain:port — resolved asynchronously at startup
  ]
}

Resolution Behavior

node.backup.members (high-reliability, synchronous):

• Due to the high reliability requirements of primary/standby election, domain resolution is synchronous and blocks node startup until resolution finished.
• If the domain entry failed to resolve, the node refuses to start and logs a prominent fatal error with the exact hostname and remediation advice:

  [FATAL] Failed to start: cannot resolve backup member "backup-node.example.com".
  Please check DNS configuration or replace the entry with a reachable IP address.
  

• After startup, a background task re-resolves the domain entry on a periodic schedule (interval defined as a constant in BackupManager, not configurable).
  • On refresh, successfully resolved IP replace the previous one for that domain.
  • If the domain temporarily fails to resolve on refresh, the last known IP is retained and a warning is logged — the node does not stop.

seed.node.ip.list (best-effort, asynchronous):

• To avoid lengthening startup time, domain entries are resolved asynchronously in the background. Peer discovery begins immediately using raw IP entries; resolved IPs are added to the seed pool as results arrive.
• All domain lookups are submitted in parallel so resolution finishes as quickly as possible.
• Per-entry failures are logged as warnings; the entry is skipped and startup always continues:

  [WARN] Cannot resolve seed node "seed1.tron.network" — skipping. Check DNS or update ip.list.
  

• No periodic re-resolution after startup. The p2p protocol dynamically discovers and expands the peer list; the seed list is only used for initial bootstrap.

API Changes

None — this is a configuration parsing enhancement only.

Protocol Changes

None.

Scope of Impact

• Network layer (peer discovery, backup node election)
• Configuration parsing (Args.java, CommonParameter.java)

Breaking Changes

None. All existing IP-only configurations remain valid.

Backward Compatibility

Fully backward compatible. Raw IP entries continue to work as-is; the parser treats an entry as a domain only when it is not a valid IP literal (e.g., via Guava's InetAddresses.isInetAddress()).

Implementation

Ideas regarding implementation:

1. In Args.java, after reading node.backup.members and seed.node.ip.list, pass each entry through a helper that distinguishes IP literals from hostnames.
2. Invoke the DNS resolver interface exposed by the libp2p library to perform hostname-to-IP resolution.
3. For node.backup.members:
   • At startup, submit the domain entry to the resolver and wait synchronously; fail fast with a descriptive message if the resolution failed.
   • In BackupManager, add a ScheduledExecutorService task that re-resolves the domain entry at a fixed interval (e.g. 10 minutes, defined as a constant) and atomically swaps the live member ip set. On refresh failure, retain the last known IP and log a warning.
4. For seed.node.ip.list:
   • At startup, submit all domain entries to a thread pool asynchronously (fire-and-forget with callbacks); node startup continues immediately using raw IP entries.
   • Each callback logs WARN on failure or adds resolved IPs to the seed pool on success.
   • No scheduled re-resolution task needed.

Are you willing to implement this feature?

Yes.

Estimated Complexity

Medium — the core parsing/resolution change is straightforward, but the periodic re-resolution in BackupManager and the synchronous-vs-asynchronous split require careful implementation and testing.

Testing Strategy

Test Scenarios

node.backup.members:

• IP entry: behavior unchanged.
• Hostname entry: resolved IP used correctly by backup election.
• For unresolvable hostname at startup: node refuses to start with a clear fatal error message.
• Periodic refresh: updated IP reflected in member set without restart.
• Transient refresh failure: last known IP retained, warning logged, node continues.

seed.node.ip.list:

• IP-only entries: behavior unchanged.
• Hostname entries: resolved IPs used as initial seeds.
• Mixed IP + hostname entries: both work correctly.
• Some or all hostnames unresolvable: warnings logged per entry, node starts and continues with available IPs.
• Asynchronous resolution: startup is not delayed; domain lookups complete in the background.
• Parallel resolution: all domain lookups submitted concurrently, total resolution time bounded by the slowest single lookup.

Performance Considerations

• node.backup.members resolution is synchronous and blocks startup.
• seed.node.ip.list resolution is asynchronous and does not add to startup time; raw IP entries are usable immediately.
• Per-lookup timeout: libp2p's SimpleResolver uses setTimeout(Duration.ofMillis(1000)) per attempt with up to 5 retries (worst-case ~5 s per domain). The same configuration should be reused for consistency.
• Periodic re-resolution in BackupManager must run on a dedicated scheduled thread, not on the backup UDP event loop.

Alternatives Considered

• Re-implement DNS resolution in java-tron — rejected to avoid duplicating logic already maintained in the libp2p library.
• Periodic refresh for seed nodes — rejected; seed nodes are numerous and the p2p protocol already handles dynamic peer discovery after bootstrap, so the added complexity is not justified.

Additional Context

Related Issues/PRs

• tronprotocol/libp2p — exposes the DNS resolver interface this feature would consume

References

• Current config: framework/src/main/resources/config.conf — node.backup, seed.node
• Backup member usage: framework/src/main/java/org/tron/common/backup/BackupManager.java
• Seed node config parsing: framework/src/main/java/org/tron/core/config/args/Args.java

[vividctrlalt]

This is a well-designed proposal. Domain name support for seed nodes and backup members is standard practice — Bitcoin Core, Go-Ethereum, and Cosmos/Tendermint all support hostnames in their peer/seed configuration. TRON only accepting raw IPs is a gap that should be closed.

The sync-vs-async split between node.backup.members (fatal on failure) and seed.node.ip.list (best-effort) makes sense given their different reliability requirements.

One note on timing: PR #6615 refactors Args.java config parsing from manual hasPath/getXxx to ConfigBeanFactory bean binding. The backup members and seed node parsing are both affected. Implementing this feature after #6615 merges would avoid conflicts and allow the DNS resolution logic to be cleanly placed in the bean's fromConfig() method rather than adding more manual parsing to Args.java.

[waynercheung]

@Sunny6889 Thanks for putting together a thoughtful proposal, I agree with the overall direction and the sync-vs-async split.

After checking the current code path, I think we may want to tighten the problem statement a bit:

1. node.backup.members does not support hostnames reliably today.
   It is stored as raw strings, keepalive packets are sent via new InetSocketAddress(member, port), but inbound membership is checked against sender.getHostString(). In practice, if the config contains a hostname and the packet arrives from the resolved IP, the membership check will fail.

2. seed.node.ip.list is a bit more nuanced.
   The current parser already accepts host:port syntactically because it goes through NetUtil.parseInetSocketAddress(...), which creates InetSocketAddress(host, port).
   So the gap is not just “parser rejects hostnames”, but rather “hostname resolution is not explicit, deterministic, or safely integrated”.
   In particular, unresolved addresses look risky in the current libp2p bootstrap path.

I agree with @vividctrlalt that #6615 may be the cleaner place to land the implementation. Before then, we can still use this issue to align on some of the design details and expected runtime behavior.

Two implementation concerns seem worth making explicit in the spec:

• For node.backup.members, fatal resolution failure needs to happen before BackupServer / BackupManager background startup, otherwise it may only be logged instead of aborting node startup.
• For seed.node.ip.list, if resolution is truly async and completes after p2pService.start(), we likely need an explicit runtime injection path into libp2p bootstrap/discovery. Appending to the config list after startup may not be enough.

One more spec question:

• How should we handle multiple A/AAAA records for a single hostname?
• For seeds, adding all resolved addresses seems safest.
• For backup members, it would help to define whether one hostname maps to one active address or to the full resolved set.

So overall: +1 on the feature. I think it would help to frame this not only as accepting hostnames in config, but as defining how hostname resolution should behave for backup members and seed nodes, including failure handling, timing, and runtime refresh.

[Sunny6889]

@waynercheung Thanks for the detailed review and the code-level findings — you're right on both counts.

On backup members membership check failure:
You're right — members stores the raw config strings (hostnames or IPs), but sender.getHostString() always returns the IP the packet arrived from. The fix should be on the check side: when processing an incoming packet check against the resolved set, rather than doing a raw string match. This way the membership check stays correct regardless of whether the config uses hostnames or IPs.

On the multi-A/AAAA record question for backup members:
I'd propose: one hostname → one active address (the first resolved IP). Backup HA is designed as a 1-master + 1-slave topology — the current heartbeat protocol does not handle N>2 members reliably anyway (concurrent MASTER promotion is possible when multiple slaves time out simultaneously). Mapping one hostname to multiple IPs would make that worse without fixing the underlying protocol.

On fatal failure timing:
Agreed — resolution failure for node.backup.members should be fatal before BackupServer starts, not after.

On seed node async injection:
There do need an explicit runtime injection path into libp2p bootstrap/discovery.

Will update issue with more details mentioned above.

[bladehan1]

Thanks for the detailed proposal — this is already very close to an implementation-ready design.
I support the direction. Before coding, I suggest clarifying a few points to reduce integration and ops risk:

1) Config semantics / naming

seed.node.ip.list now accepts domain names, but the field name still implies “IP-only”.
Please explicitly document this in config.conf comments and user docs to avoid operator confusion.

2) Address parsing edge cases

Please specify parsing rules for:

• IPv6 literal with port ([2001:db8::1]:18888)
• Hostname with port
• Invalid host:port formats
• Trailing spaces / mixed-case hostnames normalization

3) Security / trust boundaries

Please clarify whether any safeguards are needed for DNS-based inputs:

• Allow/deny private or loopback targets?
• Any validation of resolved results before adding into seed/backup sets?
• Expected behavior under DNS poisoning / hijack scenarios?

If these are captured in the spec, implementation and review should be much smoother.

[xxo1shine]

@Sunny6889 In Java-tron, backup nodes are currently configured using IP addresses. If we switch to supporting domain names, it introduces a problem:

When a node receives a connection, it determines whether the peer belongs to the same primary-backup cluster by checking whether the peer’s communication IP exists in the configured backup node list. Once domain names are used, this IP-based identification mechanism no longer works, making it impossible for nodes to reliably determine whether they belong to the same cluster.

Therefore, under the current design, directly replacing IP addresses with domain names is not a good solution for implementing primary-backup relationships.

However, the idea of supporting domain names itself is reasonable. We can approach this differently:
Instead of relying on a configured list of backup nodes to define primary-backup relationships, we can introduce a cluster identifier (e.g., a key). Nodes would include this key in their communications, and use it to determine whether they belong to the same cluster, thereby enabling primary-backup identification.

[Little-Peony]

Thanks for the feedback! This is the same membership check issue @waynercheung raised earlier.

The fix is on the check side: match sender.getHostString() against the resolved IP set maintained by BackupManager's periodic re-resolution task, rather than raw config strings. No protocol change needed.

On the cluster key proposal — the current backup protocol is designed for a 1-master + 1-slave topology. Concurrent MASTER promotion is already possible when multiple slaves time out simultaneously, so the protocol doesn't reliably handle N > 2 members. Introducing a cluster key would add complexity without fixing that underlying limitation.

Domain name support is a pure config-parsing enhancement — backward compatible, no protocol change. That's a better fit for the actual operational problem here.

[Little-Peony]

Thanks for the thorough review!

1) Config naming

Agreed — seed.node.ip.list is a legacy name we can't rename without breaking existing configs. We'll add a clear comment in config.conf and update the user docs to explicitly state that both IP addresses and domain names are accepted.

2) Address parsing edge cases

Good catches. The parsing rules will be:

• IPv6 with port: detect [...] prefix and parse as [addr]:port
• Hostname with port: standard host:port split on the last :
• Invalid formats: log WARN and skip the entry; startup continues
• Trailing spaces / mixed-case: trim whitespace and lowercase before parsing

3) Security / trust boundaries

This is operator-supplied config, so we treat it with the same trust level as the rest of config.conf. Concretely:

• No allow/deny list for private or loopback addresses — operators running private testnets or internal clusters legitimately use RFC-1918 ranges
• Resolved IPs are validated to be syntactically valid before use; no additional filtering
• DNS poisoning is mitigated by using libp2p's SimpleResolver with explicit per-query timeout (1 s, up to 5 retries) rather than the JVM default resolver. Full DNSSEC validation is out of scope for this feature

We'll capture all of the above in the spec before implementation starts.

[waynercheung]

@Sunny6889 A few details still seem worth making explicit before implementation:

• For node.backup.members, I would separate send-side target selection from receive-side membership matching. one hostname -> one active address is reasonable for the send path, but the receive path should still compare against a normalized resolved address set rather than raw getHostString() strings.
• If the policy is one hostname -> one active address, the first resolved IP still feels underspecified. It may help to either require exactly one usable address for backup hostnames, or define a deterministic selection rule.
• I think invalid-format behavior should remain field-specific: fatal for node.backup.members, warn-and-skip for seed.node.ip.list.
• If seed async injection needs a new libp2p hook/API, it would help to call that dependency out explicitly.

One minor wording nit: SimpleResolver improves timeout/retry control, but DNS poisoning/hijack still remains within the operator's DNS trust boundary.