QuickNode Deterministic Local Loop
Overview
Develop against an injectable transport by default. Local tests should model QuickNode protocol contracts without a live token, then use one explicit sandbox read to catch integration drift.
Prerequisites
- Existing QuickNode or JSON-RPC adapter
- Repository test runner and fixture convention
- Optional non-production, read-only credential in a local secret manager
Instructions
Step 1: Locate the boundary
Use Read and Grep to find direct endpoint calls, SDK constructors, global environment reads, retries, timers, and response parsing. Choose one adapter seam for injection.
Step 2: Define fixture contracts
Use Write or Edit to add success, HTTP error, JSON-RPC error, timeout, rate limit, malformed response, and pagination fixtures. Preserve request IDs and nested causes.
Step 3: Inject transport and time
Pass the transport, base URL, clock, and sleeper into the adapter. Use documented SDK base URL overrides only for a local stub or approved staging endpoint.
Step 4: Sanitize recordings
If a real response becomes a fixture, retain only necessary fields and replace endpoint URLs, tokens, API keys, addresses, and business payloads. Add a leak assertion to the fixture test.
Step 5: Run fast tests
Use Bash(npm:*) to run the repository's pinned unit and contract commands. Keep network disabled in the default lane and make accidental outbound access fail.
Step 6: Opt into one live read
Gate a sandbox read behind an explicit variable or command. Verify chain identity and shape, cap timeout and calls, and skip cleanly when the opt-in credential is absent locally.
Tool Discipline
Use Read/Grep for adapter discovery, Write/Edit for injection and fixtures, and Bash(npm:*) for repository-defined tests. Do not use production endpoints, funded signers, or live writes.
Output
- Injectable QuickNode transport boundary
- Sanitized deterministic fixtures
- Fast offline test command
- Explicit sandbox-read contract
Examples
An SDK adapter receives a stub base URL and fake clock. Retry tests advance virtual time, while a separate opt-in command performs one authenticated chain-ID read.
Error Handling
| Failure | Response |
|---|---|
| Unit test reaches the network | Block outbound access and fix the adapter seam |
| Fixture contains a token | Remove it, rotate if real, and add a regression assertion |
| Retry test sleeps in real time | Inject clock and sleeper |
| Sandbox differs from production | Document the gap and cover it in protected CI |