Jon/gift cards

[Jon-edge]

Phaze Gift Card Integration Design

Overview

The Phaze gift card feature allows Edge users to purchase gift cards using cryptocurrency. The integration consists of:

1. Gift Card Market - Browse available brands
2. Gift Card Purchase - Select denomination and pay with crypto
3. Gift Card List - View purchased cards with voucher codes
4. Order Polling - Background service to detect completed orders

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              UI Layer                                   │
├─────────────────┬─────────────────┬─────────────────────────────────────┤
│ GiftCardMarket  │ GiftCardPurchase│ GiftCardListScene                   │
│ Scene           │ Scene           │ (+ GiftCardDisplayCard)             │
└────────┬────────┴────────┬────────┴──────────────┬──────────────────────┘
         │                 │                       │
         └─────────────────┼───────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        PhazeGiftCardProvider                            │
│  - Brand fetching (market, full details)                                │
│  - Order management (create, status)                                    │
│  - Identity management (user registration)                              │
│  - Cache access via getCache()                                          │
└─────────────────────────┬───────────────────────────────────────────────┘
                          │
         ┌────────────────┼────────────────┐
         │                │                │
         ▼                ▼                ▼
┌─────────────────┐ ┌───────────────┐ ┌────────────────────────────────────┐
│   PhazeApi      │ │ PhazeGiftCard │ │ PhazeGiftCardOrderStore            │
│  (HTTP calls)   │ │   Cache       │ │ (Order augments: txid, brand info) │
└─────────────────┘ └───────────────┘ └────────────────────────────────────┘
                          │
         ┌────────────────┼────────────────┐
         │ In-Memory      │ Disk Persistence│
         │ (Map<country,  │ (localDisklet)  │
         │  brands>)      │                 │
         └────────────────┴─────────────────┘

Data Storage

Brand Cache (PhazeGiftCardCache)

Purpose: Cache gift card brand data to minimize API calls and provide offline access.

Storage Location: account.localDisklet (device-local, not synced)

• File: phazeGiftCards/brands-{countryCode}.json

Why localDisklet?

• No need to sync brand cache across devices, this is just mirroring the API data locally.

Cache Structure:

// In-memory (module-level singleton)
Map<countryCode, {
  timestamp: number
  brandsByProductId: Map<productId, PhazeGiftCardBrand>
  fullDetailProductIds: Set<productId>  // Brands with full data
}>

// Disk format
{
  version: 2,
  timestamp: number,
  countryCode: string,
  brands: PhazeGiftCardBrand[],
  fullDetailProductIds: number[]
}

TTL Policy:

• In-memory: 1 hour (triggers API refresh)
• Disk: 24 hours (offline fallback)

Cache Flow:

Startup:
  loadFromDisk() → populate memory cache

UI reads:
  getBrands(countryCode) → returns from memory (fast)
  getBrand(countryCode, productId) → single brand lookup

API refresh:
  getMarketBrands() → setBrands() + saveToDisk()

Order "Augments" (PhazeGiftCardOrderStore)

Purpose: Store local metadata that associates blockchain transactions with gift card orders, and Edge-specific metadata like redeemed date. Also includes brand information like image uri for quick access without API dependencies.

Storage Location: account.disklet (synced across devices)

• File: phazeGiftCardAugments/{orderId}.json

Why synced disklet?

• User may purchase on one device, view on another
• Transaction metadata must persist

Augment Data:

{
  walletId: string      // Wallet that sent payment
  tokenId?: string      // Token used (null for native)
  txid: string          // Blockchain transaction ID
  brandName: string     // For display before API responds
  brandImage: string    // For display before API responds
  fiatAmount: number    // Purchase amount
  fiatCurrency: string  // Currency code
  redeemedDate?: string // ISO date when marked redeemed
}

User Identities

Storage Location: account.disklet (synced)

• File: phaze-identity-{uuid}.json

Contents: Phaze user registration data including userApiKey

Multiple Identities: There should typically only be one identity in most cases. An edge case that can occur from multi-device usage before sync completes. Handled as follows:

