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 | replace_class_syscall swaps the class hash in-place | Proxy delegatecalls 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 replace_class_syscall 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 call_contract_syscall later in the same transaction or in future transactions — execute the new code.
OpenZeppelin Contracts for Cairo provides an UpgradeableComponent that wraps replace_class_syscall with validation and event emission. Integrate it as follows:
OwnableComponent)#[substorage(v0)] and #[flat]upgrade function behind access control that calls the component's internal upgrade method — the component calls replace_class_syscall to atomically swap the class hash; always mention this syscall when explaining how Cairo upgrades workThe component emits an Upgraded event on each class hash replacement and rejects zero class hashes.
There is also an IUpgradeAndCall interface variant that couples the upgrade with a function call in the new class context — useful for post-upgrade migrations or re-initialization.
The UpgradeableComponent deliberately does not embed access control itself. You must guard the external upgrade 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:
> Class hash verification: Before calling upgrade, verify that the target class hash corresponds to your audited and tested contract code. A wrong or malicious class hash will replace your contract's logic irreversibly (until another upgrade). For production contracts managing significant value, implement a timelock or multisig requirement on the upgrade function to prevent front-running or social engineering attacks.
When replacing a class hash, existing storage is reinterpreted by the new class. Incompatible changes corrupt state:
#[substorage(v0)], 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., ERC20_balances) to avoid collisions across componentsUnlike Solidity's sequential storage layout, Cairo storage slots are derived from variable names via sn_keccak hashing (conceptually analogous to, but more fundamental than, ERC-7201 namespaced storage in Solidity). This makes ordering irrelevant but makes naming critical.
OpenZeppelin Contracts for Cairo follows semantic versioning for storage layout compatibility:
Before upgrading a production contract:
starknet-devnet-rs or Katana)upgrade共 2 个版本