Skip to main content

x/async

Overview​

The x/async module is a Cosmos SDK module for running offchain heavyweight computations asynchronously and storing the results onchain. It uses the ABCI 2.0 framework and its vote extensions.

This module implements the following concepts:

Usage​

You can call the x/async module from your EVM smart contract using the x/async precompile. This module allows you to build any logic combining offchain computation with onchain verification.

At this moment, x/async supports two types of computations:

  • AI-driven price predictions
  • HTTP requests to external services, such as blockchain APIs

You can learn the basics and then dive deeper by following these guides:

Concepts​

Task​

A Task is an offchain user-defined unit of computation that is executed asynchronously. The result is stored onchain.

A user can request a Task, specifying an input and a Plugin, which determines what format of input to accept and how to handle it. There are different types of Tasks, depending on the Plugin type.

After that, a validator running a Prophet executes the Plugin and provides the Task result of a Task. Other validators vote on correctness of the result. It takes several blocks to get the output, but it doesn't slow the blockchain down thanks to asynchronous execution.

You can learn more in the Task execution flow section of this article.

Plugin​

A Plugin is code that determines what kind of Task input to accept and how to handle it in order to retrieve the result (output). In other words, the type of the computation to be executed depends on the Plugin type.

When requesting a Task, a user references a Plugin by ID. Then the Plugin is executed by a Prophet.

Developers can create their own Plugins or use the existing ones. Currently, we support two Plugins, which allow executing price predictions and HTTP requests.

You can learn more in the Plugins section of this article.

Prophet​

A Prophet is a subprocess running on validator nodes, which has two responsibilities:

  • Fetching Task requests and executing Plugins to provide Task results
  • Fetching requests satisfied by other validators to vote on the results

Prophets run on validator nodes separately from the wardend process, without blocking the consensus. Running a Prophet is optional for a validator.

You can learn more in the Prohpets section of this article.

State​

The x/async module keeps track of Tasks.

Completed Tasks are pruned after some time, to avoid state bloat.

Messages​

MsgAddFuture​

Creates a new Task, providing the following:

  • A []byte input
  • A string ID of the Plugin to use
  • The address of a callback contract (optional)
Notes
  • The Task has the pending status until it has a result. Users can query Tasks by their IDs to check the progress.
  • The callback contract must have a cb() function, allowing it to be invoked once the Task is ready.

Plugins​

pricepred​

The pricepred Plugin allows producing AI-driven price predictions.

You can find a usage example in the following guide: Implement automated Orders with price prediction.

http​

The http Plugin allows making HTTP requests to any external service. For example, developers can use x/async as an advanced oracle service for fetching token prices from external APIs.

Note that Warden automatically converts HTTP responses to the CBOR format.

You can find a usage example in the following guide: Use the HTTP Plugin.

Prophets​

Executing Tasks​

A Prophet continuously polls the chain to discover new pending Tasks, maintaining a local queue for them.

At the same time, a Prophet takes Tasks from the queue, and executes Plugins referenced in these Tasks to generate Task results. This usually involves calling an external service.

The results are stored in the memory for the blockchain node to fetch it later.

Voting on Task results​

A Prophet continuously polls the chain to discover Tasks that have a result submitted by another validator, maintaining a local queue for them.

Concurrently, Tasks are taken from the queue and validated (this usually involves calling an external service).

The votes are stored in memory for the blockchain node to fetch it later.

ABCI lifecycle​

The ABCI (Application Blockchain Interface) lifecycle includes these steps:

  1. Preparing a proposal
    Vote extensions from the previous block are processed and included in the proposal for the next block. The proposer validator also fetches new results from its Prophet instance and includes them in a special transaction at the beginning of the block proposal.
  2. Broadcasting votes
    Then all validators, even non-proposers, fetch votes on existing Tasks from their Prophets and broadcast these votes as vote extensions.
  3. Finalizing the block
    When the proposal is processed (for example, the block is finalized), all new results and new votes are persisted in the blockchain storage, ready to be consumed.

Task execution flow​

Task execution includes the following steps, as shown in the diagram below:

  1. A user (Alice) inserts a new Task with an input (2+4) and a reference to a Plugin (MathPlugin).
  2. Node 1 asynchronously executes the Plugin (MathPlugin), providing a Task result.
  3. When Node 1 is elected as the proposer for a block (H+N), it inserts the result (6) to be recorded.
  4. Node 2 notices the new result for the Task and invokes its Plugin (MathPlugin) to verify the result.
  5. The verification is broadcasted as vote extensions and eventually recorded at height H+N+M+1 since vote extensions are committed to the state only in the next block.