Identity & Crafting Module

On-chain NFT identity, item crafting, achievement attestations, and dynamic metadata.

What This Module Does

The Identity module is the bridge between off-chain gameplay and permanent on-chain ownership. It answers three questions that every blockchain game needs to answer:

What does a player own? — MonsutaNFT.sol defines the NFT standard: upgradeable, batch-mintable, lockable, and royalty-aware.
How do new items come into existence? — CraftingRecipes.sol defines the rules: players can forge new NFTs by combining existing ones, either entirely on-chain (trustless) or with server authorization (server-gated).
What has a player accomplished? — AchievementsRegistry.sol records on-chain attestations that prove a player reached a milestone, completed a quest, or won a tournament.

The metadata router ties it together: token IDs encode their type mathematically, so traits are generated dynamically without a database lookup for every request.

Components

Component	Description	Doc
Crafting	Recipe-driven item creation from NFT materials	Crafting →
Achievements	On-chain achievement attestations with direct, batch, and server-gated issuance	Achievements →

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        GAME SERVER                               │
│                                                                  │
│  Player earns materials ────────── Player crafts item            │
│  through gameplay                  (selects recipe)              │
│         │                                │                       │
│         │ (tracked off-chain)            │                       │
│         │                                ▼                       │
│         │                    Server checks conditions            │
│         │                    (XP, quest complete, etc.)          │
│         │                                │                       │
│         │                                ▼                       │
│  Player reaches                Server signs EIP-712 attestation  │
│  achievement milestone                   │                       │
│         │                                │                       │
└─────────┼────────────────────────────────┼───────────────────────┘
          │                                │
          │ (NFTs held in wallet)          ▼
          │                   ┌────────────────────────┐
          │                   │   CraftingRecipes.sol  │
          │                   │                        │
          │                   │  1. Verify sig / recipe│
          │                   │  2. Check NFT ownership│
          ▼                   │  3. Burn input NFTs    │
  MonsutaNFT.sol ◄────────────│  4. Mint output NFT   │
  (owns the token IDs)        └────────────────────────┘
          │
          │  ┌────────────────────────────────┐
          │  │  AchievementsRegistry.sol      │
          │  │                                │
          │  │  1. Verify issuer or signature │
          │  │  2. Record achievement on-chain│
          │  │  3. Emit AchievementIssued     │
          │  └────────────────────────────────┘
          │
          ▼
  Metadata Router (Railway)
  GET /meta/{tokenId}.json
  → Dynamic traits via tokenId math

Token ID Design

Token IDs carry their type identity mathematically:

tokenId = typeId × 1,000,000 + serial

This means:

tokenId = 5 → Base token, serial 5 (a Rock)
tokenId = 1_000_001 → TypeId 1, serial 1 (first Marble Slab ever crafted)
tokenId = 2_000_047 → TypeId 2, serial 47 (47th Tetra Goldium crafted)

The metadata router decodes this on every request — no database, no registry, no state to keep in sync. A new crafted type just needs a new typeId added to the config.

Crafting Modes

CraftingRecipes.sol supports two modes that can be mixed across different recipes:

Trustless Crafting

No server involvement. The recipe lives entirely on-chain.

Example: Burn 4 Rocks → Receive 1 Marble Slab
Player approves the contract, calls craft(), done
No signature required, no server round-trip
Gas cost: ~220k (~0.002 AVAX at 10 gwei)

Server-Gated Crafting

The game server authorizes the craft with an EIP-712 signature.

Example: Reach Level 20 + hold 3 Rare cards → Receive 1 Legendary
Server checks off-chain conditions (XP, rank, quest state)
Server signs a Craft(player, recipeId, nonce, deadline) payload
Player submits the signature on-chain — contract verifies and executes
Conditions are defined and enforced by the game, not the contract

Both modes support two output types: MINT_ON_DEMAND (contract mints fresh) and PRE_MINTED (tokens queued and transferred FIFO).

Key Properties

Property	Detail
Non-custodial	NFTs stay in player wallets — never locked in the crafting contract
Batch minting	`mintBatch(address, uint256[])` — gas-optimized for bridging 100s of NFTs at once
Lockable	`LOCK_MANAGER_ROLE` allows staking and tournament contracts to lock tokens
Upgradeable	UUPS proxy on all contracts — owners can upgrade without redeploying
Multi-minter	`MINTER_ROLE` on MonsutaNFT supports bridge + crafting + future systems
EIP-712 replay protection	Each server signature has a nonce and deadline — cannot be reused
Royalties	ERC-2981 royalty support built into MonsutaNFT
Achievement attestations	Permanent on-chain records with revocable/non-revocable modes

When to Use This Module

Your Situation	What You Need
Game has a crafting or item-forging mechanic	Crafting
Game wants to reward milestones with on-chain proof	Achievements
Game has tradeable items that players own permanently	Both
Game only has gameplay with no items or progression	❌ Not needed

What This Module Does​

Components​

Architecture​

Token ID Design​

Crafting Modes​

Trustless Crafting​

Server-Gated Crafting​

Key Properties​

When to Use This Module​