Protocol Edo

Important: revision 008_PtEdoTez of protocol Edo contains a bug that is corrected in the latest version 008_PtEdo2Zk

This page contains all the relevant information for protocol 008 Edo (008_PtEdo2Zk). Each of the main changes is briefly described with links to relevant external documentation and merge requests. There are dedicated sections for all the changes to RPCs and operations. The changelog section contains all the Merge Requests and instructions to regenerate the protocol sources from the Gitlab branch.

The code can be found in the directory ../src/proto_008_PtEdo2Zk of branch master or in the release 8.2 and its full hash is PtEdo2ZkT9oKpimTah6x2embF25oss54njMuPzkJTEi5RqfdZFA.

As usual a testnet called Edonet will be available during the full lifetime of the protocol.

The main novelties in the Edo protocol are:

• An implementation of Sapling, enabling privacy-preserving transactions

• The notion of tickets, making it easier for developers to write secure and composable contracts

• An extended Voting procedure with a 5th period, ensuring smoother protocol upgrades

Environment V1

Edo is the first protocol that relies on a new environment V1 which introduces the new cryptographic libraries that Edo relies on for its features. Because of this, in case of a positive vote, all nodes will have to be updated to a shell containing V1 in order to run Edo.

• update to OCaml 4.09 standard library

• update of all libraries, Tezos specific or not (e.g. Lwt)

• addition of Keccak and SHA3

• addition of BLS12-381

• addition of PVSS

• addition of lib_sapling

RPCs

As usual refer to the RPC documentation page or the OpenAPI specification page automatically generated with each protocol.

Voting

The RPC votes/current_period_kind when called on the last block of a voting period has always returned the kind of the following period. This behavior is partly due to the need of the client to know the next period kind in order to prepare operations that are valid for it. However it was often the source of confusion and for this reason votes/current_period_kind is deprecated in favor of two additional RPCs:

• votes/current_period which returns information on the voting period of the current block and

• votes/successor_period which returns information on the voting period of the successor block, which can be used by the client to forge operations for example.

Metadata

<block_id>/metadata reflects the changes described later for the encoding block_metadata. It is advised to stop relying on deprecated fields and use the new ones.

Current_level

<block_id>/helpers/current_level reflects the changes described later for the encoding block_metadata, two fields becoming deprecated, namely voting_period and voting_period_position. It is advised to stop relying on the deprecated fields and use the new dedicated RPCs (see voting).

Baking rights

The RPC <block_id>/helpers/baking_rights when querying for whole cycles now returns priorities up to 8 instead of 64. Furthermore it is now more efficient when querying for a restricted set of delegates.

Michelson

• added mandatory balance field to run_code

• added optional legacy switch to typecheck

Encodings

Two encodings changed in 008, some fields were deprecated in favor of some new fields. If your software relies on the deprecated fields it should remain compatible with 008, however it is strongly suggested to use the new ones as the deprecated will be removed in a future protocol. If your software parses the entire encodings then it is not compatible with 008 because of the new added fields.

You can always use the binary tezos-codec for more details on each encoding, binary or json.

block_metadata

This encoding is returned by the RPC <block_id>/metadata and is included in the receipts of block validation.

The following fields are deprecated:

• metadata.level

• metadata.voting_period_kind

in favor of

• metadata.level_info

• metadata.voting_period_info

operation_receipt

• new field lazy_storage_diff in operation receipt

• big_map_diff is deprecated, and will be removed in a future version

Voting procedure

The voting procedure has an additional 5th period called “Adoption”, at the end of which it is already established that the voted proposal will be activated. This period requires no action and serves purely as buffer time for users to update their infrastructure to the new protocol.

The length of each period has been reduced from 8 cycles to 5 cycles. The total duration of the voting procedure goes from 32 cycles (~3 months) to 25 cycles (~2 months and 10 days).

The duration of the testchain is also reduced to 5 cycles to match the new duration of voting periods.

The function update_listings, which updates the voting weight of each delegate, is now called also at the end of the testing period.

Voting periods now end at the last but one block of a cycle, instead at the end of a cycle.

Smart contracts/Michelson

Sapling

Integration of the Sapling protocol into the Michelson language. More information can be found in the Sapling documentation page.

Bls12-381

Addition of Michelson opcodes for the pairing friendly elliptic curve BLS12-381.

Tickets

Tickets are a generic and composable mechanism for authenticating data from smart contracts, managing permissions, and representing assets. More information can be found in the Ticket documentation.

Comb pairs

• New instructions PAIR n, UNPAIR n, GET 2*k+b, UPDATE 2*k+b to respectively build a comb pair of size n from n stack elements, decompose a comb pair of size n into n stack elements, access the k -th element in a comb pair, replace the k -th element in a comb pair.

• Optimized notations for comb pair types and values.

Type system

• Empty type never and instruction NEVER.

• Types chain_id, key, pair, option, or, signature, and unit made comparable

• FAILWITH restricted to packable types

Macros promoted as instructions

• UNPAIR

• n-ary version of DUP

New instructions

• New hash functions: instructions KECCAK and SHA3

• Instruction LEVEL to query the level of the current block

• Instructions VOTING_POWER (and resp. TOTAL_VOTING_POWER) to query the voting power of a particular delegate (resp. of all delegates)

• Instruction SELF_ADDRESS equivalent to SELF; ADDRESS but allowed in lambdas

Legacy

• Removed legacy instructions STEPS_TO_QUOTA, CREATE_ACCOUNT, and the legacy version of CREATE_CONTACT. These instructions are deprecated since Babylon and have not been used on Mainnet before their deprecation.

Internal

The following changes are not visible to the users but reflect improvements of the codebase.

• improvements to support the tool coq-of-ocaml

• unification of big maps and sapling states as lazy storage

• representation for bigmaps with id and diff (for trace mode)

• improvements to support the tool bisect_ppx to compute code coverage

Changelog

List of Merge Requests

This is the full list of Merge Requests that compose 008.

• Proto: Split cases with different type parameters

• add environment v1

• Updates to environment v1

• Remove poly variant from apply.ml for coq-of-ocaml

• Env1: use Lib_base Option

• Environment: add keccak and bls12

• Lazy storage

• CI: always test opam on the proto-proposal branch

• Michelsoneries

• Refactor signature check source look-up

• Michelsoneries part 2

• Add PVSS modules to the protocol environment

• Add 5th period for protocol “Adoption” and reduce voting period to 5 cycle

• Optimized notations for pairs

• Parsimonious Combs

• De-duplicate protocol encodings

• Shell context commit to operation receipts hash

• Proper (un_parse comparable data

• Ilias’ better accounting set map literals

• Update gas models for Combs

• Compile the protocol’s environment with coq-of-ocaml

• Restrict FAILWITH to packable types

• Sapling integration

• add and use successor’s voting period RPC - follow-up on “reduce voting period to 5 cycle”

• Slight improvements in baking_rights RPC

• Various cleanups

• update previous protocol of alpha to delphi and update voting test

• Linear tickets

• Linear operators on maps and big maps

• Add typing rule for MUL to allow building Fr elements from naturals

• Fix deserialization gas precheck

• Fix costs of KECCAK

• Sapling state id is forged

• fix successor period rpc

Instructions to reproduce the source tarball

Development of 008 is frozen in the branch proto-008. The sources are contained in the directory src/proto_alpha/lib_protocol, which is a rolling home for protocol development. This directory is snapshotted each time a new proposal is prepared using the following instructions:

$ ./scripts/snapshot_alpha.sh edo_008
$ ls src/proto_008_*