@evvm/testnet-contracts 2.2.0 → 2.2.1

package/LICENSE

@@ -1,5 +1,5 @@
 Copyright (c) 2025
-GERMAN MARIA ABAL BAZZANO <g@evvm.org>
+MATE Labs Inc., a Delaware corporation ("Licensor")
 
 EVVM is licensed under the EVVM Noncommercial License v1.0 (the "License").
 You may obtain a copy of the License text in this file or at:
@@ -47,7 +47,7 @@ URL for them above, as well as copies of any plain-text lines
 beginning with `Required Notice:` that the licensor provided
 with the software.  For example:
 
-> Required Notice: Copyright (c) 2025 GERMAN MARIA ABAL BAZZANO (g@evvm.org)
+> Required Notice: Copyright (c) 2025 MATE Labs Inc., a Delaware corporation ("Licensor")
 
 ## Changes and New Works License
 

package/README.md

@@ -20,13 +20,21 @@ EVVM provides a complete ecosystem of smart contracts:
 ## Latest Features
 
 **Enhanced Deployment Experience:**
-- **Interactive TypeScript Wizard**: Modern, user-friendly deployment wizard with comprehensive guidance
-- **Automatic RPC Fallback**: 99%+ deployment success rate with 5 fallback RPCs per network
+- **CLI Executable**: Global `evvm` command for seamless deployment and management
+- **Interactive Wizard**: User-friendly deployment wizard with comprehensive guidance
+- **Automatic RPC Fallback**: 99%+ deployment success rate with multiple fallback endpoints
 - **Deployment Summary**: Instant access to all deployed contract addresses with explorer links
 - **Auto Registry Integration**: Automatic EVVM registration and ID configuration
 - **Smart Prerequisites Check**: Automatic dependency initialization and validation
 - **Multi-Wallet Support**: Easy selection from your Foundry keystores
 
+**CLI Commands Available:**
+- `evvm deploy` - Deploy new EVVM instance with interactive setup
+- `evvm register` - Register existing EVVM in the registry
+- `evvm fulltest` - Run complete test suite
+- `evvm help` - Display comprehensive help
+- `evvm version` - Show CLI version
+
 **Reliability Improvements:**
 - Intelligent retry mechanism for network failures
 - Comprehensive error handling and troubleshooting guides
@@ -226,26 +234,57 @@ forge install hyperlane-xyz/hyperlane-monorepo  # For cross-chain functionality
 ```
 
 ## Repository Structure
+- `evvm` — CLI executable - Main entry point for all EVVM commands
+- `cli/` — CLI source code (TypeScript)
+  - `index.ts` — Main entry point and CLI initialization
+  - `commands/` — Command implementations
+    - `deploy/` — Deployment command modules
+      - `deploySingle.ts` — Single-chain deployment
+      - `deployCross.ts` — Cross-chain deployment
+    - `register/` — Registration command modules
+      - `registerSingle.ts` — Single-chain registration
+      - `registerCross.ts` — Cross-chain registration
+    - `developer.ts` — Developer utilities
+    - `help.ts` — Help documentation
+    - `version.ts` — Version information
+    - `registerEvvm.ts` — EVVM registration logic
+    - `setUpCrossChainTreasuries.ts` — Cross-chain treasury setup
+  - `utils/` — Utility functions
+    - `configurationInputs.ts` — Configuration input handling
+    - `crossChain.ts` — Cross-chain utilities
+    - `explorerVerification.ts` — Block explorer contract verification
+    - `foundry.ts` — Foundry integration and scripts
+    - `prompts.ts` — Interactive CLI prompts
+    - `rpc.ts` — RPC endpoint management and fallback
+    - `validators.ts` — Input validation functions
+  - `constants/` — CLI constants and configuration
+    - `ChainData.json` — Network and chain configuration data
+    - `index.ts` — Constants exports
+  - `types/` — TypeScript type definitions
+    - `index.ts` — Type definitions
 - `src/contracts/evvm/` — Core EVVM contracts and storage
 - `src/contracts/nameService/` — NameService contracts for domain management
 - `src/contracts/staking/` — Staking and Estimator contracts
 - `src/contracts/treasury/` — Treasury contract for managing deposits and withdrawals
 - `src/contracts/p2pSwap/` — P2P token exchange service contracts
 - `src/lib/` — Shared Solidity libraries (AdvancedStrings, SignatureRecover, etc.)
-- `script/` — Foundry deployment scripts (e.g., `DeployTestnet.s.sol`)
-- `scripts/` — TypeScript utilities and deployment wizard (`evvm-init.ts`)
+- `script/` — Foundry deployment scripts (e.g., `Deploy.s.sol`)
 - `lib/` — External dependencies (OpenZeppelin, Uniswap v3, forge-std)
 - `broadcast/` — Foundry deployment artifacts and transaction history
 - `cache/` — Foundry compilation cache
-- `input/` — Configuration files for deployment (generated by wizard)
-- `evvm-init.sh` — Legacy bash wizard (deprecated, use `npm run wizard` instead)
+- `input/` — Configuration files for deployment (generated by CLI)
 
 ## Prerequisites
 - [Foundry](https://getfoundry.sh/) (Solidity development toolkit)
-- [Node.js](https://nodejs.org/) v16 or higher (required for deployment wizard)
+- [Bun](https://bun.sh/) v1.0 or higher (JavaScript runtime for CLI - faster than Node.js)
 - Git (for cloning and managing the repository)
 - Environment variables set up (`.env` file with API keys and RPC URLs)
 
+> **Note**: The CLI uses Bun for superior performance. If you don't have Bun installed, you can install it with:
+> ```bash
+> curl -fsSL https://bun.sh/install | bash
+> ```
+
 ### Environment Setup
 Create a `.env` file with your configuration:
 ```bash
