Skip to content

How Theft Shield Works

This page provides a technical deep dive into Theft Shield's protection mechanism.

The RBF Race

When a transaction is broadcast to the Bitcoin network, it enters the mempool (memory pool) where it waits to be included in a block. During this time, the transaction can be replaced by a conflicting transaction that:

  1. Spends the same inputs (UTXOs)
  2. Pays higher fees

Miners generally prefer higher-fee transactions, so the replacement is more likely to be confirmed.

Full RBF Support

The Bitcoin network majority now supports full RBF (Replace-By-Fee), meaning any unconfirmed transaction can be replaced—even if it doesn't signal opt-in RBF. This makes Theft Shield highly effective, as attackers cannot prevent replacement by simply not signaling RBF.

The Attack Scenario

Timeline of a theft attempt:

T=0:    Attacker steals your seed phrase
T=1:    Attacker broadcasts tx sending funds to their address
        Fee: 10 sat/vB
T=2:    Vigil detects unauthorized tx in mempool
T=3:    Theft Shield broadcasts replacement tx to your safe address
        Fee: 50 sat/vB (higher fee wins)
T=10m:  Your transaction confirms, funds are safe

Pre-Signed PSBT Architecture

What is a PSBT?

A PSBT (Partially Signed Bitcoin Transaction) is a Bitcoin standard (BIP-174) that allows creating transactions in stages:

  1. Creation - Define inputs and outputs
  2. Signing - Add signatures from required keys
  3. Finalization - Complete the transaction for broadcast
  4. Broadcast - Send to the Bitcoin network

How Vigil Uses PSBTs

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Vigil     │───▶│   Your      │───▶│   Vigil     │
│   creates   │    │   hardware  │    │   stores    │
│   unsigned  │    │   wallet    │    │   signed    │
│   PSBT      │    │   signs     │    │   PSBT      │
└─────────────┘    └─────────────┘    └─────────────┘
  1. Vigil generates a PSBT that spends your UTXOs to your safe address
  2. You sign the PSBT with your hardware wallet
  3. Vigil stores the signed PSBT securely
  4. If theft is detected, Vigil broadcasts the PSBT

Security Guarantee

The signed PSBT:

  • Only sends to YOUR safe address (you verified this before signing)
  • Cannot be modified after signing (cryptographic guarantee)
  • Is only broadcast when theft is detected

Multi-Round Fee Strategy

Theft Shield uses a multi-round approach to outbid attackers:

Round System

Round Fee Rate Purpose
1 Low Initial response, catches low-effort attacks
2 Medium Escalation if attacker responds
3 High Strong response for persistent attackers
4 Maximum All-out defense using remaining budget

How Rounds Work

Attacker broadcasts: 10 sat/vB
  ↓
Vigil Round 1: 25 sat/vB
  ↓
Attacker responds: 30 sat/vB (if they're watching)
  ↓
Vigil Round 2: 50 sat/vB
  ↓
Attacker responds: 55 sat/vB
  ↓
Vigil Round 3: 100 sat/vB
  ↓
Transaction confirms (defender wins)

Fee Budget Exhaustion

If your fee budget is exhausted before the attacker's, they may win the RBF race. Higher fee budgets provide stronger protection.

Detection Mechanism

What Triggers Protection

Theft Shield activates when we detect:

  1. A transaction spending your monitored UTXOs
  2. That is NOT sending to whitelisted addresses
  3. That you did NOT authorize

Whitelist Protection

Legitimate transactions are protected by your whitelist:

  • Addresses you mark as trusted
  • Your own wallet addresses (auto-detected)
  • Explicit whitelisted destinations

Learn about whitelisting →

False Positive Prevention

We minimize false positives by:

  • Requiring explicit UTXO coverage in PSBTs
  • Checking against your whitelist first
  • Only broadcasting when confident in theft detection

Broadcast Timing

Speed is Critical

The faster we broadcast, the less time the attacker has to respond:

Response timing depends on network conditions and system load. In general, Theft Shield is designed to respond quickly once an unauthorized transaction is detected.

Network Propagation

After broadcast, our transaction propagates through the Bitcoin network. We broadcast to multiple nodes simultaneously to maximize propagation speed.

Limitations

Theft Shield Cannot Protect Against

Scenario Reason
Immediate confirmation No time for RBF if attacker's tx confirms in next block
Lucky attackers A sophisticated attacker able to keep increasing fees and get their transaction confirmed before we can broadcast ours
High fee attacks Extremely high fees that exceed our budget
Uncovered UTXOs RBF only works when transactions share inputs

Understanding UTXO Coverage

Coverage Below 100%

When your PSBT coverage falls below 100%, protection works differently:

Covered UTXOs (included in your PSBT):

  • If an attacker's transaction spends ANY of these UTXOs, RBF protection works normally
  • Theft Shield can broadcast the pre-signed sweep to outbid the attacker

Uncovered UTXOs (new deposits since PSBT generation):

  • If an attacker's transaction contains NONE of the inputs in your PSBT, RBF cannot work
  • This is because RBF requires spending the same UTXOs to create a "conflict"
  • Without shared inputs, there's no conflict and no replacement is possible

Likelihood Assessment:

This scenario is low likelihood in practice. Attackers who compromise your seed phrase typically want to steal ALL funds, which would include covered UTXOs and trigger protection. An attacker would need to specifically target only your newest deposits while ignoring older funds—an unusual attack pattern.

Nevertheless, for complete protection, always update your PSBT after receiving new deposits.

Mitigations

  • Higher fee budgets - More resources to outbid attackers
  • Timely PSBT updates - Keep PSBTs current when UTXOs change
  • Layered security - Theft Shield + strong key security

Single-Use Protection

Theft Shield is Single-Use

A Theft Shield configuration is intended to be used once. When a theft response is triggered:

  1. The protection fee is consumed
  2. The sweep transaction is broadcast
  3. The configuration becomes inactive once the incident resolves (successfully or not)

After a theft attempt, abandon the wallet immediately—it has been compromised.

What Happens After an Incident

Whether the sweep succeeds or fails:

  • Your protection fee is consumed (it paid for the RBF battle)
  • The Theft Shield configuration is deactivated
  • The wallet should be considered compromised and unsafe for future use

If you want to continue using the wallet after an incident, you would need to:

  1. Set up a completely new Theft Shield configuration
  2. Pay a new protection fee
  3. Generate and sign new PSBTs

However, this is not recommended—if your seed phrase was compromised once, the wallet is permanently unsafe.

Technical Details

Transaction Structure

Theft Shield transactions:

  • Spend ALL monitored UTXOs in the wallet
  • Send to a single output (your safe address)
  • Use P2WPKH for the safe address (efficient)
  • Signal RBF (BIP-125)
  • Include appropriate fee for the current round

Signature Type

  • SIGHASH_ALL - Signs all inputs and outputs
  • Prevents any modification after signing

Nonce Security

Each PSBT uses unique nonces to prevent signature reuse attacks.

Next: Setup Wizard →