Skip to content

02-QuickStart.md

Latest commit

 

History

History
422 lines (313 loc) · 12.7 KB

02-QuickStart.md

File metadata and controls

422 lines (313 loc) · 12.7 KB
description Step-by-step guide to deploy your EVVM virtual blockchain in minutes using the EVVM CLI
sidebar_position 2

QuickStart

Deploy your EVVM virtual blockchain in minutes.

:::info[Not sure this is the right guide?]

  • Building dApps on an existing EVVM? Check out How to Create an EVVM Service instead.
  • Just want to experiment? Start with the scaffold-evvm starter kit.
  • Are you a Docker user? Skip the local tooling setup entirely — the EVVM Docker Quick Start provides a pre-built image with everything ready to run. Keep in mind that the Docker setup deploys a standard EVVM with default parameters. If you need to customize contracts or deployment settings to fit your specific requirements, follow this guide instead. :::

Prerequisites

The CLI validates these automatically.

1. Clone and Install

git clone --recursive https://github.com/EVVM-org/Testnet-Contracts
cd Testnet-Contracts
bun install
forge install

2. Environment Setup

cp .env.example .env

Edit .env with your values:

# RPC URL for blockchain to deploy EVVM
RPC_URL="https://sepolia-rollup.arbitrum.io/rpc"

# Optional: Custom Ethereum Sepolia RPC for registry operations
EVVM_REGISTRATION_RPC_URL="https://gateway.tenderly.co/public/sepolia"

# Optional: Etherscan API Key for contract verification
ETHERSCAN_API="your_etherscan_api_key"

Cross-Chain Configuration (Optional)

# Host chain RPC (main EVVM deployment)
HOST_RPC_URL="https://sepolia-rollup.arbitrum.io/rpc"

# External chain RPC (Treasury External Station)
EXTERNAL_RPC_URL="https://sepolia.base.org"

# Optional: Custom Ethereum Sepolia RPC for registry
EVVM_REGISTRATION_RPC_URL="https://gateway.tenderly.co/public/sepolia"

# Optional: Etherscan API Key for verification
ETHERSCAN_API="your_etherscan_api_key"

:::warning[Never Store Private Keys in .env] Use Foundry's encrypted keystore to protect your private keys. The .env file should only contain RPC URLs and API keys. :::

3. Import Wallet

cast wallet import defaultKey --interactive

This command securely encrypts and stores your private key.

:::tip[Custom Wallet Name] You can use any name instead of defaultKey:

cast wallet import myWallet --interactive

Then specify it during deployment:

./evvm deploy --walletName myWallet

:::

4. Deploy with CLI

If you are on Linux or macOS, run:

./evvm deploy

:::warning[Windows is not supported] The EVVM CLI does not provide a native Windows executable. To use it on a Windows machine, choose one of the following alternatives:

  • Docker — No local tooling needed. Use the EVVM Docker Quick Start to get a pre-configured environment up and running in minutes.
  • WSL 2 (Windows Subsystem for Linux) — Install WSL 2 with a Linux distribution (Ubuntu recommended) and follow the Linux/macOS instructions above. See the official WSL installation guide.
  • Virtual Machine — Use VirtualBox, VMware, or any hypervisor with a Linux guest OS, then follow the Linux/macOS instructions. :::

:::info Some systems may require chmod +x evvm to make the script executable. :::

The interactive wizard will:

  1. Validate prerequisites
  2. Configure your EVVM (addresses, metadata, network)
  3. Deploy contracts
  4. Verify on block explorer
  5. Register in EVVM Registry (optional)

Configuration

The interactive wizard prompts for:

Administrator Addresses (required):

  • Admin - Full contract administrator privileges
  • Golden Fisher - Sudo account for privileged staking operations
  • Activator - Manages epoch activation for rewards
Enter the admin address: 0x...
Enter the goldenFisher address: 0x...
Enter the activator address: 0x...

Token Configuration (required):

EVVM Name [EVVM]: My EVVM
Principal Token Name [Mate Token]: My Token
Principal Token Symbol [MATE]: MYT

Press Enter to accept the default values shown in brackets [default], or type a new value.

Advanced Metadata (optional):

The CLI will ask:

Configure advanced metadata (totalSupply, eraTokens, reward)? (y/n):

If you answer y, you'll configure:

  • totalSupply - Maximum token supply (default: 2033333333000000000000000000)
  • eraTokens - Tokens allocated per era (default: 1016666666500000000000000000)
  • reward - Reward per transaction (default: 5000000000000000000)

:::tip[Recommended for Most Users] Unless you have specific token economics requirements, answer n to use default values. The defaults are optimized for most use cases. :::

Configuration Summary:

Review all values before deployment:

═════════════════════════════════════════
        Configuration Summary
═════════════════════════════════════════

Addresses:
  admin: 0x...
  goldenFisher: 0x...
  activator: 0x...

Token Metadata:
  EvvmName: My EVVM
  Token Name: My Token
  Token Symbol: MYT

Confirm configuration? (y/n):

The CLI shows a summary before deployment. Review and confirm to proceed.

Block Explorer Verification:

Choose a verification method for automatic contract verification:

Select block explorer verification:
  🭬 Etherscan v2
    Blockscout
    Sourcify
    Custom
    Skip verification (not recommended)

