> For the complete documentation index, see [llms.txt](https://docs.xrpl-commons.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xrpl-commons.org/evm-sidechain/set-up-an-evm-project.md). # Set up a Foundry project This guide will walk you through setting up an EVM project on the XRPL sidechain using Foundry, a powerful toolkit for Ethereum application development. ## Part 1: Installing Foundry Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust. It consists of four main tools: * **Forge**: Ethereum testing framework * **Cast**: Swiss army knife for interacting with EVM smart contracts * **Anvil**: Local Ethereum node for development * **Chisel**: Fast, utilitarian, and verbose solidity REPL ### Prerequisites Before installing Foundry, ensure you have: * A terminal application (Git BASH or WSL for Windows users) * Internet connection for downloading the installer ### Installation Methods #### Option 1: Using Foundryup (Recommended) Foundryup is the official installer for the Foundry toolchain and the easiest way to get started. 1. **Install Foundryup** Open your terminal and run: ```bash curl -L https://foundry.paradigm.xyz | bash ``` 2. **Follow the on-screen instructions** to complete the installation 3. **Install Foundry tools** Run the following command to install the latest stable version: ```bash foundryup ``` For the latest nightly build (with newest features), use: ```bash foundryup --version nightly ``` #### Option 2: Building from Source If you prefer to build from source or need a custom configuration: 1. **Install Rust** First, install Rust using rustup: ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` 2. **Update Rust** (if already installed) ```bash rustup update stable ``` 3. **Install via Cargo** ```bash cargo install --git https://github.com/foundry-rs/foundry --profile release --locked forge cast chisel anvil ``` #### Option 3: Using Docker For containerized development: ```bash docker pull ghcr.io/foundry-rs/foundry:latest ``` ### Verification After installation, verify that Foundry is properly installed by checking the version: ```bash forge --version ``` You should see version information for Forge, confirming the installation was successful. ### Platform-Specific Notes * **Windows**: Use Git BASH or WSL as your terminal. PowerShell and Command Prompt are not currently supported by foundryup * **macOS**: Standard terminal works perfectly * **Linux**: Any terminal emulator will work ### Troubleshooting If you encounter issues during installation: 1. **Check your internet connection** 2. **Ensure you have the latest version of your terminal** 3. **For Windows users**: Make sure you're using Git BASH or WSL 4. **Refer to the** [**Foundry FAQ**](https://book.getfoundry.sh/faq) for additional help ### Security Note Foundry binaries are verified using GitHub artifact attestations to ensure integrity and authenticity. The installer automatically verifies these attestations during installation. *** ✅ **Checkpoint**: You now have Foundry installed and ready to use for XRPL sidechain development! ## Part 2: Initializing a Foundry Project Now that Foundry is installed, let's create a new project and understand the project structure. ### Creating a New Project Initialize a new Foundry project using the `forge init` command: ```bash forge init my-xrpl-project cd my-xrpl-project ``` This creates a new directory with a complete Foundry project structure. ### Understanding the Project Structure After initialization, your project will have the following structure: ``` my-xrpl-project/ ├── foundry.toml # Foundry configuration file ├── src/ # Smart contracts directory │ └── Counter.sol # Example contract ├── script/ # Deployment and interaction scripts │ └── Counter.s.sol # Example deployment script ├── test/ # Test files │ └── Counter.t.sol # Example test file └── lib/ # Dependencies (managed by Soldeer) ``` #### Key Directories Explained * **`/src`**: Contains your smart contracts written in Solidity * **`/test`**: Contains test files for your contracts (typically with `.t.sol` extension) * **`/script`**: Contains deployment scripts and other automation scripts * **`/lib`**: Contains external dependencies managed by Soldeer package manager ### Setting Up Soldeer Package Manager Soldeer is Foundry's native package manager for handling smart contract dependencies. Let's configure it for your project: 1. **Initialize Soldeer** ```bash forge soldeer init ``` 2. **Verify Soldeer Configuration** Check that `foundry.toml` now includes Soldeer configuration: ```bash cat foundry.toml ``` You should see something like: ```toml [profile.default] src = "src" out = "out" libs = ["lib"] [dependencies] # Dependencies will be listed here ``` ### Building Your Project Compile the smart contracts to ensure everything is set up correctly: ```bash forge build ``` You should see output indicating successful compilation of the example Counter contract. ### Running Tests Run the included tests to verify the setup: ```bash forge test ``` This will execute all tests in the `/test` directory and show the results. ### Understanding the Foundry Tools Your project now has access to all Foundry tools: | Tool | Purpose | | ---------- | ------------------------------------------------------------------- | | **forge** | Build, test, debug, deploy and verify smart contracts | | **anvil** | Run a local Ethereum development node with forking capabilities | | **cast** | Interact with contracts, send transactions, and retrieve chain data | | **chisel** | Fast Solidity REPL for rapid prototyping and debugging | ### Adding Dependencies with Soldeer To add external smart contract libraries (like OpenZeppelin), use Soldeer: ```bash # Example: Add OpenZeppelin contracts forge soldeer install @openzeppelin/contracts@5.0.0 ``` Dependencies will be automatically added to your `foundry.toml` and downloaded to the `/lib` directory. ### Customizing Your Project You can customize various aspects of your project by editing `foundry.toml`: ```toml [profile.default] src = "src" out = "out" libs = ["lib"] optimizer = true optimizer_runs = 200 via_ir = true [rpc_endpoints] xrpl_devnet = "https://rpc-evm-sidechain.xrpl.org" ``` *** ✅ **Checkpoint**: You now have a fully initialized Foundry project with proper structure and dependency management! ## Part 3: Setting Up Your Environment Before deploying contracts to the XRPL sidechain, you need to set up a wallet and obtain test tokens for deployment. ### Installing MetaMask MetaMask is a popular Ethereum wallet that works with XRPL EVM sidechain. Follow these steps to install and set it up: 1. **Install MetaMask** * Visit [metamask.io](https://metamask.io/) * Click "Download" and choose your browser * Install the browser extension * Create a new wallet or import an existing one 2. **Create a New Wallet** (if you don't have one) * Click "Create a wallet" * Set a strong password * **IMPORTANT**: Write down your seed phrase securely and never share it * Confirm your seed phrase ### Adding XRPL EVM Sidechain to MetaMask Configure MetaMask to connect to the XRPL EVM sidechain: 1. **Open MetaMask** and click the network dropdown (usually shows "Ethereum Mainnet") 2. **Add Custom Network** with these details: ``` Network Name: XRPL EVM Sidechain New RPC URL: https://rpc-evm-sidechain.xrpl.org Chain ID: 1440002 Currency Symbol: XRP Block Explorer URL: https://evm-sidechain.xrpl.org ``` 3. **Save** the network configuration 4. **Switch** to the XRPL EVM Sidechain network ### Getting Your Private Key **⚠️ Security Warning**: Never share your private key with anyone. Only use it for development and testing purposes. 1. **Open MetaMask** 2. **Click the three dots** next to your account name 3. **Select "Account Details"** 4. **Click "Show private key"** 5. **Enter your password** 6. **Copy the private key** (you'll need this for deployment) ### Getting Test Tokens from the Faucet You need test XRP tokens to deploy contracts on the XRPL sidechain: 1. **Visit the XRPL EVM Faucet**: 2. **Connect Your Wallet** * Click "Connect Wallet" * Select MetaMask * Approve the connection 3. **Request Test Tokens** * Make sure you're on the XRPL EVM Sidechain network * Your wallet address should be displayed * Click "Send me XRP" or the equivalent button * Wait for the transaction to complete 4. **Verify Token Receipt** * Check your MetaMask balance * You should see test XRP tokens in your wallet ### Setting Up Environment Variables Create a `.env` file in your project root to store your private key securely: 1. **Create the file**: ```bash touch .env ``` 2. **Add your private key**: ```env PRIVATE_KEY=your_private_key_here RPC_URL=https://rpc.testnet.xrplevm.org ``` 3. **Add `.env` to `.gitignore`** (if not already present): ```bash echo ".env" >> .gitignore ``` ### Configuring Foundry for XRPL Update your `foundry.toml` to include XRPL-specific settings: ```toml [profile.default] src = "src" out = "out" libs = ["lib"] optimizer = true optimizer_runs = 200 [rpc_endpoints] xrpl = "https://rpc.testnet.xrplevm.org" [etherscan] xrpl = { key = "your_api_key_if_available", url = "https://evm-sidechain.xrpl.org/api" } ``` ### Testing Your Setup Verify your environment is ready: 1. **Check your balance**: ```bash cast balance --rpc-url https://rpc.testnet.xrplevm.org YOUR_WALLET_ADDRESS ``` 2. **Load environment variables** (if using .env): ```bash source .env ``` 3. **Test connection**: ```bash cast block-number --rpc-url $RPC_URL ``` ### Security Best Practices * **Never commit your private key** to version control * **Use environment variables** for sensitive data * **Use separate wallets** for development and production * **Regularly backup** your seed phrase securely * **Consider using hardware wallets** for production deployments *** ✅ **Checkpoint**: Your environment is now configured with MetaMask, test tokens, and proper security setup! ## Part 4: Deploying Your Smart Contract Now that your environment is set up, let's deploy the example Counter contract to the XRPL EVM sidechain using the `forge create` command. ### Understanding the Counter Contract First, let's look at the Counter contract in `src/Counter.sol`: ```solidity // SPDX-License-Identifier: UNLICENSED pragma solidity ^0.8.13; contract Counter { uint256 public number; function setNumber(uint256 newNumber) public { number = newNumber; } function increment() public { number++; } } ``` This simple contract stores a number and provides functions to set and increment it. ### Deploying with forge create The `forge create` command allows you to deploy a single contract directly without deployment scripts. #### Basic Deployment Command ```bash forge create src/Counter.sol:Counter \ --rpc-url https://rpc.testnet.xrplevm.org \ --private-key $PRIVATE_KEY \ --broadcast ``` #### Using Environment Variables For better security, load your environment variables first: ```bash source .env forge create src/Counter.sol:Counter \ --rpc-url $RPC_URL \ --private-key $PRIVATE_KEY \ --broadcast ``` #### Using Foundry Configuration If you configured the RPC endpoint in `foundry.toml`, you can use: ```bash forge create src/Counter.sol:Counter \ --rpc-url xrpl \ --private-key $PRIVATE_KEY \ --broadcast ``` ### Understanding Deployment Output After successful deployment, you'll see output like: ``` [⠢] Compiling... [⠆] Compiling 1 files with 0.8.19 [⠰] Solc 0.8.19 finished in 1.23s Compiler run successful! Deployer: 0xa735b3c25f... Deployed to: 0x4054415432... Transaction hash: 0x6b4e0ff93a... ``` **Key Information**: * **Deployer**: Your wallet address * **Deployed to**: Your contract's address on the blockchain * **Transaction hash**: Reference for the deployment transaction ### Deploying Contracts with Constructor Arguments If your contract has constructor parameters, use the `--constructor-args` flag: ```solidity // Example contract with constructor contract MyToken { constructor(string memory name, string memory symbol, uint256 supply) { // constructor logic } } ``` Deploy with arguments: ```bash forge create src/MyToken.sol:MyToken \ --rpc-url $RPC_URL \ --private-key $PRIVATE_KEY \ --broadcast \ --constructor-args "MyToken" "MTK" 1000000 ``` ### Dry Run Deployment Test your deployment without broadcasting to the network: ```bash forge create src/Counter.sol:Counter \ --rpc-url $RPC_URL \ --private-key $PRIVATE_KEY # Note: No --broadcast flag ``` This simulates the deployment and shows gas estimates without spending real tokens. ### Verifying Your Deployment 1. **Check deployment on block explorer**: * Visit * Search for your contract address * View the contract details 2. **Interact with your contract using Cast**: ```bash # Set your contract address CONTRACT_ADDRESS="your_deployed_contract_address" # Get the current counter value (should be 0) cast call $CONTRACT_ADDRESS "number()" --rpc-url $RPC_URL # Increment the counter cast send $CONTRACT_ADDRESS "increment()" \ --rpc-url $RPC_URL \ --private-key $PRIVATE_KEY # Check the new value (should be 1) cast call $CONTRACT_ADDRESS "number()" --rpc-url $RPC_URL # Set a specific number cast send $CONTRACT_ADDRESS "setNumber(uint256)" 42 \ --rpc-url $RPC_URL \ --private-key $PRIVATE_KEY ``` ### Contract Verification (Optional) If the XRPL EVM sidechain supports contract verification, you can verify your contract: ```bash forge verify-contract \ --chain-id 1440002 \ --watch \ --verifier blockscout \ --verifier-url https://evm-sidechain.xrpl.org/api \ $CONTRACT_ADDRESS \ src/Counter.sol:Counter ``` ### Deployment Best Practices 1. **Always test locally first**: ```bash # Start local Anvil node anvil # Deploy to local node (in another terminal) forge create src/Counter.sol:Counter \ --rpc-url http://127.0.0.1:8545 \ --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \ --broadcast ``` 2. **Check gas costs before deployment**: ```bash # Dry run to see gas estimates forge create src/Counter.sol:Counter --rpc-url $RPC_URL ``` 3. **Keep track of deployed contracts**: * Save contract addresses in a deployment log * Document which version was deployed when * Keep constructor arguments for reference ### Troubleshooting Common Issues 1. **Insufficient Funds**: * Check your balance: `cast balance YOUR_ADDRESS --rpc-url $RPC_URL` * Get more test tokens from the faucet if needed 2. **Private Key Format**: * Ensure your private key starts with `0x` * Check for any extra spaces or characters 3. **Network Issues**: * Verify the RPC URL is correct * Check if the XRPL EVM sidechain is operational 4. **Compilation Errors**: * Run `forge build` first to check for compilation issues * Ensure all dependencies are properly installed ### Using Legacy Transactions If you encounter EIP-1559 issues, use the `--legacy` flag: ```bash forge create src/Counter.sol:Counter \ --rpc-url $RPC_URL \ --private-key $PRIVATE_KEY \ --broadcast \ --legacy ``` *** 🎉 **Congratulations!** You have successfully deployed your first smart contract to the XRPL EVM sidechain using Foundry! Your contract is now live and ready for interaction.