NFT Bridge
Migration strategy for non-fungible assets from WAX (AtomicAssets) to Avalanche (ERC-721/1155).
Purpose
Existing players hold NFTs on WAX (AtomicAssets standard). As the game economy migrates to Avalanche, these assets must be representable on the target chain without:
- Losing ownership
- Losing metadata (attributes, rarity, history)
- Forcing players to act within a deadline
- Creating duplicates across chains
Why this is separate 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 |
| No data loss | All attributes, rarity, and provenance must transfer |
| No duplicates | NFTs must be locked/burned on WAX when minted on Avalanche |
| Reversible during transition | Bidirectional flow until full migration is complete |
| Schema preservation | WAX template/schema structure maps to on-chain metadata |
Phased Migration Strategy
Phase 1: Metadata Snapshot
Goal: Build a complete catalog of all NFT assets on WAX.
Tasks:
- Query AtomicAssets API for all schemas and templates in the collection
- Record: template ID, schema name, immutable data, mutable data
- Snapshot current ownership (account → [asset IDs])
- Store snapshot in an off-chain database (not on-chain — too large)
AtomicAssets API
│
▼
┌──────────────────────┐
│ Metadata Snapshot │
│ │
│ template_id: 12345 │
│ schema: "monsuta" │
│ name: "Fire Drake" │
│ rarity: "legendary" │
│ attack: 85 │
│ defense: 42 │
│ owner: "player1.wax" │
└──────────────────────┘
Phase 2: Avalanche Contract Deployment
Goal: Deploy NFT contracts on Avalanche that can represent migrated assets.
Contract requirements:
- ERC-721 or ERC-1155 (depending on fungibility needs)
- Metadata storage: on-chain attributes OR tokenURI pointing to IPFS/Arweave
- Mint function restricted to bridge authority (oracle or admin)
- Template ID field preserved for provenance tracking
originChainandoriginAssetIdfields for audit trail
struct MigratedNFT {
uint256 tokenId;
uint256 waxTemplateId;
uint64 waxAssetId;
string schema;
string name;
string metadataURI; // IPFS hash of full attribute set
bool migrated; // true = has been bridged
}
Phase 3: Bridge Contract
Goal: Deploy a bridge that locks WAX NFTs and mints equivalents on Avalanche.
Player initiates NFT migration
│
▼
WAX Bridge Contract locks NFT
(transfers asset to bridge account)
│
▼
Oracle(s) detect lock event
│
▼
Oracles sign migration attestation
│
▼
Player (or relayer) calls mint()
on Avalanche NFT contract with attestation
│
▼
Avalanche NFT minted with preserved metadata
WAX NFT remains locked (not burned — reversible)
Lock vs Burn
During the transition period, WAX NFTs are locked, not burned. This allows:
- Reverse migration if the player wants to return to WAX
- Validation that the asset still exists at any time
- Final burn only executed when full migration is declared complete
Phase 4: Player Migration Portal
Goal: Provide a UI for players to migrate their NFTs.
Portal features:
- Connect WAX wallet and Avalanche wallet
- View all eligible WAX NFTs
- Select assets for migration (individual or batch)
- Preview Avalanche metadata before confirming
- Track migration status
- Reverse migration option
Phase 5: Legacy Deprecation
Goal: After sufficient migration, deprecate WAX NFT support.
Steps:
- Announce deprecation timeline (minimum 90 days notice)
- Stop minting new NFTs on WAX
- In-game systems only recognize Avalanche NFTs
- WAX bridge remains operational for claims but no new locks
- Final burn of locked WAX NFTs (optional, after extended window)
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"
}
}
Player Preservation
What Players Keep
- Full ownership of all migrated assets
- Complete attribute set (rarity, stats, element, etc.)
- Historical provenance (original WAX template/asset IDs)
- Ability to reverse migration during transition period
What Changes
- Token standard: AtomicAssets → ERC-721
- Chain: WAX → Avalanche C-Chain
- Marketplace: changes from AtomicHub to Avalanche-native markets
- Wallet: WAX Cloud Wallet → MetaMask or equivalent
Integration Guide for Other Games
To migrate NFTs from another chain using this pattern:
- Snapshot your assets — enumerate all NFTs from your source chain's API
- Design metadata mapping — map your source format to ERC-721/1155 + IPFS
- Deploy Avalanche NFT contract — include origin fields for provenance
- Deploy source chain lock contract — holds assets during transition
- Run oracle(s) — adapt the bridge oracle to detect lock events on your source chain
- Build migration portal — UI for players to connect both wallets and migrate
- Follow the 5-phase plan — snapshot → deploy → bridge → portal → deprecate
The NFT bridge pattern is chain-agnostic. Replace WAX/AtomicAssets with your source chain's NFT standard and the rest of the flow remains the same.