fix(ui): recover pool global state the bulk read didn't carry

Moving pool state to a single accountInformation read on the registry left two
gaps where a pool the bulk request missed stayed missed.

`processPoolData` fell back on the presence of the entry, not on what it held. A
pool whose state came back partial decodes to `{}`, which is truthy, so it kept
the empty entry and returned no lastPayout - which the Status column renders as
"Payouts stopped".

`algodVer` lost its fallback entirely. It came off LocalPoolInfo, and
StakingPoolInfo now reads it only from the bulk map; the per-pool read inside the
metrics query keeps lastPayout and discards the algodVer it fetched. Any pool the
map lacks reported its node version as "--" for the rest of the session.

Both now gate on `isPoolGlobalStateComplete`. It tests lastPayout rather than the
field being displayed, because lastPayout is written when the pool is created -
stakingPool.algo.ts sets it to the creation round as the first epoch's baseline -
so every pool has one and its absence can only mean an incomplete read. Gating on
algodVer instead would have been wrong: it is only written once the node daemon
reports in, and 88 of MainNet's 283 pools legitimately have none, so keying on it
would re-read a third of all pools on every visit and still show "--".

The 1020 fixture claimed a missing lastPayout stood for "a pool that has never
paid out", which the contract does not do. It now models the case that does
occur - a pool whose daemon has never reported, so no algodVer - and the tests
around it cover the fallback firing on an incomplete entry and staying put on a
complete one.

Author: pbennett

ui/src/api/contracts.spec.ts

@@ -1,5 +1,5 @@
 import { HttpResponse, http } from 'msw'
