Token Sender

I created this project as a tool to use during Urbe Campus. In my experience, faucets are usually crap so I decided to create a script to send a small amount of ETH to the students.

A Foundry project that includes a script to send 0.01 ETH to multiple addresses from a CSV file.

Features

• Reads Ethereum addresses from a CSV file
• Sends a small amount of ETH to each address
• Smart balance checking: Validates the sender's wallet balance before sending
• Includes comprehensive error handling and logging
• Supports any EVM-compatible network
• File system permissions configured for secure CSV reading

How It Works

The script:

1. Reads your private key from environment variables [BE SURE TO USE A TEST WALLET, DEAR PATRICK COLLINS: FORGIVE ME]
2. Derives your wallet address from the private key
3. Reads addresses from the addresses.csv file
4. Checks your wallet balance to ensure you have enough ETH
5. Sends 0.01 ETH to each address in the CSV
6. Logs all transactions with detailed information

Setup

1. Install Foundry (if not already installed):

   curl -L https://foundry.paradigm.xyz | bash
   foundryup

2. Install dependencies:

   forge install

3. Configure environment variables:

   cp env.example .env

   Edit .env and add your:

   • PRIVATE_KEY: Your wallet's private key (can be with or without 0x prefix)
   • RPC_URL: RPC endpoint for your target network

4. Prepare your addresses CSV:

   The addresses.csv file should have the following format:

   address
   0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6
   0x1234567890123456789012345678901234567890
   0xabcdefabcdefabcdefabcdefabcdefabcdefabcd
   

Usage

Quick Start (Recommended)

1. For local testing:

   ./test_local.sh

2. For production use:

   ./run_token_sender.sh

Manual Usage

For Local Testing (Anvil)

1. Start a local Anvil instance:

   anvil

2. Run the script on local network:

   forge script script/TokenSender.s.sol:TokenSender --rpc-url http://localhost:8545 --broadcast

For Testnet/Mainnet

1. Run the script on your target network:

   forge script script/TokenSender.s.sol:TokenSender --rpc-url $RPC_URL --broadcast

Important Notes

• Balance Check: The script automatically checks your wallet balance and calculates the total amount needed (0.01 ETH × number of addresses + gas fees)
• Gas Fees: The script will use the current gas price on the network
• Network Selection: Use appropriate RPC URLs for your target network (mainnet, testnet, etc.)
• Security: Never commit your .env file with real private keys
• File Permissions: The project is configured to allow reading the addresses.csv file securely

Scripts

The project includes two helper scripts to make usage easier:

test_local.sh

• Automatically starts an Anvil instance
• Sets up the environment for local testing
• Runs the token sender script
• Perfect for testing and development

run_token_sender.sh

• Validates your configuration
• Calculates total ETH needed
• Provides safety checks and confirmations
• Ideal for production use

Customization

You can modify the AMOUNT_PER_ADDRESS constant in script/TokenSender.s.sol to change the amount sent to each address:

uint256 constant AMOUNT_PER_ADDRESS = 0.01 ether; // Change this value

Error Handling

The script includes several safety checks:

• Wallet Balance Validation: Checks your wallet has sufficient ETH before sending
• Transaction Success Verification: Ensures each transfer succeeds before proceeding
• Detailed Logging: Shows sender address, balance, total amount needed, and each transaction
• File Access Security: Configured file permissions for secure CSV reading

Example Output

Sender address: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
Sender balance: 1000000000000000000000
Total amount needed: 30000000000000000
Number of addresses: 3
Sent 10000000000000000 ETH to 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6
Sent 10000000000000000 ETH to 0x1234567890123456789012345678901234567890
Sent 10000000000000000 ETH to 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd
Token sending completed!

Troubleshooting

Common Issues

1. "Insufficient balance" error: Make sure your wallet has enough ETH for all transfers + gas fees
2. "File not found" error: Ensure addresses.csv exists in the project root
3. "Private key parsing" error: Check that your private key is correctly formatted in the .env file

Testing

Run the test suite to verify everything works:

forge test