Skip to main content

QuickStart

Get up and running with EVVM Testnet Contracts in minutes using our interactive deployment wizard. Deploy your EVVM virtual blockchain on your chosen host blockchain network with just three simple commands: clone, install, and run the wizard.

Quick Start Options​

Choose your path based on what you want to achieve:

Option A: Building Services on Existing EVVM​

Perfect if you want to create smart contracts that interact with already deployed EVVM instances.

Simply install the library and start building:

# Install via NPM
npm install @evvm/testnet-contracts

# OR install via Forge  
forge install EVVM-org/Testnet-Contracts

What you get: Access to all EVVM interfaces and contracts to build services that interact with live EVVM instances on testnets.

Next steps: Jump to Library Usage section below.

Option B: Deploy Your Own Complete EVVM Instance​

Perfect if you want to create your own virtual blockchain with custom tokens and governance.

Follow the complete deployment process below:

What you get: Your own virtual blockchain with custom tokens, domain system, staking rewards, and treasury management - all deployed and verified on public testnets.

Next steps: Jump to Deploy Your Own EVVM section below.

Library Usage​

If you chose Option A above, here's how to use EVVM contracts as a library in your project:

NPM Installation​

npm install @evvm/testnet-contracts

Forge Installation​

forge install EVVM-org/Testnet-Contracts

After installing with Foundry, add the following to your foundry.toml file to configure the library paths correctly:

[profile.default]
remappings = [
    "@evvm/testnet-contracts/=lib/Testnet-Contracts/src/",
]

Create Your Service​

Check out How to Create an EVVM Service for detailed development guides.

Deploy Your Own EVVM​

If you chose Option B above, follow this streamlined deployment process to create your own virtual blockchain:

Prerequisites​

The deployment wizard will automatically validate that you have the required tools 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
  • Initialize git submodules
  • Compile contracts with IR optimization (--via-ir)

2. Environment Setup​

Create your .env file with required API keys and RPC URLs:

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

