Skip to main content

QuickStart

Get up and running with EVVM Testnet Contracts in minutes using our interactive setup wizard. Deploy your EVVM virtual blockchain on your chosen host blockchain network.

Prerequisites​

Ensure you have the following installed:

1. Clone and Install​

git clone https://github.com/EVVM-org/Testnet-Contracts
cd Testnet-Contracts
make install

The make install command will:

  • Install npm dependencies
  • Compile contracts with IR optimization (--via-ir)

2. Environment Setup​

Create your .env file with required API keys:

# Copy the example and fill in your values
cp .env.example .env

Add your configuration:

You can get others in https://chainlist.org/

RPC_URL_ETH_SEPOLIA="https://0xrpc.io/sep"

RPC_URL_ARB_SEPOLIA="https://arbitrum-sepolia.therpc.io"

ETHERSCAN_API=your_etherscan_api_key

3. Secure Key Management​

Import your testnet private key securely using Foundry:

cast wallet import defaultKey --interactive
Security Note

This command will prompt you to enter your private key securely. The key will be encrypted and stored locally by Foundry. Never commit real private keys to version control.

4. Interactive Setup & Deployment​

Run the automated setup wizard:

./evvm-init.sh

The script will guide you through:

Administrator Configuration​

  • Admin address - Contract administrator with governance privileges
  • Golden Fisher address - Special sudo-like account with unrestricted golden staking privileges
  • Activator address - Controls system activation and feature flags
Golden Fisher Privileges

The Golden Fisher is a special account that operates like a "sudo" user in the EVVM staking system:

  • Direct Staking/Unstaking: Can perform staking and unstaking operations without any limits or restrictions
  • No Signature Required: Operations are executed directly without signature verification
  • Bypass All Constraints: Ignores normal staking rules, cooldown periods, and validation requirements
  • Administrative Control: Intended for system administration and emergency operations
  • Single Account: Only one Golden Fisher address can be configured per deployment

This account should be secured with the highest level of protection as it has unrestricted access to staking operations.

