Skip to main content

FAQ

Frequently asked questions about Monsuta Core and Faded Monsuta.

General​

What is Monsuta Core?​

The on-chain economic layer for competitive games. It handles trustless settlement — prize pools, token bridging, NFT bridging, crafting, achievement attestations, and staking — while gameplay runs off-chain on a traditional server-authoritative game server.

Is Monsuta Core a blockchain?​

No. It is a set of smart contracts deployed on Avalanche C-Chain (and corresponding contracts on WAX). It does not operate its own chain.

Can I use this without Faded Monsuta?​

In principle, yes. The contracts are token-agnostic and the architecture applies to any server-authoritative multiplayer game. However, the current tooling and oracle infrastructure is built specifically for Faded Monsuta. Generalizing it to other games is planned post-MVP work.

Architecture​

Why not put everything on-chain?​

Real-time multiplayer produces thousands of events per second. Putting every action on-chain means wallet popups before every move, gas fees per action, and 2–3 second confirmation latency mid-match. Players quit. The only events that benefit from on-chain settlement are economic outcomes — payouts, crafted items, token movements.

Why Avalanche?​

Fast finality (~2 seconds), low gas fees, full EVM compatibility, and existing ecosystem tooling (Snowtrace, DeFi infrastructure, wallets). The contracts are standard Solidity — they could run on any EVM chain with a config change.

Do players need a wallet to play?​

No. Players authenticate with standard login (username, email, or social). A wallet is only needed when:

  • Claiming a prize from a pool
  • Bridging tokens or NFTs between WAX and Avalanche
  • Crafting an on-chain item
  • Staking NFTs

What happens if the game server goes down?​

  • Gameplay stops (same as any online multiplayer game)
  • On-chain assets — tokens, NFTs, staked positions — remain fully accessible
  • Prize claims already submitted to chain can still be processed
  • Rewards not yet submitted to chain are held in the server database only

What's the trust model?​

Players trust the game server for gameplay correctness — the same trust they place in any online game's server. They do not need to trust the game server for fund custody. Prize pools, bridged tokens, and crafted NFTs are held and governed by smart contracts that the developer cannot access unilaterally.

Prize Pools​

Who holds the prize funds?​

The PrizePool smart contract. Not the game developer, not any individual. Players and sponsors deposit directly into the contract.

Can the developer steal the prize pool?​

No. There is no admin withdrawal function for prize funds in PrizePool.sol. The only ways money leaves the contract are:

  • claim() — called by a verified winner listed in the submitted results
  • refund() — called by a depositor if the pool is cancelled
  • sweepUnclaimed() — called by the owner after the 30-day claim deadline expires, routing remaining funds to treasury (not to an arbitrary address)

What if the tournament gets cancelled?​

If the owner or server calls cancel(), the pool enters Cancelled state. Every depositor (players who paid entry fees, sponsors) can call refund() to recover their exact deposit.

What happens to unclaimed prizes?​

After a configurable 30-day claim window expires, the pool owner can call sweepUnclaimed(). Remaining funds go to the treasury address. This prevents funds from being permanently locked if winners don't claim.

Can one pool support both AVAX and ERC-20 prizes?​

No — each pool is initialized with a single settlement token (address(0) for native AVAX, or any ERC-20 address). Deploy separate pools for different currencies.

Token Bridge​

How does WAX → Avalanche bridging work?​

  1. Player calls teleport() on the WAX bridge contract (teleporteos)
  2. Oracle detects the event and signs the packed teleport data with its ETH key
  3. Signature is stored on the WAX chain
  4. Player (or a relayer) calls claim(sigData, signatures[]) on Avalanche
  5. Contract verifies signatures, checks replay protection, and mints THC to the player's address

How long does token bridging take?​

Typically 1–5 minutes. Claims expire after 30 days from the original teleport timestamp.

Is the token bridge bidirectional?​

Yes. WAX → Avalanche mints THC on Avalanche. Avalanche → WAX burns THC on Avalanche and releases the equivalent on WAX.

What is the minimum bridge amount?​

100 THC (configured in the WAX contract at 4 decimal precision).

NFT Bridge​

How is the NFT bridge different from the token bridge?​

The token bridge moves fungible tokens (THC) — simple arithmetic equivalence. The NFT bridge moves individual non-fungible assets that each have unique metadata, template IDs, and attributes. The NFT bridge requires:

  • An off-chain database to map WAX template IDs → Avalanche token IDs
  • AtomicAssets API queries to look up NFT metadata
  • Vault locking instead of burning (so assets are always recoverable)
  • Batch minting to make moving large quantities practical

How does WAX → Avalanche NFT bridging work?​

  1. Player transfers NFTs to the WAX bridge contract with memo "teleport:<chain_id>:<destination_address>"
  2. NFTs are locked in the WAX vault — not burned
  3. The oracle detects the event, queries AtomicAssets for template IDs, translates to Avalanche token IDs via PostgreSQL, and signs an EIP-712 payload
  4. Player calls NFTBridge.claim(tokenIds, waxTxId, signatures[]) on Avalanche
  5. Contract verifies threshold signatures and calls MonsutaNFT.mintBatch()

