truja/truebit-beta

•Updated almost 6 years ago

Image

338

truja/truebit-beta repository overview

⁠What 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.

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⁠ for solving and verifying tasks, WASM ports⁠ and Emscripten module wrapper⁠ for generating them, the off-chain interpreter⁠, 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:

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⁠ channel.

⁠Table of contents

Quickstart guide: computational playground⁠
Solve and verify tasks⁠
Getting data into and out of Truebit⁠
Building your own tasks with the Truebit toolchain⁠
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 truja/truebit-beta:latest

⁠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 UNIX, type pwd. For example, if we wish to place the files at \Users\Shared, we would write

YYY='/Users/Shared'
docker run --network host -v $YYY/docker-geth:/root/.ethereum -v $YYY/docker-ipfs:/root/.ipfs --rm -it truja/truebit-beta:latest /bin/bash

Docker will then store your Geth and IPFS files configuration files in the directoriesdocker-geth and docker-ipfs respectively. The incantation above avoids having to synchronize the blockchain and your accounts from genesis and also stores your IPFS "ID" for better connectivity when you later restart the container.

⁠"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, find the name of your container running truja/truebit-beta:latest by using docker ps, open a new local terminal window and enter the following at the command line.

docker exec -it _yourContainerName_ /bin/bash

yourContainerName might look something like xenodochial_fermat. 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.

You can share files between your native machine and the Docker container by copying them into your docker-geth or docker-ipfs folders. Alternatively, you may copy into (or out of) the container with commands of the following form.

docker cp truebit-eth/supersecret.txt f7b994c94911:/docker-geth/supersecret.txt

Here f7b994c94911 is the name of the container's ID. 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.

⁠"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, start IPFS in the background and configure the compiler with the following pair of commands (in this order).

source /emsdk/emsdk_env.sh
bash startup.sh

You can terminate IPFS at any time by typing ipfs shutdown.

Geth requires a more nuanced setup relative to IPFS. Below we'll connect to Truebit on the Görli testnet. As we shall see, connecting to Ethereum mainnet is quite similar. Truebit OS automatically detects which blockchain network Geth is connected to (Görli testnet or Ethereum mainnet).

⁠Initializing accounts

If you don't already have a local Görli account in your Docker container, create a new one inside the Docker container with the following command.

geth --goerli account new

Geth will prompt you for an account password. You may wish to create more than one account. Paste each of your account passwords on separate lines, in order, into a text file. Drop this text file into your docker-geth folder. For example, your password file might have the name supersecret.txt and might look something like this:

truebit
task
solve
verify

Finally, fund your accounts! You can obtain Görli ETH from one of the faucets below, or send your accounts ETH from your favorite wallet (e.g. Metamask⁠ or MyCrypto⁠).

https://goerli-faucet.slock.it/⁠

https://faucet.goerli.mudit.blog/⁠

⁠Connecting with Geth

In your Truebit Docker container, connect your account(s) to the Görli network using an incantation of the following form:

geth --goerli --rpc --unlock "0,1,2,3" --password /root/.ethereum/supersecret.txt --syncmode "light" --allow-insecure-unlock console

Here 0,1,2,3 denotes the indices of the accounts you wish to use with Truebit OS. If we wanted to connect to mainnet instead of Görli, we would simply delete the term --goerli in the incantation above. Your Geth client should now begin syncing with the network and be up to date within a minute. If you are have trouble connecting to a light client peer, try the following.

Exit geth (Ctrl-C or exit) and re-run the geth incantation above.
Try running Truebit OS natively⁠ instead of using Docker.
Change your IP address.
Reconnect later, or consider running a full Ethereum node.

To view a list of 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. If you haven't already, "start container"⁠ and "connect to the network"⁠. Now 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 /  __/ |  | |  _| |_| |
  \__\__,_|___/_|\_\ |___/\___/|_| \_/ \___|   \_/ \___|_|  |_|_|  \__, |
                                                                   |___/

[10-17 22:40:48] info: Truebit OS 1.0.6 has been initialized on goerli network at block 3594922.

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: Invalid JSON RPC response: "Error: connect ECONNREFUSED 127.0.0.1:8545 ... or error: no suitable peers available). If this happens, quit and restart.

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                 List available network accounts.
balance [options]        Show account balances.
bonus                    Display current per task bonus payout.
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.

⁠Staking 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. Check the price using token price, then

token purchase -v 1000 -a 0

Now we can stake some of our TRU.

token deposit -v 500 -a 0

We can repeat this process for account 1, if desired. We are ready to start a Verifier, but 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, 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

