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

[317787106]

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 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 each manually blocked IP and its record creation timestamp

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, libp2p 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 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 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 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 (v2.3.0) should provide the following runtime operations (tronprotocol/libp2p#159 and tronprotocol/libp2p#160 ):

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 only adapt JSON-RPC calls to the service. Database access, validation, concurrency control, libp2p 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.

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 libp2p dependency.

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

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

[xxo1shine]

@317787106, the node already supports dynamically reloading the node.active and node.passive configurations. Adding an IP blocklist to the existing dynamic configuration mechanism, then disconnecting matching TCP connections and preventing subsequent inbound and outbound connections when the configuration is updated, should cover the main operational requirements described in this issue. An operator who needs to temporarily disconnect a peer can add its IP to the blocklist and remove it after the operation is complete.

In comparison, introducing a complete Admin peer-management API would add substantial work and complexity around API authorization, HTTP/IPC exposure, state persistence, concurrent updates, consistency between multiple sources of truth, and testing. I suggest narrowing the scope to implement TCP IP blocking through the existing dynamic configuration mechanism, without adding Admin APIs for active-node management or peer disconnection.

[317787106]

@xxo1shine Thanks for the suggestion. Extending dynamic configuration has clear advantages: a smaller initial change, file-based persistence, and integration with existing configuration-management workflows.

However, configuration reload and interactive peer management serve different operational needs. Reloading depends on a polling cycle and provides no direct, structured response to the operator. Temporarily blocking an IP also affects every connection using that IP and requires a subsequent unblock operation; it does not provide the same semantics as disconnecting one specific endpoint. Peer inspection is another requirement that configuration reload alone does not address.

The Admin approach requires additional validation, concurrency control, persistence handling, and security testing. These are real costs. However, it builds on the shared HTTP/IPC architecture described in #6497. The proposal also explicitly prevents competing active-node updates by disabling Admin add/remove operations when dynamic configuration is enabled.

On balance, I recommend implementing these operational capabilities through the Admin interface and keeping the existing dynamic configuration behavior for compatibility, without extending it with new peer-management or IP-blocklist functionality. This provides immediate operation feedback and more precise control, while avoiding further investment in a second management mechanism.