An Alchemy RPC migration changes a production dependency. Inventory standard RPC calls and provider-specific services, validate a replacement with read-only traffic and keep a rollback route until the new path is proven. This is a cutover runbook. For the business case, use the variable-demand pricing forecast; for prerequisites, use the API compatibility checklist.
Inventory dependencies and stored state
List every standard RPC method, SDK feature, indexed endpoint and webhook subscription used by the application. Include archive reads and diagnostic methods that are rarely used but matter during incidents. Record saved event cursors, credentials and in-flight transactions. A new RPC URL alone does not replace proprietary APIs, stored indexes or a subscription with a different payload.
Create sanitized request fixtures
Build fixtures for successful reads, empty results, errors and representative historical queries. Pin comparisons to the same network and block where possible. Include bounded log requests and the block tags used by production features. Record each candidate response and any adapter work needed to preserve the application’s expected field meanings.
Shadow reads without duplicating writes
Send a controlled sample of read-only requests through the candidate and compare data freshness, result shape and errors. Keep transaction submission on the established path during the shadow test. Comparing two latest heads can produce misleading differences; use a common block when checking deterministic results. Confirm rate limits before mirroring a large workload.
Prepare configuration rollout and rollback
Keep endpoint configuration independent from application logic. Roll out the candidate gradually and monitor per-method errors, freshness and response-time percentiles. Define the evidence that triggers rollback and who owns it. Retain the previous configuration for the controlled evaluation period, while handling credentials through the normal secret-management process.
Move submissions with an explicit unknown-result policy
Keep a record of each signed payload and its derived hash before submission. If a timeout occurs, check that hash through the relevant network before creating another transfer. Changing providers does not establish that the original submission failed. Keep a single controlled submission path and preserve nonce or equivalent transaction-state handling in the application.
Reconcile events and retire the old path
Replay event consumers from their stored position using an overlap, deduplicate observations and reconcile derived state. Confirm there are no unresolved in-flight transactions or historical gaps. Compare observed usage with the forecast, document unsupported behavior and rotate retired credentials once the migration has passed its acceptance gates. Check Crypto Chief RPC coverage against the exact migrated networks.
Frequently Asked Questions
Can I replace an Alchemy URL without changing code?
Sometimes standard JSON-RPC calls can use another endpoint with configuration changes. Provider-specific APIs, subscriptions and SDK features may require adapters or a separate migration. Test the actual dependencies.
Why should writes stay out of a shadow test?
Duplicating a production submission path can create ambiguous outcomes or unintended transactions. Shadow read-only traffic first and migrate submissions through a controlled, observable path.
What should trigger rollback?
Set the criteria before rollout. Unsupported required methods, stale data, unresolved errors or missing events can justify rollback when they violate the application’s acceptance criteria. Preserve evidence for the decision.