Foundry Cast 使用文档

Foundry Cast 是 Foundry 工具集中用于与以太坊区块链交互的命令行工具，它允许开发者直接从命令行执行以太坊 RPC 调用、查询链上数据、发送交易以及与智能合约进行交互。

一、Cast 工具概述

1.1 什么是 Cast？

Cast 是 Foundry 框架中的瑞士军刀式链上交互 CLI 工具，专门用于对兼容以太坊虚拟机（EVM）的区块链进行 RPC 调用。通过 Cast，开发者可以：

• 查询区块、交易、账户余额等链上数据
• 发送交易到区块链网络
• 调用智能合约的只读方法
• 编码和解码各种数据格式
• 部署智能合约
• 解析交易日志和事件

1.2 Cast 在 Foundry 生态中的位置

Foundry 是一个用 Rust 编写的极速、可移植和模块化的以太坊应用开发工具包，包含四个核心组件：

工具名	说明
Forge​	合约开发、测试、编译的主工具
Cast​	与链交互工具：查询数据、发送交易、部署合约
Anvil​	本地模拟链，用于测试、开发和 fork 主网数据
Chisel​	Foundry 集成的 Solidity REPL

二、安装与配置

2.1 安装 Foundry（包含 Cast）

Cast 作为 Foundry 的一部分安装，推荐使用 Foundryup 进行安装：

# 下载并安装 Foundryup
curl -L https://foundry.paradigm.xyz | bash

# 重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装最新版本的 Foundry
foundryup

# 验证安装
forge --version
cast --version
anvil --version

2.2 环境变量配置

为了方便使用，可以设置环境变量避免重复指定 RPC URL：

# 设置以太坊主网 RPC URL
export ETH_RPC_URL="https://eth-mainnet.alchemyapi.io/v2/your-api-key"

# 设置 Sepolia 测试网 RPC URL  
export SEPOLIA_RPC_URL="https://sepolia.infura.io/v3/your-api-key"

设置后，Cast 命令会自动使用对应的 RPC 节点，无需在每个命令后添加 --rpc-url参数。

三、Cast 命令分类与详解

3.1 基本命令结构

Cast 命令的基本格式为：

cast [options] <subcommand> [args]

获取帮助信息：

cast help                    # 获取所有命令帮助
cast help <subcommand>       # 获取特定子命令帮助
cast --version              # 查看 Cast 版本

3.2 区块链信息查询命令

3.2.1 查询链信息

cast chain                  # 获取当前链的名称
cast client                 # 获取当前客户端的版本

3.2.2 区块相关查询

cast block-number           # 获取最新区块号（十进制）
cast block <block_number>   # 获取指定区块的信息
cast block --json <block_number>  # 以 JSON 格式输出区块信息
cast basefee <block_number> # 获取区块的基础费用
cast age <block_number>     # 获取区块的时间戳
cast find-block <timestamp> # 获取与提供的时间戳最接近的区块编号

3.2.3 交易相关查询

cast tx <tx_hash>           # 获取交易信息
cast receipt <tx_hash>      # 获取交易收据
cast receipt <tx_hash> logs # 只获取交易日志
cast logs --from-block <start> --to-block <end> --address <contract_address> # 按区块范围和地址获取日志

3.3 账户与余额查询

cast balance <address>      # 获取账户余额，单位为 Wei
cast balance --ether <address> # 获取账户余额，单位为 ETH

3.4 智能合约交互命令

3.4.1 只读调用（call）

# 调用合约方法，不指定返回值类型，返回 byte hex 串
cast call 0x6b175474e89094c44da98b954eedeac495271d0f "totalSupply()" --rpc-url $ETH_RPC_URL

# 调用合约方法，指定返回值类型为 uint256，直接返回数字
cast call 0x6b175474e89094c44da98b954eedeac495271d0f "totalSupply()(uint256)" --rpc-url $ETH_RPC_URL

3.4.2 发送交易（send）

# 发送交易到合约
cast send --private-key "your_private_key" 0xContractAddress "functionName(type1,type2)" arg1 arg2 --rpc-url $RPC_URL

# 示例：调用 mint 函数
cast send --private-key "dcf6d16a9283f0446df2812fba0ad0a7cfa363937d02543ac4cfe17bf9be776f" \
  "0xbE5ca556b6a49AAEf52683913360d1307ca11cFc" \
  "mint(address,uint256)" \
  0x3402Dd0C05999f0c0526fcecf2F975b899Ff8371 1234 \
  --rpc-url http://localhost:6789 --legacy