-import { fetchPoolGlobalStates, processPoolData } from '@/api/contracts'
+import { fetchPoolGlobalStates, isPoolGlobalStateComplete, processPoolData } from '@/api/contracts'
 import { LocalPoolInfo } from '@/interfaces/validator'
 import {
   LAST_ROUND,
@@ -48,8 +48,8 @@ describe('fetchPoolGlobalStates', () => {
       lastPayout: 1000n,
       algodVer: '3.23.1 rel/stable [34171a94] : v0.8.2 [c58270f]',
     })
-    // A pool that has never paid out simply has no lastPayout key
-    expect(states.get(1020n)?.lastPayout).toBeUndefined()
+    // A pool whose node daemon has never reported has no algodVer, but still has lastPayout
+    expect(states.get(1020n)).toEqual({ lastPayout: 1080n })
   })
 
   it('warns and returns what it got when algod truncates the created app list', async () => {
@@ -109,10 +109,38 @@ describe('processPoolData', () => {
     expect(paths).toContain('/v2/applications/1011')
   })
 
-  it('leaves lastPayout undefined for a pool that has never paid out', async () => {
+  it('recovers a pool whose bulk entry came back without lastPayout', async () => {
+    const paths = trackRequests()
+
+    // Truthy, so a presence check would accept it and leave lastPayout undefined - which the
+    // Status column renders as "payouts stopped"
     const poolData = await processPoolData(poolFixture(1020n), { algodVer: '3.23.1' })
 
-    expect(poolData.lastPayout).toBeUndefined()
+    expect(poolData.lastPayout).toBe(1080n)
+    expect(paths).toContain('/v2/applications/1020')
+  })
+
+  it('does not re-read a complete entry that has no algodVer', async () => {
+    const paths = trackRequests()
+
+    const poolData = await processPoolData(poolFixture(1020n), { lastPayout: 1080n })
+
+    expect(poolData.lastPayout).toBe(1080n)
     expect(poolData.balance).toBe(AVAILABLE_BALANCE)
+    expect(paths.some((path) => path.startsWith('/v2/applications/'))).toBe(false)
+  })
+})
+
+describe('isPoolGlobalStateComplete', () => {
+  it('accepts an entry carrying lastPayout, with or without algodVer', () => {
+    expect(isPoolGlobalStateComplete({ lastPayout: 1000n })).toBe(true)
+    expect(isPoolGlobalStateComplete({ lastPayout: 0n, algodVer: '3.23.1' })).toBe(true)
+  })
+
+  it('rejects a missing or partially decoded entry', () => {
+    expect(isPoolGlobalStateComplete(undefined)).toBe(false)
+    expect(isPoolGlobalStateComplete({})).toBe(false)
+    // algodVer alone is not enough - lastPayout is what every pool is guaranteed to have
+    expect(isPoolGlobalStateComplete({ algodVer: '3.23.1' })).toBe(false)
   })
 })

ui/src/api/contracts.ts

@@ -179,6 +179,24 @@ function decodePoolGlobalState(globalState: algosdk.modelsv2.TealKeyValue[] = []
   return state
 }
 
+/**
+ * Whether a pool's global state was read completely.
+ *
+ * `lastPayout` is written when the pool is created - `stakingPool.algo.ts` sets it to the
+ * creation round to establish the first epoch's baseline - so every pool has it, and all 283
+ * on MainNet do. Its absence therefore means the read didn't carry this pool's state, not that
+ * the pool is new, and the caller should recover it with a per-pool request.
+ *
+ * `algodVer` is deliberately not part of this test: it is only written once the node daemon
+ * reports in, so a pool can legitimately lack it (88 of those 283 do) and re-reading won't
+ * produce one.
+ */
+export function isPoolGlobalStateComplete(
+  state: PoolGlobalState | undefined,
+): state is PoolGlobalState {
+  return state?.lastPayout !== undefined
+}
+
 /**
  * Every staking pool's global state in a single request.
  *
@@ -235,8 +253,9 @@ export function createBaseValidator({
 }
 
 /**
- * @param globalState - the pool's entry from {@link fetchPoolGlobalStates}. Omitted only when
- *   the bulk read didn't carry this pool, which costs one request to recover.
+ * @param globalState - the pool's entry from {@link fetchPoolGlobalStates}. Absent or
+ *   incomplete only when the bulk read didn't carry this pool, which costs one request to
+ *   recover.
  */
 export async function processPoolData(
   pool: LocalPoolInfo,
@@ -247,7 +266,10 @@ export async function processPoolData(
   // Define the promises for the async operations
   const balancePromise = fetchAccountBalance(poolAddress.toString(), true)
 
-  const globalStatePromise = globalState
+  // Tested on the field rather than on the entry: a pool whose state came back partial decodes
+  // to `{}`, which is truthy, and would otherwise skip the fallback and surface as a missing
+  // lastPayout - which the Status column renders as "payouts stopped".
+  const globalStatePromise = isPoolGlobalStateComplete(globalState)
     ? Promise.resolve(globalState)
     : fetchPoolGlobalState(pool.poolAppId)
 

ui/src/api/queries.ts

@@ -8,6 +8,7 @@ import {
   fetchAllValidatorData,
   fetchMbrAmounts,
   fetchPoolApy,
+  fetchPoolGlobalState,
   fetchPoolGlobalStates,
   fetchProtocolConstraints,
   fetchStakedInfoForPool,
@@ -155,6 +156,21 @@ export const poolGlobalStatesQueryOptions = queryOptions({
   refetchOnWindowFocus: false,
 })
 
+/**
+ * One pool's global state, for recovering a pool the bulk read above didn't carry - algod caps
+ * the resources it returns per account, and the request can fail outright. Callers gate this on
+ * `isPoolGlobalStateComplete`, so on the normal path it never runs.
+ */
+export const poolGlobalStateQueryOptions = (poolAppId: bigint) =>
+  queryOptions({
+    queryKey: ['pool-global-state', String(poolAppId)],
+    queryFn: () => fetchPoolGlobalState(poolAppId),
+    enabled: !!poolAppId,
+    staleTime: METRICS_STALE_TIME,
+    refetchInterval: POOL_GLOBAL_STATES_REFETCH_INTERVAL,
+    refetchOnWindowFocus: false,
+  })
+
 const NO_POOL_GLOBAL_STATES: ReadonlyMap<bigint, PoolGlobalState> = new Map()
 
 export interface ValidatorMetricsInput {

ui/src/components/ValidatorDetails/StakingPoolInfo.tsx

@@ -1,7 +1,12 @@
 import { useQuery } from '@tanstack/react-query'
 import { ProgressBar } from '@tremor/react'
 import { Copy } from 'lucide-react'
-import { nfdLookupQueryOptions, poolGlobalStatesQueryOptions } from '@/api/queries'
+import { isPoolGlobalStateComplete } from '@/api/contracts'
+import {
+  nfdLookupQueryOptions,
+  poolGlobalStateQueryOptions,
+  poolGlobalStatesQueryOptions,
+} from '@/api/queries'
 import { AlgoDisplayAmount } from '@/components/AlgoDisplayAmount'
 import { Loading } from '@/components/Loading'
 import { NfdDisplay } from '@/components/NfdDisplay'
@@ -38,9 +43,21 @@ export function StakingPoolInfo({
   // Not stored in the validator box. Comes from the same bulk read of every pool's global
   // state that the dashboard's metrics use, so getting here is normally a cache hit.
   const poolGlobalStatesQuery = useQuery(poolGlobalStatesQueryOptions)
-  const algodVersion = poolInfo
-    ? poolGlobalStatesQuery.data?.get(poolInfo.poolAppId)?.algodVer
-    : undefined
+  const bulkPoolState = poolInfo ? poolGlobalStatesQuery.data?.get(poolInfo.poolAppId) : undefined
+
+  // The bulk read can come back without this pool, and can fail outright. Recover just this one
+  // rather than reporting the node as version "--" for the rest of the session. Gated on
+  // lastPayout, not on algodVer: a pool whose daemon has never reported has no algodVer to find,
+  // and re-reading it every time would put back the per-pool request the bulk read removed.
+  const poolStateIncomplete =
+    !!poolInfo && !poolGlobalStatesQuery.isPending && !isPoolGlobalStateComplete(bulkPoolState)
+
+  const poolGlobalStateQuery = useQuery({
+    ...poolGlobalStateQueryOptions(poolInfo?.poolAppId ?? 0n),
+    enabled: poolStateIncomplete,
+  })
+
+  const algodVersion = (poolStateIncomplete ? poolGlobalStateQuery.data : bulkPoolState)?.algodVer
 
   const numPools = validator.state.numPools
   const maxStakePerPool = calculateMaxAlgoPerPool(validator, constraints)

ui/src/utils/tests/fixtures/applications.ts

@@ -41,6 +41,7 @@ function stakingPool(appId: number, globalState: TealKeyValue[]): Application {
 export const appFixtures: FixtureData = {
   '1010': stakingPool(1010, [bytesValue('algodVer', ALGOD_VERSION), uintValue('lastPayout', 1000)]),
   '1011': stakingPool(1011, [bytesValue('algodVer', ALGOD_VERSION), uintValue('lastPayout', 1050)]),
-  // No lastPayout: stands in for a pool that has never paid out
-  '1020': stakingPool(1020, [bytesValue('algodVer', ALGOD_VERSION)]),
+  // No algodVer: the node daemon has never reported one. Every pool has lastPayout from
+  // creation, so this - not a missing lastPayout - is what a never-updated pool looks like.
+  '1020': stakingPool(1020, [uintValue('lastPayout', 1080)]),
 }