[Feature] Support runtime peer management and manual IP blocking through Admin APIs #6989

Background

The Admin architecture described in #6497 provides a unified JSON-RPC interface over Admin HTTP and local IPC. Both transports share the same method definitions, parameter validation, business implementation, and error handling.

Peer management should be implemented as an operational capability on top of this existing architecture.

In an open P2P network, a FullNode may be affected by malicious peers, connection exhaustion, Sybil attacks, or network isolation. After identifying a suspicious peer through logs, synchronization status, or connection statistics, operators need to disconnect it immediately or block its IP from reconnecting.

Operators may also need to add an operator-selected active endpoint while the node is running. Compared with restarting the node or waiting for dynamic configuration reload, an Admin request provides immediate and structured feedback without interrupting synchronization, block production, or message propagation.

Rationale

This feature should support the following operational scenarios:

• Add or remove an active node without restarting the FullNode.
• Disconnect an exact peer connection without changing active-node configuration.
• Inspect current peer connections and synchronization statistics.
• Persistently block a malicious IP and disconnect its existing TCP connections.
• Remove an IP from the manual blocklist.
• Restore the manual blocklist after a normal node restart.

The result of admin_addPeer only indicates that the endpoint was added to the active-node set. It does not mean that the TCP connection or P2P handshake has completed. If the remote node is temporarily full or unreachable, the existing p2p active-node scheduler should continue retrying according to its normal retry policy.

Specification

Admin methods

The existing AdminJsonRpc interface should be extended with the following methods:

Admin HTTP and IPC should expose the same JSON-RPC methods and business semantics.

Peer endpoints accept only IPv4:port and [IPv6]:port. IP blocklist methods accept only IPv4 or IPv6 literals. Domain names, CIDR ranges, and endpoints without valid ports must be rejected without performing DNS resolution.

Operation result

Peer mutation methods share a structured response:

{
  "success": true,
  "changed": true,
  "disconnectedCount": 0,
  "errorMessage": ""
}

success indicates whether the operation completed. changed indicates whether the target runtime set changed. disconnectedCount reports how many existing connections were closed. errorMessage provides a reason when an operation is unavailable.

Repeated add, remove, block, or unblock requests should be idempotent.

Active-node management

admin_addPeer should add the endpoint to the runtime active-node set. It should not add the endpoint or its IP to trustNodes, and the change should not be persisted across node restarts.

admin_removePeer should remove the endpoint from the active-node set and disconnect its current connection.

admin_disconnectPeer should only close the current connection. If the endpoint remains in the active-node set, the p2p module may reconnect to it after the normal connection cooldown.

NOTE：When node.dynamicConfig.enable=true, the configuration file remains the only source of truth for active nodes. In this mode, admin_addPeer and admin_removePeer should return a structured failure directing the operator to update node.active. They must not modify p2p state or disconnect an existing peer.

Other operations, including exact disconnection, peer queries, and manual IP blocklist management, should remain available when dynamic configuration is enabled.

Active-peer query

admin_listActivePeers should return the currently connected business peers from PeerManager. Peers that have already been marked disconnected but are waiting for delayed cleanup should be excluded.

The response should contain:

• Total, active, passive, and valid peer counts.
• Normalized remoteAddress, which can be passed directly to admin_disconnectPeer.
• Connection duration and average latency.
• Last known block number.
• Synchronization direction and queue statistics.
• Inactive duration and blocks currently being processed.

The peer statistics should reuse the immutable snapshot used by peer logging so that Admin output and operational logs do not maintain separate calculation logic.

For IPC only, the client may accept:

admin_listActivePeers
admin_listActivePeers json
admin_listActivePeers text

The default format is JSON. The optional text format is handled entirely by the IPC client and renders the same fields as a compact table. It must not change the server-side JSON-RPC method signature or the Admin HTTP response.

Manual IP blocklist

The manual blocklist be persisted directly in CommonStore with the fixed key: blocked-ips.

Its logical value is a normalized, deduplicated, and deterministically ordered InetAddress → blockedAtMillis. No separate BlockedIpStore should be introduced.

The blocklist must be loaded and installed in P2pConfig before the p2p module starts listening or dialing. Invalid persisted data should be deleted on a best-effort basis, after which the node should continue startup with an empty manual blocklist. This auxiliary data must not prevent synchronization, block production, or network startup.

