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

[317787106]

Background

The Admin architecture described in tronprotocol#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 libp2p 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:

Method	Description
admin_addPeer	Add an endpoint to the runtime active-node set
admin_removePeer	Remove an endpoint from the active-node set and disconnect its current connection
admin_disconnectPeer	Disconnect an exact endpoint without changing the active-node set
admin_listActivePeers	Return current connected peers and their runtime statistics
admin_blockIp	Add an IP to the persistent manual blocklist and disconnect matching TCP connections
admin_unblockIp	Remove an IP from the manual blocklist
admin_listBlockedIps	Return the current manual blocklist

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

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

Operation result

Peer mutation methods should share a structured response:

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

success indicates whether the operation completed. changed indicates whether the target runtime set changed. disconnectedCount reports how many existing connections were closed. message 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, libp2p may reconnect to it after the normal connection cooldown.

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 libp2p 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 should be persisted directly in CommonStore with the fixed key:

blocked-ips

Its logical value is a normalized, deduplicated, and stably ordered List<InetAddress>. No separate BlockedIpStore should be introduced.

The blocklist must be loaded and installed in P2pConfig before libp2p 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 libp2p, 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 libp2p must not connect to it until the IP is unblocked.

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

libp2p integration

The libp2p layer should provide the following runtime operations:

boolean addActiveNode(InetSocketAddress address);

boolean removeActiveNode(InetSocketAddress address);

int disconnect(InetSocketAddress address);

int replaceBlockedIps(Set<InetAddress> blockedIps);

libp2p 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 should only adapt JSON-RPC calls to the service. Database access, validation, concurrency control, libp2p operations, lifecycle state, and peer-statistics assembly should remain inside the network-layer service.

No additional node.admin.peerManagement configuration option should be 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 should remain disabled by default and bound to loopback by default. IPC access should continue 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.

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

Tests should cover:

• HTTP and IPC method dispatch and identical error behavior.
• IPv4, IPv6, endpoint, port, length, and DNS-free validation.
• Active-node addition, removal, idempotency, and asynchronous connection semantics.
• Exact disconnection without modifying the active-node set.
• Dynamic-configuration conflicts without side effects.
• Active-peer counts, synchronization fields, disconnected-peer filtering, and normalized endpoints.
• IPC JSON and text output without changing the server request.
• Blocklist persistence, restart restoration, normalization, and stable ordering.
• Missing, malformed, oversized, or invalid persisted blocklist data.
• Concurrent block and unblock operations.
• libp2p, CommonStore, and in-memory snapshot update ordering.
• Rejection of active endpoints whose IP is blocked.
• TCP connection rejection and existing-connection cleanup in libp2p.

Scope of Impact

The change affects the Admin interface, network service lifecycle, peer statistics, CommonStore, the effective-connection service, and the libp2p dependency.

It does not change protobuf definitions, the TRON P2P wire protocol, synchronization messages, consensus behavior, or chain-data formats.

Backwards Compatibility

The feature only adds new Admin JSON-RPC methods. 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 tronprotocol/java-tron#6497
• Previous peer-management discussion: Support dynamic management of peers tronprotocol/java-tron#6296