Coordinated Upgrades in Kwild
The coordinated upgrade system and hardfork definitions defined here are experimental. The system is likely to change in the future as use cases are evaluated.
kwild provides a mechanism for reducing network disruption by formally
specifying:
- The consensus-level changes, and
- The height at which the changes should go into effect.
This permits delaying the changes after a software update until a block height specified in the genesis configuration file. CometBFT uses a similar approach1 to enable certain features, including vote extensions and proposer-based time stamps (PBTS). The height-based activation system is exposed to developers to alter application logic that affects consensus.
In brief, the process of defining a coordinated backward incompatible upgrade involves:
- Specify the activation height in the
genesis.jsonfile, as described in next section. - Define changes using the extension system, which requires no modification to
the
kwildsource code. See Extension-based Changes for more. - If the changes cannot be specified by the functionality exposed by the
extension system, modify
kwildsource code to add ad-hoc conditional logic. See Canonical Changes for more. These become "canonical" upgrades. This approach is primarily intended for the core Kwil development team to coordinate updates applicable to all networks.
In the event that software updates must introduce changes that cannot leverage
these mechanisms to retain the ability to execute pre-upgrade blocks, and thus
require a new chain (new genesis with exported state), kwild also has the
ability to halt at a specified block. At this point, a new version of the node
software may start with exported state and an updated genesis configuration. See
the planned halt mechanism.