chain-scanner 0.1.0

On-chain AML pattern detection tool for cryptocurrency transactions

Onchain AML

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

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

Or install from source:

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

Quick Start

Command Line

# 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

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:

{
    "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

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

API Source (Etherscan)

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

Custom Transactions

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

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:

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

Input File Formats

JSON

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

CSV

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

Development

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

License

MIT License - see 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.