|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a Monad-flavored Foundry template repository for Ethereum smart contract development. It's configured specifically for the Monad Testnet blockchain (chain ID 10143) and includes comprehensive verification testing scripts for multiple block explorers. |
| 8 | + |
| 9 | +## Key Commands |
| 10 | + |
| 11 | +### Build and Compilation |
| 12 | +```bash |
| 13 | +forge build # Build all contracts |
| 14 | +forge build --skip test # Build contracts, skip test files |
| 15 | +``` |
| 16 | + |
| 17 | +### Testing |
| 18 | +```bash |
| 19 | +forge test # Run all tests |
| 20 | +``` |
| 21 | + |
| 22 | +### Code Formatting |
| 23 | +```bash |
| 24 | +forge fmt # Format Solidity code |
| 25 | +``` |
| 26 | + |
| 27 | +### Gas Analysis |
| 28 | +```bash |
| 29 | +forge snapshot # Generate gas usage snapshots |
| 30 | +``` |
| 31 | + |
| 32 | +### Local Development |
| 33 | +```bash |
| 34 | +anvil # Start local Ethereum node |
| 35 | +``` |
| 36 | + |
| 37 | +### Deployment (Monad Testnet) |
| 38 | + |
| 39 | +1. Create keystore (one-time setup): |
| 40 | +```bash |
| 41 | +cast wallet import monad-deployer --private-key $(cast wallet new | grep 'Private key:' | awk '{print $3}') |
| 42 | +``` |
| 43 | + |
| 44 | +2. Check deployer address: |
| 45 | +```bash |
| 46 | +cast wallet address --account monad-deployer |
| 47 | +``` |
| 48 | + |
| 49 | +3. Deploy contracts: |
| 50 | +```bash |
| 51 | +forge create src/Counter.sol:Counter --account monad-deployer --broadcast |
| 52 | +``` |
| 53 | + |
| 54 | +4. Deploy with constructor arguments: |
| 55 | +```bash |
| 56 | +forge create src/Counter.sol:Counter --account monad-deployer --broadcast --constructor-args <constructor_arguments> |
| 57 | +``` |
| 58 | + |
| 59 | +### Contract Verification |
| 60 | + |
| 61 | +#### Standard verification (multiple explorers): |
| 62 | +```bash |
| 63 | +# Etherscan |
| 64 | +forge verify-contract --watch --chain 10143 <contract_address> src/Counter.sol:Counter --verifier etherscan --etherscan-api-key <api_key> |
| 65 | + |
| 66 | +# Monad Explorer (Sourcify) |
| 67 | +forge verify-contract <contract_address> src/Counter.sol:Counter --chain 10143 --verifier sourcify --verifier-url https://sourcify-api-monad.blockvision.org |
| 68 | + |
| 69 | +# Socialscan |
| 70 | +forge verify-contract <contract_address> src/Counter.sol:Counter --chain 10143 --watch --etherscan-api-key test --verifier-url https://api.socialscan.io/monad-testnet/v1/explorer/command_api/contract --verifier blockscout |
| 71 | +``` |
| 72 | + |
| 73 | +#### With constructor arguments: |
| 74 | +```bash |
| 75 | +forge verify-contract <contract_address> src/Counter.sol:Counter --chain 10143 --verifier sourcify --verifier-url https://sourcify-api-monad.blockvision.org --constructor-args <abi_encoded_constructor_arguments> |
| 76 | +``` |
| 77 | + |
| 78 | +### Verification Testing Scripts |
| 79 | + |
| 80 | +The repository includes two comprehensive testing scripts for automated verification testing: |
| 81 | + |
| 82 | +#### Basic Contract Verification Test: |
| 83 | +```bash |
| 84 | +bash script/testVerification.sh [contract_source_file] |
| 85 | +``` |
| 86 | +- Creates random contract variants with unique functions |
| 87 | +- Deploys and verifies on all three block explorers |
| 88 | +- Default: tests `src/Counter.sol:Counter` |
| 89 | + |
| 90 | +#### Proxy Contract Verification Test: |
| 91 | +```bash |
| 92 | +bash script/testSimpleProxyVerification.sh |
| 93 | +``` |
| 94 | +- Creates and deploys both implementation and proxy contracts |
| 95 | +- Tests verification of proxy patterns across all explorers |
| 96 | +- Provides block explorer links for manual verification |
| 97 | + |
| 98 | +## Network Configuration |
| 99 | + |
| 100 | +- **Chain ID**: 10143 (Monad Testnet) |
| 101 | +- **RPC URL**: https://testnet-rpc.monad.xyz |
| 102 | +- **Block Explorers**: |
| 103 | + - Monadscan: https://testnet.monadscan.com |
| 104 | + - Socialscan: https://monad-testnet.socialscan.io |
| 105 | + - Monad Explorer: https://testnet.monadexplorer.com |
| 106 | + |
| 107 | +## Architecture and Structure |
| 108 | + |
| 109 | +### Core Contracts |
| 110 | + |
| 111 | +- **Counter.sol**: Basic counter contract with increment/set functionality |
| 112 | +- **SimpleImplementation.sol**: Implementation contract for proxy pattern with ownership and initialization |
| 113 | +- **SimpleProxy.sol**: Custom proxy contract using EIP-1967 storage slots for upgradeable patterns |
| 114 | + |
| 115 | +### Script Organization |
| 116 | + |
| 117 | +- **script/Counter.s.sol**: Basic deployment script template |
| 118 | +- **script/testVerification.sh**: Comprehensive verification testing for single contracts |
| 119 | +- **script/testSimpleProxyVerification.sh**: Verification testing for proxy patterns |
| 120 | + |
| 121 | +### Dependencies |
| 122 | + |
| 123 | +- **forge-std**: Standard Foundry testing and scripting utilities |
| 124 | +- **openzeppelin-contracts**: OpenZeppelin contract library for security patterns |
| 125 | + |
| 126 | +### Configuration |
| 127 | + |
| 128 | +- **foundry.toml**: Configured for Monad Testnet with metadata settings optimized for verification |
| 129 | +- Metadata hash disabled (`metadata_hash = "none"`) to avoid IPFS dependencies |
| 130 | +- Literal content enabled (`use_literal_content = true`) for source code verification |
| 131 | + |
| 132 | +## Development Workflow |
| 133 | + |
| 134 | +1. Use the verification testing scripts frequently to ensure contract verification works across all block explorers |
| 135 | +2. The repository is specifically configured for Monad Testnet - change network settings in `foundry.toml` if targeting other chains |
| 136 | +3. Both basic contracts and proxy patterns are supported with dedicated testing infrastructure |
| 137 | +4. Keystore management is used instead of raw private keys for security |
| 138 | + |
| 139 | +## Troubleshooting |
| 140 | + |
| 141 | +- **Insufficient balance error**: Check deployer balance with `cast wallet address --account monad-deployer` |
| 142 | +- **Verification failures**: Use the testing scripts to diagnose issues across different block explorers |
| 143 | +- **Constructor argument issues**: Use `cast abi-encode` to properly encode constructor arguments for verification |
| 144 | + |
| 145 | +The verification testing scripts provide detailed output and cleanup temporary files automatically, making them safe for repeated use during development. |
0 commit comments