@evvm/testnet-contracts 2.1.2 → 2.2.0

package/README.md

@@ -1,7 +1,5 @@
 # EVVM Testnet Contracts
 
-![](https://github.com/user-attachments/assets/08d995ee-7512-42e4-a26c-0d62d2e8e0bf)
-
 EVVM is an innovative blockchain virtualization system that allows you to create and deploy your own virtual blockchains on top of existing Ethereum networks where you can:
 
 - **Create your own virtual blockchain** with custom tokens and governance
@@ -15,10 +13,26 @@ EVVM provides a complete ecosystem of smart contracts:
 - **Core EVVM**: Your virtual blockchain's main engine
 - **NameService**: Domain name system for your blockchain (like ENS)
 - **Staking**: Token staking and rewards system
-- **Treasury**: Secure fund management inside the host chain or across chains 
+- **Treasury**: Secure fund management inside the host chain or across chains
 - **Estimator**: Reward calculation and optimization
 - **P2PSwap**: Peer-to-peer token exchange service with automated market making
 
+## 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
+- **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
+
+**Reliability Improvements:**
+- Intelligent retry mechanism for network failures
+- Comprehensive error handling and troubleshooting guides
+- Verified high-performance RPC endpoints
+- Zero-configuration setup for most users
+
 ## Use Cases
 
 This repository serves two main purposes:
@@ -218,27 +232,35 @@ forge install hyperlane-xyz/hyperlane-monorepo  # For cross-chain functionality
 - `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/` — Deployment and automation scripts (e.g., `DeployTestnet.s.sol`)
+- `script/` — Foundry deployment scripts (e.g., `DeployTestnet.s.sol`)
+- `scripts/` — TypeScript utilities and deployment wizard (`evvm-init.ts`)
 - `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 `evvm-init.sh`)
-- `evvm-init.sh` — Interactive setup and deployment script
+- `input/` — Configuration files for deployment (generated by wizard)
+- `evvm-init.sh` — Legacy bash wizard (deprecated, use `npm run wizard` instead)
 
 ## Prerequisites
 - [Foundry](https://getfoundry.sh/) (Solidity development toolkit)
-- Node.js (if using npm installation method)
-- Bash shell (for running `evvm-init.sh`)
+- [Node.js](https://nodejs.org/) v16 or higher (required for deployment wizard)
+- Git (for cloning and managing the repository)
 - Environment variables set up (`.env` file with API keys and RPC URLs)
 
 ### Environment Setup
 Create a `.env` file with your configuration:
 ```bash
-RPC_URL_ETH_SEPOLIA=<YOUR_ETH_SEPOLIA_RPC_URL>
-RPC_URL_ARB_SEPOLIA=<YOUR_ARB_SEPOLIA_RPC_URL>
+# Ethereum Sepolia RPC (primary endpoint)
+RPC_URL_ETH_SEPOLIA=https://0xrpc.io/sep
+
+# Arbitrum Sepolia RPC (primary endpoint)
+RPC_URL_ARB_SEPOLIA=https://sepolia-rollup.arbitrum.io/rpc
+
+# Etherscan API key for contract verification
 ETHERSCAN_API=<YOUR_ETHERSCAN_API_KEY>
 ```
 
+**Note**: The deployment wizard includes automatic RPC fallback mechanisms. If your primary RPC endpoint fails, it will automatically try alternative endpoints to ensure deployment success. See the [RPC Reliability](#rpc-reliability) section for details.
+
 ### Security Setup - Import Private Key
 Before deploying to testnets, securely import your private key using Foundry:
 ```bash
@@ -280,17 +302,33 @@ cast wallet import defaultKey --interactive
 
 ### 4. Interactive Setup & Deploy
 ```bash
-./evvm-init.sh
+npm run wizard
 ```
 
-The wizard will configure:
+The interactive deployment wizard will guide you through:
+- **Prerequisites check** (Foundry, Git, Node.js)
+- **Dependency initialization** (git submodules - automatic)
 - **Administrator addresses** (admin, golden fisher, activator)
-- **EVVM metadata** (name, ID, principal token details)
+- **EVVM metadata** (name, principal token details)
 - **Advanced parameters** (supply, rewards) - optional
-- **Network selection** (Ethereum Sepolia, Arbitrum Sepolia, or custom)
+- **Network selection** (Ethereum Sepolia, Arbitrum Sepolia, or custom RPC)
+- **Wallet selection** (from your Foundry keystores)
 - **Automatic deployment** with contract verification
-
-That's it! Your EVVM virtual blockchain is now deployed and verified on your chosen host blockchain.
+- **Deployment summary** with all contract addresses and explorer links
+- **Registry EVVM registration** (automatic for supported networks)
+- **EVVM ID configuration** (automatic setup)
+
+**What happens after deployment:**
+- All 6 core contracts deployed and verified on your chosen network
+- Complete deployment summary displayed with:
+  - EVVM Core contract address
+  - 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
+
+That's it! Your EVVM virtual blockchain is now deployed, verified, and ready to use.
 
 ## Manual Configuration (Alternative)
 
@@ -360,6 +398,144 @@ make seeSizes    # Check contract sizes
 make help        # Show all available commands
 ```
 
+### NPM Scripts
+```bash
+npm run wizard           # Run interactive deployment wizard (recommended)
+npm run build           # Copy src/ files to root (for NPM publishing)
+npm run clean           # Remove copied files from root
+npm run compile         # forge build
+npm run test            # forge test
+npm run deploy:anvil    # Deploy to local Anvil
+npm run deploy:sepolia  # Deploy to Ethereum Sepolia
+npm run deploy:arbitrum # Deploy to Arbitrum Sepolia
+```
+
+## RPC Reliability
+
+The deployment wizard includes an intelligent RPC fallback mechanism to ensure maximum deployment success rates, even when individual RPC providers experience downtime.
+
+### How It Works
+
+**Automatic Failover**: If your primary RPC endpoint fails, the wizard automatically tries alternative endpoints without user intervention.
+
+**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)
+
+**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)
+
+**Smart Retry Logic**: The wizard displays clear progress messages during fallback attempts and provides troubleshooting tips if all endpoints fail.
+
+### Benefits
+- **99%+ success rate** through endpoint redundancy
+- **Zero configuration** required for most users
+- **Automatic recovery** from individual RPC failures
+- **Clear visibility** into which RPC is being used
+- **Future-proof** against provider outages
+
+## Deployment Summary
+
+After successful deployment, the wizard displays a comprehensive summary of all deployed contracts:
+
+```
+═══════════════════════════════════════════════════════════
+                 DEPLOYED CONTRACTS SUMMARY
+═══════════════════════════════════════════════════════════
+
+Network: Ethereum Sepolia (Chain ID: 11155111)
+
+Core Contracts:
+  EVVM:        0xb0994626541c9bd3d64605dee610386c7a005a39
+               https://sepolia.etherscan.io/address/0xb099...
+  Treasury:    0x47be342c4d803490530737cac7bcf34916cf7e80
+               https://sepolia.etherscan.io/address/0x47be...
+
+Supporting Contracts:
+  Staking:     0xc2cd4ec40bb4fa6f98c7b7095f692588e6b68fd4
+  Estimator:   0x1adf3fd08f0744f24bb29bbfcfb57a5f37f144cb
+  NameService: 0xe28eedff481b7c640394f44070309a0afe06de00
+  P2PSwap:     0xc90dc57d848fae4ecf46268b8a90015085968645
+
+═══════════════════════════════════════════════════════════
+```
+
+This summary includes:
+- Network name and chain ID
+- All 6 deployed contract addresses
+- Direct links to block explorer for verification
+- Organized by contract importance (Core vs Supporting)
+
+## Troubleshooting
+
+### RPC Connection Issues
+
+**Problem**: Deployment fails with "Connection timed out" or "HTTP error 522"
+
+**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)
+4. Update your `.env` file with a custom RPC from [chainlist.org](https://chainlist.org/)
+
+### Wallet Not Found
+
+**Problem**: "No wallets found" error during deployment
+
+**Solution**:
+```bash
+cast wallet import <WALLET_NAME> --interactive
+```
+Then run the wizard again and select your imported wallet.
+
+### Insufficient Funds
+
+**Problem**: Deployment fails with "insufficient funds for gas"
+
+**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)
+2. Verify your wallet address has received funds
+3. Run the wizard again
+
+### Git Submodules Not Initialized
+
+**Problem**: Compilation fails with missing dependencies
+
+**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"
+
+**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.
+
+### TypeScript/TSX Not Found
+
+**Problem**: `npm run wizard` fails with "tsx: command not found"
+
+**Solution**:
+```bash
+npm install  # Reinstall dependencies
+```
+
 ## Contract Architecture
 The EVVM ecosystem consists of six main contracts:
 - **Evvm.sol**: Core virtual machine implementation
@@ -372,10 +548,12 @@ The EVVM ecosystem consists of six main contracts:
 
 ## Configuration Files
 Key files for EVVM deployment:
-- `evvm-init.sh` — Interactive setup wizard
+- `scripts/evvm-init.ts` — Interactive TypeScript deployment wizard (run with `npm run wizard`)
 - `input/` — Generated configuration files (address.json, evvmBasicMetadata.json, evvmAdvancedMetadata.json)
+- `.env` — Environment variables (RPC URLs, API keys)
 - `foundry.toml` — Foundry project configuration
 - `makefile` — Build and deployment automation
+- `package.json` — NPM scripts and dependencies
 
 ## Contributing
 

package/contracts/evvm/Evvm.sol

@@ -3,7 +3,6 @@
 
 pragma solidity ^0.8.0;
 /**
-
 ░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓██████████████▓▒░  
 ░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░ 
 ░▒▓█▓▒░       ░▒▓█▓▒▒▓█▓▒░ ░▒▓█▓▒▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░ 
@@ -78,7 +77,7 @@ import {NameService} from "@evvm/testnet-contracts/contracts/nameService/NameSer
 import {EvvmStorage} from "@evvm/testnet-contracts/contracts/evvm/lib/EvvmStorage.sol";
 import {ErrorsLib} from "@evvm/testnet-contracts/contracts/evvm/lib/ErrorsLib.sol";
 import {SignatureUtils} from "@evvm/testnet-contracts/contracts/evvm/lib/SignatureUtils.sol";
-import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
+import {AdvancedStrings} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
 
 contract Evvm is EvvmStorage {
     /**
@@ -146,6 +145,8 @@ contract Evvm is EvvmStorage {
         address _stakingContractAddress,
         EvvmMetadata memory _evvmMetadata
     ) {
+        evvmMetadata = _evvmMetadata;
+        
         stakingContractAddress = _stakingContractAddress;
 
         admin.current = _initialOwner;
@@ -158,7 +159,7 @@ contract Evvm is EvvmStorage {
 
         breakerSetupNameServiceAddress = FLAG_IS_STAKER;
 
-        evvmMetadata = _evvmMetadata;
+        
     }
 
     /**
@@ -210,14 +211,14 @@ contract Evvm is EvvmStorage {
      * @dev Allows the admin to change the EVVM ID within a 1-day window after deployment
      */
     function setEvvmID(uint256 newEvvmID) external onlyAdmin {
-        if (newEvvmID == 0) {
+        if (evvmMetadata.EvvmID != 0) {
             if (block.timestamp > windowTimeToChangeEvvmID)
                 revert ErrorsLib.WindowToChangeEvvmIDExpired();
         }
 
         evvmMetadata.EvvmID = newEvvmID;
 
-        windowTimeToChangeEvvmID = block.timestamp + 1 days;
+        windowTimeToChangeEvvmID = block.timestamp + 24 hours;
     }
 
     /**
@@ -381,7 +382,7 @@ contract Evvm is EvvmStorage {
         if (priorityFlag && asyncUsedNonce[from][nonce])
             revert ErrorsLib.InvalidAsyncNonce();
 
-        address to = !Strings.equal(to_identity, "")
+        address to = !AdvancedStrings.equal(to_identity, "")
             ? NameService(nameServiceAddress).verifyStrictAndGetOwnerOfIdentity(
                 to_identity
             )
@@ -502,7 +503,7 @@ contract Evvm is EvvmStorage {
                 }
             }
 
-            to_aux = !Strings.equal(payData[iteration].to_identity, "")
+            to_aux = !AdvancedStrings.equal(payData[iteration].to_identity, "")
                 ? NameService(nameServiceAddress)
                     .verifyStrictAndGetOwnerOfIdentity(
                         payData[iteration].to_identity
@@ -634,7 +635,7 @@ contract Evvm is EvvmStorage {
         for (uint256 i = 0; i < toData.length; i++) {
             acomulatedAmount += toData[i].amount;
 
-            if (!Strings.equal(toData[i].to_identity, "")) {
+            if (!AdvancedStrings.equal(toData[i].to_identity, "")) {
                 if (
                     NameService(nameServiceAddress).strictVerifyIfIdentityExist(
                         toData[i].to_identity
@@ -951,7 +952,9 @@ contract Evvm is EvvmStorage {
      */
     function proposeImplementation(address _newImpl) external onlyAdmin {
         proposalImplementation = _newImpl;
-        timeToAcceptImplementation = block.timestamp + 30 days;
+        timeToAcceptImplementation =
+            block.timestamp +
+            TIME_TO_ACCEPT_IMPLEMENTATION;
     }
 
     /**
@@ -1000,7 +1003,7 @@ contract Evvm is EvvmStorage {
         }
 
         admin.proposal = _newOwner;
-        admin.timeToAccept = block.timestamp + 1 days;
+        admin.timeToAccept = block.timestamp + TIME_TO_ACCEPT_PROPOSAL;
     }
 
     /**

package/contracts/evvm/lib/EvvmStorage.sol

@@ -20,6 +20,8 @@ import {EvvmStructs} from "./EvvmStructs.sol";
 abstract contract EvvmStorage is EvvmStructs {
     address constant ETH_ADDRESS = address(0);
     bytes1 constant FLAG_IS_STAKER = 0x01;
+    uint256 constant TIME_TO_ACCEPT_PROPOSAL = 1 days;
+    uint256 constant TIME_TO_ACCEPT_IMPLEMENTATION = 30 days;
 
     address nameServiceAddress;
 

package/contracts/evvm/lib/SignatureUtils.sol

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
 // Full license terms available at: https://www.evvm.info/docs/EVVMNoncommercialLicense
 
-import {SignatureRecover} from "@evvm/testnet-contracts/library/SignatureRecover.sol";
-import {AdvancedStrings} from "@evvm/testnet-contracts/library/AdvancedStrings.sol";
-import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
+import {SignatureUtil} from "@evvm/testnet-contracts/library/utils/SignatureUtil.sol";
+import {AdvancedStrings} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
 
 pragma solidity ^0.8.0;
 
@@ -46,8 +45,8 @@ library SignatureUtils {
         bytes memory signature
     ) internal pure returns (bool) {
         return
-            SignatureRecover.signatureVerification(
-                Strings.toString(evvmID),
+            SignatureUtil.verifySignature(
+                evvmID,
                 "pay",
                 string.concat(
                     _receiverAddress == address(0)
@@ -56,11 +55,11 @@ library SignatureUtils {
                     ",",
                     AdvancedStrings.addressToString(_token),
                     ",",
-                    Strings.toString(_amount),
+                    AdvancedStrings.uintToString(_amount),
                     ",",
-                    Strings.toString(_priorityFee),
+                    AdvancedStrings.uintToString(_priorityFee),
                     ",",
-                    Strings.toString(_nonce),
+                    AdvancedStrings.uintToString(_nonce),
                     ",",
                     _priorityFlag ? "true" : "false",
                     ",",
@@ -98,19 +97,19 @@ library SignatureUtils {
         bytes memory signature
     ) internal pure returns (bool) {
         return
-            SignatureRecover.signatureVerification(
-                Strings.toString(evvmID),
+            SignatureUtil.verifySignature(
+                evvmID,
                 "dispersePay",
                 string.concat(
                     AdvancedStrings.bytes32ToString(hashList),
                     ",",
                     AdvancedStrings.addressToString(_token),
                     ",",
-                    Strings.toString(_amount),
+                    AdvancedStrings.uintToString(_amount),
                     ",",
-                    Strings.toString(_priorityFee),
+                    AdvancedStrings.uintToString(_priorityFee),
                     ",",
-                    Strings.toString(_nonce),
+                    AdvancedStrings.uintToString(_nonce),
                     ",",
                     _priorityFlag ? "true" : "false",
                     ",",

package/contracts/nameService/NameService.sol

@@ -57,8 +57,7 @@ pragma solidity ^0.8.0;
  */
 
 import {Evvm} from "@evvm/testnet-contracts/contracts/evvm/Evvm.sol";
-import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
-import {AdvancedStrings} from "@evvm/testnet-contracts/library/AdvancedStrings.sol";
+import {AdvancedStrings} from "@evvm/testnet-contracts/library/utils/AdvancedStrings.sol";
 import {ErrorsLib} from "@evvm/testnet-contracts/contracts/nameService/lib/ErrorsLib.sol";
 import {SignatureUtils} from "@evvm/testnet-contracts/contracts/nameService/lib/SignatureUtils.sol";
 
@@ -129,6 +128,11 @@ contract NameService {
         uint256 amount;
     }
 
+    uint256 constant TIME_TO_ACCEPT_PROPOSAL = 1 days;
+
+    /// @dev Amount of Principal Tokens locked in pending marketplace offers
+    uint256 private principalTokenTokenLockedForWithdrawOffers;
+
     /// @dev Nested mapping: username => offer ID => offer details
     mapping(string username => mapping(uint256 id => OfferMetadata))
         private usernameOffers;
@@ -153,9 +157,6 @@ contract NameService {
     address private constant PRINCIPAL_TOKEN_ADDRESS =
         0x0000000000000000000000000000000000000001;
 
-    /// @dev Amount of Principal Tokens locked in pending marketplace offers
-    uint256 private principalTokenTokenLockedForWithdrawOffers;
-
     /// @dev Restricts function access to the current admin address only
     modifier onlyAdmin() {
         if (msg.sender != admin.current) revert ErrorsLib.SenderIsNotAdmin();
@@ -955,7 +956,7 @@ contract NameService {
         }
 
         admin.proposal = _adminToPropose;
-        admin.timeToAccept = block.timestamp + 1 days;
+        admin.timeToAccept = block.timestamp + TIME_TO_ACCEPT_PROPOSAL;
     }
 
     /**
@@ -1007,7 +1008,9 @@ contract NameService {
         }
 
         amountToWithdrawTokens.proposal = _amount;
-        amountToWithdrawTokens.timeToAccept = block.timestamp + 1 days;
+        amountToWithdrawTokens.timeToAccept =
+            block.timestamp +
+            TIME_TO_ACCEPT_PROPOSAL;
     }
 
     /**
@@ -1046,7 +1049,7 @@ contract NameService {
             revert();
         }
         evvmAddress.proposal = _newEvvmAddress;
-        evvmAddress.timeToAccept = block.timestamp + 1 days;
+        evvmAddress.timeToAccept = block.timestamp + TIME_TO_ACCEPT_PROPOSAL;
     }
 
     /**

package/contracts/nameService/lib/ErrorsLib.sol

@@ -24,4 +24,4 @@ library ErrorsLib {
     error EmptyCustomMetadata();
     error InvalidKey();
     error FlushUsernameVerificationFailed();
-}
+}