# Wallet Blacklist - Product Knowledge Base

## Overview
**Status:** Active
**Type:** Data Service / Threat Intelligence
**Format:** JSONL (JSON Lines)
**Update Frequency:** Daily

The Wallet Blacklist is a high-performance threat intelligence database containing confirmed malicious Solana wallets. It is used by the PumpFun Sniper and other trading bots to prevent interactions with rug-pullers, serial scammers, and spam deployers.

## Data Format

The file is a Line-Delimited JSON (JSONL).
**File:** `blacklist.jsonl`

### Schema
```json
{
  "addr": "String (Base58 Public Key)",
  "ts": "Number (Unix Timestamp in Milliseconds)",
  "hash": "String (Hex Hash of Evidence/Reason)"
}
```

### Example Data
```jsonl
{"addr":"3DadyvFvwkTTmAyyPnBTkuDu3CxUdDN3WxDNfwjC219L","ts":1763076072862,"hash":"5dc00e16480fa054"}
{"addr":"236Tgr4empAwEHwTXTtQg9VYXyz8fRWuzgRwzGxTDcGz","ts":1762960639871,"hash":"2c09eaf1400f0059"}
{"addr":"5dRGVSmzwbi2N2wAgm44grNsZHgmUM7USG6V7vejZ5AA","ts":1763353660955,"hash":"d41e2150cb519782"}
```

---

## Integration

### Downloading
```bash
wget https://allenhark.com/blacklist.jsonl
# OR
curl -o blacklist.jsonl https://allenhark.com/blacklist.jsonl
```

### Usage in Rust
```rust
use std::fs::File;
use std::io::{BufRead, BufReader};
use serde::Deserialize;

#[derive(Deserialize)]
struct BlacklistEntry {
    addr: String,
    ts: u64,
    hash: String,
}

fn load_blacklist(path: &str) -> Vec<String> {
    let file = File::open(path).expect("Failed to open blacklist");
    let reader = BufReader::new(file);
    
    reader.lines()
        .filter_map(|line| line.ok())
        .filter_map(|line| serde_json::from_str::<BlacklistEntry>(&line).ok())
        .map(|entry| entry.addr)
        .collect()
}
```

### Usage in Node.js
```javascript
const fs = require('fs');
const readline = require('readline');

async function loadBlacklist(path) {
  const fileStream = fs.createReadStream(path);
  const rl = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity
  });

  const blacklist = new Set();
  for await (const line of rl) {
    try {
      const entry = JSON.parse(line);
      blacklist.add(entry.addr);
    } catch (e) {
      console.error('Skipping invalid line:', line);
    }
  }
  return blacklist;
}
```

---

## Maintenance

The blacklist is generated by analyzing on-chain behavior:
1.  **Rug Pulls**: Creators who remove liquidity < 1 hour after launch.
2.  **Spam**: Wallets creating > 10 tokens per day with low liquidity.
3.  **Honeypots**: Tokens with restricted transfer logic.

---

## Detailed Q&A

### Data & Updates

**Q: How often is the blacklist updated?**
A: The master list at `https://allenhark.com/blacklist.jsonl` is rebuilt **every 24 hours** at 00:00 UTC. For high-frequency bots, we recommend setting up a cron job to download the new list once a day.

**Q: What is the `hash` field for?**
A: The `hash` represents a cryptographic proof of the evidence collected (e.g., the transaction signature of the rug pull or the pattern match ID). It is primarily used by our internal auditing tools to verify *why* a wallet was added. You can generally ignore it in your trading bot logic.

**Q: Can I manually check if a wallet is blacklist?**
A: Yes. Since the file is simple text (JSONL), you can use `grep`:
```bash
grep "WALLET_ADDRESS" blacklist.jsonl
```
If it returns a line, the wallet is blacklisted.

### False Positives

**Q: My wallet is on the list, but I am not a scammer. What do I do?**
A: Our automated heuristics are aggressive to protect traders. Common reasons for false flags include:
*   Launching multiple test tokens in a short period (looks like spam).
*   Removing liquidity for legitimate migration reasons without locking it first.
To appeal, please open a ticket in our **Discord Support** channel with your wallet address. We review appeals within 48 hours.

**Q: Does using this list guarantee safety?**
A: **No.** It significantly reduces risk by filtering known bad actors, but it cannot predict *new* scammers who generate fresh wallets for every launch. Always manage your position sizing and risk accordingly.

### Integration Tips

**Q: The file is getting large. Will it slow down my bot?**
A: The file currently contains ~4,000 entries, which is negligible for modern systems. However, as it grows:
*   **Do not** re-read the file for every trade.
*   **Do** load it into a `HashSet` (Rust) or `Set` (JS) at startup. Lookups will remain O(1) (instant).
*   **Do** `SIGHUP` or restart your bot daily after downloading the update.