Last update: October 11, 2021

Node keys and node address

Each node has a private and public key pair, and a node address. Hyperledger Besu uses the private and public key pair to sign and verify transactions, and the node address as an identifier for the node.

Node private key

When starting Hyperledger Besu, if the --node-private-key-file option is not specified and a key file does not exist in the data directory for the node, Besu generates a node private key and writes it to the key file.

If a key file does exist in the data directory when starting Besu, the node starts using the private key in the key file.

Info

The private key is not encrypted.

Node public key

The node public key displays in the log after starting Besu. Also referred to as the node ID, the node public key forms part of the enode URL of a node.

You can export the node public key, either to standard output or to a specified file, using the public-key export subcommand.

Node address

Besu generates the node address by creating a hash of the node public key and using the last 20 bytes of the hash as the node address. It is also displayed in the logs after starting Besu.

You can export the node address, either to standard output or to a specified file, using the public-key export-address subcommand.

Specifying a custom node private key file

Use the --node-private-key-file option to specify a custom key file in any location.

If the key file exists, the node starts with the private key in the key file. If the key file does not exist, Besu generates a node private key and writes it to the key file.

For example, the following command either reads the node private key from privatekeyfile or writes a generated private key to privatekeyfile.

Example

besu --node-private-key-file="/Users/username/privatekeyfile"

Enode URL

The enode URL identifies a node. For example, the --bootnodes option and the perm_addNodesToAllowlist method specify nodes by enode URL.

The enode URL format is enode://<id>@<host:port>[?discport=<port>] where:

• <id> is the node public key, excluding the initial 0x.

• <host:port> is the host and TCP port the bootnode is listening on for P2P discovery. Specify the host and TCP port using the --p2p-host and --p2p-port options. The default host is 127.0.0.1 and the default port is 30303.

  Note

  Standard Ethereum enode URLs allow hostnames as IP addresses only, however Besu provides domain name support in private permissioned networks.

• If the TCP listening and UDP discovery ports differ, the UDP port is specified as query parameter discport.

Example

If the node public key is 0xc35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f, the host is 10.3.58.6, the TCP listening port is 30303, and the UDP discovery port is 30301, then the enode URL is enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@10.3.58.6:30303?discport=30301

If the --p2p-host or --p2p-port options are not specified and the node public key is 0xc35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f, then the enode URL is enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@127.0.0.1:30303

The enode URL displays when starting a Besu node. Use the net_enode JSON-RPC API method to get the enode URL of the node.

The enode advertised to other nodes during discovery is the external IP address and port, as defined by --nat-method.

Domain name support

Warning

Enode URL domain name support is an experimental feature that you can use in private permissioned networks only.

To use domain names in enode URLs:

• Configure DNS reverse lookup.
• Enable DNS support using Besu’s --Xdns-enabled experimental command line option.

Example enode URL using a domain name

enode://c35c3ec90a8a51fd5703594c6303382f3ae6b2ecb9589bab2c04b3794f2bc3fc2631dabb0c08af795787a6c004d8f532230ae6e9925cbbefb0b28b79295d615f@mydomain.dev.example.net:30301

Tip

If deploying Besu using Kubernetes in private permissioned networks, use the --Xdns-enabled and --Xdns-update-enabled options to ensure that Besu can connect to a container after restarting even if the IP address of the container changes.

Use the --Xhelp command line option to view experimental options and their descriptions.

If nodes are not connecting as expected, set the log level to TRACE to help troubleshoot the issue.