Module spam_filter 

Spam Filtering for UTXO Commitments

Implements spam detection and filtering for Bitcoin transactions:

• Ordinals/Inscriptions detection
• Dust output filtering
• BRC-20 pattern detection
• Adaptive witness size thresholds based on script type

This filter enables 40-60% bandwidth savings by skipping spam transactions during ongoing sync while maintaining consensus correctness.

Critical Design Note: Spam filtering applies to OUTPUTS only, not entire transactions. When a spam transaction is processed:

• Its spent INPUTS are still removed from the UTXO tree (maintains consistency)
• Its OUTPUTS are filtered out (bandwidth savings)

This ensures the UTXO tree remains consistent even when spam transactions spend non-spam inputs. The process_filtered_block function in initial_sync.rs implements this correctly by processing all transactions but only adding non-spam outputs.

Structs

SpamBreakdown

Breakdown of spam by category

SpamFilter

Spam filter implementation

SpamFilterConfig

Spam filter configuration

SpamFilterConfigSerializable

Serializable spam filter configuration (for config files)

SpamFilterResult

Spam filter result

SpamSummary

Summary of filtered spam

WitnessElementAnalysis

Witness element analysis result

WitnessSizeThresholds

Adaptive witness size thresholds based on script type

WitnessSizeThresholdsSerializable

Serializable adaptive thresholds

Enums

ScriptType

Script type classification

SpamFilterPreset

Spam filter preset configurations

SpamType

Spam classification for a transaction

Constants

DEFAULT_DUST_THRESHOLD

Default dust threshold (546 satoshis = 0.00000546 BTC)

DEFAULT_MAX_SIZE_VALUE_RATIO

Default maximum transaction size to value ratio Non-monetary transactions often have very large size relative to value transferred

DEFAULT_MAX_WITNESS_SIZE

Default maximum witness size (bytes) - larger witness stacks suggest data embedding

DEFAULT_MIN_FEE_RATE

Default minimum fee rate threshold (satoshis per vbyte) Transactions with fee rate below this are suspicious

Functions

detect_input_script_type

Detect script type from input script (scriptSig)