Welcome to labChain’s documentation!

This project is a completely new blockchain-based coin, with P2P networking, a consensus mechanism and a wallet interface. The goal of the project is to provide a framework that is easy to modify for people who want to develop proof-of-concepts for blockchain-based technology.

DO NOT USE THIS AS A REAL CURRENCY TO SEND, RETRIEVE, OR STORE ACTUAL MONEY! While we do not currently know of any way to do so, there are almost certainly bugs in this implementation that would allow anyone to create money out of the blue or take yours away from you.


miner The executable that participates in the P2P network and optionally mines new blocks. Can be reached through a REST API by the wallet.
wallet The wallet allows a user to query account balance, send money, and get status information about a miner.

To start a minimal network of two peers that do not mine, you can do this on different machines:

./miner.py --listen-port 1234
./miner.py --bootstrap-peer a.b.c.d:1234

To actually start mining, you’ll need to use the wallet and generate a new address that should receive the mining rewards:

./wallet.py --wallet mining.wallet create-address mining-address.pem

Afterwards, you can copy the file mining-address.pem to the second machine and restart the miner like this:

./miner.py --bootstrap-peer a.b.c.d:1234 --mining-pubkey mining-address.pem

This miner will now mine new blocks for the block chain and send them to the miner application on the other machine. Once some blocks have been mined, you can check how much money you have made like this:

./wallet.py --wallet mining.wallet show-balance

Once you have earned money mining, you can send some of it to someone else. To send them 42 coins (we already know how the other person can generate an address), you can do this:

./wallet.py --wallet mining.wallet transfer other_person_address.pem 42

Both the miner and the wallet have many more options than just these, which can be found using the –help switch of the programs. Especially useful might also be the –rpc-port option of the miner, which needs to be set to different values when one wants to start more than one instance on the same computer:

./miner.py --rpc-port 2345 --listen-port 1234
./miner.py --rpc-port 3456 --bootstrap-peer
./wallet.py --miner-port 2345 --wallet mining.wallet show-balance

Source Code Documentation

src.blockchain Definition of block chains.
src.block Definitions of blocks, and the genesis block.
src.chainbuilder The chain builder maintains the current longest confirmed (primary) block chain as well as only partially downloaded longer chains that might become the new primary block chain once completed and verified.
src.crypto Generic functions for the cryptographic primitives used in this project.
src.merkle Functionality for creating a Merkle tree.
src.mining Functionality for mining new blocks.
src.mining_strategy Defines the contents of newly mined blocks.
src.proof_of_work Implementation and verification of the proof of work.
src.protocol Implementation of the P2P protocol.
src.transaction Defines transactions and their inputs and outputs.
src.persistence Functionality for storing and retrieving the miner state on disk.
src.rpc_client The RPC functionality used by the wallet to talk to the miner application.
src.rpc_server The RPC functionality the miner provides for the wallet.


To run the tests, just run the pytest command.

Indices and tables