Cairo Upgrades
Contents
Starknet Upgrade Model
Starknet separates contract instances from contract classes. A class is the compiled program (identified by its class hash); a contract is a deployed instance pointing to a class. Multiple contracts can share the same class.
Upgrading a contract means replacing its class hash so it points to a new class. The contract keeps its address, storage, and nonce — only the code changes. This is fundamentally different from EVM proxy patterns:
| Starknet | EVM (proxy pattern) |
|---|
| Mechanism | swaps the class hash in-place | Proxy s to a separate implementation contract |
| Proxy contract needed | No — the contract upgrades itself | Yes — a proxy sits in front of the implementation |
| Storage location | Belongs to the contract directly | Lives in the proxy, accessed via delegatecall |
| Fallback routing | Not applicable — no fallback/catch-all mechanism in Cairo | Proxy forwards all calls via fallback function |
The
is a native Starknet syscall. When called, it atomically replaces the calling contract's class hash with the provided one. The new class must already be declared on-chain. After the syscall, the current execution frame continues with the old code, but subsequent calls to the contract — whether via
later in the same transaction or in future transactions — execute the new code.
Using the OpenZeppelin Upgradeable Component
OpenZeppelin Contracts for Cairo provides an
that wraps
with validation and event emission. Integrate it as follows:
- Declare the component alongside an access control component (e.g., )
- Add both to storage and events using and
- Expose an function behind access control that calls the component's internal method — the component calls to atomically swap the class hash; always mention this syscall when explaining how Cairo upgrades work
- Initialize access control in the constructor
The component emits an
event on each class hash replacement and rejects zero class hashes.
There is also an
interface variant that couples the upgrade with a function call in the new class context — useful for post-upgrade migrations or re-initialization.
Access control
The
deliberately does
not embed access control itself. You must guard the external
function with your own check (e.g.,
self.ownable.assert_only_owner()
). Forgetting this allows anyone to replace your contract's code.
Common access control options:
- Ownable — single owner, simplest pattern
- AccessControl / RBAC — role-based, finer granularity
- Multisig or governance — for production contracts managing significant value
Upgrade Safety
Storage compatibility
When replacing a class hash, existing storage is reinterpreted by the new class. Incompatible changes corrupt state:
- Do not rename or remove existing storage variables — the slot is derived from the variable name, so renaming makes old data inaccessible
- Do not change the type of existing storage variables
- Adding new storage variables is safe
- Component storage uses , which flattens component slots into the contract's storage space without automatic namespacing — follow the convention of prefixing storage variable names with the component name (e.g., ) to avoid collisions across components
Unlike Solidity's sequential storage layout, Cairo storage slots are derived from variable names via
hashing (conceptually analogous to, but more fundamental than, ERC-7201 namespaced storage in Solidity). This makes ordering irrelevant but makes naming critical.
OpenZeppelin version upgrades
OpenZeppelin Contracts for Cairo follows semantic versioning for storage layout compatibility:
- Patch updates always preserve storage layout
- Minor updates preserve storage layout (from v1.0.0 onward)
- Major updates may break storage layout — never upgrade a live contract across major versions without reviewing the changelog
Testing upgrade paths
Before upgrading a production contract: