Add pattern matching, leading char scoring, smart validation, and help system

[l3wi]

Summary

This PR adds comprehensive pattern matching with prefix/suffix support, a new leading character scoring method, smart combination validation, an interactive help system, and increases the GPU device limit from 10 to 32.

New Features

1. Pattern Matching (Prefix/Suffix)

• Prefix matching (--prefix / -p): Match addresses starting with a pattern (e.g., cafe, dead)
• Suffix matching (--suffix / -s): Match addresses ending with a pattern (e.g., beef, 1337)
• 3x scoring weight: Each matching character scores 3 points vs 1 point for base methods
• Works standalone or combined with scoring methods
• Supports hex patterns with or without 0x prefix
• Can be used without any scoring method: ./vanity -p cafe -s beef -d 0

2. Leading Character Scoring

• New flag (--leading-char / -lc): Count leading occurrences of a specific hex character
• Find addresses like 0x111111... or 0xaaaaaa... efficiently
• Takes a single hex character (0-9, a-f) as input
• 1 point per matching leading character
• Can combine with prefix: -p cafe -lc 1 finds 0xcafe1111...
• Credit: Implementation based on code snippet from @MrSpike63

3. Smart Prefix + Leading Scoring

• Leading zeros/chars count AFTER prefix when combined
• -p cafe -lz finds 0xcafe0000... (12 pts prefix + 1 pt per zero after)
• -p dead -lc 1 finds 0xdead1111... (12 pts prefix + 1 pt per '1' after)
• Enables highly targeted compound patterns with optimal scoring

4. Smart Validation System

Blocks impossible combinations:

• -lz -p cafe (removed - now scores zeros after prefix)
• Multiple base scoring methods together (-lz -z, -lc 1 -lz)

Warns on inefficient combinations:

• -lz -p 000 (all-zero prefix makes -lz redundant)
• -lc 1 -p 111 (all-same prefix makes -lc redundant)
• Provides clear explanation and allows user override

5. Comprehensive Help System

• Added --help / -h flag with detailed usage information
• Automatically displays help when no arguments provided
• Includes all options, scoring explanations, and real examples
• Shows which combinations work best

6. Increased GPU Support

• GPU device limit increased from 10 to 32 devices
• Supports large multi-GPU mining rigs

Usage Examples

Pattern Matching

# Simple patterns
./vanity -p cafe -d 0                    # Find 0xcafe...
./vanity -s beef -d 0                    # Find 0x...beef
./vanity -p dead -s beef -d 0            # Find 0xdead...beef

# Compound patterns (prefix + leading scoring)
./vanity -p cafe -lz -d 0                # Find 0xcafe0000...
./vanity -p dead -lc 1 -d 0              # Find 0xdead1111...
./vanity -p beef -lz -s cafe -d 0        # Find 0xbeef000...cafe

# Leading character patterns
./vanity -lc 1 -d 0                      # Find 0x111111...
./vanity -lc a -s beef -d 0              # Find 0xaaaa...beef

Scoring Method Flexibility

# Scoring method now optional if using patterns
./vanity -p cafe -d 0                    # Just prefix (12 pts)
./vanity -p dead -s beef -d 0            # Prefix + suffix (24 pts)

# Or combine for compound scoring
./vanity -lz -s beef -d 0                # Leading zeros + suffix
./vanity -z -p cafe -s beef -d 0         # Zero bytes + both patterns

Scoring System

Method	Weight	Behavior with Prefix
Prefix match	3 pts/char	Scores prefix characters
Suffix match	3 pts/char	Scores suffix characters
Leading zeros	1 pt/char	Counts zeros after prefix
Leading char	1 pt/char	Counts chars after prefix
Zero bytes	1 pt/byte	Counts zeros anywhere

Example: -p cafe -lz finding 0xcafe0000

• Prefix "cafe": 4 chars × 3 = 12 pts
• Zeros after: 4 chars × 1 = 4 pts
• Total: 16 pts

Implementation Details

Technical Changes

• Modified score_leading_zeros() to count nibbles and skip prefix
• Modified score_leading_char() with efficient nibble scanning and prefix skip
• Added score_prefix_match() and score_suffix_match() device functions
• Added constant memory for prefix/suffix/leading char patterns on GPU
• Integrated scoring into handle_output() and handle_output2()
• Added comprehensive CLI argument parsing and validation
• Added print limiting (max 10 results per score level)
• Made scoring method optional when patterns are provided

Validation Logic

• Prevents using multiple base scoring methods together
• Warns when prefix already covers the pattern (with user override)
• Improved error messages explaining why combinations don't work
• Allows compound patterns with clear scoring explanations

Testing

All changes tested and verified. Existing functionality preserved. Ready for production use.

---

Total commits: 7

• feat: add prefix and suffix pattern matching with 3x scoring weight
• feat: add --help flag and display help when no arguments provided
• fix: increase GPU device limit from 10 to 32
• feat: add --leading-char scoring method for specific character matching
• feat: add validation for impossible and inefficient flag combinations
• feat: make scoring method optional when using prefix/suffix patterns
• feat: score leading zeros/chars AFTER prefix for compound patterns

🤖 Generated with Claude Code

[l3wi]

Tested on Vast.ai with a 12x RTX 4090 system.

Type	Total Speed	GPU Speed
Address	43.8 GH/s	3.65 GH/s
Contract	23.7 GH/s	1.975 GH/s

[l3wi]

Added better startup text as well

./vanity-eth-address -p 987654321000 -d 0 -d 1 -d 2 -d 3 -d 4 -d 5 -d 6 -d 7 -d 8 -d 9 -d 10 -d 11 

Starting vanity address generation on 12 GPUs
  Type:     Address
  Scoring:  None + Patterns
  Patterns: Prefix: 0x987654321000 (bonus: 36)