https://hub.docker.com/r/truebitprotocol/truebit-ethWhat is Truebit?
Truebit is a blockchain enhancement which enables smart contracts to securely perform complex computations in standard programming languages at reduced gas costs. As described in the whitepaper and this graphical, developer-oriented overview, Task Givers can issue computational tasks while Solvers and Verifiers receive remuneration for correctly solving them. You may wish to familiarize yourself with the practical, high-level user guide before proceeding.
This comprehensive Ethereum implementation includes everything you need to create (from C, C++, or Rust code), issue, solve, and verify Truebit tasks. This repo includes the Truebit-OS command line client configurations for solving and verifying tasks, some libraries ported to WebAssembly, an Emscripten module wrapper for adding runtime hooks, a Rust tool for generating tasks, the off-chain interpreter for executing and snapshotting computations, as well as sample tasks. You can install Truebit using Docker or build it from source for Linux, MacOS, or Windows.
Feel free to browse the legacy wiki, contribute to this repo's wiki, or check out these classic development blog posts:
Developing with Truebit: An Overview
Using the Truebit Filesystem
Truebit Toolchain & Transmute
Writing a Truebit Task in Rust
JIT for Truebit
In addition, Truebit's Reddit channel features links to some excellent introductions and mainstream media articles about Truebit. If you'd like to speak with developers working on this project, come say hello on Truebit's Gitter and Discord channels.
Table of contents
Quickstart guide: computational playground
Solve and verify tasks
Getting data into and out of Truebit
Client configuration
Building your own tasks
Native installation
Contract API reference
Quickstart guide: computational playground
This tutorial demonstrates how to install Truebit, connect to Görli or Ethereum mainnet networks, solve, verify and issue tasks, and finally build your own tasks. Use the following steps to connect to the Görli testnet blockchain and solve tasks with your friends!
Install or update Truebit OS
Follow the following steps to run a containerized Truebit OS client for Solvers, Verifiers, and Task Givers on any Docker-supported system. Docker provides a replicable interface for running Truebit OS and offers a streamlined installation process. First, download and install Docker. Then run the following at your machine's command line.
docker pull truebitprotocol/truebit-eth:latest
If you are running older version of Truebit OS and receive errors in your client, you should update to the latest Docker container via the same command. The current Truebit OS version is listed in the badge at the top of this README file, and you can compare this against the local version which Truebit OS displays at startup.
Docker incantations
Building the image above will take some minutes, but thereafter running the container will give an instant prompt. While you are waiting for the image download to complete, familiarize yourself with the following three command classes with which you will access the Truebit network.
"Start container"
We first open a new container with two parts:
Truebit OS. Solvers and Verifiers can solve and verify tasks via command-line interface.
Truebit Toolchain. Task Givers can build and issue tasks.
Select a directory where you wish to store network cache and private keys. For convenience, we let $YYY denote the full path to this directory. To get the full path for your current working directory in MacOS or Linux, type pwd. For example, if we wish to place the files at ~/truebit-docker, we would write
YYY=$HOME'/truebit-docker'
docker run --network host -v $YYY/docker-clef:/root/.clef -v $YYY/docker-geth:/root/.ethereum -v $YYY/docker-ipfs:/root/.ipfs --name truebit --rm -it truebitprotocol/truebit-eth:latest /bin/bash
Docker will then store your Clef, Geth, and IPFS configuration files in the directories docker-clef, docker-geth and docker-ipfs respectively. The -v flags in the incantation above avoid having to synchronize the blockchain and reconstruct your accounts, IPFS ID's, master seed, and rule attestation from genesis when you later restart the container.
If you are using Windows, try the following incantation.
SET YYY=%userprofile%/truebit-docker
docker run --network host -v %YYY%/docker-clef:/root/.clef -v %YYY%/docker-geth:/root/.ethereum -v %YYY%/docker-ipfs:/root/.ipfs --name truebit --rm -it truebitprotocol/truebit-eth:latest /bin/bash
"Open terminal window"
When you connect to the network, you will need to open multiple windows in the same Docker container. Running Geth or IPFS locally or in a different container from Truebit OS will not work. When it is time to open a new terminal window for your existing container, open a new local terminal window and enter the following at the command line.
docker exec -it truebit /bin/bash
If you omitted the --name truebit flag when starting your container (i.e., you did not cut and paste the command above), you will need to find the name of the container running truebitprotocol/truebit-eth:latest by using docker ps. Then, in place of "truebit" in the docker exec incantation above, substitute either your container's name, which might look something like xenodochial_fermat, or the container's ID, which looks something like 859841f65999.
If you instead wish to run all processes in a single terminal window, initiate tmux and create sub-windows by typing ctrl-b " or ctrl-b % and using ctrl-b (arrow) to switch between sub-windows. To exit a container, type exit. Your container process will remain alive in other windows unless you exited the original window which initiated with the --rm flag.
"Share files"
You can share files between your native machine and the Docker container by copying them into the local docker-clef, docker-geth, or docker-ipfs folders you created above or the respective folders in the Docker container, namely ~/.clef, ~/.geth, or ~/.ipfs. If you wish to synchronize a specific local file with a container file which does not belong to one of these directories on the container, say config.json, first copy config.json to your local directory $YYY/config.json, and then restart the docker run command with an additional volume, e.g. -v $YYY/config.json:/truebit-eth/wasm-client/config.json.
Alternatively, you may copy into (or out of) the container with commands of the following form.
docker cp truebit-eth/mydata.txt f7b994c94911:/root/.ethereum/mydata.txt
Here f7b994c94911 is either the container's name, namely truebit if you followed the convention above, or the container's ID. This example command copies a local file into the container. If you wish to copy from container to local, reverse the order of the files in the incantation.
Finally, for quick text file sharing from your local machine, you can simply copy text into a buffer and then paste into a file on the Docker container via the vim or nano text editors.
Initializing accounts
In order to interact with the Truebit network, you'll need account(s) to handle both Ethereum (ETH) and Truebit (TRU) tokens. We'll use Clef to securely manage account keys and addresses. The first time you start the Docker container, you'll need to initialize Clef with the following command.
clef init
Clef will ask you to create a master seed password which you'll use to unlock all your accounts. Next run the following line exactly as it appears.
clef attest 6441d5def6ec7ebe4ade8a9cf5d74f81088efaef314d8c4bda91221d02a9d976
This will allow Clef to sign all transactions automatically. Task Submitters, Solvers, and Verifiers must sign multiple transactions for each task, and you may find it inconvenient to sign each one manually. For security, all connections to Truebit OS are by default IPC, hence only your local machine can sign your transactions. If you wish to modify the automatic signing script, go to /truebit-eth/wasm-client/ruleset.js, compute its sha256sum hash, and then call clef attest again with your new hash. By default, clef will log its activities in a file called audit.log. If you used the docker run ... command above, you'll find your master seed file on your local computer in a folder called ~/truebit-docker/docker-clef.
You may check your existing accounts in Geth's console using personal.listWallets, in Truebit OS using accounts -r, or at the main Docker command prompt using geth --goerli account list (sans --goerli for mainnet).
New accounts
Repeat the following steps for each new account you wish to create. First, make a new private key for Görli testnet.
clef newaccount --keystore ~/.ethereum/goerli/keystore
Clef returns a "generated account" which is <YOUR PUBLIC ADDRESS>. To add an account for mainnet instead, just use the vanilla command clef newaccount. Clef will ask you to create a password for this account, and the next command will attach the account password to your master seed password keychain.
clef setpw <YOUR PUBLIC ADDRESS>
Clef can now autofill the keystore password for
On testnet one can create keystore files with shorter passwords using geth --goerli account new.
Importing existing accounts
For hardware wallets, you can either add the --privileged flag when starting Docker or run Truebit OS outside the Docker container using a native install. In either case, you will need to remove the --nousb flag from both the clef and geth startup incantations.
If you wish to use an existing keystore file with Truebit, simply paste it into your local folder docker-geth/goerli/keystore (for testnet) or docker-geth/keystore (for mainnet). Alternatively use docker cp to paste into the Docker container at ~/.ethereum/goerli/keystore (testnet) or ~/.ethereum/keystore (mainnet). MyCrypto's Desktop App conveniently manages keystore files offline (i.e. outside the browser).
Funding your accounts with ETH
Finally, get some ETH! You can obtain Görli ETH from one of the free faucets below, or send ETH to your accounts from your favorite wallet (e.g. Metamask or MyCrypto).
https://goerli-faucet.slock.it/https://faucet.goerli.mudit.blog/As Ethereum mainnet lacks a faucet, you'll have to source ETH from an existing account (or mining).
Connect to the network
One must simultaneously run Geth and IPFS in order to communicate with the blockchain and data infrastructures. When you start up a new Truebit container, initialize the Truebit toolchain compiler, start IPFS, and start Geth as with the following command.
bash /goerli.sh
If you wish to connect to Ethereum mainnet rather than Görli, use instead
bash /mainnet.sh
After running the startup script, the Clef account management tool should pop up at the bottom of a split tmux screen with Geth waiting to start above. After you enter the master seed password for your accounts, your Geth node should start to synchronize with the blockchain.
Once your Geth node is fully synchronized, you may enhance IPFS connectivity by running the last four lines in /goerli.sh (sans comment symbol #) or by running the equivalent commands in Truebit OS. Open a new Docker terminal and type cat /goerli.sh to view the file contents, cut and paste to your command line, and cat /ipfs-connect.log for connection results. Alternatively, you can configure Truebit OS to synchronize with an external IPFS node rather than running one in Docker.
Note that one can terminate an IPFS connection at any time by typing ipfs shutdown. If you get an error message like Error: execution aborted (timeout = 5s) when running the commands described in the previous paragraph, check your connection in the Geth window and rerun the offending command. Messages like Error: Invalid JSON RPC response: "Error: connect ECONNREFUSED 127.0.0.1:8545 ... or error: no suitable peers available indicate that IPFS failed to obtain the list of registered Truebit nodes due to lack of Geth connection or synchronization.
Note that Truebit OS automatically detects the blockchain network to which Geth is connected (either Görli testnet or Ethereum mainnet). If you are have trouble connecting to a light client peer, try the following.
Terminate the Clef/Geth split screen (Ctrl-C, Ctrl-D and/or exit) and re-run sh /goerli.sh.
Test your connection with a vanilla command at the main Docker prompt, e.g. geth --goerli --syncmode "light", or for mainnet geth --syncmode "fast". Try geth --help for more options.
Test Truebit OS with a plug-and-play API, e.g. Infura or others. See below for configuration instructions.
Change your IP address.
Try running Truebit OS natively instead of using Docker.
Consider running a full Ethereum node on dedicated hardware.
Reconnect later.
To view a list of your connected addresses inside the geth console, type personal.listWallets at the Geth command line.
Solve and verify tasks
We are now ready to run Truebit Solver and Verifier nodes. This walk-through assumes you've already set up your accounts and connected to the network. Use the "open terminal window" incantation to connect to your Docker container in a terminal window separate from Geth. Then start Truebit OS!
cd /truebit-eth
./truebit-os
You should now see a new shell prompt.
THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. YOU MAY NOT MODIFY, REVERSE ENGINEER, DISASSEMBLE, DECOMPILE, OR ATTEMPT TO DERIVE THIS FILE'S SOURCE CODE.
_____ _ _ _
|_ _| _ __ _ _ ___ | |__ (_) | |_ _
| | | '__| | | | | / _ \ | '_ \ | | | __| (_)
| | | | | |_| | | __/ | |_) | | | | |_ _
|_| |_| \__,_| \___| |_.__/ |_| \__| (_)
_ _ _ _ __
| |_ __ _ ___| | __ ___ ___ | |_ _____ __ _____ _ __(_)/ _|_ _
| __/ _` / __| |/ / / __|/ _ \| \ \ / / _ \ \ \ / / _ \ '__| | |_| | | |
| || (_| \__ \ < \__ \ (_) | |\ V / __/ \ V / __/ | | | _| |_| |
\__\__,_|___/_|\_\ |___/\___/|_| \_/ \___| \_/ \___|_| |_|_| \__, |
|___/
[01-21 14:42:00] info: Truebit OS 1.2.6 has been initialized on goerli network at block 4145800 with throttle 3 and gas price 20.1 gwei.
Note that you must be connected to either Görli testnet or Ethereum mainnet in order to execute commands in Truebit OS. You may see error messages at this point if your local node has not yet synchronized with the blockchain or is not connected to a suitable peer (e.g. Error: CONNECTION ERROR: Couldn't connect to node on IPC., Error: Invalid JSON RPC response: "Error: connect ECONNREFUSED 127.0.0.1:8545, or error: no suitable peers available). If this happens, exit Truebit OS and restart. To avoid gas waste on Ethereum mainnet, make sure your account(s) have sufficient ETH balance(s) to complete desired operation(s). Try first a dry run on Görli testnet using account(s) with identical ETH balance(s) before moving to mainnet. Some methods, like uploading data onchain, may require your account to authorize an ETH equivalent of 5 million gas even if the corresponding transaction consumes only a small fraction of that amount. Always close your Görli (respectively mainnet) connection before running mainnet.sh (respectively goerli.sh); clef can only handle one connection per masterseed, and mainnet.sh and goerli.sh each redirect Truebit OS's connection.
For a self-guided tour or to explore additional options not provided in this tutorial, type help at the command line, and (optionally) include a command that you want to learn more about. Here is a list of available commands:
help [command...] Provides help for a given command.
exit Exits application.
accounts [options] List web3 account indices (-r to refresh).
balance [options] Show account balances (-a account index).
bonus Display current per task subsidy.
gas [options] <cmd> Check or set gas price.
ipfs [options] <cmd> Manage IPFS nodes.
license [options] <cmd> Obtain a Solver license.
ps List active Solvers and Verifiers along with their games and tasks.
start [options] <cmd> Start a Solver or Verifier.
stop <num> Stop a Solver or Verifier. Get process numbers with 'ps'.
task [options] <cmd> Submit a task or run a utility.
token [options] <cmd> Swap ETH for TRU. Deposit to or withdraw from incentive layer.
version Display Truebit OS version.
Purchasing, staking, and retiring TRU tokens
In order to start a Solver or Verifier, one must first stake TRU into Truebit's incentive layer. Let's purchase 1000 TRU tokens for account 0. First check the available account indices using accounts and the price in ETH using
token price -v 1000
If you add or remove node accounts while Truebit OS is open, you can refresh and synchronize Truebit OS's account list with
accounts -r
Truebit OS will retain the current list of account indices until one runs this command. After checking balances for account 0 using balance, we are ready to purchase some TRU. WARNING: The purchase command will spend ETH from your account. Please practice the commands in this section on Görli testnet before trying them on Ethereum mainnet.
token purchase -v 1000 -a 0
We should now have 1000 freshly minted TRU in account 0. We can now stake some of our TRU which will enable us to solve or verify a task.
token deposit -v 500 -a 0
We can repeat this process for account 1, if desired. We are ready to start a Verifier, however if we wish to run a Solver, there is one additional step. We must purchase a Solver license with ETH. Check the price using license price, determine whether the account already has a license using license check -a 0, and then
license purchase -a 0
Finally, we can confirm account balances for ETH and TRU and the amount of TRU we have staked in Truebit's incentive layer.
balance -a 0
Eventually, when we are ready to discard TRU and recover ETH, we can retire the tokens as follows. First check the buyback price using token price -v 100. Then
token retire -v 100 -a 1
This transaction will destroy 100 TRU and send ETH from the reserve to account 1. We can conveniently transfer TRU and ETH among accounts in Truebit OS using token transfer-eth and token transfer-tru. For example,
token transfer-tru -a 0 -t 1 -v 20
will transfer 20 TRU from account 0 to account 1.
Running Solvers and Verifiers
We can now start our Solver and Verifier as follows. For clarity it is recommended, but not required, to run each Task Submitter, Solver, or Verifier in a separate terminal window with a distinct account.
start solve -a 0
start verify -a 1
Note that account 0 is assumed for the start command when the -a flag is not specified. If the Solver and Verifier do not immediately find a task on the network, try issuing a sample task yourself.
task -f factorial.json submit -a 0
The Task Submitter address always has first right-of-refusal to solve its own task, so your Solver should pick this one up! You can check progress of your Görli task here:
https://goerli.etherscan.io/address/0x76c73774bC137F3229c422a8E054A022d9066b22For mainnet, check here:
https://etherscan.io/address/0x388a3bD8f54F305266898e77B126609Ec6265f1eSolvers and Verifiers will continue to solve and verify new tasks until instructed to stop. To limit task participation based on TRU rewards, Solvers and Verifiers can use the -l flag to set a minimum, (constant) non-zero reward threshold per task, or use -p to fix a minimum TRU reward per block of computation. For example,
start verify -l 10 -p 0.5
will initialize a Solver who participates when the the total reward for Verifiers is at least 10 TRU and pays at least 0.5 TRU per block of computation. Neither the -l nor the -p flag takes subsidy payments into consideration, so choose parameters accordingly.
You can terminate all Solvers and Verifiers in your terminal by exiting Truebit OS, however it is safer to end them using ps and stop, illustrated below, as this will allow them to complete active tasks(s), active verification game(s) and unbond deposits before terminating.
truebit-os:> ps
SOLVERS
1. Account 4: 0xa1b4CbC091E9B15e334d95D92CA7677152F52ac4
VERIFIERS
2. Account 5: 0x755908B829B8189a8B6D757da2A8ed4747506a84
Task 1: 0x100a6f1a7fe990a2839ff309
