Migration guides
These guides cover changes to your application when upgrading ensforge. For the complete release history, see the changelogs. This section is about package upgrades; moving an ENS name from V1 to V2 is covered by the name migration actions.
Choose your upgrade
| Target | What to review |
|---|---|
| 0.6 | Effect 4 stable and the October Sepolia deployment |
| 0.5 | Stateless HCA sessions, resolver permissions, and replacement Sepolia accounts |
| 0.4 | Custom deployments, HCA providers, and resumable workflow storage |
| 0.3 | Indexer discovery and Wagmi compatibility |
| 0.2 | Grouped type imports, optional Wagmi entrypoints, and deployed contract interfaces |
| 0.1.1 | React's Atom options, result state, and callback names |
Version 0.1.0 is the initial release. Version 0.3.1 updates repository metadata and provenance; it requires no application changes. The 0.0.0 packages were bootstrap publications, not a supported application baseline. HCA first shipped as part of the aligned 0.4.0 release.
Upgrade packages together
Keep the ensforge packages installed by your application on the same release. The current published release is 0.6.0. For an SDK application:
Also update @ensforge/react, @ensforge/contracts, and @ensforge/hca to 0.6.0 if you install them
directly. You do not need to add packages your application does not use. See
HCA installation for provider-specific dependencies.
Skipping releases
Read the intervening guides in version order, but install the target version once. For example, moving from 0.3 to 0.6 requires reviewing the 0.4, 0.5, and 0.6 guides. You do not need to deploy accounts on each intermediate Sepolia snapshot: create fixtures and accounts only on your target deployment.
Historical guides describe the change introduced in that release. Linked API references and provider guides describe the current version. In particular, use Effect 4 stable for 0.6; older releases used release-candidate dependencies.
Before changing deployments, reconcile submitted transactions using their original chain and contract addresses. Preserve old workflow records for recovery, and start new operations with a separate deployment configuration. Deleting a record does not cancel a transaction or revoke a session.