This page contains information about how to manage multiple keys on a group of nodes.
Multikey architecture overview
Since the mainnet launch, and up until the release candidate RC/v1.6.0, each node could have managed only
one key. So the relationship between the nodes and staked validator keys is
1:1, the node "following" the shard where
the managed key is assigned.
The multikey feature allows a node instance to hold more than one key. However, since MultiversX is a sharded blockchain
and a single node is only able to store the state of a single shard at a time, we need a group of nodes with exactly
one node in each shard, similar with what we have on observing squad. Also, in each epoch, the keys can be shuffled among shards.
This means that running multiple keys will require at least the number of shards + 1 node instances (one for each shard + metachain).
The same set of keys should be provided for all node instances.
This type of nodes used in multikey operation can be assimilated as a hybrid between an observer node and a validator.
It behaves as an observer by holding in the
validatorKey.pem file a BLS key that will never be part of the consensus
group and the shard should be specified in the
prefs.toml file, so the node will not change shards.
The node behaves also as a validator (or multiple validators) by monitoring and emitting consensus messages,
whenever required on the behalf of the managed keys set.
Since an observer already performs block validation in its own shard, it can be easily used to manage a group of validator
keys and propose or validate blocks on behalf of the keys it possesses.
To summarize, this type of node can use any provided keys, in any combination, to generate consensus messages provided
that those used keys are part of the consensus group in the current round. With the multikey feature, the relationship
n:m, providing that
n is the number of keys managed by an entity and
m is the number of shards + 1.
This feature is purely optional. Normal
1:1 relationship between the keys and the nodes is still supported. The multikey
mode should optimize the costs when running a set of keys (check Economics running multikey nodes section)
The following image describes the keys and nodes relationship between the single operation mode versus multikey operation mode.
General implementation details
The nodes running with the multikey feature, beside deciding the consensus group (which is normally done on each node),
can access the provided keys set and use, in any combination, one or more keys, if the node detects that at least one managed
key is part of the consensus group.
The code changes to support multikey nodes affected mainly the
The group managing the set of keys (we will call them multikey nodes or multikey group), will pass the validators BLS information tight to "virtual" peer IDs. A "virtual peer ID" is a generated p2p identity that the p2p network can not connect to as it does not have a real address bind to. Consequentially, this feature brings a new layer of security as the multikey nodes will hide the relationship between the validator BLS keys and the host that manages those BLS keys.
The redundancy sub-system has been upgraded to accommodate the multikey requirements keeping the multiple redundancy
fallback groups operation. A fallback multikey group will monitor each managed key for missed consensus activity independent on
each managed node. So, a bad configured main group, offline or stuck main group nodes should trigger fallback events on
the redundancy group.
Example: if main multikey group was set to manage the following key set
[key_0, key_1 ... key_e-1, key_e+1 ... key_n]
(mind the missing
key_e) and the redundancy fallback multikey group has the set
[key_0, key_1 ... key_e-1, key_e, key_e+1 ... key_n],
then, the fallback group, after
k misses in the consensus activity (propose/sign block) will start using that
key_e as it
was the only key assigned to the multikey group (
k is the value defined in the
Economics running multikey nodes
n managed keys we will need at least a group of nodes, there is a threshold that a staking operator
will want to consider when deciding to switch the operation towards the multikey mode. The switch becomes attractive for the
operator when the number of managed keys is greater than the number of shards. So, for the time being, when we have
at least 5 keys that are either eligible or waiting, the switch to multikey mode becomes feasible.
The switch towards the multikey operation will only require aggregating all BLS keys in a new file, called
that will be loaded by default from the same directory where the
validatorKey.pem file resides. The path can be altered by using the
binary flag called
Example of an
-----BEGIN PRIVATE KEY for e296e97524483e6b59bce00cb7a69ec8c0d1ac4227925f07fdd57b3ab4ec2f64b240728a0a3c5be2930aea570bf12c12314e25d942b106472800e51524add26ec9546475c1cfae91dd7e799f256d1b0758e17aaa3898c29d489bd87c86d04498-----
-----END PRIVATE KEY for e296e97524483e6b59bce00cb7a69ec8c0d1ac4227925f07fdd57b3ab4ec2f64b240728a0a3c5be2930aea570bf12c12314e25d942b106472800e51524add26ec9546475c1cfae91dd7e799f256d1b0758e17aaa3898c29d489bd87c86d04498-----
-----BEGIN PRIVATE KEY for 5585ddceb6b7bf0d308162efd895d0717b22bab6b0412f09fb9cee234be73d197bfef8ae10064be5733472c573894015029672b70f63e0b58c7ab2e831ee0aff88b868e4d712bec0baf9a1cd1982e138af9b6cc55e4454b01cb8ad02a064f515-----
-----END PRIVATE KEY for 5585ddceb6b7bf0d308162efd895d0717b22bab6b0412f09fb9cee234be73d197bfef8ae10064be5733472c573894015029672b70f63e0b58c7ab2e831ee0aff88b868e4d712bec0baf9a1cd1982e138af9b6cc55e4454b01cb8ad02a064f515-----
-----BEGIN PRIVATE KEY for 791c7e2bd6a5fb1371af18269267ad8ef9e56e264c4c95703c57526b16b84dd8df6347c0cc14f93d595a12316d38ae11264e05d2fa26d80387d12db52c1a98e93064d073d02549c71ec4e352d73724c21c02245b25d3643b532fac25d7580f0b-----
-----END PRIVATE KEY for 791c7e2bd6a5fb1371af18269267ad8ef9e56e264c4c95703c57526b16b84dd8df6347c0cc14f93d595a12316d38ae11264e05d2fa26d80387d12db52c1a98e93064d073d02549c71ec4e352d73724c21c02245b25d3643b532fac25d7580f0b-----
The existing fields
Identity will be applied to all managed and loaded BLS keys. The
be suffixed with an order index for all managed keys.
For example, suppose we have the above example of the
allValidatorsKeys.pem file and the
NodeDisplayName is set to
The name for the managed keys will be:
If part of the managed BLS keys will need to be run on a different identity and/or different naming, the file section called
NamedIdentity will be of great use.
Following the above example, if we need to use a different identity and/or node name for the
we will need to define the section as:
# NamedIdentity represents an identity that runs nodes on the multikey
# There can be multiple identities set on the same node, each one of them having different bls keys, just by duplicating the NamedIdentity
# Identity represents the keybase/GitHub identity for the current NamedIdentity
Identity = "identity2"
# NodeName represents the name that will be given to the names of the current identity
NodeName = "random"
# BLSKeys represents the BLS keys assigned to the current NamedIdentity
BLSKeys = [
which will generate the naming as: