Hardfork Procedure

Introduction

A hardfork in a blockchain is a change in which an older version of the code cannot process blocks generated by the newer version. However, the new version still has to be able to process the entire blockchain, so it needs to handle blocks generated by both versions.

In Peerplays, hardforks are defined only by their name (in most cases a number) and a timestamp. The timestamp is after a new version of the software was released, so that users have time to upgrade. Up to this timestamp, blocks are generated according to the old version, and after the timestamp the new version kicks in.

On the block processing side, the hardfork timestamps are used in the same way: If the block was generated before a certain hardfork's timestamp, the old parsing rules are used. If it was generated later, the new rules are used.

Defining a hardfork

Peerplays stores a list of hardforks and their timestamps in the libraries/chain/hardfork.d directory. To add a hardfork called myhf in the code, create a new file in that directory with the filename of myhf.hf with contents like

#ifndef HARDFORK_MYHF_TIME
#define HARDFORK_MYHF_TIME (fc::time_point_sec( 1540000000 ))
#endif

where MYHF should be replaced with the uppercase hardfork name and 1540000000 with the Unix timestamp of your desired hardfork time.

Making backwards-incompatible changes to the code

After the hardfork is defined, you can use its defined timestamp to perform runtime checks.

If the hardfork includes introducing new operations to the blockchain, all the code dealing with these operations can safely assert that the current time is later the hardfork timestamp

FC_ASSERT(...)

This includes both code for creating/manipulating such operations and for parsing/applying them.

Git Flow

Since changes requiring hardforks are by definition incompatible, they should be kept in the hardfork branch. While in this branch, the hardfork timestamp can still be edited, so that it always remains in the future. The main develop branch is then regularly merged into the hardfork branch.

If there are any pending hardforks, a release branch is made from the hardfork branch. It follows the normal rules for release branches, including merging back into both develop and hardfork once the release it made. Special care must be taken to keep the hardfork timestamp far enough in the future for the release.