Protocol Environment — Octez & Protocol products documentation (original) (raw)

Protocol Environment#

The protocol environment is a restricted API that may be used by the economic protocol’s code, on one hand, and the rest of the Octez code, on the other hand, to interact with each other. Firstly, this allows protocols to only call authorized modules and functions. Secondly, it allows the node (i.e., the main binary built around the shell) as well as the other binaries (e.g., the baker) to call a subset of the protocol functions.

Motivation#

In the currently active protocol, as in any sound future protocols, updates are approved by voting. That way, the responsibility of switching to a new protocol code is the responsibility of voters, and one could argue that it is up to them to check that the code does not call, for instance, unsafe array access functions.

Yet, we decided to introduce a minimum level of machine checks, by compiling the protocol with a specific compiler that checks that no known-unsafe function is used in its code. This static form of sandboxing is performed by the OCaml typechecker: we simply compile protocols in a restricted set of modules with restricted interfaces that hide any unsafe, non wanted feature.

Another goal of that specific environment is maintaining a stable OCaml API for protocol development. Imagine that at some point, the OCaml standard library changes (a function is added or removed, a type is changed), then we will be able to upgrade to the new OCaml while still remaining compatible with past protocols, by providing an adapter layer.

Environment contents#

Here is a quick description of each file in this environment, all located undersrc/lib_protocol_environment/:

• Files in the sigs/vX/ directories declare the interface that the protocols can be compiled against. These interfaces are repeats of other library interfaces with some unsafe functions removed. These interfaces are frozen and cannot be changed: changing them can break previous protocols.
  • Special cases: the files context.mli, fitness.mli, and updater.mli are interfaces that the protocol exposes to the shell (rather than the other way around).
  • All the files in sigs/vX/ are assembled into a single interface file VX.mli by a helper program located in s_packer/.
• Files in the structs/vX/ directory declare compatibility layers for old protocol environments. E.g., structs/V0/error_monad_traversors.ml contain the code of error-monad-compatible list traversors that used to be part of the Error Monad at the time of the environment V0. These implementations are meant to evolve alongside the ecosystem: when an incompatibility is introduced in a library a compatibility layer needs to be implemented or amended in order to provide a backwards compatible overlay to the protocol. These implementations are assembled into a single implementation file VX.ml by a helper program located in s_packer/.

The API can be found in tezos-protocol-environment

Environment versions#

An environment interface includes a frozen, immutable interface provided to the protocol. And so when a new protocol needs new functions, types, or values, this protocol must use a new environment. This is why the environments are versioned.

A protocol’s manifest (e.g., src/proto_alpha/lib_protocol/TEZOS_PROTOCOL) includes a field named expected_env_version. This field specifies the environment used to compile the protocol.

Protocol environments can only ever increase in version. Specifically, from within a protocol P1 built on environment version X, the activation of a protocol P2 built on environment Y fails unless X ≤ Y.

Some examples of prior environment switches can be found within past protocol changelogs:

• Edo - environment V1
• Hangzhou - environment V3
• Ithaca - environment V4
• Jakarta - environment V5
• Kathmandu - environment V6

For how to prepare and implement an environment switch, see Adding a new protocol environment.