This is the documentation of Blockchain a simple implementation in Python to get familiar with Python and the basic concepts of Blockchains.
It is just a private
Python 3.7.2 project. Its purposes is to get a little bit familiar with the Python projects and the concepts of Blockchains.
Therefore it is not intended for production usage, and any warranties are excluded.
The easiest way to get up a single miner or a whole blockchain network is to use Docker. This repository offers the needed
docker-compose.yaml in the directory
Do the following steps:
- Change to
docker build --no-cache -t blockchain .
This starts a Blockchain network with 3 miners and forwards their ports (12345, 12346, 12347) to your host system.
It uses the directory
~/.blockchain/ on your host system to save the created files for each miner.
Install the CLI Locally¶
- Clone this repository:
git clone firstname.lastname@example.org:se-jaeger/blockchain.git
- Open the clone directory:
- Create a virtual env:
python -m venv venv
- Activate the virtual env:
- Install all dependencies:
pip install -r requirements.txt
- Install the
blockchainCLI, run the following in the root directory of this project:
pip install -e .
- Check available commands:
How Does This Blockchain Implementation Work?¶
This implementation produces a simple
UI. It is necessary to get up and running a local Miner.
The CLI, as well as the UI, uses the Miners
REST interface to interact with it.
messages get synchronized with all other known Miners (
neighbours) in the Blockchain network.
A Miner asks all its neighbours periodically (if not max amount of neighbours is reached) to send unknown Miner and connects to them.
Also in a periodical manner, Miner synchronizes their local Blockchain with the chains of there neighbours and use the longest valid chain in the network.
This Miner implementation offers a REST API with the following endpoints:
/add(PUT): needs the URL parameter
message. Adds the message to the local cache of unprocessed data.
response(200): JSON with message: ‘Message added!’
response(400): JSON with message: ‘No Message added!’
/chain(GET): Returns the miners local chain.
response(200): JSON with the actual chain and its length.
/neighbours(GET): Returns the miners neighbours.
response(200): JSON with the actual neighbours and its length.
/data(GET): Returns the miners local cache of unprocessed data.
response(200): JSON with the actual list of unprocessed data.
The miner uses a set of files for normal operation:
<filename>.chain: Representation of the actual file.
SHA-256of the actual chain file. Is used to check if the local chain differs from its on disc representation.
<filename>_<date>_<time>: Older versions of the chain file. Created at
miner.log: Log file and up to three backup files named
xis a number.
The Miner runs several Threads and a Process to run parallel and periodical tasks:
Gossip Job(Thread): Implementation of a simple
Gossip Protocol. Fetches periodical all
Sync Chain Job(Thread): To get the actual longest global chain. Fetches periodical the chain of all
Sync Unprocessed Data Job(Thread): To propagate unprocessed data through the network. Fetches periodical the set of unprocessed data of all
Backup Local Chain Job(Thread): To backup the local chain to disc. Backups periodical the local chain to disc if they differ from each other.
Server Process(Process): Servers the Miners REST API in a separate process.
Communication Job(Thread): Communication thread to exchange message with the server process.
Web-based User Interface¶
CLI offers a subcommand
ui, this allows to start an webserver for convenient interaction with the blockchain system.
Proof of Work¶
A very simple implementation of a
Proof of Work algorithm.
SHA-256 hash value of the concatenation of the previous
proof and the
proof of the new Block has to start with
difficulty trailing 0s.
- Miner endpoint (health) to check availability and provide opportunity to delete a neighbour
- More Error handling -> chain probably gets corrupt when killing miner
- Use locking for (chain, neighbours, data)