Contents

mrlsd/swift-evm

---

Key Features

  • Yellow Paper Compliant: Strict adherence to Ethereum protocol specifications.
  • Zero-Copy Architecture: Optimized memory handling to minimize ARC overhead in hot execution paths.
  • Platform Agnostic: Runs natively on macOS, iOS, Linux, and WebAssembly (wasm32) and many others.
  • Uncompromising Reliability: The codebase maintains 100% unit test coverage. Every opcode, edge case, and gas calculation path is rigorously tested, ensuring production-grade stability and correctness rarely seen in early-stage implementations.
  • Deterministic Execution: 100% reproducible state transitions.
  • Modular Design: Decoupled components (Gasometer, Stack, Memory, Interpreter) allowing for custom extensions and instrumentation.

Architecture

SwiftEVM is composed of specialized modules to ensure performance and correctness:

1. PrimitiveTypes (Arithmetic Core)

A specialized math library tailored for the EVM's 256-bit word size.

  • Why not BigInt? Generic BigInt libraries introduce overhead for dynamic allocation and do not natively handle EVM-specific behaviors (e.g., specific overflow wrapping, two's complement representation for SDIV/SMOD).
  • UInt128 Support: Leverages Swift 6 native UInt128 for optimized high-precision calculations.

2. EVM (Core Execution)

The heart of the virtual machine.

  • Interpreter: Optimized opcode dispatch loop.
  • Stack: Fixed-size, high-performance LIFO structure with boundary safety checks.
  • Memory: Dynamic linear memory with gas-metered expansion logic.
  • Gasometer: Exact gas accounting for opcodes, intrinsic costs, and memory expansion.

3. Tracing

Granular execution tracing for debugging and state analysis. Supports standard JSON-RPC trace formats and custom hooks for indexers.

Implementation Status & Roadmap

The project targets the Ethereum specification upgrades listed below.

| Component | Status | Notes | | :--- | :--- | :--- | | Machine State | ✅ Complete | Stack, Memory, Context, Gas | | Opcode Logic | ✅ Complete | Arithmetic, Bitwise, Control Flow, System | | Precompiles | 🔄 In Progress | ECRecover, SHA256, RIPEMD160, Identity etc. | | Runtime | 🛠 Active Dev | Transaction context, Block environment | | zkEVM | 🔜 Planned | Guest program, Block validation & execution |

Compliance & Verification

  • ✅ Unit Testing: 100% Code Coverage enforced by CI and CodeCov.
  • 🔜 Ethereum State Tests: Planned full integration with the official Ethereum Test Suite (execution-spec-tests) to guarantee pixel-perfect consensus compatibility.

Hard Fork Support

Targeting compliance with the following upgrades:

  • ✅ Berlin
  • ✅ London
  • ✅ Shanghai
  • ✅ Cancun
  • 🔜 Prague / Osaka (Planned)

Integration

Requirements

  • Swift 6.0+ (Required for UInt128 and concurrency features).
  • OS: macOS 14+, iOS 17+, Ubuntu 22.04+, or any environment supporting Swift 6.

Swift Package Manager

Add SwiftEVM to your Package.swift dependencies:

dependencies: [
    .package(url: "https://github.com/mrLSD/swift-evm.git", from: "0.5.24")
]

Contributing

We welcome contributions from EVM experts and systems engineers. To maintain the integrity of the consensus engine, we enforce strict quality gates:

  1. 100% Test Coverage: No code merges without full unit test coverage. Edge cases must be proven.
  2. Linting: Code must pass swiftlint and be formatted via swiftformat.
  3. Performance: PRs affecting the hot loop must demonstrate no regression in benchmarks.

Development Environment


swift test

# Run tests with prettified output
swift test | xcbeautify

# Check coverage (requires llvm-cov)
./Scripts/coverage.sh

License

SwiftEVM is released under the MIT License.

Package Metadata

Repository: mrlsd/swift-evm

Default branch: main

README: README.md