Breaking changes

Breaking changes#

This section presents the breaking changes that users can encounter between different Protocols or Octez versions. It complements the “Breaking changes” sections in the development changelogs by providing more context and/or less fragmented mentions.

For each change, there may be subsections Deprecation and Breaking changes. The former subsection will explain what changes can be made during a deprecation phase to adapt smoothly to the new changes. The latter subsection will present the changes that can not be done by the deprecation mechanism and that may be breaking.

In the particular case of RPC changes, you may consult complementary information on RPC versioning, covering how new versions are introduced, the deprecation policy, and a concrete calendar of RPCs planned to be removed.

Denunciation operations#

Protocol S adds new operations and changes the encoding of some existing operations, for instance by adding new fields. These changes are related to the support for tz4 BLS addresses and their aggregated signatures.

Backward compatibility#

Most of the changes in the encodings of existing operations are either purely added operations (e.g. update_companion_key) or optional fields that should not break (e.g., for operations reveal and update_consensus_key).

However, tool providers who do not use encodings but rather p2p message format, may experience some issues.

Breaking changes#

Starting in protocol S, the Double_preattestation_evidence and Double_attestation_evidence operations are replaced with a new Double_consensus_operation_evidence operation, in order to enable denunciations of aggregated consensus operations. This new operation contains a denounced slot and two denounced consensus operations. For the evidence to be valid, the denounced operations must both be preattestations (each one may be aggregated or not) or both be attestations. Moreover, both must involve the denounced slot, that is, be either a standalone operation for this slot or an aggregate whose committee includes this slot. The receipts for these operations have also been reworked, see Operation receipts.

All existing tz4 addresses are being unrevealed when protocol S is adopted, and they must provide a proof of possession to be revealed again, see Breaking Changes.

Attestations#

Support for deprecated attestation legacy name (“endorsement”), that was still usable with RPCs version 0 will be removed in the protocol proposal Q and Octez v21.0.

Opam packages#

Starting from Octez v18, the Opam packages are being reworked as a new set containing fewer packages. This allows easier installation and maintenance.

These changes are transparent for users of the different kinds of Octez distributions (static executables, Docker images, Opam-installed binaries, etc.). They only impact software developers directly relying on Opam packages within the Octez repository (i.e. using them as dependencies).

New architecture#

Some Octez libraries which used to be distributed as their own Opam package have been aggregated into fewer and coarser Opam packages.

Each aggregate is related to a part of Octez.

Octez is now distributed as the following set of Opam packages:

  • octez-libs : Contains the base libraries for Octez (cryptography primitives, error management helpers, etc.).

  • octez-shell : Contains the libraries related to the Octez shell.

  • octez-proto-libs : Contains the libraries for the Tezos protocol.

  • octez-l2-libs : Contains the libraries related to layer 2.

  • For each protocol P: - octez-protocol-P-libs : The protocol P dependent libraries. - tezos-protocol-P: The Tezos protocol P itself.

To have a better understanding of the packages and the complete description of them, you might want to follow the OCaml API documentation.

Note on library renaming#

In aggregated packages, redundant suffixes and prefixes have been removed. Specifically, all the sub-libraries prefixed with tezos- or octez- are now renamed without the prefix. For instance, tezos-base, which is now a sub-library of octez-libs, is now octez-libs.base.

The protocol name suffixes of the protocol libraries have also been removed. For instance, Tezos-client-017-PtNairob is now the sub-library Client of the package Octez-017-PtNairob-libs.

Backward compatibility#

One can install the Octez suite directly by using the command:

opam install octez

This process is the same as with the previous set of packages. The only difference is the installed packages, but no compatibility issues will be encountered.

Alternatively, each Octez package can be installed separately:

opam install package-name

Breaking changes#

Opam packages can be used as dependencies for software development. Contrary to the previous section, the rework of the Octez Opam packages will require you to adapt how your software declares Octez-related Opam dependencies.

For each dependency:

  • Search for the new package name in the API.

  • Change the Opam depends to the package name.

  • Update the dune files with the new name package.sub-library.

  • Change the module name in the open in the code to Package.Sub-library.

For instance, if your software depends on tezos-rpc which is now a sub-library of octez-libs and has been renamed to rpc:

  • Update the opam file content to rename the tezos-rpc dependency to octez-libs. If octez-libs is already present, only remove the dependency on tezos-rpc.

  • Update the dune file to rename occurences of tezos-rpc, e.g. in libraries clauses of executable stanzas to octez-libs.rpc.

  • In your code, update all references to the Tezos_rpc module (e.g. open Tezos_rpc) to Octez-libs.Rpc (e.g. open Octez-libs.Rpc).

The same method applies to each dependency that is now a sub-library of a new package. Check the API to see the new packages.

Delegates rights vs stake snapshots#

The selection of the delegates’ participation rights in the proof-of-stake consensus protocol is done based on their stake. This computation is explained in generic terms in Proof-of-stake.

One detail of the rights computation has changed: which values are considered for the delegates’ stake in each cycle. Previously, the considered values corresponded to a notion of stake snapshots, recorderd regularly by the protocol.

Breaking changes#

Since protocol Paris, there are no more stake snapshots, so the protocol no longer relies on stake snapshots to compute the rights.

Instead:

  • Rights originating from staked tez are computed from the value at the end of the cycle;

  • Rights originating from delegated tez are computing using the minimum value over the cycle.

Timelocks: chest keys#

Timelocks were temporarily disabled by the activation of the Lima protocol. to address a critical vulnerability.

A new safer version of Timelocks was developed to address this issue, and the feature was re-enabled in the Oxford protocol. However, the new chest keys format could not be made backward compatible with the previous one.

Fortunately, no contracts using the legacy format of chest keys are deployed on Tezos mainnet.

Breaking changes#

However, this change may impact old contracts on the Ghostnet test network. For example, one (trivial) chest key demo contract was originated a long time ago on Ghostnet and uses the legacy format for chest keys.

As a consequence, inspecting this Ghostnet contract currently returns an error response with status 500:

Body:
[
    {
        "kind": "permanent",
        "id": "proto.019-PtParisB.michelson_v1.ill_typed_data",
        "expected_type": {
            "prim": "chest_key"
        },
        "ill_typed_expression": {
            "bytes": "e4c38197..."
        }
    },
    ...
]

Upcoming changes#

Baker: Explicit choice on using DAL or not via the CLI#

Octez v21.3 introduces the new --without-dal option for the baker daemon. In Octez v21.3, this option is not mandatory and will only trigger a warning.

Starting from Octez v22, launching a baker daemon requires an explicit mention of the DAL. The recommended approach is to run a DAL node and start the baker using the --dal-node <uri> option. If you do not wish to use a DAL node, you can opt-out by using the --without-dal option.