@@ -283,28 +322,69 @@ Want to create your own virtual blockchain? Follow these steps to deploy a compl
 
 ### 1. Clone and Install
 ```bash
-git clone https://github.com/EVVM-org/Testnet-Contracts
+git clone --recursive https://github.com/EVVM-org/Testnet-Contracts
 cd Testnet-Contracts
 make install
 ```
 
-### 2. Environment Setup
+### 2. Make CLI Globally Available (Optional but Recommended)
+```bash
+# Make the CLI executable
+chmod +x evvm
+
+# Add to your PATH (choose one method):
+# Method 1: Create symlink in local bin
+mkdir -p ~/.local/bin
+ln -s $(pwd)/evvm ~/.local/bin/evvm
+
+# Method 2: Add to PATH in your shell profile
+echo 'export PATH="'$(pwd)':$PATH"' >> ~/.bashrc  # or ~/.zshrc
+source ~/.bashrc  # or source ~/.zshrc
+
+# Verify installation
+evvm version
+```
+
+Once installed, you can use `evvm` commands from anywhere in your terminal.
+
+### 3. Environment Setup
 Create `.env` file with your configuration:
 ```bash
 cp .env.example .env
 # Add your RPC URLs and API keys
 ```
 
-### 3. Secure Key Import
+### 4. Secure Key Import
 ```bash
 cast wallet import defaultKey --interactive
 ```
 
-### 4. Interactive Setup & Deploy
+### 5. Deploy Using the CLI
+
+The **recommended way** to deploy is using the EVVM CLI. You have two options:
+
+**Option A: Using Global CLI (Recommended - if you completed step 2)**
+```bash
+evvm deploy
+```
+
+**Option B: Using NPM from the repository directory**
 ```bash
 npm run wizard
 ```
 
+**Option C: Using CLI with custom options**
+```bash
+# Skip interactive setup and use existing configuration
+evvm deploy --skipInputConfig
+
+# Deploy with a specific wallet
+evvm deploy --walletName myWallet
+
+# Combine options for quick deployment
+evvm deploy -s -w myWallet
+```
+
 The interactive deployment wizard will guide you through:
 - **Prerequisites check** (Foundry, Git, Node.js)
 - **Dependency initialization** (git submodules - automatic)
@@ -315,8 +395,8 @@ The interactive deployment wizard will guide you through:
 - **Wallet selection** (from your Foundry keystores)
 - **Automatic deployment** with contract verification
 - **Deployment summary** with all contract addresses and explorer links
