Getting Started Guide

Follow our Getting Started guide to install the Truebit CLI and connect to the pre-configured Truebit Developer Node, available for community use. This platform enables developers to simulate the Truebit network’s execution environment, ensuring optimal performance and reliability before deployment in production.

Prerequisites

• node.js: 22.13.1 or higher

• npm: 10.7.0 or higher

1. Installing the Truebit CLI

Install the Truebit CLI globally by using the following command:

npm i -g @truebit/cli

Then, run:

truebit

This command will verify the installation and accept the Terms of Use.

2. Register Into Truebit

Already Have An Account?

If you already registered into Truebit, please follow the instruction below:

Update the secret.json file located in the ~/.truebit directory

{
  "address": "your-wallet-address",
  "privateKey": "your-private-key"
}

Create New Account

To setup a new Truebit account, please run the following command:

truebit setup 

You will need to accept the Terms of Use. Once accepted, you will see the following result:

A new secret.json file containing your account information has been created at: /Users/<username>/.truebit/secret.json.

Welcome to Truebit Verify!

Your all-in-one solution to develop, build, test, and deploy tasks seamlessly.
Let's get started by setting up your account and configuring your wallet.
We'll guide you through each step to ensure a smooth experience.

**Important: Private Key Information

Truebit Verify employs a private key system to secure your account:

  - A unique private key will be automatically generated for you.
  - This key serves as your secure identifier within Truebit Verify.
  - It's used internally to authenticate your actions.
  - You won't need to manage this key directly.

We are committed to ensuring the security of your private key and safeguarding your account.
Ready to begin?
Press [Y] to proceed or [N] to exit: 

Create An Account

Step 1:

Step 1: Create an Account

It appears you're a new user without a wallet configured locally.

Would you like to create a new wallet now?
Press [Y] to proceed or [N] to skip:

Once you type "Y":

Setting up your new wallet...

Your new wallet address is: <wallet>

Your wallet information has been securely stored in /Users/<username>/.truebit/secret.json
Please keep this file safe, as it contains your credentials for using Truebit Verify.

Step 2:

To finally create an account, the system will need the following information:

• Name: Your full name

• Verification Email: An email address

• Company Name: Your company’s name

• Job Position: Your job position

• EULA Acceptance: Accept the End User License Agreement (EULA) [ Y|N ]

Now that your wallet is set up, let's create your Truebit Verify account.

Please provide the following information:

