@evvm/testnet-contracts 2.1.1 → 2.1.3

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;
 /**
-
 ░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓██████████████▓▒░  
 ░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░ 
 ░▒▓█▓▒░       ░▒▓█▓▒▒▓█▓▒░ ░▒▓█▓▒▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░ 
@@ -217,7 +216,7 @@ contract Evvm is EvvmStorage {
 
         evvmMetadata.EvvmID = newEvvmID;
 
-        windowTimeToChangeEvvmID = block.timestamp + 1 days;
+        windowTimeToChangeEvvmID = block.timestamp + 1 minutes;
     }
 
     /**
@@ -1000,7 +999,7 @@ contract Evvm is EvvmStorage {
         }
 
         admin.proposal = _newOwner;
-        admin.timeToAccept = block.timestamp + 1 days;
+        admin.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**

package/contracts/evvm/EvvmLegacy.sol

@@ -1225,7 +1225,7 @@ contract Evvm is EvvmStorage {
         }
 
         admin.proposal = _newOwner;
-        admin.timeToAccept = block.timestamp + 1 days;
+        admin.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**

package/contracts/evvm/lib/SignatureUtils.sol

@@ -14,7 +14,6 @@ library SignatureUtils {
      *       by the users
      */
 
-
     /**
      *  @notice This function is used to verify the message signed for the payment
      *  @param signer user who signed the message

package/contracts/nameService/NameService.sol

@@ -955,7 +955,7 @@ contract NameService {
         }
 
         admin.proposal = _adminToPropose;
-        admin.timeToAccept = block.timestamp + 1 days;
+        admin.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -1007,7 +1007,7 @@ contract NameService {
         }
 
         amountToWithdrawTokens.proposal = _amount;
-        amountToWithdrawTokens.timeToAccept = block.timestamp + 1 days;
+        amountToWithdrawTokens.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -1046,7 +1046,7 @@ contract NameService {
             revert();
         }
         evvmAddress.proposal = _newEvvmAddress;
-        evvmAddress.timeToAccept = block.timestamp + 1 days;
+        evvmAddress.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**

package/contracts/p2pSwap/P2PSwap.sol

@@ -819,7 +819,7 @@ contract P2PSwap is StakingServiceHooks {
             revert();
         }
         owner_proposal = _owner;
-        owner_timeToAccept = block.timestamp + 1 days;
+        owner_timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -868,7 +868,7 @@ contract P2PSwap is StakingServiceHooks {
             revert();
         }
         rewardPercentage_proposal = Percentage(_seller, _service, _mateStaker);
-        rewardPercentage_timeToAcceptNewChange = block.timestamp + 1 days;
+        rewardPercentage_timeToAcceptNewChange = block.timestamp + 1 minutes;
     }
 
     /**
@@ -915,7 +915,7 @@ contract P2PSwap is StakingServiceHooks {
             revert();
         }
         rewardPercentage_proposal = Percentage(_seller, _service, _mateStaker);
-        rewardPercentage_timeToAcceptNewChange = block.timestamp + 1 days;
+        rewardPercentage_timeToAcceptNewChange = block.timestamp + 1 minutes;
     }
 
     /**
@@ -956,7 +956,7 @@ contract P2PSwap is StakingServiceHooks {
             revert();
         }
         percentageFee_proposal = _percentageFee;
-        percentageFee_timeToAccept = block.timestamp + 1 days;
+        percentageFee_timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -997,7 +997,7 @@ contract P2PSwap is StakingServiceHooks {
             revert();
         }
         maxLimitFillFixedFee_proposal = _maxLimitFillFixedFee;
-        maxLimitFillFixedFee_timeToAccept = block.timestamp + 1 days;
+        maxLimitFillFixedFee_timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -1049,7 +1049,7 @@ contract P2PSwap is StakingServiceHooks {
         tokenToWithdraw = _tokenToWithdraw;
         amountToWithdraw = _amountToWithdraw;
         recipientToWithdraw = _to;
-        timeToWithdrawal = block.timestamp + 1 days;
+        timeToWithdrawal = block.timestamp + 1 minutes;
     }
 
     /**

package/contracts/staking/Estimator.sol

@@ -180,7 +180,7 @@ contract Estimator {
         address _proposal
     ) external onlyActivator {
         activator.proposal = _proposal;
-        activator.timeToAccept = block.timestamp + 1 days;
+        activator.timeToAccept = block.timestamp + 1 minutes;
     }
 
     function cancelActivatorProposal() external onlyActivator {
@@ -200,7 +200,7 @@ contract Estimator {
         address _proposal
     ) external onlyAdmin {
         evvmAddress.proposal = _proposal;
-        evvmAddress.timeToAccept = block.timestamp + 1 days;
+        evvmAddress.timeToAccept = block.timestamp + 1 minutes;
     }
 
     function cancelEvvmAddressProposal() external onlyAdmin {
@@ -220,7 +220,7 @@ contract Estimator {
         address _proposal
     ) external onlyAdmin {
         addressStaking.proposal = _proposal;
-        addressStaking.timeToAccept = block.timestamp + 1 days;
+        addressStaking.timeToAccept = block.timestamp + 1 minutes;
     }
 
     function cancelAddressStakingProposal() external onlyAdmin {
@@ -240,7 +240,7 @@ contract Estimator {
         address _proposal
     ) external onlyAdmin {
         admin.proposal = _proposal;
-        admin.timeToAccept = block.timestamp + 1 days;
+        admin.timeToAccept = block.timestamp + 1 minutes;
     }
 
     function cancelAdminProposal() external onlyAdmin {

package/contracts/staking/Staking.sol

@@ -216,7 +216,7 @@ contract Staking {
 
         secondsToUnlockStaking.actual = 0;
 
-        secondsToUnllockFullUnstaking.actual = 21 days;
+        secondsToUnllockFullUnstaking.actual = 30 seconds;
 
         breakerSetupEstimatorAndEvvm = 0x01;
     }
@@ -761,7 +761,7 @@ contract Staking {
      */
     function proposeAdmin(address _newAdmin) external onlyOwner {
         admin.proposal = _newAdmin;
-        admin.timeToAccept = block.timestamp + 1 days;
+        admin.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -795,7 +795,7 @@ contract Staking {
      */
     function proposeGoldenFisher(address _goldenFisher) external onlyOwner {
         goldenFisher.proposal = _goldenFisher;
-        goldenFisher.timeToAccept = block.timestamp + 1 days;
+        goldenFisher.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -829,7 +829,7 @@ contract Staking {
         uint256 _secondsToUnlockStaking
     ) external onlyOwner {
         secondsToUnlockStaking.proposal = _secondsToUnlockStaking;
-        secondsToUnlockStaking.timeToAccept = block.timestamp + 1 days;
+        secondsToUnlockStaking.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -863,7 +863,7 @@ contract Staking {
         uint256 _secondsToUnllockFullUnstaking
     ) external onlyOwner {
         secondsToUnllockFullUnstaking.proposal = _secondsToUnllockFullUnstaking;
-        secondsToUnllockFullUnstaking.timeToAccept = block.timestamp + 1 days;
+        secondsToUnllockFullUnstaking.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -894,7 +894,7 @@ contract Staking {
      * @dev Initiates the time-delayed process to enable/disable public staking
      */
     function prepareChangeAllowPublicStaking() external onlyOwner {
-        allowPublicStaking.timeToAccept = block.timestamp + 1 days;
+        allowPublicStaking.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -924,7 +924,7 @@ contract Staking {
      * @dev Initiates the time-delayed process to enable/disable presale staking
      */
     function prepareChangeAllowPresaleStaking() external onlyOwner {
-        allowPresaleStaking.timeToAccept = block.timestamp + 1 days;
+        allowPresaleStaking.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**
@@ -956,7 +956,7 @@ contract Staking {
      */
     function proposeEstimator(address _estimator) external onlyOwner {
         estimator.proposal = _estimator;
-        estimator.timeToAccept = block.timestamp + 1 days;
+        estimator.timeToAccept = block.timestamp + 1 minutes;
     }
 
     /**