Stylus 升级机制

目录

• Stylus 升级模型
• 代理模式
• 访问控制
• 升级安全性

Stylus 升级模型

Stylus 合约以 WebAssembly（WASM）程序形式运行在 Arbitrum 上，与 EVM 并行执行。它们共享 Solidity 合约所使用的相同状态默克尔树（state trie）、存储模型和账户系统。正因如此，EVM 代理模式对 Stylus 完全适用——Solidity 编写的代理合约可委托调用 Stylus 实现，反之亦然。

现有 Solidity 合约可通过代理模式升级为 Stylus（Rust）实现。#[storage] 宏将字段布局方式与 Solidity 完全一致地映射至 EVM 状态默克尔树中，因此只要类型定义匹配，存储槽位即可对齐。

代理模式

OpenZeppelin Contracts for Stylus 提供了三种代理模式：

注意：当前 OpenZeppelin Contracts for Stylus 未提供透明代理（Transparent Proxy）模式。请改用 UUPS 模式（推荐用于大多数项目）。

UUPS

实现合约需在其 #[storage] 结构体中组合 UUPSUpgradeable（同时集成访问控制，例如 Ownable）。集成步骤如下：

1. 将 UUPSUpgradeable（及访问控制模块）作为字段添加至 #[storage] 结构体中
2. 在构造函数中调用 self.uups.constructor() 并完成访问控制模块的初始化
3. 暴露 initialize 函数，内部调用 self.uups.set_version() —— 此函数需在部署后通过代理合约调用
4. 实现 IUUPSUpgradeable 接口：由访问控制保护的 upgrade_to_and_call，以及将调用委托给 self.uups 的 upgrade_interface_version
5. 实现 IErc1822Proxiable 接口：将 proxiable_uuid 调用委托给 self.uups

代理合约是一个轻量级的 Erc1967Proxy，其构造函数接收实现合约地址与初始化数据；并配备一个 #[fallback] 处理器，将全部调用委托转发。

部署代理合约时，应将 set_version 作为初始化调用数据传入。可使用 cargo stylus deploy 或部署合约完成该操作。初始化数据为 ABI 编码后的 setVersion 调用：

let data = MyContractAbi::setVersionCall {}.abi_encode();
// 部署时，将 `data` 作为代理合约构造函数的第二个参数传入。

Beacon

多个 BeaconProxy 合约均指向同一个 UpgradeableBeacon，后者负责存储当前实现合约地址。更新 Beacon 即可在单笔交易中同步升级所有关联代理。

上下文检测（Stylus 特有）

Stylus 不支持 immutable 关键字。不同于 Solidity 中将 __self = address(this) 作为 immutable 存储的方式，UUPSUpgradeable 使用一个位于唯一存储槽位的布尔型 logic_flag：

• 实现合约的 构造函数 在自身存储中设置 logic_flag = true。
• 当代码通过代理（delegatecall）执行时，代理合约的存储中不包含该标志，故读取值为 false。
• only_proxy() 通过检查该标志，确保升级函数仅能经由代理调用，而不可直接在实现合约上调用。

only_proxy() 还会验证 ERC-1967 实现地址槽位非零，且代理中存储的版本号与实现合约的 VERSION_NUMBER 一致。

示例：详见 rust-contracts-stylus 仓库的 examples/ 目录，其中提供了 UUPS、Beacon 及相关模式的完整可运行集成示例。

访问控制

升级函数必须受访问控制保护。OpenZeppelin 的 Stylus 合约并未将访问控制逻辑嵌入升级逻辑本身 —— 你必须在 upgrade_to_and_call 中显式添加：

fn upgrade_to_and_call(&mut self, new_implementation: Address, data: Bytes) -> Result<(), Vec> {
    self.ownable.only_owner()?; // 或任意其他访问控制检查
    self.uups.upgrade_to_and_call(new_implementation, data)?;
    Ok(())
}

