Pulsechain Fork - Local Development Environment

This project provides a local Pulsechain fork using Foundry/Anvil for testing and development purposes. It creates a local blockchain that mirrors the state of Pulsechain mainnet, allowing you to test contracts and transactions without using real PLS tokens.

🚀 Quick Start

Prerequisites

• Foundry installed
• Node.js (optional, for additional tooling)

Installation

1. Clone this repository (if not already done)

2. Install dependencies:

   forge install

3. Copy the environment file:

   cp env.example .env

Starting the Fork

Use the provided script to start a local Pulsechain fork:

./start-fork.sh

This will start an Anvil instance that forks Pulsechain mainnet with the following configuration:

• Local RPC URL: http://127.0.0.1:8545
• Chain ID: 369 (Pulsechain mainnet)
• Accounts: 10 pre-funded accounts
• Balance: 1000 PLS per account
• Gas Limit: 30M
• Host: 0.0.0.0 (accessible from other machines)

🔧 Configuration

Foundry Configuration

The foundry.toml file is configured with:

• Pulsechain RPC endpoints
• Fork settings
• Compiler optimizations
• Test configurations

Environment Variables

Edit the .env file to customize:

• RPC URLs
• API keys
• Private keys (for testing only)
• Fork block number
• Anvil settings

📋 Usage Examples

Running the Fork Test Script

Test that your fork is working correctly:

forge script script/StartFork.s.sol --fork-url http://127.0.0.1:8545

Deploying Contracts

Deploy contracts to the local fork:

forge script script/YourScript.s.sol --fork-url http://127.0.0.1:8545 --broadcast

Running Tests

Run tests against the fork:

forge test --fork-url http://127.0.0.1:8545

Interacting with Existing Contracts

Since this is a fork of Pulsechain, all existing contracts and their state are available. You can interact with them using their deployed addresses.

🌐 Network Information

Pulsechain Mainnet

• RPC URL: https://rpc.pulsechain.com
• Chain ID: 369
• Block Explorer: PulseScan

Pulsechain Testnet

• RPC URL: https://rpc.v4.testnet.pulsechain.com
• Chain ID: 943
• Block Explorer: Testnet PulseScan

🔍 Useful Commands

Foundry Commands

# Build contracts
forge build

# Run tests
forge test

# Format code
forge fmt

# Get gas reports
forge test --gas-report

# Deploy and verify
forge script script/Deploy.s.sol --rpc-url pulsechain --broadcast --verify

# Check contract size
forge build --sizes

Anvil Fork Commands

# Start fork with specific block
anvil --fork-url https://rpc.pulsechain.com --fork-block-number 12345678

# Start fork with more accounts
anvil --fork-url https://rpc.pulsechain.com --accounts 20

# Start fork with custom balance
anvil --fork-url https://rpc.pulsechain.com --balance 10000

🛠 Project Structure

├── src/               # Contract source files
├── test/              # Test files
├── script/            # Deployment and utility scripts
├── lib/               # Dependencies (forge-std)
├── foundry.toml       # Foundry configuration
├── start-fork.sh      # Fork startup script
├── env.example        # Environment variables template
└── README.md          # This file

🔒 Security Notes

• Never use real private keys with actual funds in this development environment
• The default private key in env.example is a well-known test key
• This fork is for development and testing purposes only
• Always test on testnets before mainnet deployment

🤝 Contributing

Feel free to submit issues and enhancement requests!

📄 License

This project is licensed under MIT License.

🆘 Troubleshooting

Common Issues

1. Fork fails to start: Check your internet connection and Pulsechain RPC availability
2. Out of gas errors: Increase gas limit in the start script
3. Connection refused: Ensure Anvil is running and accessible on the specified port

Getting Help

• Foundry Documentation
• Pulsechain Documentation
• Anvil Documentation

---

Happy Forking! 🍴⛓️