EVM Smart Contracts
Relevant source files
The following files were used as context for generating this wiki page:
EVM (Ethereum Virtual Machine) smart contracts within the X3-VM ecosystem serve as a critical layer for trust-minimized atomic swaps and cross-chain liquidity coordination. These contracts allow the X3 Chain to interface with Ethereum through a dual-VM architecture, facilitating atomic execution between EVM, SVM (Solana), and the native X3VM. Sources: production/public/x3-technical.html:41, plans/COMPLETE_BLOCKCHAIN_AUDIT_REPORT.md:14
The primary purpose of the EVM contract suite is to manage Hash Time-Locked Contracts (HTLCs), interface with flashloan providers like Balancer V2 and Aave V3, and ensure state parity across disparate virtual machines during cross-chain trades. Sources: production/public/x3-technical.html:41-45, production/public/x3-validators.html:115-120
Architecture and Core Components
The EVM integration is built upon the Frontier pallet within the Substrate runtime, allowing for Ethereum-compatible execution and JSON-RPC support. Sources: plans/COMPLETE_BLOCKCHAIN_AUDIT_REPORT.md:144-149
AtlasHTLC.sol
The central component for Ethereum-based swaps is AtlasHTLC.sol. This contract implements the Hash Time-Lock mechanism required for atomic settlement. It relies on a secret $S$ and its SHA-256 hash $H$ to lock assets until a valid preimage is revealed or a timelock expires. Sources: production/public/x3-validators.html:150-155, production/public/x3-technical.html:43
Flashloan Adapters
To enable capital-efficient swaps without requiring the user to provide full principal upfront, the system utilizes flashloan adapters. On the EVM side, these adapters interface with:
- Balancer V2: Utilized for its 0% fee structure.
- Aave V3: Used as a secondary provider with a 0.05% fee.
Sources: production/public/x3-validators.html:115-120
Logic Flow for Cross-VM Coordination
The following diagram illustrates the high-level system topology where the EVM acts as one of the target chains for the X3-kernel.
The diagram shows how X3-kernel coordinates between EVM and SVM payloads to ensure atomic execution. Sources: production/public/x3-technical.html:56-72
Contract Specifications and Constraints
EVM contracts operate under specific network constraints that differ from the native X3 Chain and the SVM.
| Feature | EVM Specification | X3 Chain Comparison |
|---|---|---|
| Language | Solidity | WASM (x3-lang) |
| Finality | ~60 seconds (12 blocks) | ~200-400ms |
| Fee Model | Gas (volatile) | Weight-based |
| Timelock (T_E) | Typically now + 2 hours | N/A |
| Reentrancy | Requires nonReentrant guards | Minimal risk |
| Clock Source | block.timestamp (±15s) | Substrate Timestamp |
Sources: production/public/x3-technical.html:122-132, production/public/x3-validators.html:150-165
Cross-VM Atomic State Machine
The EVM contracts follow a deterministic four-phase state machine coordinated by the X3-kernel. Failure in any leg of the state machine triggers an abort path that prevents the reveal of the secret $S$, ensuring all assets are eventually refunded. Sources: production/public/x3-technical.html:81-92
Security and Verification
EVM contracts are subject to rigorous verification gates, including parity tests with the SVM and formal proof receipts.
Verified Claims
The EVM implementation has successfully verified several critical security claims:
- x3.contracts.evm_core: Ensuring core contracts are deployable and functional.
- x3.contracts.evm_svm_parity: Verifying that cross-VM behavior is identical for the same test vectors.
- x3.flashloan.repay_or_revert: Ensuring that if a flashloan repayment fails, the entire transaction reverts, preventing asset theft.
Sources: plans/COMPLETE_BLOCKCHAIN_AUDIT_REPORT.md:37-43, proof/features/feature_matrix.yml:634-645
Attack Mitigation
Specific mitigations are implemented within the EVM contracts to handle common vulnerabilities:
- Frontrunning: Secret $S$ remains off-chain until both flashlegs are confirmed. Private relays (like Flashbots) are used for transaction broadcasting.
- Chain Reorgs: The system requires a 12-block confirmation delay on Ethereum before considering a transaction final.
- Partial Fills: The atomic executor guarantees all legs succeed or the transaction reverts.
Sources: production/public/x3-validators.html:170-185, production/public/x3-technical.html:138-145
Implementation Standards
The project uses automated tools to maintain documentation and code quality for Solidity contracts. The docgen utility extracts NatSpec comments, function signatures, events, and errors to generate Markdown documentation. Sources: crates/x3-cli/src/commands/docgen.rs:104-140
Mandatory CI/CD Gates
All EVM contracts must pass the following checks before mainnet deployment:
cargo test -p pallet-x3-cross-vm-routertest_x3_native_evm_svm_roundtrip_preserves_supplyexternal_bridges_are_paused_at_genesischeck.
Sources: MAINNET_LAUNCH_CHECKLIST.md:46-60
Summary
EVM Smart Contracts provide the programmable entry point for Ethereum users into the X3 ecosystem. Through the use of audited HTLCs and flashloan adapters, they enable high-speed atomic swaps with the X3 Chain while maintaining strict security through confirmation delays and atomic revert logic. Their parity with SVM programs is a cornerstone of the X3 universal asset kernel. Sources: production/public/x3-technical.html:138-142, plans/COMPLETE_BLOCKCHAIN_AUDIT_REPORT.md:43