deploying-contracts-on-base

在 Base 上部署合约

前提条件

1. 配置 RPC 端点（测试网：sepolia.base.org，主网：mainnet.base.org）
2. 将私钥存储在 Foundry 的加密密钥库中——切勿提交私钥
3. 通过 CDP 水龙头获取测试网 ETH（仅限测试网）
4. 获取 BaseScan API 密钥，用于验证合约

安全

• 切勿将私钥提交到版本控制中——使用 Foundry 的加密密钥库（cast wallet import）
• 切勿在源文件中硬编码 API 密钥——使用环境变量，或在 foundry.toml 中使用 ${ENV_VAR} 引用
• 切勿公开 .env 文件——将 .env 添加到 .gitignore
• 主网部署时使用生产环境 RPC 提供商（而非公共端点），以避免速率限制和数据泄露
• 在 BaseScan 上验证合约，以便公众审计已部署的代码

输入验证

在构造 Shell 命令之前，请验证所有用户提供的值：

• contract-path：必须匹配 ^[a-zA-Z0-9_/.-]+\.sol:[a-zA-Z0-9_]+$。拒绝包含空格、分号、管道符或反引号的路径。
• rpc-url：必须是有效的 HTTPS URL（^https://[^\s;|&]+$）。拒绝非 HTTPS 或格式错误的 URL。
• keystore-account：必须仅包含字母数字字符、连字符和下划线（^[a-zA-Z0-9_-]+$）。
• etherscan-api-key：必须仅包含字母数字字符（^[a-zA-Z0-9]+$）。

不要将未经验证的用户输入传入 Shell 命令。

通过 CDP 水龙头获取测试网 ETH

在 Base Sepolia 上支付 Gas 需要测试网 ETH。使用 CDP 水龙头领取。支持的代币：ETH、USDC、EURC、cbBTC。每次领取的 ETH 上限为 0.0001 ETH，每 24 小时最多可领取 1000 次。

选项 A：CDP Portal UI（推荐用于快速设置）

**Agent 行为：**如果你可以访问浏览器，请前往门户网站并直接领取。否则，请让用户完成以下步骤并提供已充值的钱包地址。

1. 登录 CDP Portal（如有需要，可在 portal.cdp.coinbase.com/create-account 创建账户）
2. 前往 Faucets
3. 选择 Base Sepolia 网络
4. 选择 ETH 代币
5. 输入钱包地址并点击 Claim
6. 在 sepolia.basescan.org 上确认资金已到账

选项 B：通过 CDP SDK 以编程方式操作

需要 CDP API 密钥和 Wallet Secret。

npm install @coinbase/cdp-sdk dotenv

import { CdpClient } from "@coinbase/cdp-sdk";
import dotenv from "dotenv";
dotenv.config();

const cdp = new CdpClient();
const account = await cdp.evm.createAccount();

const faucetResponse = await cdp.evm.requestFaucet({
  address: account.address,
  network: "base-sepolia",
  token: "eth",
});

console.log(`Funded: https://sepolia.basescan.org/tx/${faucetResponse.transactionHash}`);

.env 中需要的环境变量：

CDP_API_KEY_ID=your-api-key-id
CDP_API_KEY_SECRET=your-api-key-secret
CDP_WALLET_SECRET=your-wallet-secret

若要为现有钱包充值，而不是创建新钱包，请将其地址直接传给 requestFaucet。

获取 BaseScan API 密钥

使用 --verify 标志在 BaseScan 上自动验证合约需要 BaseScan API 密钥。BaseScan 与 Etherscan 使用相同的账户系统。

**Agent 行为：**如果你可以访问浏览器，请前往 BaseScan 网站并创建密钥。否则，请让用户完成以下步骤并提供 API 密钥。

1. 前往 basescan.org/myapikey（或 etherscan.io/myapikey——使用同一账户即可）
2. 登录或创建免费账户
3. 点击 Add 创建新的 API 密钥
4. 复制密钥并在环境中设置：

export ETHERSCAN_API_KEY=your-basescan-api-key

也可以直接传给 forge：

forge create ... --etherscan-api-key <your-key>

或者将其添加到 foundry.toml：

[etherscan]
base-sepolia = { key = "${ETHERSCAN_API_KEY}", url = "https://api-sepolia.basescan.org/api" }
base = { key = "${ETHERSCAN_API_KEY}", url = "https://api.basescan.org/api" }

部署命令

测试网

forge create src/MyContract.sol:MyContract \
  --rpc-url https://sepolia.base.org \
  --account <keystore-account> \
  --verify \
  --etherscan-api-key $ETHERSCAN_API_KEY

主网

forge create src/MyContract.sol:MyContract \
  --rpc-url https://mainnet.base.org \
  --account <keystore-account> \
  --verify \
  --etherscan-api-key $ETHERSCAN_API_KEY

重要说明

• 合约格式：<contract-path>:<contract-name>
• --verify 标志会在 BaseScan 上自动验证（需要 API 密钥）
• 区块浏览器：basescan.org（主网）、sepolia.basescan.org（测试网）
• CDP 水龙头文档：docs.cdp.coinbase.com/faucets

常见问题

错误	原因
nonce has already been used	节点同步未完成
交易失败	ETH 不足以支付 Gas 费 — 从水龙头领取
验证失败	目标网络的 RPC 端点错误
验证返回 403/未授权	缺少或无效的 BaseScan API 密钥