Last update: November 22, 2021

Adding and removing signers and validators

You can add and remove signers to/from an existing Clique network, and add and remove validators to/from an existing IBFT 2.0 or QBFT network.

To propose adding or removing participants using the JSON-RPC methods, enable the HTTP interface with --rpc-http-enabled or the WebSockets interface with --rpc-ws-enabled.

Clique

The Clique API methods are not enabled by default. To enable them, specify the --rpc-http-api or --rpc-ws-api option and include CLIQUE.

The JSON-RPC methods to add or remove signers are:

Important

A majority of existing signers must agree to add or remove a signer. That is, more than 50% of signers must execute clique_propose to add or remove a signer. For example, if you have four signers, the same vote must be made by three signers.

To view signer metrics for a specified block range, call clique_getSignerMetrics.

Tip

clique_getSignerMetrics can be used to identify validators that are not active. An inactive validator’s lastProposedBlockNumber is 0x0.

Adding a signer

To propose adding a signer to a Clique network, call clique_propose, specifying the address of the proposed signer and true. A majority of signers must execute the call.

JSON-RPC clique_propose request example

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_propose","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' <JSON-RPC-endpoint:port>

When the signer creates the next block, the signer adds a vote to the block for the proposed signer.

When more than half of the existing signers propose adding the signer, with their votes distributed in blocks, the signer can begin signing blocks.

To return a list of signers and confirm the addition of a proposed signer, call clique_getSigners.

JSON-RPC clique_getSigners request example

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"], "id":1}' <JSON-RPC-endpoint:port>

To discard your proposal after confirming the addition of a signer, call clique_discard specifying the address of the proposed signer.

JSON-RPC clique_discard request example

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_discard","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' <JSON-RPC-endpoint:port>

Removing a signer

The process for removing a signer from a Clique network is the same as adding a signer, except you specify false as the second parameter of clique_propose.

Epoch transition

At each epoch transition, Clique discards all pending votes collected from received blocks. Existing proposals remain in effect and signers re-add their vote the next time they create a block.

Define the number of blocks between epoch transitions in the Clique genesis file.

IBFT 2.0

In an IBFT 2.0 network, add and remove validators by voting or if network conditions require it, without voting.

Adding and removing validators by voting

The IBFT API methods are not enabled by default. To enable them, specify the --rpc-http-api or --rpc-ws-api option and include IBFT.

The JSON-RPC methods to add or remove validators are:

Important

A majority of existing validators must agree to add or remove a validator. That is, more than 50% of validators must execute ibft_proposeValidatorVote to add or remove a validator. For example, if you have four validators, the same vote must be made by three validators.

To view validator metrics for a specified block range, use ibft_getSignerMetrics.

Tip

ibft_getSignerMetrics can be used to identify validators that are not active. An inactive validator’s lastProposedBlockNumber is 0x0.

Adding a validator

To propose adding a validator to an IBFT 2.0 network, call ibft_proposeValidatorVote, specifying the address of the proposed validator and true. A majority of validators must execute the call.

JSON-RPC ibft_proposeValidatorVote request example

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_proposeValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' <JSON-RPC-endpoint:port>

When the validator proposes the next block, the protocol inserts one proposal received from ibft_proposeValidatorVote into the block. If blocks include all proposals, subsequent blocks proposed by the validator will not contain a vote.

When more than half of the existing validators have published a matching proposal, the protocol adds the proposed validator to the validator pool and the validator can begin validating blocks.

To return a list of validators and confirm the addition of a proposed validator, use ibft_getValidatorsByBlockNumber.

JSON-RPC ibft_getValidatorsByBlockNumber request example

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockNumber","params":["latest"], "id":1}' <JSON-RPC-endpoint:port>

To discard your proposal after confirming the addition of a validator, call ibft_discardValidatorVote, specifying the address of the proposed validator.

JSON-RPC ibft_discardValidatorVote request example

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_discardValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' <JSON-RPC-endpoint:port>

Removing a validator

The process for removing a validator from an IBFT 2.0 network is the same as adding a validator except you specify false as the second parameter of ibft_proposeValidatorVote.

Epoch transition

At each epoch transition, IBFT 2.0 discards all pending votes collected from received blocks. Existing proposals remain in effect and validators re-add their vote the next time they create a block.

An epoch transition occurs every epochLength blocks. Define epochlength in the IBFT 2.0 genesis file.

Adding and removing validators without voting

IBFT 2.0 network conditions might not allow voting to change validators. For example, if a majority of the current validators are no longer participating in the network, a vote to add or remove validators can’t be successful. You can bypass voting and specify new validators in the genesis file.

To add or remove validators without voting:

Stop all nodes in the network.

In the genesis file, add the transitions configuration item where:

