Incidents¶

This page describes what happens when Theft Shield detects and responds to a potential theft attempt.

Incident Timeline¶

Detection Phase (seconds)¶

Unauthorized transaction enters mempool
Vigil detects the transaction and matches it to your monitored UTXOs
Whitelist check: NOT whitelisted
Theft Shield triggers and broadcasts a defense transaction
Transactions propagate across the network

Response Phase (until confirmation)¶

Vigil continues monitoring the mempool
Check if attacker responds with a higher fee
  └── If yes → broadcast the next round PSBT
  └── If no  → continue monitoring
One of the transactions confirms
  └── Your transaction → Funds are safe ✓
  └── Attacker's tx → Funds may be lost ✗

Incident Notifications¶

You'll receive notifications at each stage:

Incident Detected¶

🚨 THEFT SHIELD ALERT

Wallet: My Cold Storage
Event: Unauthorized transaction detected

Attacker's Transaction:
  TXID: abc123...
  Attempting to send: 0.5 BTC
  To address: bc1qattacker...
  Fee rate: 10 sat/vB

Status: Theft Shield responding...

Response Broadcast¶

🛡️ THEFT SHIELD RESPONSE

Wallet: My Cold Storage
Event: Defense transaction broadcast

Your Transaction:
  TXID: def456...
  Sending: 0.4975 BTC
  To safe address: bc1qsafe...
  Fee rate: 50 sat/vB (Round 1)

Status: Awaiting confirmation...

Resolution¶

✅ THEFT SHIELD SUCCESSFUL

Wallet: My Cold Storage
Event: Defense transaction confirmed

Result: Funds secured
  Amount saved: 0.4975 BTC
  Fee spent: 0.0025 BTC
  Confirmed in block: 800,000

Your funds are now at your safe address.

Or if unsuccessful:

❌ THEFT SHIELD UNSUCCESSFUL

Wallet: My Cold Storage
Event: Attacker transaction confirmed

Result: Funds may be lost
  Attacker's tx confirmed in block: 800,000

This can happen if:
  - Attacker's fee budget exceeded yours
  - Attacker's transaction confirmed immediately

Contact support for assistance.

Incident Dashboard¶

During an active incident, the dashboard shows:

┌─────────────────────────────────────────────────┐
│ 🚨 ACTIVE INCIDENT                              │
├─────────────────────────────────────────────────┤
│ Wallet: My Cold Storage                         │
│ Status: RBF RACE IN PROGRESS                    │
│                                                 │
│ Attacker                    Your Defense        │
│ ──────────────────          ────────────────    │
│ TXID: abc123...             TXID: def456...     │
│ Fee: 10 sat/vB              Fee: 50 sat/vB      │
│ Confirmations: 0            Confirmations: 0    │
│                                                 │
│ Current Round: 1 of 4                           │
│ Next escalation at: 15 sat/vB attacker fee      │
│                                                 │
│ [View on mempool.space]                         │
└─────────────────────────────────────────────────┘

Post-Incident Actions¶

If Successful¶

Verify funds arrived at your safe address
Investigate the compromise
How were your keys exposed?
What devices/backups were compromised?
Secure compromised wallet
Do NOT reuse the compromised seed
Create a new wallet if needed
Update Vigil configuration
Remove the compromised wallet
Add new wallet if created

If Unsuccessful¶

Document everything
Transaction IDs
Timeline
Evidence of compromise
Contact authorities if appropriate
Local law enforcement
FBI IC3 (for US victims)
Forensic analysis
How were keys compromised?
Prevent future incidents
Contact Vigil support
We can help analyze what happened
Improve protection for the future

RBF Race Dynamics¶

Your Advantages¶

Pre-signed PSBTs: Instant response
Multi-round strategy: Can escalate multiple times
Monitoring speed: Detection in under 1 second

Attacker Advantages¶

May have more budget: Well-funded attackers
Can watch mempool: Respond to your broadcasts
First-mover: Their transaction is already propagating

Typical Outcomes¶

Scenario	Likely Winner
Amateur attacker, low fee	Defender
Attacker with moderate budget	Usually defender
Well-funded, sophisticated attacker	Depends on budgets
Instant block confirmation	Attacker (no time to respond)

Incident History¶

View past incidents:

Go to Theft Shield → Incidents
See list of all incidents
Click to view details:
Timeline
Transaction IDs
Outcome
Fees spent

False Positives¶

What Causes Them¶

Transaction to address not yet in whitelist
Legitimate but unexpected spending

What Happens¶

If Theft Shield triggers on a legitimate transaction:

Your funds go to your safe address (not lost)
You receive incident notifications
Fees are spent on the defense transaction

Prevention¶

Maintain an accurate whitelist
Add addresses before making transactions
Pause protection for unusual transactions

Next: Troubleshooting →