Octez & Protocol overview ************************* Octez, bundled with the Tezos protocol, is a complete implementation of the Tezos blockchain. Tezos is a distributed consensus platform with meta-consensus capability. This means that Tezos not only comes to consensus about the state of its ledger, like Bitcoin or Ethereum. It also attempts to come to consensus about how the protocol and the nodes should adapt and upgrade. Tezos is backed up by a vibrant Tezos community, which may also be contacted for technical support when needed. Octez includes a node, a client, a baker, an accuser, and other tools, distributed with the Tezos economic protocols of Mainnet for convenience. The source code is placed under the MIT Open Source License, and is available at https://gitlab.com/tezos/tezos. This website contains technical documentation about both Octez and the Tezos protocol. The current latest release of Octez is Version 25.3. See that page for minimal hardware requirements for running Octez in a typical setup. The current Tezos protocol is Ushuaia. For installing instructions, see Installing Octez, the reference implementation of Tezos. Mainnet & Test Networks ======================= The Tezos network, called "mainnet", is the current incarnation of the Tezos blockchain. It runs with real tez that have been allocated to the donors of July 2017 fundraiser (see Getting keys for fundraiser accounts). It has been live and open since June 30th 2018. All the instructions in this documentation are valid for Mainnet however we **strongly** encourage users to first try all the introduction tutorials on some test network to familiarize themselves without risks. There are several test networks for the Tezos blockchain with faucets to obtain free tez. These networks are intended for developers wanting to test their software before going to beta and for users who want to familiarize themselves with Tezos before using their real tez. Documentation source ==================== The source of this technical documentation website is an integral part of the Octez repository, following Docs as Code best practices. The documentation is automatically built from the current version of the master branch. Installing Octez, the reference implementation of Tezos ******************************************************* In this how-to we explain how to get up-to-date binaries to run Tezos (more precisely, the "Octez" implementation of Tezos software) on any network (either on the mainnet or on one of the test networks). Octez consists of several binaries (i.e., executable files), including: a client, a node, and a baker. There are several options for getting the binaries, depending on how you plan to use Octez: * installing packages. This is the easiest way to install native binaries for the latest stable release, together with their dependencies, using a package manager. * using docker images. This is the easiest way to run the latest stable release of the binaries in Docker containers, on any OS supported by Docker. * getting static binaries. This is the easiest way to get native binaries for the latest stable release, requiring no dependencies, under Linux. * using homebrew. For macOS (and also Linux) you can use our Homebrew formula to compile and install octez. * Building Octez by compiling the sources like developers do. This is the way to take if you plan to contribute to the source code. It allows to install any version you want (typically, the current development version on the master branch) by compiling it yourself from the sources. These different options are described in the following sections, except the last one, described in its own page. Some Octez binaries also require certain parameter files to run. Only some of the packaged distributions include such parameter files. Therefore, depending on the type of installation and your user profile, you may have to install some extra parameter files separately. Their installation is described in page Building Octez from source, but those instructions may be used for other installation types: * Install Zcash Parameters * Install DAL trusted setup Note that some of the packaged distributions are not only available for the latest stable release. For instance, static binaries are also available for release candidates, and Docker images are also available for the current development version (see Release System for more information). When choosing between the installation options, you may take into account the convenience of the installation step (and of upgrading steps), but also efficiency and security considerations. For instance, static binaries have a different memory footprint compared to dynamically-linked binaries. Also, compiling the sources in the official Octez repository is more secure than installing OPAM packages from a repository that is not under Tezos control. In particular, compiling from sources enforces a fixed set of dependencies; when compiling via OPAM, this set of dependencies may change, which may or may not be compatible with your security practices. All our installation scenarios are tested daily, including by automated means, to ensure that they are correct and up to date. These tests are performed by applying scenarios in several standard environments, from scratch. However, if you encounter problems when performing one of the installation scenarios in your own environment, you may want to take a look at Installation troubleshooting. Installing binary packages ========================== When it comes to installing software, especially for critical applications like Tezos/Octez, it’s crucial to ensure a secure and stable environment. While compiling from source can provide customization options, it often introduces complexities and risks. Instead, opting for binary packages such as Deb packages from a trusted source simplifies installation and enhances security. Deb packages compiled for a specific platform should be always preferred over statically compiled binaries. Deb packages can also be used to simplify the creation of OCI images or simply deployed on bare metal using provisioning tools such as Ansible. Using the official Deb packages offers several advantages: * **Security**: Packages are pre-compiled and thoroughly tested, reducing the risk of vulnerabilities introduced during compilation. All our packages are signed and our supply chain is strictly monitored to make sure the packages that we deliver only use components that were vetted by our engineering team. * **Stability**: Packages from a trusted repository undergo rigorous testing, ensuring stability and compatibility with the target system. We make sure to compile our binaries in a clean environment and using an up-to-date software distribution. We use LTS (long-term service) distributions to enhance stability and reduce the attack surface. * **Ease of Installation**: Packages can be installed using standard package management tools, streamlining the process. For instance, "apt" is ubiquitous in the Debian world. These tools allow us to sign our packages that can be automatically verified by the end user during installation. We provide packages that allow the end user to easily tailor their installation for different use cases. * **Reduced Downtime**: With reliable binaries and straightforward installation, system downtime due to installation errors or compatibility issues is minimized. We carefully test the upgrade process of our packages to make sure that end users can enjoy a click and go upgrade process with near to zero downtime. Ubuntu and Debian Octez packages -------------------------------- Warning: Starting from Octez version 26, Nomadic Labs no longer publishes Debian and Ubuntu packages for Octez. Packages built along the same lines, called Tzinit packages, are available instead. See Migrating from Nomadic Labs packages to Tzinit packages for instructions on how to migrate. If you're using Ubuntu or Debian, you can install the Debian packages using "apt" directly from our APT repository. We support the following distribution/releases: * "debian/trixie" * "ubuntu/jammy" (up to Octez version 24 included), becoming "ubuntu/22.04" (starting from Octez version 25) * "ubuntu/noble" (up to Octez version 24 included), becoming "ubuntu/24.04" (starting from Octez version 25) * "ubuntu/26.04" (starting from Octez version 25) both on "amd64" and "arm64" architectures. For the full support matrix, the support policy, and the planned end- of-support dates, see Supported Linux distributions. In order to set the Tezos package repository to your machine, do: export distribution=debian export release=trixie We also maintain a separate repository for release candidates. To set the last release candidate or Beta simply prepend "RC/" or "BETA/" to the distribution name as in "export distribution=RC/debian". Now add the Tezos package repository: sudo apt-get install -y gpg curl curl -s "https://packages.nomadic-labs.com/$distribution/octez.asc" | sudo gpg --dearmor -o /etc/apt/keyrings/octez.gpg echo "deb [signed-by=/etc/apt/keyrings/octez.gpg] https://packages.nomadic-labs.com/$distribution $release main" | sudo tee /etc/apt/sources.list.d/octez.list sudo apt-get update sudo apt-get install -y octez-archive-keyring sudo sed -i 's|signed-by=/etc/apt/keyrings/octez.gpg|signed-by=/usr/share/keyrings/octez-archive-keyring.gpg|' \ /etc/apt/sources.list.d/octez.list sudo apt-get update The above commands download a bootstrap signing key, configure the repository, and then install the "octez-archive-keyring" package which ships the signing keys at "/usr/share/keyrings/octez-archive- keyring.gpg". The "sed" command switches APT to use the managed keyring. Once set up, signing key rotations are handled automatically through normal package updates -- there is no need to manually download keys when they are rotated. If you already have Octez packages installed with a manually downloaded key, you can migrate to the managed keyring by running: sudo apt-get update sudo apt-get install octez-archive-keyring sudo sed -i 's|signed-by=[^ ]*.gpg|signed-by=/usr/share/keyrings/octez-archive-keyring.gpg|' \ /etc/apt/sources.list.d/octez.list sudo apt-get update Then, to install the binaries, run the following command to install the octez-baker and all its dependencies: sudo apt install octez-baker Once the Octez binary packages are installed, you may want to start a node, and then perhaps start a baker. Alternatively, they can be set up as services as explained in Setting up Octez Services. To remove the Octez packages you can simply run the following command. sudo apt-get autopurge -y octez-baker To upgrade packages, use "apt-get update" and "apt-get upgrade". If runnning Octez as services, see also how to restart them. Warning: If you installed Ubuntu packages for Octez v24 (or earlier) from the APT repository, the old codename-based path is no longer updated. Running "apt-get update" and "apt-get upgrade" will therefore not upgrade you to v25 until you repoint the repository to the new version-number-based path.To upgrade, set the "release" to your Ubuntu version number and re-add the repository: export distribution=ubuntu export release=24.04 # or 22.04, 26.04 then follow the install instructions above to refresh "/etc/apt/sources.list.d/octez.list", and finally run: sudo apt-get update sudo apt-get upgrade Debian users are not affected: the Debian repository keeps using codenames ("debian/trixie"). Getting static binaries ======================= You can get static Linux binaries of the latest release from the Octez package registry. This repository provides static binaries for x86_64 and arm64 architectures. Since these binaries are static, they can be used on any Linux distribution without any additional prerequisites. However, note that, by embedding all dependencies, static binary executables are typically much larger than dynamically-linked executables. For upgrading to a newer release, you just have to download and run the new versions of the binaries. Octez static binaries are signed via GPG. To verify that a binary was not tampered with, you can download and import our public GPG key and use "gpg" to verify the signature associated with the binary. curl -O https://packages.nomadic-labs.com/octez.asc gpg --import octez.asc ... # download the static binary you want to verify and the associated sig file gpg --verify .sig Using Homebrew ============== On macOS and Linux, you can compile and install Octez using Homebrew. If Homebrew is not yet installed on your system, please refer to the official Homebrew installation guide for detailed instructions. Once Homebrew is set up, follow these steps to install Octez. Download the Octez formula by executing the following command in your terminal: curl -q "https://packages.nomadic-labs.com/homebrew/Formula/octez.rb" -O For "RC" versions, do rather: curl -q "https://packages.nomadic-labs.com/homebrew/RC/Formula/octez.rb" -O Install Octez using the downloaded formula, creating a new tap if necessary, with the following commands: # Create a local tap if not having one already: brew tap-new octez-user/octeztap # Move formula to the newly created tap: mv octez.rb $(brew --repository)/Library/Taps/octez-user/homebrew-octeztap/Formula/ # Install formula from tap brew install octez-user/octeztap/octez Depending on the speed of your system, the build can take more than 10 minutes. We regularly test the build in our CI using macOS 14 (Sonoma) with Xcode 15 on an ARM-based Mac. More recent configurations should also work. Using Docker images =================== For every change committed in the GitLab repository, Docker images are automatically generated and published on DockerHub. This provides a convenient way to run an always up-to-date "octez-node". From version 22.0 all Octez Docker images are signed using Cosign. You can verify if the images are correctly signed, using Cosign. You can use the Docker images either directly or using Docker compose files, as explained next. In both cases, you need to have Docker installed and started (Docker Desktop would suffice for the instructions below). Plain Docker images ------------------- The Docker images can be directly used to run the different Octez binaries. To make sure you use the most recent version of Octez, run: docker pull tezos/tezos-bare:latest For instance, to run a node on currentnet, starting from a snapshot, in Rolling history mode, start with a fresh directory and configure the node: mkdir $HOME/rolling-data-directory docker run -it --rm \ --volume "$HOME/rolling-data-directory:/home/tezos/.tezos-node" \ tezos/tezos-bare:latest \ octez-node config init --network https://teztnets.com/currentnet --rpc-addr 127.0.0.1 \ --history-mode rolling (You may use another location than "$HOME", but note that option "-- volume" requires absolute paths.) Then, download and import a snapshot, and finally run the node: wget -O $HOME/rolling https://snapshots.tzinit.org/currentnet/rolling docker run -it --rm \ --volume "$HOME/rolling-data-directory:/home/tezos/.tezos-node" \ --volume "$HOME/rolling:/rolling:ro" \ tezos/tezos-bare:latest \ octez-node snapshot import /rolling docker run --name octez-local-node -it \ --volume "$HOME/rolling-data-directory:/home/tezos/.tezos-node" \ tezos/tezos-bare:latest \ octez-node run You may check when your node is bootstrapped by executing in another terminal: docker exec -it octez-local-node octez-client bootstrapped You may stop and restart the node as needed, for instance if you need to upgrade the version of the storage: docker stop octez-local-node docker run --rm --volumes-from octez-local-node tezos/tezos-bare:latest \ octez-node upgrade storage docker start octez-local-node Docker compose files -------------------- Another way to run those Docker images is with docker-compose. A predefined Docker compose file is available at scripts/docker/bake.yml. It aims at helping you launch **a testnet** baker quickly, providing services for an Octez node, a DAL node, a baker, and an accuser. You may copy the compose file in the directory where you want to run the baker: wget https://gitlab.com/tezos/tezos/-/raw/master/scripts/docker/bake.yml The client, node, and DAL data are stored in the following subdirectories of your current directory, respectively: "./client_data/", "./node_data/", and "./dal_data/". You may want to start with empty (or non-existent) directories in the beginning, then reuse them to restart the services. Note: If the node complains that it is configured for another network, you'll have to remove the node configuration file before running it: rm ./node_data/data/config.json First, you have to make some choices: * choose a network to connect to (by default, "shadownet") * specify a vote for the liquidity baking feature ("on", "off", or "pass") Create an environment file called ".env" in your current directory with a content of the following form: LIQUIDITY_BAKING_VOTE='pass' NETWORK='ushuaianet' and build the compose file: docker compose --file bake.yml build Note that you must have already: * a "baker" key on the network you chose, which is sufficiently funded, staked enough tez, and is registered as a delegate, * optionally but recommended, a consensus key named "signing-key" and a "companion-key" associated with the baker key. This is the case, for instance, if you had already run the baker using this compose file. Note: If you don't have yet configured the baker keys, you can first do this: docker compose -f bake.yml up manual-config -d wait until the node is bootstraped from the snapshot, and then do: docker compose -f bake.yml exec manual-config sh and in the shell set up the baker keys: octez-client gen keys baker octez-client show address baker # Fund baker with > 6000 tez, e.g. at https://faucet.shadownet.teztnets.com octez-client register key baker as delegate octez-client stake 6000 for baker # Define auxiliary consensus and companion keys (recommended): octez-client gen keys signing-key -s bls octez-client set consensus key for baker to signing-key octez-client gen keys companion-key -s bls octez-client set companion key for baker to companion-key exit Alternatively, if you already have the baker and auxiliary keys, but you never ran this compose file, you can import them by rather doing this in the above shell: octez-client import secret key baker unencrypted: octez-client import secret key consensus-key unencrypted: octez-client import secret key companion-key unencrypted: # if your baker was deactivated, reactivate it: octez-client register key baker as delegate You can arbitrarily combine the two methods above, at your convenience. For example, if you have a baker key but not auxiliary keys, you can import the baker key and create the auxiliary keys. Now, you just have to start all the services: docker compose --file bake.yml up -d You can see the logs by doing in another terminal (in the same directory): docker compose --file bake.yml logs -f (add a service such as "node" or "baker" at the end of the command line to see only its log). You should have now running together: the node, the DAL node, the baker and the accuser. You can stop the services with: docker compose --file bake.yml down Alternatively, you may stop and restart only one service. For instance if the Octez version you are using requires to upgrade the version of the storage, you can restart the node after upgrading the storage: docker compose -f bake.yml stop node docker compose -f bake.yml run --rm node octez-node upgrade storage --data-dir /var/run/tezos/node/data docker compose -f bake.yml up node Further customization ~~~~~~~~~~~~~~~~~~~~~ Beyond the common usage shown above, you can use the following variables in the environment file to customize the behavior of the compose file, grouped by category. Configuration: * LIQUIDITY_BAKING_VOTE (mandatory): value to pass to the baker daemon in mandatory flag "--liquidity-baking-toggle-vote" * NETWORK (default: shadownet): network to connect to * NETWORK_URL (default: "https://teztnets.com/$NETWORK"): URL to get the network configuration * HISTORY_MODE (default: rolling): set the history mode of your node * TEZOS_NODE_OPTIONS (default: none): extra options to be passed to the node Snapshot management: * IMPORT_SNAPSHOT (default: true): if false, don't import a snapshot, bootstrap from origin; if true, import a snapshot unless the node has recent data (but see FORCE_IMPORT_SNAPSHOT) * FORCE_IMPORT_SNAPSHOT (default: false): import the snapshot even if the node has recent data (same day); has no effect when IMPORT_SNAPSHOT is false * FORCE_DOWNLOAD_SNAPSHOT (default: false): if true, download the snapshot even if it has been found localy (see SNAPSHOT_URL) * CHECK_SNAPSHOT (default: false): if false, import the snapshot with option --no-check * SNAPSHOT_URL (default: use teztnet server): URL where download the snapshot if not found localy (see SNAPSHOT_NAME) * SNAPSHOT_NAME (default: no local file): name of a local snapshot file Baking keys management: * BAKER_ADDRESS: the "tz..." address of the baker manager account (not needed if the key "baker" has been configured manually) * SIGNING_KEY: the name of the signing key (defaults to "signing-key") * COMPANION_KEY: the name of the companion key (defaults to "companion-key"; optional, unless the signing key is a tz4 address) * BAKER_SECRET_KEY: secret key of the baker (not needed if a baker or signing key has been configured manually, or if CONSENSUS_SECRET_KEY is defined) * CONSENSUS_SECRET_KEY: secret key of the consensus key (not needed if a baker or signing key has been configured manually, or if BAKER_SECRET_KEY is defined) * COMPANION_SECRET_KEY: secret key of the companion address (optional, unless a baker or signing key has been configured manually as a tz4 address or CONSENSUS_SECRET_KEY is defined as a tz4 address) Note: If you want to manually configure the node, use the same "manual- config" service as for configuring the baker keys: docker compose -f bake.yml exec manual-config sh then in the shell interact with the node directly: octez-node config show octez-node config update ... Building Docker Images Locally ------------------------------ The docker image used throughout the docker-compose files is fetched from upstream, but you can also build one locally and reference it. Run the following command to build the image: ./scripts/create_docker_image.sh The distribution is built FROM base images that the script expects to find first. If they are missing, it stops and prints how to obtain them; see "images/README.md" and "./scripts/create_docker_image.sh --help" for the details. And then update the docker-compose file (e.g., "alpha.yml") with the docker tag: node: image: tezos:latest ... Docker Image Configuration -------------------------- Lastly, the entrypoint script (scripts/docker/entrypoint.sh) provides the following configurable environment variables: * "DATA_DIR": The directory to store the node's data (defaults to "/var/run/tezos"). * "NODE_HOST": The name of the node container (defaults to "node"). * "NODE_RPC_PORT": The RPC port **inside the container** the node listens to (defaults to "8732"). * "NODE_RPC_ADDR": The RPC address **inside the container** the node binds to (defaults to "[::]"). * "PROTOCOL": The protocol used (if the protocol is not provided, "octez-baker" and "octez-accuser" will be used). These variables can be set in the docker-compose file, as demonstrated in scripts/docker/alpha.yml: octez-node: ... environment: PROTOCOL: alpha ... If the above options are not enough, you can always replace the default "entrypoint" and "command" fields. version: "3" services: octez-node: container_name: octez-node-alpha entrypoint: /bin/sh command: /etc/my-init-script.sh volumes: - ./my-init-script.sh:/etc/my-init-script.sh - ... environment: PROTOCOL: alpha ... Installing binaries =================== Depending on your operating system, you may install Octez (dynamically-linked) binaries and their dependencies by first downloading the packages for your distribution from the Octez release page, browsing to your distribution and then installing them with your package tool manager. Most of the configuration options are accessible by the user in "/etc/default/". If you are upgrading from a different package distributor such as Serokell's tezos-packaging, please pay attention to the possible differences between the two packages, in particular regarding the home directory for the "tezos" user. There are several packages: * "octez-client": the client for manipulating wallets and signing items * "octez-node": the Octez node * "octez-baker": the Octez baking and VDF daemons * "octez-smartrollup": the Octez Smart Rollup daemons * "octez-signer": the remote signer, to hold keys on (and sign from) a different machine from the baker or client Appendix ======== * Building Octez from source * Install Rust * Install Zcash Parameters * Install DAL trusted setup * Get the sources * Install Octez dependencies * Compile * Update * Migrating from Nomadic Labs packages to Tzinit packages * Supported platforms * Step-by-step procedure * Context and explanations * Verifying Octez Docker Images with Cosign * Prerequisites * Obtaining the Public Key * Verifying the Docker Image * Inspecting the SLSA Provenance Attestation * Inspecting the Software Bill of Materials (SBOM) * Installation troubleshooting * Generic issues * Mixing LLVM and GNU binutils * Compiling the sources Building Octez from source ************************** If you plan to contribute to the Octez codebase or if you want to build a version of Octez that is based on the most recent code, the way to go is to set up a complete development environment by cloning the repository and compiling the sources using the provided makefile. Note that setting up a complete development environment requires a powerful machine, and the required resources are increasing in the long run. If you are using Octez for production, consider installing forms of prebuilt binaries, refer to Installing Octez, the reference implementation of Tezos. You can either build all the executables, as illustrated below, or only a subset of the executables, as detailed in section Compile. Note: In order to build Octez v24.0 (and later versions) from sources, please make sure that you have installed opam [v2.3 or later](https://opam.ocaml.org/doc/Install.html). **TL;DR**: From a fresh Debian Trixie x86_64, you typically want to select a source branch in the Octez repository, e.g.: REPO="tezos/tezos" BRANCH="latest-release" and then do: sudo apt-get install -y rsync git m4 build-essential patch unzip wget opam jq bc libev4 postgresql cmake libclang-dev # [install rust] wget https://sh.rustup.rs/rustup-init.sh chmod +x rustup-init.sh ./rustup-init.sh --profile minimal --default-toolchain 1.94.0 -y . $HOME/.cargo/env # [get sources] git clone https://gitlab.com/"$REPO".git tezos cd tezos git checkout $BRANCH # [init opam] opam init --bare make build-deps # [compile sources] eval $(opam env) make release # [optional setup] # puts Octez binaries in PATH: # export PATH=$PWD/_build/install/default/bin/:$PATH # if using bash, enables autocompletion: # source ./src/bin_client/bash-completion.sh # removes Mainnet/testnet disclaimers: # export TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y Warning: If you rerun the procedure above in an already cloned repository, typically by restarting from "git checkout $BRANCH" after upgrading the sources to a new version of Octez, you should do a "git fetch" before, to ensure that the tags for the latest release are known to Git. Otherwise, the sources compile perfectly fine but Octez executables may report their version incorrectly (e.g. "21.2+dev" instead of "22.0"). The following sections describe the individual steps above in more detail. Note: Besides compiling the sources, it is recommended to also install Python and some related tools, which are needed, among others, to build the documentation and to use the Git pre-commit hook. Install Rust ============ Compiling Octez requires the Rust compiler (see recommended version in variable "$recommended_rust_version" in file "scripts/version.sh") and the Cargo package manager to be installed. If you have rustup installed, it should work without any additional steps on your side. You can use rustup 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: wget https://sh.rustup.rs/rustup-init.sh chmod +x rustup-init.sh ./rustup-init.sh --profile minimal --default-toolchain 1.94.0 -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: . $HOME/.cargo/env Note that the command line above assumes that rustup installed Cargo in "$HOME/.cargo", but this may change depending on how you installed rustup. See the documentation of your rustup distribution if file ".cargo" does not exist in your home directory. Install Zcash Parameters ======================== Octez binaries require the Zcash parameter files to run. Docker images come with those files, and the source distribution also includes those files. But if you compile from source and move Octez to another location (such as "/usr/local/bin"), the Octez 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/713fc761dd9cf4c9087c37b078bdeab98697bad2/zcutil/fetch-params.sh chmod +x fetch-params.sh ./fetch-params.sh The node will try to find Zcash parameters in the following directories, in this order: 1. "$XDG_DATA_HOME/.local/share/zcash-params" 2. "$XDG_DATA_DIRS/zcash-params" (if "$XDG_DATA_DIRS" contains several paths separated by colons ":", each path is considered) 3. "$OPAM_SWITCH_PREFIX/share/zcash-params" 4. "./_opam/share/zcash-params" 5. "~/.zcash-params" 6. "~/.local/share/zcash-params" 7. "/usr/local/share/zcash-params" 8. "/usr/share/zcash-params" If the node complains that it cannot find Zcash parameters, check that at least one of those directories contains both files "sapling- spend.params" and "sapling-output.params". Here is where you should expect to find those files: * if you are compiling from source, parameters should be in "_opam/share/zcash-params" (you may need to run "eval $(opam env)" before running the node); * if you used "fetch-params.sh", parameters should be in "~/.zcash- params". Note: Some operating systems may not be covered by the list of directories above. If Zcash is located elsewhere on your system (typically, on MacOS X), you may try creating a symbolic link such as: "ln -s ~/Library/Application\ Support/ZcashParams ~/.zcash-params".Also on MacOS X, the script may complain if you have BSD-compatible tools installed such as "sha256sum". In this case, a solution is to install GNU-compatible tools and use them instead when running the script: brew install coreutils PATH="$(brew --prefix coreutils)/libexec/gnubin:$PATH" ./fetch-params.sh Note that the script "fetch-params.sh" downloads a third file containing parameters for Sprout (currently called "sprout- groth16.params"), which is not loaded by Sapling and can be deleted to save a significant amount of space (this file is *much* bigger than the two other files). Install DAL trusted setup ========================= Users running DAL in **operator or observer** profiles need to have a set of cryptographic parameters (known as an SRS) installed in order to run their DAL node. In particular, these are needed when executing the Octez test suite, which involves DAL nodes running in various profiles. However, for simplicity, on some test networks the initialization parameters are mocked-up and built-in. The cryptographic parameters can be retrieved via the following script: scripts/install_dal_trusted_setup.sh Get the sources =============== Octez "git" repository is hosted at GitLab. All development happens here. Do **not** use our GitHub mirror which we don't use anymore and only mirrors what happens on GitLab. Checkout the "latest-release" branch to use the latest release. Alternatively, you can checkout a specific version based on its tag. Install Octez dependencies ========================== Install the OCaml compiler and the libraries that Octez depends on: make build-deps Alternatively, if you want to install extra development packages such as "merlin", you may use the following command instead: make build-dev-deps Note: * These commands create a local OPAM switch ("_opam" folder at the root of the repository) where the required version of OCaml and OCaml Octez dependencies are compiled and installed (this takes a while but it's only done once). * Be sure to "eval $(scripts/env.sh)" when you "cd" into the repository in order to be sure to load this local environment. * As the opam hook would overwrite the effects of "eval $(scripts/env.sh)" the script will disable the opam hook temporarily. * OPAM is meant to handle correctly the OCaml libraries but it is not always able to handle all external C libraries we depend on. On most systems, it is able to suggest a call to the system package manager but it currently does not handle version checking. * Building the smart rollup node compiles RocksDB, whose "bindgen" step needs "libclang" and clang's builtin headers. The package list above installs them as "libclang-dev". On Fedora, RHEL and Rocky it is "clang-devel". On macOS the Xcode command line tools or the Homebrew "llvm" formula provide them. If the build fails with "Unable to find libclang", set "LIBCLANG_PATH" to the directory holding it. * As a last resort, removing the "_opam" folder (as part of a "git clean -dxf" for example) allows to restart in a fresh environment. Compile ======= Once the dependencies are installed we can update OPAM's environment to refer to the new switch and compile the project to build all the executables: eval $(opam env) make release Note: Instead of the simple "make" command above, you may use more restrictive targets in the makefile to build only some subset of the executables. For instance, you may exclude experimental executables using "make release"; furthermore exclude executables such as the EVM node using "make octez"; or even restrict to Layer 1 executables using "make octez-layer1". Lastly, you can also add the Octez binaries to your "PATH" variable, and after reading the Disclaimer a few hundred times you are allowed to disable it with "TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y". You may also activate Bash autocompletion by executing: source ./src/bin_client/bash-completion.sh Warning: Note that if your shell is "zsh", you may need extra configuration to customize shell completion (refer to the "zsh" documentation). Incremental Rust builds ----------------------- You can enable incremental Rust compilation for development builds with: OCTEZ_RUST_INCREMENTAL=1 make This speeds up rebuilds after Rust code changes, at the cost of extra disk space for cached compilation results. Run "dune clean" to reclaim that space; the next build will rebuild everything. Update ====== For updating to a new version, you typically have to update the sources by doing "git pull" in the "tezos/" directory and replay the compilation scenario starting from "make build-deps". You may also use "make clean" (and "rm -Rf _opam/" if needed) before that, for restarting compilation in a fresh state. Migrating from Nomadic Labs packages to Tzinit packages ******************************************************* Starting from Octez version 26, Nomadic Labs no longer publishes Debian and Ubuntu packages for Octez. Packages built along the same lines, called *Tzinit packages*, are available in an APT repository at "https://apt.tzinit.org". Individual package files (including RPM packages) are also available at https://packages.tzinit.org/. These packages are documented at https://chrispinnock.com/tezos/packages/. This page explains how to migrate an installation of the Nomadic Labs packages for Octez v25.2 (abbreviated as *NL packages* hereafter) to the Tzinit packages. The migration is an in-place upgrade: chain data, wallets and baker state are left untouched. However, the configuration of the baker changes, and some services must be re-enabled manually. Warning: Do **not** uninstall or purge the NL packages to switch to the Tzinit packages. Purging the "octez-node" NL package can delete the node's data directory, and purging the "octez-baker" NL package deletes the baker's high watermarks and nonces. Supported platforms =================== The Tzinit packages are available for: * Debian 13 ("trixie"), * Ubuntu 24.04 ("noble"), both on "amd64" and "arm64" architectures. If you are running another distribution, there is no direct upgrade path using "apt"; see Installing Octez, the reference implementation of Tezos for other installation methods. Step-by-step procedure ====================== 1. Back up your configuration and wallet ---------------------------------------- The procedure does not modify your data, but it is good practice to save your configuration files and your wallet (including the baker's high watermarks and nonces) before proceeding: sudo tar czf ~/octez-migration-backup.tgz /etc/default/octez-* /var/tezos/.tezos-client 2. Stop all Octez services -------------------------- sudo systemctl stop octez-smart-rollup-node octez-baker octez-dal-node octez-node Stopping "octez-baker" also stops the bakers and accusers that it started. Check that no Octez service is still running: systemctl list-units 'octez*' Services may be listed as "failed" instead of being absent from the list: this is expected, as Octez daemons exit with a non-zero status when they are stopped. 3. Replace the APT repository ----------------------------- Remove the NL repository: sudo rm /etc/apt/sources.list.d/octez.list Add the signing key of the Tzinit repository: sudo apt-get install -y gpg curl curl -s https://apt.tzinit.org/keys/tzinit.asc | sudo gpg --dearmor -o /etc/apt/keyrings/tzinit.gpg Check that the fingerprint of the key is "181E 6294 A077 0AE9 AF01 73B2 1F68 8E12 01D8 19B4": gpg --show-keys /etc/apt/keyrings/tzinit.gpg Then add the Tzinit repository. On Debian 13: echo "deb [signed-by=/etc/apt/keyrings/tzinit.gpg] https://apt.tzinit.org/debian trixie main" | sudo tee /etc/apt/sources.list.d/tzinit-octez.list On Ubuntu 24.04: echo "deb [signed-by=/etc/apt/keyrings/tzinit.gpg] https://apt.tzinit.org/ubuntu noble main" | sudo tee /etc/apt/sources.list.d/tzinit-octez.list 4. Upgrade the packages ----------------------- Upgrade the packages while keeping your current configuration files: sudo apt-get update sudo apt-get -o Dpkg::Options::=--force-confold full-upgrade Use "full-upgrade" rather than "upgrade": the NL packages depend on each other's exact versions, and "upgrade" may keep some of them back (for instance "octez-node" when "octez-smart-rollup-node" is installed). Before confirming, check that "apt-get" does not plan to remove any package. When a configuration file that you modified is kept, the default version shipped by the Tzinit package is saved next to it, with suffix ".dpkg-dist". Warning: Files "/etc/default/octez-accuser" and "/etc/default/octez-vdf" are overwritten by the Tzinit "octez-baker" package, without keeping any previous version. If you created "/etc/default/octez-accuser" yourself, restore its contents from your backup and check it after each upgrade. Check that all Octez packages now come from the Tzinit repository: dpkg -l 'octez*' All packages should be at version "25.2-10" or later, except "octez- smart-rollup-node" which uses a date-based version such as "20260724-10". The NL "octez-baker" package recommended "octez-signer", but the Tzinit one does not. As a consequence, "apt" may now report "octez- signer" as "automatically installed and no longer required". If you use the signer, prevent "apt autoremove" from removing it: sudo apt-mark manual octez-signer 5. Adapt the baker configuration -------------------------------- In the NL packages, service "octez-baker" started the bakers and accusers, as well as the DAL node if "--dal-node" was configured. In the Tzinit packages, service "octez-baker" only runs the baker; the accuser and the DAL node are separate services. The variables of "/etc/default/octez-baker" have also changed. Edit this file (using "/etc/default/octez-baker.dpkg-dist" as a template, if it exists) as follows: +----------------------------------------------------+----------------------------------------------------+ | NL packages | Tzinit packages | |====================================================|====================================================| | "LQVOTE="pass"" | "LQ_VOTE="pass"" (**mandatory**: the baker does | | | not start until it is set) | +----------------------------------------------------+----------------------------------------------------+ | "BAKER_KEY="mybaker"" | "KEYS="mybaker"" | +----------------------------------------------------+----------------------------------------------------+ | "RUNTIME_OPTS="--dal-node http://127.0.0.1:10732"" | "DAL_OPTIONS="--dal-node http://127.0.0.1:10732"", | | | and remove "--dal- node" from "RUNTIME_OPTS" | +----------------------------------------------------+----------------------------------------------------+ | no DAL node | "DAL_OPTIONS="--without-dal"" (the default) | +----------------------------------------------------+----------------------------------------------------+ | "AGNOSTIC_BAKER=..." | remove (the protocol-agnostic baker is always | | | used) | +----------------------------------------------------+----------------------------------------------------+ The Tzinit baker does not read "/etc/default/octez-node". If you changed "DATADIR" in "/etc/default/octez-node", also set "DATADIR" in "/etc/default/octez-baker". Similarly, if the base directory of "octez-client" (option "--base-dir") is not "/var/tezos/.tezos- client", set "CLIENTDIR". The accuser is configured separately, in "/etc/default/octez-accuser". 6. Adapt the smart rollup node configuration -------------------------------------------- Skip this step if you do not run a smart rollup node. The "octez-smart-rollup-node" service of the Tzinit packages does not read file "/etc/default/octez-smart-rollup-node". To make it read this file, add the following override: sudo mkdir -p /etc/systemd/system/octez-smart-rollup-node.service.d printf '[Service]\nEnvironmentFile=-/etc/default/octez-smart-rollup-node\n' | sudo tee /etc/systemd/system/octez-smart-rollup-node.service.d/override.conf The Tzinit service already passes the data directory to the smart rollup node. Do not put "--data-dir" in "RUNTIME_OPTS": set "DATADIR" instead. 7. Start the services --------------------- sudo systemctl daemon-reload sudo systemctl enable --now octez-node If you run a DAL node: sudo systemctl enable --now octez-dal-node If you run a baker: sudo systemctl enable --now octez-baker octez-accuser If you run a smart rollup node: sudo systemctl enable --now octez-smart-rollup-node 8. Check the logs ----------------- The services of the Tzinit packages write their logs in "/var/log/tezos", but some file names have changed: +-----------------------------------+-----------------------------------+-----------------------------------+ | Service | NL packages | Tzinit packages | |===================================|===================================|===================================| | "octez-node" | "node.log" | "octez-node.log" | +-----------------------------------+-----------------------------------+-----------------------------------+ | "octez-baker" | "baker-.log" or | "octez-baker.log" | | | "baker.log" | | +-----------------------------------+-----------------------------------+-----------------------------------+ | "octez-accuser" | "accuser-.log" or | "octez-accuser.log" | | | "accuser.log" | | +-----------------------------------+-----------------------------------+-----------------------------------+ | "octez-dal-node" | "octez-dal-node.log" | "octez-dal-node.log" (unchanged) | +-----------------------------------+-----------------------------------+-----------------------------------+ | "octez-smart-rollup-node" | "smart-rollup-node.log" | "octez-smart-rollup.log" | +-----------------------------------+-----------------------------------+-----------------------------------+ For instance, check that the node is running with: tail -f /var/log/tezos/octez-node.log Once all services run correctly, you may delete the old log files. Context and explanations ======================== Data ---- Both the NL and Tzinit packages run the Octez daemons as user "tezos", whose home directory is "/var/tezos". The Tzinit packages reuse the existing "tezos" user and its home directory. As a consequence, all data stays in place: * the node data directory, "/var/tezos/.tezos-node" by default (variable "DATADIR" of "/etc/default/octez-node"); * the wallet and the baker state (high watermarks, nonces), "/var/tezos/.tezos-client"; * the DAL node data directory and configuration, "/var/tezos/.tezos- dal-node"; * the smart rollup node data directory, "/var/tezos/.tezos-smart- rollup-node". The "octez-node" binary of the Tzinit packages for v25.2 is built from the same commit as the NL one, so the node data needs no conversion. The Tzinit "octez-smart-rollup-node" package ships a standalone release of the smart rollup node instead of the one from Octez v25.2, but both use the same storage format. Configuration files ------------------- Except for "/etc/default/octez-accuser" and "/etc/default/octez-vdf", files "/etc/default/octez-*" are configuration files: when you have modified one of them, the upgrade does not overwrite it (thanks to option "--force-confold"). Files "/etc/default/octez-node" and "/etc/default/octez-dal-node" use the same variables in the NL and Tzinit packages. File "/etc/default/octez-baker" does not, hence step 5. Services -------- The Tzinit packages ship systemd services with the same names as the NL packages for "octez-node", "octez-baker", "octez-dal-node" and "octez-smart-rollup-node"; services that were enabled remain enabled. The per-protocol services "octez-baker@" and "octez- accuser@" of the NL packages, as well as "octez-agnostic- baker" and "octez-agnostic-accuser", are replaced by "octez-baker" and "octez-accuser". The upgrade does not restart the services, which is why they are stopped before the upgrade and started again afterwards. The Tzinit packages also provide services that were not present in the NL packages: "octez-baker-remote" (a baker using a node on another machine), "octez-vdf", "octez-signer", as well as packages "octez-evm- node" and "octez-teztale-archiver". See https://chrispinnock.com/tezos/packages/ for details. Signer ------ The NL packages did not provide a system-wide service for "octez- signer". If you followed Setting up Octez Services, you run the signer as a systemd *user* service, defined in "~/.config/systemd/user/octez- signer.service". This service keeps working after the migration. The Tzinit "octez-signer" package provides a system-wide "octez- signer" service running as a dedicated user "tzsigner", with its own keys in "/var/tzsigner/.tezos-signer", and listening over HTTP. This service is not enabled by default; do not enable it in addition to your existing signer. Verifying Octez Docker Images with Cosign ***************************************** Cosign is a tool developed by Sigstore to sign and verify container images and other artifacts. This document provides instructions on how to verify Docker images of Octez signed using Cosign. Prerequisites ============= Before you can verify Docker images signed with Cosign, ensure you have Docker and Cosign installed on your system. * Docker Installation Guide * Cosign Installation Guide Obtaining the Public Key ======================== To verify a signed Docker image, you need the public key that corresponds to the private key used for signing. The pem certificate is available at https://keyserver.nomadic-labs.com/cosign/nl-prod- docker-sign-key.pem Saving the public key: # Save the public key to a file (e.g., octez.pub) curl -o octez.pub https://keyserver.nomadic-labs.com/cosign/nl-prod-docker-sign-key.pem Verifying the Docker Image ========================== To verify the Octez Docker image, follow these steps: 1. **Pull the Docker Image** (if not already pulled): docker pull tezos/tezos-bare:master 2. **Use Cosign to Verify the Image**: Replace the image name with the name of your Docker image and tag with the specific tag ( for example "tezos/tezos:22.0" ) cosign verify --key octez.pub tezos/tezos-bare:master Or more directly: cosign verify --key https://keyserver.nomadic-labs.com/cosign/nl-prod-docker-sign-key.pem tezos/tezos-bare:master 3. **Check the Output**: You can use tools like "jq" to parse the json output of Cosign: cosign verify --key https://keyserver.nomadic-labs.com/cosign/nl-prod-docker-sign-key.pem tezos/tezos-bare:master | jq If the verification is successful, Cosign will output the signatures and their claims in JSON format: The following checks were performed on each of these signatures: - The cosign claims were validated - Existence of the claims in the transparency log was verified offline - The signatures were verified against the specified public key [ { "critical": { "identity": { "docker-reference": "" }, "image": { "docker-manifest-digest": "sha256:" }, "type": "cosign container image signature" }, "optional": { "Bundle": { "SignedEntryTimestamp": "", "Payload": { "body": "", "integratedTime": "