Web3 Types

Overview

These types define the Web3 integration layer in G3Engine, including Solana tokens, NFTs, game economy configuration, and transaction tracking.

TokenInfo

Represents a Solana token, including standard SPL tokens and Pump.fun tokens.

export interface TokenInfo {
    mint: string;
    name: string;
    symbol: string;
    balance: number;
    decimals: number;
    imageUri?: string;
    // Pump.fun specific
    isPumpToken?: boolean;
    bondingCurveComplete?: boolean;
    priceInSol?: number;
}

Properties

mint

string

required

The token’s mint address on Solana (base58 encoded public key)

name

string

required

Full name of the token (e.g., “Solana”, “USD Coin”)

symbol

string

required

Token symbol/ticker (e.g., “SOL”, “USDC”)

balance

number

required

User’s token balance in base units (before decimal adjustment)

decimals

number

required

Number of decimal places for the token (typically 9 for SPL tokens)

imageUri

string

URL to the token’s logo/icon image

Show Pump.fun Specific Fields

isPumpToken

boolean

Whether this is a Pump.fun launched token

bondingCurveComplete

boolean

For Pump.fun tokens, indicates if the bonding curve has completed and liquidity migrated to Raydium

priceInSol

number

Current price of the token in SOL

Usage Example

const token: TokenInfo = {
  mint: "So11111111111111111111111111111111111111112",
  name: "Wrapped SOL",
  symbol: "SOL",
  balance: 1500000000, // 1.5 SOL with 9 decimals
  decimals: 9,
  imageUri: "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png"
};

// Display balance with decimals
const displayBalance = token.balance / Math.pow(10, token.decimals);
console.log(`${displayBalance} ${token.symbol}`); // "1.5 SOL"

NFTInfo

Represents a Solana NFT with metadata.

export interface NFTInfo {
    mint: string;
    name: string;
    imageUri: string;
    collection?: string;
    attributes?: { trait_type: string; value: string }[];
}

Properties

mint

string

required

The NFT’s mint address on Solana (base58 encoded public key)

name

string

required

Name of the NFT

imageUri

string

required

URL to the NFT’s image asset

collection

string

Collection address or name that this NFT belongs to

attributes

array

Array of trait attributes for the NFT

Show Attribute Object

trait_type

string

required

Name of the trait (e.g., “Background”, “Hat”, “Rarity”)

value

string

required

Value of the trait (e.g., “Blue”, “Crown”, “Legendary”)

Usage Example

const nft: NFTInfo = {
  mint: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  name: "SMB #1355",
  imageUri: "https://arweave.net/example.png",
  collection: "SMB Gen2",
  attributes: [
    { trait_type: "Background", value: "Blue" },
    { trait_type: "Hat", value: "Crown" },
    { trait_type: "Rarity", value: "Legendary" }
  ]
};

GameEconomyConfig

Configuration for the in-game token economy system.

export interface GameEconomyConfig {
    rewardTokenMint: string | null;
    rewardPerLevel: number;
    tipJarEnabled: boolean;
    itemPrices: { itemId: string; priceToken: string; amount: number }[];
}

Properties

rewardTokenMint

string | null

required

Mint address of the token used for player rewards, or null if no reward token is configured

rewardPerLevel

number

required

Amount of reward tokens to give players per level completion (in base units)

tipJarEnabled

boolean

required

Whether the tip jar feature is enabled, allowing players to tip the game creator

itemPrices

array

required

Array of in-game items with their token prices

Show Item Price Object

itemId

string

required

Unique identifier for the in-game item

priceToken

string

required

Mint address of the token used to purchase this item

amount

number

required

Price amount in base units

Usage Example

const economyConfig: GameEconomyConfig = {
  rewardTokenMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
  rewardPerLevel: 1000000, // 1 USDC (6 decimals)
  tipJarEnabled: true,
  itemPrices: [
    {
      itemId: "sword_legendary",
      priceToken: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      amount: 5000000 // 5 USDC
    },
    {
      itemId: "health_potion",
      priceToken: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      amount: 100000 // 0.1 USDC
    }
  ]
};

Web3Transaction

Tracks Solana transactions performed within the application.

export interface Web3Transaction {
    id: string;
    type: 'token_launch' | 'buy' | 'sell' | 'mint_nft' | 'transfer' | 'airdrop';
    signature: string;
    status: 'pending' | 'confirmed' | 'failed';
    description: string;
    timestamp: number;
}

