NFT Redemption Flow: From Blockchain Back to Game

// core/fortem/types.ts
 
export interface RedeemItemResponse {
  success: boolean;
  data?: {
    id: number;
    name: string;
    description: string;
    attributes: Array<{ name: string; value: string }>;
    status: string;
    itemImage: string;
    nftNumber: number;
  };
  error?: string;
}
 
export interface RedeemResult {
  success: boolean;
  item?: {
    name: string;
    itemType: string;
    rarity: string;
  };
  error?: string;
}

// ui/redeem-popup.ts
 
export type RedeemPopupStep =
  | 'input'
  | 'verifying'
  | 'success'
  | 'error'
  | 'login_required';
 
export interface RedeemedItemInfo {
  name: string;
  itemType: string;
  rarity: string;
}

// supabase/functions/fortem-mint/index.ts
 
async function redeemNFT(redeemCode: string): Promise<Response> {
  if (!redeemCode) {
    return new Response(
      JSON.stringify({ success: false, error: 'Missing redeemCode' }),
      { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
    );
  }
 
  try {
    const accessToken = await getAccessToken();
 
    const statusResponse = await fetch(
      `${FORTEM_API_URL}/api/v1/developers/collections/${FORTEM_COLLECTION_ID}/items/${redeemCode}`,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
        },
      }
    );
 
    if (!statusResponse.ok) {
      if (statusResponse.status === 404) {
        return new Response(
          JSON.stringify({ success: false, error: 'Item not found' }),
          { status: 404, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
        );
      }
      return new Response(
        JSON.stringify({ success: false, error: `Failed to verify redeem code: ${statusResponse.status}` }),
        { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
      );
    }
 
    const itemData = await statusResponse.json();
    const status = itemData.data?.status;
 
    // The critical check: only REDEEMED items can be claimed
    if (status !== 'REDEEMED') {
      return new Response(
        JSON.stringify({
          success: false,
          error: status === 'MINTED' || status === 'KIOSK_LISTED'
            ? 'Item not yet redeemed on ForTem. Please redeem it on the ForTem marketplace first.'
            : `Item status is ${status}. Only REDEEMED items can be claimed.`,
        }),
        { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
      );
    }
 
    // Return full item data for the client to grant in-game
    return new Response(
      JSON.stringify({
        success: true,
        data: {
          id: itemData.data?.id,
          name: itemData.data?.name,
          description: itemData.data?.description,
          attributes: itemData.data?.attributes ?? [],
          status: itemData.data?.status,
          itemImage: itemData.data?.itemImage,
          nftNumber: itemData.data?.nftNumber,
        },
      }),
      { status: 200, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
    );
  } catch (error) {
    console.error('Redeem verification error:', error);
    return new Response(
      JSON.stringify({ success: false, error: error instanceof Error ? error.message : 'Unknown error' }),
      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
    );
  }
}

// ui/redeem-popup.ts
 
export class RedeemPopup extends Panel {
  private currentStep: RedeemPopupStep;
  private contentElements: GameObjects.GameObject[] = [];
  private redeemCodeInput?: string;
  private redeemedItem?: RedeemedItemInfo;
  private errorMessage?: string;
  private spinnerAngle: number = 0;
  private spinnerTimer?: Phaser.Time.TimerEvent;
 
  constructor(scene: Scene, popupConfig: RedeemPopupConfig) {
    const width = popupConfig.width ?? 380;
    const height = popupConfig.height ?? 400;
 
    super(scene, {
      x: popupConfig.x,
      y: popupConfig.y,
      width,
      height,
      title: '',
      showCloseButton: true,
      onClose: popupConfig.onClose,
    });
 
    this.popupConfig = popupConfig;
 
    if (!popupConfig.isLoggedIn) {
      this.currentStep = 'login_required';
    } else {
      this.currentStep = 'input';
    }
 
    this.renderCurrentStep();
  }
 
  private renderCurrentStep(): void {
    this.clearContent();
    switch (this.currentStep) {
      case 'login_required': this.renderLoginRequired(); break;
      case 'input':          this.renderInput();         break;
      case 'verifying':      this.renderVerifying();     break;
      case 'success':        this.renderSuccess();       break;
      case 'error':          this.renderError();         break;
    }
  }
 
  // Public methods for external state control
  setStep(step: RedeemPopupStep): void {
    this.currentStep = step;
    this.renderCurrentStep();
  }
 
  setSuccess(item: RedeemedItemInfo): void {
    this.redeemedItem = item;
    this.currentStep = 'success';
    this.renderCurrentStep();
  }
 
  setError(message: string): void {
    this.errorMessage = message;
    this.currentStep = 'error';
    this.renderCurrentStep();
  }
}

// ui/redeem-popup.ts
 
private renderInput(): void {
  const title = this.scene.add.text(0, 5, 'Redeem NFT', {
    ...FONT_STYLE.HEADING,
    fontSize: '24px',
  }).setOrigin(0.5);
  this.addContent(title);
  this.contentElements.push(title);
 
  const giftIcon = this.scene.add.text(0, 70, '\u{1F381}', {
    fontSize: '48px',
  }).setOrigin(0.5);
  this.addContent(giftIcon);
  this.contentElements.push(giftIcon);
 
  const message = this.scene.add.text(0, 125, 'Enter your ForTem redeem code:', {
    ...FONT_STYLE.SMALL,
    fontSize: '14px',
    color: COLORS_HEX.TEXT_SECONDARY,
    align: 'center',
  }).setOrigin(0.5);
  this.addContent(message);
  this.contentElements.push(message);
 
  // Visual input field
  const inputWidth = 300;
  const inputY = 175;
 
  const inputBg = this.scene.add.graphics();
  inputBg.fillStyle(0x1a1a2e, 1);
  inputBg.fillRoundedRect(-inputWidth / 2, inputY - 26, inputWidth, 52, 10);
  inputBg.lineStyle(2, COLORS.PRIMARY, 0.6);
  inputBg.strokeRoundedRect(-inputWidth / 2, inputY - 26, inputWidth, 52, 10);
  this.addContent(inputBg);
  this.contentElements.push(inputBg);
 
  this.redeemCodeInput = '';
  const inputText = this.scene.add.text(-inputWidth / 2 + 15, inputY, 'PP-XXX-XXXXX-XXXX', {
    ...FONT_STYLE.BODY,
    fontSize: '15px',
    color: '#555555',
  }).setOrigin(0, 0.5);
  this.addContent(inputText);
  this.contentElements.push(inputText);
 
  // Clickable area triggers browser prompt
  const inputArea = this.scene.add.rectangle(0, inputY, inputWidth, 52, 0x000000, 0);
  inputArea.setInteractive({ useHandCursor: true });
  inputArea.on('pointerdown', () => {
    const code = prompt('Enter your ForTem redeem code:');
    if (code) {
      this.redeemCodeInput = code.trim().toUpperCase();
      inputText.setText(this.redeemCodeInput || 'PP-XXX-XXXXX-XXXX');
      inputText.setColor(this.redeemCodeInput ? COLORS_HEX.TEXT : '#555555');
    }
  });
  this.addContent(inputArea);
  this.contentElements.push(inputArea);
 
  // Redeem button with validation
  const redeemBtn = new Button(this.scene, {
    x: 75,
    y: 285,
    width: 130,
    height: 48,
    text: 'REDEEM',
    fontSize: '18px',
    color: COLORS.SUCCESS,
    onClick: () => {
      if (!this.redeemCodeInput || this.redeemCodeInput.length < 5) {
        this.showToast('Please enter a valid redeem code');
        return;
      }
      this.currentStep = 'verifying';
      this.renderCurrentStep();
      this.popupConfig.onRedeem(this.redeemCodeInput);
    },
  });
  this.addContent(redeemBtn);
  this.contentElements.push(redeemBtn);
}

// core/fortem/fortem-service.ts
 
async redeemItem(redeemCode: string): Promise<RedeemResult> {
  const supabase = getSupabase();
  if (!supabase) {
    return { success: false, error: 'Supabase not configured' };
  }
 
  try {
    const { data: { session } } = await supabase.auth.getSession();
    if (!session) {
      return { success: false, error: 'Please login to redeem NFTs' };
    }
 
    const { data, error } = await supabase.functions.invoke<RedeemItemResponse>(
      'fortem-mint',
      {
        body: {
          action: 'redeem',
          redeemCode,
        },
      }
    );
 
    if (error) {
      return { success: false, error: error.message ?? 'Unknown error' };
    }
 
    if (!data?.success || !data.data) {
      return { success: false, error: data?.error ?? 'Unknown error' };
    }
 
    // Parse item identity from NFT attributes
    const attributes = data.data.attributes ?? [];
    const typeAttr = attributes.find(a => a.name === 'Type');
    const rarityAttr = attributes.find(a => a.name === 'Rarity');
 
    return {
      success: true,
      item: {
        name: data.data.name,
        itemType: typeAttr?.value ?? 'UNKNOWN',
        rarity: rarityAttr?.value ?? 'Common',
      },
    };
  } catch (err) {
    const message = err instanceof Error ? err.message : 'Network error';
    return { success: false, error: message };
  }
}

// scenes/auth/profile-scene.ts
 
private async handleRedeem(redeemCode: string): Promise<void> {
  EventBus.emit(GameEvents.NFT_REDEEM_STARTED, { redeemCode });
 
  // Critical: sync cloud data first to find user's own minted items
  if (syncService.isCloudSyncAvailable()) {
    await syncService.syncOnLogin();
  }
 
  // Check if this is user's own minted item
  const existingItem = economyManager.findItemByRedeemCode(redeemCode);
 
  // Only check marketplace redeems for double-redemption
  if (!existingItem && economyManager.isAlreadyRedeemed(redeemCode)) {
    this.redeemPopup?.setError('This code has already been redeemed');
    EventBus.emit(GameEvents.NFT_REDEEM_FAILED, { redeemCode, error: 'Already redeemed' });
    return;
  }
 
  // Verify with ForTem that the NFT was burned
  const result = await fortemService.redeemItem(redeemCode);
 
  if (!result.success || !result.item) {
    this.redeemPopup?.setError(result.error ?? 'Failed to redeem');
    EventBus.emit(GameEvents.NFT_REDEEM_FAILED, { redeemCode, error: result.error });
    return;
  }
 
  if (existingItem) {
    // Scenario 1: Restore user's own minted item
    economyManager.restoreRedeemedItem(redeemCode);
  } else {
    // Scenario 2: Add new item from marketplace purchase
    const itemTypeMap: Record<string, ItemType> = {
      'SKIN': ItemType.PADDLE_SKIN,
      'paddle': ItemType.PADDLE_SKIN,
      'PADDLE_SKIN': ItemType.PADDLE_SKIN,
      'ball': ItemType.BALL_SKIN,
      'BALL_SKIN': ItemType.BALL_SKIN,
      'COLLECTIBLE': ItemType.BADGE,
      'BADGE': ItemType.BADGE,
    };
 
    const rarityMap: Record<string, Rarity> = {
      'Common': Rarity.COMMON,
      'COMMON': Rarity.COMMON,
      'Uncommon': Rarity.UNCOMMON,
      'UNCOMMON': Rarity.UNCOMMON,
      'Rare': Rarity.RARE,
      'RARE': Rarity.RARE,
      'Epic': Rarity.EPIC,
      'EPIC': Rarity.EPIC,
      'Legendary': Rarity.LEGENDARY,
      'LEGENDARY': Rarity.LEGENDARY,
    };
 
    const itemType = itemTypeMap[result.item.itemType] ?? ItemType.BADGE;
    const rarity = rarityMap[result.item.rarity] ?? Rarity.COMMON;
 
    economyManager.addRedeemedItem(itemType, rarity, redeemCode);
  }
 
  // Show success
  this.redeemPopup?.setSuccess({
    name: result.item.name,
    itemType: result.item.itemType,
    rarity: result.item.rarity,
  });
 
  EventBus.emit(GameEvents.NFT_REDEEM_SUCCESS, {
    redeemCode,
    item: result.item,
  });
}

# Decision Tree
# Enter redeem code
#   │
#   ▼
# Sync cloud data (critical!)
#   │
#   ▼
# findItemByRedeemCode(code)
#   │
#   ├─ Found ──▶ User's OWN minted item
#   │            Verify REDEEMED on ForTem
#   │            restoreRedeemedItem() → isNFT = false
#   │
#   └─ Not found ──▶ MARKETPLACE purchase
#                    isAlreadyRedeemed()? → Error
#                    Verify REDEEMED on ForTem
#                    addRedeemedItem() → new item + random skin

// core/economy/economy-manager.ts
 
// Scenario 1: Find the original minted item
findItemByRedeemCode(redeemCode: string): InventoryItem | null {
  const normalizedCode = redeemCode.toUpperCase();
  return this.data.inventory.find(
    item => item.nftMetadata?.redeemCode?.toUpperCase() === normalizedCode
  ) ?? null;
}
 
// Scenario 1: "Un-NFT" the item
restoreRedeemedItem(redeemCode: string): InventoryItem | null {
  const item = this.findItemByRedeemCode(redeemCode);
  if (!item) return null;
 
  item.isNFT = false;
  delete item.nftId;
  delete item.nftMetadata;
 
  this.save();
  return item;
}
 
// Prevent double-redemption for marketplace purchases
isAlreadyRedeemed(redeemCode: string): boolean {
  const normalizedCode = redeemCode.toUpperCase();
  return this.data.inventory.some(item => {
    const redeemedFrom = item.metadata?.redeemedFrom as string | undefined;
    return redeemedFrom?.toUpperCase() === normalizedCode;
  });
}
 
// Scenario 2: Create a new item from marketplace purchase
addRedeemedItem(
  itemType: ItemType,
  rarity: Rarity,
  redeemCode: string
): InventoryItem {
  const definition = ITEM_DEFINITIONS[itemType];
 
  const newItem: InventoryItem = {
    id: this.generateItemId(),
    itemType,
    rarity,
    quantity: 1,
    acquiredAt: Date.now(),
    isNFT: false, // Redeemed items are not NFTs (the NFT was burned)
    metadata: {
      redeemedFrom: redeemCode,
    },
  };
 
  // Assign random skin frame if applicable
  if (definition.skinVariants) {
    const usePremium =
      definition.skinVariants.premiumFrames &&
      definition.skinVariants.premiumFrames.frames[rarity]?.length > 0 &&
      Math.random() > 0.5;
 
    const source = usePremium
      ? definition.skinVariants.premiumFrames!
      : { textureKey: definition.skinVariants.textureKey, frames: definition.skinVariants.frames };
 
    const frames = source.frames[rarity];
    if (frames && frames.length > 0) {
      const randomFrame = frames[Math.floor(Math.random() * frames.length)]!;
      newItem.skinData = {
        textureKey: source.textureKey,
        frame: randomFrame,
      };
    }
  }
 
  this.data.inventory.push(newItem);
  this.save();
  return newItem;
}

# [In-Game Item] → Mint (Art. 3-4) → [NFT on Sui] → Trade on ForTem → Burn/Redeem → Redeem Code (Art. 5) → [In-Game Item]