How to create exercises

Disclaimer: This page will be moved to its own dedicated documentation in the future, along with a public git repo as a tutorial


You've finished all exercises on the website and are wondering what I have for you next. Guess what? I will present what's behind the scenes. The whole tutorial you've just completed is written in Markdown. Because this documentation is not aimed at learning you how to markdown, I won't spend time explaining all this language details, while it should still be understandable.

Pro tip: To better follow this tutorial, create an empty file on your machine and update it as you go through this webpage

Writing text

When you are reading a book or a website, you usually don't interact with it. You are reading text. As a content creator, writing text is quite easy. For example, this page you're viewing is written in Markdown. Like this:

# How to create exercises
> **Disclaimer**: This page will be moved to its own dedicated documentation in the future

## Introduction

You've finished all exercises on the website

Basic Markdown features


Text is the default mode of Markdown. Just write it inside your file and it will be rendered with no fancy decoration.

This is a text that will show itself

Title, subtitle, subsubtitle

Title, subtitle, subsubtitle, - I think you got the point by now - are just text prefixed by one or more #. The number of # denotes the level of the title. # is for title, ## for subtitle, ##### for subsubsubsubtitle.

# Title
## Subtitle
##### Subsubsubsubtitle


To teach code, you need to write code. And writing code is simple.

Short code

If you do not care about it to be formatted, just write it with

`code here`

and it gives code here.

Long code

But sometimes, when the code is long, highlighting is great. Markdown supports it. I've been using it to present you Markdown feature.

  pragma solidity ^0.4.24;

  contract Test {
    // ...
`` `

Interactive exercise

Interactive exercise is the way to write smart contracts exercises and allow users to run them on a blockchain.

Formalising your idea

Before going straight into writting a formatted exercise, it is great to test it live. To do so, you can use tools like:

  • Remix: Online Solidity editor
  • Truffle: Local smart contract development environement




pragma solidity ^0.4.24; contract Contract { uint i = 0; // Increment function here }

A complete exercise includes the following:

  • wording: describes the purpose of the exercise
  • initial: the initial code that is proposed to the user
  • solution: one solution to the exercise, proving it is valid
  • validation: test contracts the user will call to validate its answer

Writing of the exercise

Now you know what an exercise is. Here is the source of the exercise above.

{% exercise %}

{% initial %}
pragma solidity ^0.4.24;

contract Contract {
  uint i = 0;

  // Increment function here

{% solution %}
pragma solidity ^0.4.24;

contract Contract {
  uint private i = 0;

  function increment() public returns (uint) {
    // Don't care about overflow
    i = i + 1;
    return i;

{% validation %}
// Tests need proper pragma
pragma solidity ^0.4.24;

// Assert library is available here
import 'Assert.sol';
// Import contracts, filenames should match contract names given in the solution
import 'Contract.sol';

contract TestMuffin {
  // Declare variable associated to the contract you want to test
  // __ADDRESS__ specifies the contract is the one provided at runtime by the user
  Contract deployedContract = Contract(__ADDRESS__);

  // test function
  // IMPORTANT: only one assertion per function
  function testIncrement() public {
    uint result = deployedContract.increment();
    uint expected = 1;
    Assert.equal(result, expected, "Increment is not properly implemented");

  // event to communicate with the web interface
  event TestEvent(bool indexed result, string message);

{% endexercise %}


Issues and Improvements

If you feel anything is wrong, bad behaving, or you are thinking about improvement, please open an issue here

Adding exercises

Disclaimer: For now, contributing with exercises requires knowledge of git and command line interface

If you would like your exercise to be added to the main website, and we would be more than happy to welcome it, simply follow the steps:

  1. Fork the template repository -
  2. Run it locally with instruction provided in
  3. When you think your exercise is ready, create a pull request to the main repository