-- **Registry EVVM registration** (automatic for supported networks)
-- **EVVM ID configuration** (automatic setup)
+- **Registry EVVM registration** (cross-chain registration on Ethereum Sepolia)
+- **EVVM ID configuration** (automatic setup on your deployment chain)
 
 **What happens after deployment:**
 - All 6 core contracts deployed and verified on your chosen network
@@ -325,11 +405,158 @@ The interactive deployment wizard will guide you through:
   - Treasury contract address
   - Staking, Estimator, NameService, and P2PSwap addresses
   - Direct links to block explorer for each contract
-- Automatic registration with Registry EVVM (Ethereum Sepolia)
-- EVVM ID assigned and configured
+- **Cross-chain registration flow:**
+  1. Registry registration happens on Ethereum Sepolia (where the Registry EVVM lives)
+  2. You receive a unique EVVM ID (e.g., ID: 1090)
+  3. The EVVM ID is then set on your deployed contract (on your deployment chain)
+  4. Both transactions show explorer links for verification
 
 That's it! Your EVVM virtual blockchain is now deployed, verified, and ready to use.
 
+## CLI Commands Reference
+
+The EVVM CLI provides powerful commands for managing your EVVM deployments:
+
+### Deploy Command
+
+Deploy a new EVVM instance with interactive configuration:
+
+```bash
+evvm deploy [options]
+```
+
+**Options:**
+- `--skipInputConfig`, `-s` - Skip interactive setup, use existing `./input/Inputs.sol`
+- `--walletName <name>`, `-w <name>` - Specify Foundry wallet (default: `defaultKey`)
+
+**Examples:**
+```bash
+# Interactive deployment with configuration wizard
+evvm deploy
+
+# Deploy using existing configuration
+evvm deploy --skipInputConfig
+
+# Deploy with specific wallet
+evvm deploy --walletName myWallet
+
+# Quick deploy with existing config and custom wallet
+evvm deploy -s -w production
+```
+
+### Register Command
+
+Register an existing EVVM instance in the registry:
+
+```bash
+evvm register [options]
+```
+
+**Options:**
+- `--evvmAddress <address>` - EVVM contract address to register
+- `--walletName <name>`, `-w <name>` - Foundry wallet name (default: `defaultKey`)
+- `--useCustomEthRpc` - Use custom Ethereum Sepolia RPC for registry calls
+
+**Examples:**
+```bash
+# Register with prompts for missing information
+evvm register
+
+# Register with specific EVVM address
+evvm register --evvmAddress 0x123...
+
+# Register with custom wallet and RPC
+evvm register --evvmAddress 0x123... --walletName myWallet --useCustomEthRpc
+```
+
+**Note**: The RPC URL for your deployment chain is read from the `RPC_URL` environment variable in your `.env` file.
+
+### Test Command
+
+Run the complete EVVM test suite:
+
+```bash
+evvm fulltest
+```
+
+Executes all unit tests with:
+- Test results summary
+- Detailed execution logs
+- Gas usage reports
+- Progress indicators
+
+### Help Command
+
+Display comprehensive CLI documentation:
+
+```bash
+evvm help
+# or
+evvm --help
+evvm -h
+```
+
+### Version Command
+
+Show current CLI version:
+
+```bash
+evvm version
+# or
+evvm --version
+evvm -v
+```
+
+### Global Options
+
+These options work with any command:
+
+- `-h`, `--help` - Show help for the command
+- `-v`, `--version` - Show CLI version
+
+### Environment Variables
+
+The CLI reads configuration from your `.env` file:
+
+```bash
+# Required for deployment
+RPC_URL=https://sepolia-rollup.arbitrum.io/rpc
+
+# Optional: Custom Ethereum Sepolia RPC (for registry operations)
+ETH_SEPOLIA_RPC=https://eth-sepolia.public.blastapi.io
+
+# Optional: Block explorer API key for contract verification
+ETHERSCAN_API=your_api_key_here
+
+# Optional: For Blockscout verification
+BLOCKSCOUT_HOMEPAGE=https://sepolia.explorer.com
+```
+
+### CLI Features
+
+Automatic RPC Fallback:
+- Automatically tries 5 fallback endpoints if primary RPC fails
+- 99%+ deployment success rate
+- No manual intervention required
+
+Smart Prerequisites Check:
+- Validates Foundry installation
+- Verifies wallet configuration
+- Checks network connectivity
+- Initializes git submodules automatically
+
+Interactive Prompts:
+- Address validation with format checking
+- Secure password input for sensitive data
+- Arrow-key selection menus
+- Confirmation dialogs with defaults
+
+Comprehensive Error Handling:
+- Clear error messages with troubleshooting tips
+- Automatic retry on transient failures
+- Helpful suggestions for common issues
+- Direct links to documentation
+
 ## Manual Configuration (Alternative)
 
 If you prefer manual control over configuration, create these files in `input/`:
