Mastering Ethereum, 2nd Edition: what the ethereumbook repository actually contains

What the ethereumbook repository is, and who should open it

This repository is the manuscript source of Mastering Ethereum: 2nd Edition, credited to Andreas M. Antonopoulos, Gavin Wood, Carlo Parisi, Alessandro Mazza and Niccolò Pozzolini. The README points readers to two places: a paid copy on Amazon and a free online version at masteringethereum.xyz. That framing tells you who the repository is for. It is for people who want to read the book, and for people who want to change the book.

It is not an SDK. The topics list mentions Solidity, devp2p, tokens, web3.js and two older development frameworks, which describes the subject matter of the chapters, not code that ships from this repository. If you arrive looking for something to import into a project, you are in the wrong place. If you arrive wanting a structured explanation of how Ethereum works, written by people who were present at its creation, the repository is the canonical source for that text.

How the book is built: book.toml and the src/ directory

The repository layout is small and legible. At the top level you find .github/, .gitignore, README.md, book.toml and src/. The presence of book.toml identifies the build tool as mdBook, the Rust-based static site generator that turns a directory of Markdown files into an HTML book. The chapters themselves live under src/, which is the default source directory mdBook expects.

The data flow is one-directional and simple. Markdown files in src/ are the source of truth. book.toml configures how those files are assembled: the book title, the output format, and any mdBook options the maintainers have set. Running the mdBook build step renders the whole thing into static HTML. Nothing here compiles to a binary, nothing is published to a package registry, and there is no runtime. The only artefact is a website.

That architecture has a practical consequence for contributors. A correction to a paragraph is a Markdown edit in src/, reviewed like any other pull request. There is no generated output committed alongside it that also needs to be regenerated, at least not in the top-level listing. The default branch is develop, not main, which is worth noting before you open a pull request against the wrong base.

Rendering the book locally with mdBook

The README does not document a build procedure for the repository itself, because there is nothing to install in the application sense. What you need is mdBook, the tool that renders src/ into a readable book. The repository does not name a version or a distribution channel for it, so where you get mdBook is a decision the project leaves to you.

The repository files listed do not include any install commands, so there is no command line to reproduce here. What the layout does tell you is the entry point: book.toml sits at the repository root, and mdBook expects to be invoked from the directory that contains it. Once mdBook is available and you have the source checked out on the develop branch, running its build or serve step from the repository root is what turns src/ into HTML. You should see the chapter list from src/ in the sidebar of the rendered book, and, if you use the live-preview mode, the page reloading as you edit Markdown.

If a build fails, the most likely cause is a book.toml option your installed mdBook does not recognise, since no version is pinned in the files listed. That is a real gap: a contributor following only this repository has to infer the toolchain.

The licence changes twelve months after publication

The README states the terms in two phases. For the first twelve months after publication, the work is available under CC BY-NC-ND 4.0: attribution, non-commercial, no derivatives. After that period, it becomes available under CC BY-SA 4.0: attribution and share-alike, with commercial use and derivatives permitted.

This matters more than a typical open source licence line, because the two phases allow very different things. Under the first phase, you cannot sell a translation, cannot ship an adapted version inside a paid course, and cannot redistribute a modified copy at all. Under the second, you can, provided you license the result under the same terms. The repository does not state which phase is currently in force, so anyone planning to reuse the text commercially should determine that from the publication date rather than assume. The README notes that O'Reilly Media approved this arrangement. Nothing here is legal advice; the licence text governs.

Where the book stops being the right tool

A book ages differently from a library. The second edition carries a release tag dated 2025-11-26, and the repository itself was last pushed on 2026-09-19, so the text is being maintained. But the topics list names truffle-framework and embark, two development frameworks that have seen significant change and, in Truffle's case, deprecation in the wider ecosystem. A printed chapter describing a workflow around a specific tool version will drift out of step with that tool even while the repository stays current.

The failure mode is therefore not that the book is wrong, but that it is a snapshot. If you need the current recommended way to deploy a contract, or the current state of a client's JSON-RPC surface, the book is a starting point and the client documentation is the authority. Similarly, if you want runnable, tested code that you can drop into CI, this repository does not provide it. It provides prose and examples intended for reading. Treating it as a dependency rather than a reference is the mistake to avoid.

How this differs from Mastering Bitcoin and Mastering the Lightning Network

The obvious alternative is the sibling series. Mastering Bitcoin: unlocking digital cryptocurrencies and Mastering the Lightning Network: A second layer Blockchain Protocol for Instant Bitcoin Payments are the same editorial project applied to different subjects. The difference is not depth or quality; it is the object of study. Mastering Bitcoin explains the UTXO model, script, and proof-of-work mining. Mastering the Lightning Network explains payment channels and routing on top of that base layer. Mastering Ethereum explains accounts, the EVM, gas, and smart contracts.

If your work involves stateful contracts, tokens or the EVM, the Ethereum book covers ground the Bitcoin books do not touch, and vice versa. Choosing between them is a question of which chain you are building on, not which book is better. There is no overlap that makes one a substitute for the other.

Maintenance status and what upgrading means here

The repository is not archived, and the last push was on 2026-09-19, so it is being touched. The only release listed is tagged second-edition, dated 2025-11-26. Because the deliverable is a book, upgrade cost works differently than for a library. There is no version to bump in a manifest and no breaking API change to absorb. You re-read a chapter, or you re-render the site.

For a contributor, the cost is a pull request against develop and a review cycle. For a reader, the cost is nothing: the online version at masteringethereum.xyz reflects the current source. For anyone reusing the text, the cost is licence compliance, which as noted shifts between two Creative Commons variants depending on how much time has passed since publication. The repository does not document a changelog between editions, so if you need to know what changed from the first edition to the second, you will have to compare the texts yourself.

Editorial conclusion

Adopt this repository if you want the source of Mastering Ethereum, 2nd Edition, plan to read it at masteringethereum.xyz, or intend to file corrections against the book text. Do not clone it expecting a Solidity library, a node client or a dapp scaffold: the top level holds only .github/, .gitignore, README.md, book.toml and src/. Before contributing, verify the current licence phase, because the README states the terms change from CC BY-NC-ND 4.0 to CC BY-SA 4.0 twelve months after publication, and check the develop branch rather than assuming main.

Frequently asked questions

Official sources

1. ethereumbook/ethereumbook on GitHub
2. Issues
3. Project website
4. README
5. Releases