A private XDPoS network, for example a consortium chain or a test network inside one company, often wants its nodes to talk only to each other. xOneRS can do that with a node allowlist: start with --permissions.nodes <file>, and the node refuses every peer whose id is not in the file, in both directions and in discovery. The list can change at run time through three perm_ methods or a SIGHUP. The feature is off unless you set the flag, and the perm_ methods are admin-class. It came in two parts, the last on 2026-11-15 (PR #1037), so use a build from main.

This controls who can connect. It does not decide who validates: on XDPoS the masternode set comes from the 0x88 contract and the epoch rules. See epoch switches.

How do I turn it on?

Write the file, then start the node with it:

[
  "enode://<128-hex node id>@10.0.0.11:30303",
  "enode://<128-hex node id>@10.0.0.12:30303",
  "enode://<128-hex node id>@10.0.0.13:30303"
]

xone --network <your network> --permissions.nodes /etc/xone/allowed-nodes.json

The file can also be TOML with nodes = [...]. From the flag help in bin/xone/src/flags.rs: "When set, any other node is refused in and out, and every static and trusted node must be listed." A static or trusted node that is missing from the file stops the start.

For a new private network, see the one-validator dev chain and the xone network init command for private XDPoS networks.

What does the node do with an unlisted peer?

  • Dial or accept: the RLPx connection is closed with UselessPeer (0x03).
  • Discovery (discv4): no reply, no entry in the table, and no ping to an unlisted node id.

So an unlisted node does not learn about the network from your nodes, and it cannot use them to sync.

How do I change the list without a restart?

Two ways (crates/xone-rpc/src/perm.rs, services/net.rs):

REFERENCE TABLEScroll to explore all columns →
Way Effect
perm_getNodesAllowlist Returns the current list
perm_addNodesToAllowlist(["enode://…", …]) Adds nodes and rewrites the file
perm_removeNodesFromAllowlist(["enode://…", …]) Removes nodes and rewrites the file
kill -HUP <pid> Reloads the file from disk

The file is the source of truth. A change is written atomically: to a temporary file, synced to disk, then renamed. A node can be named by its enode URL or by its 128-hex node id. If the node was started without --permissions.nodes, the methods answer node permissioning is not enabled; start with --permissions.nodes.

Who can call the perm_ methods?

They are admin-class. The perm namespace is served only where a listener's API list names it: over IPC by default, and on HTTP or WebSocket only if --http.api or --ws.api includes perm. Do not add it to a public listener. If you must reach it over HTTP, use the per-principal ACL so only an operator token can call perm_* (TLS and method ACLs).

What is still unverified?

PR #1037 lists one check before the issue could close: a private network of four nodes, in the style of net2040, producing blocks with the allowlist on. The issue (#199) is closed, but we did not find that run reported. Test your own network with the allowlist on before you depend on it.

How does this compare with other clients?

REFERENCE TABLEScroll to explore all columns →
Client As named in xOne's flag table xOneRS
besu --permissions-nodes-config-file, and the perm_getNodesAllowlist family of methods --permissions.nodes, and the same three method names

xOne's flag table cites besu's flag as the model, and the perm.rs module names besu's perm_getNodesAllowlist and siblings.

Frequently asked questions

How do I make an XDC node accept only known peers?

Start xOneRS with --permissions.nodes pointing to a JSON array of the allowed enode URLs. Every other node is refused in and out.

Can I add a node to the allowlist without restarting?

Yes. Call perm_addNodesToAllowlist over IPC, or edit the file and send SIGHUP to the node.

Is the allowlist on by default?

No. Without --permissions.nodes the node accepts peers as usual, and the perm_ methods answer that permissioning is not enabled.

Does the allowlist choose the validators?

No. It controls network connections only. XDPoS chooses masternodes from the 0x88 contract and the epoch rules.

Sources