Application State Migration | Proposal by WakeUp Labs
Contact details
Email: aztec@wakeuplabs.io | Twitter: x.com/wakeuplabs | Github: github.com/wakeuplabs-io
Summary
This project proposes to research, design, and prototype generalizable application-level state migration patterns for the Aztec Network during Alpha roll-up upgrades. As Aztec upgrades are expected to frequently start from a clean state, applications with persistent private or public state require explicit, well-designed migration mechanisms. Our goal is to explore and implement practical migration approaches that balance trust minimization, user experience, and privacy, while remaining broadly applicable across many classes of Aztec applications.
We will prototype and document a decentralized, fully on-chain approach using the existing L2–L1 messaging infrastructure and define clear guidelines for its use. The work will deliver a working prototype demonstrating migration between two local Aztec rollups, supported by design documentation, threat models, and UX flows. All artifacts will be open-source and structured as a reusable pattern rather than an app-specific solution. The outcome is intended to serve as a reference for application developers navigating Alpha-era upgrades.
Start Date & End Date
Start: January 27, 2026 Immediately upon grant approval
End: February 27, 2026
About Us: Team Background and Experience
WakeUp Labs is a software Engineering studio focused on decentralized technology, zk tooling, and blockchain. Our work is rooted in open-source development and we bring deep technical expertise across chains and zero-knowledge technologies. Our team of experienced engineers consistently delivers high-quality tooling and research-grade implementations for the Web3 space.
Ecosystem alignment
Throughout our journey, we have actively collaborated with leading DAOs and projects, aligning closely with the goals of cutting-edge teams likeAztec. Some of our most impactful contributions include:
- Aztec Private Markets - Cross-chain private prediction market PoC [repo]
- Enigma – A private ERC-20 standard built with Noir, deployed on Starknet, enabling shielded transfers. [demo] and [repo]
- Noir Stylus Verifier - A Stylus-compatible UltraHonk verifier that bridges Noir’s zero-knowledge capabilities with Arbitrum Stylus [repo]
- Aztec Sequencer Node – We are running infrastructure contributing to the Aztec blockchain
We actively share knowledge and code with the broader community and remain deeply engaged with the evolving Web3 landscape.
Best practices
At WakeUp Labs, we follow rigorous engineering processes, prioritizing secure design, detailed documentation, and maintainable code. All our open-source contributions reflect our commitment to quality and transparency. As part of this we’ve committed to external audits for the project.
Selected Migration Approach & Methodology
Our solution follows Category B: purely on-chain, self-migration, leveraging Aztec’s Inbox and Outbox mechanisms. The design deliberately minimizes centralized components and aligns closely with Aztec’s privacy-first, trust-minimized philosophy.
We introduce a simple application level emergency function that, once migration is decided, allows application developers to freeze state transitions and set a target for the new rollup. After this function is invoked, the application state is considered final and eligible for migration. No complex coordination, governance processes, or off-chain dependencies are introduced at this layer.
The core of the work focuses on defining a generalizable on-chain migration pattern that supports both public and private state. This is complemented by developer tooling and documentation to make the approach practical and reusable across applications.
Because the time window between a migration decision and the shutdown of the old roll-up may be constrained, we propose two alternative migration patterns that can be purely on-chain and would demand little to no effort from a developer and user standpoint, each with different tradeoffs in UX, cost, and guarantees to be analyzed by each project. In short, both approaches leverage the Outbox of the source rollup and the Inbox of the destination rollup, with an L1 contract serving as an intermediary to forward messages and ensure safe migration of storage snapshots between them. Similar to how the token portal operates, we’re utilizing the Inbox/Outbox system to enable fully on-chain transfer of private data—sending it privately from one rollup and reclaiming it privately on another, while using an L1 relayer to minimize transaction overhead for the user. The difference between these remains mostly at when these snapshots are done.
- Continuous snapshotting, where state commitments are updated on every transaction, allowing users to be migration ready at any time. (For the user meaning just one private transaction for the user on the new rollup to reclaim state)
- Single snapshot at migration time, where users must actively migrate their state before sequencers go down and portals stop working. (For the user meaning 2 transactions at migration window)
These options allow application developers to choose the most appropriate point in the design space depending on their priorities.
Below, we outline the user flow, pros and cons, and trust assumptions for each pattern.
Pattern 1: Continuous Snapshotting (Per-Transaction)
In this approach, L2 contracts continuously post state updates to L1 as messages, ensuring that users are always migration-ready. When migration is triggered, application developers lock the state, configure the target rollup in the L1 contract and batch-forward the committed state snapshots, allowing users to later reclaim their state with a single L2 transaction. Each snapshot will have to overwrite the previous one such that the new L2 only gets the latest state.
The main advantages of this pattern are a significantly improved user experience: users only need to submit one transaction on the destination rollup, with no migration window or activity requirements. It’s also the cleanest regarding migration status, just after one transaction we can totally forget about previous rollup. On the communication aspect we can notice it’s still needed and encouraged but not as urgent as it could be, users can claim back their state on their next session.
The main drawbacks are higher ongoing gas costs due to continuous state “backups” to L1, as well as some development and management overhead.
Regarding Trust Assumptions, this approach is largely trustless, but some considerations remain. In particular, it relies on the correct pausing of the L2 contract state and on the proper deployment and configuration of the L1 contracts. Additionally, users may still require access to a fully functioning node in order to read and verify their previous rollup state.
The following image shows a tentative reference sequence diagram illustrating the proposed migration flow under the described assumptions.
Pattern 2: Single Snapshot at Migration Time (exploratory - not best UX)
In this approach, once migration is approved, application administrators configure the L1 migration contract to point to the new rollup, freeze the state in the L2 contract, and require users to individually bridge a snapshot of both their private and public state. Users must complete the migration as quickly as possible, since a functioning sequencer is still required to exit the original rollup.
The main advantages of this pattern are the minimal ongoing gas costs, there is only a one-time cost at migration, and its simplicity of implementation, as it requires only a single migration function per contract.
The primary drawbacks are related to timing. First, requiring users to come online to migrate, under the risk of permanently losing state (at least without the escape hatch), is a poor user experience. Additionally, users must execute at least two transactions: one on the source rollup to initiate the migration and another on the destination rollup to reclaim their state. This may also involve waiting for messages to be relayed through L1, introducing additional latency.
Regarding Trust Assumptions, just like pattern 1, this approach is largely trustless, but some considerations remain. In particular, it relies on the correct pausing of the L2 contract state and on the proper deployment and configuration of the L1 contracts. Additionally, users may still require access to a fully functioning node in order to read and verify their previous rollup state.
Due to these UX limitations, this approach could be generally undesirable, taking into account the Reasonable UX requirement of the RFGP. However, because it shares many components with the alternative design, we will focus primarily on Pattern 1 while documenting this approach as a secondary option for teams that are willing to accept the associated trade-offs.
The following image shows a tentative reference sequence diagram illustrating the proposed migration flow under the described assumptions.
Note: During the Ecosystem Call earlier this week, the possibility of extending the migration window from 7 to 30 days was mentioned. This would further reduce the risk of users failing to complete the migration in time and could be particularly relevant for certain applications. Even more with the potential Escape Hatch that was mentioned as well.
Generalization Across Multiple Applications
Our L1 contracts and SDKs will be fully application-agnostic. They operate purely with the messaging portals. The L1 contracts will be splitted and structured in such a way that they become immediately responsive to the new portal incoming messages for withdrawals by leveraging the Aztec Registry while maintaining support for a time window to support potential previous pending messages.
While we will provide guidance on recommended migration hooks, data structures, and patterns, developers retain full flexibility to adapt these mechanisms to their application’s needs—whether migrating balances, NFTs, identities, or other user-owned state.
The goal is to provide reusable primitives and patterns, not a prescriptive framework, enabling broad adoption across the Aztec ecosystem. In both cases we’ll suggest different strategies app developers can apply to further improve UX with centralized components if this is an option they wish to pursue.
Milestones and Timeline
This structure emphasizes early validation of the core migration mechanisms, followed by usability improvements and ecosystem-facing documentation, aligning closely with the goals of the State Migration RFPG.
Milestone 1 (Weeks 1–3): Working On-Chain Migration Prototype
During this phase, we will focus on delivering a functional on-chain migration prototype. We will first set up a testing environment that accurately represents the target migration scenarios. We will then implement the L1 contracts and the required L2 migration functions. Example implementations will be provided for the migration patterns.
Milestone 2 (Week 4): SDK Wrapping, UX Improvements and edge cases exploration
In the second milestone, we will package the core migration logic into developer-friendly libraries to further simplify the implementation of similar systems. We will also explore UX improvements, such as application-level sponsorship of L1 transactions and other mechanisms to reduce user friction, while keeping trust assumptions explicit. Lastly we’ll dive deep into the system looking for edge cases that may break the system.
Milestone 3 (Week 5): Documentation and Demonstration
To conclude the project, we will document both migration patterns in detail and provide example projects with clear instructions for setup and execution. We will also include demo videos showcasing the end-to-end migration process to serve as a practical reference for application developers.
Potential future milestones:
Milestone 4 (Week 6 stretch): Gas optimizations
Every migration involves storage writes, making it a gas-intensive operation. At this stage, we aim to minimize all non-essential gas consumption as much as possible.
Milestone 5 (Week 7 stretch): Explore alternatives for a lack of sequencer
In this stretch milestone we will analyze and simulate cases where the original rollup no longer has a functioning sequencer at the time migration is required. This work will examine what recovery paths remain available, which guarantees can still be upheld, and where limitations arise when users can no longer actively exit the old rollup. The goal is to clearly characterize what can and cannot be done in these degraded conditions, document the necessary assumptions, and provide concrete guidance to application developers on how to design migration-ready systems that remain as robust as possible even in the absence of a working sequencer.
Timeline and Deliverables
Right here we detail our plan to achieve the 3 phases in the stipulated time.
| Milestones | Description |
|---|---|
| 1 (week 1-3) | Goal: Build a working, fully on-chain application state migration prototype. Implement a minimal emergency stop function to freeze application state on the old roll-up, followed by on-chain migration of both public and private state using Inbox and Outbox messaging. Deliverable: End-to-end working migration example on a local network, including emergency freeze mechanism, L1 contracts, and tests demonstrating public and private state migration between two roll-ups. |
| 2 (week 4) | Goal: Reduce developer and user friction by packaging the migration logic into reusable libraries and exploring UX optimizations and edge cases. Deliverable: Developer-facing SDK packages (Noir and TypeScript), reusable migration utilities, and documented UX improvement and edge cases. |
| 3 (week 5) | Goal: Package the work as a clear, reusable reference for the ecosystem. Add missing tests, fixes and clarifications. Deliverable: Comprehensive documentation of both migration patterns, example projects with setup instructions, and demo videos showcasing end-to-end migration flows. |
Grant Amount Requested
USD 23,000
Grant Rationale
To deliver a robust, production-relevant reference for application state migration on Aztec within a constrained timeline, we propose a lean, highly specialized team. This structure allows us to validate complex on-chain migration mechanisms early, while concentrating the majority of engineering effort on privacy-preserving state handling, cross-rollup messaging, and developer usability.
The proposed team composition is intentionally minimal, ensuring efficient coordination and rapid iteration while still covering the critical areas of protocol design, private-state engineering, testing, and ecosystem-facing documentation.
Team Composition
- One part time Team Lead for ~5 weeks to oversee the technical architecture, unblock specific hurdles, and ensure all milestones align with the State Migration request.
- One full time Senior Privacy Engineer for ~4 weeks to architect the contracts that manage state migrations.
- One part time Senior Privacy Engineer for ~2.5 weeks to help setup the testing structure, build the examples and review decisions.
- One Content & Documentation Lead for ~1 weeks to produce clear documentation and video content.