第五部分 · 证据与收尾
附录 B 账号、凭证与 API 密钥
学习资料只教「去哪里申请、怎样保管」,永远不要把真实的 API 密钥、私钥或助记词写进教材、截图、聊天或 Git 仓库。
本附录根据 2026-11-12 查阅的 Etherscan 与 Sourcify 官方文档整理。网站的按钮名称和免费额度可能会变,请以你打开时的官方页面为准。
先分清几样完全不同的东西
| 名称 | 是什么 | 泄露了会怎样 | 这次实验怎么处理 |
|---|---|---|---|
| 钱包私钥 | 对应一个地址的十六进制秘密 | 别人可以花掉这个地址上的全部资产 | 只存在本地被忽略的目录,从不打印、从不写入报告 |
| 助记词 | 通常 12 或 24 个英文单词,可恢复整个钱包 | 整个钱包被接管 | 没有使用真实钱包的助记词,也不导入主网钱包 |
| API 密钥 | 网站发给你的访问口令 | 一般不能转走币,但会被用光额度或冒名调用 | 只放在环境变量里,不进聊天、源码、Git |
| RPC 地址 | 你和节点「对话」的网址 | 公共 RPC 不是秘密;带密钥的付费 RPC 泄露会被占用配额 | 用免费公共节点,没有申请节点密钥 |
| 合约地址 | 合约在链上的门牌号 | 不是秘密;被引导到假地址才是风险 | 全部公开,并附 Etherscan 链接 |
记住一句:私钥和助记词能动钱;API 密钥一般只能调用网站服务;合约地址是公开的。 保管方式要按这个风险来。
Etherscan 和「验证源码」
区块浏览器把链上数据做成可以搜索的网页。Sepolia Etherscan 是本书一直在用的那个。
合约部署后,链上保存的是字节码,不是你写的 Solidity 源码。验证源码就是把源码和编译参数提交给浏览器,它用同样的参数重新编译;若结果与链上一致,就公开源码并标记为已验证。要分清三件事:验证实现合约、验证代理合约本身、把代理「关联」到当前实现——完成一件不等于另外两件自动完成。
验证通常不花钱、不发交易:不消耗 SepETH、不占 nonce、不需要钱包签名。但源码一旦公开会长期显示,请只提交愿意公开的代码。
申请 Etherscan 账号和 API 密钥
- 打开官方注册页 etherscan.io/register(请看清地址栏是
etherscan.io,不要点来路不明的广告)。 - 设置用户名、邮箱、单独的密码(不要用任何私钥或助记词当密码),完成人机验证,提交。
- 去邮箱点验证链接激活,然后在 etherscan.io/login 登录。
- 打开 API Dashboard,点 Add,给它起个名字(例如
Web3-Sandbox-Learning,这只是标签,不是密钥)。 - 页面显示一串新的 API 密钥。立刻复制并妥善保存。
注册免费;做学习实验时可以忽略升级付费套餐的引导。官方文档(2026-11-12 查阅)写明免费计划在大多数链上是每秒 3 次、每天最多 100,000 次请求,按账户下所有密钥合计;对「只做几次源码验证」来说绰绰有余。
一把密钥,多条链
Etherscan 现在使用 API V2:同一个接口地址,用参数 chainid 区分网络。Sepolia 的 chain ID 是:
11155111
所以在 etherscan.io 注册的那把密钥,可以直接用于 Sepolia,调用时把 chainid 设成 11155111 即可,不需要另外申请「测试网密钥」。主网的 chainid 是 1,提交前务必确认自己选的是 Sepolia。在一条链上验证成功,不会让其他链上的同一地址自动变成已验证。
怎样安全保存
- 放进密码管理器,或者本机的环境变量。
- 不要发到任何群聊,不要贴进 GitHub、报告、幻灯片或截图,不要写进合约或前端网页代码。
- 如果泄露了:在 API Dashboard 里删除它,再建一把新的(轮换)。
在当前终端里设置(把占位符换成真实值后,不要把这一行发给任何人):
export ETHERSCAN_API_KEY='粘贴你的密钥'
想确认「已经设置」又不把值打印出来:
if [ -n "$ETHERSCAN_API_KEY" ]; then echo present; else echo absent; fi
不要用 echo $ETHERSCAN_API_KEY 来检查,那会把秘密打到屏幕和命令历史里;也不要把密钥写成命令行参数。程序应自己读 process.env.ETHERSCAN_API_KEY(Node.js)或 os.environ["ETHERSCAN_API_KEY"](Python)。
这次实验的实际做法:密钥通过保密输入框交给助手,只保存为环境变量;实验记录、报告、Git 和本书都不包含这把密钥。
这把密钥能做什么、不能做什么
- 能:读取公开链上数据;提交源码验证、查询结果;把代理关联到当前实现。
- 不能:代替私钥签名或转账;扣你的 SepETH;升级 UBOX 代理(那需要 ProxyAdmin owner 的签名)。
用 API 验证:两步
- 提交:向
https://api.etherscan.io/v2/api?chainid=11155111&module=contract&action=verifysourcecode发送源码(推荐 Standard JSON 格式)、完整编译器版本(本实验是v0.8.34+commit.80d5c536)、优化器设置(本实验关闭)、EVM 版本(osaka)。成功提交时返回一个 GUID——这只代表「已排队」,不是验证成功。 - 查询:用
action=checkverifystatus&guid=…查询,直到出现Pass - Verified;再去浏览器上亲眼看一下已验证标记。
代理合约还要额外一步 verifyproxycontract。本书第 15 章记录了真实结果:8 份提交在快照时仍是 Pending in queue。
成功的前提是源码能复现链上字节码:编译器版本、优化器、EVM 版本、构造参数、源码本身都必须和部署时一致。本实验的 V1/V2 就是反例:源码后来改过,只能用重建的历史快照尝试,而且元数据可能挡住「完全匹配」。
不用 API 密钥的途径:Sourcify
Sourcify 是另一套开源的源码验证服务。用网页 verify.sourcify.dev 或 Foundry 验证时,通常不需要 Etherscan API 密钥:
forge verify-contract 0x合约地址 \
src/MyToken.sol:MyToken \
--chain 11155111 \
--verifier sourcify
结果分 exact_match 和 match 两种。查看已验证合约的地址规律:
https://repo.sourcify.dev/11155111/0x你的合约地址
Etherscan 和 Sourcify 是两套独立的公开记录,一边通过,另一边不会自动通过。(2026-11-12 查阅时,Sourcify 文档写明旧的 v1 API 已于 2026-07-07 关闭,请使用 v2。)
这次实验还需要申请什么?
| 事项 | 本次是否申请 | 要不要付钱 | 说明 |
|---|---|---|---|
| Etherscan 账号 + 免费 API 密钥 | 是(用于源码验证) | 否 | 本附录 |
| Sourcify 账号 | 否 | 否 | 网页验证通常可以直接上传 |
| Infura / Alchemy 等节点密钥 | 否 | 否 | 用了免费公共 RPC |
| 交易所或主网钱包 | 否,明确禁止导入 | — | 只用本地生成的测试账户 |
| 购买 ETH 或测试币 | 否 | 预算 0 美元 | 只用水龙头 |
| GitHub 令牌 | 否 | 否 | 只做本地 Git |
| Foundry / solc | 安装工具,无需密钥 | 否 | 开源工具 |