@evvm/testnet-contracts 2.2.3 → 3.0.0

package/LICENSE

@@ -1,166 +1,193 @@
-Copyright (c) 2025
-MATE Labs Inc., a Delaware corporation ("Licensor")
+================================================================================
+EVVM NONCOMMERCIAL LICENSE v1.0
+================================================================================
 
-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:
+SPDX-License-Identifier: EVVM-NONCOMMERCIAL-1.0
+
+Copyright (c) 2025 MATE Labs Inc., a Delaware corporation
+
+================================================================================
+
+1. OVERVIEW
+
+This software is licensed under a modified PolyForm Noncommercial License
+1.0.0 with additional share-alike requirements. You may use, modify, and
+distribute this software for noncommercial purposes only, subject to the terms
+below.
+
+COMMERCIAL USE REQUIRES A SEPARATE LICENSE.
+For commercial licensing inquiries, contact: g@evvm.org
+
+Full license text available 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.
+================================================================================
+
+2. BASE LICENSE: PolyForm Noncommercial 1.0.0
+
+2.1 Acceptance
+
+By using this software, you agree to these terms as binding obligations and
+conditions.
+
+2.2 Copyright License
+
+MATE Labs Inc. grants you a copyright license to use the software for any
+permitted purpose, subject to the distribution and modification restrictions
+below.
+
+2.3 Distribution License
+
+You may distribute copies of the software, including modified versions,
+provided you comply with Section 3 (Share-Alike Requirements) and Section 2.4
+(Notices).
+
+2.4 Notices
+
+Anyone receiving the software from you must also receive:
+  - A copy of this license or the URL:
+    https://polyformproject.org/licenses/noncommercial/1.0.0/
+  - The following notice: "Copyright (c) 2025 MATE Labs Inc."
+
+2.5 Changes and New Works License
+
+You may create modifications and derivative works for any permitted purpose,
+subject to Section 3.
+
+2.6 Patent License
+
+MATE Labs Inc. grants you a patent license covering any patent claims that
+would be infringed by using the software.
+
+2.7 Permitted Purposes
+
+The following are permitted purposes:
+
+  - Noncommercial purposes: Any use that does not generate revenue or provide
+    commercial advantage
 
---------------------------------------------------------------------------------
+  - Personal use: Research, experimentation, testing, study, entertainment,
+    hobbies, or religious observance without commercial application
 
-# PolyForm Noncommercial License 1.0.0
+  - Noncommercial organizations: Use by charitable, educational, research,
+    public safety, health, environmental, or government institutions
 
-https://polyformproject.org/licenses/noncommercial/1.0.0
+2.8 Fair Use
 
-## Acceptance
+These terms do not limit your fair use rights under applicable law.
 
-In order to get any license under these terms, you must agree
-to them as both strict obligations and conditions to all
-your licenses.
+2.9 No Sublicensing
 
-## Copyright License
+You may not sublicense or transfer your licenses to others.
 
-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).
+2.10 Patent Defense
 
-## Distribution License
+If you or your company claims the software infringes any patent, all your
+licenses terminate immediately.
 
-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).
+2.11 Violations and Cure Period
 
-## Notices
+If you violate these terms, you have 32 days from written notification to:
+  - Come into full compliance, AND
+  - Take practical steps to correct past violations
 
-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:
+Otherwise, all licenses terminate immediately.
 
-> Required Notice: Copyright (c) 2025 MATE Labs Inc., a Delaware corporation ("Licensor")
+================================================================================
 
-## Changes and New Works License
+3. SHARE-ALIKE REQUIREMENTS
 
-The licensor grants you an additional copyright license to
-make changes and new works based on the software for any
-permitted purpose.
+3.1 Scope
 
-## Patent License
+If you create a Derivative Work and engage in Triggering Distribution, you
+must publicly release that Derivative Work under this same 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.
+3.2 Definitions
 
-## Noncommercial Purposes
+"Derivative Work" means any modification, enhancement, or work based on the
+software that:
+  - Alters, adds, or removes functionality of the original code
+  - Incorporates substantial portions of the original source code
+  - Creates new components that depend on or interface with the original
+    software
 
-Any noncommercial purpose is a permitted purpose.
+Derivative Work does NOT include:
+  - Configuration files or parameters
+  - Plugins or extensions that use only public APIs
+  - Works that merely link to or use the software as a library without
+    modification
 
