Documentation
Public docs for project teams and token holders
Use the audience guides if you want the shortest path, or open the deeper reference pages for fees, how migration works, security, FAQ, and glossary.
How Migration Works
How migration works
Learn how a migration moves from setup to holder participation, then through liquidation, settlement, lockups, and finalization.
Lifecycle at a glance
w3Swap uses explicit project states so each phase is clear and easy to track.
- 1Created: project configuration has been initialized and the protocol knows the token pair, timing, and rules.
- 2Funded: the project has received the funds needed for the migration path.
- 3Active: holders can migrate during the live window.
- 4Ended: the holder window is over and the project can proceed with liquidation and settlement.
- 5Migrated, Liquidating, LiquidationComplete: intermediate states track post-window processing of old-token value.
- 6Finalized: settlement is complete and the LP lock timer has started.
Atomic holder migration
The migration is designed so holders do not have to send tokens away and wait for a manual distribution later.
- A holder signs the migration from their own wallet.
- The program checks whether the wallet is eligible and what ratio applies.
- Old tokens move into the project's old-token vault.
- New tokens are distributed according to the active ratio logic.
- The holder does not wait for a later manual spreadsheet payout to receive the new tokens.
Ratios and eligibility
w3Swap supports both a standard ratio and an optional per-wallet override path.
Base ratio
The project can set a global exchange ratio, such as 1:1 or any other published numerator and denominator.
Special ratios
If enabled, the project publishes a Merkle root for special per-wallet ratios. The migrating wallet must provide the matching proof for that ratio.
Allowlist
If enabled, the project publishes a separate Merkle root that defines which wallets may migrate at all.
Artifact URIs
The protocol stores artifact URIs for allowlist and special-ratio data so the project can publish the supporting dataset behind those Merkle roots.
Settlement, liquidation, and LP funding
The post-window flow is what turns a migration into a liquidity-aware relaunch instead of just a token swap.
- After the migration window ends, the project moves the on-chain state forward and processes collected old tokens.
- Old tokens can be liquidated through an allowlisted CPI backend into WSOL or SOL, depending on the path used.
- The protocol tracks liquidation proceeds and enforces a minimum reinvestment threshold back into LP. At least 25% of liquidation proceeds must be added back into LP.
- Completing settlement records the event on chain and starts the LP lock timer.
Lockups, vaults, and finalization
Settlement is not the last step.
- Once settlement completes, the project enters a lockup period for the LP position.
- The minimum LP lock period is 30 days.
- After lockup ends, the project can reclaim remaining balances and finalize transfers according to the protocol's normal finalize-and-close flow.
- The project record itself can remain on chain as a discoverable record even after subordinate vaults are closed.
Why CPI allowlists matter
The protocol does not let arbitrary external programs into settlement and liquidity flows.
w3Swap stores an allowlist of swap or liquidity-related external programs in platform configuration. Only approved program IDs can be used as CPI targets for old-token liquidation and managed liquidity actions. This reduces the surface area compared with a design that lets any program be invoked during settlement.