Properties

string

required

Unique identifier for this transaction record (UUID)

type

string

required

Type of transaction:

token_launch - Token creation/launch on Pump.fun
buy - Token purchase
sell - Token sale
mint_nft - NFT minting
transfer - Token or NFT transfer
airdrop - Airdrop claim

signature

string

required

Solana transaction signature (base58 encoded)

status

string

required

Current status of the transaction:

pending - Submitted but not yet confirmed
confirmed - Successfully confirmed on-chain
failed - Transaction failed

description

string

required

Human-readable description of the transaction (e.g., “Bought 100 MYTOKEN”)

timestamp

number

required

Unix timestamp (milliseconds) when the transaction was created

Usage Example

const transaction: Web3Transaction = {
  id: "550e8400-e29b-41d4-a716-446655440000",
  type: "buy",
  signature: "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
  status: "confirmed",
  description: "Bought 100 MYTOKEN for 0.5 SOL",
  timestamp: Date.now()
};

// Format for display
const date = new Date(transaction.timestamp).toLocaleString();
console.log(`[${transaction.status.toUpperCase()}] ${transaction.description}`);
console.log(`Signature: ${transaction.signature}`);

SolanaNetwork

Defines the available Solana network environments.

export type SolanaNetwork = 'devnet' | 'mainnet-beta';

devnet - Solana’s development/test network
mainnet-beta - Solana’s production network

Usage Example

import { useWeb3Store } from '@/store/web3Store';

const setNetwork = useWeb3Store((state) => state.setNetwork);

// Switch to mainnet
setNetwork('mainnet-beta');

// Switch to devnet for testing
setNetwork('devnet');

Integration Examples

Fetching User Tokens

import { useWeb3Store } from '@/store/web3Store';
import type { TokenInfo } from '@/store/web3Store';

const { walletAddress, setTokens } = useWeb3Store();

async function fetchUserTokens() {
  if (!walletAddress) return;
  
  // Fetch tokens from Solana (example)
  const response = await fetch(`/api/tokens/${walletAddress}`);
  const tokens: TokenInfo[] = await response.json();
  
  setTokens(tokens);
}

Recording a Transaction

import { useWeb3Store } from '@/store/web3Store';
import type { Web3Transaction } from '@/store/web3Store';
import { v4 as uuidv4 } from 'uuid';

const addTransaction = useWeb3Store((state) => state.addTransaction);

async function buyToken(amount: number) {
  const txId = uuidv4();
  
  // Create pending transaction
  const tx: Web3Transaction = {
    id: txId,
    type: 'buy',
    signature: '', // Will be filled after sending
    status: 'pending',
    description: `Buying ${amount} tokens`,
    timestamp: Date.now()
  };
  
  addTransaction(tx);
  
  // Send transaction...
  // Then update with signature and status
}

Configuring Game Economy

import { useWeb3Store } from '@/store/web3Store';

const updateEconomy = useWeb3Store((state) => state.updateEconomy);

// Set reward token
updateEconomy({
  rewardTokenMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  rewardPerLevel: 1000000 // 1 USDC per level
});

// Add item pricing
updateEconomy({
  itemPrices: [
    {
      itemId: "power_up",
      priceToken: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      amount: 500000 // 0.5 USDC
    }
  ]
});

Core API

Types

Overview

TokenInfo

Properties

Usage Example

NFTInfo

Properties

Usage Example

GameEconomyConfig

Properties

Usage Example

Web3Transaction

Properties

Usage Example

SolanaNetwork

Usage Example

Integration Examples

Fetching User Tokens

Recording a Transaction

Configuring Game Economy

Build docs developers (and LLMs) love

Core API

Types

​Overview

​TokenInfo

​Properties

​Usage Example

​NFTInfo

​Properties

​Usage Example

​GameEconomyConfig

​Properties

​Usage Example

​Web3Transaction

​Properties

​Usage Example

​SolanaNetwork

​Usage Example

​Integration Examples

​Fetching User Tokens

​Recording a Transaction

​Configuring Game Economy

Build docs developers (and LLMs) love

Overview

TokenInfo

Properties

Usage Example

NFTInfo

Properties

Usage Example

GameEconomyConfig

Properties

Usage Example

Web3Transaction

Properties

Usage Example

SolanaNetwork

Usage Example

Integration Examples

Fetching User Tokens

Recording a Transaction

Configuring Game Economy