Learn Blockchains by Building One

The fastest way to learn how Blockchains work is to build one You’re here because, like me, you’re psyched about the rise of Cryptocurrencies. And you want to know how Blockchains work—the fundamental technology behind them. But understanding Blockchains isn’t easy—or at least wasn’t for me. I trudged through dense videos, followed porous tutorials, and dealt with the amplified frustration of too few examples. I like learning by doing. It forces me to deal with the subject matter at a code level, which gets it sticking. If you do the same, at the end of this guide you’ll have a functioning Blockchain with a solid grasp of how they work. Before you get started… Remember that a blockchain is an chain of records called Blocks. They can contain transactions, files or any data you like, really. But the important thing is that they’re together using . immutable, sequential chained hashes If you aren’t sure what a hash is, . here’s an explanation You should be comfy reading and writing some basic Python, as well as have some understanding of how HTTP requests work, since we’ll be talking to our Blockchain over HTTP. Who is this guide aimed at? Make sure that + (along with pip) is installed. You’ll also need to install Flask and the wonderful Requests library: What do I need? Python 3.6 pip install Flask== requests== 0.12 .2 2.18 .4 Oh, you’ll also need an HTTP Client, like or cURL. But anything will do. Postman The source code is . Where’s the final code? available here Step 1: Building a Blockchain Open up your favourite text editor or IDE, personally I ❤️ . Create a new file, called . We’ll only use a single file, but if you get lost, you can always refer to the . PyCharm blockchain.py source code Representing a Blockchain We’ll create a class whose constructor creates an initial empty list (to store our blockchain), and another to store transactions. Here’s the blueprint for our class: Blockchain = [] self.current_transactions = [] def new_block(self): # Creates a Block and adds it to the chain pass def new_transaction(self): # Adds a transaction to the list transactions pass @staticmethod def hash(block): # Hashes a Block pass @property def last_block(self): # Returns the last Block the chain pass ( ): ( ): . class Blockchain object def __init__ self self chain new new of in (Blueprint of our Blockchain Class) Our class is responsible for managing the chain. It will store transactions and have some helper methods for adding new blocks to the chain. Let’s start fleshing out some methods. Blockchain What does a Block look like? Each Block has an , a (in Unix time), a , a (more on that later), and the . index timestamp list of transactions proof hash of the previous Block Here’s an example of what a single Block looks like: block = { : , : , : [ { : , : , : , } ], : , : } 'index' 1 'timestamp' 1506057125.900785 'transactions' 'sender' "8527147fe1f5426f9dd545de4b27ee00" 'recipient' "a77f5cdfa2934df3954a5c7c7da5df1f" 'amount' 5 'proof' 324984774000 'previous_hash' "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824" ( Example of a Block in our Blockchain) At this point, the idea of a should be apparent—each new block contains within itself, the hash of the previous Block. If an attacker corrupted an earlier Block in the chain then subsequent blocks will contain incorrect hashes. chain This is crucial because it’s what gives blockchains immutability: all Does this make sense? If it doesn’t, take some time to let it sink in—it’s the core idea behind blockchains. Adding Transactions to a Block We’ll need a way of adding transactions to a Block. Our method is responsible for this, and it’s pretty straight-forward: new_transaction() { : sender, : recipient, : amount, }) self.last_block[ ] + ( ): ... ( , , , ): """ : : : : : : : : """ . . ( class Blockchain object def new_transaction self sender recipient amount Creates a new transaction to go into the next mined Block param sender str Address of the Sender param recipient str Address of the Recipient param amount int Amount return int The index of the Block that will hold this transaction self current_transactions append 'sender' 'recipient' 'amount' return 'index' 1 After adds a transaction to the list, it returns the of the block which the transaction will be added to— This will be useful later on, to the user submitting the transaction. new_transaction() index the next one to be mined. Creating new Blocks When our is instantiated we’ll need to seed it with a block—a block with no predecessors. We’ll also need to add a to our genesis block which is the result of mining (or proof of work). We’ll talk more about mining later. Blockchain genesis “proof” In addition to creating the block in our constructor, we’ll also flesh out the methods for , and : genesis new_block() new_transaction() hash() hashlib json time time = [] self.chain = [] # Create the genesis block self.new_block(previous_hash= , proof= ) def new_block(self, proof, previous_hash=None): block = { : len(self.chain) + , : time(), : self.current_transactions, : proof, : previous_hash or self.hash(self.chain[ ]), } # Reset the current list transactions self.current_transactions = [] self.chain.append(block) block def new_transaction(self, sender, recipient, amount): self.current_transactions.append({ : sender, : recipient, : amount, }) self.last_block[ ] + @property def last_block(self): self.chain[ ] @staticmethod def hash(block): # We must make sure that the Dictionary is Ordered, or we import import from import ( ): ( ): . class Blockchain object def __init__ self self current_transactions 1 100 "" " Create a new Block in the Blockchain :param proof: The proof given by the Proof of Work algorithm :param previous_hash: (Optional) Hash of previous Block :return: New Block " "" 'index' 1 'timestamp' 'transactions' 'proof' 'previous_hash' -1 of return "" " Creates a new transaction to go into the next mined Block :param sender: Address of the Sender :param recipient: Address of the Recipient :param amount: Amount :return: The index of the Block that will hold this transaction " "" 'sender' 'recipient' 'amount' return 'index' 1 return -1 "" " Creates a SHA-256 hash of a Block :param block: Block :return: " "" 'll have inconsistent hashes block_string = json.dumps(block, sort_keys=True).encode() return hashlib.sha256(block_string).hexdigest() The above should be straight-forward—I’ve added some comments and to help keep it clear. We’re almost done with representing our blockchain. But at this point, you must be wondering how new blocks are created, forged or mined. docstrings Understanding Proof of Work A Proof of Work algorithm (PoW) is how new Blocks are created or on the blockchain The goal of PoW is to discover a number which solves a problem. The number must be —computationally speaking—by anyone on the network. This is the core idea behind Proof of Work. mined . difficult to find but easy to verify We’ll look at a very simple example to help this sink in. Let’s decide that the of some integer x multiplied by another y must end in 0. So, . And for this simplified example, let’s fix . Implementing this in Python: hash hash(x * y) = ac23dc...0 x = 5 hashlib sha256 x = y = # We don {x*y} The solution is y = {y} from import 5 0 't know what y should be yet... while sha256(f' '.encode()).hexdigest()[-1] != "0": y += 1 print(f' ') The solution here is . Since, the produced hash ends in 0: y = 21 hash( * ) = e.. e860 5 21 1253e9373 .5e3600155 In Bitcoin, the Proof of Work algorithm is called . And it’s not too different from our basic example above. It’s the algorithm that miners race to solve in order to create a new block. In general, the difficulty is determined by the number of characters searched for in a string. The miners are then rewarded for their solution by receiving a coin—in a transaction. Hashcash The network is able to verify their solution. easily Implementing basic Proof of Work Let’s implement a similar algorithm for our blockchain. Our rule will be similar to the example above: p Find a number that when hashed with the previous block’s solution a hash with 4 leading 0s is produced. hashlib json time time uuid uuid4 = self.valid_proof(last_proof, proof) is False: proof += proof @staticmethod def valid_proof(last_proof, proof): guess = f .encode() guess_hash = hashlib.sha256(guess).hexdigest() guess_hash[: ] == import import from import from import ( ): ... ( , ): """ : - ' ( ') 4 , ' - , ' : : : : """ class Blockchain object def proof_of_work self last_proof Simple Proof of Work Algorithm Find a number p such that hash pp contains leading zeroes where p is the previous p p is the previous proof and p is the new proof param last_proof int return int proof 0 while 1 return "" " Validates the Proof: Does hash(last_proof, proof) contain 4 leading zeroes? :param last_proof: Previous Proof :param proof: Current Proof :return: True if correct, False if not. " "" '{last_proof}{proof}' return 4 "0000" To adjust the difficulty of the algorithm, we could modify the number of leading zeroes. But 4 is sufficient. You’ll find out that the addition of a single leading zero makes a mammoth difference to the time required to find a solution. Our class is almost complete and we’re ready to begin interacting with it using HTTP requests. Step 2: Our Blockchain as an API We’re going to use the Python Flask Framework. It’s a micro-framework and it makes it easy to map endpoints to Python functions. This allows us talk to our blockchain over the web using HTTP requests. We’ll create three methods: to create a new transaction to a block /transactions/new to tell our server to mine a new block. /mine to return the full Blockchain /chain Setting up Flask Our “server” will form a single node in our blockchain network. Let’s create some boilerplate code: hashlib json textwrap dedent time time uuid uuid4 flask Flask = Flask(__name__) # Generate a globally unique address node node_identifier = str(uuid4()).replace( , ) # Instantiate the Blockchain blockchain = Blockchain() @app.route( , methods=[ ]) def mine(): @app.route( , methods=[ ]) def new_transaction(): @app.route( , methods=[ ]) def full_chain(): response = { : blockchain.chain, : len(blockchain.chain), } jsonify(response), __name__ == : app.run(host= , port= ) import import from import from import from import from import ( ): ... # class Blockchain object Instantiate our Node app for this '-' '' '/mine' 'GET' return "We'll mine a new Block" '/transactions/new' 'POST' return "We'll add a new transaction" '/chain' 'GET' 'chain' 'length' return 200 if '__main__' '0.0.0.0' 5000 A brief explanation of what we’ve added above: Instantiates our Node. Read more about Flask . Line 15: here Create a random name for our node. Line 18: Instantiate our class. Line 21: Blockchain Create the endpoint, which is a request. Line 24–26: /mine GET Create the endpoint, which is a request, since we’ll be sending data to it. Line 28–30: /transactions/new POST Create the endpoint, which returns the full Blockchain. Line 32–38: /chain Runs the server on port 5000. Line 40–41: The Transactions Endpoint This is what the request for a transaction will look like. It’s what the user sends to the server: { : , : , : } "sender" "my address" "recipient" "someone else's address" "amount" 5 Since we already have our class method for adding transactions to a block, the rest is easy. Let’s write the function for adding transactions: hashlib json textwrap dedent time time uuid uuid4 flask Flask, jsonify, request ... @app.route( , methods=[ ]) def new_transaction(): values = request.get_json() # Check that the required fields are the POST sender recipient amount Missing values sender recipient amount message Transaction will be added to Block {index} import import from import from import from import from import '/transactions/new' 'POST' in 'ed data required = [' ', ' ', ' '] if not all(k in values for k in required): return ' ', 400 # Create a new Transaction index = blockchain.new_transaction(values[' '], values[' '], values[' ']) response = {' ': f' '} return jsonify(response), 201 ( A method for creating Transactions) The Mining Endpoint Our mining endpoint is where the magic happens, and it’s easy. It has to do three things: Calculate the Proof of Work Reward the miner (us) by adding a transaction granting us 1 coin Forge the new Block by adding it to the chain hashlib json time time uuid uuid4 flask Flask, jsonify, request ... @app.route( , methods=[ ]) def mine(): # We run the proof work algorithm to get the next proof... last_block = blockchain.last_block last_proof = last_block[ ] proof = blockchain.proof_of_work(last_proof) # We must receive a reward finding the proof. # The sender is to signify that node has mined a coin. blockchain.new_transaction( sender= , recipient=node_identifier, amount= , ) # Forge the Block by adding it to the chain previous_hash = blockchain.hash(last_block) block = blockchain.new_block(proof, previous_hash) response = { : , : block[ ], : block[ ], : block[ ], : block[ ], } jsonify(response), import import from import from import from import '/mine' 'GET' of 'proof' for "0" this new "0" 1 new 'message' "New Block Forged" 'index' 'index' 'transactions' 'transactions' 'proof' 'proof' 'previous_hash' 'previous_hash' return 200 Note that the recipient of the mined block is the address of our node. And most of what we’ve done here is just interact with the methods on our Blockchain class. At this point, we’re done, and can start interacting with our blockchain. Step 3: Interacting with our Blockchain You can use plain old cURL or Postman to interact with our API over a network. Fire up the server: $ python blockchain.py * Running on http: //127.0.0.1:5000/ (Press CTRL+C to quit) Let’s try mining a block by making a request to : GET http://localhost:5000/mine ( Using Postman to make a GET request) Let’s create a new transaction by making a request to with a body containing our transaction structure: POST http://localhost:5000/transactions/new ( Using Postman to make a POST request) If you aren’t using Postman, then you can make the equivalent request using cURL: $ curl -X POST -H -d "Content-Type: application/json" '{ "sender": "d4ee26eee15148ee92c6cd394edd974e", "recipient": "someone-other-address", "amount": 5 }' "http://localhost:5000/transactions/new" I restarted my server, and mined two blocks, to give 3 in total. Let’s inspect the full chain by requesting http://localhost:5000/chain { : [ { : , : , : , : , : [] }, { : , : , : , : , : [ { : , : , : } ] }, { : , : , : , : , : [ { : , : , : } ] } ], : } "chain" "index" 1 "previous_hash" 1 "proof" 100 "timestamp" 1506280650.770839 "transactions" "index" 2 "previous_hash" "c099bc...bfb7" "proof" 35293 "timestamp" 1506280664.717925 "transactions" "amount" 1 "recipient" "8bbcb347e0634905b0cac7955bae152b" "sender" "0" "index" 3 "previous_hash" "eff91a...10f2" "proof" 35089 "timestamp" 1506280666.1086972 "transactions" "amount" 1 "recipient" "8bbcb347e0634905b0cac7955bae152b" "sender" "0" "length" 3 Step 4: Consensus This is very cool. We’ve got a basic Blockchain that accepts transactions and allows us to mine new Blocks. But the whole point of Blockchains is that they should be . And if they’re decentralized, how on earth do we ensure that they all reflect the same chain? This is called the problem of , and we’ll have to implement a Consensus Algorithm if we want more than one node in our network. decentralized Consensus Registering new Nodes Before we can implement a Consensus Algorithm, we need a way to let a node know about neighbouring nodes on the network. Each node on our network should keep a registry of other nodes on the network. Thus, we’ll need some more endpoints: to accept a list of new nodes in the form of URLs. /nodes/register to implement our Consensus Algorithm, which resolves any conflicts—to ensure a node has the correct chain. /nodes/resolve We’ll need to modify our Blockchain’s constructor and provide a method for registering nodes: ... from urllib.parse urlparse ... class Blockchain(object): def __init__(self): ... self.nodes = set() ... def register_node(self, address): parsed_url = urlparse(address) self.nodes.add(parsed_url.netloc) import "" " Add a new node to the list of nodes :param address: Address of node. Eg. 'http://192.168.0.5:5000' :return: None " "" ( A method for adding neighbouring nodes to our Network) Note that we’ve used a to hold the list of nodes. This is a cheap way of ensuring that the addition of new nodes is idempotent—meaning that no matter how many times we add a specific node, it appears exactly once. set() Implementing the Consensus Algorithm As mentioned, a conflict is when one node has a different chain to another node. To resolve this, we’ll make the rule that In other words, the longest chain on the network is the one. Using this algorithm, we reach amongst the nodes in our network. the longest valid chain is authoritative. de-facto Consensus ... import requests = chain[ ] current_index = current_index < len(chain): block = chain[current_index] print(f ) print(f ) print( ) # Check that the hash the block is correct block[ ] != self.hash(last_block): False # Check that the Proof Work is correct not self.valid_proof(last_block[ ], block[ ]): False last_block = block current_index += True def resolve_conflicts(self): neighbours = self.nodes new_chain = None # We http: response.status_code == : length = response.json()[ ] chain = response.json()[ ] # Check the length is longer and the chain is valid length > max_length and self.valid_chain(chain): max_length = length new_chain = chain # Replace our chain we discovered a , valid chain longer than ours new_chain: self.chain = new_chain True False ( ) ... ( , ): """ : : : : , """ class Blockchain object def valid_chain self chain Determine if a given blockchain is valid param chain list A blockchain return bool True if valid False if not last_block 0 1 while '{last_block}' '{block}' "\n-----------\n" of if 'previous_hash' return of if 'proof' 'proof' return 1 return "" " This is our Consensus Algorithm, it resolves conflicts by replacing our chain with the longest one in the network. :return: True if our chain was replaced, False if not " "" 're only looking for chains longer than ours max_length = len(self.chain) # Grab and verify the chains from all the nodes in our network for node in neighbours: response = requests.get(f' //{node}/chain') if 200 'length' 'chain' if if if new if return return The first method is responsible for checking if a chain is valid by looping through each block and verifying both the hash and the proof. valid_chain() is a method which loops through all our neighbouring nodes, their chains and verifies them using the above method. resolve_conflicts() downloads If a valid chain is found, whose length is greater than ours, we replace ours. Let’s register the two endpoints to our API, one for adding neighbouring nodes and the another for resolving conflicts: @app.route( , methods=[ ]) def register_nodes(): values = request.get_json() nodes = values.get( ) nodes is None: , node nodes: blockchain.register_node(node) response = { : , : list(blockchain.nodes), } jsonify(response), @app.route( , methods=[ ]) def consensus(): replaced = blockchain.resolve_conflicts() replaced: response = { : , : blockchain.chain } : response = { : , : blockchain.chain } jsonify(response), '/nodes/register' 'POST' 'nodes' if return "Error: Please supply a valid list of nodes" 400 for in 'message' 'New nodes have been added' 'total_nodes' return 201 '/nodes/resolve' 'GET' if 'message' 'Our chain was replaced' 'new_chain' else 'message' 'Our chain is authoritative' 'chain' return 200 At this point you can grab a different machine if you like, and spin up different nodes on your network. Or spin up processes using different ports on the same machine. I spun up another node on my machine, on a different port, and registered it with my current node. Thus, I have two nodes: and . http://localhost:5000 http://localhost:5001 ( Registering a new Node) I then mined some new Blocks on node 2, to ensure the chain was longer. Afterward, I called on node 1, where the chain was replaced by the Consensus Algorithm: GET /nodes/resolve ( Consensus Algorithm at Work) And that’s a wrap... Go get some friends together to help test out your Blockchain. I hope that this has inspired you to create something new. I’m ecstatic about Cryptocurrencies because I believe that Blockchains will rapidly change the way we think about economies, governments and record-keeping. I’m planning on following up with a Part 2, where we’ll extend our Blockchain to have a Transaction Validation Mechanism as well as discuss some ways in which you can productionize your Blockchain. Update: If you enjoyed this guide, or have any suggestions or questions, let me know in the comments. And if you’ve spotted any errors, feel free to contribute to the code here ! Agree or disagree with some of the ideas presented in this article? Let us know your thoughts on Digg. Looking for more Blockchain articles? Subscribe to our newsletter in the footer below! Check out our podcast on blockchain.