Skip to main content

Become a baker

In this chapter, we will see the CLI command lines for registering as a delegate. Then we will see how to exercise your rights as a validator and accuser.

This chapter requires the deployment of your own Tezos node, explained in the module Deploy a node.

caution

The current Octez version is v20.2 and the protocol version is Paris.

Running a Delegate​

A delegate is responsible for baking blocks, attesting blocks, and accusing other delegates if they try to double bake or double attest.

What you need​

  • 3 CPU cores: 2 needed by the node and 1 needed by the baker (arm64 or amd64/x86-64)
  • 8GB of RAM + 8GB of swap (or 16GB of RAM)
  • 100GB SSD storage (or similar I/O performance)
  • A low-latency reliable internet connection
  • A Tezos node configured and running (if not, please go here)
caution

running a node in full or archive mode requires extra storage space (500GB for full and 2TO for archive);

Deposit​

When baking or attesting a block, a security deposit (>6,000ꜩ) is frozen for 3 cycles from the account of the delegate. Hence a delegate must have enough funds to be able to pay security deposits for all the blocks it can potentially bake/attest during 3 cycles.

note

It is necessary to have at least 10% of your stake to follow the deposits.

Registration​

Create a basic wallet​

The Octez client is also a basic wallet. After the activation command below, you will notice that the Octez client data directory (by default, ~/.octez-client) has been populated with 3 files: public_key_hashs, public_keys and secret_keys.

The content of each file is in JSON format and keeps the mapping between aliases (e.g. bob) and the kind of keys indicated by the name of each file. Create an address for bob (argument --encrypted to cipher the private key):

octez-client gen keys bob

Supply your wallet​

Now that you have created an account, you need to supply it with real Tez.

caution

Be sure you are on the mainnet if you send real Tez.

You can get the address of the previously created wallet with the following command:

octez-client list known addresses

You can now send to bob any number of Tez from a wallet of your choice.

caution

If you are not sure what you are doing, start by sending a small amount. Then send the whole amount. (6,000ꜩ is the minimum to register as a delegate).

Copy and paste the destination address into the search bar of an explorer (like TzStats) to see the transaction. The address should be visible in the explorer after the first transaction.

You can check the amount that bob holds with:

octez-client get balance for bob

Register as a delegate​

To run a delegate, you first need to register as one using the alias of your account:

octez-client register key bob as delegate

Stake your tez​

Since Adaptive Issuance, it is no longer enough to just register your key. You must stake as well. It now takes 2 cycles (~6 days) before your baker receives baking rights. You can stake the entire value of your spendable balance if you want, but you should leave some balance free for staking, unstaking and finalization fees.

octez-client stake 6000 for bob

Baker​

The baker is a daemon that, once connected to an account, computes the baking rights for that account, collects transactions from the mempool, and bakes a block. Note that the baker is the only program that needs direct access to the node data directory for performance reasons. This daemon also emits the attestation operations.

info

A daemon is a computer program that runs as a background process.

The mempool is made of all transactions that have been submitted for inclusion in the chain but have not yet been included in a block by a baker.

Let’s launch the daemon pointing to the standard node directory and baking for the user bob.

There are different command lines depending on the network on which your node is configured:

  • ParisCnet, Ghostnet & Mainnet: octez-baker-PsParisC

So, for bob on the Mainnet, the command is as follows:

octez-baker-PsParisC run with local node ~/.octez-node bob
caution

Remember that having two bakers running connected to the same account could lead to double baking/attesting and the loss of all your bonds. If you are worried about the availability of your node when it is its turn to bake/attest, there are other ways than duplicating your credentials (see the discussion in section Inactive delegates).

Never use the same account on two daemons.

Accuser​

The accuser is a daemon that monitors all blocks received on all chains and looks for validators who:

  • signed two blocks at the same level, or
  • injected more than one attestation operation for the same baking slot

Upon finding such irregularity, it will respectively emit a double-baking or double-attesting denunciation operation, which will cause the offender to lose its security deposit.

There are different command lines depending on the network on which your node is configured:

  • ParisCnet, , Ghostnet & Mainnet: octez-accuser-PsParisC

So, on the Mainnet, the command is as follows:

octez-accuser-PsParisC run

Let's dive into the practical part​

The following section will guide you through the complete installation and setup of your own Tezos baker on Linux, using Docker images, APT packages, or by building from source.

Prerequisites​

Baking blocks on the Tezos blockchain requires:

  • at least 6,000 tez staked

and a dedicated machine online 24/7 with at least:

  • 3 CPU cores: 2 needed by the node and 1 needed by the baker (arm64 or amd64/x86-64)
  • 8GB of RAM + 8GB of swap (or 16GB of RAM)
  • 100GB SSD storage (or similar I/O performance)
  • A low-latency reliable internet connection
  • A Tezos node configured and running (if not, please go here)

Set up using APT with Octez packages​

If you’re using Ubuntu or Debian, you can install the same packages as in the release page using apt directly from our APT repository, instead of going to the Octez release page as explained above.

We support the following distribution/releases: - debian/bookworm - ubuntu/noble - ubuntu/jammy

both on amd64 and arm64 architectures.

Step 1: Installation

In order to add the Tezos package repository to your machine, do:

export distribution=debian
export release=bookworm

