NFT Migration Guide

How Faded Monsuta's 100,000+ WAX NFTs are migrating to Avalanche — the phased player migration plan. For the technical bridge implementation, see NFT Bridge →.

Migration Phases

Phase	Description
1. Metadata Snapshot	Catalog all WAX NFT templates and ownership state
2. Avalanche Contracts	Deploy NFT contracts (`MonsutaNFT.sol`) on Avalanche
3. Bridge Contract + Oracle	Vault-based bridge with oracle threshold signatures
4. Player Migration Portal	UI for players to move their WAX NFTs to Avalanche
5. Legacy Deprecation	WAX NFT support sunset with 90-day notice

Purpose

Faded Monsuta has 100,000+ NFTs on WAX (AtomicAssets standard). As the game's economy migrates to Avalanche, these assets need to be representable on the new chain without:

Losing ownership
Losing metadata (attributes, rarity, history)
Forcing players to act within a deadline
Creating duplicates across chains

Why this is different from the token bridge: Fungible tokens have a 1:1 numerical equivalence. NFTs carry metadata, schemas, templates, and individual attributes. The migration strategy must account for this complexity.

Design Constraints

Constraint	Reason
No forced deadline	Players migrate on their own schedule — nobody loses anything by waiting
No data loss	All attributes, rarity, and provenance must transfer
No duplicates	NFTs are locked (vaulted) on WAX when minted on Avalanche — not burned
Reversible during transition	Bidirectional flow until full migration is declared complete
Schema preservation	WAX template/schema structure maps to on-chain metadata

Important: The implementation uses vault-based locking, not burning. WAX NFTs are held in the bridge contract and can always be returned. See NFT Bridge → for the full technical details.

The Migration Phases

Phase 1: Metadata Snapshot

Goal: Build a complete catalog of all NFT assets on WAX.

The oracle's PostgreSQL database maintains the authoritative mapping:

WAX template_id → Avalanche type_id (stored in wax_template_map)
Atomic serial counters per type (stored in nft_id_counter)
Full ownership snapshot available via AtomicAssets API queries

AtomicAssets API
       │
       ▼
wax_template_map table
  template_id: 12345
  avax_type_id: 1
  avax_class: "Base"

No on-chain storage of the mapping — it all lives in the oracle's database and is queried at bridge time.

Phase 2: Avalanche Contract Deployment

Goal: Deploy NFT contracts on Avalanche that can represent migrated assets.

MonsutaNFT.sol is deployed and live on Fuji testnet:

ERC-721 with UUPS upgradeability
MINTER_ROLE granted to the NFT bridge contract
Token IDs encode type via bitwise scheme: avaxTokenId = (typeId << 128) | serial
Dynamic metadata via the Metadata Router on Railway

All attributes and provenance are preserved in the metadata JSON served by the router.

Phase 3: Bridge Contract + Oracle

Goal: Deploy a working bridge so WAX NFTs can be moved to Avalanche and back.

The bridge is live. See NFT Bridge → for the full technical documentation.

Player transfers NFTs to WAX bridge contract
       │
       ▼
NFTs vault-locked on WAX (NOT burned — always recoverable)
       │
       ▼
nft-oracle-wax.js detects event, translates IDs, signs EIP-712 payload
       │
       ▼
Player calls NFTBridge.claim() on Avalanche
       │
       ▼
MonsutaNFT.mintBatch() — Avalanche NFTs issued with full metadata

Vault-based locking means:

Reverse migration is always possible during the transition period
NFTs can be validated against the WAX vault at any time
Nothing is permanently destroyed until Phase 5 is explicitly executed

Phase 4: Player Migration Portal

Goal: A UI that lets players move their WAX NFTs to Avalanche without touching a command line.

Portal features:

Connect both WAX wallet and Avalanche wallet
View all eligible WAX NFTs with their metadata
Select assets for migration (individual or batch)
Preview how the NFT will appear on Avalanche before confirming
Track pending and completed migration status
Initiate reverse migration (Avalanche → WAX) if needed

Phase 5: Legacy Deprecation

Goal: After the migration window, formally sunset WAX NFT support.

Steps (minimum 90-day notice period required):

Publish deprecation timeline publicly
Stop minting new NFTs on WAX
In-game systems exclusively recognize Avalanche NFTs
WAX bridge remains operational for late migrators
Optional: final release of WAX vault (locked assets returned to original holders)

No forced burns. Players who haven't migrated by the end of the window will have their WAX NFTs returned, not destroyed.

Metadata Mapping

WAX AtomicAssets → Avalanche ERC-721

WAX Field	Avalanche Equivalent	Notes
`template_id`	`waxTemplateId`	Stored on-chain for provenance
`asset_id`	`waxAssetId`	Unique WAX identifier
`schema_name`	`schema` (string)	Preserved in metadata
`immutable_data`	Metadata URI (IPFS)	All attributes in JSON
`mutable_data`	Metadata URI (updatable)	Points to current state
`collection_name`	Contract-level constant	One contract per collection
`owner`	NFT owner address	Mapped via wallet link

