Reliability & Determinism Playbook
7/7/2025 · 5 min
So what?
Canonical patterns: deterministic tests, RPC rotation, latency trimming, CI flake prevention.
Replaces repeated descriptions across testing, payment portal, and RPC posts.
1. Deterministic Web3 test layering
- Fork: probe & rank RPCs → pick fastest healthy; abort loud if fork fails.
- Funding: impersonate + approvals + transfers; idempotent + logged.
- Wallet: stub provider object (predictable
request, event stubs) instead of brittle extension automation. - Intercepts: only stability-critical calls (balance, allowance) not the entire network.
- Unit isolation: pure logic & branching via Jest + MSW; UI narrative via Cypress.
2. Flake taxonomy
| Cause | Cure |
|---|---|
| Stalled RPC | Pre-run latency probe + cache |
| Nonce races | Serialized funding orchestration |
| Missing wallet | Deterministic stub; treat absence as branch |
| Late injection | Short retry loop then guidance toast |
3. RPC reliability
Transparent proxy rotates to next fastest on failure. Principle: user never pays retry cost.
4. Performance heuristics
- Collapse duplicate network detection.
- Hardcode invariant token metadata (trim 6–7 calls).
- Optimistic static shell + deferred dynamic state.
- Prune unused assets before refactoring.
5. CI harness
Bounded poll for chain readiness + serialized funding removes “nonce too low” noise; logs narrate setup story.
6. Observability
Log: fork source, latency stats, funding saga, rotation events, request count delta pre/post optimization.
7. Portable checklist
□ Probe & rank RPCs
□ Deterministic fork or abort
□ Idempotent funding run
□ Stub provider (mobile aware)
□ Minimal selective intercepts
□ Rotation proxy in prod path
□ Optimistic static render
□ Flake taxonomy logDeterminism happens on purpose; this playbook centralizes the knobs.