Available Options:

  • Etherscan v2 - Requires ETHERSCAN_API in .env file

    • Best for: Major networks (Ethereum, Arbitrum, Base, Optimism)
    • Note: Most common option

  • Blockscout - Requires block explorer homepage URL

    • Best for: Custom L2s and networks with Blockscout explorer
    • Example URL: https://sepolia.arbiscan.io/

  • Sourcify - No API key required

  • Custom - Provide custom verification parameters

    • For: Specialized verification setups
    • Example: --verify --verifier-url <url> --verifier-api-key <key>

  • Skip verification - Deploy without verification

    • ⚠️ Not recommended for production
    • Use only for local testing

5. Deployment Output

The deployment compiles and deploys 6 core contracts:

Contract Purpose
Evvm Core virtual machine logic
Staking Staking and reward management
Estimator Reward calculation engine
NameService Domain name system
Treasury Asset management and liquidity
P2PSwap Peer-to-peer token exchange

Success Screen:

After deployment, you'll see:

✓ Deployment completed successfully!

═══════════════════════════════════════
       Deployed Contracts
═══════════════════════════════════════

  ✓ Staking
    → 0x1111111111111111111111111111111111111111
  ✓ Evvm
    → 0x2222222222222222222222222222222222222222
  ✓ Estimator
    → 0x3333333333333333333333333333333333333333
  ✓ NameService
    → 0x4444444444444444444444444444444444444444
  ✓ Treasury
    → 0x5555555555555555555555555555555555555555
  ✓ P2PSwap
    → 0x6666666666666666666666666666666666666666

Verification:

All contracts are automatically verified on the block explorer with direct links to view them.

Artifacts:

  • Deployment data: broadcast/Deploy.s.sol/[chainId]/run-latest.json
  • Generated config: input/BaseInputs.sol
  • Output summary: output/evvmDeployment.json (if saved)

6. Register in EVVM Registry

After deployment, register your EVVM to obtain an official EVVM ID.

During Deployment

The CLI asks if you want to register immediately:

Your EVVM instance is ready to be registered.

Do you want to register the EVVM instance now? (y/n):

If you choose y:

  1. CLI prompts for Ethereum Sepolia RPC (optional, uses default if not provided)
  2. Submits registration to EVVM Registry contract
  3. Receives unique EVVM ID (≥ 1000)
  4. Updates your EVVM contract with the assigned ID

If you choose n, register later using the command below.

Register Later

./evvm register --evvmAddress 0x...

Options:

# Basic registration
./evvm register --evvmAddress 0x3e562a2e932afd6c1630d5f3b8eb3d88a4b058c2

# With custom wallet
./evvm register \
  --evvmAddress 0x3e562a2e932afd6c1630d5f3b8eb3d88a4b058c2 \
  --walletName myWallet

# With custom Ethereum Sepolia RPC
./evvm register \
  --evvmAddress 0x3e562a2e932afd6c1630d5f3b8eb3d88a4b058c2 \
  --useCustomEthRpc

EVVM Registry Details

  • Address: 0x389dC8fb09211bbDA841D59f4a51160dA2377832
  • Network: Ethereum Sepolia
  • View: Etherscan

ID Assignment Rules:

  • IDs 1-999: Reserved for official EVVM deployments
  • IDs ≥ 1000: Public community registrations
  • ID is permanent after 24 hours

:::warning[Critical Requirements] All registrations happen on Ethereum Sepolia, regardless of where your EVVM is deployed.

You need ETH Sepolia for gas fees:

Verify Registration:

After registration, verify using the registry contract:

# Check EVVM ID metadata (on Ethereum Sepolia)
cast call 0x389dC8fb09211bbDA841D59f4a51160dA2377832 \
  "getEvvmIdMetadata(uint256)" <evvmID>

# Check ID on your EVVM contract (on your deployment chain)
cast call <your_evvm_address> "getEvvmID()" --rpc-url <your_rpc>

CLI Command Reference

Deployment & Registration:

./evvm deploy                    # Deploy EVVM interactively (single-chain)
./evvm deploy --skipInputConfig  # Deploy using saved config (non-interactive)
./evvm deploy --crossChain       # Deploy cross-chain EVVM instance
./evvm register                  # Register EVVM in registry (interactive)
./evvm register --crossChain     # Register cross-chain EVVM
./evvm register --evvmAddress 0x...

Cross-Chain & Developer:

./evvm setUpCrossChainTreasuries  # Connect treasury stations
./evvm developer --makeInterface  # Generate Solidity interfaces
./evvm developer --runTest        # Run test suite
./evvm install                    # Install dependencies

Information:

./evvm help                       # Show comprehensive help
./evvm version                    # Show CLI version

Common examples:

# Interactive deploy with custom wallet
./evvm deploy --walletName myWallet

# Non-interactive deploy (use saved config)
./evvm deploy --skipInputConfig --walletName myWallet

# Register an EVVM
./evvm register --evvmAddress 0x... --walletName myWallet

# Run tests
./evvm developer --runTest

# Generate interfaces
./evvm developer --makeInterface

Wallet Management:

# Import a wallet securely
cast wallet import defaultKey --interactive

# Import with custom name
cast wallet import myWallet --interactive

# List available wallets
cast wallet list

Support: https://github.com/EVVM-org/Testnet-Contracts/issues

Next Steps

Learn More About CLI:

Build Services on Your EVVM:

Advanced Topics:

Support & Issues:

Your EVVM is ready for development!