Execution
Governing smart contract upgrades
An upgrade replaces the logic behind live user funds. It deserves the strictest path in your governance stack, from the wording of the proposal to the transaction hash that lands onchain.
How upgradeable contracts are governed
Most protocols use a proxy pattern where a stable address holds state and points at an implementation contract that holds logic. Governance does not rewrite code, it votes to point the proxy at a new implementation address.
That makes the upgrade a single privileged function call, usually owned by a timelock which is in turn owned by the governor contract. Whoever controls that chain of ownership controls the protocol, so mapping it precisely matters more than any individual vote.
Approve the implementation address
The proposal should name the deployed implementation and its verified source. Voting on a description of the change is not the same as voting on the change.
Include the constructor arguments, the compiler version and the verified block explorer link. Reviewers should be able to reproduce the bytecode themselves rather than trusting a summary written by the team proposing it.
Review before the timelock, not during
Audits and diffs should be attached at proposal time so the timelock is a final check rather than the first read.
Storage layout is the most common source of silent breakage. A reordered or resized variable can corrupt balances without reverting, so the diff review should explicitly confirm the layout is append-only.
Simulate the upgrade against a fork of mainnet state and publish the results. A dry run that exercises the main user flows after the swap catches far more than a code read alone.
Have a rollback ready
Keep the previous implementation address and a pre-drafted revert proposal. Recovery speed matters more than optimism.
Record the upgrade transaction hash, the block number and the new implementation address in one place. Six months later, the question is never whether the vote passed, it is which transaction actually made the change.
Upgrades are the highest stakes governance action
A parameter change adjusts behaviour inside known limits. An upgrade can replace the logic entirely, which means it can change custody, permissions and accounting in one transaction. The approval process should reflect that difference.
Require the new implementation address to be deployed, verified and published before voting opens. Approving an upgrade to an address that does not exist yet is approving a blank cheque.
A checklist before the vote closes
Confirm the audit covers the exact commit being deployed, that storage layout is compatible, that the proxy admin is the timelock rather than an individual, and that a rollback plan exists with a pre written transaction.
Rehearse the upgrade on a fork of mainnet state. Simulation catches storage collisions and permission errors that no amount of proposal discussion will surface.
Keep the execution path connected: this guide pairs well with protocol parameter change, governance attack and snapshot voting, which cover the neighbouring steps between an approved vote and a settled onchain transaction.
Key concepts explained
New to this topic? These are the core terms you will meet again and again in governance work. Understanding them makes every proposal easier to read.
- Proxy pattern
- An architecture where a stable proxy contract forwards calls to a replaceable implementation. Upgrades change the implementation while state and address stay put.
- Implementation slot
- The storage location where the proxy keeps the current implementation address. The upgrade transaction is simply a governed write to this slot.
- Storage layout
- The order of state variables in a contract. Upgrades must preserve it - a mismatch silently corrupts data, which is why upgrades demand extra review and timelock.
- Upgrade authority
- Whoever can point the proxy at new code. If a single key holds it, the DAO is one compromise away from total loss.
Frequently asked questions
- How are smart contracts upgraded through governance?
- Most protocols use a proxy pattern. Governance approves a transaction that points the proxy at a new implementation contract, and the timelock delays that switch so users can review it first.
- Can an upgrade be reversed?
- Usually yes, by pointing the proxy back at the previous implementation, but any state written by the new logic in the meantime may not be recoverable.
- Who should control the proxy admin?
- The timelock controlled by governance, never a single externally owned account. An individual key with upgrade rights is functionally a centralised protocol.