System Architecture

A complete high-level overview of Monsuta Core's data flow, deployment topologies, and modular integrations.

The Separation of Powers

Monsuta Core is built on a fundamental architectural divide: separating the game's actual state and latency-sensitive logic from its verifiable economic settlement.

The Game Server commands all authority over matchmaking, mechanics, inventory states, and rankings. It is built in traditional server technologies (Node.js, Go, standard databases).
The Blockchain acts purely as a financial and administrative root of trust. It holds prizes, facilitates crafting conversions, validates staking, and secures cross-chain telemetry.

You should never write a smart contract to move a player character, and you should never write a database row to permanently securely custody another human's funds.

High-Level Topology

                  ┌────────────────────┐
                  │    GAME CLIENT     │
                  │  (Web / Unity)     │
                  └─────────┬──────────┘
                            │
               WebSocket / REST  (Real-Time Input)
                            │
                  ┌─────────▼──────────┐
                  │    GAME SERVER     │
                  │ (Authoritative)    │
                  └─────────┬──────────┘
                            │
               Asynchronous SDK  (Settlement)
                            │
        ┌───────────────────┴────────────────────┐
        │                                        │
┌───────▼────────┐                       ┌───────▼────────┐
│  Avalanche     │                       │  Legacy Chains │
│  C-Chain       │ ◄── Oracle Network ──►│  (e.g., WAX)   │
│  (Settlement)  │                       │  (Origin)      │
└────────────────┘                       └────────────────┘

Component Responsibilities

Game Client

The client acts strictly as a dumb presentation layer. It contains zero authority over state or mechanics, making game clients natively secure against fabricated actions. It only reaches out to a web3 wallet when interacting with the on-chain settlement layer, such as paying tournament entry fees or claiming staked rewards.

Game Server

The game server is universally trusted for operational execution, similar to standard competitive titles.

Compiles matchmaking queues and player ratings.
Resolves inputs, latency handling, abilities, and combat damage.
Verifies and coordinates the issuance of EIP-712 achievement attestations.
Generates exact payout configurations for prize pools.

The Settlement Layer (Smart Contracts)

Monsuta Core decomposes its settlement layer into modular EVM-compatible contracts (Solidity). A game integrating the system only needs to deploy the components it actively uses.

Contract	Pattern	Purpose
`PrizePoolFactory.sol`	UUPS Upgradeable	Deploys un-ruggable ERC1967 proxy components to hold funds for distinct tournaments.
`NFTStaking.sol`	UUPS Upgradeable	Handles epoch-based Merkle distribution for staking rewards so assets never leave player custody.
`CraftingRecipes.sol`	UUPS Upgradeable	Translates off-chain progression or burns raw components to directly mint on-chain items.
`AchievementsRegistry.sol`	UUPS Upgradeable	Cryptographically verifies and stores server-issued attestations for player milestones.
`FadedMonsutaTHC.sol`	Oracle Consensus	Bridging protocol managing fungible token burns/mints across diverse networks.
`NFTBridge.sol`	Vault Escrow	Locks origin NFTs securely so they can be bridged dynamically without irreversible burning.

Core Operations

Tournament Payout Flow

Monsuta Core automates the handoff between gameplay logic and final economic settlement.

A tournament initializes its own proxy PrizePool contract on Avalanche.
Players or external sponsors deposit entry fees directly into this trustless vault.
The server watches the contract state to ensure entry fees are paid prior to matchmaking authorization.
Matches process entirely off-chain, free of latency or gas fees.
Once the server resolves final tournament standings, it interacts with the SDK to invoke the submitResults() transaction.
The PrizePool permanently finalizes the payouts. Over the next 30 days, verified winners initiate a simple claim() to withdraw their exact rewards directly to their wallets.

Cross-Chain Bridge Flow

Legacy bridging relies heavily on mint/burn loops. Because Monsuta Core manages complex game NFTs holding intricate progression metadata, the bridge functions on a sophisticated Vault mechanism.

Tokens or NFTs originated on legacy chains (like WAX) are seamlessly transited to high-performance networks (like Avalanche) via an independent Node.js oracle system.

A player deposits their NFT into the origin chain's locked vault contract.
The nft-oracle-wax.js service detects the operation. It queries the legacy asset protocol, translates the metadata payload, and prepares an execution signature.
The player broadcasts the signature to Avalanche, minting an ERC-721 equivalent.
If the player ever migrates back, the Avalanche token is sequestered, and the original legacy chain vault is gracefully unlocked.

The Separation of Powers​

High-Level Topology​

Component Responsibilities​

Game Client​

Game Server​

The Settlement Layer (Smart Contracts)​

Core Operations​

Tournament Payout Flow​

Cross-Chain Bridge Flow​