Skip to content

WALLET-NETWORK-SYNC-IMPLEMENTATION.md

Latest commit

 

History

History
222 lines (157 loc) · 6.84 KB

WALLET-NETWORK-SYNC-IMPLEMENTATION.md

File metadata and controls

222 lines (157 loc) · 6.84 KB
Raw

Wallet Network Sync Implementation

Overview

Successfully implemented wallet network sync detection to prevent fund payments from being built for the wrong network when users change networks in their wallet extensions after connecting.

What Was Implemented

1. Core Type Updates (packages/core/src/types/index.ts)

  • Added walletNetwork field to WalletState interface
  • This tracks the actual network state from the wallet extension (separate from provider network)

2. Enhanced useWallet Hook (packages/core/src/hooks/useWallet.ts)

New Features:

  • refreshWalletNetwork(): Async function to query and refresh the wallet's current network state
  • isNetworkMismatch: Computed boolean that returns true when provider network doesn't match wallet network
  • walletNetwork: New state field exposing the wallet's actual network

Implementation Details:

  • Modified connectFreighter() to capture and return wallet network during connection
  • Added getFreighterNetwork() helper that maps network passphrases to network identifiers
  • refreshWalletNetwork() safely handles errors and won't throw, just sets error state
  • isNetworkMismatch automatically computes based on wallet.network vs wallet.walletNetwork

3. Payment Protection (packages/core/src/hooks/useSendPayment.ts)

Network Mismatch Check:

if (wallet.walletNetwork && wallet.network !== wallet.walletNetwork) {
  throw new Error(
    `Network mismatch: Provider is on ${wallet.network} but wallet is on ${wallet.walletNetwork}. ` +
      `Switch your wallet to ${wallet.network} or call refreshWalletNetwork() to update.`
  )
}
  • Prevents transaction submission when networks don't match
  • Provides clear error message with actionable guidance
  • Only checks if walletNetwork is set (backward compatible with existing state)

4. Updated Provider Context (packages/core/src/context/StellarProvider.tsx)

  • Updated DEFAULT_WALLET to include walletNetwork: null
  • Ensures all new wallet connections start with proper state

5. Enhanced Wallet Demo (packages/demo/app/demo/wallet/page.tsx)

New Display Features:

  • Shows both "Provider Network" and "Wallet Network" separately
  • Color-coded network status (green for match, red for mismatch)
  • Visual "Network mismatch!" warning when networks don't align
  • "Refresh Network" button to manually check wallet network state

Updated Hook Usage:

const {
  connect,
  disconnect,
  connected,
  address,
  connecting,
  error,
  network: walletProviderNetwork,
  walletNetwork,
  refreshWalletNetwork,
  isNetworkMismatch,
} = useWallet()

const { network: providerNetwork } = useNetwork()

6. Comprehensive Tests

useWallet.test.tsx - 6 test suites covering:

  • ✅ Wallet network capture on connection
  • ✅ Network mismatch detection on connection attempt
  • ✅ Manual wallet network refresh
  • ✅ Network state updates after refresh
  • ✅ No-op when wallet not connected
  • ✅ Error handling during refresh
  • ✅ isNetworkMismatch computation (matching & mismatched cases)
  • ✅ State cleanup on disconnect

useSendPayment.test.tsx - 5 test suites covering:

  • ✅ Error when wallet not connected
  • ✅ Error when networks mismatch
  • ✅ Success when networks match
  • ✅ Success with null walletNetwork (legacy state)
  • ✅ Helpful error messages for network mismatch

All tests passing: 28 tests total across 3 test files

API Changes

useWallet Hook - New Return Values

{
  // Existing fields...
  walletNetwork: StellarNetwork | null // NEW: Actual wallet network
  refreshWalletNetwork: () => Promise<void> // NEW: Refresh wallet network
  isNetworkMismatch: boolean // NEW: Network mismatch indicator
}

Usage Example

const { connect, walletNetwork, refreshWalletNetwork, isNetworkMismatch } = useWallet()

// Connect wallet
await connect("freighter")

// Later, user might change network in Freighter
// Developer can refresh to detect this
await refreshWalletNetwork()

// Check for mismatch
if (isNetworkMismatch) {
  alert("Please switch your wallet to the correct network!")
}

Acceptance Criteria Status

✅ Wallet network state can be refreshed after connection

  • refreshWalletNetwork() function implemented and tested

✅ Mismatched wallet/provider network is visible to developers

  • isNetworkMismatch boolean exposed
  • walletNetwork field shows actual wallet network
  • Demo page visually indicates mismatch

✅ Payment hooks block unsafe submission on network mismatch

  • useSendPayment checks network before building transaction
  • Clear error message thrown when mismatch detected

✅ Demo page clearly shows network status

  • Displays both Provider Network and Wallet Network
  • Color-coded visual indicators (green/red)
  • "Network mismatch!" warning message
  • Refresh Network button

✅ Tests cover mismatch handling

  • 11 tests specifically for network sync features
  • Tests cover connection, refresh, mismatch detection, and error scenarios
  • Tests verify payment blocking on mismatch

Technical Notes

Network Detection Approach

Since Freighter doesn't expose network change events, we implemented:

  1. Capture on connection: Store wallet network during initial connection
  2. Manual refresh: refreshWalletNetwork() for polling when needed
  3. Automatic validation: Payment hooks check mismatch before submission

Backward Compatibility

  • walletNetwork can be null for old state or wallets that don't support detection
  • Network mismatch check only runs if walletNetwork is populated
  • Existing integrations work without changes

Security

  • Prevents cross-network transaction submission
  • Clear error messages guide users to fix misconfiguration
  • No automatic network switching (user must explicitly fix mismatch)

Files Modified

  1. packages/core/src/types/index.ts
  2. packages/core/src/context/StellarProvider.tsx
  3. packages/core/src/hooks/useWallet.ts
  4. packages/core/src/hooks/useSendPayment.ts
  5. packages/demo/app/demo/wallet/page.tsx

Files Created

  1. packages/core/src/hooks/useWallet.test.tsx (268 lines)
  2. packages/core/src/hooks/useSendPayment.test.tsx (195 lines)

Build & Test Status

  • ✅ TypeScript compilation successful
  • ✅ All tests passing (28/28)
  • ✅ Build artifacts generated successfully
  • ✅ No linting errors

Git Commit

Branch: fix/wallet-network-sync
Commit: fix(wallet): sync wallet network state
Files changed: 8 files changed, 655 insertions(+), 37 deletions(-)

Next Steps for Users

  1. The changes are committed to the fix/wallet-network-sync branch
  2. Push the branch: git push -u origin fix/wallet-network-sync
  3. Create a PR to merge into main
  4. Demo the feature by:
    • Connecting Freighter wallet
    • Changing network in Freighter extension
    • Clicking "Refresh Network" button
    • Observing the network mismatch warning