Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Truebit OS

Build Status

Truebit OS is the client software needed for running Solvers and Verifiers in Truebit network. The smart contracts are also included in the repo. The offchain interpreter is at and the JIT environment is at Tools for developing apps are at and

Below is a step-by step system demo with some sample tasks. You can run Truebit on Docker or build it from source, install locally or run over the Görli testnet. For directions on generating your own Truebit tasks and using the filesystem, please see the Quick start links on the Wiki. If you want to talk to the developers working on this project feel free to say hello on our Gitter channel.


  1. Running on Docker
    1. Compiling and running Truebit tasks
    2. Goerli testnet tutorial
  2. Linux installation
  3. MacOS installation
  4. Development

Running on Docker

Install Docker, and open a Terminal.

Compiling and running Truebit tasks

First start up the docker image:

docker run --rm -ti mrsmkl/wasm-ports:19-05-15 /bin/bash

Start up the Truebit environment:

cd truebit-os
sh scripts/

Run test tasks:

cd /wasm-ports/samples

If you want to recompile a sample, go to a sample directory, and then first setup the environment with

source /emsdk/

Then use the script. You'll also have to re-deploy with node ../deploy.js

Testing on Goerli network

To speed up network sync the next time, make a directory ~/goerli and then mount it with docker:

docker run --rm --name=tb -it -p 4001:4001 -p 30303:30303 -v ~/goerli:/root/.local/share/io.parity.ethereum mrsmkl/wasm-ports:19-05-15 /bin/bash

Start up IPFS and Parity:

cd truebit-os
sh scripts/

Wait for parity to sync, should take few minutes. (For example tail -F ~/goerli_log)

Find out your Goerli ETH address:

parity --chain=goerli account list

Then use the faucet to get some GÖETH:

To connect to IPFS nodes, try ipfs swarm connect /ip4/ (does not matter if fails)

(Optional) After parity has synced, you can start Truebit:

sh scripts/

Testing samples, Scrypt

cd /wasm-ports/samples/scrypt
node send.js <text>

Computes scrypt, the string is extended to 80 bytes. See source at Originally by @chriseth

Bilinear pairing (enter a string with more than 32 characters)

cd /wasm-ports/samples/pairing
node send.js <text>

Uses libff to compute bilinear pairing for bn128 curve. Reads two 32 byte data pieces a and b, they are used like private keys to get a*O and b*O. Then bilinear pairing is computed. The result has several components, one of them is posted. (To be clear, the code just shows that libff can be used to implement bilinear pairings with Truebit) See source at

Chess sample

cd /wasm-ports/samples/chess
node send.js <text>

Checks a game of chess. For example the players could use a state channel to play a match. If there is a disagreement, then the game can be posted to Truebit. This will always work for state channels, because both parties have the data available. Source at Doesn't implement all the rules, and not much tested.

Validate WASM file

cd /wasm-ports/samples/wasm
node send.js <wasm file>

Uses parity-wasm to read and write a WASM file. Source at

Size of video packets in a file:

cd /wasm-ports/samples/ffmpeg
node send.js input.ts

Source at

Progress of tasks can be followed from

Goerli testnet tutorial

Quickstart: try running these steps!

  1. Install Docker.

  2. Open a terminal window.

  3. Create directory ~/goerli to store your blockchain data.

  4. Start a session:

docker run --rm --name=tb -it -p 8545:8545 -p 3000:80 -p 4001:4001 -p 30303:30303 -v ~/goerli:/root/.ethereum mrsmkl/truebit-goerli:19-03-25 /bin/bash
  1. Initiate tmux.

  2. Create three windows by typing ctrl-b " then ctrl-b %.

  3. Start IPFS. Navigate to one of the smaller windows on the the bottom ``ctrl-b (down arrow)'' and type

ipfs daemon

If it looks like IPFS doesn't find files, try ipfs swarm connect /ip4/ to connect to a Truebit node running IPFS.

  1. Set up a new ethereum account. Navigate to the other small window and type:
cd ~/.ethereum
echo plort > supersecret.txt
geth --goerli account new --password=supersecret.txt

If you already have an account, just cd ~/.ethereum

To check addresses created, type

geth --goerli account list

Make sure there is just one account.

  1. Connect to Goerli. Type:
geth --goerli --rpc --unlock 0 --password=supersecret.txt
  1. Get testnet tokens for the account(s) above here:

  2. Start Truebit-OS. Wait a few minutes to sync with Goerli. Console will say "Imported" when ready. Navigate to the top window ctrl-b (up arrow) and type

cd truebit-os
npm run truebit

The balance command should show that you've claimed TRU testnet tokens.

  1. Task - Solve - Verify! Start a Solver:
start solve

Start a Verifier:

start verify

Issue a task (factorial example):

  1. Check your decentralized computations on the blockchain here:

Building from source in Linux

Getting Started

Start with an ethereum client running on port 8545, and an ipfs daemon at port 5001. For a quick start, ganache-cli is a blockchain emulator that can be used for development.

npm i -g ganache-cli

You will also need the latest version of solidity compiler installed and available on your path. Please refer to its documentation to install its binary package.


Install instructions are catered to Linux users. However, other OS's can use this by simply installing ocaml-offchain without the npm run deps script.

In order to get things running you'll have to go through all these commands at least once.

cd truebit-os/
npm i
npm run fixperms
npm run deps # you'll need to be in root (su root)
npm run compile
npm run deploy


The shell provides a number of commands which you can get instructions by using the help command:


Before submitting a task you will need to claim some test TRU tokens, from our faucet.

claim -a 0

Then account0 after the transaction is confirmed you should have 10000 TRU.


After starting up the shell you can enter commands to start submitting and solving tasks:

You can start up a task giver process that will monitor the incentive layer smart contract for events:

start task -a 0

Now the process will be monitoring for tasks created by account 0.

We can also start up a solver with a different account:

start solve -a 1

We've started up a solver with account 1 (this is to simulate different users, but it could be the same account).

Finally, we can submit our task:

task -a 0 -t testWasmTask.json

We have specified to submit a task from account 0. And the data related to the task is located at testWasmTask.json

If you are running this on a development test net you will need to skip blocks to see the solution in the solutions directory.

skip -n 120 # Go past the challenge period
skip -n 120 # Go past reveal period and finalize task

NOTE These parameters are subject to future change

Building from source in MacOS

  1. Install brew.
/usr/bin/ruby -e "$(curl -fsSL"
  1. Clone this repo.
git clone
cd truebit-os
  1. Install Solidity, NPM, IPFS, the off-chain interpreter, and client.
  1. Compile and deploy the contracts.
npm run compile
npm run deploy

Check that everything works with npm run test. Type npm run for more options.

  1. Task-Solve-Verify. Open a separate Terminal and start an Ethereum client, i.e.
ganache-cli -h

and optionally open another terminal with IPFS via ipfs daemon. Finally, start Truebit-OS!

npm run truebit

To get some tokens, type claim, and check your address using balance. If you need ETH, then exit Truebit-OS and use node send.js youraddress to send test ETH from account[0]. Use help For assistance with other Truebit-OS commands.


To run the tests use: npm run test

WASM Client

The wasm-client directory houses the primary Truebit client. It contains 4 relevant JS modules that wrap the internal details of the protocol for a user friendly experience. These modules are designed to interact with the Truebit OS kernel and shell. The four modules are taskGiver, taskSubmitter, solver, and verifier. These modules can be run independently from each other. With the exception of taskGiver and taskSubmitter being recommended to run together.


The way that Truebit OS knows where to load the relevant modules is with a config file. This is a simple JSON file with a couple fields, that tell the OS where to find the modules at. Here is the example config.json provided used for basic-client:

    "http-url": "http://localhost:8545",
    "verifier": "../wasm-client/verifier",
    "solver": "../wasm-client/solver",
    "task-giver": "../wasm-client/taskGiver"


Logging is provided by winston. If you would like to disable console logging, you can set the NODE_ENV to production, like so:

NODE_ENV='production' npm run test

Git Submodule Commands

Add submodule

git submodule add *url*

Cloning repo with submodule

git clone *repo*
cd *submodule_name*
git submodule init
git submodule update

If you want to include all the submodules with the repo you clone

git clone --recurse-submodules *url*

Fetching submodule updates

git submodule update --remote *submodule_name*

Pushing changes of a submodule to remote

git submodule update --remote --merge

Deleting submodules

git rm *submodule_name*
rm -rf .git/modules/*submodule_name*
You can’t perform that action at this time.