L1 Migration Plan (Redux - June 2025)

[0xmovses]

Movement Labs is migrating from its current sidechain implementation to a fully-fledged L1 using our Aptos fork. This issue tracks the complete migration plan, reflecting recent architectural decisions and test strategies discussed during the June 25 meeting and recent Slack threads.

We will be using commit hash movementlabsxyz/aptos-core 94542b6de1a2c258b363a65ef1a7ceb615493c87 Which is our last sync with the upstream and contains latest release of all the binaries.

Note that all development for the migration is happening on this feature branch https://github.com/movementlabsxyz/aptos-core/tree/l1-migration

Summary

This migration will be accomplished in coordinated phases, each producing clear validation artifacts. The high-level deliverables include:

• ✅ A replaced and verified mainnet DB compatible with the latest Aptos binary
• ✅ A finalized framework upgrade enabling full governance
• ✅ Ecosystem compatibility (explorer, SDKs, indexer, etc.)
• ✅ Switch to a running L1 validator and validator full node setup
• ✅ Support for decentralized validator set via governance
• ✅ Deployment of validator incentives (reward model)

Primary Workstreams and DRIs

Task	DRIs
DB Replacement	@areshand @sebtomba
Framework Upgrade	@0xmovses @andygolay
E2E Testing	@sebtomba @areshand
SRE & DevOps	@radupopa369 @nicholasflintwillow
Verification Tooling	@sebtomba @0xmovses
Ecosystem Migration & Indexer	@andygolay @Rahat-ch

---

Phase 1 – State & Framework Migration

A. DB Replacement

We now leverage Aptos’ native logic for backward-compatible state DB upgrades. Our task is to:

• Define some E2E verification criteria (balance checks, smart contract state, etc.)
• Compare RocksDB snapshots using tooling already developed (e.g. movement-migration)
• Validate deterministic ledger info and state root (jellyfish Merkle tree)

Plan:

1. Define Aptos target version / commit. (done)
2. Start a Movement node, generate TX load, then replace the DB by migrating it via Aptos node.
3. Optional: try this on devnet DB before mainnet backup.
4. Validate state equivalence using:
   • Byte-by-byte RocksDB comparators
   • Sampled REST API assertions

Outcome: A reproducible, DB ready for validation and testing.

B. Framework Migration

The necessary Framework upgrades are split into two transactions:

1. Pre-Governed Upgrade

• Remove deprecated bridge/native features (return null)
• Enable or disable needed feature flags

2. Post-Governed Upgrade

• Destroy core_resources signer
• Enable full governance via aptos_governance
• Upgrade the Framework via governance proposals to the latest framework version.

All framework upgrades are triggered by transaction(s). The consensus is:

• Both transactions will be ran on the new Aptos L1-Node after DB Replacement

---

Phase 2 – Scripting

Scripting scope Scope

1. Shutdown Network

• CLI wrapper or script:
  2. Replace DB (migration step)
  3. Run all Framework Upgrade TXs
• 4. Validate:
  • Account balances remain intact
  • Ledger info root matches expectations
  • Smart contracts function as expected

---

Network Mirror Testing

Migration switch should be simulated on the following mirrors:

• Testnet Mirror
• Mainnet mirror

Then executed live on:

• Testnet
• Mainnet

Execution Plan:

1. Stop public RPC + DA Sequencer
2. Load DB into Aptos-core node
3. DB verification
4. Start validator + fullnode (centralized)
5. Start new indexer (index only post-switch TXs)
6. Upgrade Framework

---

🌐 Phase 4 – Ecosystem & Indexer

• Migrate and test indexer v2 (new processor)
• Confirm compatibility with:
  • Explorer
  • Partner apps using public/private RPC
• Optional updates to UI if schema has changed
• Let indexer run until final switch

---

Phase 5 – Governance & Decentralization

• Deploy and validate L1 validator + validator fullnode setup
• Submit onchain governance TXs to incrementally add more validators
• Finalize reward model and incentive structure (?)

---

🧾 Migration Outputs

Output	Description
✅ Migrated and validated mainnet DB	RocksDB compatible with Aptos-core
✅ Upgraded Aptos framework	All features activated, governance enabled
✅ Verified ecosystem	Explorer, Indexer, SDKs
✅ Governance onboarding path	Validators added via proposals
✅ Centralized to decentralized test coverage	Simulate validator set expansion
✅ Validator reward model	Tied to phase 5

---

🔗 Linked Issues

Sprint VI

• Build DB switch mechanism #179
• Verification of DB Integrity Post-Migration to Latest Aptos Core #181
• Migrate The Indexer movement#1258
• Deprecate Governed Gas Pool for transaction_fee::collect_fee #180
• Port In Framework Upgrades #187
• Ecosystem Compatibility & Migration Validation for Aptos Core Upgrade #183

Sprint VII

• Start a single node network #188

---

📌 Notes

• Reward model is still pending — needs planning and issue creation.
• Migration steps assume final DB "replacement", not in-place mutation.
• Downtime will depend on DB replacement speed; minimized if switch is optimized.

cc @l-monninger @sebtomba @andygolay @radupopa369 @nicholasflintwillow @Primata @musitdev @areshand @0xIcarus @sausagee @apenzk

[0xmovses]

From @musitdev once we upgrade framework after replacing DB, this will change the state. So must we run all the tests to verify the integrity of the DB prior to upgrading the framework?

[areshand]

We need to finalize the token economics before launching the L1. Currently, new tokens are minted each epoch to reward node operators and stakers. We should thoroughly review the Aptos binary and framework to either remove this minting logic or implement a mechanism to burn the newly minted tokens post-launch to prevent unintended inflation.