What happens if I bridge back from Avalanche to WAX?​

  1. Player calls NFTBridge.teleport(waxName, tokenIds, chainId) on Avalanche
  2. NFTs are locked in the Avalanche bridge vault
  3. The oracle detects the event and checks the WAX vault
  4. If the originals are in the WAX vault (round-trip) → they are released to the player
  5. If they're not in the WAX vault (native Avalanche NFTs) → new NFTs are minted on WAX

Are NFTs ever destroyed during bridging?​

No. Both bridges are vault-based. NFTs are locked on the source chain when bridged out and unlocked (or minted new) on the destination. If anything goes wrong in transit, the vault ensures assets are always recoverable.

How are token IDs assigned on Avalanche?​

Using bitwise encoding:

avaxTokenId = (typeId << 128) | serial

typeId encodes what type of NFT it is (mapped from the WAX template ID). serial is an atomically incrementing counter that ensures no two NFTs share an ID.

Achievements​

What are on-chain achievements?​

Achievements are attestation records stored directly in the AchievementsRegistry contract. They prove a player accomplished something specific — won a tournament, reached a milestone, or completed a quest. They are queryable by any external system and serve as reputation signals, access gates, and historical records.

How are achievements issued?​

Two modes:

ModeHow
TrustlessAn authorized issuer or the contract owner calls issueAchievement() directly
Server-GatedThe game server signs an EIP-712 payload; the player (or any relayer) submits it on-chain

Can achievements be revoked?​

Only if the achievement type was registered with revocable = true. Non-revocable achievements are permanent — once issued, they can never be removed. After revocation, achievements can be re-issued.

Can achievements be transferred?​

No. Achievements are soulbound attestation records, not NFT tokens. They are permanently associated with the player address they were issued to.

Staking​

What can I stake?​

ERC-721 NFTs from whitelisted collections. The game operator configures which collections are eligible and the weight assigned to each token type.

Do staked NFTs leave my wallet?​

No. Staking is non-custodial. Your NFTs stay in your wallet. The NFTStaking contract tracks your staking position by recording the collection address and token ID, then verifying ownership via IERC721.ownerOf() when distributing rewards.

What if I sell a staked NFT?​

Your staking position becomes stale. Anyone can call syncPosition() or syncAccount() to detect the ownership mismatch and remove the invalid position. Unclaimed rewards accumulated since the NFT was transferred are forfeited.

What are the reward models?​

ModelHow It Works
FixedEmissionsA fixed token amount distributed per epoch, regardless of staker count
PooledA percentage of the remaining reward pool distributed per epoch
HybridFixed base emissions plus a pooled percentage bonus

How are staking rewards claimed?​

Via Merkle proof. An off-chain worker computes every staker's weight and reward share, builds a Merkle tree, and publishes the root on-chain. Stakers call claim(epochId, weight, amount, merkleProof[]). Multiple epochs can be claimed in a single transaction via batchClaim().

Crafting​

What is the crafting system?​

CraftingRecipes.sol defines on-chain recipes that burn input NFTs and produce output NFTs. It supports two modes:

  • Trustless — no server required; the recipe is fully on-chain (e.g., burn 4 Rocks → receive 1 Marble Slab)
  • Server-gated — the game server checks off-chain conditions and signs an EIP-712 authorization before the player can craft

What happens to my NFTs when I craft?​

Input NFTs are burned by the crafting contract after verifying ownership and approval. The output NFT is either minted fresh (MINT_ON_DEMAND) or transferred from a pre-minted queue (PRE_MINTED).

Can crafted items be traded?​

Yes. Output NFTs from crafting are standard ERC-721 tokens on Avalanche — they can be transferred, sold, or bridged back to WAX.

How much does crafting cost in gas?​

  • Trustless 4-NFT burn + mint: ~220k gas (~0.002 AVAX at 10 gwei)
  • Server-gated mode adds approximately +6k gas for signature verification

Security​

What if an oracle is compromised?​

The bridge requires threshold valid unique oracle signatures. Compromising a single oracle is insufficient to forge a claim — the attacker would need to compromise at least threshold independent oracles simultaneously.

Can the game server manipulate prize payouts?​

The server submits exact payout amounts via submitResults(). The contract validates that the total submitted does not exceed the pool balance minus the treasury fee. The server:

  • Cannot award more than the pool holds
  • Cannot take funds for itself — there is no server withdrawal path
  • Cannot submit results twice — the state transition to Finalized is irreversible

Is the smart contract code audited?​

Audit is planned before mainnet deployment. The contracts are currently deployed on testnet for functional validation.

What is the domain separator and why does it matter?​

The domain separator is a bytes32 value derived from the contract name, chain ID, and contract address:

DOMAIN_SEPARATOR = keccak256("FADEDMONSUTA_THC_BRIDGE", block.chainid, address(this))

This ensures that oracle signatures are only valid for the specific contract on the specific chain they were created for. A signature for one network cannot be replayed on another.