Skip to content

Commit 3a63463

Browse files
committed
docs: add governance-awareness warning to GetSystemContractsTransition
Warn that contract params may have been modified by governance proposals before a hardfork upgrade, and that upgrade authors must query on-chain state to avoid silently overwriting governance-approved values.
1 parent 7554718 commit 3a63463

File tree

1 file changed

+15
-0
lines changed

1 file changed

+15
-0
lines changed

systemcontracts/systemcontracts.go

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,21 @@ func checkSystemContractVersions(systemContracts *params.SystemContracts) error
7474
// and they set up the required storage layout (owner, quorum, members, etc.).
7575
// Starting with any other version will skip initialization, leaving the contract in an
7676
// uninitialized state with empty storage — which will cause runtime failures.
77+
//
78+
// WARNING — Upgrade Params and on-chain governance:
79+
// Contract parameters (e.g., quorum, owner, fee rates) can be modified at runtime
80+
// through governance proposals BEFORE a hardfork upgrade is applied. The upgrade*()
81+
// functions write ONLY the Params keys specified in the hardfork config, overwriting
82+
// the corresponding storage slots unconditionally. If a governance proposal has already
83+
// changed a value that the upgrade also sets, the governance-approved value will be
84+
// silently replaced by the hardfork value.
85+
//
86+
// Therefore, when defining Params for an upgrade, you MUST:
87+
// 1. Query the current on-chain state to identify governance-modified values.
88+
// 2. Decide for each Params key whether the hardfork value should override
89+
// the governance-approved value, or whether it should be omitted (nil)
90+
// to preserve the on-chain state.
91+
// 3. Only include Params keys that genuinely need to change for the upgrade.
7792
func GetSystemContractsTransition(systemContracts *params.SystemContracts, alloc *types.GenesisAlloc) (*params.StateTransition, error) {
7893
st := &params.StateTransition{}
7994

0 commit comments

Comments
 (0)