Prerequisites#

• Python 3.7+
• Apache Spark
• Google Colab (for the provided notebook) or local Jupyter environment
• Sufficient storage space for blockchain data

Dependencies#

Install the required packages:

pip install pyspark
pip install PyDrive
pip install wget
pip install pyvis
pip install streamlit
pip install networkx
pip install matplotlib

Setup#

1. Clone the repository:

git clone https://github.com/VincenzoImp/Bitcoin-Address-Clustering.git
cd Bitcoin-Address-Clustering

2. Configure Spark context with appropriate memory settings:

conf = SparkConf()\
    .set('spark.executor.memory', '50G')\
    .set('spark.driver.memory', '50G')\
    .set('spark.driver.maxResultSize', '50G')\
    .set("spark.driver.cores", "10")\
    .set("spark.sql.analyzer.maxIterations", "100000")

Basic Usage#

1. Set Global Constants:

start_block = 0
end_block = 115000

2. Download Dataset:

v_path, e_path, a_path, d_path = download_dataset(start_block, end_block, DATA_DIR, spark, True)

3. Generate Transaction Graph:

nx_graph = generate_nx_graph(v_df, e_df, graph_path, start_block, end_block, True)

4. Apply Clustering Algorithm:

clustered_addresses = address_clustering(nx_graph, a_df, known_tx_df, spark, start_block, debug=True)

Web Application#

Launch the interactive web interface:

streamlit run app.py 0 115000

Simple Heuristics#

1. Satoshi Heuristic: Groups addresses from early coinbase transactions (blocks < 19,500) as likely belonging to Satoshi Nakamoto

2. Coinbase Transaction Mining Address Clustering: Assumes all output addresses from coinbase transactions belong to the same miner

3. Common-Input-Ownership: Groups all input addresses in multi-input transactions as belonging to the same entity

4. Single Input/Output: Treats single input, single output transactions as address movements within the same entity

5. Consolidation Transaction: Groups addresses in transactions with multiple inputs and single output

Advanced Heuristics#

6. Payment Transaction Analysis: Identifies payment transactions with change addresses

7. Change Address Detection: Uses multiple sub-heuristics:

   • Same address in input and output
   • Address reuse patterns
   • Unnecessary input analysis
   • New address identification
   • Round number detection

8. Mixed Transaction Recognition: Identifies and handles CoinJoin transactions using taint analysis

Clustering Effectiveness#

• Initial Addresses: ~1,000,000 unique addresses
• After Clustering: ~550,000 entities (45% reduction)
• With Small Cluster Assumption: ~220,000 entities (78% reduction)

Entity Distribution#

The clustering reveals a power-law distribution of entity sizes:

• Most entities contain 1-2 addresses
• Few large entities contain hundreds of addresses
• Largest clusters likely represent exchanges or major services

Features:#

• Interactive network visualization using PyVis
• Real-time address clustering
• Detailed transaction information
• Export capabilities

1. Entity Movement Visualization#

Track how funds move between addresses belonging to the same entity:

address = '115uADbwcLhfKeWJzy7EHjSWjn3dpHK1vZ'
cluster_graph = visualize_entity_movements(address)

2. Chain Analysis Queries#

Answer specific questions about blockchain activity:

• “How many unique miners were active before 2011?”
• “What’s the largest entity by address count?”
• “Which entities show mixing behavior?“

3. Research Applications#

• Academic research on Bitcoin privacy
• Compliance and AML investigations
• Cryptocurrency forensics
• Network analysis studies

Development Guidelines#

1. Follow PEP 8 style guidelines
2. Add comprehensive docstrings
3. Include unit tests for new heuristics
4. Update documentation for new features