Peer Management

If you followed any of the language-specific guides, you now have a well-functioning network that people will want to join.

Public Blockchain

In an open network, peer admission is still a chain policy decision. A node can run the correct software and connect to Torii, but it only participates in consensus after the network admits its peer identity.

Private Blockchain

In a bank setting, allowing everyone to join at their leisure is a security risk. For safety, private Iroha deployments usually pin the peer topology in configuration and genesis instead of relying on open discovery.

Registering peers

To add a peer to the network, it must be manually registered. Let's discuss the steps that should be taken in order to complete this process.

1. Grant the user permissions

The account that registers the peer must have the appropriate Permission. This can be granted through a Role or as a direct permission grant.

Grant a role when an account will manage peers over time. Use a direct permission grant for a one-time registration by an account that does not otherwise manage peers.

INFO

The default executor uses the CanManagePeers permission token for registering and unregistering peers.

We discuss permissions and roles with more detail in a separate chapter.

2. Set up a peer

After a new peer was granted permissions, it must be set up.

Request the current peer configuration before admitting a node. Torii exposes node parameter and capability endpoints for this purpose. Peer bootstrap does not negotiate these values automatically: operators must verify that timeouts, batch sizes, and other consensus-relevant settings match the network.

To simplify the process, you can ask the network administrator for a redacted version of config.toml, which excludes privileged information, such as peer private keys.

3. Submit the instruction

After your peer is running, you should submit the register peer instruction. The peer will go through the handshake process and start chatting with the network.

TIP

Submitting a peer registration instruction does not (and cannot) instantiate a new peer process.

Unregistering peers

What about unregistering peers? For security reasons this process is one-sided. The network reaches consensus that it wants to remove a peer, but the peer itself doesn't know much about why nobody's talking to it.

In most circumstances, if you want to unregister a peer, you want to do so because it is a Byzantine fault. Just "ghosting" this peer makes the life of the malicious actor on the network harder.