@@ -356,12 +583,14 @@ If you prefer manual control over configuration, create these files in `input/`:
 **input/evvmAdvancedMetadata.json**:
 ```json
 {
-  "totalSupply": 2033333333000000000000000000,
   "eraTokens": 1016666666500000000000000000,
-  "reward": 5000000000000000000
+  "reward": 5000000000000000000,
+  "totalSupply": 2033333333000000000000000000
 }
 ```
 
+> **Important**: The field order in `evvmAdvancedMetadata.json` **must be alphabetical** (`eraTokens`, `reward`, `totalSupply`). Foundry's `vm.parseJson` decodes fields alphabetically, not by matching field names. Do not use code formatters (like Prettier) on these files as they may reorder fields incorrectly.
+
 ## Local Development & Manual Deployment
 
 ### Start Local Development
@@ -400,7 +629,7 @@ make help        # Show all available commands
 
 ### NPM Scripts
 ```bash
-npm run wizard           # Run interactive deployment wizard (recommended)
+npm run wizard           # Run interactive deployment wizard (uses CLI internally)
 npm run build           # Copy src/ files to root (for NPM publishing)
 npm run clean           # Remove copied files from root
 npm run compile         # forge build
@@ -410,6 +639,25 @@ npm run deploy:sepolia  # Deploy to Ethereum Sepolia
 npm run deploy:arbitrum # Deploy to Arbitrum Sepolia
 ```
 
+### Direct CLI Usage
+
+Once you've set up the CLI executable, use it directly:
+
+```bash
+evvm deploy              # Deploy new EVVM instance
+evvm register            # Register existing EVVM
+evvm fulltest            # Run test suite
+evvm help                # Show all commands
+evvm version             # Show CLI version
+```
+
+Advantages of direct CLI usage:
+- Faster execution with Bun runtime
+- Available globally from any directory
+- Cleaner syntax
+- Better error messages
+- Tab completion support in compatible shells
+
 ## RPC Reliability
 
 The deployment wizard includes an intelligent RPC fallback mechanism to ensure maximum deployment success rates, even when individual RPC providers experience downtime.
@@ -421,18 +669,18 @@ The deployment wizard includes an intelligent RPC fallback mechanism to ensure m
 **Multi-Provider Support**: Each network has 5 verified RPC endpoints:
 
 **Ethereum Sepolia Fallback Chain:**
-1. `https://0xrpc.io/sep` (Primary)
-2. `https://ethereum-sepolia.rpc.subquery.network/public` (0.165s latency)
-3. `https://ethereum-sepolia.gateway.tatum.io` (0.172s latency)
-4. `https://sepolia.drpc.org` (0.192s latency)
-5. `https://gateway.tenderly.co/public/sepolia` (0.184s latency)
+1. `https://1rpc.io/sepolia` (1RPC - fastest)
+2. `https://ethereum-sepolia.rpc.subquery.network/public` (SubQuery)
+3. `https://ethereum-sepolia-rpc.publicnode.com` (PublicNode - stable)
+4. `https://sepolia.drpc.org` (dRPC)
+5. `https://gateway.tenderly.co/public/sepolia` (Tenderly)
 
 **Arbitrum Sepolia Fallback Chain:**
 1. `https://sepolia-rollup.arbitrum.io/rpc` (Official Arbitrum)