3.4.3 部署合约

# 使用 cast send 直接部署合约
cast send \
  --from 0xf39f...92266 \
  --rpc-url http://127.0.0.1:8545 \
  --create out/TokenPresale.sol/TokenPresale.json \
  -- \
  -vvvv

3.5 数据编码与解码

3.5.1 函数选择器与 calldata 解码

# 解码 calldata
cast 4byte-decode 0x1F1F897F676d00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003e71
# 输出： "fulfillRandomness(bytes32,uint256)" 0x676d000000000000000000000000000000000000000000000000000000000000999

# 计算函数选择器
cast sig "transfer(address,uint256)"  # 输出：0xa9059cbb

3.5.2 数据格式转换

cast from-utf8 "hello world"          # 将字符串转换为 bytes
cast to-hexdata "some data"           # 转换为十六进制数据
cast --to-dec 0x10                    # 十六进制转十进制
cast --to-hex 16                      # 十进制转十六进制

3.6 钱包管理命令

Cast 提供了丰富的钱包管理功能，包括生成和管理 keystore 文件。

3.6.1 生成新账户和 Keystore

# 生成新的随机密钥对并创建 keystore
cast wallet new [目录路径] [账户名称]

# 示例：在当前目录创建名为 "my-account" 的 keystore
cast wallet new . my-account

# 生成带有助记词的账户
cast wallet new-mnemonic

生成过程详解：

1. 运行 cast wallet new . my-account命令

2. 系统会提示您输入密码来加密 keystore 文件

3. 生成两个文件：

   • my-account- 加密的 keystore 文件（JSON 格式）
   • my-account.txt- 包含私钥的明文文件（仅用于测试）

安全提示：

• 确保在安全环境中生成 keystore
• 使用强密码保护 keystore 文件
• 立即删除或安全存储明文私钥文件
• 不要将 keystore 文件提交到版本控制系统

3.6.2 从私钥生成 Keystore

# 导入私钥并生成 keystore
cast wallet import --interactive --keystore <KEYSTORE目录> <账户名称>

# 从文件导入私钥
cast wallet import --keystore ~/keystore my-account --private-key-file private.key

3.6.3 其他钱包命令

cast wallet address [私钥]               # 从私钥计算地址
cast wallet sign [消息] [私钥]           # 使用私钥对消息签名
cast wallet vanity [前缀]                 # 生成带有特定前缀的地址
cast wallet verify [地址] [签名] [消息]   # 验证签名

3.6.4 使用 Keystore 发送交易

生成了 keystore 后，您可以在发送交易时使用它：

# 方法1：通过环境变量设置私钥（适用于测试）
export PRIVATE_KEY="your_private_key_here"
cast send --private-key $PRIVATE_KEY 0xContractAddress "function()"

# 方法2：从文件读取私钥（更安全）
cast send --private-key $(cat my-account.txt) 0xContractAddress "function()"

# 注意：在生产环境中，建议使用更安全的私钥管理方式
# 如硬件钱包、专门的密钥管理服务等

3.7 其他实用命令

cast rpc eth_blockNumber                  # 执行原始 JSON-RPC 请求
cast access-list <tx_hash>                # 为交易创建访问列表
cast run <tx_hash>                        # 在本地环境中运行已发布的交易，并打印跟踪
cast publish <raw_tx>                     # 向网络发布原始交易

四、实际应用示例

4.1 查询 DAI 代币总供应量

cast call 0x6b175474e89094c44da98b954eedeac495271d0f "totalSupply()(uint256)" --rpc-url https://eth-mainnet.alchemyapi.io/v2/your-api-key

4.2 在两个 Anvil 账户之间发送消息

cast send --private-key <Your_Private_Key> 0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc $(cast from-utf8 "hello world") --rpc-url http://127.0.0.1:8545/

4.3 查询最新区块信息

# 设置环境变量
export ETH_RPC_URL="https://eth-mainnet.alchemyapi.io/v2/your-api-key"

# 查询最新区块号（十六进制）
cast rpc eth_blockNumber

# 查询最新区块号（十进制）
cast block-number

# 查询特定区块详情
cast block 15769241 --json

4.4 生成并管理测试账户

# 1. 为测试环境生成新的 keystore
mkdir -p ~/test-keystores
cast wallet new ~/test-keystores test-account-1

# 2. 查看生成的地址
cast wallet address $(cat ~/test-keystores/test-account-1.txt)