and run:

  apt-get install -y sudo gpg curl

  curl "https://packages.nomadic-labs.com/$distribution/octez.asc" |
    sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/octez.gpg
  echo "deb [arch=amd64] https://packages.nomadic-labs.com/$distribution $release main" |
    sudo tee /etc/apt/sources.list.d/octez.list
  sudo apt-get update

Then, to install the binaries, run the following commands:

sudo apt-get install -y octez-client
sudo apt-get install -y octez-node
sudo apt-get install -y octez-baker
Step 2: Let's config and run!

It is possible to define the directory where the data will be stored with --data-dir (by default, it is in .octez-node).

--network=NETWORK Select which network to run. Possible values are: sandbox, mainnet, [testnet] (e.g., ghostnet, parisCnet. Learn more about testnet aliases here). Default is mainnet.

--history-mode= MODE Set the mode for the chain's data history storage. Possible values are archive , full (default), full:N, rolling, rolling:N.

  • Archive mode retains all data since the genesis block.
  • Full mode only maintains block headers and operations allowing replaying the chain since the genesis if wanted (full mode is recommended to bake. More information here).
  • Rolling mode retains only the most recent data and deletes the rest.

For both Full and Rolling modes, it is possible to adjust the number of cycles to preserve by using the :N annotation. The default number of preserved cycles is 5. The value experimental-rolling is deprecated but is equivalent to rolling which should be used instead.

Read more about node configuration here).

For example, the following command configures the node for the Ghostnet Network and stores data in the specified directory ~/tezos-ghostnet with the full mode.

octez-node config init --data-dir ~/tezos-ghostnet --network=ghostnet --history-mode=full

You can run the node with :

octez-node run --rpc-addr 127.0.0.1:8732 --log-output tezos.log

The parameter --rpc-addr url:port activate the RPC interface that will allow communication with the node. By default, it runs on port 8732 so it is not mandatory to specify it. The file tezos.log will be saved in /home/user/.

Step 3: Check synchronization ✅

The Octez client can be used to interact with the node. It can query its status or ask the node to perform some actions. For example, after starting your node, you can check if it has finished synchronizing with the following command (you can use another terminal window if you still watch the log):

octez-client -E http://127.0.0.1:8732/ bootstrapped

(-E option is equal to --endpoint option) When you see the message " Node is Bootstrapped ", your Tezos node is synchronized with the blockchain and you may now perform operations on it!

Step 4: Import your keys

Option 1: Import keys from a Ledger Prerequisites: The Ledger Nano should be configured with the Tezos wallet and Tezos baking apps. On Linux make sure you correctly set up your udev rules as explained here. Access the "Tezos wallet" app on your ledger and list the connected Ledgers with the following command:

octez-client --endpoint http://127.0.0.1:8732 list connected ledgers

Import a key from a Ledger with the following command:

octez-client --endpoint http://127.0.0.1:8732 import secret key <key_alias> <ledger://path/to/the/secret/key/on/your/device>

You have to replace <key_alias> by the alias of your choice, and <ledger://path/to/the/secret/key/on/your/device> by the path to your secret key on your ledger (four options are available to generate either tz1, tz2 or tz3 addresses). Validate the public key hash displayed on the ledger to validate the key import.

Option 2: Import a secret key with the octez-client

caution

This option isn't recommended. Be careful when using your private keys unencrypted

You have to replace <key_alias> by the alias of your choice and provide the clear private key to the octez-client, after the keyword unencrypted:

octez-client --endpoint http://127.0.0.1:8732 import secret key key_alias unencrypted:your_private_key
Step 5: Let's register as delegate

Option 1 (next): Setup the Ledger to bake for your address Access the "Tezos Baking" app on your ledger and then do execute the following command: (replace <key_alias> by the alias chosen in step 4)

sudo octez-client -E http://127.0.0.1:8732 setup ledger to bake for key-alias-or-ledger-uri

You will need to validate the request on your ledger.

Register your key as a delegate on the network (replace <key-alias> by the alias chosen in step 4)

octez-client --endpoint http://127.0.0.1:8732 register key <key_alias> as delegate
Step 6: Let's stake

You need to stake at least 6000 tez now :

octez-client stake 6000 for key_alias

It now takes 2 cycles before your baker receives baking rights. You can stake the entire value of your spendable balance if you want, but you should leave some balance free for staking, unstaking and finalization fees.

Step 7: Let's bake!
info

Since the Jakarta amendment, the --liquidity-baking-toggle-vote <vote> command line toggle is mandatory. <vote> should be replaced by on, off or pass. Read more about liquidity baking in the technical documentation.

You can launch the baker with:

octez-baker-PsParisC --endpoint http://127.0.0.1:8732 run with local node /home/user/.octez-node --liquidity-baking-toggle-vote vote

🎉 Congratulations on setting up a baker node! 🎉

Bonus: Quick synchronization from a snapshot

If you want your node to be bootstrapped quickly, you can synchronize it with the blockchain using a snapshot.

