fix(scripts): address wallet-operator-mapper review feedback

Fix critical bugs and configuration issues identified in code review:

Bug Fixes:
- Fix wallet count aggregation in analyze-per-operator.js
  - Changed assignment operator from = to += on lines 122, 125
  - Now correctly sums wallet counts across all operators per provider
  - Previously only recorded last operator's count, causing incorrect analysis

Configuration:
- Externalize hard-coded file paths to environment variables
  - query-dkg-events.js: Use PROOF_OF_FUNDS_PATH with ./data/ fallback
  - validate-operator-list.js: Use THRESHOLD_STAKERS_CSV_PATH with ./data/ fallback
  - Scripts now portable across team members and environments

Documentation:
- Add data file setup section to README.md
- Document two setup options: default directory and env variables
- Create data/README.md with file requirements and sources
- Update .env.example with new configuration variables
- Add data/ directory to .gitignore

All review comments from piotr-roslaniec addressed.

Author: lrsaturnino

scripts/wallet-operator-mapper/.env.example

@@ -11,3 +11,10 @@ QUERY_DELAY_MS=100
 
 # Optional: Enable verbose logging
 DEBUG=false
+
+# Data file paths (optional - defaults to ./data/ directory)
+# Path to tBTC proof-of-funds JSON file
+PROOF_OF_FUNDS_PATH=./data/tbtc-proof-of-funds.json
+
+# Path to threshold stakers CSV file
+THRESHOLD_STAKERS_CSV_PATH=./data/threshold_stakers_may_2025.csv

scripts/wallet-operator-mapper/.gitignore

@@ -8,6 +8,9 @@ package-lock.json
 # Output
 wallet-operator-mapping.json
 
+# Data files
+data/
+
 # Logs
 *.log
 npm-debug.log*

scripts/wallet-operator-mapper/README.md

@@ -12,10 +12,44 @@ npm install
 cp .env.example .env
 # Edit .env with your Alchemy/Infura archive node URL
 
-# 3. Run analysis
+# 3. Set up data files (see Data Files Setup below)
+mkdir -p data
+# Copy required data files to ./data/ directory
+
+# 4. Run analysis
 node analyze-per-operator.js
 ```
 
+## Data Files Setup
+
+The scripts require two data files from the Memory Bank project:
+
+### Required Files
+
+1. **tBTC Proof of Funds** (`tbtc-proof-of-funds.json`)
+   - Contains wallet balances and metadata
+   - Source: Memory Bank `/knowledge/20251006-tbtc-proof-of-funds.json`
+
+2. **Threshold Stakers CSV** (`threshold_stakers_may_2025.csv`)
+   - Contains operator list and stake information
+   - Source: Memory Bank `/knowledge/threshold_stakers_may_2025.csv`
+
+### Setup Options
+
+**Option 1: Use default data directory** (recommended)
+```bash
+mkdir -p data
+cp /path/to/memory-bank/knowledge/20251006-tbtc-proof-of-funds.json data/tbtc-proof-of-funds.json
+cp /path/to/memory-bank/knowledge/threshold_stakers_may_2025.csv data/threshold_stakers_may_2025.csv
+```
+
+**Option 2: Use environment variables**
+```bash
+# Add to .env file:
+PROOF_OF_FUNDS_PATH=/custom/path/to/tbtc-proof-of-funds.json
+THRESHOLD_STAKERS_CSV_PATH=/custom/path/to/threshold_stakers_may_2025.csv
+```
+
 ## What This Does
 
 Analyzes tBTC wallets to identify which contain deprecated operators being removed during consolidation.

scripts/wallet-operator-mapper/analyze-per-operator.js

@@ -119,10 +119,10 @@ Object.entries(operatorShares).forEach(([addr, data]) => {
   if (providerShares[data.provider]) {
     if (data.status === 'KEEP') {
       providerShares[data.provider].keep += data.totalShare;
-      providerShares[data.provider].keepWallets = data.walletCount;
+      providerShares[data.provider].keepWallets += data.walletCount;
     } else {
       providerShares[data.provider].disable += data.totalShare;
-      providerShares[data.provider].disableWallets = data.walletCount;
+      providerShares[data.provider].disableWallets += data.walletCount;
     }
   }
 });

scripts/wallet-operator-mapper/query-dkg-events.js

@@ -29,7 +29,8 @@ if (limitArg) {
 }
 
 // File paths
-const PROOF_OF_FUNDS_PATH = '/Users/leonardosaturnino/Documents/GitHub/memory-bank/20250809-beta-staker-consolidation/knowledge/20251006-tbtc-proof-of-funds.json';
+const PROOF_OF_FUNDS_PATH = process.env.PROOF_OF_FUNDS_PATH ||
+  path.join(__dirname, 'data', 'tbtc-proof-of-funds.json');
 const OPERATORS_PATH = path.join(__dirname, 'operators.json');
 const BRIDGE_CONTRACT_PATH = path.join(__dirname, 'contracts', 'Bridge.json');
 const OUTPUT_PATH = path.join(__dirname, 'wallet-operator-mapping.json');

scripts/wallet-operator-mapper/validate-operator-list.js

@@ -10,7 +10,8 @@ const fs = require('fs');
 const path = require('path');
 
 const MAPPING_FILE = path.join(__dirname, 'wallet-operator-mapping.json');
-const CSV_PATH = '/Users/leonardosaturnino/Documents/GitHub/memory-bank/20250809-beta-staker-consolidation/knowledge/threshold_stakers_may_2025.csv';
+const CSV_PATH = process.env.THRESHOLD_STAKERS_CSV_PATH ||
+  path.join(__dirname, 'data', 'threshold_stakers_may_2025.csv');
 
 console.log('🔍 Operator List Validation\n');
 console.log('='.repeat(80));