Summary

This DIP describes the operation of the proof of authority consensus model that is used to establish consensus about the ledger state of the Diem Blockchain. In a proof of authority consensus model, known participants leverage cryptographical digital signatures to agree upon a set of transactions and their output to advance the blockchain's state. For the Diem Blockchain the set of potential entities that can participate in consensus are known as Validator Owners, while the active participants are known as the Validator Set. The adding and removing of Validator Owners and specifying the current Validator Set is left to the sole discretion of the entity managing DiemRoot account.

Background

Diem Payment Network ("DPN") is a blockchain-backed payment platform and an infrastructure for stablecoins.

The Diem Association ("DA" or the “Association”) is an independent membership organization that is responsible for the DPN technology and the development of the Diem project. Diem Networks ("DN"), a wholly owned subsidiary of DA is in the process of applying for a license as a payment system operator from the Swiss Financial Market Supervisory Authority ("FINMA"). Once granted, DN will be responsible for ensuring that DPN operates in compliance with the payment system license from FINMA.

Validator Owners are all members of the Association.

DN and DA will jointly manage the DiemRoot account. The DiemRoot account determines the composition of the Validator Set at any given time. Reasons for changing the Validator Set include new members joining the Association or existing members leaving the Association, or possible suspension of Validator Owners for breaching their obligations.

Framework Guide

Terminology

• Validator Node is a replica that runs the Diem consensus protocol to maintain and advance the blockchain state. A Validator Node processes transactions and interacts with other Validator Nodes to reach consensus on the ordering of transactions and the resulting state of the database after transaction execution.
• Validator Config is an on-chain configuration or Move resource that contains configuration information of a Validator Node. This includes a consensus public key and network addresses.
• Consensus public key verifies the digital signature authenticating the sender of a consensus message in the Diem consensus protocol.
• Network addresses define endpoints and cryptographic credentials for establishing secure connections with other Validator Nodes as well as FullNodes and other participants.
• Validator Owner is the entity responsible for the operation of a Validator Node and is a member of the Diem Association. Each Validator Owner has an account on the Diem Blockchain that stores the Validator Config Move resource (see Move Tutorial).
• Validator Operator is the entity, approved by DN, that operates a Validator Node. A Validator Operator could be run by a Validator Owner, or a Validator Operator could be a separate entity acting as an operator on behalf of one or more Validator Owners. A Validator Operator may run multiple Validator Nodes up to a maximum established by DN. The Validator Operator for a Validator Owner has permission to modify the Validator Config stored in the Validator Owner account and update its copy in the Validator Set.
• Validator Set is an on-chain Move resource represented by a vector containing the active set of Validator Owners. There exists a one-to-one relationship between a Validator Owner in the Validator Set and a Validator Node. The entries within the Validator Set consist of the Validator Owner's address as well as a copy of its Validator Config. Each Validator Owner address must appear only once in the Validator Set. Validator Nodes run according to the configuration defined in the Validator Set. Validator Set changes come in two ways: a change in the set of Validator Owners or a change in the configuration of some Validator Owners. Both cases result in a Reconfiguration.
• Reconfiguration is an on-chain configuration change. Reconfigurations are separated by epochs signified by a NewEpochEvent. If a transaction causes a Reconfiguration, that transaction is the last transaction within the current epoch. Subsequent transactions will be executed in the new epoch with the configuration change that triggered the Reconfiguration.
• DiemRoot is the sole account capable of adding or removing Validator Owner and Validator Operator accounts and specifying the current Validator Owners in the Validator Set. It may also submit an AdminScript.
• AdminScript is a transaction script that can be sent by the DiemRoot on behalf of any other account. This includes key rotation enabling DiemRoot to support account recovery for both Validator Owners and Operators.

For the aforementioned roles, Diem uses a variant of role-based access control as defined in DIP2: Diem Roles and Permissions.

Move modules

Four move modules are involved in the validator configuration management

• ValidatorConfig: defines local consensus configuration for a Validator Node of a Validator Owner.
• ValidatorOperatorConfig: defines the configuration of the Validator Operator (it only contains a human-readable name identifying the Validator Operator).
• DiemSystem: publishes the Validator Set as a global on-chain config and enforces the rules for modifying it.
• DiemConfig: a generic module that manages all of the global on-chain configurations, including the Validator Set configurations.

Move resources

For Validator Owner the Diem Account has a Validator Role and stores a ValidatorConfig resource managed by ValidatorConfig module:

resource struct ValidatorConfig {

config: Option<Config>,

operator_account: Option<address>,

human_name: vector<u8>,

}

It contains a human-readable name, human_name, of the account, a UTF-8 encoded string, which is set at the account creation time and cannot be changed. The config and operator_account fields are initially set to none. The config is a place holder for parameters of the Validator Node.

struct Config {

consensus_pubkey: vector<u8>,

validator_network_addresses: vector<u8>,

fullnode_network_addresses: vector<u8>,

}

For Validator Operator the Diem Account has a Validator Operator Role (see dip-2: Diem Roles and Permissions) and stores a ValidatorOperatorConfig resource managed by the ValidatorOperatorConfig module.