<BlockNumber> is the upcoming block at which to change validators.
<ValidatorAddressX> ... <ValidatorAddressZ> are strings representing the account addresses of the validators after <BlockNumber>.

Transitions object in the genesis file

Syntax

{
  "config": {
     ...
     "ibft2": {
       "blockperiodseconds": 2,
       "epochlength": 30000,
       "requesttimeoutseconds": 4
     },
     "transitions": {
       "ibft2": [
       {
         "block": <BlockNumber>,
         "validators": [
            <ValidatorAddressX>,
            ...
            <ValidatorAddressZ>
         ]
       }
       ]
     }
  },
  ...
}

Example

{
  "config": {
    ...
    "ibft2": {
      "blockperiodseconds": 2,
      "epochlength": 30000,
      "requesttimeoutseconds": 4
    },
    "transitions": {
       "ibft2": [
       {
        "block": 25,
        "validators": [
          "0x372a70ace72b02cc7f1757183f98c620254f9c8d",
          "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb"
          ]
        }
       ]
    }
  },
  ...
}

Restart all nodes in the network using the updated genesis file.
To verify the changes after the transition block, call ibft_getValidatorsByBlockNumber, specifying latest.

Caution

Do not specify a transition block in the past. Specifying a transition block in the past could result in unexpected behavior, such as causing the network to fork

QBFT

QBFT provides two methods (modes) to manage validators:

Block header validator selection - Existing validators propose and vote to add or remove validators, or if network conditions require it, without voting.
Contract validator selection - Use a smart contract to add or remove validators.

Adding and removing validators by voting

The QBFT API methods are not enabled by default. To enable them, specify the --rpc-http-api or --rpc-ws-api option and include QBFT.

The JSON-RPC methods to add or remove validators are:

Important

A majority of existing validators must agree to add or remove a validator. That is, more that 50% of validators must execute qbft_proposeValidatorVote to add or remove a validator. For example, if you have four validators, the vote must be made on three validators.

To view validator metrics for a specified block range, use qbft_getSignerMetrics.

Tip

qbft_getSignerMetrics can be used to identify validators that are not active. The validator’s lastProposedBlockNumber will be 0x0

Adding a validator

To propose adding a validator, call qbft_proposeValidatorVote, specifying the address of the proposed validator and true. A majority of validators must execute the call.

JSON-RPC qbft_proposeValidatorVote request example

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_proposeValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' <JSON-RPC-endpoint:port>

When the validator proposes the next block, the protocol inserts one proposal received from qbft_proposeValidatorVote into the block. If blocks include all proposals, subsequent blocks proposed by the validator will not contain a vote.

When more than half of the existing validators have published a matching proposal, the protocol adds the proposed validator to the validator pool and the validator can begin validating blocks.

To return a list of validators and confirm the addition of a proposed validator, use qbft_getValidatorsByBlockNumber.

JSON-RPC qbft_getValidatorsByBlockNumber request example

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockNumber","params":["latest"], "id":1}' <JSON-RPC-endpoint:port>

To discard your proposal after confirming the addition of a validator, call qbft_discardValidatorVote, specifying the address of the proposed validator.

JSON-RPC qbft_discardValidatorVote request example

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_discardValidatorVote","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' <JSON-RPC-endpoint:port>

Removing a validator

The process for removing a validator is the same as adding a validator except you specify false as the second parameter of qbft_proposeValidatorVote.

Epoch transition

At each epoch transition, QBFT discards all pending votes collected from received blocks. Existing proposals remain in effect and validators re-add their vote the next time they create a block.

An epoch transition occurs every epochLength blocks. Define epochlength in the QBFT genesis file.

Adding and removing validators without voting

QBFT network conditions might not allow voting to change validators. For example, if a majority of the current validators are no longer participating in the network, so a vote to add or remove validators will never be successful. You can bypass voting and specify new validators in the genesis file.

To add or remove validators without voting:

Stop all nodes in the network.

In the genesis file, add the transitions configuration item where:

<BlockNumber> is the upcoming block at which to change validators.
<ValidatorAddressX> ... <ValidatorAddressZ> are strings representing the account addresses of the validators after <BlockNumber>.

Transitions object in the genesis file

Syntax

{
  "config": {
     ...
     "qbft": {
       "blockperiodseconds": 2,
       "epochlength": 30000,
       "requesttimeoutseconds": 4
     },
     "transitions": {
       "qbft": [
       {
         "block": <BlockNumber>,
         "validators": [
            <ValidatorAddressX>,
            ...
            <ValidatorAddressZ>
         ]
       }
       ]
     }
  },
  ...
}

Example

{
  "config": {
    ...
    "qbft": {
      "blockperiodseconds": 2,
      "epochlength": 30000,
      "requesttimeoutseconds": 4
    },
    "transitions": {
       "qbft": [
       {
        "block": 25,
        "validators": [
          "0x372a70ace72b02cc7f1757183f98c620254f9c8d",
          "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb"
          ]
        }
       ]
    }
  },
  ...
}

