API Task

This Dynamic Oracle implementation allows your smart contract to execute a pre deployed Truebit API Task, providing off-chain computation with on-chain guarantees.

To execute a Truebit task, you must first deploy it using the Truebit CLI (run truebit deploy). Once deployed, you will need both the namespace and the task name of your API task.

1

Inherit From BaseTBContract

Import BaseTBContract.sol contract and extend from it.

2

Constructor

When deploying the contract, ensure you set the correct values for both watchTowerAddress and sourceCode within your contract:

• watchTowerAddress: 0xEcd0EeD24Ed6a54d05a07125c4ccb809b3A09868.

• sourceCode: In the case of API task this value must be an empty string ("").

3

Submitting a Request

In your contract, call the _requestExecution function. This will trigger the task execution on the Truebit platform.

To Call the _requestExecution You must:

1. Define the method signature string.

2. Encode all parameters using abi.encode .

3. Specify the execution type as: DOTypes.ExecutionType.API .

Method Signature

The method signature must follow a strict format. It begins with the method name (in this case, "request"), followed by parentheses containing the parameter definitions, separated by commas.

The following parameters are required and must appear in this exact order with the specified names:

namespace, taskname, method, path, executionTimeout, async

Depending on your API call, you may also include:

• params() — if your endpoint uses path or query parameters.

• body — if your call includes a request body (e.g. for POST/PUT).

If params() is required, you must specify the key and type inside the parentheses, for example:

params(orderId:uint256)

Multiple parameters can be separated by commas.

If body is also needed, it should appear after params() or async, depending on whether parameters are present.

Examples:

Only params:

request(namespace,taskname,method,path,executionTimeout,async,params(orderId:uint256))

Only body:

request(namespace,taskname,method,path,executionTimeout,async,body)

Both params and body:

request(namespace,taskname,method,path,executionTimeout,async,params(orderId:uint256),body)

4

Filling The Payload

Once the method signature is defined, you must fill the payload with the values for the parameter defined on the signature, and encode it using abi.encode(...).

The payload values are the following:

1. The namespace where the task was deployed.

2. The name of the task defined at deployment.

3. The HTTP method to call (GET, POST, PUT, DELETE, PATCH).

4. The endpoint path you want to call in your Truebit API task.

5. The executionTimeout (e.g. 100000).

6. The async flag:

   1. true → returns an executionId immediately.

   2. false → waits until the task completes and returns the response.

7. (Optional) Any path/query parameters.

8. (Optional) The body content.

5

Call _requestExecution

Finally, you call _requestExecution() with:

• The method signature (string).

• The encoded payload (bytes).

• The execution type: DOTypes.ExecutionType.API .

bytes memory payload = abi.encode(
    'Your Namespace', // namespace - identifies the API collection
    'Your Taskname',      // taskname - specific API task to execute
    'GET',      // HTTP method
    '/store/order/{orderId}', // API endpoint path
    100000,     // executionTimeout - max time for execution
    false,      // async - whether to run asynchronously
    orderId     // orderId - the parameter for the API call
);
// Submit the execution request to the Truebit network
uint256 wtExecutionId = _requestExecution(
    "request(namespace,taskname,method,path,executionTimeout,async,params(orderId:uint256))",
    payload,
    DOTypes.ExecutionType.API
);

6

Handling The Callback

When the execution is finished, your will receive the result within the callbackTask .

function callbackTask(
        bytes calldata resultData, 
        string[] memory transcripts, 
        uint256 wtExecutionId, 
        uint8 status,
        string memory callbackMessageDetails
    ) external override onlywatchTower {

• resultData: The encoded result data from the execution.

• transcripts: Array of execution transcripts for verification.

• wtExecutionId: The execution identifier.

• status: Execution status (0 = success, >0 = error).

• callbackMessageDetails: Additional details about the execution.

Status types

Status	Code	Description
SUCCESS	0	The execution completed successfully.
FAILED	1	This execution is invalid. Check the callbackMessageDetails for more information.
ERROR	2	A verified error occurred during execution. The network did reach consensus, and the agreed-upon result is that the program failed.
EXCEEDED	3	Execution was halted for exceeding the computational resource limit. You Should optimize your program or reduce input size before retrying.
CODE_HASH_MISMATCH	4	The executed code's hash does not match the one committed in the original ExecutionRequest .

Key considerations:

• Always check status before decoding resultData

• Treat all non-zero statuses as failures; the exact value is useful for logging but your control flow should not depend on it.

Grant Permissions

User Contract Permission

In order to authorize the user contract, the task developer must grant permissions to the user contract over the namespace called in the _requestExecution. To do so, please use the following CLI command

truebit auth grant <namespace_to_grant> <address_grantee>

• namespace_to_grant: Namespace mentioned in _requestExecution.

• address_grantee: Contract address.

Truebit Verify Hub Access

Each user who wants to execute API or Function Tasks via Dynamic Oracle must grant permissions to the Truebit Verify address to complete the connection. For example:

truebit auth grant <namespace_to_grant> <truebit_hub_address>

• namespace_to_grant: Namespace mentioned in _requestExecution.

• truebit_hub_address: 0xd70C3454aaD1B7ec660a064d8b1FE5708d898d84.