Users-index resolution stalls startup (~45s) when IPNS+Base-RPC are both down; no cache/server-assist

[ehsan6sha]

Summary

At app startup, resolving the users-index (the record mapping a user → their data-root CID) repeatedly fails via IPNS (exhausted) and the Base chain RPC (https://mainnet.base.org transport error), which blocks all metadata restores and any live bucket listing for ~45s before it self-recovers. We want this to degrade gracefully (and ideally avoid re-resolving on every startup).

This is pre-existing infrastructure/resilience, not related to the v8 bucket migration.

Observed (on-device, 2026-06-08, app v1.11.4, account ehsan6sha)

• 17× users-index resolution failed: IPNS exhausted; chain: users-index resolution failed: chain RPC transport: error sending request for url (https://mainnet.base.org/) over ~45s at startup.
• During that window, every metadata forest failed to load: dump-metadata, fula-metadata, nft-metadata, website-metadata, tag-metadata, folder-watch, cloud-sync-mappings.
• A live images-v8 bucket listing retried 4× over ~49s.
• Recovered ~T+45s (CloudSyncMapping: Downloaded 822 mappings from cloud).
• The frozen legacy-listing cache was immune (served from local cache, no network) — only live resolution was blocked.

Question that prompted this

"Why does it fall through to IPNS/chain when the master/server is up — isn't the order server → IPNS → chain?"

Clarification from the code: the users-index is decentralized by design — an on-chain anchor + IPNS lookup (lib/core/services/fula_api_service.dart:35). The master/gateway serves data, not the index, so there is no server-served index to try first. The fast path ("warm-cache": local block cache + public gateway, :31-33) is about data; the index resolution itself is IPNS + chain. So a transient IPNS+RPC outage stalls startup even with the master up.

Shallow findings (app side)

• Cold-start users-index resolution is configured + active (fula_api_service.dart:48-78):
  • kUsersIndexChainRpcUrl = 'https://mainnet.base.org'
  • kUsersIndexAnchorAddress = '0x00fB6AD1B42Fb37a0Ac7C2977fC1fa4462C36Af9'
  • kUsersIndexIpnsName = 'k51qzi5...'
  • IPNS gateways empty by design → the SDK owns selection (registry_resolver::default_ipns_gateway_urls, leads with ipfs.io).
• object_cache_service.dart:18-19 already acknowledges: "The IPNS chain RPC backing the forest's users-index resolution is unreachable or slow (e.g. mainnet.base.org outages)."
• The actual resolution order + caching lives in the SDK's registry_resolver (fula-client, Rust) — not in this repo.

Hypotheses / directions (tackle later)

1. Cache the resolved users-index with a sensible TTL so a transient IPNS/chain outage doesn't re-block every startup (the index changes rarely).
2. Server-assisted index path: let the gateway cache/serve the latest users-index so the decentralized IPNS/chain lookup is only needed when the master is down (true cold-start).
3. More reliable Base RPC than public mainnet.base.org (it is rate-limited/flaky); make it configurable / add fallbacks.
4. App-side: throttle/defer the startup metadata-restore storm (shelf/tags/NFT/website/folders/mappings all fire at once and all retry on failure), so a transient outage degrades gracefully instead of a ~45s stall; show cached/stale immediately while resolving in the background.

Scope

• Pre-existing infra/resilience; not a v8-migration regression.
• Core fix is SDK (fula-client registry_resolver) + gateway (functionland/fula-api, relates to the users-index work, e.g. fula-api#26). App-side mitigation (throttle restore storm + show cached) belongs here.

Filed from an on-device E2E while validating the v8 migration.