-## Personal Uses
+"Triggering Distribution" means:
+  - Making the Derivative Work available to any third party (whether by
+    download, hosting, or other means)
+  - Using the Derivative Work to provide services accessible to third parties
+  - Deploying the Derivative Work in production environments accessible to
+    others
 
-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.
+3.3 Publication Requirements
 
-## Noncommercial Organizations
+Within 90 days of first Triggering Distribution, you must:
 
-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.
+  1. Publish source code on a publicly accessible platform (e.g., GitHub,
+     GitLab, Codeberg)
 
-## Fair Use
+  2. Include this license with the published code
 
-You may have "fair use" rights for the software under the
-law. These terms do not limit them.
+  3. Provide clear attribution identifying:
+     - The original work (EVVM)
+     - MATE Labs Inc. as the original licensor
+     - A description of your modifications
 
-## No Other Rights
+  4. Ensure accessibility - the code must remain publicly available for at
+     least 3 years
 
-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.
+3.4 Internal Use Exception
 
-## Patent Defense
+You are NOT required to publish Derivative Works that:
+  - Remain internal to your organization
+  - Are not distributed to third parties
+  - Are not used to provide services to external users
 
-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.
+However, once you engage in Triggering Distribution, the 90-day publication
+requirement begins.
 
-## 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.
+4. NO LIABILITY
 
-## No Liability
+AS FAR AS THE LAW ALLOWS, THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY
+WARRANTY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT.
 
-***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.***
+MATE LABS INC. SHALL NOT BE LIABLE FOR ANY DAMAGES ARISING FROM THE USE OF
+THIS SOFTWARE UNDER ANY LEGAL THEORY.
 
-## Definitions
+================================================================================
 
-The **licensor** is GERMAN MARIA ABAL BAZZANO (g@evvm.org),
-and the **software** is EVVM and related components made
-available under these terms.
+5. DEFINITIONS
 
-**You** refers to the individual or entity agreeing to these
-terms.
+  - "MATE Labs Inc." or "Licensor": MATE Labs Inc., a Delaware corporation
 
-**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.
+  - "Software": EVVM and all related components distributed under this license
 
-**Your licenses** are all the licenses granted to you for the
-software under these terms.
+  - "You": The individual or entity agreeing to these terms
 
-**Use** means anything you do with the software requiring one
-of your licenses.
+  - "Your company": Any legal entity you work for, plus all entities under
+    common control
 
---------------------------------------------------------------------------------
+  - "Control": Ownership of substantially all assets or power to direct
+    management
 
-ADDITIONAL TERMS (Share-Alike Requirement):
+  - "Use": Any activity with the software requiring a license
 
-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.
+6. QUESTIONS AND COMMERCIAL LICENSING
 
-3. These terms supplement and do not replace any conditions in the PolyForm
-   Noncommercial 1.0.0 license.
+For questions about this license or to obtain a commercial license:
+  - Email: g@evvm.org
+  - Include "EVVM License Inquiry" in subject line
 
---------------------------------------------------------------------------------
+================================================================================
 
-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.
+END OF LICENSE

package/README.md

@@ -1,91 +1,214 @@
 # EVVM Testnet Contracts
 