1. Download a .full snapshot from a snapshot provider (https://xtz-shots.io/, https://snapshots.tezos.marigold.dev/, https://snapshots-tezos.giganode.io/, https://lambsonacid.nl/) in your current repository by replacing with <snapshot_url> in following command:

wget <snapshot_url>

2. Register the current directory in a variable:

path=$(pwd)

3. Import from the snapshot!

(Replace <name_of_snapshot_file>)

octez-node snapshot import $path/<name_of_snapshot_file>

(It is possible to define the directory where the data will be stored with --data-dir directory, by default, it is in .octez-node)

4. You can get some information with the following command:

octez-node snapshot info $path/<name_of_snapshot_file>

Set up using Docker images​

In this part, we will see how to install Tezos with Docker.

Docker​

Step 1: Installation

If you don't have Docker on your machine, you can install it with the following command:

sudo apt install docker.io

and follow instructions on: https://docs.docker.com/engine/install/linux-postinstall/.

Step 2: Let's config and run!

Run the node in detached mode (-d), as instance on the testnet parisCnet network with the history-mode "full" using the following command:

docker run --privileged -v /dev/bus/usb:/dev/bus/usb -v node-data-volume:/var/run/tezos/node -d -it -p 8732:8732 --name=octez-public-node-full tezos/tezos:latest octez-node --network=parisCnet --history-mode=full

This command will automatically download the tezos/tezos:latest image:

  • --privileged mode is only used to allow a connection with an Hardware secure module, e.g. Ledger

  • --name option to specify the name of the container

  • -v /dev/bus/usb:/dev/bus/usb allows mounting USB volumes to the specified container

  • -v node-data-volume:/var/run/tezos/node mount node-data-volume to the specified container. It is where blockchain data will be stored

  • --network=NETWORK selects which network to run. Possible values are: sandbox, mainnet, [testnet] (e.g. ghostnet, parisCnet. Learn more about testnet aliases here). Default is mainnet.

  • --history-mode=MODE lets you set the mode for the node's blockchain history storage. Possible values are archive , full (default), full:N , rolling , rolling:N.

    • Archive mode retains all data since the genesis block.

    • Full mode only maintains block headers and operations allowing replaying of the chain since the genesis if wanted. Full mode is recommended to bake. More information here.

    • Rolling mode retains only the most recent data and deletes the rest.

For both Full and Rolling modes, it is possible to adjust the number of cycles to preserve by using the :N annotation. The default number of preserved cycles is 5. The value experimental-rolling is deprecated but is equivalent to rolling which should be used instead.

Read more about node configuration here.

After a few minutes, your node identity will be generated and you will be able to check if the node is bootstrapped:

docker exec -it octez-public-node-full octez-client --endpoint http://127.0.0.1:8732 bootstrapped

(Use Ctrl+C to stop logs displaying)

Step 3: Import your keys

Option 1: Import keys from a Ledger

Prerequisites: The Ledger Nano should be configured with the Tezos wallet and Tezos baking apps.

Access the Tezos wallet app on your ledger and list the connected Ledgers with the following command:

docker exec -it octez-public-node-full sudo octez-client --endpoint http://127.0.0.18732 list connected ledgers

Import a key from the Ledger:

docker exec octez-public-node-full sudo octez-client --endpoint http://127.0.0.1:8732 import secret key <key_alias> <ledger://path/to/the/secret/key/on/your/device>

You have to replace <key_alias> by the alias of your choice, and <ledger://path/to/the/secret/key/on/your/device> by the path to your secret key on your ledger (four options are available to generate either tz1, tz2 or tz3 addresses). (You will need to validate the public key hash displayed on the ledger to validate the key importation).

Option 2: Import a secret key with the octez-client

caution

This option isn't recommended. Be careful when using your private keys unencrypted.

You have to replace <key_alias> by the alias of your choice and provide the clear private key to the octez-client, after the keyword unencrypted::

docker exec octez-public-node-full octez-client --endpoint http://127.0.0.1:8732 import secret key <key_alias> unencrypted:<your_private_key>
Step 4: Let's register as delegate

_Option 1 (next): Setup the Ledger to bake for your address Access the "Tezos Baking" app on your ledger and then execute the following command: (replace <key_alias> by the alias chosen in Step 3)

docker exec -it octez-public-node-full sudo octez-client -E http://127.0.0.1:8732 setup ledger to bake for <key_alias>

Validate the request on your ledger.

Register your key as a delegate on the network (Replace <key-alias> with the alias chosen in Step 3)

docker exec octez-public-node-full octez-client --endpoint http://127.0.0.1:8732 register key <key_alias> as delegate
Step 5: Let's stake
You need to stake at least 6000 tez now :
docker exec octez-public-node-full octez-client --endpoint http://127.0.0.1:8732 stake 6000 for key_alias
Step 6: Let's bake!
note

Since the Jakarta amendment, the --liquidity-baking-toggle-vote vote command line toggle is mandatory. vote should be replaced by on, off or pass.

Read more about Liquidity Baking in the technical documentation.

You can launch the baker with:

docker exec -it octez-public-node-full sh 
octez-baker-PsParisC --endpoint http://127.0.0.1:8732 run with local node /usr/local/bin/ --liquidity-baking-toggle-vote <vote>

(In the future, you may change octez-baker-PsParisC by the next protocol binary)

Check baking has started by watching the logs.

🎉 Congratulations on setting up a baker node! 🎉

Some useful commands

To see the manual of commands you can use:

docker run -it tezos/tezos:latest man

To see the various commands and options of the tezos node, use the following command:

docker run -it tezos/tezos:latest octez-node --help

To use the client:

docker exec -it octez-public-node-full octez-client --help

Docker-compose​

One way to run those Docker images is with Docker Compose!

Step 1: Let's launch the node and the baker!

The code below launches a full node, a baker and an accuser for the Paris protocol. You can adapt it to run a baker and accuser for another protocol by replacing the PROTOCOL environment variable, in our case PsParisC, with the desired protocol. (full mode is recommended to bake. More information here.


version: "3.4"
volumes:
  node_data_rolling_ghostnet:
    name: ghostnet-node
    external: false
  client_data_ghostnet:
    name: ghostnet-client
    external: false
services:
####################################################################################################################################
# You have to uncomment this section if you want to synchronize your node using a snapshot, else you can ignore or delete it.
# Replace /absolute/path/to/your_snapshot.full:/snapshot by the absolute path to the downloaded snapshot.
###################################################################################################################################
  import_ghostnet:
    image: tezos/tezos:octez-latest
    container_name: tezos-snapshot-import-ghostnet
    command: octez-snapshot-import
    volumes:
      - node_data_rolling_ghostnet:/var/run/tezos/node
      - client_data_ghostnet:/var/run/tezos/client
      - "/root/tezos-docker/ghostnet/snapshot_file:/snapshot"
################################################################################################
# If you want to run a node with history-mode=full, keep that "node_full" part, else delete it.
# You can change the version of the image of tezos in : image: tezos/tezos:v20.2
# You can change the --network=NETWORK option.
################################################################################################
  node_rolling_ghostnet:
    container_name: tezos-public-node-rolling-ghostnet
    image: tezos/tezos:latest
    command: octez-node --network=GHOSTNET --net-addr :9732 --rpc-addr 0.0.0.0:8732 --allow-all-rpc 0.0.0.0:8732 --history-mode=rolling
    ports:
    - '9732:9732'
    - '8732:8732'
    expose:
    - "8732"
    - "9732"
    privileged: true
    volumes:
     - node_data_rolling_ghostnet:/var/run/tezos/node
     - client_data_ghostnet:/var/run/tezos/client
     - /dev/bus/usb:/dev/bus/usb
    restart: on-failure
    network_mode: "host"
##################################################################################################################
# Use -f parameter if your key is encrypted, you can remove if not
##################################################################################################################
  baker-ghostnet:
    container_name: octez-baker-ghostnet
    image: tezos/tezos-bare:latest
    environment:
     - HOME=/tmp
     - NODE_HOST=127.0.0.1
     - NODE_RPC_PORT=8732
     - PROTOCOL=PsParisC
    command: octez-baker-PsParisC -f /var/run/tezos/client/password.txt --endpoint http://127.0.0.1:8732 run with local node /var/run/tezos/node/data --liquidity-baking-toggle-vote pass

    volumes:
     - node_data_rolling_ghostnet:/var/run/tezos/node:ro
     - client_data_ghostnet:/var/run/tezos/client
     - /root/tezos-docker/ghostnet/password.txt:/var/run/tezos/client/password.txt
     - /dev/bus/usb:/dev/bus/usb
    restart: on-failure
    network_mode: "host"

##################################################################################################################
# This is useful when an upgrade is available, you can run both baker-ghostnet with actual version and update one
# You can change the version of the image of tezos in: image: tezos/tezos-bare:v20.2
# You can change the PROTOCOL with the next update name
##################################################################################################################
  baker-ghostnet-update:
    container_name: octez-baker-ghostnet-update
    image: tezos/tezos-bare:latest
    environment:
     - HOME=/tmp
     - NODE_HOST=127.0.0.1
     - NODE_RPC_PORT=8732
     - PROTOCOL= (Next Protocol)
    command: octez-baker-(Next Protocol) -f /var/run/tezos/client/password.txt --endpoint http://127.0.0.1:8732 run with local node /var/run/tezos/node/data --liquidity-baking-toggle-vote pass

    volumes:
     - node_data_rolling_ghostnet:/var/run/tezos/node:ro
     - client_data_ghostnet:/var/run/tezos/client
     - /root/tezos-docker/ghostnet/password.txt:/var/run/tezos/client/password.txt
     - /dev/bus/usb:/dev/bus/usb
    restart: on-failure
    network_mode: "host"

################################################################################################
# If you want to run an accuser, keep that "accuser" part, else delete it.
# You can change the version of the image of tezos in: image: tezos/tezos:v20.2
# You can change the PROTOCOL
################################################################################################
  accuser:
    container_name: octez-accuser
    image: tezos/tezos:latest
    environment:
     - HOME=/tmp
     - NODE_HOST=127.0.0.1
     - NODE_RPC_PORT=8732
     - PROTOCOL=PsParisC
    command: octez-accuser
    volumes:
     - node_data_full:/var/run/tezos/node:ro
     - client_data:/var/run/tezos/client
    restart: on-failure
    network_mode: "host"

Copy and paste the code above into a docker-compose.yml file, and start the node with:

docker-compose -f docker-compose.yml up -d

To check if the node is bootstrapped:

docker exec -it octez-public-node-full octez-client --endpoint http://127.0.0.1:8732 bootstrapped
Step 2: Import your keys

Option 1: Import keys from a Ledger Prerequisites: The Ledger Nano should be configured with the Tezos wallet and Tezos baking apps. Open the "Tezos wallet" app on your ledger and list the connected Ledgers with the following command:

docker exec -it octez-baker sudo octez-client --endpoint http://127.0.0.1:8732 list connected ledgers

Import a key from the Ledger:

docker exec octez-baker sudo octez-client --endpoint http://127.0.0.1:8732 import secret key <key_alias> <ledger://path/to/the/secret/key/on/your/device>

You have to replace <key_alias> with the alias of your choice, and <ledger://path/to/the/secret/key/on/your/device> by the path to your secret key on your ledger (four options are available to generate either tz1, tz2 or tz3 addresses).

Validate the public key hash displayed on the ledger to validate the key import.

Option 2: Import a secret key with the octez-client

caution

This option isn't recommended. Be careful when using your private keys unencrypted

You have to replace <key_alias> by the alias of your choice and provide the clear private key to the octez-client, after the keyword unencrypted::

docker exec octez-baker octez-client --endpoint http://127.0.0.1:8732 import secret key <key_alias> unencrypted:<your_private_key>
Step 3: Let's register as delegate

Option 1 (next): Setup the Ledger to bake for your address Open the "Tezos Baking" app on your ledger. Then execute the following command: (Replace <key_alias> by the alias chosen earlier in Step 3)

docker exec -it octez-baker sudo octez-client -E http://127.0.0.1:8732 setup ledger to bake for <key_alias>Validate the request on your ledger.

Register your key as a delegate on the network (Replace <key-alias> by the alias chosen earlier in Step 3)

docker exec octez-baker octez-client --endpoint http://127.0.0.1:8732 register key <key_alias> as delegate
Step 4: Let's stake

You need to stake at least 6000 tez now :

docker exec octez-public-node-full octez-client --endpoint http://127.0.0.1:8732 stake 6000 for <key_alias>

🎉 Congratulations on setting up a baker node! 🎉

Bonus: Quick synchronization from a snapshot

If you want your node to be bootstrapped quickly, you can synchronize it with the blockchain using a snapshot.

1. Download a .full snapshot from a snapshot provider (https://xtz-shots.io/, https://snapshots.tezos.marigold.dev/, https://snapshots-tezos.giganode.io/, https://lambsonacid.nl/) in your current repository by replacing with <snapshot_url> in following command:

wget <snapshot_url>

2. Launch the node and baker daemons:

docker-compose up -d node_full
docker-compose up -d baker
sudo docker exec -it octez-public-node-full sh
sudo rm /var/run/tezos/data/lock
exit

3. Stop the node, baker, and accuser daemons:

docker-compose stop node_full baker accuser

4. Execute these commands to clean up data and avoid duplicates:

sudo su
rm -rf /var/lib/docker/volumes/mainnet-node/_data/data/context
rm -rf /var/lib/docker/volumes/mainnet-node/_data/data/store
rm -rf /var/lib/docker/volumes/mainnet-node/_data/data/lock

(do Ctrl+d to quit su mode)

5. In the .yml file presented in Step 1, replace /absolute/path/to/your_snapshot.full:/snapshot by the absolute path to the downloaded snapshot. You can use pwd command to know the absolute path of your current repository. ( Read the comment in the .yml file in Step 1 )

6. Upload the snapshot into the mainnet-node volume:

docker-compose up import

You will have to wait ~1-2 hours to import a full snapshot.

7. Start synchro from snapshot:

docker-compose stop import
docker-compose up -d node_full baker accuser

If you’re using Ubuntu or Debian, you can install the same packages as in the release page using apt directly from our APT repository, instead of going to the Octez release page as explained above.

We support the following distribution/releases: - debian/bookworm - ubuntu/noble - ubuntu/jammy

both on amd64 and arm64 architectures.

Step 1: Installation

In order to add the Tezos package repository to your machine, do:

export distribution=debian
export release=bookworm

and run:

  apt-get install -y sudo gpg curl

  curl "https://packages.nomadic-labs.com/$distribution/octez.asc" |
    sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/octez.gpg
  echo "deb [arch=amd64] https://packages.nomadic-labs.com/$distribution $release main" |
    sudo tee /etc/apt/sources.list.d/octez.list
  sudo apt-get update

Then, to install the binaries, run the following commands:

sudo apt-get install -y octez-client
sudo apt-get install -y octez-node
sudo apt-get install -y octez-baker
Step 2: Let's config and run!

It is possible to define the directory where the data will be stored with --data-dir (by default, it is in .octez-node).

--network=NETWORK Select which network to run. Possible values are: sandbox, mainnet, [testnet] (e.g., ghostnet, kathmandunet. Learn more about testnet aliases here). Default is mainnet.

--history-mode= MODE Set the mode for the chain's data history storage. Possible values are archive , full (default), full:N, rolling, rolling:N.

  • Archive mode retains all data since the genesis block.
  • Full mode only maintains block headers and operations allowing replaying the chain since the genesis if wanted (full mode is recommended to bake. More information here).
  • Rolling mode retains only the most recent data and deletes the rest.

For both Full and Rolling modes, it is possible to adjust the number of cycles to preserve by using the :N annotation. The default number of preserved cycles is 5. The value experimental-rolling is deprecated but is equivalent to octez-client rolling which should be used instead.

Read more about node configuration here).

For example, the following command configures the node for the Ghostnet Network and stores data in the specified directory ~/tezos-ghostnet with the full mode.

octez-node config init --data-dir ~/tezos-ghostnet --network=ghostnet --history-mode=full

You can run the node with :

octez-node run --rpc-addr 127.0.0.1:8732 --log-output tezos.log

The parameter --rpc-addr url:port activate the RPC interface that will allow communication with the node. By default, it runs on port 8732 so it is not mandatory to specify it. The file tezos.log will be saved in /home/user/.

Step 3: Check synchronization ✅

The Octez client can be used to interact with the node. It can query its status or ask the node to perform some actions. For example, after starting your node, you can check if it has finished synchronizing with the following command (you can use another terminal window if you still watch the log):

octez-client -E http://127.0.0.1:8732/ bootstrapped

(-E option is equal to --endpoint option) When you see the message " Node is Bootstrapped ", your Tezos node is synchronized with the blockchain and you may now perform operations on it!

Step 4: Import your keys

Option 1: Import keys from a Ledger Prerequisites: The Ledger Nano should be configured with the Tezos wallet and Tezos baking apps. Access the "Tezos wallet" app on your ledger and list the connected Ledgers with the following command:

octez-client --endpoint http://127.0.0.1:8732 list connected ledgers

Import a key from a Ledger with the following command: octez-client

octez-client --endpoint http://127.0.0.1:8732 import secret key <key_alias> <ledger://path/to/the/secret/key/on/your/device>

You have to replace <key_alias> by the alias of your choice, and <ledger://path/to/the/secret/key/on/your/device> by the path to your secret key on your ledger (four options are available to generate either tz1, tz2 or tz3 addresses). Validate the public key hash displayed on the ledger to validate the key import.

Option 2: Import a secret key with the octez-client

caution

This option isn't recommended. Be careful when using your private keys unencrypted

You have to replace <key_alias> by the alias of your choice and provide the clear private key to the octez-client, after the keyword unencrypted:

octez-client --endpoint http://127.0.0.1:8732 import secret key key_alias unencrypted:your_private_key
Step 5: Let's register as delegate

Option 1 (next): Setup the Ledger to bake for your address Access the "Tezos Baking" app on your ledger and then do execute the following command: (replace <key_alias> by the alias chosen in step 4)

sudo octez-client -E http://127.0.0.1:8732 setup ledger to bake for key-alias-or-ledger-uri

You will need to validate the request on your ledger.

Register your key as a delegate on the network (replace <key-alias> by the alias chosen in step 4)

octez-client --endpoint http://127.0.0.1:8732 register key <key_alias> as delegate
Step 6: Let's stake

You need to stake at least 6000 tez now :

octez-client stake 6000 for <key_alias>
Step 7: Let's bake!
info

Since the Jakarta amendment, the --liquidity-baking-toggle-vote <vote> command line toggle is mandatory. <vote> should be replaced by on, off or pass. Read more about liquidity baking in the technical documentation.

You can launch the baker with:

octez-baker-PsParisC --endpoint http://127.0.0.1:8732 run with local node /home/user/.octez-node --liquidity-baking-toggle-vote vote

🎉 Congratulations on setting up a baker node! 🎉

Bonus: Quick synchronization from a snapshot

If you want your node to be bootstrapped quickly, you can synchronize it with the blockchain using a snapshot.

1. Download a .full snapshot from a snapshot provider (https://xtz-shots.io/, https://snapshots.tezos.marigold.dev/, https://snapshots-tezos.giganode.io/, https://lambsonacid.nl/) in your current repository by replacing with <snapshot_url> in following command:

wget <snapshot_url>

2. Register the current directory in a variable:

path=$(pwd)

3. Import from the snapshot!

(Replace <name_of_snapshot_file>)

octez-node snapshot import $path/<name_of_snapshot_file>

(It is possible to define the directory where the data will be stored with --data-dir directory, by default, it is in .octez-node)

4. You can get some information with the following command:

octez-node snapshot info $path/<name_of_snapshot_file>

Set up by building from source​

In this part, we will see how to install Tezos from source. The easiest way to build the binaries from the source code is to use the OPAM source package manager for OCaml.

This method is recommended for advanced users as it requires basic knowledge of the OPAM package manager and the OCaml packages workflow. In particular, upgrading Tezos from release to release might require tinkering with different options of the OPAM package manager to adjust the local environment for the new dependencies.

From scratch method​

Step 1: Install OPAM

First, you need to install the OPAM package manager, at least version 2.0, that you can get by following the install instructions. The quickest way to get the latest opam up and working is to run this script:

bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"

(If you have trouble with curl, just download the script and run sh install.sh) For the next command line, answers the prompts with 'N' then 'y'. You may also be prompted for your sudo password. You may encounter a "switch" error, but you can ignore it.

opam init --bare
Step 2: Install Rust
Compiling Tezos requires the Rust compiler, version 1.52.1, and the Cargo package manager for Rust to be installed. If you have [rustup](https://rustup.rs/) installed, you can use [rustup](https://rustup.rs/) to install both. If you do not have `rustup`, please avoid installing it from Snapcraft; you can rather follow the simple installation process shown below:
cd $HOME
wget https://sh.rustup.rs/rustup-init.sh
chmod +x rustup-init.sh
./rustup-init.sh --profile minimal --default-toolchain 1.52.1 -y```

Once Rust is installed, note that your PATH environment variable (in .profile) may be updated and you will need to restart your session so that changes can be taken into account. Alternatively, you can do it manually without restarting your session with the following command :

$HOME/.cargo/env
Step 3: Install Zcash Parameters

Tezos binaries require the Zcash parameter files to run. This is for shielded/confidential transactions with Sapling, that were added in the Edo amendment. If you compile from source and move Tezos to another location (such as /usr/local/bin), the Tezos binaries may prompt you to install the Zcash parameter files. The easiest way is to download and run this script:

wget https://raw.githubusercontent.com/zcash/zcash/master/zcutil/fetch-params.sh
chmod +x fetch-params.sh
./fetch-params.sh
Step 4: Install Tezos dependencies

Install the libraries that Tezos is dependent on:

sudo apt-get install -y rsync git m4 build-essential patch unzip wget pkg-config libgmp-dev libev-dev libhidapi-dev opam jq zlib1g-dev bc autoconf

Get the source code:

git clone https://gitlab.com/tezos/tezos.git
cd tezos
git checkout latest-release

Install tezos dependencies:

make build-deps

You may encounter a "switch" error, but you can ignore it.

You may encounter failures in the processes of the make build-deps command. In that case, just re-type the command opam init --bare to re-initiate.

Step 5: Compile sources

Compile sources:

eval $(opam env)
make
Step 6: Check installation

To check the installation you can use the following commands:

octez-node --version
Step 7: Let's config and run!

It is possible to define the directory where the data will be stored with --data-dir (by default, it is in .octez-node). --network= NETWORK. Select which network to run. Possible values are: sandbox , mainnet , [testnet] (e.g. ghostnet, parisCnet. See current testnets here). Default is mainnet. --history-mode= MODE.

Set the mode for the chain's data history storage. Possible values are archive , full (default), full:N, rolling, rolling:N.

  • Archive mode retains all data since the genesis block.
  • Full mode only maintains block headers and operations allowing replaying the chain since the genesis if wanted. (full mode is recommended to bake. More information here).
  • Rolling mode retains only the most recent data and deletes the rest.

For both Full and Rolling modes, it is possible to adjust the number of cycles to preserve by using the :N annotation. The default number of preserved cycles is 5. The value experimental-rolling is deprecated but is equivalent to rolling which should be used instead.

Read more about node configuration here).

For example, the following command configures the node for the Ghostnet Network and stores data in the specified directory ~/tezos-ghostnet with the full mode.

octez-node config init --data-dir ~/tezos-ghostnet --network=ghostnet --history-mode=full

You can run the node with :

octez-node run --rpc-addr 127.0.0.1:8732 --log-output tezos.log

The parameter --rpc-addr url:port activate the RPC interface that will allow communication with the node. By default, it runs on port 8732 so it is not mandatory to specify it. The file tezos.log will be saved in /home/user/.

Step 8: Check synchronization ✅

The Octez client can be used to interact with the node. It can query its status or ask the node to perform some actions. For example, after starting your node, you can check if it has finished synchronizing with the following command (you can use another terminal window if you still watch the log) :

octez-client -E http://127.0.0.1:8732/ bootstrapped

Where:

  • -E option is equal to --endpoint option

When you see the message " Node is Bootstrapped ", your Tezos node is synchronized with the blockchain, and you may now perform operations on it!

Step 9: Import your keys

Option 1: Import keys from a Ledger Prerequisites: The Ledger Nano should be configured with the Tezos wallet and Tezos baking apps. Access the "Tezos wallet" app on your ledger and list the connected Ledgers with the following command:

octez-client --endpoint http://127.0.0.1:8732 list connected ledgers

Import a key from a Ledger with the following command:

octez-client --endpoint http://127.0.0.1:8732 import secret key <key_alias> <ledger://path/to/the/secret/key/on/your/device>

You have to replace <key_alias> by the alias of your choice, and <ledger://path/to/the/secret/key/on/your/device> by the path to your secret key on your ledger (four options are available to generate either tz1, tz2 or tz3 addresses). Validate the public key hash displayed on the ledger to validate the key import.

Option 2: Import a secret key with the octez-client

caution

This option isn't recommended. Be careful when using your private keys unencrypted

You have to replace <key_alias> by the alias of your choice and provide the clear private key to the octez-client, after the keyword unencrypted :

octez-client --endpoint http://127.0.0.1:8732 import secret key key_alias unencrypted:your_private_key
Step 10: Let's register as delegate

Option 1 (next): Setup the Ledger to bake for your address Access the "Tezos Baking" app on your ledger and then do execute the following command: (replace <key_alias> by the alias chosen in step 9)

sudo octez-client -E http://127.0.0.1:8732 setup ledger to bake for key-alias-or-ledger-uri

You will need to validate the request on your ledger.

Register your key as a delegate on the network (replace <key-alias> by the alias chosen in step 4)

octez-client --endpoint http://127.0.0.1:8732 register key key_alias as delegate
Step 11: Let's stake

You need to stake at least 6000 tez now :

octez-client --endpoint http://127.0.0.1:8732 stake 6000 for <key_alias>
Step 12: Let's bake!
caution

Since the Jakarta amendment, the --liquidity-baking-toggle-vote <vote> command line toggle is mandatory. <vote> should be replaced by on, off or pass. Read more about liquidity baking in the technical documentation.

You can launch the baker with:

octez-baker-PsParisC --endpoint http://127.0.0.1:8732 run with local node /home/user/.octez-node --liquidity-baking-toggle-vote vote

🎉 Congratulations on setting up a baker node! 🎉

Tezos OPAM packages method​

Step 1: Install OPAM

First, you need to install the OPAM package manager, at least version 2.0, that you can get by following the install instructions. The quickest way to get the latest opam up and working is to run this script:

bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"

(If you have trouble with curl, just download the script and run sh install.sh) For the next command line, answers the prompts with 'N' then 'y'. You may also be prompted for your sudo password. You may encounter a "switch" error, but you can ignore it.

opam init --bare
Step 2: Get an environment
wget -O latest-release:version.sh https://gitlab.com/tezos/tezos/raw/latest-release/scripts/version.sh

The binaries need a specific version of the OCaml compiler (see the value of the variable $ocaml_version in file /tezos/scripts/version.sh).

source latest-release:version.sh
opam switch create for_tezos $ocaml_version
eval $(opam env)

If you get a "c compiler error", run this to install some necessary tools:

sudo apt-get install build-essential
Step 3: Get dependencies

In order to get the system dependencies of the binaries, do:

opam depext tezos
Step 4: Install binaries
opam install tezos

Now follow Steps 6-7-8-9-10-11-12 of "From scratch method"

Bonus: Quick synchronization from a snapshot

If you want your node to be bootstrapped quickly, you can synchronize it with the blockchain using a snapshot.

1: Download a .full snapshot from a snapshot provider (https://xtz-shots.io/, https://snapshots.tezos.marigold.dev/, https://snapshots-tezos.giganode.io/, https://lambsonacid.nl/) in your current repository by replacing with <snapshot_url> in following command:

wget <snapshot_url>

2: Register the current directory in a variable:

path=$(pwd)

3: Import from the snapshot!

(Replace <name_of_snapshot_file>)

octez-node snapshot import $path/name_of_snapshot_file

(It is possible to define the directory where the data will be stored with --data-dir directory, by default, it is in .octez-node)

4: You can get some information with the following command:

octez-node snapshot info $path/name_of_snapshot_file
caution

Be careful when closing terminal windows because this stops the node.

tip

Use screen, or nohup to keep the node running in the background.

Unstake your balance​

You can use first the unstake command :

octez-client unstake 6000 for <key_alias>

After 2 cycles (6 days) they no longer contribute to baking rights calculations, but they are still frozen. To unfreeze them and return them to the spendable balance, you must wait 4 cycles (12 days) and issue the finalization command:

octez-client finalize unstake for <key_alias>

Upgrade a baking node​

Docker and docker-compose​

Upgrade the docker image

To upgrade your node to the lastest Octez version, replace your previous image version (most likely v13.0) by the lastest: v20.2. Note that if you run the image named latest, a restart of your container is sufficient.

To use the v20.2 image, use the following tezos image, for both docker and docker-compose:

tezos/tezos:v20.2

The binary versions of both the baker and accuser must be replaced by the latest ones. If you use dokcer-compose, replace the PROTOCOL variable by:

PROTOCOL=PsParisC

APT Octez binaries​

Upgrade tezos packages

To fetch the latest node, baker and accuser deamons, run the following command:

sudo apt-get update
sudo apt-get upgrade

From source​

From scratch​

Upgrade from scratch

Refer to the section upgrade an octez node from source. The required daemons will be automatically downloaded. Finally, relaunch your node, and run the new daemons (suffixed by PsParisC).

caution

If the protocol upgrade has not yet taken place, keep running the "old" daemons. Note that you can both run old and new daemons without any double baking/attestation risks.

Upgrade .service files​

You can find the latest .service files in this section.

The general idea is to create the corresponding .service files, for the futur baker and accuser daemons, while still running the current ones. As with the current .servicefiles that you are most likely running, you will be able to enable, and then start them even if the current ones are running.

First of all, refer to your installation method and follow one of the previous sections to upgrade your node.

Once your node is upgraded, copy the .service files of your current baker and accuser and paste them in new .service files. For example: baker-1.service and accuser-1.service. Change the octez-accuser-Proxfordhma and octez-baker-Proxfordhma binary names (of the newly created files) respectively by octez-accuser-PsParisC and octez-baker-PsParisC. **Carefully check that the new .service files contain the PsParisC daemons before following the next steps.

Execute:

systemctl daemon-reload
systemctl enable baker-1.service accuser-1.service
systemctl start baker-1.service accuser-1.service

While your are still baking blocks, your future daemons will take over at the first block of the new protocol!

Switching testnet​

Tezos is a fast-evolving blockchain and testnets follow each other and replace each other. It will therefore be necessary from time to time to connect to a new network to prepare for a change.

Let's say we already had a node configured on ParisCnet and that the new testnet has just been released, let's say its name is Newtestnet (for example).

To switch to Newtesnet, we will have to initialize another Tezos node.

Let's create a directory that will contain all the elements of our second node:

mkdir ~/tezos-newtestnet

We then create the configuration, which initializes the connection to Newtestnet and the list of bootstrap peers:

octez-node config init --data-dir ~/tezos-newtestnet --network newtestnet

Then we generate the identity:

octez-node identity generate --data-dir ~/tezos-newtestnet

And finally, we can launch it, with a different RPC port than the one already running on ParisCnet:

octez-node run --rpc-addr 127.0.0.1:8733 --data-dir ~/tezos-newtestnet

The day ParisCnet is shut down, we can delete the contents of the .tezos-parisCnet directory, the data of our node.

Other options for Baking​

This section presents how to set up a baker "from scratch", but here are several options for setting up a baker, each with its own advantages and disadvantages. Here are some baking options, with links to more information:

The following links also provide information on setting up a baker:

References​

[1] https://tezos.gitlab.io/introduction/howtorun.html#delegateregistration