upgrade-cairo-contracts

To upgrade Cairo contracts on Starknet without changing the deployed address, use the replace_class_syscall to atomically replace the contract's class hash. This applies new code while preserving the original contract address and on-chain storage.

Starknet class-based upgrades use replace_class_syscall semantics to swap class hashes directly, contrasting with EVM proxy patterns that delegate calls. This model enables atomic class replacements while preserving contract addresses and storage layout.

To integrate OpenZeppelin's UpgradeableComponent for Cairo contract upgrades, add the component to your contract, emit Upgraded events upon execution, and use IUpgradeAndCall for any required post-upgrade initialization steps.

To prevent unauthorized upgrades and storage corruption during Starknet contract upgrades, guard upgrade entry points with Ownable or RBAC access-control. Additionally, follow storage compatibility rules and run devnet-based upgrade testing checklists.

Yes, you can use devnet to test storage compatibility before upgrading a production Cairo contract. Run devnet migrations to declare the new class, verify storage reads, and ensure the upgrade plan preserves storage layout safely.

The step-by-step process to safely replace a contract class hash on Starknet involves declaring the new class, running devnet migrations, verifying storage compatibility, restricting the upgrade call to authorized signers, and emitting Upgraded events.