Foundry Cast Commands Reference

A comprehensive guide to Foundry's cast command-line tool for Ethereum blockchain interaction, debugging, and development.

Table of Contents

• Basic Setup
• Block & Chain Data
• Transaction Operations
• Account & Balance
• Contract Interaction
• Storage & State
• Utilities & Conversion
• Gas & Estimation
• Debugging & Analysis
• Advanced Operations
• Practical Examples

Basic Setup

RPC Connection

# Set default RPC endpoint (optional)
export ETH_RPC_URL="http://localhost:8545"

# Or use -r flag with each command
cast block-number -r localhost:8545
cast block-number --rpc-url https://mainnet.infura.io/v3/YOUR_KEY

Common RPC Endpoints

# Local nodes
-r localhost:8545     # Geth default
-r localhost:8546     # Reth default  
-r localhost:8551     # Auth RPC
-r localhost:8080     # Besu default

# Public endpoints
-r https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY
-r https://mainnet.infura.io/v3/YOUR_KEY
-r https://rpc.flashbots.net

Block & Chain Data

Block Information

# Get latest block number
cast block-number

# Get block by number (decimal)
cast block 18500000

# Get block by number (hex)
cast block 0x11a3dc0

# Get block by hash
cast block 0x1234abcd...

# Get full block with transactions
cast block --full 18500000

# Get block in JSON format
cast block 18500000 --json

# Get specific block field
cast block 18500000 --field gasUsed
cast block 18500000 --field timestamp

Chain Information

# Get chain ID
cast chain-id

# Get gas price
cast gas-price

# Get base fee (EIP-1559)
cast base-fee

# Get network name
cast client

Transaction Operations

Transaction Details

# Get transaction by hash
cast tx 0x1234abcd...

# Get transaction receipt
cast receipt 0x1234abcd...

# Get transaction logs
cast logs --from-block 18500000 --to-block 18500100

# Get transaction by block and index
cast tx --block 18500000 --index 0

Send Transactions

# Send ETH
cast send 0xRecipient --value 1ether --private-key 0xYourKey

# Send to contract
cast send 0xContract "transfer(address,uint256)" 0xRecipient 1000000000000000000 --private-key 0xYourKey

# Send with gas limit
cast send 0xContract "mint()" --gas-limit 200000 --private-key 0xYourKey

Account & Balance

Account Information

# Get ETH balance
cast balance 0x1234abcd...

# Get ETH balance at specific block
cast balance 0x1234abcd... --block 18500000

# Get account nonce
cast nonce 0x1234abcd...

# Get code (for contracts)
cast code 0x1234abcd...

# Get code size
cast codesize 0x1234abcd...

ENS Resolution

# Resolve ENS name to address
cast resolve-name vitalik.eth

# Reverse resolve address to ENS
cast lookup-address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Contract Interaction

Reading Contracts

# Call contract function (view/pure)
cast call 0xA0b86a33E6441E2A2a57D6F15b8F8d5d8b7A6dEB "totalSupply()"

# Call with parameters
cast call 0xA0b86a33E6441E2A2a57D6F15b8F8d5d8b7A6dEB "balanceOf(address)" 0x1234abcd...

# Call at specific block
cast call 0xA0b86a33E6441E2A2a57D6F15b8F8d5d8b7A6dEB "totalSupply()" --block 18500000

# Decode output
cast call 0xA0b86a33E6441E2A2a57D6F15b8F8d5d8b7A6dEB "name()" | cast to-ascii

Contract Creation

# Predict contract address
cast compute-address 0xDeployer --nonce 42

# Create2 address prediction
cast create2 --starts-with 0x000 --deployer 0xDeployer --init-code 0x608060405...

Storage & State

Storage Slots

# Read storage slot
cast storage 0x1234abcd... 0

# Read multiple slots
cast storage 0x1234abcd... 0x1
cast storage 0x1234abcd... 0x2

# Storage at specific block
cast storage 0x1234abcd... 0 --block 18500000

State Access

# Get proof for storage slot
cast proof 0x1234abcd... 0x0 --block 18500000

# Get multiple proofs
cast proof 0x1234abcd... 0x0 0x1 0x2 --block 18500000

Utilities & Conversion

Number Conversions

# Decimal to hex
cast to-hex 255
cast to-hex 18500000

# Hex to decimal  
cast to-dec 0xff
cast to-dec 0x11a3dc0

# Unit conversions
cast to-wei 1 ether        # 1000000000000000000
cast from-wei 1000000000000000000  # 1.000000000000000000

# Other units
cast to-wei 1 gwei         # 1000000000
cast to-wei 1 kwei         # 1000

Data Formatting

# Bytes32 padding
cast to-bytes32 0x1234

# ASCII conversion
cast to-ascii 0x48656c6c6f  # "Hello"
cast from-ascii "Hello"     # 0x48656c6c6f

# UTF-8 conversion
cast to-utf8 0x48656c6c6f

Hashing & Encoding

# Keccak256 hash
cast keccak "Hello World"

# Hash data
cast keccak 0x1234abcd

# ABI encoding
cast abi-encode "transfer(address,uint256)" 0x1234abcd... 1000000000000000000

# ABI decoding
cast abi-decode "transfer(address,uint256)" 0xa9059cbb000000000000000000000000...

Gas & Estimation

Gas Operations

# Estimate gas
cast estimate 0xContract "mint()" --from 0xSender

# Estimate with value
cast estimate 0xContract "payableFunction()" --value 1ether --from 0xSender

