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 a subsection
changes. The first subsection will explain what changes can be made during a
deprecation phase to adapt smoothly to the new changes. The second subsection
will present the changes that can not be done by the deprecation mechanism and
that may be breaking.
Starting with the Oxford protocol proposal and the Octez
v19 the legacy attestation name
endorsement is now deprecated and
attestation should be used everywhere. Then,
preendorsement is renamed
double_attestation_evidence. The same goes for operation receipts such as
lost endorsing rewards, which are renamed to
lost attesting rewards.
To allow a smooth transition we implemented a deprecation mechanism that will
start with Oxford and Octez
v19 and should end in two protocols and two
Octez releases. We were not able to version everything so some changes, detailed
below, are breaking.
For the Oxford and Octez
v19 we introduced a new version argument
?version=<n> for the following RPCs that can output
attestation (and legacy
See changelog for more details.
O and version
v19, using the version
0, which is the
default value, will still output the legacy attestation name. Version
allows the RPCs to output
attestation instead of the legacy name.
For a protocol upgrade proposal to succeed Oxford, i.e. for protocol
the next major release of Octez,
v20.0, the default value of these RPCs will be
1 but the version
0 will still be usable.
0 and support for legacy name (“endorsement”) will be removed in the
subsequent protocol and major Octez versions – that is, protocol upgrade
Q and Octez
As an exception, for the
GET /chains/<chain>/mempool/pending_operations RPC,
O and version
v19`, due to previous versioning of this RPC,
the legacy version is already ``1 (currently the default) and you should use
2 to output
Starting with protocol Oxford, the protocol
parameters, storage fields and errors that were using the legacy attestation
name now use
attestation. The baker and accuser will no longer use the
legacy attestation name in their event messages and errors and will use
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).
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
Pdependent libraries. -
tezos-protocol-P: The Tezos protocol
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
octez- are now renamed without the prefix.
tezos-base, which is now a sub-library of
octez-libs, is now
The protocol name suffixes of the protocol libraries have also been removed.
Tezos-client-017-PtNairob is now the sub-library
Client of the package
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
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
dependsto the package name.
dunefiles with the new name
Change the module name in the
openin the code to
For instance, if your software depends on
tezos-rpc which is now a sub-library of octez-libs and has been renamed to
Update the opam file content to rename the
octez-libsis already present, only remove the dependency on
Update the dune file to rename occurences of
tezos-rpc, e.g. in
In your code, update all references to the
open Tezos_rpc) to
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.