docs(bridge): add operations and cutover runbooks - #371
Merged
islandbitcoin merged 4 commits intoMay 26, 2026
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Bridge operations documentation for deploys, webhook handling, replay, reconciliation, incidents, and Cash Wallet cutover execution.
Includes:
docs/bridge-integration/OPERATIONS.mdfor steady-state Bridge operationsdocs/bridge-integration/CUTOVER-RUNBOOK.mdfor OPS-50 cutover-day go/no-go executionReview-driven fixes before PR
Ran an external DeepSeek Reasoner review, then passed that critique to GPT-5.5 for second-pass validation. Patched the confirmed blockers before opening this PR:
tmp/bridge-rebase-pr-ready, which includes ENG-345 cutover CLI/schema/Bruno files.dev/config/base-config.yamlwithPROD_CONFIG_PATHand explicit environment preflight checks.X-Webhook-Signature: t=<timestamp_ms>,v0=<base64_signature>.preview,prepare,start,run-batch,status, andcomplete.Second review iteration
Ran a second DeepSeek Reasoner review against the patched PR, then passed those findings to GPT-5.5. Patched the confirmed issues:
PRE: old and capable clients both see legacyUSD.IN_PROGRESS: not-started accounts remainUSD; completed/skipped migrated accounts showUSDTto capable clients and legacy-compatibleUSDto old clients.COMPLETE: capable clients seeUSDT; old clients see legacy-compatibleUSD.IN_PROGRESSandCOMPLETE.IN_PROGRESSandCOMPLETEactions as emergency overrides requiring backend-owner approval and operator-log entries.Follow-ups created:
Verification
git diff --check origin/tmp/bridge-rebase-pr-ready...HEADBridge-SignatureBridge-Timestamp--configPath dev/config/base-config.yamlapproved migration jobapproved admin operationUSDTpre-cutover expectationsIN_PROGRESS/COMPLETEguidanceNotes
This PR intentionally does not implement ENG-364 rollback mechanics. The cutover runbook treats rollback after irreversible wallet/default changes as a separate data-repair process and defines the handoff packet for ENG-364.