Skip to content

Scala 3 Migration — Success Story

Project: Fukuii Ethereum Client
Migration Period: October 2025
Status: ✅ COMPLETE

Overview

Fukuii successfully migrated from Scala 2.13 to Scala 3.3.4 (LTS), modernizing the codebase and ensuring long-term support. This was a significant milestone that included:

  • ✅ Scala 3.3.4 (LTS) — Primary and only supported version
  • ✅ JDK 21 (LTS) — Upgraded from JDK 17
  • ✅ Apache Pekko — Migrated from Akka (Scala 3 compatible)
  • ✅ Cats Effect 3 IO — Migrated from Monix
  • ✅ Native Scala 3 derivation — Replaced Shapeless in RLP module
  • ✅ json4s 4.0.7 — Updated for Scala 3 compatibility
  • ✅ All dependencies — Updated to Scala 3 compatible versions
  • ✅ Scalanet — Vendored locally with full Scala 3 support
  • ✅ Static analysis — Toolchain updated for Scala 3

Migration Phases

Phase 0: Dependency Updates

  • Updated all critical dependencies to Scala 3 compatible versions
  • Scala 2.13.6 → 2.13.8 → 2.13.16 (for compatibility)
  • Akka 2.6.9 → Pekko 1.2.1 (Scala 3 compatible fork)
  • Cats 2.6.1 → 2.9.0
  • Cats Effect 2.5.5 → 3.5.4
  • Circe 0.13.0 → 0.14.10
  • json4s 3.6.9 → 4.0.7
  • All critical dependencies updated to Scala 3 compatible versions

Phase 1-3: Code Migration

  • Automated Scala 3 syntax migration
  • Manual fixes for complex type issues
  • RLP module: Shapeless → native Scala 3 derivation
  • Monix → Cats Effect 3 IO (~100+ files)
  • Observable → fs2.Stream conversions

Phase 4: Validation & Testing

  • All modules compile successfully
  • Test suite validation (91/96 tests passing)
  • 5 pre-existing test failures (unrelated to migration)
  • No regressions introduced

Phase 5: Compilation Error Resolution

  • Resolved 13 scalanet module errors (CE3 API issues)
  • Resolved 508 main node module errors
  • Fixed RLP type system issues
  • Fixed CE3 migration issues (Task → IO, Observable → Stream)

Phase 6: Monix to IO Migration

  • Migrated ~85 files from monix.eval.Task to cats.effect.IO
  • Migrated ~16 files from monix.reactive.Observable to fs2.Stream
  • Updated all Scheduler usage to IORuntime
  • Complete Monix removal from codebase

Key Achievements

Scala Version

  • Primary Version: Scala 3.3.4 (LTS)
  • JDK: 21 (Temurin)
  • Build: Scala 3 only (no cross-compilation needed)

Modern Dependencies

  • Effect System: Cats Effect 3.5.4
  • Actor System: Apache Pekko 1.2.1
  • Streaming: fs2 3.9.3
  • JSON: json4s 4.0.7
  • Networking: Scalanet (vendored locally)

Static Analysis

  • Scalafmt: 3.8.3 (Scala 3 support)
  • Scalafix: 0.10.4
  • Scapegoat: 3.1.4 (Scala 3 support)
  • Scoverage: 2.0.10 (Scala 3 support)

Technical Highlights

Scala 3 Features Now Available

  • Native given/using syntax for implicit parameters
  • Union types for flexible type modeling
  • Opaque types for zero-cost abstractions
  • Improved type inference
  • Native derivation (no Shapeless dependency)

Migration Approach

  1. Dependency Updates — All critical dependencies updated first
  2. Automated Syntax Migration — Using scala3-migrate plugin
  3. Manual Fixes — Complex type issues resolved manually
  4. RLP Module — Shapeless replaced with native Scala 3 derivation
  5. Effect System — Monix replaced with Cats Effect 3 IO
  6. Validation — Comprehensive test suite verification

References

For historical details, see the archived migration planning documents: - Dependency updates strategy - Cats Effect 3 migration approach - Monix to IO migration methodology - Phase validation reports

Migration Completed: October 2025
Project Status: Production-ready on Scala 3.3.4 (LTS)