Skip to main content

Migration Guide

How to migrate an existing game from a legacy chain to Avalanche using Monsuta Core.

Why Migrate?​

Migration is necessary when a game's token or NFT ecosystem exists on a chain that does not meet the project's needs for:

  • Transaction cost — gas fees too high for frequent reward distribution
  • Ecosystem tooling — better DeFi, marketplace, or developer tooling on target chain
  • Performance — faster finality for settlement transactions
  • Consolidation — unifying assets currently spread across multiple chains

Monsuta Core's first migration path is WAX → Avalanche C-Chain.

Critical rule: Migration must preserve player assets. No player should lose value or history because of a chain change.

Migration Phases​

Phase 1           Phase 2           Phase 3           Phase 4           Phase 5
──────────────    ──────────────    ──────────────    ──────────────    ──────────────
Legacy asset      Token bridge      Competitive       New assets        Full economic
inventory         goes live         rewards on AVAX   minted on AVAX    migration
                                                                        complete
│                 │                 │                 │                 │
▼                 ▼                 ▼                 ▼                 ▼
Catalog all       Players can       Tournament        Crafted items     Legacy chain
existing tokens   move THC from     prizes paid       and achievements  enters
and NFTs on WAX   WAX to AVAX       in AVAX/USDC      created on AVAX   maintenance
                  and back                                               mode

Phase 1 — Legacy Asset Inventory​

Goal: Catalog everything that exists on the legacy chain.

Tasks:

  • Enumerate all token balances (THC on WAX)
  • Catalog all NFT collections (AtomicAssets schemas, templates)
  • Record player ownership state
  • Document any staked or locked assets
  • Snapshot the total supply

Phase 2 — Token Bridge​

Goal: Enable bidirectional token movement between WAX and Avalanche.

This phase uses the existing bridge implementation (see Token Bridge Module).

Tasks:

  • Deploy FadedMonsutaTHC ERC-20 contract on Avalanche C-Chain
  • Deploy teleporteos contract on WAX
  • Register oracle(s) on both contracts
  • Verify bidirectional flow: WAX → AVAX and AVAX → WAX
  • Set production oracle threshold (≥ 3)

Phase 3 — Competitive Rewards on Avalanche​

Goal: Begin settling competitive rewards on Avalanche.

Tasks:

  • Deploy Prize Pool Contract on Avalanche
  • Connect game server to Avalanche settlement
  • First tournaments pay out in AVAX/USDC
  • THC rewards also claimable on Avalanche

Phase 4 — New Assets on Avalanche​

Goal: New items, achievements, and crafted NFTs are created natively on Avalanche.

Tasks:

  • Deploy Achievement/Identity contracts on Avalanche
  • Deploy Crafting contracts on Avalanche
  • New NFTs minted on Avalanche only
  • Legacy NFTs still valid on WAX (phase 5 handles migration)

Phase 5 — Full Economic Migration​

Goal: All primary economic activity occurs on Avalanche. Legacy chain enters maintenance.

Tasks:

  • NFT migration path for existing WAX NFTs (see NFT Bridge Module)
  • WAX contracts remain operational but deprecated
  • All new content exclusively on Avalanche
  • Communication to players: timelines, FAQs, support

Migration Principles​

  1. Voluntary — Players choose when to migrate. Forced migration destroys trust.
  2. Preserving — All historical value (tokens, NFTs, achievements) must be representable on the target chain.
  3. Bidirectional — During transition, tokens must flow in both directions. One-way bridges trap users.
  4. Gradual — Each phase is deployed and validated independently. No big bang.
  5. Transparent — Publish migration timelines, bridge addresses, and oracle identities.

For Other Projects​

If your game exists on Chain A and you want to migrate to Chain B using Monsuta Core:

  1. Adapt the bridge contracts — Replace WAX-specific logic (EOSIO tables, Hyperion) with your source chain's equivalents
  2. Deploy target-chain contracts — Use or fork FadedMonsutaTHC.sol for your token
  3. Run oracles — Deploy oracle instances that listen to your source chain and sign attestations
  4. Follow the 5-phase plan — Same structure applies regardless of chain pair
  5. NFT migration — Use the phased approach in NFT Bridge to handle non-fungible assets

The bridge architecture is chain-agnostic at the protocol level. The oracle listens for events on the source chain and signs data for the target chain. The target contract verifies signatures and acts.