QuickNode Production Reference Architecture
Overview
Separate provisioning and account governance from chain traffic, and separate synchronous reads/writes from asynchronous event ingestion. Give every credential, endpoint, cursor, queue, and recovery path one owner.
Prerequisites
- Service inventory and trust boundaries
- Chain/network, method, history, write, and event requirements
- SLO, recovery, compliance, and cost constraints
Instructions
Step 1: Map control and data planes
Use Read and Grep to identify Admin API, unified SDK, qn, RPC/WSS endpoints, Streams, Webhooks, SQL Explorer, and KV Store usage. Mark credentials and mutation authority.
Step 2: Isolate credentials
Use separate API keys for control-plane automation and endpoint tokens for data-plane RPC. Separate applications and environments with multiple tokens; keep signing keys outside QuickNode clients.
Step 3: Split synchronous workloads
Route bounded reads through chain-specific adapters. Put transaction intent, signing, broadcast identity, confirmation, and reorg reconciliation behind a dedicated write service.
Step 4: Build asynchronous ingestion
Terminate Streams or Webhooks at an authenticated receiver, acknowledge after durable enqueue, and process idempotently. Persist a replay cursor and send large historical pipelines to an appropriate durable destination.
Step 5: Define data capability
Use Write or Edit to record chain, network, API family, add-ons, archive/pruning semantics, pagination, and block consistency. Do not assume feature parity across chains.
Step 6: Close observability and recovery
Correlate application requests with endpoint metrics and sanitized request IDs. Define endpoint/token cutover, chain-provider degradation, event replay, transaction reconciliation, and budget alerts.
Tool Discipline
Use Read and Grep for topology discovery and Write/Edit for architecture records, interfaces, and tests. This design workflow performs no account, endpoint, Stream, or production mutation.
Output
- Trust-boundary and credential map
- Synchronous read/write interfaces
- Durable event-ingestion and replay path
- Observability, cost, and recovery contracts
Examples
An API serves cached finalized reads, a signer service owns transaction state, and a Stream receiver writes authenticated batches to a queue. Admin automation has no signer or endpoint token.
Error Handling
| Failure | Response |
|---|---|
| One key spans control and data planes | Split identity and rotate through overlap |
| Event receiver performs business work inline | Insert a durable queue before acknowledgement |
| Chain capability is assumed | Bind the interface to a verified chain/network contract |
| Provider timeout can duplicate a write | Persist broadcast identity and reconcile before retry |