Metadata JSON (on IPFS)

{
  "name": "Fire Drake",
  "description": "Legendary Monsuta from Season 1",
  "image": "ipfs://Qm.../fire_drake.png",
  "attributes": [
    { "trait_type": "Rarity", "value": "Legendary" },
    { "trait_type": "Attack", "value": 85 },
    { "trait_type": "Defense", "value": 42 },
    { "trait_type": "Element", "value": "Fire" },
    { "trait_type": "Origin Chain", "value": "WAX" },
    { "trait_type": "WAX Template ID", "value": "12345" },
    { "trait_type": "WAX Asset ID", "value": "1099512345678" }
  ],
  "provenance": {
    "originChain": "WAX",
    "originContract": "atomicassets",
    "originCollection": "fadedmonsuta",
    "migratedAt": "2026-03-15T00:00:00Z"
  }
}

What Players Keep vs What Changes

What Players Keep

Full ownership of all migrated assets — same NFTs, new chain
Complete attribute set (rarity, stats, element, type)
Historical provenance — WAX template and asset IDs are preserved in metadata
The ability to bridge back to WAX during the transition period

What Changes

Before (WAX)	After (Avalanche)
AtomicAssets standard	ERC-721
WAX blockchain	Avalanche C-Chain
AtomicHub marketplace	Avalanche-native markets
WAX Cloud Wallet / Anchor	MetaMask or equivalent

Players do not lose any asset value or history. The migration changes the technical representation, not the ownership.

Metadata Mapping

WAX AtomicAssets → Avalanche ERC-721

WAX Field	Avalanche Equivalent	Notes
`template_id`	`typeId` (in token ID encoding)	Stored in oracle DB, encoded in token ID
`asset_id`	`serial` (in token ID encoding)	Unique per-type serial counter
`schema_name`	Metadata JSON `schema` field	Preserved via metadata router
`immutable_data`	Metadata JSON attributes	Served dynamically by metadata router
`collection_name`	Contract-level constant	One `MonsutaNFT` contract for the collection
`owner`	ERC-721 `ownerOf()`	Mapped via wallet link at bridge time

Metadata JSON (served by metadata router)

{
  "name": "Fire Drake",
  "description": "Legendary Monsuta from the original WAX collection",
  "image": "ipfs://Qm.../fire_drake.png",
  "attributes": [
    { "trait_type": "Rarity", "value": "Legendary" },
    { "trait_type": "Attack", "value": 85 },
    { "trait_type": "Defense", "value": 42 },
    { "trait_type": "Element", "value": "Fire" },
    { "trait_type": "Origin Chain", "value": "WAX" },
    { "trait_type": "WAX Template ID", "value": "12345" }
  ],
  "provenance": {
    "originChain": "WAX",
    "originContract": "atomicassets",
    "originCollection": "fadedmonsuta"
  }
}

Adapting for Other Games

To run this migration pattern for a different game migrating from WAX (or any chain):

Snapshot your assets — enumerate all NFTs from your source chain's API
Design the metadata mapping — map source format to ERC-721 + IPFS
Deploy your NFT contract — include origin fields for provenance tracking
Deploy source chain bridge contract — vault-based locking, not burning
Configure the oracle database — populate wax_template_map with your template IDs
Run oracle processes — adapt nft-oracle-wax.js for your source chain's events
Build the migration portal — UI for players to connect both wallets and migrate
Follow the 5-phase plan — snapshot → deploy → bridge → portal → deprecate

The pattern is chain-agnostic. Replace WAX/AtomicAssets with your source chain's NFT standard and the architecture remains the same.

Migration Phases​

Purpose​

Design Constraints​

The Migration Phases​

Phase 1: Metadata Snapshot​

Phase 2: Avalanche Contract Deployment​

Phase 3: Bridge Contract + Oracle​

Phase 4: Player Migration Portal​

Phase 5: Legacy Deprecation​

Metadata Mapping​

WAX AtomicAssets → Avalanche ERC-721​

Metadata JSON (on IPFS)​

What Players Keep vs What Changes​

What Players Keep​

What Changes​

Metadata Mapping​

WAX AtomicAssets → Avalanche ERC-721​

Metadata JSON (served by metadata router)​

Adapting for Other Games​

Migration Phases

Purpose

Design Constraints

The Migration Phases

Phase 1: Metadata Snapshot

Phase 2: Avalanche Contract Deployment

Phase 3: Bridge Contract + Oracle

Phase 4: Player Migration Portal

Phase 5: Legacy Deprecation

Metadata Mapping

WAX AtomicAssets → Avalanche ERC-721

Metadata JSON (on IPFS)

What Players Keep vs What Changes

What Players Keep

What Changes

Metadata Mapping

WAX AtomicAssets → Avalanche ERC-721

Metadata JSON (served by metadata router)

Adapting for Other Games