Optimism 智能合约开发规范OP Stack 合约安全、代理升级与工程实践指南【免费下载链接】optimismOptimism is Ethereum, scaled.项目地址: https://gitcode.com/GitHub_Trending/op/optimism本文是面向 OP Stack 智能合约开发与审阅者的技术指南以packages/contracts-bedrock/AGENTS.md为骨架结合 contracts-bedrock 仓库源码与配置系统讲解非幂等初始化器风险、EIP-1967 透明代理升级机制、跨链消息体系、Solidity 编码标准、测试规范与 CI 检查流程。读完本文你将掌握在 Optimism 主网、Base 及 Superchain 成员链上安全开发与审阅合约的完整方法并能正确使用mise x -- just ...命令链完成构建、测试与提交前的全套质量门禁。写在前面这份文档服务于谁packages/contracts-bedrock/AGENTS.md是 contracts-bedrock 面向AI Agent 与智能合约开发者的协作规范。它的首要假设是这里的 L1/L2 智能合约守护着真实资产——OP Mainnet、Base 以及其他 Superchain 成员——因此每一处改动都承担风险尤其是packages/contracts-bedrock/src/下实现合约的任何变更。文档中的每一条规则都不是风格偏好而是由真实安全事故如可重入、可重初始化导致的存储损坏倒逼出来的硬性约束。非幂等初始化器升级路径上的第一道风险风险场景可重初始化与状态污染OP Stack 中所有协议合约都位于代理之后升级时可通过reinitializer(version)对已持有旧状态的合约再次调用initialize()。典型场景是OPContractsManagerV2._apply()这类编排器在升级时对多个合约批量执行初始化——如果初始化器不是幂等的重复执行就会损坏状态。原文档给出了ETHLockbox.initialize()的例子它对每个传入的 portal 调用_authorizePortal()。当前安全的原因在于_authorizePortal()是幂等的——将authorizedPortals[portal] true设置两次与设置一次效果相同。但假如将来有人在此基础上增加一个每次授权自增的 portal 计数重复初始化就会导致 portal 被重复计数存储失真。参见 ETHLockbox.sol。哪些行为使初始化器非幂等审阅initialize()/reinitializer时重点排查以下操作自增计数器或 nonce每次调用状态都会变化向数组追加元素重复初始化会产生重复项带有持久副作用的外部调用例如铸造代币、发送 ETH依赖先前状态的操作例如在余额上 10非幂等与把余额设为 10幂等的本质区别。此外即使初始化器本身幂等也存在不宜重复执行的情况触发会驱动链下动作的事件例如按事件精确处理一次的索引器覆盖其他合约或链下系统已经依赖的变量例如重置在线合约正在指向的注册表地址或修改应在首次初始化后保持不可变的配置值。规则与审阅清单规则initialize()/reinitializer中的非幂等或不宜重跑行为一律禁止除非在函数上以notice注释明确承认其后果并解释在调用方使用方式下为何安全。缺少该注释代码不得被批准。审阅清单适用于改动initialize()或其调用方时初始化器中的每个操作是否幂等把变量赋为固定值是幂等的自增、追加、调用外部合约则可能不是。覆盖某个变量是否不安全某些值只应设置一次——重初始化时覆盖可能破坏依赖原值的其他合约或系统。该合约是否可以被重新初始化检查是否存在reinitializer修饰符若只使用一次性initializer风险不适用。如果存在非幂等或不安全行为是否有notice注释承认它注释必须解释为何安全。缺失即为阻断性问题blocking issue。合约作用域与架构全景目录与文档导航OP Stack 的 L1/L2 智能合约主体位于packages/contracts-bedrock/。开发与审阅者应同时参考以下规范文档权威 Solidity 风格指南style-guide.md接口策略interfaces.md版本管理与升级策略packages/contracts-bedrock/book/src/policies/目录下。代理系统一切合约的底座所有协议合约都位于EIP-1967 透明代理之后。代理实现是自定义的非 OpenZeppelin位于 Proxy.sol由ProxyAdmin合约统一管理系统内所有代理的升级。从源码看Proxy.solproxyCallIfNotAdmin修饰符实现了透明代理的核心逻辑若调用者是 admin 或address(0)则直接执行管理函数否则走_doProxyCall()进行 delegatecall。关键属性管理员调用不被代理转发透明代理模式避免函数选择器冲突msg.sender address(0)检查允许eth_call模拟——链下工具可以不依赖底层存储读取直接与代理交互upgradeToAndCall()原子升级并调用Proxy.sol先_setImplementation再delegatecall(_data)失败则整体回滚保证初始化式升级的原子性兼容 CHUGSPLASH 与 RESOLVED 两类旧代理类型保证历史合约平滑迁移。跨链消息L1-L2 与 L2-L2存在两套消息系统L1↔L2抽象基类CrossDomainMessenger见 CrossDomainMessenger.sol及其 L1/L2 特化实现L2↔L2L2ToL2CrossDomainMessenger预部署于0x4200...0023见 L2ToL2CrossDomainMessenger.sol。消息 nonce 的高 16 位编码版本号低 240 位为实际 nonce。V1 消息载荷包含 sender、target、value、gasLimit、data 五个字段。Gas 开销常量考虑了 EIP-150 的 63/64 转发规则详见下文跨链消息小节。关键不变量审阅任何改动前先对照这些系统级不变量代理升级安全存储布局不得发生不兼容变更初始化器守卫未经 StorageSetter 流程合约不得被重新初始化桥消息完整性跨域消息必须可证明地被中继存款交易排序存款按 L1 包含顺序处理禁止重复消息中继successfulMessages映射防止重放重入安全所有消息中继路径使用瞬态存储守卫。关键合约速查表合约用途位置OptimismPortal2L1 存款/取款门户src/L1/SystemConfig链上系统配置src/L1/SuperchainConfig全局 Superchain 配置暂停、守护者src/L1/ETHLockbox面向授权 portal 的统一 ETH 流动性src/L1/L1CrossDomainMessengerL1 跨域消息src/L1/L1StandardBridgeL1 代币桥src/L1/L1ERC721BridgeL1 ERC-721 桥src/L1/OPContractsManager管理 L1 合约部署与升级实现为OPContractsManagerV2src/L1/opcm/L2ContractsManagerL2CM——管理 L2 预部署合约升级src/L2/CrossDomainMessenger抽象基类信使src/universal/StandardBridge抽象基类桥src/universal/ProxyEIP-1967 透明代理src/universal/ProxyAdmin代理管理src/universal/DisputeGameFactory创建/注册争议游戏的工厂src/dispute/FaultDisputeGame故障证明争议解决src/dispute/AnchorStateRegistry按游戏类型存储最新锚点状态src/dispute/工具库速查表库用途Hashing跨域消息哈希、存款来源哈希EncodingRLP 编码、带版本的 nonce 编码SafeCall带 EIP-150 记账的燃气安全外部调用见 SafeCall.solConstants协议级常量与地址PredeploysL2 预部署地址Storage底层存储访问sload/sstoreTransientContext瞬态存储重入守卫见 TransientContext.solSemverComp运行时 semver 比较源码目录结构packages/contracts-bedrock/src/ ├── L1/ # L1 协议合约OptimismPortal2、SystemConfig、桥 │ └── opcm/ # OPContractsManager 实现 ├── L2/ # L2 预部署合约GasPriceOracle、信使、桥 ├── universal/ # L1/L2 共享Proxy、ProxyAdmin、StandardBridge、CrossDomainMessenger ├── libraries/ # 纯工具库Hashing、Encoding、SafeCall、Constants、Predeploys ├── dispute/ # 故障证明争议游戏合约 ├── governance/ # 治理合约 ├── safe/ # Safe 多签扩展 ├── cannon/ # Cannon VM 合约 ├── periphery/ # 外围合约 ├── integration/ # 集成工具 ├── vendor/ # 外部供应商代码 └── legacy/ # 弃用合约代理与可升级性规范新实现合约的固定模式每个新的实现合约必须遵循如下模式继承 OpenZeppelin 的Initializable提供带reinitializer(initVersion())修饰符的initialize()构造函数中调用_disableInitializers()且只设置 immutable 变量继承ReinitializableBase(N)并传入当前初始化版本绝不向reinitializer(...)传硬编码字面量版本号——始终使用initVersion()。关于第 4 点仓库中的 ReinitializableBase.sol 给出了具体实现它以 immutableINIT_VERSION保存版本号构造函数对 0 版本直接revert ReinitializableBase_ZeroInitVersion()并提供initVersion()视图函数。immutable 存储在后缀存储区天然与可升级存储布局解耦这正是永远用initVersion()而不用字面量的底层原因——当版本升级时只需修改继承参数所有reinitializer调用点自动跟随。原子三步升级流程升级通过ProxyAdmin.upgradeAndCall()原子完成见 ProxyAdmin.sol将实现升级为StorageSetter见 StorageSetter.sol用 StorageSetter 将 initialized 槽位清零通常为槽位 0升级到新实现并调用initialize()。三步合并在单笔交易内执行中间状态不可观测杜绝升级一半的窗口。存储布局约束绝不修改既有存储槽位的分配被移除的字段使用私有 spacer 变量spacer_slot_offset_length并以custom:legacy与custom:spacer标签标注继承链使用存储间隙uint256[N] private __gapCI 通过snapshots/storageLayout/中的快照校验存储布局SystemConfig 使用确定性存储槽位基于keccak256(systemconfig.fieldname)见 SystemConfig.sol。访问控制原语ProxyAdminOwnedBase代理管理员所有权检查见 ProxyAdminOwnedBase.solCrossDomainOwnable3L2 合约的跨域所有权onlyEOA()修饰符阻止智能合约钱包调用onlyOtherBridge()桥消息校验跨链调用方验证使用ICrossDomainMessenger.xDomainMessageSender()。重入保护基于瞬态存储EIP-1153的守卫TransientReentrancyAware消息中继函数上的nonReentrant修饰符通过TransientContext.increment()/decrement()跟踪调用深度successfulMessages映射防止重复消息中继。瞬态存储守卫的优势在于槽位在交易结束自动清零无需在构造函数或初始化器里预留存储位也不占用可升级存储布局。跨链消息编码细节消息版本内嵌于 nonce高 16 位为版本低 240 位为 nonceV1 编码abi.encode(nonce, sender, target, value, gasLimit, data)V1 哈希keccak256(abi.encode(nonce, sender, target, value, gasLimit, data))Gas 开销常量定义于 CrossDomainMessenger200k 中继常量、5k 检查缓冲EIP-150 的 63/64 燃气转发规则由 SafeCall 库处理见 SafeCall.sol。合约组织模板以 SystemConfig 与 OptimismPortal2 为参照SystemConfig.sol与OptimismPortal2.sol是权威参考实现。新合约按下述结构组织// SPDX-License-Identifier: MIT pragma solidity 0.8.15; // Contracts import { ProxyAdminOwnedBase } from src/universal/ProxyAdminOwnedBase.sol; import { Initializable } from openzeppelin/contracts/proxy/utils/Initializable.sol; // Libraries import { SafeCall } from src/libraries/SafeCall.sol; // Interfaces import { ISemver } from interfaces/universal/ISemver.sol; /// custom:proxied true /// title ContractName /// notice Description contract ContractName is Initializable, ProxyAdminOwnedBase, ReinitializableBase, ISemver { // Constants and immutables // Custom errors // Events // State variables (with custom:network-specific where appropriate) // Spacers (with custom:legacy and custom:spacer) // Constructor (call _disableInitializers()) // Initializer // External functions // Internal functions }注意导入顺序与分组合约→库→接口以及custom:proxied true标注。Solidity 编码标准工具链永远经由 just绝不直接调 forge底层是 Foundry但一律通过packages/contracts-bedrock/justfile中的just配方驱动绝不直接调用forge。配方会自动接好 go-ffi、profiles 与脚本缓存。just build构建合约just build-dev是快速变体FOUNDRY_PROFILElite用于本地迭代。构建必须零警告foundry.toml中deny warningsjust test运行测试套件just test-dev是 lite-profile 快速变体。默认 64 轮 fuzzCI 用 128 轮just lint执行格式化与检查底层为forge fmt120 字符行长、括号间距、多行函数头Semgrep用于安全 lint自定义规则位于.semgrep/rules/通过just semgrep运行Slither用于静态分析。在packages/contracts-bedrock下所有配方都必须经mise运行以使用钉定的工具链例如mise x -- just build-dev。Pragma 策略全代码库统一 Solidity 版本目前绝大多数合约使用0.8.15最终派生合约与脚本必须钉死精确版本pragma solidity 0.8.15;。CI 的strict-pragma检查对含具体合约的文件强制执行可复用库允许浮动 pragma^0.8.0常见且可接受——适用于src/libraries/、抽象基类与接口。它们被钉死版本的具体合约消费且 CI 有意豁免库、接口与抽象合约引入新 Solidity 版本必须有正式 design-doc 提案新版本采用前必须至少发布 6 个月。命名约定元素约定示例函数参数_下划线前缀function set(address _newOwner)返回值下划线后缀_returns (uint256 balance_)事件参数camelCase无前缀event Transfer(address from, address to)自定义错误ContractName_Descriptionerror SystemConfig_InvalidCaller()ImmutableSCREAMING_SNAKE_CASEinternaladdress internal immutable OWNER_ADDRESS常量SCREAMING_SNAKE_CASEuint256 internal constant DEPOSIT_VERSION 0Spacerspacer_slot_offset_lengthprivatebytes32 private spacer_52_0_32结构体存储变量_下划线前缀internalConfig internal _configImmutable 与结构体存储变量Immutable 必须为internal绝不public且必须提供返回小写名称的手写 getter——这使 ABI 与值是存储字段还是 immutable解耦address internal immutable OWNER_ADDRESS; function ownerAddress() public view returns (address) { return OWNER_ADDRESS; }结构体存储变量同样必须internal加_前缀并提供返回结构体类型而非元组的手写 getter因为 Solidity 自动生成的 getter 返回元组破坏可读性Config internal _config; function config() public view returns (Config memory) { return _config; }错误与 NatSpec新代码全部使用自定义 Solidity 错误格式error ContractName_ErrorDescription()以revert ContractName_ErrorDescription()触发新代码禁止require(condition, string)或revert(string)注释使用三斜杠///只用notice禁用devnotice与首个param之间、param与首个return之间各留空行注释行长 100 字符。自定义标签语义custom:proxied——合约位于代理之后custom:upgradeable——合约供可升级实现继承custom:semver——版本变量semver 格式custom:legacy——仅为向后兼容存在的函数/事件custom:network-specific——在不同 OP Chain 间变化的存储变量custom:spacer——已移除存储的 spacer 变量。接口策略源合约不得继承自身接口合约可以导入其他合约的接口每个源合约必须在interfaces/下有对应接口接口必须包含__constructor__()伪构造函数CI 强制源合约与接口 ABI 1:1 匹配由scripts/checks/interfaces实现经just interfaces-check运行。版本管理Semver所有非库、非抽象合约必须实现ISemver暴露string public constant version X.Y.Z;并加custom:semver标签Patch仅注释变更除版本字符串外字节码不变Minor字节码或 ABI 扩展非破坏性Major破坏性接口或安全模型变更生产就绪要求version 1.0.0每个 PR 只升一次版本而非每次提交——PR 以 squash 合并历史中只出现一个提交最终版本应反映从 PR 基础分支到合并的全部变更。事件所有状态变更函数必须发出对应事件以支持透明监控与日志重建。测试规范函数命名格式[method]_[FunctionName]_[reason]_[status][method]test、testFuzz或testDiff[FunctionName]被测函数或行为[reason]可选描述reverts/fails必填[status]succeeds、reverts、works、fails或benchmark。规则各部分 camelCase无双下划线恰好 3 或 4 段。// 合法 function test_transfer_succeeds() external { } function test_transfer_insufficientBalance_reverts() external { } function testFuzz_balanceOf_randomAccount_succeeds(address _account) external { } // 非法 function test_transfer_reverts() external { } // 缺 reason function test_TRANSFER_succeeds() external { } // 非 camelCase function testTransferSucceeds() external { } // 无下划线合约命名与文件组织ContractName_FunctionName_Test——针对特定函数的测试ContractName_TestInit——可复用的初始化/设置ContractName_Harness——暴露内部函数供测试ContractName_Uncategorized_Test——杂项测试。测试文件位于test/扩展名.t.sol镜像src/目录结构每个被测函数一个测试合约所有测试继承CommonTest提供完整 OP Stack 部署。测试基础设施CommonTest基类部署完整 OP StackL1 L2见 CommonTest.sol预配置角色 alice 与 bob各持 10,000 ETH特性开关支持测试变体altDA、interop、custom gas tokenFork 测试支持通过FORK_TEST环境变量自动检测不变量测试位于test/invariants/支持引导与非引导 fuzz 模式Kontrol 形式化验证位于test/kontrol/Go FFI 支持测试中的链下计算经just build-go-ffi构建。Foundry 配置要点配置见 foundry.toml默认优化器999,999 runsDispute/OPCM 合约5,000 runs控制字节码体积EVM 版本cancun额外输出devdoc、userdoc、metadata、storageLayout为脚本/测试启用 FFIGas 上限max int64支撑大测试Fuzz 轮数64默认、128CI、20,000ciheavy。编译 Profile 一览Profile优化器Fuzz 轮数用途default999,999 runs64生产构建lite关闭8快速开发迭代ci999,999 runs128CI 测试ciheavy关闭20,000压力测试cicoverage关闭1仅覆盖率kprove默认—Kontrol 形式化验证foundry.toml的compilation_restrictions明确列出以 5,000 runs 编译的合约src/dispute/FaultDisputeGame.sol、PermissionedDisputeGame.sol、SuperFaultDisputeGame.sol、SuperPermissionedDisputeGame.sol、src/L1/opcm/OPContractsManagerV2.sol及其容器/迁移/工具合约、src/L1/OptimismPortal2.sol、src/universal/StorageSetter.sol、src/L2/L2ContractsManager.sol例外是OPContractsManagerStandardValidator.sol使用 200 runs。构建与测试命令实战所有命令都必须经mise运行以使用钉定版本的 forge、solc、go 等。绝不裸跑just target或forge cmd会绕过钉定工具链mise x -- just build-dev # 快速开发构建本地工作首选 mise x -- just test-dev # 快速开发测试本地工作首选 mise x -- just lint # 格式化修复 检查 mise x -- just pr # 完整 PR 前套件build、lint、全部检查 mise x -- just test-upgrade # 对主网状态做 Fork 测试需要 ETH_RPC_URL mise x -- just semver-lock # 重新生成 semver-lock.json mise x -- just snapshots # 重新生成全部快照 mise x -- just semver-lock-no-build # 从现有构建产物重新生成更快just build与just test运行全量优化的生产构建较慢日常迭代用just build-dev/just test-dev。配方会把额外参数透传给forge因此可用--match-contract/--match-test缩小范围例如mise x -- just test-dev --match-contract OptimismPortal2_Test这比跑全套快得多。开 PR 前务必运行完整just test——这正是 CI 运行的命令。just test-upgrade升级路径测试以每日钉定的区块高度 fork 主网或 Sepolia应用升级路径运行test/{L1,dispute,cannon}/下的测试。它验证升级在真实已部署状态下可行——是真实升级路径而非全新部署。需要ETH_RPC_URL。修改可升级合约或升级流程本身时务必运行。从 justfile 可以看到test-upgrade经由prepare-upgrade-env将FORK_BLOCK_NUMBER钉定到当天 UTC 零点附近区块print-pinned-block-number配方通过cast find-block计算并设置FORK_TESTtrue、FORK_RPC_URL$ETH_RPC_URL再以--match-path test/{L1,dispute,cannon}/**收敛测试范围。CI 检查清单以下检查必须全部通过多数对应 justfile 中的-check配方并汇总于just check/just prforge fmt --check——格式化Semgrep 扫描——安全规则快照生成——ABI 存储布局 semver lockSemver diff——字节码变化时必须升版本无未使用导入严格 pragma——禁止浮动 pragma存储 spacer——spacer 命名与位置Reinitializer 修饰符——正确的升级守卫由scripts/checks/reinitializer实现经just reinitializer-check运行接口正确性——ABI 1:1 匹配合约体积——在 EIP-170 限制内经just size-check以forge build --sizes检查测试命名——由校验脚本强制。Rebase 冲突中的生成快照处理snapshots/semver-lock.json是生成文件——冲突双方都是错的。哈希必须基于 rebase 落地后的实际编译产物重新计算即使是分支作者预先计算的哈希也可能过期。接受任意一侧以清除冲突标记在packages/contracts-bedrock/下运行mise x -- just semver-lock重新生成暂存重新生成的文件并 amend 提交或继续 rebase。同样的规则适用于任何其他生成快照snapshots/storageLayout/等。若构建失败无网络/solcrebase 无法正确完成——应明确说明而非保留任何手工挑选的哈希。提交合约变更前的最终检查just test-dev——零测试失败lite-profile 快速迭代。迭代期间可用 forge 过滤器缩小范围例如just test-dev --match-contract OptimismPortal2_Test或just test-dev --match-test test_finalizeWithdrawalTransaction_succeeds。开 PR 前运行未过滤的just test-dev以及just testCI 运行的全量优化变体just pr——完整 PR 前套件build、lint、全部检查字节码变化则升级合约版本每个 PR 一次而非每次提交——PR 是 squash 合并以安全视角审阅——这些合约守护真实资产。结语OP Stack 的合约工程规范可以概括为一句话把不可逆的破坏前置到代码审查与 CI 阶段。从初始化器幂等性、代理升级存储布局到命名约定、测试命名与版本管理每一条规则都能在 AGENTS.md 与packages/contracts-bedrock/的源码、配置、测试中找到落点。对任何计划为 Superchain 贡献合约代码的开发者或 AI Agent 而言遵循这套规范不仅是通过 CI 的前提更是守护链上真实资产的第一道防线。【免费下载链接】optimismOptimism is Ethereum, scaled.项目地址: https://gitcode.com/GitHub_Trending/op/optimism创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考