From 63ac6ec00f00e5039267ad0ba533b0b0f7c47d8f Mon Sep 17 00:00:00 2001
From: Enki <enki@git@sovbit.dev>
Date: Thu, 19 Dec 2024 21:25:26 +0000
Subject: [PATCH] Update Readme

---
 README.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 167 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8a04e83..64abb2f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,168 @@
-# stirfry-spam-filter
+# Strfry Nostr Spam Filter
 
-A spam filter for stirfry relays. 
\ No newline at end of file
+A sophisticated spam filtering system for Nostr relays, designed to protect against various types of spam while maintaining a good experience for legitimate users.
+
+## Features
+
+- Reputation-based filtering system
+- Per-user rate limiting
+- Content similarity detection
+- New account protection
+- Bot behavior detection
+- Progressive penalty system
+- Automatic recovery mechanism
+- Kind-specific rate limits
+- Configurable thresholds
+
+## Installation
+
+1. Clone this repository:
+```bash
+git clone https://github.com/yourusername/strfry-spam-filter.git
+```
+
+2. Make the filter executable:
+```bash
+chmod +x relay-spam-filter.js
+```
+
+3. Configure your strfry relay to use the filter:
+```bash
+# Add to your strfry configuration
+plugins = [
+  {
+    exec = "/path/to/relay-spam-filter.js"
+  }
+]
+```
+
+## Configuration
+
+The filter includes many configurable options. Here are the key settings:
+
+### Rate Limits
+```javascript
+maxRepliesPerMinute: 50,        // Maximum replies per minute per user
+maxRepliesPerHour: 400,         // Maximum replies per hour per user
+```
+
+### Event-Type Specific Limits
+```javascript
+kindSpecificLimits: {
+    0: { maxPerHour: 10 },      // Profile updates
+    3: { maxPerHour: 5 },       // Contact list updates
+    1: {                        // Regular posts
+        maxPerMinute: 30,
+        maxPerHour: 200
+    }
+}
+```
+
+### Reputation System
+```javascript
+reputationConfig: {
+    initialScore: 100,          // Starting reputation for new users
+    goodEventBonus: 1,          // Points gained for good events
+    spamPenalty: -15,           // Base penalty for spam
+    recoveryRate: 3,            // Points recovered per hour
+    minScore: -100,             // Minimum possible reputation
+    maxScore: 1000,             // Maximum possible reputation
+    blockThreshold: -50,        // Users blocked at this score
+    blockRecoveryThreshold: -25 // Must recover to this to post again
+}
+```
+
+### New User Protection
+```javascript
+newPubkeyReplyThreshold: 60,    // Seconds new users must wait to reply
+newPubkeyMaxPostsIn5Min: 10     // Maximum posts in first 5 minutes
+```
+
+### Content Analysis
+```javascript
+contentSimilarityThreshold: 0.8, // 80% similarity triggers spam detection
+fastReplyThreshold: 30,          // Minimum seconds between reply and original post
+```
+
+## How It Works
+
+### Reputation System
+
+The filter maintains a reputation score for each user:
+
+1. New users start at 100 points
+2. Good behavior slowly increases reputation
+3. Spam behavior results in penalties:
+   - -15 points above 0 reputation
+   - -20 points below -25 reputation
+   - -25 points below -50 reputation
+4. Recovery rates:
+   - 3 points/hour above 0
+   - 2 points/hour between -25 and 0
+   - 1 point/hour below -50
+5. Users are blocked at -50 until they recover to -25
+
+### Spam Detection
+
+The filter checks for several types of spam behavior:
+
+1. Rate Limiting
+   - Monitors post frequency per user
+   - Different limits for different event types
+   - Limits scale with reputation
+
+2. Content Analysis
+   - Checks for duplicate content across users
+   - Detects suspiciously fast replies
+   - Identifies bot-like behavior patterns
+
+3. New Account Protection
+   - Stricter limits for new accounts
+   - Longer waiting periods for replies
+   - Limited initial posting rate
+
+4. Bot Detection
+   - Identifies automated posting patterns
+   - Checks for relay URL spam
+   - Monitors reply timing patterns
+
+### Progressive Enforcement
+
+The system becomes progressively stricter with problematic behavior:
+
+1. Initial warnings and small penalties
+2. Increased penalties for continued violations
+3. Stricter rate limits for low-reputation users
+4. Eventual blocking for persistent offenders
+
+## Bypass Rules
+
+Certain event kinds can bypass specific checks:
+
+```javascript
+allowedKinds: [3, 5, 10001, 10002, 30311],  // Bypass content checks
+bypassAllChecksKinds: [38383]                // Bypass all checks
+```
+
+## Monitoring
+
+The filter provides detailed logging:
+
+```javascript
+[2024-12-19T10:15:30.123Z] Event abc123 from pubkey xyz789 (reputation: 85.50)
+[2024-12-19T10:15:30.124Z] Rate limit exceeded for pubkey xyz789
+```
+
+## Performance Considerations
+
+- Memory usage is managed through periodic cleanup
+- Old events and stats are automatically purged
+- Reputation data persists for 24 hours of inactivity
+
+## Contributing
+
+Contributions are welcome!
+
+## License
+
+MIT License - See LICENSE file for details