Become a baker using the Concordium Client#

This guide takes you through the steps involved in upgrading your node to a baker node and managing the node using the Concordium Client.

The process of becoming a baker involves the following:

  1. Create an account in the wallet and acquire CCD.

  2. Create a set of baker keys.

  3. Register the baker keys with the account.

  4. Start the node with the baker keys.

After completing these steps, the baker node will bake blocks. If a baked block is added to the chain, the baker receives a reward.

Note

In this section the name bakerAccount indicates the name of the account that will be used to register and manage a baker.

Prerequisites#

  • Run a node

  • Create an account

  • Export the JSON file with the account information

  • Install the Concordium Client

For general information about baking concepts, see Bakers.

Start baking#

Import the account#

This section provides a brief description of how to import an account using the Concordium Client.

Note

You can only import accounts created in the Concordium Wallet for Mobile or Concordium Wallet for Web into the Concordium Client. That is, you cannot import accounts created in the Desktop Wallet because they are created using a LEDGER device. You get the account information by exporting a JSON file with the account information from the Concordium Legacy Wallet. For more information, see Make a backup of identities and accounts.

To import an account run:

$concordium-client config account import <path/to/exported/file> --name bakerAccount

For the Concordium Wallet for Web, use the following command:

concordium-client config account import <Wallet.export> --name <Your-Wallet-Name>.json

concordium-client asks for a password to decrypt the exported file and import all accounts. The same password will be used for encrypting the transaction signing keys and the encrypted transfers key.

Create and register baker keys#

Each account has a unique baker ID that is used when registering its baker. This ID has to be provided by the network and currently cannot be precomputed. This ID must be given inside the baker keys file to the node so that it can use the baker keys to create blocks. The concordium-client will automatically fill this field when performing the following operations.

To create a fresh set of keys run:

$concordium-client baker generate-keys <keys-file>.json

You can choose an arbitrary name for the <keys file>. To register the keys in the network you need to be running a node and send a baker add transaction to the network:

$concordium-client baker add MyBakerKeys.json --sender bakerAccount --stake <amount-to-stake> --open-delegation-for all --delegation-transaction-fee-commission 0.1 --delegation-baking-commission 0.1 --delegation-finalization-commission 1.0 --baker-url https://example.com/baker --out <concordium-data-dir>/baker-credentials.json

where you replace

  • MyBakerKeys.json with the name of baker keys file you generated

  • <amount-to-stake> with the CCD amount for the baker’s initial stake

  • MyBakerURL with the URL containing information for your baker pool; can be left as an empty string if you do not want to provide a URL.

  • <concordium-data-dir> with any path of your choice.

    Note

    For a node on Docker, the <concordium-data-dir> must use the following paths:

    • on Linux and MacOS: ~/.local/share/concordium

    • on Windows: %LOCALAPPDATA%\\concordium.

    Remember to configure your node to bake using this path:

Keep the output file name as baker-credentials.json.

The following arguments are also required for the baker add transaction:

  • --open-delegation-for sets whether the baker’s pool is open for delegators. Options are: none (no delegators will be allowed), all (any account can delegate), existing (only existing delegators can delegate).

  • --baker-url is the URL for baker information. The URL should resolve to (JSON-formatted) metadata about the baker.

  • --out can be used to write a baker credential file containing the baker ID (and the supplied keys) to use when starting a baker node.

  • --delegation-transaction-fee-commission specifies the transaction fee commission for the baker pool.

  • --delegation-baking-commission specifies the baking commission for the baker pool.

  • --delegation-finalization-commission specifies the finalization commission for the baker pool.

Note

To find the range for the commissions, see the Concordium client Show Chain Parameters command.

The following arguments are optional. If no selection is made, earnings are restaked automatically.

  • --restake sets that earnings are restaked.

  • --no-restake sets that earnings are not restaked. This flag means that rewards to the staked amount are not added on the baker automatically. Read more about this behavior in the section Restake earnings.

Warning

concordium-client will offer to encrypt the generated baker-credentials.json file. Choose not to encrypt it since Concordium does not support easily starting a baker with encrypted baker credentials. If this is a firm requirement for you, then you need to run the debian package and configure it appropriately.

Warning

Do not stake all of your funds or you will not have enough funds to cover transaction fees.

To start the node with these baker keys and bake blocks, configure the node to use the baker keys, and restart it. The node will automatically start baking when the baker is included in the bakers for the current epoch.

This change is executed immediately, and it will take effect at the next pay day after the one in which the transaction for adding the baker was included in a block. If the change is made in the last epoch before pay day, then the change will not occur until the following pay day.

When transaction is included in a block

At next pay day

Change is visible by querying the node

Baker is included in the baking committee

Manage the baker#

Check the status of the baker and its lottery power#

