A pocket-sized implementation of Bitcoin
|size (curr.)||89 kB|
Putting the rough in “rough consensus"
Tinychain is a pocket-sized implementation of Bitcoin. Its goal is to be a compact, understandable, working incarnation of the Nakamoto consensus algorithm at the expense of advanced functionality, speed, and any real usefulness.
I wrote it primarily to understand Bitcoin better, but hopefully it can serve as a jumping-off point for programmers who are interested in (but don’t have intimate familiarity with) Bitcoin or cryptocurrency. At the very least, it can be a piñata for protocol developers who actually know what they’re doing.
$ cloc --quiet tinychain.py ------------------------------------------------------------------------------- Language files blank comment code ------------------------------------------------------------------------------- Python 1 341 174 679 -------------------------------------------------------------------------------
- Install Docker & docker-compose
- Clone this repo:
git clone firstname.lastname@example.org:jamesob/tinychain.git
- Make sure you’re in a Python3.6 environment:
virtualenv --python=python3.6 venv && . venv/bin/activate
- Grab Python dependencies locally:
pip install -r requirements.txt
docker-compose up. This will spawn two tinychain nodes.
- In another window, run
./bin/sync_wallets. This brings the wallet data from the Docker containers onto your host.
$ ./bin/sync_wallets Synced node1's wallet: [2017-08-05 12:59:34,423][tinychain:1075] INFO your address is 1898KEjkziq9uRCzaVUUoBwzhURt4nrbP8 0.0 ⛼ Synced node2's wallet: [2017-08-05 12:59:35,876][tinychain:1075] INFO your address is 15YxFVo4EuqvDJH8ey2bY352MVRVpH1yFD 0.0 ⛼
- Try running
./client.py balance -w wallet1.dat; try it with the other wallet file.
$ ./client.py balance -w wallet2.dat [2017-08-05 13:00:37,317][tinychain:1075] INFO your address is 15YxFVo4EuqvDJH8ey2bY352MVRVpH1yFD 0.0 ⛼
- Once you see a few blocks go by, try sending some money between the wallets
$ ./client.py send -w wallet2.dat 1898KEjkziq9uRCzaVUUoBwzhURt4nrbP8 1337 [2017-08-05 13:08:08,251][tinychain:1077] INFO your address is 1Q2fBbg8XnnPiv1UHe44f2x9vf54YKXh7C [2017-08-05 13:08:08,361][client:105] INFO built txn Transaction(...) [2017-08-05 13:08:08,362][client:106] INFO broadcasting txn 2aa89204456207384851a4bbf8bde155eca7fcf30b833495d5b0541f84931919
- Check on the status of the transaction
$ ./client.py status e8f63eeeca32f9df28a3a62a366f63e8595cf70efb94710d43626ff4c0918a8a [2017-08-05 13:09:21,489][tinychain:1077] INFO your address is 1898KEjkziq9uRCzaVUUoBwzhURt4nrbP8 Mined in 0000000726752f82af3d0f271fd61337035256051a9a1e5881e82d93d8e42d66 at height 5
What is Bitcoin?
In brief terms that map to this code…
Bitcoin is a way of generating pseudo-anonymous, decentralized trust at the cost of electricity. The most commonly known (but not sole) application of this is as a currency or store of value. If that sounds abstruse, general, and mindblowing, that’s because it is.
In Bitcoin, value is recorded using a
Transaction, which assigns some
number of coins to an identity (via
TxOuts) given some cryptographically
TxIns. TxIns must always refer to previously created but unspent
A Transaction is written into history by being included in a
Block. Each Block
contains a data structure called a Merkle
Tree which generates a fingerprint
unique to the set of Transactions being included. The root of that Merkle tree
is included in the block “header” and hashed (
Block.id) to permanently seal
the existence and inclusion of each Transaction in the block.
Blocks are linked together in a chain (
active_chain) by referring to the
previous Block header hash. In order to add a Block to the chain, the contents
of its header must hash to a number under some difficulty target, which is set
based upon how quickly recent blocks have been discovered
get_next_work_required()). This attempts to
normalize the time between block discovery.
When a block is discovered, it creates a subsidy for the discoverer in the form of newly minted coins. The discoverer also collects fees from transactions included in the block, which are the value of inputs minus outputs. The block reward subsidy decreases logarithmically over time. Eventually the subsidy goes to zero and miners are incentivized to continue mining purely by a fee market.
Nodes in the network are in a never-ending competition to mine and propagate the
next block, and in doing so facilitate the recording of transaction history.
Transactions are submitted to nodes and broadcast across the network, stored
mempool where they are queued for block inclusion.
For more comprehensive descriptions of Bitcoin, see
- Bitcoin: A Peer-to-Peer Electronic Cash System by Satoshi Nakamoto
- Mastering Bitcoin by Andreas Antonopoulos
- The Bitcoin Developer Guide
Notable differences from Bitcoin
Byte-level representation and endianness are very important when serializing a data structure to be hashed in Bitcoin and are not reproduced faithfully here. In fact, serialization of any kind here is very dumbed down and based entirely on raw strings or JSON.
Transaction types are limited to pay-to-public-key-hash (P2PKH), which facilitate the bare minimum of “sending money.” More exotic transaction types which allow m-of-n key signatures and Script-based unlocking are not implemented.
Initial Block Download is at best a simplified version of the old “blocks-first” scheme. It eschews
getdataand instead returns block payloads directly in
The longest, valid chain is determined simply by chain length (number of blocks) vs. chainwork.
Peer “discovery” is done through environment variable hardcoding. In bitcoin core, this is done with DNS seeds.
Replace by fee is absent.
Memory usage is egregious. Networking is a hack.
Satoshis are instead called Belushis because, well…
How does RPC work?
We use JSON for over-the-wire serialization. It’s slow and unrealistic but
human-readable and easy. We deserialize right into the
each of which dictates how a particular RPC message is handled via
Why doesn’t the client track coins we’ve spent but haven’t confirmed yet?
Yeah I know, the client sucks. I’ll take a PR.
How can I add another RPC command to reveal more data from a node?
Just add a
NamedTuple subclass with a
handle() method defined; it registers
automatically. Mimic any existing
Why aren’t my changes changing anything?
Remember to rebuild the Docker container image when you make changes
docker-compose build && docker-compose up
How do I run automated tests?
pip install -r requirements.test.txt py.test --cov test_tinychain.py
Is this yet another cryptocurrency created solely to Get Rich Quick™?
A resounding Yes! (if you’re dealing in the very illiquid currency of education)
Otherwise nah. This thing has 0 real-world value.
What’s with the logo?
It’s a shitty unicode Merkle tree. Give a guy a break here, this is freeware!
Where can I get more of you ranting?
Do you take tips to Get Rich Quick™?
Half of all tips will be donated to an organization providing aid to Syrian refugees.