# 3. 为账户充值（在测试网上）
# 从水龙头获取测试 ETH 到该地址

# 4. 使用该账户发送交易
cast send --private-key $(cat ~/test-keystores/test-account-1.txt) \
  0xContractAddress \
  "functionName()" \
  --rpc-url $SEPOLIA_RPC_URL

4.5 调试交易调用栈

cast run 0x20e7dda515f04ea6a787f68689e27bcadbba914184da5336204f3f36771f59f0 --rpc-url $RPC_URL

五、高级用法与技巧

5.1 使用 --legacy 参数

对于不支持 EIP-1559 的旧链或节点，需要添加 --legacy参数：

cast send --private-key $PRIVATE_KEY --legacy ...

5.2 交易模拟与调试

Cast 的 run命令可以模拟交易执行，帮助调试复杂的合约交互：

cast run <tx_hash> --rpc-url $RPC_URL -vvvv

5.3 批量查询与脚本化

由于 Cast 是命令行工具，可以轻松集成到 Shell 脚本中实现自动化：

#!/bin/bash

# 批量查询多个地址余额
ADDRESSES=("0xaddress1" "0xaddress2" "0xaddress3")

for addr in "${ADDRESSES[@]}"; do
  balance=$(cast balance $addr --ether)
  echo "地址 $addr 余额: $balance ETH"
done

5.4 与 Forge 结合使用

在 Foundry 项目中，Cast 常与 Forge 配合使用：

# 编译合约
forge build

# 部署合约并获取地址
deployed_addr=$(cast send --create out/MyContract.sol/MyContract.json --rpc-url $RPC_URL --private-key $PK)

# 调用部署的合约
cast call $deployed_addr "getValue()(uint256)" --rpc-url $RPC_URL

5.5 安全的私钥管理实践

# 最佳实践：使用临时环境变量，避免私钥留在 shell 历史中
PRIVATE_KEY=$(cat ~/secure-path/private-key.txt) cast send ...

# 或者使用子shell
(cd ~/project && PRIVATE_KEY=$(cat .env.private) cast send ...)

# 对于生产环境，考虑使用硬件钱包或专门的密钥管理服务
# Cast 目前不直接支持硬件钱包集成，但可以通过中间件实现

六、常见问题与故障排除

6.1 RPC 连接问题

• 错误：Error: RPC request failed
• 解决方案：检查 RPC URL 是否正确，网络连接是否正常，或尝试更换 RPC 提供商

6.2 交易失败

• 错误：Error: execution reverted
• 解决方案：检查合约地址、函数签名和参数是否正确，确保发送账户有足够余额支付 Gas 费

6.3 私钥格式错误

• 错误：Error: Invalid private key
• 解决方案：确保私钥是 64 字符的十六进制字符串（不带 0x 前缀）

6.4 Keystore 生成问题

• 错误：Error: Failed to generate keystore

• 解决方案：

  1. 确保目标目录有写入权限
  2. 检查磁盘空间是否充足
  3. 使用强密码（至少 12 个字符，包含大小写字母、数字和特殊符号）
  4. 在交互模式下运行：cast wallet new --interactive

6.5 Gas 费用估算

使用 --gas-limit和 --gas-price参数手动设置 Gas 参数：

cast send ... --gas-limit 300000 --gas-price 20gwei

七、最佳实践建议

1. 安全第一：永远不要在公共场合或版本控制系统中暴露私钥

2. 测试先行：在测试网（如 Sepolia、Goerli）充分测试后再部署到主网

3. 使用环境变量：将敏感信息（私钥、RPC URL）存储在环境变量中

4. 验证交易：发送交易后，使用 cast receipt确认交易状态

5. 利用 JSON 输出：使用 --json标志获取结构化数据，便于脚本处理

6. 组合命令：通过管道将多个 Cast 命令组合使用，实现复杂查询

7. keystore 管理：

   • 为不同的网络（主网、测试网、开发网）使用不同的 keystore
   • 定期备份 keystore 文件到安全的离线存储
   • 使用密码管理器管理 keystore 密码
   • 在测试环境中可以使用明文私钥文件，但生产环境必须使用加密的 keystore

八、资源与参考

• 官方文档：Foundry Book
• 中文文档：登链社区 Foundry 中文文档
• GitHub 仓库：foundry-rs/foundry
• 社区支持：Foundry Discord 频道、以太坊开发者论坛
• 安全指南：以太坊官方安全最佳实践

---

<!--EndFragment-->