To see if the node is baking, you can check various sources that offer different degrees of precision in the information displayed.

  • In the network dashboard, the baker ID of the node is shown in the Baker column.

  • Using the concordium-client you can check the list of current bakers and the relative staked amount that they hold, that is, their lottery power. The lottery power determines how likely it is that a given baker will win the lottery and bake a block.

      $concordium-client consensus show-parameters --include-bakers
      Election nonce:      07fe0e6c73d1fff4ec8ea910ffd42eb58d5a8ecd58d9f871d8f7c71e60faf0b0
      Bakers:
                              Account                       Lottery power  Account Name
         ------------------------------------------------------------------------------
      0: 4fvxZZ225xcEiCkgXTZt3cSReYgbxiMsSoj1UhAbGCsqvVg9N7   17.0326 %
      1: 3p8FSc3KN5pKxRvEdsvJS8VS21KbkRS3x4MnGq1t6omuJXydJQ   17.0498 %
      2: 39zGK3yRxHjgVVnHae2cgZBo6uWtC5Qg8GkmtMjPsJYgDc5pfF   17.0514 %
      3: 353yq84vTgYZcVLpj4Vd5fdgGbMxAUpkktNnDFs1ogzSvDxMiH   17.0254 %
      4: 33PbbH58cQj6CAHfLGy5z3FDKhHtjohQmK3ff63tzXJLWsAm8V   17.0600 %
     48: 4QdCxcP9cApLxA8UGFXiY1HjSPnSkUaeVUERU8BmBdStgnS5Vh    2.8368 %
     54: 4Z28EXyghd7tLbrMntGZxjBypwGxbQdcnexmeWxPaVeyvFC4bk    0.0144 %
     99: 3aj3DHzofkuAG7JweHJdhwcuVZePXNrN7JvZLuoTnJgiK1dfYM    0.1418 %
    108: 4PXYJcvLLz7cgdn9UnYhhB35zrMP6azPSoh4oL6Vr9gvSMZDDi    2.8368 %
    223: 3zZPUWS8BMdeCAsGzPiD512mVJS4gDjUWFFsFsbPSWnvHPL2kZ   <0.0001 %
    
  • Using the concordium-client you can check that the account has registered a baker and the current amount that is staked by that baker.

    $./concordium-client account show bakerAccount
    ...
    
    Baker: #22
     - Staked amount: 10.000000 CCD
     - Restake earnings: yes
    ...
    
  • If the staked amount is high enough, and there is a node running with the baker keys loaded, the baker should eventually produce blocks. When this happens, you can see in your wallet that the account is receiving baking rewards.

Update the staked amount#

To update the baker stake run

$concordium-client baker update-stake --stake <newAmount> --sender bakerAccount

When the staked amount is modified, the probability that a baker gets elected to bake blocks is also modified.

When a baker adds a stake for the first time or increases the stake, that change is executed on the chain and becomes visible as soon as the transaction is included in a block (can be seen through concordium-client account show bakerAccount) and takes effect at the next pay day. If the change is made in the last epoch before pay day, then the change will not occur until the following pay day.

When transaction is included in a block

At next pay day

Change is visible by querying the node

Baker uses the new stake

When a baker decreases the staked amount, the change requires a 21 day cool-down to take effect. The change becomes visible on the chain when the transacton is included in a block and takes effect at the next pay day after the cool-down ends. It can be consulted through concordium-client account show bakerAccount:

$concordium-client account show bakerAccount
...

Baker: #22
 - Staked amount: 50.000000 CCD to be updated to 20.000000 CCD at epoch 261  (2020-12-24 12:56:26 UTC)
 - Restake earnings: yes

...

When transaction is included in a block

First pay day after cool-down

Change is visible by querying the node

Baker uses the new stake

Stake can be increased, decreased again or baker can be removed

Note

In the Mainnet, the cool-down duration for reducing baker stake is set to 21 days. This value can be checked as follows:

$concordium-client consensus show-chain-parameters
...
      + pool owner cooldown duration: 21d
...

Warning

The staked amount is locked. That is, you can’t transfer it or use it for payment. You should take this into account and consider staking an amount that will not be needed in the short term. In particular, to deregister a baker or to modify the staked amount you need to own some non-staked CCD to cover the transaction costs.

Restake the earnings#

When participating as a baker in the network and baking blocks, the account receives rewards on each baked block. These rewards are automatically added to the staked amount by default.

You can choose to modify this behavior and instead receive the rewards in the account balance without staking them automatically. You can change this switch through concordium-client:

$concordium-client baker update-restake False --sender bakerAccount
$concordium-client baker update-restake True --sender bakerAccount

Changes to the restake flag will take effect immediately; however, the changes start affecting baking and finalizing power in the next pay day. If the change is made in the last epoch before pay day, then the change will not occur until the following pay day. The current value of the switch can be seen in the account information which you can query using concordium-client:

$concordium-client account show bakerAccount
...