Add your configuration (you can get more RPC URLs from 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
IMPORTANT: No Private Keys in .env

The .env file should ONLY contain:

  • RPC URLs for blockchain networks
  • API keys for block explorers (Etherscan, Arbiscan)

NEVER store private keys in the .env file. Private keys will be managed securely through Foundry's encrypted keystore in the next step.

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 or store them in .env files.

4. Interactive Deployment Wizard​

Run the automated deployment wizard:

npm run wizard

This interactive TypeScript wizard will guide you through the entire deployment process with a modern, user-friendly interface.

What the Wizard Does​

The wizard automates the complete deployment process:

  1. Prerequisites Validation - Checks that Foundry, Git, and Node.js are properly installed
  2. Git Submodule Initialization - Ensures all dependencies are properly configured
  3. Environment Setup - Guides you through RPC URL and API key configuration
  4. Wallet Selection - Lists available Foundry keystores and helps you select the deployment account
  5. Interactive Configuration - Prompts for all deployment parameters (see sections below)
  6. Automatic Deployment - Deploys all contracts with optimized settings
  7. Contract Verification - Automatically verifies contracts on block explorers
  8. Deployment Summary - Provides contract addresses and explorer links
  9. Registry Registration - Optionally registers your EVVM in the Registry EVVM Contract

Wizard Features​

  • RPC Fallback System: Includes 5 backup RPC endpoints per network for 99%+ deployment success
  • Input Validation: Ensures all addresses and values are properly formatted
  • Network Selection: Choose from Ethereum Sepolia, Arbitrum Sepolia, or custom RPC
  • Configuration Summary: Review all settings before deployment
  • Automatic File Generation: Creates configuration files in input/ directory

The wizard 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 the Testnet repository as they will be discarded immediately

Network Selection​

The wizard will prompt you to select a deployment network:

  • Ethereum Sepolia - Deploy EVVM on Ethereum Sepolia testnet (host blockchain)
  • Arbitrum Sepolia - Deploy EVVM on Arbitrum Sepolia testnet (host blockchain)
  • Custom RPC - Deploy EVVM on any EVM-compatible blockchain using a custom RPC URL
CRITICAL: Testnet Tokens Required

You must have testnet tokens for the network where you want to deploy your EVVM contracts. These tokens are free but required for paying gas fees during deployment.

Get testnet tokens from these public faucets:

Ethereum Sepolia:

Arbitrum Sepolia:

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

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

This warning is normal and expected. One library dependency cannot be automatically verified on the block explorer, but this doesn't affect your EVVM functionality. All main contracts will be verified successfully.

5. What Happens During Deployment​

The npm run wizard command automatically:

  1. Validates Prerequisites - Checks that Foundry, Git, and Node.js are properly installed with correct versions

  2. Initializes Dependencies - Ensures git submodules and npm packages are up to date

  3. Configures Environment - Guides you through RPC URLs and API key setup with fallback options

  4. Collects Configuration - Interactively prompts for administrator addresses, EVVM metadata, and token parameters

  5. Generates Configuration Files in the input/ directory:

  6. Displays Configuration Summary - Shows all entered values for your review and confirmation

  7. Deploys Contracts - Automatically deploys the complete EVVM ecosystem on your chosen host blockchain using DeployTestnet.s.sol

  8. Verifies Contracts - Automatically verifies all contracts on the host blockchain's block explorers using Etherscan API

  9. Provides Deployment Summary - Shows deployed contract addresses with direct links to block explorers

  10. Assists with Registry Registration - Optionally helps you register your EVVM in the Registry EVVM Contract

6. Manual Deployment (Alternative)​

If you prefer manual control or need to customize the deployment process beyond what the wizard provides, you can still use the traditional deployment methods:

Environment Setup for Manual Deployment​

First, create and configure your .env file:

cp .env.example .env

Add your RPC URLs and API keys (get more from 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

Manual Deployment Commands​

# 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
Configuration Files Required

For manual deployment, you must first create the configuration files in the input/ directory:

  • address.json - Administrator addresses
  • evvmBasicMetadata.json - EVVM and token metadata
  • evvmAdvancedMetadata.json - Supply and reward parameters

The wizard creates these automatically, or you can create them manually based on the examples in the repository.

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 five 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
  • Treasury.sol - Asset deposit and withdrawal system between EVVM and host blockchains

Understanding Your Deployment​

8. Register Your EVVM in the Registry​

After successfully deploying your EVVM virtual blockchain, the next step is registering it in the Registry EVVM Contract. This registration gives you an official EVVM ID that acts like a "phone number" for your virtual blockchain - other services and applications can use this ID to discover and connect to 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 standard deployments, use the public registration process. The system automatically assigns you an ID starting from 1000 (IDs 1-999 are reserved for official EVVM deployments):

  1. Call the Registry Contract: Execute the registerEvvm() function on the Registry EVVM Contract
  2. Provide Required Information:
    • chainId: The testnet chain ID where you deployed your EVVM (e.g., 11155111 for Sepolia, 421614 for Arbitrum Sepolia)
    • evvmAddress: Your deployed EVVM contract address (found in broadcast/DeployTestnet.s.sol/[chainId]/run-latest.json)
  3. Receive Your Unique ID: The contract automatically assigns you a unique EVVM ID (starting from 1000)

Registry Contract Location​

  • Proxy Address: 0x389dC8fb09211bbDA841D59f4a51160dA2377832
  • Implementation: 0xC1ef02492F1A75bCdB20766B558f10D643f9d504
  • Network: Ethereum Sepolia Testnet
  • View on Etherscan
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:

Using Your EVVM ID​

After registration, you must configure your EVVM ID in your contract to make it fully functional. Call the setEvvmID(uint256 evvmID) function on your deployed EVVM contract with the assigned ID.

Important ID Management Rules
  • Reserved IDs: EVVM IDs 1-999 are reserved for official deployments managed by the superUser. Public registrations automatically receive IDs starting from 1000.
  • Administrator Only: The setEvvmID function can only be called by the administrator address configured during deployment.
  • One-Hour Window: Once set, the evvmID can only be changed within a 1-hour window after the initial assignment. After this period, the ID becomes permanent.
  • No Reserved ID Registration: Do not attempt to register with reserved IDs (1-999) as these will be rejected.

How to Find Your EVVM Contract Address​

After deployment, you need to locate your EVVM contract address in the generated broadcast files:

# Navigate to your deployment broadcast directory
# Replace [CHAIN_ID] with your actual chain ID (e.g., 11155111 for Sepolia)
cd broadcast/DeployTestnet.s.sol/[CHAIN_ID]/

# Search for your EVVM contract address in the deployment results
cat run-latest.json | grep -A 5 '"contractName": "Evvm"'

What to look for: Find the contractAddress field in the transaction that deployed the "Evvm" contract. This is your main EVVM contract address that you'll need for registration.

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

Verify Your Registration​

After completing the registration process, confirm everything worked correctly:

Check in the Registry Contract:

  • Call getEvvmIdMetadata(uint256 evvmID) with your assigned ID to see your registration details
  • Verify the returned chainId and evvmAddress match your deployment

Check in Your EVVM Contract:

  • Call getEvvmID() on your deployed EVVM contract
  • It should return your assigned EVVM ID (1000+)

What Success Looks Like: Both functions should return consistent information, confirming your EVVM is properly registered and ready to use.

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​

You now have a fully deployed and verified EVVM virtual blockchain environment running on your chosen host blockchain. Your deployment is ready for development and testing.

What You've Accomplished​

  • Deployed a complete virtual blockchain ecosystem
  • Registered your EVVM with an official ID
  • Verified all contracts on the block explorer
  • Configured a secure development environment

What's Next?​

Explore the ecosystem documentation to build powerful applications on the world's first virtual blockchain architecture. Whether you're building simple services or complex dApps, EVVM provides the infrastructure for gasless, scalable blockchain applications.