Skip to main content

Vault-Based NFT Bridge

A secure, non-destructive bridge architecture designed to map and migrate 100,000+ assets across asynchronous networks gracefully.

The Migration Problem​

Faded Monsuta originated on the WAX blockchain, resulting in an ecosystem containing over 100,000 player-owned NFTs. Traditional NFT bridges rely on a Mint & Burn model: burning the asset on the origin chain, and minting it on the destination chain.

For massive pre-existing ecosystems, burning is extremely dangerous:

  1. If a cross-chain transmission drops, the user's asset is permanently destroyed.
  2. Legacy assets often contain specific creation timestamps, mint numbers, or historical data that a pure burn operation irrevocably deletes.
  3. Returning an asset to the legacy chain requires re-minting a functionally new asset, severing it from its historical lineage.

The Vault Architecture​

Monsuta Core solves this via a Vault-based locking protocol. The NFT Bridge never burns an asset. Instead, it securely locks original NFTs in an escrow vault and uses a decentralized Oracle network to translate, map, and mirror those assets onto the destination settlement chain (Avalanche).

WAX (Origin)                           Avalanche (Destination)
─────────────────────────────────────────────────────────────────
1. Player deposits NFT into 
   the WAX Vault Contract.
   (Asset Locked, NOT burned)
        │
2. Oracle detects lock.
   Translates ID & signs payload.
        │
        └──────────────────────────────► 3. Player submits signature
                                            to Avalanche contract.
                                            (Minted exact mirror)

[ Return Trip ]
4. Oracle unlocks WAX vault ◄─────────── 5. Player deposits mirrored 
   and returns original NFT.                NFT into Avalanche vault.
─────────────────────────────────────────────────────────────────

Because assets are vaulted, a failure in transit never destroys player property. The original asset is always securely held and entirely recoverable.

Token ID Engineering​

Mapping assets between blockchains with different numeric limits requires strategic ID formatting. WAX AtomicAssets use sequential IDs, whereas Avalanche uses ERC-721.

Monsuta Core leverages Bitwise Token IDs to solve this elegantly:

avaxTokenId = (typeId << 128) | serial
  • Infinite Horizontals: This provides unlimited sequential serials per item type.
  • Gas-Free Lookups: The game server and frontend can mathematically extract an item's type purely through bitwise operations, bypassing the need for expensive on-chain registries or heavy mapping arrays.

Component Topology​

The NFT Bridge comprises four independent layers:

ComponentNetwork / EnvironmentPurpose
NFTBridge.solAvalanche C-ChainUUPS proxy enforcing threshold-signature mints and securely locking bridged returns.
nftbridge.cppLegacy Chain (WAX)EOSIO contract functioning as the escrow vault for origin assets.
nft-oracle-wax.jsOff-chain Node.jsWatches legacy chain locks, queries the PostgreSQL mapping DB, and signs EIP-712 payloads.
nft-oracle-avax.jsOff-chain Node.jsWatches Avalanche locks and instructs the legacy chain vault to release specific original assets.

Resiliency & Security Rules​

PropertyEnforcement Mechanism
Cryptographic RedundancyEIP-712 typed data hashing ensures payloads cannot be altered or re-used on other chains.
Threshold ConsensusThe bridge mandates independent M-of-N oracle signatures before releasing or minting an asset, eliminating single points of failure.
Atomic Replay PreventionwaxTxId nonces are strictly verified. A distinct teleport operation can only ever be claimed once.
Emergency HaltsStrict PausableUpgradeable implementation allows operators to freeze all bridge components globally in the event of an anomaly.

Infrastructure Operations​

Database configurations and tables are automatically initialized during the first execution of the Oracle watcher.

Database Schema Auto-Generation:

  • wax_template_map: Maps origin template schemas to new Avalanche bitwise definitions.
  • nft_id_counter: Ensures atomic serial incrementation to strictly prevent ID collisions across concurrent bridge streams.
  • nft_teleports: Retains signature data, providing users an infinite claim window.

Operating the Node.js oracles requires basic PM2 orchestration:

# Start dual-directional oracle watchers
pm2 start nft-oracle-wax.js --name vault-watcher-origin
pm2 start nft-oracle-avax.js --name vault-watcher-destination