深入解读 @eth-optimism/contracts：开发者如何驾驭 Optimism 智能合约

Optimism 智能合约全景速览

@eth-optimism/contracts 是 Optimism 生态的核心仓库，收纳了所有与 Layer1（L1）与 Layer2（L2）交互的 Solidity 智能合约。
各源文件首部的注释都会写明部署目标：

把这份清单当作 Optimism 合约地图，就能迅速拿捏每份合约的“居住地址”和职责，从而在 Layer2 或 Layer1 的代码迁移上游刃有余。

只需一行命令即可将官方合约纳入项目：

npm install @eth-optimism/contracts

在你的 .sol 文件中：

import { L1CrossDomainMessenger } from "@eth-optimism/contracts/L1/messaging/L1CrossDomainMessenger.sol";

路径格式固定为：@eth-optimism/contracts/{子目录}/{合约名}.sol，与 GitHub 仓库目录完全一致。👉 想一图看懂所有合约调用顺序？点这里获取可视化备忘单

克隆仓库

git clone https://github.com/ethereum-optimism/optimism.git
cd optimism/packages/contracts
yarn

yarn build        # 编译全部合约
yarn test         # 跑所有测试
yarn coverage     # 生成覆盖率报告
open coverage/index.html

配置环境变量
复制 .env.example → .env，填入私钥、RPC、Etherscan API 等敏感信息。
编写部署配置
在 deploy-config/ 新建 {network}.ts，对照 mainnet.ts 调整跨链桥地址、gas 上限等字段。
执行部署
首次部署：
```
npx hardhat deploy --network mainnet
```
升级合约：
```
npx hardhat deploy --network mainnet --tags upgrade
```
👉 升级怕被抢先作恶？阅读官方脚本安全指南可避险
验证源码
自动由脚本提交至 Etherscan & Sourcify；若失败，手动：
```
npx hardhat etherscan-verify --network mainnet
```
生成 Genesis 文件
部署 L1 完成后执行：
```
npx hardhat take-dump --network mainnet
```
生成的 /genesis/mainnet.json 交由 geth init 读取即可。

白名单管理
自建测试网可沿用白名单机制：
```
npx hardhat whitelist --help
```
提取 Sequencer 手续费
每当 SequencerFeeWallet 余额超过阈值，可触发提现：
```
npx hardhat withdraw-fees --help
```

官方通过 Immunefi 运营 Bug Bounty，最高悬赏 200 万美元。发现漏洞请优先阅读 Security Policy 再提交详尽复现报告，切勿直接在公共渠道披露。

Q1：合约已升级，前端迟迟读不到新地址怎么办？
A：确认 .env.CONTRACTS_TARGET_NETWORK 写入的是对应网络名称，清空前端缓存并重新拉取 ./deployments/ 目录下的 address.json。

Q2：没有标注 L1 或 L2 的合约可以直接部署到主网吗？
A：可以，但请先在 fork-net 环境跑完全流程测试。安全前提下，建议先用 hardhat coverage --network localhost 跑满单元测试。

Q3：为什么 yarn test 会报内置路径错误？
A：通常是因为 Node 缓存没清。执行 yarn clean && yarn build 再重试。

Q4：升级时如何防止“中途卡死”导致合约权限无法回收？
A：升级脚本会在最后一步重置 owner。若网络中断，运行：

npx hardhat deploy --network mainnet --tags recover

即可手动取回权限。

Q5：添加自定义预部署合约需要改源代码吗？
A：不必。把新地址及字节码写入 genesis-state.json，然后在配置文件中引用即可。

Q6：部署完成后还需要人工二次签名做什么？
A：极少数配置了 MultiSig 的步骤需要额外签名确认交易，特别是跨链桥 ProxyAdmin 的转移。

借助 @eth-optimism/contracts，你就能在 Layer2、Layer1 和 本地测试网 之间顺滑切换，快速构建安全、高吞吐的 dApp。祝你开发愉快！