EVVM Metadata Configuration​

  • EVVM Name - Default: "EVVM" (your virtual blockchain's identity hosted on the selected network)
  • EVVM ID - Unique identifier for your EVVM instance (multiple EVVMs can be deployed on the same host blockchain)
  • Principal Token Name - Default: "Mate token" (the core ecosystem token)
  • Principal Token Symbol - Default: "MATE"

Advanced Configuration (Optional)​

  • Total Supply - Default: 2,033,333,333 × 10¹⁸ (total token economics)
  • Era Tokens - Default: 1,016,666,666.5 × 10¹⁸ (rewards pool for staking system)
  • Reward per operation - Default: 5 × 10¹⁸ (base reward for transaction processing)
Principal Token Address Configuration

The principalTokenAddress parameter is not included in the interactive setup wizard as it is an extremely advanced and sensitive configuration option.

If you need to specify a custom principal token address:

  1. Modify the deployment script directly in script/DeployTestnet.s.sol
  2. Update the principalTokenAddress field in the EvvmMetadata struct (currently set to 0x0000000000000000000000000000000000000001)

This option should only be used in very specific scenarios and requires deep understanding of the EVVM token architecture.

CRITICAL

Do NOT commit these changes to your repository as they will be discarded immediately

The interactive wizard will prompt you to select a deployment network:

Available Networks​

  • eth - Deploy EVVM on Ethereum Sepolia testnet (host blockchain)
  • arb - Deploy EVVM on Arbitrum Sepolia testnet (host blockchain) (default)
  • custom - Deploy EVVM on custom RPC URL (other EVM-compatible host blockchains)
CRITICAL

YOU MUST HAVE TOKENS IN THE NETWORK YOU WANT TO DEPLOY THE CONTRACTS FOR FAUCETS CHECK BELOW

Here is a list of public faucets that you can get the test tokens from: https://ethglobal.com/faucet/

https://cloud.google.com/application/web3/faucet/ethereum/sepolia https://www.alchemy.com/faucets/ethereum-sepolia https://faucets.chain.link/sepolia https://faucet.quicknode.com/ethereum/sepolia https://www.infura.io/zh/faucet/sepolia

https://www.alchemy.com/faucets/arbitrum-sepolia https://faucets.chain.link/arbitrum-sepolia https://faucet.quicknode.com/arbitrum/sepolia https://www.l2faucet.com/arbitrum https://learnweb3.io/faucets/arbitrum_sepolia/

Network Configuration​

The wizard will automatically handle host blockchain selection and deployment parameters based on your choice. Your EVVM virtual blockchain will be deployed as smart contracts on the selected host blockchain.

note

Error: Not all (5 / 6) contracts were verified!

You will get this error is totally fine, there's a library that's giving errors to verify

5. What Happens Next​

The evvm-init.sh script automatically:

  1. Validates Input - Ensures all addresses follow Ethereum format (0x + 40 hex characters) and numbers are valid

  2. Generates Configuration Files in the input/ directory:

  3. Displays Configuration Summary - Shows all entered values for confirmation

  4. Optional Immediate Deployment - Prompts to deploy contracts right after configuration

  5. Contract Deployment - Deploys the complete EVVM ecosystem on your chosen host blockchain using DeployTestnet.s.sol

  6. Contract Verification - Automatically verifies contracts on the host blockchain's block explorers using Etherscan API

6. Manual Deployment (Alternative)​

If you prefer manual control or want to deploy your EVVM virtual blockchain later:

# Deploy EVVM on Ethereum Sepolia (host blockchain)
make deployTestnet NETWORK=eth

# Deploy EVVM on Arbitrum Sepolia (host blockchain) (default)
make deployTestnet NETWORK=arb

# Deploy EVVM on custom EVM-compatible host blockchain
forge script script/DeployTestnet.s.sol:DeployTestnet \
  --rpc-url YOUR_RPC_URL \
  --account defaultKey \
  --broadcast \
  --verify \
  --etherscan-api-key $ETHERSCAN_API \
  -vvvvvv

Local Development​

For local testing with Anvil (local host blockchain):

# Start local host blockchain
make anvil

# Deploy EVVM to local host blockchain (in another terminal)
make deployLocalTestnet

7. Verify Your Deployment​

After deployment, check the broadcast/ directory for:

  • Transaction receipts - Detailed transaction information from the host blockchain
  • Deployed contract addresses - EVVM contract addresses on the host blockchain network
  • Gas usage reports - Deployment cost analysis on the host blockchain

What Gets Deployed​

The EVVM virtual blockchain ecosystem consists of four main smart contracts deployed on your chosen host blockchain:

  • Evvm.sol - Core virtual machine implementation with payment processing
  • NameService.sol - Domain name resolution and identity system
  • Staking.sol - Token staking, rewards mechanism, and fisher registration
  • Estimator.sol - Staking rewards estimation and calculation system

Understanding Your Deployment​

8. Register Your EVVM in the Registry​

After successfully deploying your EVVM virtual blockchain, you need to register it in the Registry EVVM Contract to obtain an official EVVM ID that other services can use to discover and interact with your deployment.

Why Register Your EVVM?​

The Registry EVVM Contract serves as the central directory for all EVVM deployments across testnets:

  • Official Recognition: Get an official EVVM ID for your virtual blockchain
  • Service Discovery: Allow other dApps and services to find your EVVM instance
  • Network Integration: Enable integration with EVVM ecosystem tools and services
  • Verification: Prove your deployment is legitimate and properly configured

Registration Process​

For most deployments, use the public registration function which automatically assigns IDs starting from 1000:

  1. Call the Registry Contract: Use the registerEvvm() function on the Registry EVVM Contract
  2. Provide Your Details:
    • chainId: The testnet chain ID where you deployed (e.g., 11155111 for Sepolia, 421614 for Arbitrum Sepolia)
    • evvmAddress: Your deployed EVVM contract address from the broadcast/DeployTestnet.s.sol/[chainId]/run-latest.json file
  3. Receive Your ID: The contract will assign you a unique EVVM ID (1000+) automatically

Registry Contract Location​

🔗 Official Registry EVVM Contract: View on Etherscan

  • Proxy Address: 0x389dC8fb09211bbDA841D59f4a51160dA2377832
  • Implementation: 0xC1ef02492F1A75bCdB20766B558f10D643f9d504
  • Network: Ethereum Sepolia Testnet
  • Pattern: EIP-1967 Transparent Proxy
CRITICAL REQUIREMENTS

MANDATORY FOR ALL DEPLOYMENTS: Regardless of which host blockchain you deployed your EVVM on (Sepolia, Arbitrum Sepolia, or any other testnet), you MUST register on the official Registry EVVM Contract located on Ethereum Sepolia.

ETH Sepolia Required: You need ETH Sepolia tokens to pay for the registration transaction gas fees, even if your EVVM is deployed on a different testnet.

Get ETH Sepolia tokens from these faucets:

Example Registration Call​

```solidity
// Find EVVM instances by ID
RegistryEvvm registry = RegistryEvvm(0x389dC8fb09211bbDA841D59f4a51160dA2377832);
Metadata memory evvmData = registry.getEvvmIdMetadata(1000); // Public EVVM ID

Finding Your EVVM Contract Address​

After deployment, find your EVVM contract address in the broadcast files:

# Navigate to your deployment broadcast directory
cd broadcast/DeployTestnet.s.sol/[CHAIN_ID]/

# Check the run-latest.json file for your EVVM contract address
cat run-latest.json | grep -A 5 '"contractName": "Evvm"'

Look for the contractAddress field in the transaction that deployed the "Evvm" contract.

Prerequisites for Registration​

Before registering, ensure:

  • ✅ ETH Sepolia Tokens: You have ETH Sepolia for gas fees (required even if your EVVM is on different testnet)
  • ✅ Chain ID Whitelisted: The testnet chain ID where your EVVM is deployed must be whitelisted by the Registry superUser
  • ✅ Unique Address: Your EVVM address hasn't been registered before on that specific chain
  • ✅ Valid Deployment: Your EVVM contract is properly deployed and verified on your chosen testnet
  • ✅ Correct Network: You're connected to Ethereum Sepolia network in your wallet for the registration transaction

Step-by-Step Registration Process​

  1. Switch to Ethereum Sepolia: Configure your wallet to connect to Ethereum Sepolia network
  2. Get ETH Sepolia: Obtain testnet ETH from the faucets listed above
  3. Find Your EVVM Address: Locate your deployed EVVM contract address in the broadcast files
  4. Call Registry Contract: Execute the registerEvvm() function with your details
  5. Verify Registration: Confirm your EVVM ID was assigned successfully
Whitelisted Testnets

Currently supported testnet chain IDs for EVVM registration:

  • Ethereum Sepolia: 11155111
  • Arbitrum Sepolia: 421614

Remember: The registration happens on Ethereum Sepolia, but you can register EVVMs deployed on any whitelisted testnet. If your deployment testnet isn't listed, contact the EVVM team to request chain ID whitelisting.

Using Your EVVM ID​

Once registered, your EVVM ID can be used by:

  • Frontend Applications: To connect to your specific EVVM instance
  • Service Integration: For Name Service, Staking, and Treasury operations
  • dApp Development: To target your virtual blockchain in smart contracts
  • Network Tools: For monitoring, analytics, and developer tools

Verification​

After registration, verify your EVVM is properly registered:

// Get your EVVM metadata
Metadata memory metadata = registry.getEvvmIdMetadata(myEvvmId);

// Verify it matches your deployment
assert(metadata.chainId == YOUR_CHAIN_ID);
assert(metadata.evvmAddress == YOUR_EVVM_ADDRESS);

You can also verify through the Registry's getter functions:

  • getEvvmIdMetadata(uint256 evvmID): Get registration details for your EVVM ID
  • getPublicEvvmIdActive(): See all public EVVM IDs (including yours)
  • isAddressRegistered(uint256 chainId, address evvmAddress): Confirm your address is registered
Reserved IDs

EVVM IDs 1-999 are reserved for official deployments managed by the superUser. Public registrations receive IDs starting from 1000. Do not attempt to register with reserved IDs.

9. Next Steps​

  • View deployment artifacts in broadcast/ directory
  • Check contract verification on the host blockchain's block explorer (Etherscan/Arbiscan)
  • Register your EVVM in the Registry EVVM Contract to get an official ID
  • Test your contracts using the provided test suite: make test
  • Monitor gas usage and optimize if needed: make seeSizes
  • Compile contracts for development: make compile

Ready to Build Services?​

With your EVVM virtual blockchain deployed, you can now create smart contract services that leverage the EVVM ecosystem:

  • How to Make a EVVM Service - Complete guide to building smart contracts within your EVVM instance
  • Learn about dual signature patterns, fisher incentives, and service integration
  • Connect your contracts to existing services like Name Service and Staking
  • Implement gasless transactions through the fisher network

10. Available Commands​

Run make help to see all available commands:

make install          # Install dependencies and compile EVVM contracts
make compile          # Compile EVVM contracts with IR optimization
make anvil           # Run Anvil local host blockchain
make deployLocalTestnet    # Deploy EVVM to local Anvil host blockchain
make deployTestnet NETWORK=<eth|arb>  # Deploy EVVM to public host blockchains
make seeSizes        # View EVVM contract sizes

11. Explore the EVVM Ecosystem​

Once your EVVM virtual blockchain contracts are deployed and registered on your chosen host blockchain, explore the complete EVVM documentation:

Core System Documentation​

Advanced Features​

Registry System​

Payment Functions​

  • Single Payments - Basic payment operations
  • Batch Payments - Multi-payment and dispersal functions
  • Withdrawal Functions - Move tokens from EVVM virtual blockchain back to host blockchain

Key Concepts​

Need Help?​

  • Configuration files - Review input/ directory if you need to modify settings
  • Environment setup - Check .env.example for required variables
  • Documentation - Explore the comprehensive sections above
  • Local testing - Use make anvil and make deployLocalTestnet for local host blockchain development
  • Abstract Blockchain Concepts - Start with the Introduction to understand EVVM's revolutionary virtual blockchain architecture

That's it! You now have a fully deployed and verified EVVM virtual blockchain environment running on your chosen host blockchain, ready for development and testing. Explore the ecosystem documentation to build powerful applications on the world's first abstract blockchain hosted on EVM-compatible networks.