Introducing Solidity Koans

Learn Ethereum programming by making tests pass
Published in
3 min readNov 5, 2018


As inspired by Ruby Koans, Solidity Koans guides you through simple, bite-sized programming exercises to learn Solidity the gentle way. The goal is to learn the Solidity language, syntax, structure, and how to create secure and gas-efficient smart contracts. It starts off with the basics and slowly guides you through the inner workings of the EVM, through assembly code and security considerations.

Through tests and exercises, I hope to make you think about edge cases and intrinsic properties of the blockchain and distributed systems. Your goal is to solve each puzzle and make the tests pass, test-driven development style.

How to get started

  1. Clone the Solidity Koans repo:
git clone

2. Install dependencies:

npm install -g truffle ganache-cli

3. Start up Ganache with command: ganache-cli

4. In a new tab, check out the/test directory, where each test represents a koan. To get started with the easiest (and first) Koan, run:

truffle test ./test/Test_assert_1.sol

You should see failing tests:

5. To make the tests pass, fill in the underscores __ in each file with the expected values:

// You can test if a condition returns true
function test_should_return_true() public {
Assert.isTrue(__, “should return true”);

Should be …

// You should fill in "true"
function test_should_return_true() public {
Assert.isTrue(true, “should return true”);

6. Pass all tests to finish the level.

You can find subsequent levels by looking in the /test directory. I recommend tackling them in order:

truffle test ./test/<Koan_subject>_<koan_order>.sol

What to Expect

Solidity Koans uses Ganache to run a personal Ethereum blockchain on your local machine, and uses Truffle for its testing framework. Each Koan is an actual smart contract with failing tests, that you’ll need to solve. I’ve included helpful inline comments to point you in the right direction. There are also links to relevant documentation and articles to help you understand more.

Currently, Solidity Koans has 7 basic levels that cover the most important aspects of Solidity, such as primitives and complex data types, and important concepts such as the difference between memory and storage.

For example, Level 7 looks like this:

Contributing to Solidity Koans

Solidity Koans is an open source project on Github, and is open for any pull requests or comments for improvement.

The Ethereum white paper outlines many more technical nuances worth exploring in Koans. I’m currently working on evolving future levels around coding patterns, common security pitfalls, and demystifying the EVM.

To contribute, simply:

  1. Fork this repo
  2. Examine Assert.sol: I modified truffle testing framework to provide UX enhancements like handling the double underscore __. Refactoring suggestions are welcome.

3. Submit issues, design your own levels, and then issue a Pull Request!

Thanks To: