Bitcoin Blacklist

Generate a snapshot of Non-Monetary UTXOs (NMUs) based on The Cat BIP.

Background

The Cat is a proposed Bitcoin soft fork for Non-Monetary UTXO Cleanup. It makes inscription and stamp dust UTXOs permanently unspendable, allowing them to be removed from the UTXO set by:

1. Taking a snapshot of all inscription/stamp dust UTXOs at a specific block height
2. Encoding them in a compact Binary Fuse Filter
3. Making them permanently unspendable after activation

This tool generates that snapshot from an Ord index database.

Prerequisites

Synced Ord index - You need a fully synced Ord database with address indexing:

ord --index-addresses index

Installation

git clone https://github.com/taproot-wizards/bitcoin-blacklist
cd bitcoin-blacklist
cargo build --release

Usage

Step 1: Generate CSV Snapshot

Extract all inscription UTXOs under 1000 sats:

./target/release/bitcoin-blacklist snapshot \
  --ord-db ~/.local/share/ord/index.redb \
  --output-file blacklist.csv

If your Ord index was built with --index-sats, add the --index-sats flag:

./target/release/bitcoin-blacklist snapshot \
  --ord-db ~/.local/share/ord/index.redb \
  --output-file blacklist.csv \
  --index-sats

Output CSV format:

# snapshot_height: 880000
# snapshot_hash: 0000000000000000000...
txid,vout,value,address
abc123...,0,546,bc1p...

Step 2: Generate Binary Filter

Convert the snapshot to a compact Binary Fuse Filter:

./target/release/bitcoin-blacklist generate-filter \
  --csv-input blacklist.csv \
  --output blacklist.bin

Step 3: Spread the word!