# Get gas price recommendations
cast gas-price
cast base-fee

# Calculate transaction cost
cast tx 0x1234abcd... --field gasUsed
cast tx 0x1234abcd... --field gasPrice

Debugging & Analysis

Block Analysis

# Get all transaction hashes in block
cast block --full 18500000 --json | jq '.transactions[].hash'

# Count transactions in block
cast block --full 18500000 --json | jq '.transactions | length'

# Get transaction types in block
cast block --full 18500000 --json | jq '.transactions[].type'

# Analyze gas usage
cast block 18500000 --field gasUsed
cast block 18500000 --field gasLimit

Transaction Analysis

# Get transaction trace
cast run 0x1234abcd...

# Decode transaction input
cast 4byte 0xa9059cbb  # Function selector lookup

# Get transaction value in ether
cast tx 0x1234abcd... --field value | cast from-wei

Event Analysis

# Get logs for specific event
cast logs --address 0xContract \
  --sig "Transfer(address indexed,address indexed,uint256)" \
  --from-block 18500000

# Decode event logs
cast logs --address 0xA0b86a33E6441E2A2a57D6F15b8F8d5d8b7A6dEB \
  --sig "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" \
  --from-block 18500000

Advanced Operations

Wallet Operations

# Generate new wallet
cast wallet new

# Get address from private key
cast wallet address --private-key 0xYourKey

# Sign message
cast wallet sign "Hello World" --private-key 0xYourKey

# Verify signature
cast wallet verify --address 0xSigner "Hello World" 0xSignature

Multi-call Operations

# Batch multiple calls
cast multicall --calls '[
  ["0xContract1", "balanceOf(address)", "0x1234..."],
  ["0xContract2", "totalSupply()"]
]'

Access Lists

# Create access list
cast access-list 0xContract "function()" --from 0xSender

# Estimate with access list
cast estimate 0xContract "function()" --access-list accesslist.json

Practical Examples

Debugging Failed Transactions

# 1. Get transaction details
cast tx 0xFailedTxHash

# 2. Get receipt for error info
cast receipt 0xFailedTxHash

# 3. Simulate the transaction
cast call 0xContract "function()" --from 0xSender --block $((block-1))

# 4. Trace execution
cast run 0xFailedTxHash --trace

Token Analysis

# ERC-20 token analysis
TOKEN=0xA0b86a33E6441E2A2a57D6F15b8F8d5d8b7A6dEB

# Get token info
cast call $TOKEN "name()" | cast to-ascii
cast call $TOKEN "symbol()" | cast to-ascii  
cast call $TOKEN "decimals()"
cast call $TOKEN "totalSupply()"

# Get balance
cast call $TOKEN "balanceOf(address)" 0x1234abcd...

Contract Verification

# Verify contract exists
cast code 0xContract

# Check if address is contract
if [[ $(cast code 0xAddress) == "0x" ]]; then
  echo "EOA (Externally Owned Account)"
else
  echo "Contract"
fi

# Get creation info
cast creation 0xContract

Gas Optimization Analysis

# Compare gas usage between blocks
for block in 18500000 18500001 18500002; do
  echo "Block $block: $(cast block $block --field gasUsed)"
done

# Analyze transaction gas efficiency
cast tx 0x1234abcd... --field gasUsed
cast estimate 0xContract "function()" # Compare with actual usage

Multi-Chain Operations

# Compare data across chains
cast block-number -r https://mainnet.infura.io/v3/KEY      # Ethereum
cast block-number -r https://polygon-rpc.com              # Polygon  
cast block-number -r https://arb1.arbitrum.io/rpc         # Arbitrum

# Cross-chain balance check
ADDR=0x1234abcd...
cast balance $ADDR -r https://mainnet.infura.io/v3/KEY
cast balance $ADDR -r https://polygon-rpc.com

Batch Processing

# Process multiple transactions
for tx in tx1 tx2 tx3; do
  echo "Processing $tx"
  cast receipt $tx --field status
done

# Batch block analysis
for block in {18500000..18500010}; do
  echo "Block $block: $(cast block $block --field timestamp)"
done

Environment Variables

# Set default values to avoid repetitive flags
export ETH_RPC_URL="http://localhost:8545"
export ETH_FROM="0xYourDefaultAddress"  
export ETH_PRIVATE_KEY="0xYourPrivateKey"
export ETH_CHAIN_ID=1

# Now you can use cast without specifying these repeatedly
cast balance 0x1234abcd...  # Uses ETH_RPC_URL automatically

Tips & Best Practices

Performance

# Use local node for faster responses
cast block-number -r localhost:8545

# Cache frequently used data
LATEST=$(cast block-number)
echo "Latest block: $LATEST"

Safety

# Always verify before sending transactions
cast call 0xContract "function()" --from $ETH_FROM  # Simulate first
cast send 0xContract "function()" --private-key $ETH_PRIVATE_KEY  # Then send

# Use --dry-run for testing
cast send 0xContract "function()" --dry-run

Debugging Workflow

# 1. Check connectivity
cast block-number

# 2. Verify contract
cast code 0xContract

# 3. Test function call
cast call 0xContract "function()"

# 4. Estimate gas
cast estimate 0xContract "function()"

# 5. Send transaction
cast send 0xContract "function()" --gas-limit 200000

This reference covers the most commonly used cast commands for Ethereum development, debugging, and blockchain analysis. For the complete list of commands and options, run cast --help or cast <command> --help.