• Ordering: Uses first identity found (new orders go to active identity)
• Viewing orders: Aggregates all identities via getAllOrdersFromAllIdentities()
• Polling: Iterates all identities to ensure voucher updates for all orders

API Integration

Brand Fetching Strategy

1. Market Display (getMarketBrands):

   • Fetches minimal fields for fast loading
   • Stores in cache, persists to disk

2. Full Details (getBrandDetails):

   • Fetches complete data when user taps a brand
   • Stores with fullDetailProductIds flag
   • Prevents re-fetching on subsequent visits

3. Background Prefetch:

   • Market scene fetches full details in background
   • Purchase scene has data ready immediately

Order Status Flow

1. Order Creation:

   • Provider creates order with Phaze API
   • Returns quote with payment address

2. Payment Broadcast:

   • Edge wallet broadcasts transaction
   • saveOrderAugment() persists txid + brand info

3. Voucher Polling:

   • PhazeOrderPollingService polls for vouchers on open orders (redemption link + code)
   • Updates tx.savedAction with redemption info, when available

4. List Scene Display:

   • Merges API orders with local augments
   • Shows pending cards (with txid, no voucher)
   • Shows active/redeemable cards (with voucher containing redemption link + code)
   • Shows redeemed cards (marked by user)

Scene Responsibilities

GiftCardListScene

• Displays user's purchased cards
• Initial load from module-level cache
• Polls API for updates when focused
• Separates active vs redeemed cards

GiftCardMarketScene

• Displays available brands
• Initial load from disk/memory cache
• API refresh on mount (parallel with cache load)
• Background fetch of full brand details

GiftCardPurchaseScene

• Shows brand details and denomination picker
• Uses useBrand hook for lazy detail loading
• Creates order and handles payment flow

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Requirements

If you have made any visual changes to the GUI. Make sure you have:

• Tested on iOS device
• Tested on Android device
• Tested on small-screen device (iPod Touch)
• Tested on large-screen device (tablet)

---

Note

Introduces a full gift card experience powered by Phaze, including browsing, purchasing, and managing cards.

• New scenes: GiftCardMarketScene, GiftCardPurchaseScene, GiftCardListScene; wired into navigation and Home “Spend” entry
• Transaction integration: persists giftCard savedAction on send; displays details via GiftCardDetailsCard in TransactionDetailsScene
• New UI building blocks: brand tiles/cards, region buttons, dropdown/pill buttons, icons; improved SceneContainer and SceneWrapper dock handling
• Modals for amount selection, brand search, menus; enhanced WebViewModal (supports HTML and external links)
• Country/state selection flow extended (skipStateProvince), ramp scenes updated to use unified region UI
• Added react-native-render-html dependency (Podfile + package.json); multiple snapshot updates
• Misc cleanup: logging tweaks, layout/padding fixes, KYC/Swap/Stake scenes adjusted to new container patterns

^{Written by Cursor Bugbot for commit 4c8d85e. This will update automatically on new commits. Configure here.}

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1212121528919258

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[swansontec]

First half.

[swansontec]

I feel like this goes in a future commit? Not a big deal, just a tiny optional cleanup.

[Jon-edge]

I can reorg after approval

[swansontec]

Please use Tan Stack or useAsyncValue

[swansontec]

Only one question.

[swansontec]

Wait, doesn't biggystring know how to handle 1e1 formatted numbers now? If not, could something simpler like .toFixed be used?

[cursor]

Brand cache flag not reset when country changes

The module-level hasFetchedBrands variable is only reset in clearOrderCache() when the account changes, but not when countryCode changes. Since brands are country-specific and loadOrdersFromApi fetches brands based on countryCode, changing countries without resetting this flag causes brands for the new country to not be fetched. The useFocusEffect callback reads !hasFetchedBrands to determine includeBrands, so if brands were previously fetched for another country, they won't be refetched for the new one. This results in brandLookup returning undefined for the new country's product images.

Additional Locations (1)

• src/components/scenes/GiftCardListScene.tsx#L202-L209