Contributing¶

Blockchain Engineering is an open-source technical book. Corrections and technical reviews are welcome.

Useful contributions¶

Good contributions include:

correcting a technical error
clarifying an explanation
adding a missing primary source
fixing a broken link
improving a diagram
improving a code example
identifying a historical claim that needs qualification
fixing terminology
improving navigation between chapters

Before opening a pull request¶

The book favors primary sources, direct technical language, mechanism-first explanations, explicit tradeoffs, and clear separation between fact, interpretation, and speculation.

New chapters¶

Before adding a new chapter, check SUMMARY.md and PROGRESS.md.

A new chapter should have a clear place in the existing structure.

Economic topics¶

Do not write economic chapters as advocacy.

Represent a school's arguments using original texts when possible, distinguish an author's writing from later interpretations, and include competing arguments when they materially affect the topic.

Historical topics¶

Use dates and primary sources when possible.

When evidence is uncertain, say so.

Satoshi Nakamoto's real-world identity remains unknown. Do not present speculation as fact.

Security topics¶

Security contributions should focus on understanding, prevention, and mitigation.

Do not add instructions intended to exploit live systems or steal funds.

Pull requests¶

Keep pull requests focused. A small technical correction is easier to review than a large rewrite covering unrelated chapters.