You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

4.3 KiB


build-success test-passing status-stable

Blockchain + MongoDB = BlockchainDB

blockchainDB is Blockchain's implementation. It uses MongoDB as a database management system to store blocks' metadata. Other interesting technical details such as merkle tree, nonce, difficulty, and transactions are also implemented and documented in the source code.


Project Status

It is done for the most part. Below are ideas for future implementations.


  • Model Bitcoin's blockchain structure
  • Implement Proof of Work, nonce, difficulty
  • Enable transactions
  • Implement Merkle Tree
  • Introduce mining mechanics
  • Introduce block reward
  • Remember elapsed time and hash power metrics for later analytics
  • Expose RESTful APIs, with simple UI
  • Store the full chain in mongodb


  • Dockerize the project
  • Introduce networking with multiple nodes. For now, it only works with one node, which is the local host
  • Introduce Wallet
  • Introduce Attack

Table of Contents

Files and structure

This file contains the main BlockchainDB logic. I am using pymongo to connect with mongodb database named blockchain and the block collection. Whenever a new bock is mined, it will write to the database.

Block structure

block = {
    "previous_block": <str>,
    'height': <int>,
    'timestamp': <unix time>,
    'transactions': <list>,
    "merkle_root": <str>,
    'number_of_transaction': <int>,
    'nonce': <int>,
    'previous_hash': <str>,
    'block_reward': <int>,
    'difficulty_bits': <int>,
    'difficulty': <int>,
    'elapsed_time': <int>,
    'hash_power': <int>


Here are the main methods. Details are well documented in doctrings.

  • generate_genesis_block()
  • generate_next_block(nonce, previous_hash=None)
  • add_transaction(sender, recipient, amount)
  • find_merkle_root(transaction_ids)
  • mine_for_next_block()
  • calculate_nonce(last_block, number_of_bits)
  • calculate_block_reward()
  • calculate_difficulty_bits()
  • calculate_difficulty()
  • hash_json_object(json_object)
  • hash_string_pair(string_1, string_2)

GET methods

  • get_length()
  • get_last_n_blocks(number)
  • get_top_blocks(state, number)
  • get_last_block()
  • get_genesis_block()
  • get_block(height)
  • get_all_blocks()
  • get_transaction_ids()

This file uses Flask to serve as a web page.


Endpoint Description
/reset Drop the database and create a genesis block
/mine/<int:number> Mine a number of blocks over network
/view/chain View the whole blockchain
/view/last_blocks/<int:number> View some number of last mined blocks
/view/last_block View the last mined block
/view/genesis_block View the genesis block
/view/block/<int:number> View a specific block
/view/top/<int:number>/<string:state> View top numbers of blocks for a given state


With networking

  • In src, start and visit localhost:5000
  • Hit /reset endpoint to create a genesis block. This endpoints can also be used to drop the database and start over whenever you want to.
  • Mine some number of blocks at /mine/<int:number>
  • Use available /view endpoints as mentioned above for more details.

Without networking

  • Use to create an instance of BlockchainDB to mine some blocks.
  • Execute reset() only once when you start to drop the old database and create a genesis block.
  • Comment it out after the second run and try to mine some blocks with the provided testing script.
  • Similar to the first option, start in src to serve as a web page and view the result on the web or just print it using the console.