admin_blockIp should install the complete new blocklist in the p2p module, disconnect existing TCP connections using the target IP, persist the new value, and finally publish the java-tron in-memory snapshot.

An IP in the manual blocklist has higher priority than the active-node set. admin_addPeer must reject an endpoint whose IP is blocked. If an active node is blocked after it has been added, it may remain in the active-node set, but the p2p module must not connect to it until the IP is unblocked.

The manual blocklist is separate from the p2p module's existing temporary connection-ban mechanism. Admin method names therefore use block, unblock, and blocked rather than ban.

Built-in p2p integration

#6992 has merged libp2p into java-tron as the local :p2p module. This feature no longer requires the external libp2p:2.3.0 dependency or a separate libp2p PR, SNAPSHOT artifact, or release.

The built-in p2p module should provide the following runtime operations through P2pService:

boolean addActiveNode(InetSocketAddress address);

boolean removeActiveNode(InetSocketAddress address);

int disconnect(InetSocketAddress address);

int replaceBlockedIps(Set<InetAddress> blockedIps);

The p2p module is responsible for active-node connection retries, exact channel disconnection, and blocklist enforcement for inbound TCP connections, outbound TCP connections, and active-node dial candidates.

The initial implementation does not apply the manual blocklist to Kademlia or DNS-based UDP discovery.

Service architecture

Peer-management logic should be centralized in PeerManagementService:

Admin HTTP / IPC
        |
        v
AdminJsonRpcImpl
        |
        v
PeerManagementService
        |
        +---- CommonStore["blocked-ips"]
        |
        +---- PeerManager
        |
        +---- P2pService

AdminJsonRpcImpl only adapt JSON-RPC calls to the service. Database access, validation, concurrency control, p2p operations, lifecycle state, and peer-statistics assembly remain inside the network-layer service.

No additional configuration is introduced. Access to these methods remains controlled by the existing Admin HTTP and IPC configuration.

Security Considerations

Peer management is a privileged administrative capability. Admin HTTP remains disabled by default and bound to loopback by default. IPC access continues to rely on local socket-file permissions.

If Admin HTTP is exposed outside loopback, deployment-level protection such as firewall rules, a trusted network, reverse-proxy authentication, or mTLS is required.

Endpoint and IP inputs should have explicit length and quantity limits. Parsing must not perform DNS resolution, access the filesystem, or invoke external commands. Logs must not include complete JSON-RPC requests, corrupted database values, credentials, or sensitive filesystem paths.

Before adding state-changing peer-management methods, add audit logging to the shared Admin invocation path. For HTTP and IPC, including notifications, log the transport, method, available caller context, and outcome at INFO level or through a dedicated audit logger. Capture JSON-RPC errors and business failures (success: false); do not infer success from HTTP status. Exclude raw parameters, response payloads, credentials, and sensitive paths.

Out of Scope

The initial implementation does not include:

• Domain-name or CIDR blocking.
• Node-ID blocking.
• Automatic expiration of blocked IPs.
• Automatic malicious-peer scoring.
• Persistence of active nodes added through Admin.
• Per-attempt active-node retry status.
• UDP discovery filtering.
• Runtime modification of trustNodes.

Test Specification

Implements later.

Scope of Impact

The change affects the Admin interface, network service lifecycle, peer statistics, CommonStore, the effective-connection service, and the built-in p2p module.

p2p/src/main/proto/Connect.proto adds DisconnectReason.REQUESTED = 0x0F for explicit disconnects. The existing disconnect message structure, synchronization messages, consensus behavior, and chain-data formats remain unchanged.

Backwards Compatibility

This feature exclusively introduces new Admin JSON-RPC endpoints. Existing Admin methods, business JSON-RPC APIs, HTTP APIs, gRPC APIs, and IPC transport behavior remain unchanged.

Older java-tron versions ignore the blocked-ips CommonStore key. Downgrading therefore disables manual IP blocking but does not affect blockchain data.

References

• Admin architecture: Design of a Secure IPC and JSON-RPC Based Administration Framework for FullNode #6497
• Previous peer-management discussion: Support dynamic management of peers #6296
• Built-in p2p module: chore(p2p): internalize libp2p v2.2.9 as a local p2p module #6992