Web3 (Thirdweb / Moralis)¶

IntelliVerseX Web3 SDK — Wallet auth (MetaMask / WalletConnect), NFT rewards, token gating, and on-chain leaderboards backed by Nakama + Hiro.

Requirements¶

• Node.js 18+ or modern browser with MetaMask / EIP-1193 wallet
• @heroiclabs/nakama-js v2.7+
• ethers v6+

Installation¶

npm install @intelliversex/sdk-web3 @heroiclabs/nakama-js ethers

Quick Start¶

import { IVXWeb3Manager } from '@intelliversex/sdk-web3';

const ivx = IVXWeb3Manager.getInstance();

ivx.on('walletConnected', (info) => console.log('Wallet:', info.address));
ivx.on('authSuccess', (userId) => console.log('Authenticated:', userId));

ivx.initialize({
  nakamaHost: '127.0.0.1',
  nakamaPort: 7350,
  chainId: 137,         // Polygon
  enableDebugLogs: true,
});

// Connect MetaMask
const wallet = await ivx.connectWallet();

// Authenticate via wallet signature
await ivx.authenticateWallet();

// Query NFTs owned by this wallet
const nfts = await ivx.fetchNfts('0xContractAddress');

// Token-gated content check
const hasAccess = await ivx.checkTokenGate('0xContractAddress', '1');

// Standard game features
const profile = await ivx.fetchProfile();
await ivx.submitScore('weekly_leaderboard', 2500);

API Surface¶

IVXWeb3Manager is a TypeScript singleton that follows the same Nakama-backed IVX manager pattern as Unity’s IntelliVerseX managers: one coordinator for auth, economy hooks, leaderboards, storage, and RPC. It does not literally extend a shared IVXManager class in TypeScript (there is no shared base class in npm); behavior and naming are aligned with the Unity IVX surface.

Wallet methods¶

NFT methods¶

Token methods¶

Standard IVX-style methods (Nakama session)¶

Events (on / off)¶

initialized, walletConnected, walletDisconnected, authSuccess, authError, profileLoaded, walletUpdated, leaderboardFetched, nftsFetched, tokenBalanceFetched, storageRead, rpcResponse, error — see IVXWeb3EventMap in the package typings.

Configuration (IVXWeb3Config)¶

Defaults favor the hosted IntelliVerseX Nakama endpoint; override for local development as in Quick Start.

Feature Coverage¶

Legend: Y = included in this Web3 npm SDK, - = not in scope for the Web3 JS client, S = stub / use another IntelliVerseX SDK or host platform (e.g. Unity) for full support.

Web3-Specific Features¶

Feature	Status
Wallet Connection (MetaMask / EIP-1193)
Wallet Signature Auth
NFT Ownership Queries
ERC-20 Token Balances
Token Gating
Thirdweb Integration	Config Ready
Moralis Integration	Config Ready

Standard Features¶

All standard IntelliVerseX features are included: Device Auth, Profile, Wallet/Economy, Leaderboards, Storage, RPC.

Architecture¶

Your Game / dApp
    |
    v
+----------------------------------------------+
|     IntelliVerseX Web3 SDK (IVXWeb3Manager)  |
|  Wallet | Auth | NFT | Tokens | Gate | RPC  |
+----------------------------------------------+
    |                    |
    v                    v
+------------------+  +------------------+
| Nakama Client    |  | ethers.js        |
| (nakama-js)      |  | (EIP-1193)       |
+------------------+  +------------------+
    |                    |
    v                    v
+------------------+  +------------------+
| Nakama Server    |  | EVM Blockchain   |
| + Hiro + Satori  |  | (via RPC nodes)  |
+------------------+  +------------------+

Smart Contract Integration¶

How token gating works¶

1. The browser wallet connects with connectWallet(); the SDK knows walletAddress and chainId.
2. checkTokenGate(contract, minBalance) sends a Nakama RPC (ivx_web3_check_gate) with that address, chain, contract, and threshold.
3. Your server implementation (Lua/Go in Nakama) should call an indexer or RPC node (Thirdweb, Moralis, Alchemy, etc.), verify balance or NFT ownership, and return { granted: true | false }.
4. The client never trusts itself for gate results; it only displays what the server authorizes.

