Authorize Specific Nodes
Configure a network that has authorized nodes and nodes with restricted access.
A blockchain with nodes that are granted specific permissions is different from a public or permissionless blockchain. In a permissionless blockchain, anyone can join the network by running the node software on suitable hardware. In general, a permissionless blockchain offers greater decentralization of the network. However, there are use cases where creating a permissioned blockchain might be appropriate. For example, a permissioned blockchain would be suitable for the following types of projects:
For a private or consortium network, such as a private enterprise or a non-profit organization.
In highly-regulated data environments, such as healthcare, finance, or business-to-business ledgers.
For testing of a pre-public blockchain network at scale.
Node authorization and ownership
The node-authorization
pallet is a prebuilt FRAME pallet that enables you to manage a configurable set of nodes for a network. Each node is identified by a peer identifier (PeerId
). Each peer identifier is owned by one and only one account owner (AccountId
) that claims the node.
There are two ways you can authorize a node to join the network:
By adding the peer identifier to the list of predefined nodes in the chain specification file as part of the genesis configuration for the chain. You must be approved by the governance mechanism for the chain or have access to the root account for the Sudo pallet in the network to do this.
By asking for a paired peer connection from a specific node. You can add connections between nodes by using predefined node peer identifiers or by using the peer identifiers generated from the public and private keys for each of the nodes.
As the following diagram suggests, this tutorial illustrates both authorization methods, with the peer identifiers for Alice and Bob defined in the chain specification and the additional nodes added using the node authorization pallet.
Note that any user can claim to be the owner of a PeerId
. To protect against false claims, you should claim the node identifier before you start the node. After you start the node, its PeerID
is visible to the network and anyone could subsequently claim it.
As the owner of a node, you can add and remove connections for your node. For example, you can manipulate the connection between a predefined node and your node or between your node and other non-predefined nodes. You can't change the connections for predefined nodes. They are always allowed to connect with each other.
Before you begin
Before you begin, verify the following:
Tutorial objectives
By completing this tutorial, you will accomplish the following objectives:
Check out and compile the node template.
Add the node authorization pallet to the node template runtime.
Launch multiple nodes and authorize new nodes to join.
Build the node template
If you have completed previous tutorials, you should have the Substrate node template repository available locally.
Open a terminal shell on the computer where you have Substrate node template repository.
Change to the root of the node template directory, if necessary, by running the following command:
Switch to a working branch for the repository if you want to save your changes by running a command similar to the following:
Compile the node template by running the following command:
Add the node authorization pallet
Before you can use a new pallet, you must add some information about it to the configuration file that the compiler uses to build the runtime binary.
The pallets to be imported as dependencies for the runtime, including the location and version of the pallets to import.
The features in each pallet that should be enabled when compiling the native Rust binary. By enabling the standard (
std
) feature set from each pallet, you can compile the runtime to include functions, types, and primitives that would otherwise be missing when you build the WebAssembly binary.
Add node-authorization dependencies
To add the node-authorization
pallet to the Substrate runtime:
Open a terminal shell and change to the root directory for the node template.
Open the
runtime/Cargo.toml
configuration file in a text editor.Locate the
[dependencies]
section and add thepallet-node-authorization
crate to make it available to the node template runtime.This line imports the
pallet-node-authorization
crate as a dependency and specifies the following configuration details for the crate:The pallet features are not enabled by default when compiling the runtime.
The version identifier for the crate.
The repository location for retrieving the
pallet-node-authorization
crate.The branch for retrieving the crate.
Note that you should use the same branch and version information for all pallets to ensure that they are compatible with each other. Using pallets from different branches can result in compiler errors. This example illustrates adding pallets to the
Cargo.toml
file if the other pallets usebranch = "polkadot-v1.0.0"
.Add the
pallet-node-authorization/std
features to the list offeatures
to enable when compiling the runtime.If you forget to update the
features
section in theCargo.toml
file, you might seecannot find function
errors when you compile the runtime binary.Check that the new dependencies resolve correctly by running the following command:
Add an administrative rule
To simulate governance in this tutorial, you can configure the pallet to use the EnsureRoot
privileged function that can be called using the Sudo pallet. The Sudo pallet is included in the node template by default and enables you to make calls through the root-level administrative account. In a production environment, you would use more realistic governance-based checking.
To enable the EnsureRoot
rule in your runtime:
Open the
runtime/src/lib.rs
file in a text editor.Add the following line to the file:
Implement the Config trait
To implement the node-authorization
pallet in your runtime:
Open the
runtime/src/lib.rs
file in a text editor.Add the
parameter_types
section for the pallet using the following code:Add the
impl
section for theConfig
trait for the pallet using the following code:Add the pallet to the
construct_runtime
macro with the following line of code:Save your changes and close the file.
Check that the configuration can compile by running the following command:
Add genesis storage for authorized nodes
To configure genesis storage for authorized nodes:
Open the
node/Cargo.toml
file in a text editor.Locate the
[dependencies]
section and add thebs58
library to the node template.Save your changes and close the file.
Open the
node/src/chain_spec.rs
file in a text editor.Add genesis storage for nodes that are authorized to join the network using the following code:
Locate the
testnet_genesis
function that configures initial storage state for FRAME modules.For example:
Within the
GenesisConfig
declaration, add the following code block:Save your changes and close the file.
Verify that the node compiles
Now that you have completed the code changes, you are ready to verify that the node compiles.
To compile the node:
Change to the root of the
substrate-node-template
directory, if necessary:Compile the node by running the following command:
If there are no syntax errors, you are ready to proceed. If there are errors, follow the instructions in the compile output to fix them then rerun the
cargo build
command.
Identify account keys to use
Alice
Bob
The two other development accounts—Charlie and Dave—don't have well-known node keys or peer identifiers defined in the genesis configuration. For demonstration purposes, you can use the following keys for these accounts.
Charlie
Dave
For this tutorial, you can copy the node key to a file, then use the subkey inspect-node-key
to verify the peer identifiers for Charlie and Dave. For example, save the node key for Charlie to a file named charlie-node-key
by using a command like the following:
You can then run the following command to verify the peer identifier:
The command displays the peer identifier for the Charlie node:
If you generate node keys for your own account, save the peer identifier for the node to a file so you can pass it to subkey inspect-node-key
or other commands when needed.
Launch network nodes
You can now use the node keys and peer identifiers for the predefined accounts to launch the permissioned network and authorize other nodes to join.
For the purposes of this tutorial, you are going to launch four nodes. Three of the nodes are associated with predefined accounts and all three of those nodes are allowed to author and validate blocks. The fourth node is a sub-node that is only authorized to read data from a selected node with the approval of that node's owner.
Start the first node
Because you have configured genesis storage to use the well-known node keys for Alice and Bob, you can use the --alice
command shortcut for --name alice --validator
to start the first node.
To start the first node:
Open a terminal shell on your computer, if necessary.
Change to the root directory where you compiled the Substrate node template.
Start the first node by running the following command:
In this command, the
--node-key
option to specify the key to be used for a secure connection to the network. This key is also used internally to generate the human-readable PeerId as shown in above section.As you might have seen in other tutorials, the command-line options used are:
--chain=local
for a local testnet (not the same as the--dev
flag!).--alice
to name the nodealice
and make the node a validator that can author and finalize blocks.--port
to assign a port for peer-to-peer communication.--rpc-port
to assign a listening port for WebSocket connections.
Start the second node
You can start the second node using the --bob
command shortcut for --name bob --validator
to start the second node.
To start the second node:
Open a new terminal shell on your computer.
Change to the root directory where you compiled the Substrate node template.
Start the second node by running the following command:
After both nodes are started, you should start to see new blocks authored and finalized in both terminal logs.
Add a third node to the list of well-known nodes
To start the third node:
Open a new terminal shell on your computer.
Change to the root directory where you compiled the Substrate node template.
Start the third node by running the following command:
After you start this node, you should see there are no connected peers for the node. Because this is a permissioned network, the node must be explicitly authorized to connect. The Alice and Bob nodes were configured in the genesis
chain_spec.rs
file. All other nodes must be added manually using a call to the Sudo pallet.
Authorize access for the third node
This tutorial uses the Sudo pallet for governance. Therefore, you can use the Sudo pallet to call the addWellKnownNode
function provided by node-authorization
pallet to add the third node. To keep things simple, you can use the Polkadot/Substrate Portal application to access the Sudo pallet.
Click Developer and select Sudo.
Select nodeAuthorization and select addWellKnownNode(node, owner).
Copy and paste the hex-encoded peer identifier for the node owned by Charlie after the required 0x prefix.
Select Charlie as the node owner.
Click Submit Sudo.
In Authorize transaction, note that the Alice development account is the default root administrative account and used as the
sudo
origin for this call, then click Sign and Submit.Click Network and select Explorer to view the recent transactions.
If your nodes are not on the same local network, you should use the command-line option
--no-mdns
to disable it.
Allow connections from a sub-node
The fourth node in this network is not going to be used as a validator or added to the list of well-known nodes. This fourth node is owned by the dave
user account, but is a sub-node of the charlie
node. The sub-node can only access the network by connecting to the node owned by the charlie
parent node. It's important to remember that the parent node is responsible for any sub-node it authorizes to connect to the network. The owner of the parent node is responsible for controlling access if the sub-node needs to be removed or audited.
Because this is a permissioned network, Charlie must configure his node to allow the connection from the node owned by Dave. You can use the Polkadot/Substrate Portal application to grant this permission.
To allow the sub-node to access the network:
Click Developer and select Extrinsics.
Select nodeAuthorization and select addConnections(node, connections).
Copy and paste the hex-encoded peer identifier for the node owned by Charlie after the required 0x prefix.
For the connections parameter, copy and paste the hex-encoded peer identifier for the node owned by Dave after the required 0x prefix, then click Submit Transaction.
Review the transaction details, then click Sign and Submit.
Claim the sub-node
Before starting the sub-node, the node owner should claim the peer identifier for his node. You can use the Polkadot/Substrate Portal application to submit a transaction to claim the node owned by the dave
account.
Click Developer and select Extrinsics.
Select nodeAuthorization and select claimNode(node).
Copy and paste the hex-encoded peer identifier for the node owned by Dave after the required 0x prefix, then click Submit Transaction.
Review the transaction details, then click Sign and Submit.
Start the sub-node
After claiming the node peer identifier, you are ready to start the sub-node.
To start the sub-node:
Open a new terminal shell on your computer.
Change to the root directory where you compiled the Substrate node template.
Start the sub-node by running the following command:
Allow connections to the sub-node
You now have a network with four nodes. However, to allow the sub-node to participate, you must configure it to allow connections from the parent node owned by Charlie. The steps are similar to the ones you previously performed to allow connections from the node owned by Dave.
Click Developer and select Extrinsics.
Select nodeAuthorization and select addConnections(node, connections).
Copy and paste the hex-encoded peer identifier for the node owned by Dave after the required 0x prefix.
For the connections parameter, copy and paste the hex-encoded peer identifier for the node owned by Charlie after the required 0x prefix, then click Submit Transaction.
Review the transaction details, then click Sign and Submit.
You should now see the sub-node has only one peer—the node that belongs to Charlie—and is synchronizing blocks from the chain. If the sub-node doesn't connect to its peer node right away, try stopping and restarting the sub-node.
Keys required to submit transactions
You should note that any account can be used to sign and submit transaction that affect the behavior of other nodes. However, to sign and submit a transaction that affects a node you don't own:
The transaction must reference on chain data.
You must have the signing key for an account with the required origin available in the keystore.
In this tutorial, all of the nodes have access to the development account signing keys. Therefore, you were able to sign and submit transactions that affected any connected node using account to act on behalf of Charlie or Dave. If you were building a permissioned network for a real world application, node operators would most likely only have access to their own node keys, and node owner accounts would be required to sign and submit transactions that affect the node where they have control of the signing key.
Where to go next
In this tutorial, you learned the basics of how to build a network where some nodes have limited permissions and restricted access to network resources. To learn more about the topics introduced in this tutorial, see the following resources:
Last updated