Merge pull request #121 from primev/leaderboard-miles-update

passandscore · web-flow · commit e99fc222ab9a · 2026-04-15T14:55:49.000-03:00
fix(miles): keep AppHeader and leaderboard miles in sync after settlement
diff --git a/src/app/api/fuul/leaderboard/route.ts b/src/app/api/fuul/leaderboard/route.ts
@@ -88,9 +88,11 @@ export async function GET(request: NextRequest) {
     const limit = Math.min(Math.max(parseInt(searchParams.get("limit") || "15", 10), 1), 100)
     const page = parseInt(searchParams.get("page") || "0", 10)
     const sort = searchParams.get("sort") || ""
+    const forceRefresh = searchParams.get("refresh") === "1"
 
-    // Refresh cache if stale or missing
-    const isStale = !rawCache || Date.now() - rawCache.timestamp >= LEADERBOARD_CACHE_STALE_TIME
+    // Refresh cache if stale, missing, or explicitly requested
+    const isStale =
+      forceRefresh || !rawCache || Date.now() - rawCache.timestamp >= LEADERBOARD_CACHE_STALE_TIME
     if (isStale) {
       const allResults: FuulLeaderboardEntry[] = []
       let currentPage = 1
diff --git a/src/app/api/fuul/payouts/route.ts b/src/app/api/fuul/payouts/route.ts
@@ -22,7 +22,11 @@ export async function GET(request: NextRequest) {
       )
     }
 
-    const url = `${FUUL_TOTALS_URL}/${encodeURIComponent(address)}`
+    // Fuul stores/keys addresses in lowercase (their leaderboard endpoint
+    // returns lowercase wallets). A checksummed mixed-case lookup against
+    // /payouts/totals/{address} 404s even when the wallet has credits, so
+    // always normalize before hitting Fuul.
+    const url = `${FUUL_TOTALS_URL}/${encodeURIComponent(address.toLowerCase())}`
 
     const response = await fetch(url, {
       method: "GET",
diff --git a/src/components/dashboard/LeaderboardTable.tsx b/src/components/dashboard/LeaderboardTable.tsx
@@ -30,6 +30,8 @@ import {
 import { formatCurrency, formatNumber } from "@/lib/utils"
 import { trimWalletAddress } from "@/lib/analytics/services/leaderboard-transform"
 import { FEATURE_FLAGS } from "@/lib/feature-flags"
+import { useFuulMilesLeaderboard } from "@/hooks/use-fuul-miles-leaderboard"
+import { useUserPoints } from "@/hooks/use-user-points"
 import {
   TIER_THRESHOLDS,
   getTierFromVolume,
@@ -98,63 +100,59 @@ export const LeaderboardTable = ({
 
   const [leaderboardMode, setLeaderboardMode] = useState<"volume" | "miles" | "stats">("miles")
 
-  // Single fetch for all Fuul leaderboard data (miles + referral cards)
-  const [milesLeaderboard, setMilesLeaderboard] = useState<
-    { wallet: string; points: number; referrals: number; rank: number }[]
-  >([])
-  const [referralData, setReferralData] = useState<{
+  // Shared Fuul miles leaderboard query. Listens for `refetch-user-miles`
+  // events so that when a swap transitions from pending → processed the
+  // miles tables refresh automatically, and the AppHeader stays in sync.
+  const { data: fuulMilesData, isLoading: isMilesLoading } = useFuulMilesLeaderboard()
+  const milesLeaderboard = useMemo(() => fuulMilesData?.entries ?? [], [fuulMilesData?.entries])
+  const totalParticipants = fuulMilesData?.totalParticipants ?? 0
+  const totalMiles = fuulMilesData?.totalMiles ?? 0
+  const referralData = useMemo<{
     byPoints: ReferralLeaderEntry[]
     byRefs: ReferralLeaderEntry[]
-  } | null>(null)
-  const [isMilesLoading, setIsMilesLoading] = useState(false)
-  // Server-provided totals (covers ALL participants, not just page 1)
-  const [totalParticipants, setTotalParticipants] = useState(0)
-  const [totalMiles, setTotalMiles] = useState(0)
-  useEffect(() => {
-    setIsMilesLoading(true)
-    fetch("/api/fuul/leaderboard?limit=100&page=1&sort=miles")
-      .then((res) => (res.ok ? res.json() : null))
-      .then((json) => {
-        if (!json) return
-        const entries: { wallet: string; points: number; referrals: number; rank: number }[] =
-          json.entries ||
-          json.byPoints?.map((e: ReferralLeaderEntry, i: number) => ({ ...e, rank: i + 1 })) ||
-          []
-        setMilesLeaderboard(entries)
-        // Use server-provided totals (computed from full dataset)
-        if (json.totalParticipants != null) setTotalParticipants(json.totalParticipants)
-        else setTotalParticipants(entries.length)
-        if (json.totalMiles != null) setTotalMiles(json.totalMiles)
-        else
-          setTotalMiles(entries.reduce((sum: number, e: { points: number }) => sum + e.points, 0))
-        // Derive referral card data from the same dataset
-        const byPoints = [...entries]
-          .sort((a, b) => b.points - a.points)
-          .slice(0, 10)
-          .map((e, i) => ({ ...e, rank: i + 1 }))
-        const byRefs = [...entries]
-          .sort((a, b) => b.referrals - a.referrals)
-          .slice(0, 10)
-          .map((e, i) => ({ ...e, rank: i + 1 }))
-        setReferralData({ byPoints, byRefs })
-      })
-      .catch(() => {})
-      .finally(() => setIsMilesLoading(false))
-  }, [])
+  } | null>(() => {
+    if (!milesLeaderboard.length) return null
+    const byPoints = [...milesLeaderboard]
+      .sort((a, b) => b.points - a.points)
+      .slice(0, 10)
+      .map((e, i) => ({ ...e, rank: i + 1 }))
+    const byRefs = [...milesLeaderboard]
+      .sort((a, b) => b.referrals - a.referrals)
+      .slice(0, 10)
+      .map((e, i) => ({ ...e, rank: i + 1 }))
+    return { byPoints, byRefs }
+  }, [milesLeaderboard])
+
+  // AppHeader badge value (per-user Fuul totals — updates faster than the
+  // leaderboard dataset). When the leaderboard hasn't caught up yet we
+  // surface the header value as the floor for the connected user's row
+  // so the leaderboard never shows a smaller number than the badge.
+  const { points: headerPoints } = useUserPoints()
 
   // Find user in miles leaderboard
   const userMilesEntry = useMemo(() => {
     if (!userAddr || !milesLeaderboard.length) return null
     const trimmed = trimWalletAddress(userAddr.toLowerCase())
-    return milesLeaderboard.find((e) => e.wallet === trimmed) ?? null
-  }, [userAddr, milesLeaderboard])
+    const found = milesLeaderboard.find((e) => e.wallet === trimmed) ?? null
+    if (!found) return null
+    if (headerPoints > found.points) {
+      return { ...found, points: headerPoints }
+    }
+    return found
+  }, [userAddr, milesLeaderboard, headerPoints])
 
-  // Wallet-to-miles lookup for volume leaderboard rows
+  // Wallet-to-miles lookup for volume leaderboard rows. Override the
+  // connected user's entry with the AppHeader value when it's higher.
   const milesByWallet = useMemo(() => {
     const map = new Map<string, number>()
     for (const e of milesLeaderboard) map.set(e.wallet, e.points)
+    if (userAddr && headerPoints > 0) {
+      const trimmed = trimWalletAddress(userAddr.toLowerCase())
+      const current = map.get(trimmed) ?? 0
+      if (headerPoints > current) map.set(trimmed, headerPoints)
+    }
     return map
-  }, [milesLeaderboard])
+  }, [milesLeaderboard, userAddr, headerPoints])
 
   // Next rank miles (person above user)
   const nextMilesRankEntry = useMemo(() => {
diff --git a/src/hooks/use-fuul-miles-leaderboard.ts b/src/hooks/use-fuul-miles-leaderboard.ts
@@ -0,0 +1,86 @@
+"use client"
+
+import { useEffect } from "react"
+import { useQuery, useQueryClient } from "@tanstack/react-query"
+import { trimWalletAddress } from "@/lib/analytics/services/leaderboard-transform"
+import { LEADERBOARD_CACHE_STALE_TIME, LEADERBOARD_CACHE_GC_TIME } from "@/lib/constants"
+import { REFETCH_MILES_EVENT } from "@/lib/miles-events"
+
+export interface FuulMilesEntry {
+  wallet: string
+  points: number
+  referrals: number
+  rank: number
+}
+
+export interface FuulMilesLeaderboard {
+  entries: FuulMilesEntry[]
+  totalParticipants: number
+  totalMiles: number
+}
+
+export const FUUL_MILES_LEADERBOARD_QUERY_KEY = ["fuulMilesLeaderboard"] as const
+
+async function fetchFuulMilesLeaderboard(refresh = false): Promise<FuulMilesLeaderboard> {
+  const url = `/api/fuul/leaderboard?limit=100&page=1&sort=miles${refresh ? "&refresh=1" : ""}`
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`Failed to fetch miles leaderboard: ${res.status}`)
+  const json = await res.json()
+  const entries: FuulMilesEntry[] = (json.entries ||
+    json.byPoints?.map((e: FuulMilesEntry, i: number) => ({ ...e, rank: i + 1 })) ||
+    []) as FuulMilesEntry[]
+
+  const totalParticipants =
+    typeof json.totalParticipants === "number" ? json.totalParticipants : entries.length
+  const totalMiles =
+    typeof json.totalMiles === "number"
+      ? json.totalMiles
+      : entries.reduce((sum, e) => sum + e.points, 0)
+
+  return { entries, totalParticipants, totalMiles }
+}
+
+/**
+ * Shared React Query-backed fetch of the Fuul miles leaderboard.
+ * Consumers (LeaderboardTable, AppHeader via useUserPoints) read the same
+ * cache, guaranteeing the connected user's Miles badge matches their
+ * leaderboard row. Listens for `refetch-user-miles` events (fired when a
+ * swap transitions from pending → processed) and refetches with a
+ * server-cache bust so fresh settlement data is reflected immediately.
+ */
+export function useFuulMilesLeaderboard() {
+  const queryClient = useQueryClient()
+
+  const query = useQuery<FuulMilesLeaderboard>({
+    queryKey: FUUL_MILES_LEADERBOARD_QUERY_KEY,
+    queryFn: () => fetchFuulMilesLeaderboard(false),
+    staleTime: LEADERBOARD_CACHE_STALE_TIME,
+    gcTime: LEADERBOARD_CACHE_GC_TIME,
+    refetchOnWindowFocus: false,
+    refetchOnMount: false,
+  })
+
+  useEffect(() => {
+    const handler = () => {
+      queryClient.fetchQuery({
+        queryKey: FUUL_MILES_LEADERBOARD_QUERY_KEY,
+        queryFn: () => fetchFuulMilesLeaderboard(true),
+        staleTime: 0,
+      })
+    }
+    window.addEventListener(REFETCH_MILES_EVENT, handler)
+    return () => window.removeEventListener(REFETCH_MILES_EVENT, handler)
+  }, [queryClient])
+
+  return query
+}
+
+/** Returns the leaderboard entry for the given wallet, or null. */
+export function findUserMilesEntry(
+  data: FuulMilesLeaderboard | undefined,
+  address: string | undefined | null
+): FuulMilesEntry | null {
+  if (!data || !address) return null
+  const trimmed = trimWalletAddress(address.toLowerCase())
+  return data.entries.find((e) => e.wallet === trimmed) ?? null
+}
diff --git a/src/hooks/use-user-points.ts b/src/hooks/use-user-points.ts
@@ -1,23 +1,31 @@
-import { useState, useEffect, useCallback } from "react"
+import { useState, useEffect, useCallback, useRef } from "react"
 import { useAccount } from "wagmi"
+import { REFETCH_MILES_EVENT, refetchMiles } from "@/lib/miles-events"
+import { getPendingSwapHashes, subscribeSwapSubmitted } from "@/lib/swap-events"
 
-const REFETCH_MILES_EVENT = "refetch-user-miles"
+export { REFETCH_MILES_EVENT, refetchMiles }
 
 interface UseUserPointsReturn {
   points: number
   isLoading: boolean
 }
 
-/** Trigger a miles refetch from anywhere (e.g. after a successful swap). */
-export function refetchMiles() {
-  window.dispatchEvent(new Event(REFETCH_MILES_EVENT))
-}
+/** Poll cadence for refreshing miles after a swap submission. */
+const POST_SWAP_POLL_INTERVAL_MS = 10_000
+/** Give up polling after this long if the value still hasn't changed. */
+const POST_SWAP_POLL_BUDGET_MS = 3 * 60 * 1000
 
 export function useUserPoints(): UseUserPointsReturn {
   const { address } = useAccount()
-  const [points, setPoints] = useState(0)
+  const [payoutPoints, setPayoutPoints] = useState(0)
   const [isLoading, setIsLoading] = useState(false)
 
+  // The header reads from /payouts/totals/{address}, the per-user Fuul
+  // endpoint that updates as soon as Fuul indexes the settlement. The
+  // leaderboard data is computed on a slower cadence by Fuul, so we let
+  // the badge update first and the leaderboard table catch up afterward
+  // (both share refetch-user-miles, so they refresh in the same cycle).
+
   const fetchPoints = useCallback((addr: string) => {
     let cancelled = false
     setIsLoading(true)
@@ -27,13 +35,13 @@ export function useUserPoints(): UseUserPointsReturn {
       .then((json) => {
         if (cancelled) return
         if (json?.success && typeof json.totalPoints === "number") {
-          setPoints(json.totalPoints)
+          setPayoutPoints(json.totalPoints)
         } else {
-          setPoints(0)
+          setPayoutPoints(0)
         }
       })
       .catch(() => {
-        if (!cancelled) setPoints(0)
+        if (!cancelled) setPayoutPoints(0)
       })
       .finally(() => {
         if (!cancelled) setIsLoading(false)
@@ -47,7 +55,7 @@ export function useUserPoints(): UseUserPointsReturn {
   // Initial fetch + refetch on address change
   useEffect(() => {
     if (!address) {
-      setPoints(0)
+      setPayoutPoints(0)
       setIsLoading(false)
       return
     }
@@ -62,5 +70,63 @@ export function useUserPoints(): UseUserPointsReturn {
     return () => window.removeEventListener(REFETCH_MILES_EVENT, handler)
   }, [address, fetchPoints])
 
+  // Track the latest points value so the post-swap poller can detect a
+  // change without re-subscribing on every render.
+  const points = payoutPoints
+  const latestPointsRef = useRef(points)
+  useEffect(() => {
+    latestPointsRef.current = points
+  }, [points])
+
+  // Active poll-loop bookkeeping. Settlement (and Fuul indexing of it) can
+  // take ~30s+ after a swap is submitted — well past the single 5s
+  // refetchMiles() that SwapConfirmationModal fires. Without this loop the
+  // header never updates unless the user is on the dashboard (where
+  // useUserSwaps does its own pending→processed detection).
+  const pollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const pollDeadlineRef = useRef<number>(0)
+  const baselineRef = useRef<number>(0)
+
+  const stopPolling = useCallback(() => {
+    if (pollTimerRef.current != null) {
+      clearInterval(pollTimerRef.current)
+      pollTimerRef.current = null
+    }
+  }, [])
+
+  const startPolling = useCallback(() => {
+    // Extend the budget on each new swap submission. Capture the current
+    // points value as the baseline; we stop as soon as it changes.
+    pollDeadlineRef.current = Date.now() + POST_SWAP_POLL_BUDGET_MS
+    baselineRef.current = latestPointsRef.current
+
+    if (pollTimerRef.current != null) return // already polling
+
+    pollTimerRef.current = setInterval(() => {
+      if (Date.now() >= pollDeadlineRef.current) {
+        stopPolling()
+        return
+      }
+      if (latestPointsRef.current !== baselineRef.current) {
+        stopPolling()
+        return
+      }
+      refetchMiles()
+    }, POST_SWAP_POLL_INTERVAL_MS)
+  }, [stopPolling])
+
+  // Watch for swap submissions globally so the header refreshes even if
+  // the user never visits the dashboard. Also resume polling on mount if
+  // sessionStorage shows pending hashes from before this hook mounted.
+  useEffect(() => {
+    if (!address) return
+    if (getPendingSwapHashes().length > 0) startPolling()
+    const unsubscribe = subscribeSwapSubmitted(() => startPolling())
+    return () => {
+      unsubscribe()
+      stopPolling()
+    }
+  }, [address, startPolling, stopPolling])
+
   return { points, isLoading }
 }
diff --git a/src/lib/miles-events.ts b/src/lib/miles-events.ts
@@ -0,0 +1,8 @@
+/** Fired when the user's Fuul miles may have changed (e.g. settlement finalized). */
+export const REFETCH_MILES_EVENT = "refetch-user-miles"
+
+/** Trigger a miles refetch from anywhere (e.g. after a successful swap). */
+export function refetchMiles() {
+  if (typeof window === "undefined") return
+  window.dispatchEvent(new Event(REFETCH_MILES_EVENT))
+}

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,11 @@ export async function GET(request: NextRequest) {`
`22`	`22`	`)`
`23`	`23`	`}`
`24`	`24`
`25`		- const url = `${FUUL_TOTALS_URL}/${encodeURIComponent(address)}`
	`25`	`+ // Fuul stores/keys addresses in lowercase (their leaderboard endpoint`
	`26`	`+ // returns lowercase wallets). A checksummed mixed-case lookup against`
	`27`	`+ // /payouts/totals/{address} 404s even when the wallet has credits, so`
	`28`	`+ // always normalize before hitting Fuul.`
	`29`	+ const url = `${FUUL_TOTALS_URL}/${encodeURIComponent(address.toLowerCase())}`
`26`	`30`
`27`	`31`	`const response = await fetch(url, {`
`28`	`32`	`method: "GET",`