Baker: #22
 - Staked amount: 50.000000 CCD
 - Restake earnings: yes

...

When transaction is included in a block

At pay day

Change is visible by querying the node

Earnings will [not] be restaked automatically

If restaking automatically, the gained stake affects the lottery power

When the baker is registered, it will automatically restake the earnings, but you can change this by providing the --no-restake flag to the baker add command as shown in the following:

$concordium-client baker add baker-keys.json --sender bakerAccount --stake <amount-to-stake> --out baker-credentials.json --no-restake

Finalization#

Finalization is the process by which a block is marked to be “finalized”, i.e., part of the authoritative chain. Transactions that are part of finalized blocks are considered authoritative. New blocks can be only added following the last finalized block to ensure the integrity of the chain. The finalization process is conducted by the bakers with an effective stake amount of at least 0.1% of the total amount (effective stake) of CCD in pools, known as the Finalization committee. Total stake in pools is referred to as total stake in pools without Passive Delegation.

Finalizers sign a block, and their collective signatures are aggregated to form a quorum certificate. This quorum certificate is then included in the next block. When two blocks that are parent-child are in consecutive rounds in the same epoch and both have a quorum certificate, then the block in the first of these rounds (together with its ancestors) is considered finalized. Why isn’t the child block considered to be final if it has a QC? This is to cover edge cases where network delays cause the QC of a block to not be received by the next block producer before a timeout. In that case, the block gets skipped by the next block producer and it cannot be considered final. To resolve this, only the first among two consecutive certified blocks is considered to be final.

Finalization happens at a minimum one second after block creation. A new block has to be created descended from that block for finalization to happen.

When a sufficiently large number of members of the committee have received the block and agree on its outcome, the block is finalized. Newer blocks must have the finalized block as an ancestor to ensure the integrity of the chain.

Update baker keys#

If it is necessary to update your baker keys, you need to first generate new baker keys. To create a fresh set of keys run:

$concordium-client baker generate-keys <keys-file>.json

You can choose an arbitrary name for the keys file.

Then run the transaction:

$concordium-client baker set-key <keys-file>.json --sender <account> --out <concordium-data-dir>/baker-credentials.json

--sender is the name or address of the transaction’s sender account. The name is the one that’s used when you import the account (assuming that this was done). It defaults to the account name “default”.

If you want to keep the baker-credentials.json output file in the same location as your other Concordium files, you can omit <concordium-data-dir>/.

To start the node with these baker keys and bake blocks you need to restart the node.

Configure a baker#

Use baker configure to configure a baker and open a baker pool. The following is an example of how configure baker might be used:

$concordium-client baker configure --sender "acc1" --stake 14001 --open-delegation-for existing --delegation-transaction-fee-commission 0.1 --delegation-baking-commission 0.1 --delegation-finalization-commission 1.0 --baker-url https://example.com/baker --keys-in MyBakerKeys.json --keys-out <concordium-data-dir>/baker-credentials.json

Configure baker has the following optional arguments:

  • --sender is the name or address of the baker account.

  • --stake is an amount of CCD that is the intended equity capital of the baker

  • --restake sets that earnings are restaked.

  • --no-restake sets that earnings are not restaked.

  • --open-delegation-for sets whether the baker’s pool is open for delegators. Options are: none (no delegators will be allowed), all (any account can delegate), existing (only existing delegators can delegate).

  • --baker-url is the URL for baker information. The URL should resolve to (JSON-formatted) metadata about the baker.

  • --keys-in specifies the name of the file containing the baker keys.

  • --keys-out can be used to write a baker credential file containing the baker ID (and the supplied keys) to use when starting a baker node. Replace <concordium-data-dir> with any path of your choice.

  • --delegation-transaction-fee-commission specifies the transaction fee commission for the baker pool.

  • --delegation-baking-commission specifies the baking commission for the baker pool.

  • --delegation-finalization-commission specifies the finalization commission for the baker pool.

Note

To find the range for the commissions, see the Concordium client Show Chain Parameters command.

Remove a baker#

The controlling account can choose to de-register its baker on the chain. To do so you have to execute:

$concordium-client baker remove --sender bakerAccount

This removes the baker from the baker list and unlocks the staked amount on the baker so that it can be transferred or moved freely.

When removing the baker, the change has the same timeline as decreasing the staked amount. The change requires a 21 day cool-down to take effect. The change becomes visible on the chain when the transaction is included in a block and takes effect at the next pay day after the cool-down ends. You can check when the change will take effect by querying the account information:

$concordium-client account show bakerAccount
...

Baker #22 to be removed at epoch 275 (2020-12-24 13:56:26 UTC)
 - Staked amount: 20.000000 CCD
 - Restake earnings: yes

...

Warning

Decreasing the staked amount and removing the baker can’t be done simultaneously. During the cool-down period produced by decreasing the staked amount, the baker can’t be removed and vice versa.