Implementation Overview

Implementation of the update system can be found in the Pos.Update family of modules. The general approach to implementation is the same as in other subsystems of CSL, such as Txp, Ssc and Delegation. The update system has the global state, stored in the database. The global state can be unambiguously derived from the information that is in the blockchain. The local state, sometimes referred to as “mempool”, is stored in the memory. The mempool is used for data transfer and inclusion of transferred data into blocks. The network protocol (built with standard Inv/Req/Data pattern) is described in Application-level document with the binary protocol described in Binary protocols document.

Currently, everything is done to add hard fork functionality via software update and then perform a hard fork as described in research section; soft forks (or software updates) are fully implemented.

Fields Updatable with a Soft Fork

An UpdateProposal contains fields for changing some parameters used by Cardano SL (for instance, slot duration). Specifically, upBlockVersion is used to signify that a proposal performs such changes; if upBlockVersion is greater than the last used block version, the changes from upBlockVersionData will be applied.

upBlockVersionData has the type BlockVersionData. Its fields are described below:

  • bvdScriptVersion – a script language version used to validate script transactions. If the proposal increases upBlockVersion, it must also increase bvdScriptVersion by 1 (and can’t leave it unchanged).

  • bvdSlotDuration – slot duration (in milliseconds).

  • bvdMaxBlockSize – block size limit (in bytes). A proposal can’t increase the block size limit more than twofold compared to the previous limit.

The checks described above are made in verifyNextBVData.

In addition, there are some fields that are unused right now, but will be used in the future. Their meaning is briefly described below:

  • bvdMaxTxSize – transaction size limit (in bytes).

  • bvdMpcThd – eligibility threshold for MPC.

  • bvdHeavyDelThd – threshold for heavyweight delegation.

  • bvdUpdateVoteThd – portion of total stake necessary to vote for or against an update.

  • bvdUpdateProposalThd – number of slots after which an update is implicitly approved (unless it has more negative votes than positive).

  • bvdUpdateImplicit – number of slots after which an update is implicitly approved (unless it has more negative votes than positive).

  • bvdUpdateSoftforkThd – portion of total stake such that if total stake of issuers of blocks with some block version is bigger than this portion, this block version is adopted.

Proposal Accumulation

Proposals are stored in a mempool or gathered from the blockchain in order to figure out which proposal is adopted, and whether or not the current node has to participate in voting. No matter whether a change in proposal state comes from the network/mempool, or from loading the blockchain, it is stored in the PollModifier data structure and applied appropriately.

Updating the Mempool

As nodes deserialize payloads of update system messages, they modify mempool as implemented here.

Interaction With the Database

In order to verify update system data, we have to get this data from the global state (database). To provide such interface, a well-documented set of typeclasses is presented. It is important that their implementation relies on functions found in Pos.DB.GState.Update.

Core Types

Core types are mentioned in the Binary protocols document. Those types reflect the concepts from the research section in a straightforward way. Please refer to the core types module for more information.

Update Proposal Adoption

A very important part of implementation of the update mechanism is the part that works with genesis blocks for epochs and applies updates. This logic resides in this well-documented function. We explain terminology related to this process below.

softforkResolutionThreshold Predicate

softforkResolutionThreshold is a predicate (referred to as “threshold” in the code) which, for an update proposal with version v, says that it is a version of software ran by the network.

Acceptable Proposal

A proposal is called “acceptable” if the following conditions are met:

  • It is correctly formed, including necessary cryptographic signatures.
  • Its version is greater or equal to the currently adopted proposal (see below).

Confirmed Proposal

An acceptable proposal is called “confirmed” if it was voted for by the majority of stake, but softforkResolutionThreshold predicate isn’t yet true for it.

Adopted Proposal

A confirmed proposal is said to be “adopted” if its softforkResolutionThreshold predicate is true for it. For each blockchain state, there is exactly one adopted version. Blocks are checked taking into consideration the currently adopted version.

Download New Version

In the Pos.Update.Download module, the following algorithms are implemented. Downloaded updates are applied using a tool called launcher

Download Confirmed Update

To download a confirmed update, we extract the update hash from ConfirmedProposalState. We extract it depending on whether or not we’re using an installer on given platform. If the update hash is extracted successfully, the “Download Update by Hash” algorithm to download and save the confirmed update is invoked.

Download Update by Hash

To download an update by hash, we loop through known update servers trying to download the update with given hash using httpLBS from HTTP. Simple. In the end, we will either have the update completely downloaded or server list exhausted and an error reported.