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:
Create an account in the wallet and acquire CCD.
Create a set of baker keys.
Register the baker keys with the account.
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 stakeMyBakerURL
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:
using Docker: See configure Linux node.
on MacOS: See configure MacOS node.
on Windows: See configure Windows node.
on Ubuntu: See configure Ubuntu node.
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.