# Vaultfire V3 — Incident Runbook

## 0. Prerequisites
- Multisig signers reachable within 30 min on two independent channels.
- Guardian key on secure hardware; separate from any signer key.
- Base RPC alternates configured: Alchemy primary, `base-rpc.publicnode.com` fallback.

## 1. Severity levels
- **SEV-1** — Funds at risk NOW, or Invariant #1 broken. Response: page all signers, immediate guardian pause, cap V3 writes at MultisigGovernanceV3.
- **SEV-2** — API degraded or single non-critical invariant flagged. Response: on-call investigates, no pause unless escalated.
- **SEV-3** — Informational.

## 2. SEV-1 playbook
1. On-call confirms alarm via at least 2 independent tools (indexer + direct RPC).
2. Guardian executes `MultisigGovernanceV3.guardianPause(target)` on affected contract(s).
3. Post status update on `/api/v3/protocol/status`. UI banner auto-updates.
4. Snapshot chain state:
   - Block number and hash at pause time.
   - Balances of every V3 contract on Base.
   - Open bond IDs, active mandates, unclaimed payment credits.
5. Assemble war room (multisig signers, auditor if under contract).
6. Determine remediation path:
   a. Config change → propose via multisig, execute after timelock.
   b. Contract redeploy required → freeze V3 caps, new address, indexer version bump.
   c. User migration back to V2 → keep V2 untouched, halt V3 writes only.
7. Prepare public post-mortem draft.

## 3. Compromise scenarios
- **Guardian key leaked**: multisig proposal to rotate guardian to fresh key; revoke old.
- **Multisig signer key leaked**: multisig proposal to remove signer and lower threshold if necessary; re-issue.
- **Attester key leaked (`StreetCredV3`)**: multisig proposal → `setAttester(oldAttester, false)`. Recompute affected scores.
- **Validator collusion (`ERC8004ValidationRegistryV3Safe`)**: `slash()` per validator, sweep to treasury; increase `minStake` proposal.

## 4. Rollback
- V3 contracts are additive; V2 keeps operating regardless of V3 state.
- Roll back API: disable `/api/v3/*` at edge router; `/api/*` V2 unaffected.
- Roll back SDK: publish patch of `@vaultfire/sdk-v3` that throws `V3Disabled` for all writes; V2 SDK untouched.
- Roll back UI: hide V3 tab; V2 UI unaffected.
- User funds already in V3 remain withdrawable via `PullPaymentsV3.withdrawCredit` even when the contract is paused (Invariant #11).

## 5. Post-incident
- Public post-mortem within 5 business days.
- Update `MONITORING_RUNBOOK.md` if a signal was missing.
- Update `../governance/CENTRALIZED_DEPENDENCIES.md` if a supplier was implicated.
- Add regression test to `v3-src/test/invariants` or `pr7/tests/x402`.