常用选项包括：

• Ownable —— 单所有者，最简模式
• AccessControl / RBAC —— 基于角色，粒度更细
• 多重签名或治理合约 —— 适用于管理高价值资产的生产环境合约

升级安全性

存储兼容性

Stylus 的 #[storage] 字段在 EVM 状态默克尔树中的布局方式与 Solidity 完全一致。升级时须遵循相同的存储布局规则：

• 切勿重排、删除或更改已有存储字段的类型
• 切勿在已有字段前插入新字段
• 仅可在结构体末尾追加新字段
• ERC-1967 代理合约的存储槽位位于高位且已标准化，不会与实现合约的存储发生冲突

与 Solidity 的一项差异在于：Stylus 中 #[storage] 内嵌结构体（例如将 Erc20、Ownable、UUPSUpgradeable 作为字段组合）的布局方式是每个嵌套结构体从各自确定性的槽位开始。这与 Solidity 中常规结构体嵌套一致，但不同于 Solidity 基于继承的扁平化布局（所有继承变量共享单一连续槽位范围）。

初始化安全性

• 实现合约的 构造函数 设置 logic_flag 及任何仅限实现合约使用的状态。该函数仅在实现合约部署时执行一次。
• set_version() 必须通过代理调用（部署时或通过 upgrade_to_and_call），以将 VERSION_NUMBER 写入代理合约的存储中。
• 如需额外初始化（如所有权设定、代币供应量配置），应暴露一个受保护的初始化函数，并在其中包含 set_version() 调用。
• 若初始化不当，可能导致合约失去所有者、状态未初始化，或未来升级被拒绝。

抢跑风险警告：务必在代理合约构造函数中一并传入初始化调用数据，以确保部署与初始化操作具备原子性（单笔交易）。切勿先部署代理合约、再通过独立交易执行初始化 —— 攻击者可能抢跑初始化调用，从而将自己设为所有者或破坏初始状态。初始化函数应包含防重入校验：

// 防重入初始化校验模式
fn initialize(&mut self, owner: Address) -> Result<(), Vec> {
    if self.initialized.get() {
        return Err(b"already initialized".to_vec());
    }
    self.initialized.set(true);
    self.uups.set_version();
    self.ownable.init(owner)?;
    Ok(())
}

若无此类防护，初始化函数可被多次调用，攻击者借此可重新初始化合约并夺取所有权。

UUPS 升级校验

UUPS 实现强制执行三项安全校验：

1. 访问控制 —— 限制 upgrade_to_and_call 的调用权限（例如 self.ownable.only_owner()）
2. 代理上下文强制校验 —— 若调用非经 delegatecall 发起，only_proxy() 将触发回滚
3. 可代理 UUID 校验 —— proxiable_uuid() 必须返回 ERC-1967 实现地址槽位，以确认 UUPS 兼容性

重新激活

Stylus WASM 合约须每年（365 天）重新激活一次，或在每次 Stylus 协议升级后重新激活。可使用 cargo-stylus 或 ArbWasm 预编译合约完成重新激活。若未及时重新激活，合约将无法被调用。此机制与代理升级正交，但需纳入日常运维规划。

升级路径测试

在升级生产环境合约前，请执行以下步骤：

• 在本地 Arbitrum 开发网部署 V1 实现合约与代理合约
• 使用 V1 写入状态，再通过 upgrade_to_and_call 升级至 V2，并验证所有既有状态均可正确读取
• 验证新功能 升级后是否按预期正常工作
• 确认访问控制 —— 仅授权调用方可执行 upgrade_to_and_call
• 检查存储布局 —— 确保无已有字段的重排、删除或类型变更
• 验证 VERSION_NUMBER 是否已在新实现合约中递增
• 测试重新激活 —— 确保升级后的合约可成功重新激活
• 人工审查 —— Stylus Rust 合约尚无自动化存储布局校验工具；请依赖结构体比对与开发网测试