-2. `https://arbitrum-sepolia.gateway.tenderly.co` (0.167s latency)
-3. `https://endpoints.omniatech.io/v1/arbitrum/sepolia/public` (0.258s latency)
-4. `https://arbitrum-sepolia.drpc.org` (0.590s latency)
-5. `https://arbitrum-sepolia-rpc.publicnode.com` (0.430s latency)
+2. `https://arbitrum-sepolia.gateway.tenderly.co` (Tenderly)
+3. `https://endpoints.omniatech.io/v1/arbitrum/sepolia/public` (Omnia)
+4. `https://arbitrum-sepolia-rpc.publicnode.com` (PublicNode)
+5. `https://arbitrum-sepolia.drpc.org` (dRPC)
 
 **Smart Retry Logic**: The wizard displays clear progress messages during fallback attempts and provides troubleshooting tips if all endpoints fail.
 
@@ -448,40 +696,48 @@ The deployment wizard includes an intelligent RPC fallback mechanism to ensure m
 After successful deployment, the wizard displays a comprehensive summary of all deployed contracts:
 
 ```
-═══════════════════════════════════════════════════════════
-                 DEPLOYED CONTRACTS SUMMARY
-═══════════════════════════════════════════════════════════
+DEPLOYED CONTRACTS SUMMARY
+==========================
 
-Network: Ethereum Sepolia (Chain ID: 11155111)
+Network: Arbitrum Sepolia (Chain ID: 421614)
 
 Core Contracts:
-  EVVM:        0xb0994626541c9bd3d64605dee610386c7a005a39
-               https://sepolia.etherscan.io/address/0xb099...
-  Treasury:    0x47be342c4d803490530737cac7bcf34916cf7e80
-               https://sepolia.etherscan.io/address/0x47be...
+  EVVM:        0x3e562a2e932afd6c1630d5f3b8eb3d88a4b058c2
+               https://sepolia.arbiscan.io/address/0x3e56...
+  Treasury:    0x5c3a673dcf38e08b1f4e361ed7ed7be76df7b188
+               https://sepolia.arbiscan.io/address/0x5c3a...
 
 Supporting Contracts:
-  Staking:     0xc2cd4ec40bb4fa6f98c7b7095f692588e6b68fd4
-  Estimator:   0x1adf3fd08f0744f24bb29bbfcfb57a5f37f144cb
-  NameService: 0xe28eedff481b7c640394f44070309a0afe06de00
-  P2PSwap:     0xc90dc57d848fae4ecf46268b8a90015085968645
+  Staking:     0xcdef28d767f0029f0e75563c8e7ed44a2aab6cf2
+  Estimator:   0xcfff3e950c3b1f7b850394d4cf3d60b31041f139
+  NameService: 0xdfa5e2529b06683dcec37f67f0607f294809a512
+  P2PSwap:     0xef2efb60d353731287696d74d360c635844f0ae2
 
-═══════════════════════════════════════════════════════════
+REGISTRY EVVM REGISTRATION
+==========================
+
+  EVVM Address: 0x3e562a2e932afd6c1630d5f3b8eb3d88a4b058c2
+  Deployed on: Arbitrum Sepolia (Chain ID: 421614)
+  Registry: Ethereum Sepolia (cross-chain registration)
+
+EVVM registered with ID: 1090
+EVVM ID 1090 set on Arbitrum Sepolia
 ```
 
 This summary includes:
 - Network name and chain ID
 - All 6 deployed contract addresses
-- Direct links to block explorer for verification
+- Direct links to block explorer for verification (Etherscan for ETH Sepolia, Arbiscan for Arbitrum Sepolia)
 - Organized by contract importance (Core vs Supporting)
+- Cross-chain registration status and assigned EVVM ID
 
 ## Troubleshooting
 
 ### RPC Connection Issues
 
-**Problem**: Deployment fails with "Connection timed out" or "HTTP error 522"
+Problem: Deployment fails with "Connection timed out" or "HTTP error 522"
 
-**Solution**: The wizard automatically tries fallback RPCs. If all fail:
+Solution: The wizard automatically tries fallback RPCs. If all fail:
 1. Check your internet connection
 2. Verify firewall/VPN settings aren't blocking RPC endpoints
 3. Try again later (temporary provider downtime)
