用途:帮助在 Starknet 上编写可升级的 Cairo 智能合约,使用 OpenZeppelin Contracts for Cairo 提供的 UpgradeableComponent 封装 replace_class_syscall。
主要能力:集成升级组件并配合访问控制组件(如 OwnableComponent),在存储与事件中用 #[substorage(v0)] 和 #[flat] 添加,暴露受权限保护的 upgrade 函数调用组件内部升级方法;组件在替换类哈希时发出 Upgraded 事件并拒绝零类哈希。另有 IUpgradeAndCall 接口变体,可在新类上下文中附带函数调用,用于升级后迁移或重新初始化。
使用方式:Starknet 将合约实例与类分离,升级即把合约的类哈希指向新类,合约地址、存储与 nonce 不变,新类须预先在链上声明。必须在外部 upgrade 函数加访问控制检查(如 self.ownable.assert_only_owner()),否则任何人可替换合约代码。可选单所有者、基于角色的 AccessControl/RBAC,多签或治理等模式。
限制与安全:组件本身不含访问控制。存储兼容性风险高——不得重命名、删除或改变既有存储变量类型,新增变量安全;组件存储按 #[substorage(v0)] 展平,建议变量名加组件前缀避免冲突。Cairo 存储槽由变量名经 sn_keccak 派生,命名比顺序更关键。OpenZeppelin 版本升级遵循语义化版本,补丁与小版本保持存储布局,主版本可能破坏布局,切勿在主版本间直接升级线上合约而不审阅变更日志。Cairo 无自动化存储布局校验,应先用本地 devnet(starknet-devnet-rs 或 Katana)部署 V1 与 V2,写入状态后升级并验证读取、新功能、访问控制与 API 兼容性,可用 npx @openzeppelin/contracts-cli 查看当前集成模式。具体命令与代码示例暂未提供。