chain-scanner 0.1.0
On-chain AML pattern detection tool for cryptocurrency transactions
Requires Python: >=3.9
Keywords: blockchain, aml, cryptocurrency, ethereum, bitcoin, compliance

# Onchain AML

[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/brody4321)

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buymeacoffee)](https://buymeacoffee.com/brody4321)

**On-Chain AML Pattern Detector**

A local/offline AML pattern detection tool for cryptocurrency transactions. Supports Ethereum and Bitcoin, multiple data input methods, and provides both CLI and library interfaces.

All analysis runs locally - no data is sent to external servers.

## Features

- **Multi-chain support**: Ethereum and Bitcoin
- **Multiple data sources**: JSON/CSV files, API (Etherscan), or local node
- **6 Detection modules**: Mixers, sanctions, structuring, layering, privacy coins, bridges
- **Risk scoring**: 0-100 score with LOW/MEDIUM/HIGH/CRITICAL classification
- **Flexible output**: Terminal, JSON, or CSV reports
- **Extensible**: Easy to add new detectors and data sources

## Installation

```bash
pip install git+https://github.com/cleonard2341/onchain-aml.git
```

Or install from source:

```bash
git clone https://github.com/cleonard2341/onchain-aml.git
cd onchain-aml
pip install -e .
```

## Quick Start

### Command Line

```bash
# Scan an address
chain-scanner scan 0x742d35Cc6634C0532925a3b844Bc9e7595f... --chain eth

# Scan from a file
chain-scanner scan-file transactions.json

# Check against sanctions list
chain-scanner check-sanctions 0x8589427373D6D84E98730D7795D8f6f8731FDA16

# Generate JSON report
chain-scanner scan-file data.json --output report.json --output-format json

# List available detectors
chain-scanner list-detectors
```

### As a Library

```python
from chain_scanner import Scanner

# Create scanner for Ethereum
scanner = Scanner(chain="ethereum")

# Scan transactions from a file
result = scanner.scan_file("transactions.json")

# Check the results
print(f"Risk Score: {result.risk_score}/100")
print(f"Risk Level: {result.risk_level}")

for flag in result.flags:
    print(f"  [{flag.severity}] {flag.type}: {flag.details}")
```

## Detection Modules

| Detector | Description | Signals |
|----------|-------------|---------|
| **Sanctions** | OFAC/blocklist match | Address appears on sanctions list |
| **Mixer** | Known mixer services | Tornado Cash, Wasabi, CoinJoin, etc. |
| **Structuring** | Transaction splitting | Multiple txs just below reporting thresholds |
| **Layering** | Rapid fund movement | Funds hopping 3+ addresses within 48 hours |
| **Privacy Coins** | Anonymity-enhanced | RAILGUN, Aztec, privacy token bridges |
| **Bridges** | Cross-chain movement | Wormhole, Multichain, THORChain, etc. |

## Risk Scoring

Each scan returns a risk assessment:

```python
{
    "address": "0x...",
    "risk_score": 78,          # 0-100
    "risk_level": "HIGH",      # LOW/MEDIUM/HIGH/CRITICAL
    "flags": [
        {
            "type": "MIXER",
            "severity": "HIGH",
            "details": "Tornado Cash interaction"
        }
    ],
    "summary": "High risk patterns detected: mixer usage"
}
```

### Risk Levels

| Level | Score | Description |
|-------|-------|-------------|
| LOW | 0-25 | Minor or no risk indicators |
| MEDIUM | 26-50 | Some risk indicators present |
| HIGH | 51-75 | Significant risk patterns detected |
| CRITICAL | 76-100 | Severe risk including sanctions matches |

## Data Sources

### File Input

```python
result = scanner.scan_file("transactions.json")  # JSON
result = scanner.scan_file("transactions.csv")   # CSV
```

### API Source (Etherscan)

```python
scanner = Scanner(chain="ethereum")
scanner.use_api_source(api_key="YOUR_ETHERSCAN_API_KEY")
result = scanner.scan_address("0x...", fetch_transactions=True)
```

### Custom Transactions

```python
from chain_scanner import Scanner, Transaction
from decimal import Decimal

transactions = [
    Transaction(
        hash="0xabc...",
        chain="ethereum",
        from_address="0x111...",
        to_address="0x222...",
        value=Decimal("1.5"),
    )
]

result = scanner.scan_transactions(transactions)
```

## Configuration

```python
from chain_scanner import Scanner, ScannerConfig

config = ScannerConfig()
config.structuring.threshold_usd = 10000
config.structuring.min_transactions = 3
config.risk_weights.mixer = 80

scanner = Scanner(chain="ethereum", config=config)
```

Or load from JSON:

```bash
chain-scanner --config config.json scan 0x...
```

## Input File Formats

### JSON

```json
{
  "transactions": [
    {
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "blockNumber": 15000000,
      "timeStamp": "1672531200"
    }
  ]
}
```

### CSV

```csv
hash,from,to,value,blockNumber,timeStamp
0x...,0x...,0x...,1000000000000000000,15000000,1672531200
```

## Development

```bash
git clone https://github.com/cleonard2341/onchain-aml.git
cd onchain-aml
pip install -e ".[dev]"
pytest tests/ -v
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Disclaimer

This tool is for informational and research purposes only. It should not be used as the sole basis for compliance decisions. Always consult with legal and compliance professionals for AML/KYC requirements.

The address lists included are samples for demonstration. For production use, update sanctions and mixer lists regularly from official sources.