anders94/blockchain-demo: a browser-based blockchain and SHA-256 teaching tool

What anders94/blockchain-demo actually demonstrates

The README calls it "a very basic visual introduction to the concepts behind a blockchain" and frames the goal as introducing "the idea of an immutable ledger" through an interactive web demo. That is the whole scope. It is aimed at the person who has read a blockchain explainer and still cannot say what a nonce is, or why changing one block breaks every block after it. The demo answers those two questions and stops.

It is not aimed at anyone building a chain. There is no peer discovery, no mempool, no transaction signing, no consensus between machines. The repository is a single Express app with Pug views, a routes directory and a public/javascripts folder holding the hashing logic that runs in the browser. If you want a chain you can deploy, this is the wrong repository, and the README never claims otherwise. The author points readers to a companion project, anders94/public-private-key-demo, for the key material side of the topic, which is a useful signal that key handling lives outside this codebase.

How the demo turns a hash into a mineable block

Everything runs client-side. The project description names Pug as the primary language, and the views render the pages while public/javascripts/blockchain.js holds the arithmetic. The README tells you to edit "the first two lines" of that file to change how many leading zeros the demo requires, which confirms that difficulty is a plain constant read by browser code rather than a server-side setting.

The mechanism is deliberately literal. A block carries data, a previous hash, a nonce and its own hash. Mining means incrementing the nonce until the resulting hash starts with the required number of zeros. The README gives a worked example: at a difficulty of 6, "the first nonce that works is 8719932 yielding a hash of 000000669445c22167511857d8f3b822b331c3342f25dfdcb326e35c1a7aa267". Because a hex character has 16 possible values, the README states that each extra zero makes the puzzle 16 times harder, and the accompanying table runs from roughly 500,000 attempts at four digits to numbers with 19 digits at fifteen.

The chaining is the second half of the lesson. Each block stores the previous block's hash, so editing an earlier block changes its digest and invalidates everything downstream. That is the immutability lesson in one screen, and it is the reason the demo has value beyond a hash calculator.

Installing anders94/blockchain-demo and mining your first block

The README gives two paths. The npm route clones the repository, installs dependencies and starts the Express server. Run these three commands in order; the third one is what the package.json start script invokes.

git clone https://github.com/anders94/blockchain-demo.git
cd blockchain-demo
npm install
npm start

The README lists `./bin/www` as an alternative to `npm start`, and adds a Windows note: if that fails, run `node ./bin/www`. Either way the server listens on port 3000, and the README says to point a browser at `http://localhost:3000`.

./bin/www

If you would rather not install Node dependencies locally, the repository ships a Dockerfile based on node:alpine and a docker-compose.yml that builds the image and maps port 3000. The README's Docker section is four commands long.

git clone https://github.com/anders94/blockchain-demo.git
cd blockchain-demo
docker-compose up -d

The compose file exposes `"3000:3000"` and tags the image `blockchain-demo:latest`, so the same `http://localhost:3000` address works. Once the page loads, the block view is where the lesson lands: type into the data field, watch the hash change, then raise the nonce until the hash begins with the required zeros. The README's own example, nonce `8719932` producing a hash starting `000000`, is the shape of the result you are looking for.

The difficulty ceiling is the demo's sharpest limitation

The README does not hide this. It states plainly that if you adjust the difficulty above 4, "blocks will show up as not mined because the demo data assumes 4 zeros for a signed block." The signed state is hard-coded to four zeros, so raising the constant does not produce a harder puzzle with a correct answer; it produces a page that disagrees with itself. The README's own table makes the practical case against going higher anyway: six digits is estimated at three days, eight at two years, and the estimates climb into hundreds of thousands of years by the mid teens. For context it notes that bitcoin block 458,091 has 21 leading zeros and would take this software roughly 8,454,989,768,407,765 years to mine.

That is the boundary. The demo is honest about being a toy, and the difficulty table doubles as a lesson in why real proof-of-work needs specialised hardware. Anyone who changes the constant to make the demo look more impressive will get a broken page, not a better demo. The other limitation is structural: because the hashing happens in the browser, there is no server-side validation to inspect, so the project teaches the concept but shows you nothing about how a node would verify a block it received.

How it compares with a full local chain

A tool like Ganache or a local Bitcoin regtest node gives you a real chain: actual consensus rules, actual transactions, actual RPC endpoints, and a state you can query. The difference in approach is total. A regtest node is a faithful implementation you interact with through an API; anders94/blockchain-demo is a visual model you interact with through a web form. The node will reject malformed blocks for reasons the demo never encodes. The demo will show you, in one animated page, why a nonce search is expensive and why editing history is detectable.

For a first lecture, the demo wins because the feedback loop is instant and requires no configuration. For anything after that, the node wins because the demo has no network layer at all. Choosing between them is really a question of whether you want students to understand the mechanism or to operate the machinery. The README's scope statement, "a very basic visual introduction", is the honest answer to which one this is.

Maintenance, upgrade cost and the MIT licence

The last push to the repository was on 2026-09-10, so the code is recent rather than abandoned. There are no releases, which means there is no versioned artifact to pin; you track the master branch. That has an upgrade consequence worth naming: with no tags and no changelog, a `git pull` is the upgrade, and you have no release notes to tell you what moved. For a teaching demo this is tolerable, but it means you should clone at a commit you have looked at rather than pulling blindly before a class.

The dependency list is small and conventional: express, pug, body-parser, cookie-parser, morgan, async, i18n and serve-favicon, all caret-ranged. The i18n dependency and the top-level locales directory indicate the interface is translatable, which matters if you teach in a language other than English. The Dockerfile runs `npm install` at build time and uses node:alpine, so a rebuild will pull whatever those ranges resolve to that day.

The licence is MIT, which is permissive and places few obligations on reuse. That is a statement about the licence text, not legal advice; if you intend to redistribute the demo inside a commercial course, read the LICENSE file yourself. Note also that the README solicits bitcoin donations to a specific address, which is unrelated to the licence but is part of what you are cloning.

Editorial conclusion

Adopt it if you teach hashing, nonces or chain invalidation and want a browser page students can poke at, or if you want to read roughly a thousand lines of Express and Pug before writing your own chain. Do not adopt it as a wallet, a node, a consensus implementation or anything that touches real value; it has no networking, no peers and no signatures. Before you rely on it in a class, verify that node ./bin/www still starts on your Node version, and decide whether you want the difficulty left at the default 4, because the README warns that anything above 4 makes blocks render as not mined.

Frequently asked questions

Official sources

1. anders94/blockchain-demo on GitHub
2. Issues
3. License: MIT
4. README