resource struct ValidatorOperatorConfig {

human_name: vector<u8>,

}

The Validator Set consists of a consensus signature scheme's id and the set of Validator Info described next.

struct DiemSystem {

scheme: u8,

validators: vector<ValidatorInfo>,

}

Validator Info stores the address of the Validator Owner, the consensus voting power, the copy of the Validator Owner's config (the copy is made when the Validator Owner is added to the set or when the Validator Operator triggers an update of the config in the set), the last time the config was updated (when the Validator Owner was added to the Validator Set or when the config was updated by Validator Operator whichever is later).

struct ValidatorInfo {

addr: address,

consensus_voting_power: u64,

config: ValidatorConfig::Config,

last_config_update_time: u64,

}

Transaction scripts

The following transaction scripts can be run by the DiemRoot:

• create_validator_account - creates a Validator Owner account (an account with Validator role)
• create_validator_operator_account - to create a Validator Operator account
• add_validator_and_reconfigure - to add Validator Owner to the Validator Set with its current config and trigger reconfiguration
• remove_validator_and_reconfigure - to remove Validator Owner from the Validator Set and trigger reconfiguration

The following transaction scripts can be run by the Validator Owner:

• set_validator_operator - to designate the Validator Operator

The following transaction scripts can be run by the Validator Operator:

• set_validator_config_and_reconfigure - to change values of the Validator Config resource and update the config in the Validator Set (aborts if the Validator Owner is not in the Validator Set)

The following script relevant to the operations of a Validator Owner and Validator Operator can also be run by any Diem Account's owner:

• rotate_authentication_key - to rotate the authentication key of an account.

More on these transaction scripts (their specifications, information about error-codes and emitted events) can be found in Overview of Diem Transaction Scripts.

Workflows

This section details the workflows or common scenarios related to Validator Set management.

Validator Owner and Validator Operator accounts creation

DiemRoot (through the Association Operation Services, "AOS") creates Validator Owner and Validator Operator accounts. To get an account created, each Validator Owner or Validator Operator needs to provide an authentication key and a name of their organization to DiemRoot. The authentication key is a 32 byte array, derived from the public verification key of Ed25519 or MultiEd25519 signature schemes.

DiemRoot creates the Validator Owner's account by sending the create_validator_account transaction script. An account address of a Validator Owner is derived from its name. A Validator Owner may ask the DiemRoot to manage the newly created account in which case for account creation a Validator Owner only needs to provide a name. In the case when DiemRoot maintains ownership of a Validator Owner's account the auth key of that account is set to an all-zeroes string and the transactions on behalf of the Validator Owner are sent via AdminScripts.

DiemRoot creates the Validator Operator's account by sending the create_validator_account transaction script. An account address of a Validator Operator is derived from their authentication key in the usual way: the authentication key is obtained by SHA3-256-hashing of the scheme ID (one byte: 0 for Ed25519 signature scheme and 1 for MultiEd25519) concatenated with the bytes of the public key, the address is the last 16 bytes of the authentication key.

Validator Owner to set the Validator Operator

Validator Owner may call a transaction script set_validator_operator to set the operator_account field of the ValidatorConfig resource. This script will succeed only if the operator_account has a Validator Operator role.

The transaction script takes a human-readable name of the Validator Operator (for an additional validation check) and its on-chain address. When successful this transaction changes the field operator_account of the ValdiatorConfig resource of the Validator Owner calling the transaction. When the operator_account is set, only the operator_account may change the config field of the ValidatorConfig resource.

Validator Operator (or Owner) to set the Config

For a Validator Owner who is not yet added to the Validator Set, the Validator Operator may change the config by calling a transaction script register_validator_config. This script takes an address of the Validator Owner (to avoid confusion when one Validator Operator runs Validator Nodes for multiple Validator Owners), a new consensus public key (a 32 elements byte array) and two byte arrays for network addresses: validator_network_addresses for other Validator Operators to communicate with this Validator Operator during consensus and fullnode_network_addresses for network participation for nodes outside the current Validator Set.

If a Validator Owner is in the Validator Set, the operator_account may update the config both locally and in the Validator Set by sending set_validator_config_and_reconfigure transaction script, this transaction script triggers the Reconfiguration.

Validator Owner to be added/removed from the Validator Set

A Validator Node is consensus-ready once the Validator Operator sets the config and the node is operational. At which point, AOS can submit a transaction from the DiemRoot account: add_validator_and_reconfigure. Once this transaction executes, it triggers the Reconfiguration, other Validator Operators connect to the Validator Node and the Validator Operator starts participating in the protocol. Note that the size of the Validator Set and hence the size of the quorum for consensus decisions increases.

Under certain circumstances, such as, members leaving the Association or a Validator Owner violating its obligations, the DiemRoot may remove or suspend a Validator Owner from the Validator Set. It does so by calling the remove_validator_and_reconfigure transaction script, which triggers the Reconfiguration. Note, that the size of the Validator Set and hence the size of the consensus quorum decreases.