Introduction

Diem Payment Network ("DPN") is a blockchain-backed payment platform and an infrastructure for stablecoins. Diem Networks ("DN") is a whole subsidiary of the Diem Association. DN is in the process of applying for an DPN payment system license from the Swiss Financial Market Supervisory Authority ("FINMA"). Once granted, DN will be responsible for ensuring that DPN operates in compliance with the payment system license from FINMA.

Diem Upgrade Management is a set of protocols to reconfigure the DPN blockchain. With respect to time-sensitive decisions and incident response, these protocols provide the Diem Networks with the technical means to effectively and transparently update DPN in response to critical incidents or to make time-sensitive decisions necessitated by law or for compliance reasons (“Critical Upgrades”).

Building blocks

Conceptually, the software running on validator nodes comprises two layers. One is a blockchain core whose goal is to replicate a ledger of transactions and their outcome. The second is a framework that stores the ledger-state and a set of software modules -- encoded in the Move programming language -- that define the rules for interacting with the DPN and mutating the ledge-state (see also Diem Improvement Proposal("DIP")-2). There are two corresponding types of upgrades to the system, (i) updates to the core software (ii) updates to the framework state. Both layers may be used for non-Critical Upgrades and for Critical Upgrades.

Software upgrade

Specification changes to DPN go through the DIP process. Non-specification changes (e.g. bug fixes and performance improvements) are implemented by DN without going through the DIP process. All software changes (both specification changes and non-specification changes) are submitted through standard Github reviews and proceed through the code review process before being merged to the master.

In order to release a new version of the DPN software, DN will coordinate the release plan and timeline with all the validator operators. Validator operators are responsible for deploying the software release as per the instructions provided by DN.

Some changes may require all validators to transition at the same blockchain height, which is implemented by an on-chain state update.

On-chain state upgrade

The on-chain state can only be updated via transactions that are submitted to DPN and validated. There are three ways to effectuate changes to the DPN by directly mutating the on-chain state, ordered by most likely to occur to least likely to occur: normal multi-sig transactions, multi-sig WriteSet transactions, and waypoint transactions.

Normal multi-sig transactions

Normal transactions go through the DPN Virtual Machine and invoke Diem Framework modules (see DIP-2) to produce a Writeset that alters the ledger-state. Both the resulting state change and the authenticating set of signatures are transparent and visible on-chain.

Multi-sig WriteSet transactions

Writeset transactions are a special type of multi-sig transactions that prescribes an arbitrary state change. Unlike normal transactions, which must follow specified Diem Framework rules, WriteSet transactions simply describe a state change rather than go through the Diem Framework modules. This type of transaction is only needed for situations such as updating immutable stdlib libraries due to critical bugs or reversing systematic fraudulent transactions.

The use of WriteSet transactions follows the spirit of transparency — WriteSet transactions allow an arbitrary change to the state of the blockchain without altering the history of past transactions. Even though WriteSet transactions prescribe an arbitrary state change, they are authenticated with the same multi-sig mechanism as normal transactions which means both the change and multi-sig are transparent and visible on-chain.

Waypoint transactions

Waypoint encapsulates a specific snapshot of the Diem blockchain and is used to authenticate the blockchain when validator signatures are not applicable, e.g. the genesis. (See this for more details) Waypoint transactions can be either normal or WriteSet transactions but without typical corresponding signatures. As the name suggests, the process of applying such a transaction will need a waypoint for authentication, similar to how the first genesis transaction works. The waypoint transaction applies on top of a specific snapshot of a Diem blockchain (might be empty). DN is responsible for picking the appropriate snapshot and building the waypoint transactions and calculating the waypoint. Users of Diem, including validators, use the waypoint to authenticate the blockchain. If a validator fails to acquire the correct waypoint transaction, it will vote on an irrelevant blockchain, but not otherwise impact the system. If a user of the system such as a full node or blockchain observer acquires the incorrect waypoint transaction, they will see an incorrect state.

Note that, after DPN launches, DN could use waypoint transactions as a last resort for extremely unlikely catastrophic scenarios such as losing more than a third of the validators.

The decision flow chart below summarizes the building blocks and how they will be used.

Case study

Network specification upgrade

Example: Changing the wire protocol in a backward compatible way.

Category: Spec change => Software upgrade

On-chain config update

Example: Adding new validators to the system.

Category: On-chain state change => Multi-sig transaction

VM upgrade

Example: New bytecode added.

Category: Spec change + require coordination => Software upgrade + Multi-sig transaction

Consensus protocol upgrade

Example: Switching consensus algorithm from DiemBFTv3 to DiemBFTv4.

Category: Spec change + require coordination => Software upgrade + Multi-sig transaction

Signature scheme change

Example: Switching consensus signature scheme from EdDSA to BLS.

Category: Spec change + require coordination => Software upgrade + Multi-sig transaction

Smart contract vulnerability fix/Diem Framework upgrade

Example: DAO hack

Category: On-chain state change + SmartContract incapable => Multi-sig WriteSet transaction

Large fraud

Example: Hackers mint billions of Diem.

Category: On-chain state change + SmartContract incapable => Multi-sig WriteSet transaction

Quorum Loss

Example: F+1 validators fail across multiple fault isolation zones and will not be able to recover within any reasonable time period.

Category: State change and consensus is dead. => Waypoint transaction