1. Full Name: John Doe
2. Email Address: [email protected]
3. Company Name: Acme
4. Job Position: Senior Developer
5.Accept EULA? [Y|N] (https://truebit.io/terms/): Y

Is the information provided above correct?
Press [Y] to confirm or [N] to edit: Y

By completing registration, you'll be automatically subscribed to our newsletter.
To opt-out, please follow the steps described in our documentation portal.

... registering your account.

Thanks for registering to Truebit Verify!

Congratulations! Your Truebit Verify account has been successfully created. 

Account Summary: 
- Name: John Doe 
- Email: [email protected] 
- Company: Acme 
- Position: Senior Developer 
- Wallet Address: 0xfc046e7cd36ffff3e59642387dca6dcd76c9b355
- Namespace: J349oiAO // API Key: 0x109435FR78

Run 'truebit --help' at any time to get started

If you'd like to view your personal information again, please run truebit setup.

3. Working With Your First Function Task

Download The Examples

Clone the examples repository to start working with Truebit.

git clone https://github.com/TruebitProtocol/truebit-nextgen-examples.git

We have created example tasks so you can get familiar with the process of testing and deploying code. You can learn more about creating your own Function and API Tasks.

For now, we will use one of the examples (Fibonacci) to demonstrate how to use the CLI to test and deploy Function Tasks, and the platform's REST API to execute and verify them.

Build

This command will build the Fibonacci task.

truebit build truebit-nextgen-examples/function-tasks/js/fibonacci/dist -l js

As a result of running the build command, you will receive a TaskId, which serves as the unique identifier for your task.

Testing

This command will run the Fibonacci task and provide the result and total steps executed:

truebit start <taskId> 15

• [taskId]: Add the taskId generated in the previous step.

Deploy And Register Your Function task.

This command will deploy and register the Fibonacci task.

truebit deploy <namespace> <taskname> --taskId <taskId>

• [namespace]: Use your default namespace registered in Step 2 - User Creation

• [taskname]: Choose a representative name for your task. i.e: fibonacci

• [taskId]: Add the taskId generated in the previous step

4. Executing Your First Function Task

Execute The Function Task

1. Access the Task execution Swagger UI here: Swagger UI for Truebit.

2. Open the /task/function/execute-by-name endpoint and click "Try it Out" to test it.

3. Update the following parameters in the request body:

   • namespace: Use the namespace from Step 3 – Deploy and register your Function Task

   • taskname: Use the task name from Step 3 – Deploy and register your Function Task

   • async: Set to false

4. Add your API Key from Step 2 – Register into Truebit in the x-api-key parameter.

If you don’t remember your namespace or API key, please run truebit setup again to retrieve your personal information.

You should receive the following answer

{
  "executionId": "08c717bb-f92a-4f43-96a7-940e9ef37983",
  "clearTextSolution": {
    "signature": {
      "v": 27,
      "r": "997e437a3c2828d141ea7038e68391ffa3bbc4447c5e03e72e90b981d12cf30f",
      "s": "3b503da5ba6225137ec6f546de93bbbe8a7092091c557ea1a3bc9aad27b3ba75"
    },
    "output": "6765",
    "status": "succeed",
    "senderAddress": "0x344462d1a0a3a61945aa9dd4c072df8caed1af86"
  },
  "status": "Success"
}

Get The Transcript

• Access the Transcript swagger UI here: Swagger UI for Truebit

• Use the /task/{executionId}/transcript endpoint, passing the executionId value obtained from the previous execution as a parameter

You should get the transcript associated with the given executionId.

5. Working With Your First API Task

Create-api

This command will create the API task.

truebit create-api truebit-nextgen-examples/api-tasks/petstore-crud/manifest.json 

Deploy And Register Your API task

This command will deploy and register the Fibonacci task.

truebit deploy <namespace> <taskname> --taskId <taskId>

• [namespace]: Use your default namespace registered in Step 2 - User Creation

• [taskname]: Choose a representative name for your task. i.e: petstore

• [taskId]: Add the taskId generated in the previous step.

6. Executing Your First API task

Execute The API Task

1. Access the task execution Swagger UI here: Swagger UI for Truebit.

2. Open the /task/api/execute-by-name endpoint and click "Try it Out" to test it.

3. Add your API Key from Step 2 – Register into Truebit in the x-api-key parameter.

4. Update the following parameters in the request body and click on "Execute":

   • namespace: Use the namespace from Step 6 – Deploy and register your API task

   • taskname: Use the task name from Step 6 – Deploy and register your API task

   • async: Set to false

   • input:

  "input": {
    "path": "/store/order",
    "method": "POST",
    "body": {
      "id": 2,
      "petId": 198772,
      "quantity": 7,
      "shipDate": "2077-08-24T14:15:22Z",
      "status": "approved",
      "complete": true
    }
  }

If you don’t remember your namespace or API key, please run truebit setup again to retrieve your personal information.

The following answer should appear:

{
  "executionId": "fb8bbaf4-8fb6-49d7-b089-f22c37b0285e",
  "clearTextSolution": {
    "output": {
      "id": 2,
      "petId": 198772,
      "quantity": 7,
      "shipDate": "2077-08-24T14:15:22.000+0000",
      "status": "approved",
      "complete": true
    },
    "status": "succeed",
    "senderAddress": "0xd70c3454aad1b7ec660a064d8b1fe5708d898d84"
  },
  "status": "Success",
  "totalTransferredBytes": {
    "request": 220,
    "response": 438
  }
}

Get The Transcript

• Access the Transcript swagger UI here: Swagger UI for Truebit

• Use the /task/{executionId}/transcript endpoint, passing the executionId value obtained from the previous execution as a parameter

You should get the transcript associated with the given executionId.

7. Explore Truebit in Action

By now, you’ve gone through the full journey: From installing and registering with Truebit to creating your first task locally, deploying it to the Truebit cloud, and obtaining a verifiable transcript. Now, it's time to see everything in action on a website.

To demonstrate this, we’ve built a demo page that executes a verifiable Fibonacci computation. How does it work? The page calls the Truebit execution endpoint and retrieves the corresponding verification transcript.

We run a limited-capacity Stake Sponsorship Program to support selected node operators. If you’d like to be considered for an invitation, please submit your request via http://forms.truebit.io/