Restart all nodes in the network using the updated genesis file.
To verify the changes after the transition block, call qbft_getValidatorsByBlockNumber, specifying latest.

Caution

Do not specify a transition block in the past. Specifying a transition block in the past could result in unexpected behaviour, such as causing the network to fork.

Adding and removing validators using a smart contract

Users can create their own smart contracts to add or remove validators based on their organizational requirements. View the example smart contract for more information on how to create and deploy the smart contract.

You can pre-deploy the validator smart contract in a new QBFT network by specifying the contract details in the genesis file. For existing QBFT networks you need to compile and deploy the contract using a transaction, then obtain the contract address from the receipt and use that in a transition.

Important

You cannot use the JSON-RPC calls to add or remove validators when using a smart contract to manage nodes. You must interact with the contract functions using transactions.

Overriding smart contract validators

If you can’t manage your validators using the smart contract due to network conditions, you can bypass the smart contract and specify new validators in the genesis file. For example, you lose quorum for your current list of contract validators, and you can’t perform a transaction to vote more in.

This requires temporarily switching to block header validator selection mode.

To bypass the smart contract and specify new validators:

Stop all nodes in the network.

In the genesis file, add a transitions configuration item where:

<BlockNumber> is the upcoming block at which to change validators.
<SelectionMode> is the validator selection mode to switch to. In this case we’ll switch to the blockheader mode temporarily.
<ValidatorAddressX> ... <ValidatorAddressZ> are strings representing the account addresses of the validators after <BlockNumber>. These validators only need to be sufficient to progress the chain and allow a new contract to be deployed.

Syntax

{
  "config": {
     ...
     "qbft": {
       "blockperiodseconds": 2,
       "epochlength": 30000,
       "requesttimeoutseconds": 4,
       “validatorcontractaddress”: “0x0000000000000000000000000000000000007777”
     },
     "transitions": {
       "qbft": [
       {
         "block": <BlockNumber>,
         "validatorselectionmode": <SelectionMode>,
         "validators": [
            <ValidatorAddressX>,
            ...
            <ValidatorAddressZ>
         ]
       }
       ]
     }
  },
  ...
}

Example

{
  "config": {
     ...
     "qbft": {
       "blockperiodseconds": 2,
       "epochlength": 30000,
       "requesttimeoutseconds": 4,
       "validatorcontractaddress": "0x0000000000000000000000000000000000007777"
     },
     "transitions": {
       "qbft": [
       {
         "block": 2555,
         "validatorselectionmode": "blockheader",
         "validators": [
            "0x372a70ace72b02cc7f1757183f98c620254f9c8d",
            "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb"
         ]
       }
       ]
     }
  },
  ...
}

Restart all nodes in the network using the updated genesis file.
Deploy a new contract to the blockchain containing the desired list of validators.
Stop all nodes in the network.

In the genesis file, add another transitions configuration item where:

<BlockNumber> is the upcoming block at which to change validators.
<SelectionMode> is the validator selection mode to switch to. In this case we’ll switch to contract mode.
<NewValidatorContractAddress> is the address of the new smart contract.

Syntax

{
  "config": {
     ...
     "qbft": {
       "blockperiodseconds": 2,
       "epochlength": 30000,
       "requesttimeoutseconds": 4,
       “validatorcontractaddress”: “0x0000000000000000000000000000000000007777”
     },
     "transitions": {
       "qbft": [
       {
        "block": 2555,
        "validatorselectionmode": "blockheader",
        "validators": [
          "0x372a70ace72b02cc7f1757183f98c620254f9c8d",
          "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb"
          ]
        },
       {
         "block": <BlockNumber>,
         "validatorselectionmode": <SelectionMode>,
         "validatorcontractaddress": <NewValidatorContractAddress>
       }
       ]
     }
  },
  ...
}

Example

{
  "config": {
     ...
     "qbft": {
       "blockperiodseconds": 2,
       "epochlength": 30000,
       "requesttimeoutseconds": 4,
       “validatorcontractaddress”: “0x0000000000000000000000000000000000007777”
     },
     "transitions": {
       "qbft": [
       {
        "block": 2555,
        "validatorselectionmode": "blockheader",
        "validators": [
          "0x372a70ace72b02cc7f1757183f98c620254f9c8d",
          "0x9811ebc35d7b06b3fa8dc5809a1f9c52751e1deb"
          ]
        },
       {
         "block": 2755,
         "validatorselectionmode": "contract",
         "validatorcontractaddress": “0x0000000000000000000000000000000000009999”
       }
       ]
     }
  },
  ...
}

Restart all nodes in the network using the updated genesis file.