🎛️Scenarios API Reference

Example Scenario spec

The following is an example cron job spec. This is a simple spec that you can add to the Igniter:

type            = "cron"
name            = "Example Cron scenario"
schemaVersion   = 1
schedule        = "CRON_TZ=UTC 0 0 1 1 *"
maxTaskDuration = 

# Gets actual price from CoinGecko and commit to blockchain
observationSource   = """
request     [type="http" method=GET url="https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd"];
parse       [type="jsonparse" path="ethereum,usd"];
decimals    [type="multiply" times=1000000];
encode      [type="ethabiencode"
             abi="updatePrice(uint256 price)"
             data="{\\"price\\": $(decimals) }"];
encode_tx   [type="ethtxencode"
             chainId="1"
             to="0x0000000000000000000000000000000000000000"
             data="$(encode)"];
sign_tx     [type="sign"
             hash="$(encode_tx.hash)"];
broadcast.  [type="ethtxbroadcast"
             chainId="1"
             tx="$(encode_tx)"
             signature="$(sign_tx)"]
             
request -> parse -> decimals -> encode -> encode_tx -> sign_tx -> broadcast;
"""

Every job type supported by a node shares the following TOML fields:

• name: The name of the scenario

• type: Specifies the scenario type, which can be one of the following:

  • cron

  • onchainrequest

  • monitor

  • keeper

  • webhook

• observationSource: The pipeline task DAG, which is specified in DOT syntax. See below for information on writing pipeline DAGs.

• maxTaskDuration: The default maximum duration that any task is allowed to run. If the duration is exceeded, the task is errored. This value can be overridden on a per-task basis using the timeout attribute.

Cron Scenario

Executes a scenario on a schedule. Does not rely on any kind of external trigger.

Fields

• schedule: the frequency with which the scenario is to be run. There are two ways to specify this:

  • Traditional UNIX cron format, but with 6 fields, not 5. The extra field allows for “seconds” granularity.

  • @ shorthand, e.g. @every 1h. This shorthand does not take account of the node’s timezone, rather, it simply begins counting down the moment that the scenario is added to the Igniter (or the Igniter is rebooted).

For all supported schedules, please refer to the cron library documentation.

OnchainRequest Scenario

Executes a scenario upon receipt of an explicit request made on a supported chain. The request is detected via a log emitted by an contract.

Fields

• contractAddress: The contract to monitor for requests

• chainId: The identificator of the selected blockchain

• requesters: Optional - Allows whitelisting requesters

• minIncomingConfirmations Optional - Allows you to specify the number of blocks to wait before execution of the scenario

Pipeline variables

• $(run.logBlockHash): the block hash in which the initiating log was received.

• $(run.logBlockNumber): the block number in which the initiating log was received.

• $(run.logTxHash): the transaction hash that generated the initiating log.

• $(run.logAddress): the address of the contract to which the initiating transaction was sent.

• $(run.logTopics): the log’s topics (indexed fields).

• $(run.logData): the log’s data (non-indexed fields).

• $(run.blockReceiptsRoot) : the root of the receipts trie of the block (hash).

• $(run.blockTransactionsRoot) : the root of the transaction trie of the block (hash).

• $(run.blockStateRoot) : the root of the final state trie of the block (hash).

Webhook Scenario

Webhook scenario can be initiated by HTTP request made by trusted external initiator (authenticated with JWT token).

Fields

• externalInitiators: an array of {name, spec} objects, where name is the name registered with the node, and spec is the job spec to be forwarded to the external initiator when it is created.

Pipeline variables

• $(run.requestBody): the body of the request that initiated the job run.