NFT reward flow¶

1. fetchNfts() triggers ivx_web3_fetch_nfts, again server-side, so API keys for Moralis/Alchemy stay off the client.
2. To grant an NFT or off-chain reward, use a dedicated RPC that mints, queues airdrop, or credits Hiro currency after verifying eligibility (quest complete, tournament rank, etc.).
3. Keep mint/transfer authority in custodial or contract-admin flows; the SDK surfaces reads and auth, not private keys.

On-chain leaderboard verification¶

• Default path: submitScore / fetchLeaderboard use Nakama leaderboards (authoritative game scores).
• On-chain verification: Implement an RPC that (a) accepts a score or proof payload, (b) verifies signatures or zk/state roots on the server, then © writes the Nakama leaderboard record only if valid. The Web3 SDK’s callRpc is the extension point for that custom pipeline.

Security Model¶

Wallet signature auth flow¶

1. After connectWallet(), authenticateWallet() builds a deterministic message (wallet address + nonce).
2. The user signs with their wallet (eth_sign / personal_sign via ethers).
3. The client calls authenticateCustom with the wallet id and then ivx_web3_verify_wallet with { address, message, signature, chainId }.
4. The server must recover the signer from the signature, compare to address, enforce nonce/replay rules, and only then treat the session as bound to that wallet.

Server-side verification¶

• All gating, NFT lists, and token balances intended for security decisions must be validated on Nakama (or your BFF), not by trusting client-side ethers reads alone (users can spoof devtools).
• Rate-limit verification RPCs and tie them to the authenticated Nakama user.

Never store private keys¶

• The SDK never asks for seed phrases or private keys. Only public addresses and signatures in transit.
• Do not log full signatures in production analytics.

Supported Chains¶

Any EVM-compatible chain: Ethereum (1), Polygon (137), Arbitrum (42161), Optimism (10), BSC (56), Avalanche (43114), Base (8453), and more.

Advanced Examples¶

NFT-gated tournament entry¶

await ivx.connectWallet();
await ivx.authenticateWallet();

const PASS_CONTRACT = '0xYourTournamentPass';
const canEnter = await ivx.checkTokenGate(PASS_CONTRACT, '1');
if (!canEnter) {
  throw new Error('Tournament requires NFT pass');
}
const ok = await ivx.callRpc('tournament_register', JSON.stringify({ bracketId: 'spring-2026' }));

Token reward on achievement¶

// After server-side achievement validation (recommended pattern):
const result = await ivx.callRpc('grant_achievement_token', JSON.stringify({
  achievementId: 'first_win',
  walletAddress: ivx.walletAddress,
}));
// Server credits Hiro currency, queues ERC-20 transfer, or records claimable reward
await ivx.fetchWallet();

Multi-chain setup¶

• Instantiate one IVXWeb3Manager per app shell; chainId in initialize() is the default expectation for your backend.
• If users may switch chains in MetaMask, re-read walletInfo.chainId after connectWallet() and pass chainId into every RPC payload so the server queries the correct network.
• For multiple environments (Polygon + Base), use separate Nakama RPC implementations keyed by chainId, or separate gameId/namespace per chain.

Troubleshooting¶

Further Reading¶

• SDKs/web3/README.md — npm package readme and API notes
• SDK Web3 strategy doc — product and integration context
• Nakama JavaScript client — sessions, RPC, storage
• Nakama custom authentication — how authenticateCustom maps to your verifier
• ethers v6 docs — BrowserProvider, signing
• EIP-1193 — Ethereum provider API
• EIP-4361 Sign-In with Ethereum — optional upgrade path for structured auth messages
• IntelliVerseX Hiro integration guide — economy RPCs used by fetchWallet / grantCurrency
• Nakama integration guide — RPC authoring and deployment expectations
• Feature coverage matrix — cross-platform comparison
• Unity WebGL platform doc — when pairing browser builds with the same backend

Source¶

SDKs/web3/