It is recommended, but not required, to run each Solver or Verifier node in a separate terminal window from a distinct account.

⁠Running Solvers and Verifiers

We can now start our Solver and Verifier as follows.

start solve -a 0
start verify -a 1

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/0x0E1Cb897F1Fca830228a03dcEd0F85e7bF6cD77E⁠

Your Solver and Verifier will continue to solve and verify new tasks until a stop command is issued (e.g. stop 1) or you exit Truebit OS. Use ps to identify the appropriate process index. If you lose Internet connectivity while your deposit is bonded to a task, try restarting in recovery mode. For example,

start solve -r 20

will initialize a new Solver 20 blocks behind the current block and recover the intermediate events.

⁠Faster IPFS uploads and downloads

IPFS's peer-to-peer network can route data more efficiently when it knows where to find Truebit Task Submitters, Solvers, and Verifiers. It is recommended to register your IPFS node with Truebit via the following command which makes it easier for others to find your node while you are issuing or solving tasks:

ipfs register

You can then discover other nodes on Truebit's network by running:

ipfs connect

If your node didn't successfully connect to peers, try again in a few minutes. It takes some time for new addresses to propagate. Note that some registered nodes may be offline.

⁠Logging sessions and command line execution

The vanilla ./truebit-os command generates a file combined.log.json containing a .json log spanning across all Truebit OS terminals but does not include everything displayed on the terminal screens. You can inspect this log as follows:

cat /truebit-eth/combined.log.json | more

It is safe to delete this file.

If one wishes to record a more detailed log for a Truebit OS interactive session, one can use a command of the following form to record the full terminal output:

./truebit-os 2>&1 | tee mylog.txt

One can also execute Truebit OS commands directly from the native (Docker) command line using a -c flag. For example, try:

./truebit-os -c "start solve -a 1" --batch > mylog.txt 2>&1 &

Here the --batch flag tells Truebit OS to run non-interactively, and > mylog.txt 2>&1 & tells Truebit OS to write the output to a log file called mylog.txt rather than the terminal. The command above will return a process number at the command line (e.g. [1] 412). You can stop the Solver process later using the kill command, (e.g. kill 412). The following Unix shell command will return a list of active Truebit processes from all windows.

ps a

⁠Client configuration

In the /truebit-eth/wasm-client/ directory, you will find a file called config.json which looks something like this.

{
  "http-url": "http://localhost:8545",
  "ipfs": {
    "host": "localhost",
    "port": "5001",
    "protocol": "http"
  },
  "gasPrice": 20.1,
  "throttle": 3,
  "incentiveLayer": "incentiveLayer"
}

When running on Ethereum mainnet, you may wish to modify the gasPrice parameter to increase the chances that Ethereum miners will process your Truebit OS transactions or to economize on ETH. Every Ethereum transaction invokes some ETH gas cost, and price per unit gas is given in gwei⁠. The gasPrice can be set within Truebit OS. For example,

gas set -v 47.3 --default

will set the running client gas price to 47.3 gwei, and the optional --default flag tells Truebit OS to write to config.json above so that this value becomes the starting gasPrice the next time you start Truebit OS. Beware that in Ethereum's capricious DeFi environment, gas prices can fluctuate wildly. Use the following command to get a real-time, suggested range of gas prices on mainnet.

gas check

On Görli, a gasPrice of 1 gwei may suffice.

The throttle parameter above is the maximum number of simultaneous tasks that your Solver or Verifier will process. http-url and ipfs must match the network settings for Geth and IPFS. Do not change incentiveLayer as Truebit currently only supports a single incentive layer.

You must restart Truebit OS for configuration changes to take effect. For editing convenience and to save your changes to the next "start container"⁠, you may wish to add a volume to your Docker run incantation, e.g. -v $YYY/wasm-client:/truebit-eth/wasm-client.

⁠Getting data into and out of Truebit

Truebit can read and write data to three file types.

BYTES. These are standard Ethereum bytes stored in Truebit's filesystem smart contract. Note that Truebit does not read data from arbitrary smart contracts.
CONTRACT. This method uses a smart contract whose program code consists of the task data itself. This is not a typical contract deployment as the contract may not function.
IPFS. Truebit can read and write to IPFS, a peer-to-peer, content-addressed storage system.

Ethereum has a limit of 5 million gas per contract deploy (~ 24 kilobytes) and roughly the same limit for other transactions. This means that larger files should always sit on IPFS.

⁠Writing task outputs via Truebit OS

Let's inspect a sample task meta file called reverse.json which can be found in the /truebit-eth directory:

