Working with Truebit-OS using the API

AUTHOR: Ariel Sandez

Developers can now work with the Truebit-OS Docker container via API. The following blog shows you how to get started by creating a local environment to interact with the API using a local fork.

For those who are new, a Rest API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services.

This latest release to the Truebit-OS provides new functionality for developers by allowing developers to interact with the full range of truebit commands using Rest API. In that way, you can operate Truebit remotely and, more importantly, by using scripts to automate your desired execution or to incorporate it into your application workflow.

For example, you can submit a task verification using the Rest API (Post method) from your application. However, another process could be checking the task status using Rest API get Task and deciding on the result.

STEPS TO BE TAKEN

1. Clone the repo and build or Pull the image from Docker hub
2. Run the Docker image
3. Create Infura account and get the key
4. Install and launch Ganache
5. Launch Truebit-OS with Infura and API publish
6. Interact with the API using Curl
7. API References

Step 1: Clone the repo and build or Pull the image from Docker hub

git clone https://github.com/TruebitProtocol/truebit-eth

cd truebit-eth

docker build -t truebit-os:latest . –no-cache

Pull the image from Docker Hub

docker pull truebitprotocol/truebit-eth

Step 2: Run the Docker image (please follow the Getting Started Guide)

export mypass=secretclefpassword

export YYY=$HOME’/truebit-docker’

docker run -e TBPASS=$mypass -v $YYY/docker-clef:/root/.clef -v $YYY/docker-geth:/root/.ethereum -v $YYY/docker-ipfs:/root/.ipfs -v $YYY/docker-consensus:/root/.eth2 -p 3000:3000 — name truebit -dit truebitprotocol/truebit-eth:latest /bin/bash

Step 3: Create Infura account and get the key

For this article, we chose Infura, but you can use an ethereum node already synchronized with Goerli. (in case you want to configure a node, please follow this link)

Infura is a node provider that allows developers to “plug in” to the Ethereum blockchain via nodes managed by Infura itself, saving devs time, money, and work.

https://app.infura.io/

Create a new key.

Select MAINNET or Goerli and copy the URL

Step 4: Install and launch ganache.

Ganache is a private Ethereum blockchain environment that allows you to emulate the Ethereum blockchain to interact with smart contracts in your own private blockchain.

On your local machine, open a terminal and install Ganache.

npx hardhat node — network hardhat

Launch Ganache

ganache — fork.url <<YOUR INFURA URL>> — miner.blockTime 10

Step 5: Launch Truebit-Os with Infura and API publish

Enter into the Docker instance.

docker exec -it truebit /bin/bash

Launch Truebit-OS with the API in Ganache

./truebit-eth/truebit-linux — api ws://host.docker.internal:8545

Note: port 3000 is open for the API

Step 6: Interact with the API using Curl

We have everything set up at this point and can start interacting with Truebit. But first, we can check if the API is working.

Echo test

curl http://127.0.0.1:3000/api/echo/testMessage!

Example response

testMessage!

Step 7: API References

Methods: http://localhost:3000

GET:

• /api/ Heath check
• Example call: curl http://localhost:3000/api/
• Response: OK
• /api/echo/{MeSsAgE} Message test
• Example call: curl http://localhost:3000/api/
• Response: OK
• /api/accounts List all the Ethereum accounts
• Example call: curl http://localhost:3000/api/accounts
• Response: Json format, list of Ethereum addresses
• /api/processes List all the started solver and verifiers
• Example call: curl http://localhost:3000/api/processes
• Response: Json format, solver and verifiers, index number and Ethereum address
• /api/solver/status/{solver index}
• Example call: http://localhost:3000/api/solver/status/0
• Response: Json format, solver address and status
• /api/solver/status/{:processNumber} Return the process status
• Example call: http://localhost:3000/api/status/0
• Response: Json format, process address and status
• /api/tasks List all the running tasks
• Example call: http://localhost:3000/api/tasks
• Response: List of task and operations
• /api/verifier/status/{verfier index} Return verifier status
• Example call: curl http://localhost:3000/api/verifier/status/0
• Response: Verifier account and status
• /api/tasks/:taskHash/parameters Return parameters used for task execution
• Example call: http://localhost:3000/api/tasks/{{ taskHash }}/parameters
• Response: Json format, parameter list and values
• /api/tasks/{{ taskHash }}/status Return status of a TaskHash
• Example call: http://localhost:3000/api/tasks/{{ 0xffa9cad5f9a702548781e770e7873a94f54a4865ebf619d2d9ff996cd9826ea8}}/status
• Response: Task status

POST

• /api/solver/start Start new solver
• Example call: curl -X POST http://localhost:3000/api/solver/start -H ‘Content-Type: application/json’ -d ‘{ “account”:0, “test”: true, “limit”: 1, “recover”:-1, “price”:0 }’
• Response: Account number and operation status
• /api/solver/stop Stop existing solver
• Example call: curl -X POST http://localhost:3000/api/solver/stop -H ‘Content-Type: application/json’ -d ‘{ “process”:0 }’
• Response: Account number and operation status
• /api/verifier/start Star new verifier
• Example call: curl -X POST http://127.0.0.1:3000/api/verifier/start -H “Content-Type: application/json” -d ‘{“account”: 1, “test”: false, “limit”: 1, “recover”: -1, “price”: 0}’
• Response: Account number and operation status
• /api/solver/stop Stop existing verifier
• Example call: curl -X POST http://localhost:3000/api/verifier/stop -H ‘Content-Type: application/json’ -d ‘{ “process”:0 }’
• Response: Verifier number and operation status
• /api/tasks/submit Submit Task
• Example call: curl -X POST http://localhost:3000/api/tasks/submit -H ‘Content-Type: application/json’ -d ‘{ “account”:0,”taskFile”: “factorial.json” }’
• Response: Task Hash and operation status