How to Import the Bitcoin Blockchain into Neo4j

This guide provides step-by-step instructions for importing the Bitcoin blockchain into a Neo4j graph database. By converting blockchain data into a graph structure, you unlock powerful analytical capabilities—like tracing bitcoin flows between addresses—that traditional SQL databases can't match.

👉 Explore advanced blockchain analytics with Neo4j

Understanding Bitcoin and Blockchain Basics

What Is Bitcoin?

Bitcoin is a decentralized digital currency powered by a peer-to-peer network. Its core innovation is the blockchain—an immutable, distributed ledger recording all transactions.

• Key Features:

  • Decentralized: No central authority controls the network.
  • Immutable: Transactions cannot be altered once confirmed.
  • Transparent: All transactions are publicly verifiable.

Blockchain Data Structure

The blockchain consists of sequential blocks, each containing multiple transactions.

• Storage Locations:

  • Linux: ~/.bitcoin/blocks
  • Mac: ~/Library/Application Support/Bitcoin/blocks
  • Windows: C:UsersYourUserNameAppdataRoamingBitcoinblocks

Files named blkXXXXX.dat store serialized block and transaction data.

Preparing Blockchain Data for Neo4j

Parsing blk.dat Files

1. Blocks: Begin with magic bytes, followed by block size and header metadata (e.g., timestamp, nonce).
2. Transactions: Structured as inputs (unlocking previous outputs) and outputs (locking to new addresses).

Example Transaction Hex:

0200000001f2f7ee9dda0ba82031858d30d50d3205eea07246c874a0488532014d3b653f03000000006a47304402204df1839028a05b5b303f5c85a66affb7f6010897d317ac9e88dba113bb5a0fe9022053830b50204af15c85c9af2b446338d049672ecfdeb32d5124e0c3c2256248b7012102c06aec784f797fb400001c60aede8e110b1bbd9f8503f0626ef3a7e0ffbec93bfeffffff0200e1f505000000001976a9144120275dbeaeb40920fc71cd8e849c563de1610988ac9f166418000000001976a91493fa3301df8b0a268c7d2c3cc4668ea86fddf81588ac61610700

Importing Data into Neo4j

Graph Representation

• Blocks: Nodes with properties like hash, timestamp, and nonce.
• Transactions: Nodes linked to blocks, with version and locktime attributes.
• Addresses: Nodes connected to transaction outputs.

Cypher Queries

1. Inserting a Block

MERGE (block:block {hash: $blockhash})
CREATE UNIQUE (block)-[:coinbase]->(:output:coinbase)
SET block.size = $size, block.prevblock = $prevblock, block.time = $timestamp
MERGE (prevblock:block {hash: $prevblock})
MERGE (block)-[:chain]->(prevblock)

2. Inserting a Transaction

MATCH (block :block {hash: $hash})
MERGE (tx:tx {txid: $txid})
MERGE (tx)-[:inc {i: $i}]->(block)
FOREACH (input IN $inputs | 
  MERGE (in :output {index: input.index})
  MERGE (in)-[:in {scriptSig: input.scriptSig}]->(tx)
)

👉 Optimize your blockchain queries with Neo4j

Analyzing Blockchain Data

Useful Cypher Queries

Trace Bitcoin Flow Between Addresses

MATCH path=shortestPath(
  (:address {address: $address1})-[:locked|:in|:out*]-(:address {address: $address2})
) RETURN path

Fetch Transaction Details

MATCH (inputs)-[:in]->(tx:tx)-[:out]->(outputs)
WHERE tx.txid = $txid
RETURN inputs, tx, outputs

FAQ

Why use Neo4j for blockchain data?

Graph databases natively represent transactional relationships, enabling efficient pathfinding and clustering analysis.

How do I handle SegWit transactions?

SegWit transactions require slight adjustments to the parsing logic but follow the same graph structure.

Can I import only specific blocks?

Yes—filter blocks by height or hash during the import process.

Conclusion

Importing Bitcoin data into Neo4j transforms raw blockchain records into an analyzable graph. This approach reveals hidden patterns, like money flow between wallets, with unmatched clarity.

Next Steps:

• Explore bitcoin-to-neo4j on GitHub for reference code.
• Experiment with larger datasets to uncover deeper insights.