{
    "codeFile": {
      "path": "/data/reverse_alphabet.wasm",
      "fileType": "IPFS"
    },
    "dataFiles": {
      "/data/alphabet.txt": "CONTRACT",
      "/data/reverse_alphabet.txt": "BYTES"
    },
    "outputs": {
      "reverse_alphabet.txt": "BYTES"
    },
    "solverReward": "2",
    "verifierTax": "6",
    "minDeposit": "10",
    "stackSize": "14",
    "memorySize": "20",
    "globalsSize": "8",
    "tableSize": "8",
    "callSize": "10",
    "blockLimit": "1"
}

You can experiment with its filesystem configuration by adjusting parameters below.

codeFile. This keyword specifies the compiled code that the Task Giver wishes to execute. Truebit OS automatically detects code type based on the code file extension (.wasm or .wast), however the Task Giver must specify a file type for the code (BYTES, CONTRACT, or IPFS) telling Solvers and Verifiers where to find it. Each task has exactly one codeFile.
dataFiles. All input and output files for the task program must be listed under this keyword, and each must have a file type (BYTES, CONTRACT, or IPFS).
outputs. The value(s) here are the subset of the data files which are produced and uploaded by the Solver. In this example both the empty data file /data/reverse_alphabet.txt and the corresponding output file reverse_alphabet.txt have the same file type (BYTES), however in general they need not match.
solverReward, verifierTax, and minDeposit pertain to task economics. The solverReward is the reward paid to the Solver for a correct computation, the verifierTax is the fee split among Verifiers, and minDeposit is the minimum unbonded deposit that Solvers and Verifiers must have staked in the Incentive Layer in order participate. Note that the Task Owner's fee is automatically 0 since the Task Submitter is always the Task Owner when deploying from Truebit OS.

In a typical Ethereum deployment, the Task Owner is the Dapp smart contract that sends a task to Truebit which in turns calls back with a solution. The Task Submitter is always a regular (i.e. human-controlled) blockchain address that initiates the task and pays for it.

stackSize, memorySize, globalsSize, tableSize, and callSize. These are virtual machine parameters. You may need to tweak memorySize when you create your own task.
blockLimit. This is the length of time (in blocks) for which Solvers and Verifiers will attempt to run the task before reporting a timeout.

To run this example, enter the following commands in Truebit OS.

start solve
task -f reverse.json submit

⁠Sample tasks via smart contracts

In general, Dapps will issue tasks from smart contracts rather than the Truebit OS command line. This allows Truebit to call back to the smart contract with a Truebit-verified solution. Typically the Task Owner smart contract fixes the task function code during deployment while the Task Submitter puts forth the function inputs at runtime. To demonstrate this method, we deploy and issue some tasks that are preinstalled in your container. One can deploy each of the samples onto the blockchain as follows.

cd wasm-ports/samples
sh deploy.sh

To run a sample task, cd into that directory and run node send.js as explained below. You may wish to edit ../deploy.js or send.js by replacing the '0' in accounts[0] with the index of your desired Geth account.

⁠Scrypt

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

Computes scrypt. The string is extended to 80 bytes. See the source code here⁠. Originally by @chriseth.

⁠Bilinear pairing

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

For <text>, enter a string with more than 32 characters. This example uses the libff library to compute bilinear pairings for a bn128 curve. It reads two 32 byte data pieces a and b which are used like private keys to get a*O and b*O. Then a bilinear pairing is computed. The result has several components, and one of them is posted as output. (To be clear, the code just shows that libff can be used to implement bilinear pairings with Truebit). See the source code here⁠.

⁠Chess

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

This example checks moves in a game of chess. Players could use a state channel to play a chess match, and if there is a disagreement, then the game sequence can be posted to Truebit. This method will always work for state channels because both parties have the data available. See the source code here⁠. The source code doesn't implement all the rules of chess, and is 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. See the source code here⁠.

⁠Size of video packets in a file

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

See the source code here⁠.

⁠Building your own tasks with the Truebit Toolchain

If you haven't already, from your Truebit container, run the following commands (in order):

source /emsdk/emsdk_env.sh
bash startup.sh

You should now be able to compile the sample tasks yourself in C++ (chess, scrypt, pairing), and C (ffmpeg) below.

cd /truebit-eth/wasm-ports/samples/chess
sh compile.sh
cd ../scrypt
sh compile.sh
cd ../pairing
sh compile.sh
cd ../ffmpeg
sh compile.sh

For Rust tasks, take a look @georgeroman's [workaround]( https:

Tag summary

Recent tags

Content type

Image

Digest

Size

3.1 GB

Last updated

almost 6 years ago

docker pull truja/truebit-beta