A naive blockchain/cryptocurrency implementation for educational purposes.

UCLCoin is distributed on PyPI and is available on Linux/macOS and Windows and supports Python 3.6+.

$ pip install -U uclcoin

For the following code examples it is assumed that the necessary dependecies were imported.

>>> from uclcoin import KeyPair, Transaction, Block, BlockChain

The private key is used to sign transactions and the public key is your UCLCoin address. It is used to receive coins from transactions and rewards from mining.

Use the KeyPair class to generate your keys

>>> wallet = KeyPair()
>>> address = wallet.public_key
>>> address
'03d70f9a58c9bc6d8fdc47f96d6931f14a7abb0d72cd76886ee05047023fd49471'

To reuse your key pair instantiate the class using your private key wallet.private_key

>>> wallet = KeyPair('your-private-key')

Create a new BlockChain for doing your tests:

>>> blockchain = BlockChain()

Your blockchain will contain only the Genesis block. It is ready to accept transactions, but you can't send any coins if your balance is zero.

>>> blockchain.get_balance(wallet.public_key)
0

Get a new minable block from the blockchain:

>>> new_block = blockchain.get_minable_block(wallet.public_key)

The blockchain returns a new block with the next valid index, any pending transactions and a coinbase (reward) transaction to your public key (wallet.public_key)

UCLCoin the proof of work consists on manipulating the nonce field and recalculating the block hash until it starts with N zeros. The current difficulty can be obtained with the calculate_hash_difficulty method.

>>> N = blockchain.calculate_hash_difficulty()

A simple mining method is to increment the nonce until you get a valid hash:

>>> while new_block.current_hash[:N].count('0') < N:
...     new_block.nonce +=1
...     new_block.recalculate_hash()

The operation will block while the hash is calculated. After finishing just submit the new block to the blockchain. If it is accepted your balance will be updated.

>>> blockchain.add_block(new_block)
True
>>> blockchain.get_balance(wallet.public_key)
10

You can now spent your new coins.

>>> destination = 'public_key_of_the_receiver'
>>> value = wallet.create_transaction(destination, 2)
>>> blockchain.add_transaction(value)
True

Your transaction will be added to the pending transactions queue. It will only be confirmed after being included in a mined block.

>>> blockchain.get_balance(wallet.public_key)
10

You can check your balance including the pending transactions

>>> blockchain.get_balance_pending(wallet.public_key)
8