Casper v2.2.0 Release Notes
Summary
This Minor release 2.2.0 adds two new chainspec settings to address the validator proposals CVV006 and CVV008, both of which were voted on and passed through community governance.
Specifically, a new chainspec setting minimum_delegation_rate is introduced to fulfill the requirement specified in CVV006, and a new chainspec setting reward_handling is added to fulfill the requirements of CVV008.
We have added various new types to the casper-types crate in order to support these new features for new networks as well.
This release also includes a new bug fix introduced in Casper v2.0.0, which affected the genesis process of the calculation of total supply.
Lastly, changes specific to the Casper Mainnet are discussed in a dedicated section below.
Rewards Handling
One of the requirements of proposal CVV008 was to transfer a percentage of the newly minted token rewards to a purse.
The minor release 2.2.0 extends the core config section of the chainspec with an additional setting named rewards_handling. Currently, a network can be configured to be one of two settings.
Rewards Handling: Standard
This setting preserves the behavior of the pre-v2.2.0 rewards distribution. An example configuration is
rewards_handling = { type = 'standard' }Rewards Handling: Sustain
This setting for rewards handling has been introduced in the release to support the sustain purse
requirement as specified in validator proposal CVV008. When a network is configured to run in sustain
mode, a certain ratio of the newly minted reward token is transferred to a purse. An example setting
as defined in a chainspec.toml file is:
rewards_handling = { type = 'sustain', ratio = [2,8], purse_address = "uref-a0e6202f24f9fb165711ebe5ea28518b5549cfc8f9d2ad1444b40b13d2474c05-007" }The first field type defines which setting the network will run, in the above example it is sustain.
The second field ratio defines the ratio of newly minted tokens that is transferred to the sustain purse. As the ratio is inherently a percentage, any ratio where the numerator is strictly
greater than the denominator is invalid. Attempting to run a node with such a ratio will return an error.
The third field purse_address specifies the purse that receives the transferred tokens, called the sustain purse. This purse must be a pre-existing purse. The sustain purse is a regular purse, this means that unlike a staking purse, where the token is illiquid, the tokens in a sustain purse is liquid and can be transferred out.
New Global State Entries
As both the ratio and the sustain purse may change from upgrade to upgrade, it becomes necessary to record both the ratio and sustain purse to global state for any historical queries. In order to support this, we have expanded the Key space within global state to include a new stable address variant RewardsHandling. At the time of upgrade, the ratio expressed as a u64 is serialized and written to a map in global state under this new Key variant. When a network is configured to run with sustain, the sustain purse is added to the Mint system contract's named keys under the sustain_purse name. Additionally, the rewards handling setting can be toggled, this means any network that switches from one modality to the other can switch back in the following upgrade.
For pre-existing networks like the Casper Mainnet or Testnet, the sustain handling can be turned on only by staging a protocol upgrade with a chainspec that has the sustain setting with the desired ratio and purse_address parameters.
New networks that wish to set rewards_handling to sustain at genesis, can set up their chainspec as explained above. However, since the sustain purse has to be a known purse, and no purse can be known before the genesis process, the purse_address is ignored at genesis. Instead, for new networks, the accounts.toml file must contain a single entry of
[accounts.sustain]
public_key = "013e3bbc876951c66c6f41956d3c7bde9291f529954fc9f3b2e6cca0ee0335bd1f"This binds the main purse of the account linked by the public key as specified in the accounts.toml to be the sustain purse for the network.
Minimum Delegation Rate
The v2.2.0 release extends the core section of the chainspec to include a new setting minimum_delegation_rate which represents the minimum delegation rate any validator can set on that given network. This fulfills the requirements voted on by the community in CVV006.
For new networks, minimum_delegation_rate will be enforced from genesis, and any bids with rate strictly less than the minimum will fail. For pre-existing networks, all validator bids that have a delegate rate less than the minimum will not be affected during the protocol upgrade. However, any attempt to modify the validator's pre-existing stake either through add_bid or withdraw_bid will require the validator to set a delegation rate to at least the minimum. The same applies when a validator attempts to modify their reservations.
The newly added chainspec setting is written to the Auction system contract's named keys under the entry minimum_delegation_rate. minimum_delegation_rate will be set to 0 with this release, which keeps behavior inert (as mandated by the CVV006 vote). A future community vote will select a value to be set in a future network upgrade.
Recalculation of total supply
The v2.2.0 release also includes an internal change to protocol upgrade logic that recalculates the total supply of the chain by iterating over the balance records in global state upon upgrade. If the value after tallying the sum of balances differs from the value tracked by the Mint system contract, the logic will set the total supply to the sum obtained after iterating over the balance. This action is emitted as a WARN level message.
This message will always be emitted if there is a modification to balance records during a protocol upgrade with the global_state.toml
BUGFIX: Incorrect total supply tally during Genesis
The v2.2.0 release contains a modification to the protocol upgrade logic that re-calculates the total supply by iterating over the balances in the network.
Casper Mainnet
While release 2.1.2 was published in January 28th of 2026 and promoted to Testnet, this version of the protocol was never applied to Mainnet. However with the application of the v2.2.0 binary as part of the v2.2.0 protocol upgrade, the Casper mainnet will also receive the following changes that were applied to other networks.
Additionally, in compliance with the Mainnet community's mandate dictated in CVV008, the application of this protocol version will also include a one time token issuance via a global_state.toml file.
Change to the behavior of withdraw bid
The release includes a change to the behavior of withdraw_bid. Historically, when a validator would attempt to reduce their bid by an amount larger than their staked amount, the system would return an error. Post v2.0.0, the behavior was changed to trigger an unbonding instead of returning an error. This release restores the behavior of withdraw_bid to returning an error if a validator reduces their bid by an amount exceeding their staked amount. Additionally to further reduce unintentional unbondings as a result of validator error, the minimum_bid_amount threshold has been reduced to 500 CSPR as part of the protocol upgrade, matching the minimum delegation amount for delegators in the current chainspec.
BUGFIX: Prevent delegator from exceeding delegation limits set by their validator
V2.1.2 also contained a bug fix that prevented delegators from being able to exceed the limits of their delegation as set by their validator. In the previous binary versions, when a delegator would stake their tokens, the system would only compare the amount sent as part of the delegation, and not the amount they may have previously staked. As a result, a delegator could exceed the validator-set maximum by sending multiple delegations that when summed, exceeded the maximum, even when individually none of them did. In this release, the system considers the sum of any previously staked tokens and the current amount. If the final delegated amount does not lie between the limits as set by the validator, an error is thrown. When the protocol version containing this fix is applied, any delegators that then fall under the minimum will be unbonded. Conversely, any delegations that exceed the maximum will be partially unbonded to reduce their delegated amount to the maximum limit.
One time issuance
As required by CVV008, when v2.2.0 gets activated on Mainnet, a one-time-issuance will be applied whereby new token equivalent to maximally 33% of the supply at the time of the upgrade will be minted to a designated purse as defined by the global_state.toml that is included with the upgrade package. On other networks, a global_state.toml may be included for testing purposes.