bitcoin-address-risk-model-v2

Bitcoin Address Risk Model (v2) — Ransomware Detection

This model is a LightGBM classifier trained on the UCI BitcoinHeist Ransomware Address Dataset to identify Bitcoin addresses associated with ransomware activities. It's designed as a standalone risk signal and should be combined with other intelligence in a production environment.

Dataset

• Name: UCI BitcoinHeist Ransomware Address Dataset
• Source: UCI Machine Learning Repository (Dataset ID 526)
• Task: Binary address-risk classification: white=0, ransomware family=1
• Raw Instances: 2,916,697
• Aggregation: Daily observations aggregated to one row per Bitcoin address

Features

The model uses native address/graph behavioral features from the BitcoinHeist dataset, along with address-level aggregates. These include: length, weight, count, looped, neighbors, income, snapshot_count, active_span_days, avg_daily_income

Model Performance (Test Set)

• Tuned Threshold: 0.625
• Accuracy: 0.9288
• Precision: 0.6067
• Recall: 0.6990
• F1 Score: 0.6496
• AUC-ROC: 0.9346
• PR-AUC: 0.7127

Usage Notes

This model is a ransomware-focused research/training signal. In production, combine its score with live tracing, graph analysis, VASP data, and case-specific rules. It is not a universal modern scam classifier.

Files

• bitcoin_address_risk_model.pkl: The trained LightGBM model.
• metrics_summary.json: A JSON file containing a detailed summary of the model, dataset, and performance metrics.
• confusion_matrix.png: Visualization of the confusion matrix on the test set.
• shap_summary.png: SHAP plot showing feature importances.

How to Use

import pandas as pd
import lightgbm as lgb
from huggingface_hub import hf_hub_download
import pickle

# Download the model file
model_path = hf_hub_download(repo_id="jb10231/bitcoin-address-risk-model-v2", filename="bitcoin_address_risk_model.pkl")

# Load the model
with open(model_path, 'rb') as f:
    model = pickle.load(f)

# Example data (replace with your actual data)
# Make sure your feature columns match the training data
example_data = pd.DataFrame([{
    'length': 10,
    'weight': 0.5,
    'count': 50,
    'looped': 0,
    'neighbors': 3,
    'income': 1000000000,
    'snapshot_count': 5,
    'active_span_days': 30,
    'avg_daily_income': 200000000
}])

# Make a prediction
prediction_proba = model.predict(example_data)
print(f"Prediction probability: {prediction_proba[0]:.4f}")

# Apply the tuned threshold (you might download this from the metrics_summary.json)
tuned_threshold = 0.625 # Example threshold
prediction_label = (prediction_proba[0] >= tuned_threshold).astype(int)
print(f"Predicted label (0=Benign, 1=Illicit): {prediction_label}")

Citation

If you use the underlying dataset, please cite:

*"A. V. M. F. Ribeiro, A. H. C. Oliveira, L. C. R. de Souza, C. R. P. Souza and R. A. F. Lima, "BitcoinHeist Ransomware Address Dataset," in IEEE Latin America Transactions, vol. 18, no. 12, pp. 2097-2104, December 2020, doi: 10.1109/TLA.2020.3045262."