> For the complete documentation index, see [llms.txt](https://tookey.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tookey.gitbook.io/docs/product-guides/igniter/scenarios/scenarios-api-reference.md).

# Scenarios API Reference

### Example Scenario spec <a href="#example-v2-job-spec" id="example-v2-job-spec"></a>

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

```toml
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](https://pkg.go.dev/github.com/robfig/cron?utm_source=godoc).

### OnchainRequest Scenario <a href="#job-type-specific-pipeline-variables" id="job-type-specific-pipeline-variables"></a>

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.

<br>

<br>