@evvm/testnet-contracts 1.0.0

package/LICENSE

@@ -0,0 +1,166 @@
+Copyright (c) 2025
+GERMAN MARIA ABAL BAZZANO <g@evvm.org>
+
+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:
+https://polyformproject.org/licenses/noncommercial/1.0.0/
+
+COMMERCIAL USE OF THIS SOFTWARE REQUIRES A SEPARATE COMMERCIAL LICENSE.
+For commercial licensing, please contact g@evvm.org.
+
+--------------------------------------------------------------------------------
+
+# PolyForm Noncommercial License 1.0.0
+
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+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)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is GERMAN MARIA ABAL BAZZANO (g@evvm.org),
+and the **software** is EVVM and related components made
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+--------------------------------------------------------------------------------
+
+ADDITIONAL TERMS (Share-Alike Requirement):
+
+1. Any modifications, enhancements, or derivative works created under non-commercial use
+   must be publicly released under this same License within 90 days of creation,
+   distribution, or other availability.
+
+2. "Publicly released" requires making source code freely accessible on platforms like
+   GitHub or GitLab, with clear attribution to the original work.
+
+3. These terms supplement and do not replace any conditions in the PolyForm
+   Noncommercial 1.0.0 license.
+
+--------------------------------------------------------------------------------
+
+DISCLAIMER OF WARRANTY:
+THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
+FROM THE USE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# EVVM Testnet Contracts
+
+![](https://github.com/user-attachments/assets/08d995ee-7512-42e4-a26c-0d62d2e8e0bf)
+
+The Ethereum Virtual Virtual Machine (EVVM) ⚙️
+
+**This repository is the next step after successful playground testing. It is dedicated to advanced integration, deployment, and validation on public testnets, before mainnet implementation.**
+
+EVVM provides a comprehensive set of smart contracts and tools for scalable, modular, and cross-chain EVM virtualization. This repo is intended for developers who want to:
+- Test and validate contracts on public testnets (Ethereum Sepolia, Arbitrum Sepolia)
+- Prepare for mainnet deployment after testnet validation
+- Contribute to the evolution of the EVVM protocol
+
+## Repository Structure
+- `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/lib/` — Shared Solidity libraries (AdvancedStrings, SignatureRecover, etc.)
+- `script/` — Deployment and automation scripts (e.g., `DeployTestnet.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 `evvm-init.sh`)
+- `evvm-init.sh` — Interactive setup and deployment script
+
+## Public EVVM Contract Address
+
+### Ethereum Sepolia Testnet
+- **EVVM**: [0x2029bb5e15E22c19Bc8bde3426fab29dD4db8A98](https://sepolia.etherscan.io/address/0x2029bb5e15E22c19Bc8bde3426fab29dD4db8A98#code)
+- **NameService**: [0xD904f38B8c9968AbAb63f47c21aB120FCe59F013](https://sepolia.etherscan.io/address/0xD904f38B8c9968AbAb63f47c21aB120FCe59F013#code)
+- **Staking**: [0xA68D4a0cFFDc6145D35Ae27521d01b166Fe4AE46](https://sepolia.etherscan.io/address/0xA68D4a0cFFDc6145D35Ae27521d01b166Fe4AE46#code)
+- **Estimator**: [0x2aBEAD7519c9AFc14eEc2582dDD9FF04f0da0F42](https://sepolia.etherscan.io/address/0x2aBEAD7519c9AFc14eEc2582dDD9FF04f0da0F42#code)
+- **Treasury**: [0x98465F828b82d0b676937e159547F35BBDBdfe91](https://sepolia.etherscan.io/address/0x98465F828b82d0b676937e159547F35BBDBdfe91#code)
+
+### Arbitrum Sepolia Testnet
+- **EVVM**: [0xC688C12541Ff85EF3E63755F6889317f312d03A3](https://sepolia.arbiscan.io/address/0xC688C12541Ff85EF3E63755F6889317f312d03A3#code)
+- **NameService**: [0x82Fbac7857E8407cE6578E02B0be0d3Cd15Fb790](https://sepolia.arbiscan.io/address/0x82Fbac7857E8407cE6578E02B0be0d3Cd15Fb790#code)
+- **Staking**: [0xaC3C70604a5633807Ae0149B6E6766452355635C](https://sepolia.arbiscan.io/address/0xaC3C70604a5633807Ae0149B6E6766452355635C#code)
+- **Estimator**: [0xC4FF60fBAEf050FC476f4Ab10CA75378A2Cc79A3](https://sepolia.arbiscan.io/address/0xC4FF60fBAEf050FC476f4Ab10CA75378A2Cc79A3#code)
+- **Treasury**: [0x7d4F9D95e84f6903c7247527e6BF1FA864F7c764](https://sepolia.arbiscan.io/address/0x7d4F9D95e84f6903c7247527e6BF1FA864F7c764#code)
+
+## Development Flow
+1. **Playground**: Prototype and experiment with new features in the playground repo.
+2. **Testnet (this repo)**: Integrate, test, and validate on public testnets.
+3. **Mainnet**: After successful testnet validation, proceed to mainnet deployment.
+
+## Prerequisites
+- [Foundry](https://getfoundry.sh/) (Solidity development toolkit)
+- Node.js (for dependency management)
+- Bash shell (for running `evvm-init.sh`)
+- 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>
+ETHERSCAN_API=<YOUR_ETHERSCAN_API_KEY>
+```
+
+### Security Setup - Import Private Key
+Before deploying to testnets, securely import your private key using Foundry:
+```bash
+cast wallet import defaultKey --interactive
+```
+This command will prompt you to enter your private key securely. The key will be encrypted and stored locally by Foundry.
+
+> **Note**: `defaultKey` is the default alias used in the makefile and deployment scripts. If you prefer to use a different alias, simply replace `defaultKey` with your chosen name in both the import command and update the corresponding references in the makefile and scripts.
+
+> **Security Note**: Never commit real private keys to version control. Always use the secure wallet import method above for testnet and mainnet deployments.
+
+## Key Dependencies
+- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts)
+
+## Quick Start
+
+Deploy your EVVM virtual blockchain on testnet in 4 simple steps:
+
+### 1. Clone and Install
+```bash
+git clone https://github.com/EVVM-org/Testnet-Contracts
+cd Testnet-Contracts
+make install
+```
+
+### 2. Environment Setup
+Create `.env` file with your configuration:
+```bash
+cp .env.example .env
+# Add your RPC URLs and API keys
+```
+
+### 3. Secure Key Import
+```bash
+cast wallet import defaultKey --interactive
+```
+
+### 4. Interactive Setup & Deploy
+```bash
+./evvm-init.sh
+```
+
+The wizard will configure:
+- **Administrator addresses** (admin, golden fisher, activator)
+- **EVVM metadata** (name, ID, principal token details)
+- **Advanced parameters** (supply, rewards) - optional
+- **Network selection** (Ethereum Sepolia, Arbitrum Sepolia, or custom)
+- **Automatic deployment** with contract verification
+
+That's it! Your EVVM virtual blockchain is now deployed and verified on your chosen host blockchain.
+
+## Manual Configuration (Alternative)
+
+If you prefer manual control over configuration, create these files in `input/`:
+
+**input/address.json**:
+```json
+{
+  "admin": "0x...",
+  "goldenFisher": "0x...",
+  "activator": "0x..."
+}
+```
+
+**input/evvmBasicMetadata.json**:
+```json
+{
+  "EvvmName": "EVVM",
+  "EvvmID": 1,
+  "principalTokenName": "Mate token",
+  "principalTokenSymbol": "MATE"
+}
+```
+
+**input/evvmAdvancedMetadata.json**:
+```json
+{
+  "totalSupply": 2033333333000000000000000000,
+  "eraTokens": 1016666666500000000000000000,
+  "reward": 5000000000000000000
+}
+```
+
+## Local Development
+Start a local Anvil chain:
+```bash
+make anvil
+```
+
+Deploy contracts to local testnet:
+```bash
+make deployLocalTestnet
+```
+
+## Manual Deployment
+
+If you prefer to deploy manually after configuration:
+
+```bash
+# Ethereum Sepolia
+make deployTestnet NETWORK=eth
+
+# Arbitrum Sepolia  
+make deployTestnet NETWORK=arb
+
+# Custom RPC
+forge script script/DeployTestnet.s.sol:DeployTestnet \
+    --rpc-url <YOUR_RPC_URL> \
+    --account defaultKey \
+    --broadcast \
+    --verify \
+    --etherscan-api-key $ETHERSCAN_API
+```
+
+## Local Development
+```bash
+make anvil                # Start local blockchain
+make deployLocalTestnet   # Deploy to local chain
+```
+
+## Development Commands
+```bash
+make install     # Install dependencies and compile
+make compile     # Recompile contracts
+make seeSizes    # Check contract sizes
+make help        # Show all available commands
+```
+
+## Contract Architecture
+The EVVM ecosystem consists of five main contracts:
+- **Evvm.sol**: Core virtual machine implementation
+- **NameService.sol**: Domain name resolution system  
+- **Staking.sol**: Token staking and rewards mechanism
+- **Estimator.sol**: Staking rewards estimation and calculation
+- **Treasury.sol**: Manages deposits and withdrawals of ETH and ERC20 tokens
+- **Treasury.sol**: Manages deposits and withdrawals of ETH and ERC20 tokens
+
+## Configuration Files
+Key files for EVVM deployment:
+- `evvm-init.sh` — Interactive setup wizard
+- `input/` — Generated configuration files (address.json, evvmBasicMetadata.json, evvmAdvancedMetadata.json)
+- `foundry.toml` — Foundry project configuration
+- `makefile` — Build and deployment automation
+
+## Contributing
+1. Fork the repository
+2. Create a feature branch and make changes
+3. Add tests for new features
+4. Submit a PR with a detailed description
+
+## Security Best Practices
+- **Never commit private keys**: Always use `cast wallet import <YOUR_ALIAS> --interactive` to securely store your keys
+- **Use test credentials only**: This repository is for testnet deployment only
+- **Environment variables**: Store sensitive data like API keys in `.env` files (not committed to git)
+- **Verify contracts**: Always verify your deployed contracts on block explorers

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@evvm/testnet-contracts",
+  "version": "1.0.0",
+  "description": "EVVM Testnet Contracts - Smart contracts and tools for scalable, modular, and cross-chain EVM virtualization",
+  "files": [
+    "src/**/*.sol",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "evvm",
+    "ethereum",
+    "virtual-machine",
+    "solidity",
+    "smart-contracts",
+    "cross-chain",
+    "testnet",
+    "evm",
+    "blockchain",
+    "defi"
+  ],
+  "author": "EVVM Organization",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EVVM-org/Testnet-Contracts.git"
+  },
+  "homepage": "https://github.com/EVVM-org/Testnet-Contracts#readme",
+  "bugs": {
+    "url": "https://github.com/EVVM-org/Testnet-Contracts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "forge build",
+    "test": "forge test",
+    "deploy:anvil": "make deployLocalTestnet",
+    "deploy:sepolia": "make deployTestnet NETWORK=eth",
+    "deploy:arbitrum": "make deployTestnet NETWORK=arb"
+  },
+  "peerDependencies": {
+    "@openzeppelin/contracts": "^5.0.0"
+  },
+  "dependencies": {
+    "@hyperlane-xyz/core": "^3.6.1"
+  },
+  "devDependencies": {
+    "forge-std": "^1.0.0"
+  }
+}