---

name: quicknode-local-dev-loop description: 'Create a deterministic local QuickNode development loop with transport fixtures, base-URL injection, redacted recordings, and an opt-in read-only sandbox check. Use when developing SDK, RPC, Stream, or Webhook integrations without consuming live credits on every test. Trigger with: "develop against QuickNode locally", "mock QuickNode", "test a QuickNode adapter offline".' allowed-tools: Read, Grep, Write, Edit, Bash(npm:*) version: 2.0.0 argument-hint: '[adapter-and-test-command]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• quicknode
• local-development
• testing
• fixtures compatibility: 'SDK base URL overrides are for local, staging, and approved sandbox boundaries'

---

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

Resources

• Local-loop evidence and source notes
• SDK configuration
• QuickNode API overview