@@ -489,9 +745,9 @@ This summary includes:
 
 ### Wallet Not Found
 
-**Problem**: "No wallets found" error during deployment
+Problem: "No wallets found" error during deployment
 
-**Solution**:
+Solution:
 ```bash
 cast wallet import <WALLET_NAME> --interactive
 ```
@@ -499,9 +755,9 @@ Then run the wizard again and select your imported wallet.
 
 ### Insufficient Funds
 
-**Problem**: Deployment fails with "insufficient funds for gas"
+Problem: Deployment fails with "insufficient funds for gas"
 
-**Solution**:
+Solution:
 1. Get testnet ETH from faucets:
    - Ethereum Sepolia: [sepoliafaucet.com](https://sepoliafaucet.com/)
    - Arbitrum Sepolia: [faucet.quicknode.com/arbitrum/sepolia](https://faucet.quicknode.com/arbitrum/sepolia)
@@ -510,28 +766,71 @@ Then run the wizard again and select your imported wallet.
 
 ### Git Submodules Not Initialized
 
-**Problem**: Compilation fails with missing dependencies
+Problem: Compilation fails with missing dependencies
 
-**Solution**: The wizard automatically initializes submodules, but you can also do it manually:
+Solution: The wizard automatically initializes submodules, but you can also do it manually:
 ```bash
 git submodule update --init --recursive
 ```
 
 ### Contract Size Too Large
 
-**Problem**: "Contract code size exceeds 24576 bytes"
+Problem: "Contract code size exceeds 24576 bytes"
 
-**Solution**: The project uses `via-ir` optimization to stay under limits. If you modified contracts:
+Solution: The project uses `via-ir` optimization to stay under limits. If you modified contracts:
 ```bash
 make seeSizes  # Check contract sizes
 ```
 Consider refactoring large contracts or using libraries.
 
+### CLI Command Not Found
+
+Problem: `evvm: command not found` when trying to run CLI commands
+
+Solution: The CLI executable is not in your PATH. You have three options:
+
+1. **Run from the repository directory:**
+   ```bash
+   ./evvm deploy
+   ```
+
+2. **Add to PATH temporarily (current session only):**
+   ```bash
+   export PATH="$(pwd):$PATH"
+   evvm deploy
+   ```
+
+3. **Add to PATH permanently (recommended):**
+   ```bash
+   # For bash
+   echo 'export PATH="'$(pwd)':$PATH"' >> ~/.bashrc
+   source ~/.bashrc
+   
+   # For zsh
+   echo 'export PATH="'$(pwd)':$PATH"' >> ~/.zshrc
+   source ~/.zshrc
+   ```
+
+### Bun Not Installed
+
+Problem: CLI fails with "bun: command not found"
+
+Solution: Install Bun runtime:
+```bash
+curl -fsSL https://bun.sh/install | bash
+
+# Restart your terminal or run:
+source ~/.bashrc  # or source ~/.zshrc
+
+# Verify installation
+bun --version
+```
+
 ### TypeScript/TSX Not Found
 
-**Problem**: `npm run wizard` fails with "tsx: command not found"
+Problem: `npm run wizard` fails with "tsx: command not found"
 
-**Solution**:
+Solution:
 ```bash
 npm install  # Reinstall dependencies
 ```
@@ -548,8 +847,9 @@ The EVVM ecosystem consists of six main contracts:
 
 ## Configuration Files
 Key files for EVVM deployment:
-- `scripts/evvm-init.ts` — Interactive TypeScript deployment wizard (run with `npm run wizard`)
-- `input/` — Generated configuration files (address.json, evvmBasicMetadata.json, evvmAdvancedMetadata.json)
+- `evvm` — CLI executable entry point (run with `./evvm` or just `evvm` if in PATH)
+- `cli/` — CLI implementation (TypeScript with Bun runtime)
+- `input/Inputs.sol` — Generated deployment configuration (created by CLI wizard)
 - `.env` — Environment variables (RPC URLs, API keys)
 - `foundry.toml` — Foundry project configuration
 - `makefile` — Build and deployment automation