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
fields for changing some parameters used by Cardano SL (for instance, slot
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
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
bvdScriptVersionby 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 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.
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
Updating the Mempool
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 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 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.
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).
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.
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
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.