这篇文章详细介绍了如何在 Starknet 上使用 OpenZeppelin 的 UpgradeableComponent 升级 Cairo 智能合约。它阐述了 Starknet 独特的基于类的升级模型，与 EVM 代理模式进行了对比，并强调了存储兼容性、访问控制和升级路径测试的重要性。
Cairo 升级
目录
Starknet 升级模型
Starknet 将 合约实例 与 合约类 分开。一个类是编译后的程序（通过其类哈希识别）；一个合约是指向一个类的已部署实例。多个合约可以共享同一个类。
升级合约意味着 替换其类哈希，使其指向一个新的类。合约保留其地址、存储和 nonce — 只有代码发生变化。这与 EVM 代理模式有着根本区别：
|
Starknet |
EVM（代理模式） |
| 机制 |
replace_class_syscall 就地交换类哈希 |
代理通过 delegatecall 调用独立的实现合约 |
| 是否需要代理合约 |
否 — 合约自行升级 |
是 — 代理位于实现合约之前 |
| 存储位置 |
直接属于合约 |
存在于代理中，通过 delegatecall 访问 |
| 回退路由 |
不适用 — Cairo 中没有回退/包罗一切的机制 |
代理通过回退函数转发所有调用 |
replace_class_syscall 是一个原生的 Starknet 系统调用。调用时，它原子性地将调用合约的类哈希替换为提供的新哈希。新的类必须已经声明在链上。系统调用后，当前执行帧会继续使用旧代码，但之后对合约的调用——无论是通过同一交易中稍后的 call_contract_syscall 还是未来交易中的调用——都将执行新代码。
使用 OpenZeppelin 可升级组件
OpenZeppelin Contracts for Cairo 提供了一个 UpgradeableComponent，它封装了 replace_class_syscall 并添加了验证和事件触发功能。集成方式如下：
- 声明组件，同时声明一个访问控制组件（例如，
OwnableComponent）
- 使用
#[substorage(v0)] 和 #[flat] 将两者添加到存储和事件中
- 公开一个
upgrade 函数，该函数由访问控制保护，并调用组件的内部 upgrade 方法 — 该组件会调用 replace_class_syscall 原子地交换类哈希；在解释 Cairo 升级如何工作时，务必提及此系统调用
- 在构造函数中初始化访问控制
该组件在每次类哈希替换时会触发一个 Upgraded 事件，并拒绝零类哈希。
还有一个 IUpgradeAndCall 接口变体，它将升级与新类上下文中的函数调用结合起来——这对于升级后的迁移或重新初始化很有用。
访问控制
UpgradeableComponent 刻意地不嵌入访问控制功能。你必须使用自己的检查（例如，self.ownable.assert_only_owner()）来保护外部 upgrade 函数。忘记这一点将允许任何人替换你的合约代码。
常见的访问控制选项：
- Ownable — 单一所有者，最简单的模式
- AccessControl / RBAC — 基于角色的，更精细的粒度
- 多重签名或治理 — 用于管理重大价值的生产合约
升级安全性
存储兼容性
替换类哈希时，现有存储将由新类重新解释。不兼容的更改会破坏状态：
- 不要重命名或删除 现有存储变量 — 槽位是根据变量名派生的，因此重命名会导致旧数据无法访问
- 不要改变 现有存储变量的类型
- 添加 新的存储变量是安全的
- 组件存储 使用
#[substorage(v0)]，它将组件槽位扁平化到合约的存储空间中，没有自动命名空间 — 请遵循用组件名称作为存储变量名前缀的约定（例如，ERC20_balances），以避免组件之间的冲突
与 Solidity 的顺序存储布局不同，Cairo 存储槽位是通过 sn_keccak 哈希从变量名派生出来的（概念上类似于 Solidity 中的 ERC-7201 命名空间存储，但更基础）。这使得顺序变得不重要，但命名变得至关重要。
OpenZeppelin 版本升级
OpenZeppelin Contracts for Cairo 遵循语义版本控制，以确保存储布局兼容性：
- 补丁 更新始终保留存储布局
- 次要 更新保留存储布局（从 v1.0.0 开始）
- 主要 更新可能会破坏存储布局 — 在未审查更新日志的情况下，切勿跨主要版本升级正在运行的合约
测试升级路径
在升级生产合约之前：
- [ ] 在本地 devnet 中部署 V1 和 V2 类（例如，
starknet-devnet-rs 或 Katana）
- [ ] 使用 V1 写入状态，升级到 V2，并验证所有现有状态读取正确
- [ ] 验证升级后新功能按预期工作
- [ ] 确认访问控制 — 只有授权调用者才能调用
upgrade
- [ ] 检查 API 兼容性 — 更改的外部函数签名会破坏现有的调用者和集成
- [ ] 审查存储更改 — 确保现有变量没有重命名、删除或类型更改
- [ ] 手动审查 — Cairo 没有自动化的存储布局验证；使用 MCP 合约生成器来发现当前的集成模式并依赖 devnet 测试
