Overview
Treat client, endpoint, token, chain API, and event-pipeline changes as contract migrations. Preserve a parallel read path or replay boundary until the target proves identity, correctness, capacity, and recovery.
Prerequisites
- Current and target SDK, endpoint, chain/network, and product inventory
- Compatibility tests and representative traffic
- Cutover owner, rollback window, and data-reconciliation plan
Authentication
Keep target credentials separate from the current path during the dual run. Endpoint tokens authenticate RPC through a protected URL or x-token header; Admin API inspection uses a distinct x-api-key, while qn uses its authenticated account session. Redact all three from matrices and receipts.
Instructions
Step 1: Build the change matrix
Use Read and Grep to find SDK imports, endpoint URLs, API methods, protocols, chain IDs, archive assumptions, tokens, Stream/Webhook IDs, cursors, and platform targets.
Step 2: Read current contracts
Verify the target SDK platform matrix, product API, chain deprecation, supported protocol, pruning policy, and method response. Do not derive compatibility from an unrelated chain quickstart.
Step 3: Prepare the target
Use Bash(npm:*) for a reviewed pinned SDK update and lockfile change. Use Write or Edit to adapt behind a stable interface, add dual-read comparisons, and preserve old configuration for rollback.
Step 4: Inspect provider resources
Use Bash(qn:*) for read-only current/target endpoint, security, usage, metrics, Stream, and Webhook state. Create or mutate resources only after an explicit operator checkpoint.
Step 5: Canary and reconcile
Compare chain identity, response semantics, latency, errors, credits, transaction status, and event completeness. For event migrations, start from an overlap block and deduplicate by durable event identity.
Step 6: Cut over and retire
Shift traffic gradually, retain the old endpoint/token through the rollback window, then revoke or archive only after evidence and owner approval. Record deprecation and consumer communication.
Tool Discipline
Use Read/Grep for inventory, Write/Edit for adapters and tests, Bash(npm:) for pinned package operations, and Bash(qn:) for read-only resource evidence. Destructive retirement remains approval-gated.
Output
- Current-to-target compatibility matrix
- Tested adapter and dual-run evidence
- Cutover and replay plan
- Rollback receipt and retirement approval
Examples
A service moves from a legacy Core wrapper to the unified SDK for control-plane calls while retaining its chain provider adapter. Dual reads prove equivalence before the old dependency is removed.
Error Handling
| Failure | Response |
|---|---|
| Target runtime cannot load SDK | Stop and revisit the native platform matrix |
| Dual reads differ | Classify semantic, freshness, or chain differences before cutover |
| Events are missing | Resume from the overlap cursor and deduplicate |
| Rollback credential was revoked | Stop rollout and restore a tested recovery identity |