-[![npm version](https://img.shields.io/npm/v/@evvm/testnet-contracts.svg)](https://www.npmjs.com/package/@evvm/testnet-contracts) [![license](https://img.shields.io/badge/license-EVVM--NONCOMMERCIAL--1.0-blue.svg)](LICENSE) [![docs](https://img.shields.io/badge/docs-evvm.info-blue.svg)](https://www.evvm.info/)[![npm downloads](https://img.shields.io/npm/dw/@evvm/testnet-contracts.svg)](https://www.npmjs.com/package/@evvm/testnet-contracts) 
+![Version](https://img.shields.io/badge/version-3.0.0%20%22Ichiban%22-red.svg)
+![Solidity](https://img.shields.io/badge/Solidity-^0.8.0-363636?logo=solidity)
+![Foundry](https://img.shields.io/badge/Built%20with-Foundry-FFDB1C?logo=foundry)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript)
+![Bun](https://img.shields.io/badge/Runtime-Bun-000000?logo=bun)
+[![license](https://img.shields.io/badge/license-EVVM--NONCOMMERCIAL--1.0-blue.svg)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-evvm.info-blue.svg)](https://www.evvm.info/)
+[![npm downloads](https://img.shields.io/npm/dw/@evvm/testnet-contracts.svg)](https://www.npmjs.com/package/@evvm/testnet-contracts)
+![Status](https://img.shields.io/badge/Status-Active-brightgreen)
 
 A compact toolkit for creating virtual EVM chains on testnets.
 
-Quick overview
-- Use the Solidity packages in `src/` as a library (install via NPM or Forge).
-- Use the `evvm` CLI to deploy and manage EVVM instances.
+Two ways to use EVVM:
+
+1. As a library - Import Solidity contracts in your dApp
+2. As a CLI tool - Deploy and manage EVVM instances on testnets
 
 Docs & hosted library: https://www.evvm.info/
 
+## Use as a Library (for dApp developers)
+
+### Install the library (1 min)
 
-Install the library (1 min)
+**NPM (recommended):**
 
 ```bash
-# NPM (recommended for dApp developers)
 npm install @evvm/testnet-contracts
+```
+
+**Or with Forge:**
 
-# Or with Forge
+```bash
 forge install EVVM-org/Testnet-Contracts
 ```
 
-Guide: How to build on top of EVVM (library): https://www.evvm.info/docs/HowToMakeAEVVMService
+**Import in your contracts:**
+
+```solidity
+import "@evvm/testnet-contracts/interfaces/ICore.sol";
+```
+
+Guide: How to build on top of EVVM: https://www.evvm.info/docs/HowToMakeAEVVMService
+
+## Use as a CLI Tool (for EVVM deployment)
+
+### Requirements
+
+Before deploying with the CLI, ensure you have the following installed:
+
+- **Foundry** - [Install](https://getfoundry.sh/introduction/installation/)
+- **Bun** (≥ 1.0) - [Install](https://bun.sh/)
+- **Git** - [Install](https://git-scm.com/downloads)
+
+### Quick start (2 min)
+
+1. Clone & install
 
-Quick start (2 min)
-1) Clone & install
 ```bash
 git clone --recursive https://github.com/EVVM-org/Testnet-Contracts
 cd Testnet-Contracts
-make install
+
+# Option 1: Using CLI (recommended)
+chmod +x ./evvm
+./evvm install
+
+# Option 2: Manual installation
+bun install
+forge install
 ```
 
-2) Prepare environment
+2. Prepare environment
+
 ```bash
 cp .env.example .env
 # Edit RPC_URL, ETHERSCAN_API, etc.
 ```
 
-3) Import wallet (secure)
+3. Import wallet (secure)
+
 ```bash
 cast wallet import defaultKey --interactive
 ```
 
-4) Deploy (interactive)
+4. Deploy (interactive)
+
+If you are on Linux or macOS, run:
+
+```bash
+./evvm deploy
+```
+
+If you are on Windows, run on PowerShell:
+
+```powershell
+.\evvm.bat deploy
+```
+
+Or use Bun from any directory:
+
 ```bash
-# If installed globally:
-evvm deploy
-# Or from repo:
 bun run evvm deploy
 ```
+
+**Using CLI Scripts (Recommended for local development)**
+
+The repository includes platform-specific wrapper scripts to easily call the CLI:
+
+**Linux/macOS:**
+
+```bash
+# Make script executable (first time only)
+chmod +x ./evvm
+
+# Run any EVVM CLI command
+./evvm deploy
+./evvm register --coreAddress 0x...
+./evvm developer --makeInterface
+./evvm help
+```
+
+**Windows (PowerShell):**
+
+```powershell
+# Run any EVVM CLI command
+.\evvm.bat deploy
+.\evvm.bat register --coreAddress 0x...
+.\evvm.bat developer --makeInterface
+.\evvm.bat help
+```
+
+The scripts automatically detect your OS and architecture (x64, ARM64, MUSL) and execute the appropriate compiled binary from `.executables/` folder.
+
 Quick Start (CLI): https://www.evvm.info/docs/QuickStart
 
-CLI - common commands
-- evvm deploy       # deploy EVVM (single or cross-chain)
-- evvm register     # register EVVM in registry
-- evvm fulltest     # run full test suite
-- evvm help         # show CLI help
-- evvm version      # CLI version
+## CLI - Available Commands
+
+**Deployment & Registration:**
+
+- `evvm deploy` # Deploy EVVM (single or cross-chain)
+- `evvm deploy --skipInputConfig` # Deploy with existing config (no prompts)
+- `evvm deploy --crossChain` # Deploy cross-chain EVVM instance
+- `evvm register --coreAddress <addr>` # Register EVVM in registry
+- `evvm register --crossChain` # Register cross-chain EVVM
+
+**Cross-Chain Management:**
 
-Library usage (quick)
-- NPM: `npm install @evvm/testnet-contracts`
-- Forge: `forge install EVVM-org/Testnet-Contracts`
-- Import interfaces: `import "@evvm/testnet-contracts/interfaces/IEvvm.sol";`
+- `evvm setUpCrossChainTreasuries` # Configure treasury station connections
 
-Troubleshooting (short)
-- RPC timeouts: CLI automatically tries fallback RPCs; set `RPC_URL` in `.env` to a reliable endpoint.
-- Wallet not found: import with `cast wallet import <name> --interactive`.
-- Bun missing: install Bun (`curl -fsSL https://bun.sh/install | bash`).
-- Tests: run `evvm fulltest` or `forge test`.
+**Developer Utilities:**
+
+- `evvm developer --makeInterface` # Generate Solidity interfaces from contracts
+- `evvm developer --runTest` # Run test suites with custom filters
+- `evvm install` # Install Bun and Foundry dependencies
+
+**Information:**
+
+- `evvm help` # Show comprehensive CLI help
+- `evvm version` # Show CLI version
+
+## Library Usage (Quick Reference)
+
+- **NPM install:** `npm install @evvm/testnet-contracts`
+- **Forge install:** `forge install EVVM-org/Testnet-Contracts`
+- **Import in Solidity:** `import "@evvm/testnet-contracts/interfaces/ICore.sol";`
+
+## Troubleshooting
+
+- **RPC timeouts**: CLI automatically tries fallback RPCs; set `RPC_URL` in `.env` to a reliable endpoint.
+- **Wallet not found**: import with `cast wallet import <name> --interactive`.
+- **Bun missing**: install Bun (`curl -fsSL https://bun.sh/install | bash`).
+- **Tests**: run `./evvm developer --runTest` (Linux/Mac) or `evvm.bat developer --runTest` (Windows), or `forge test`.
+- **Script not executable (Linux/Mac)**: run `chmod +x ./evvm` and ensure `.executables/` binaries have execute permissions.
+- **Wrong architecture detected**: The wrapper scripts auto-detect OS/architecture. If issues occur, manually run the correct binary from `.executables/`.
 
 Files & structure (short)
+
 - `src/contracts/` — core contracts (Evvm, NameService, Staking, Treasury, P2PSwap)
 - `cli/` — TypeScript CLI source
 - `script/` — Foundry deployment scripts
 - `input/` — optional JSON/Sol files generated by CLI
+- `.executables/` — pre-compiled CLI binaries for multiple platforms
+- `evvm` — Linux/macOS CLI wrapper script (auto-detects architecture)
+- `evvm.bat` — Windows CLI wrapper script (auto-detects architecture)
 
-Security & contributing (short)
-- Never commit private keys. Use `cast wallet import`.
-- Add tests for new features and open a PR.
+## Security & Contributing
 
 ### How to Contribute
-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
+
+We welcome contributions from the community! Here's how you can help:
+
+1. **Report Issues** - Found a bug or have a suggestion? [Open an issue on GitHub](https://github.com/EVVM-org/Testnet-Contracts/issues)
+2. **Suggest Features** - Have an idea for improvement? [Create a feature request issue](https://github.com/EVVM-org/Testnet-Contracts/issues)
+3. **Submit Code Changes**:
+   - Fork the repository
+   - Create a feature branch (`git checkout -b feature/amazing-feature`)
+   - Make your changes and add tests
+   - Push to your branch (`git push origin feature/amazing-feature`)
+   - Submit a Pull Request with a detailed description
+
+### Guidelines
+
+- **Issues**: Use [GitHub Issues](https://github.com/EVVM-org/Testnet-Contracts/issues) for bug reports, feature requests, and discussions
+- **Pull Requests**: Each PR should reference a related issue
+- **Tests**: All new features must include tests
+- **Code Style**: Follow the existing code patterns in the repository
+- **Commit Messages**: Write clear, descriptive commit messages
 
 ## 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)