Task Types
This guide outlines different task types.
'Any' task
Returns a random value from the set of inputs passed in.
Parameters
None.
Inputs
Can be anything.
Outputs
A randomly-selected value from the set of inputs.
Example
fetch1 [type="http" ...]
fetch2 [type="http" ...]
fetch3 [type="http" ...]
pick_any [type="any"]
fetch1 -> pick_any
fetch2 -> pick_any
fetch3 -> pick_any
pick_any
will return either the result of fetch1
, fetch2
, or fetch3
.
Base64 Decode task
Accepts a base64 encoded string and returns decoded bytes.
Parameters
input
: a base64 encoded string.
Outputs
Decoded bytes.
Example
my_base64decode_task [type="base64decode" input="SGVsbG8sIHBsYXlncm91bmQ="]
Given the input SGVsbG8sIHBsYXlncm91bmQ=
, the task will return Hello, playground
(as ASCII bytes).
Base64 Encode task
Encodes bytes/string into a Base64 string.
Parameters
input
: Byte array or string to be encoded.
Outputs
String with Base64 encoding of input.
Example
my_base64encode_task [type="base64encode" input="Hello, playground"]
Given the input string "Hello, playground", the task will return "SGVsbG8sIHBsYXlncm91bmQ=".
Bridge task
Bridge tasks make HTTP POST requests to pre-configured URLs. Bridges can be configured via the UI or the CLI, and are referred to by a simple user-specified name. This is the way that most jobs interact with External Adapters.
Parameters
name
: an arbitrary name given to the bridge by the node operator.requestData
(optional): a statically-defined payload to be sent to the external adapter.cacheTTL
(optional): a duration-formatted string indicating the maximum acceptable staleness for cached bridge responses in case of intermittent failures. This is disabled by default.headers
(optional): an array of strings. The number of strings must be even. Example:foo [type="bridge" name="foo" headers="[\\"X-Header-1\\", \\"value1\\", \\"X-Header-2\\", \\"value2\\"]"]
Outputs
A string containing the response body.
Example
my_bridge_task [type="bridge"
name="some_bridge"
requestData="{\\"data\\":{\\"foo\\": $(foo), \\"bar\\": $(bar)}}"
]
CBOR Parse task
CBOR Parse tasks parse a CBOR payload, typically as part of a Direct Request workflow. In Direct Request, a user makes an onchain request using a ChainlinkClient
contract, which encodes the request parameters as CBOR. See below for an example.
Parameters
data
: A byte array containing the CBOR payload.mode
: An optional parameter that specifies how to parse the incoming CBOR. The default mode isdiet
, which expects the input to be a map. Set the mode tostandard
to pass literal values through "as-is". Empty inputs return nil.
Outputs
A map containing the request parameters. Parameters can be individually accessed using $(dot.accessors)
.
Example
// First, we parse the request log and the CBOR payload inside of it
decode_log [type="ethabidecodelog"
data="$(jobRun.logData)"
topics="$(jobRun.logTopics)"
abi="SomeContractEvent(bytes32 requestID, bytes cborPayload)"]
decode_cbor [type="cborparse"
data="$(decode_log.cborPayload)"]
// Then, we use the decoded request parameters to make an HTTP fetch
fetch [type="http" url="$(decode_cbor.fetchURL)" method=GET]
parse [type="jsonparse" path="$(decode_cbor.jsonPath)" data="$(fetch)"]
// ... etc ...
See the Direct Request page for a more comprehensive example.
Divide task
Divides the provided input
by the divisor
and returns the result with a number of decimal places defined in the precision
value.
Parameters
input
: The value to be divided- number
- stringified number
- bytes-ified number
$(variable)
divisor
: The value by which to divide theinput
- number
- stringified number
- bytes-ified number
$(variable)
precision
: The number of decimal places to retain in the result- number
- stringified number
- bytes-ified number
$(variable)
Outputs
The result of the division.
Example
my_divide_task [type="divide"
input="$(json_parse_result)"
divisor="3"
precision="2"]
Given the input 10
, this example returns 3.33
.
ETH ABI Decode Log task
Decodes a log emitted by an ETH contract.
Parameters
abi
: a canonical ETH log event definition. Should be formatted exactly as in Solidity. Each argument must be named. Examples:NewRound(uint256 indexed roundId, address indexed startedBy, uint256 startedAt)
AuthorizedSendersChanged(address[] senders)
data
: the ABI-encoded log data. Can be:- a byte array
- a hex-encoded string beginning with
0x
- ... but generally should just be set to
$(jobRun.logData)
(see the Direct Request page)
topics
: the ABI-encoded log topics (i.e., theindexed
parameters)- an array of bytes32 values
- an array of hex-encoded bytes32 values beginning with
0x
- ... but generally should just be set to
$(jobRun.logTopics)
(see the Direct Request page)
Outputs
A map containing the decoded values.
Example
decode [type="ethabidecodelog"
abi="NewRound(uint256 indexed roundId, address indexed startedBy, uint256 startedAt)"
data="$(jobRun.logData)"
topics="$(jobRun.logTopics)"]
This task will return a map with the following schema:
{
"roundId": ..., // a number
"startedBy": ..., // an address
"startedAt": ..., // a number
}
ETH ABI Decode task
Decodes a ETH ABI-encoded payload, typically the result of an ETH Call task.
Parameters
abi
: a canonical ETH ABI argument string. Should be formatted exactly as in Solidity. Each argument must be named. Examples:uint256 foo, bytes32 bar, address[] baz
address a, uint80[3][] u, bytes b, bytes32 b32
data
: the ABI-encoded payload to decode. Can be:- a byte array
- a hex-encoded string beginning with
0x
Outputs
A map containing the decoded values.
Example
decode [type="ethabidecode"
abi="bytes32 requestID, uint256 price, address[] oracles"
data="$(eth_call_result)"]
This task will return a map with the following schema:
{
"requestID": ..., // [32]byte value
"price": ..., // a number
"oracles": [
"0x859AAa51961284C94d970B47E82b8771942F1980",
"0x51DE85B0cD5B3684865ECfEedfBAF12777cd0Ff8",
...
]
}
ETH ABI Encode task
Encodes a bytes payload according to ETH ABI encoding, typically in order to perform an ETH Call or an ETH Tx.
Parameters
abi
: a canonical ETH ABI argument string. Should be formatted exactly as in Solidity. Each argument must be named. If a method name is provided, the 4-byte method signature is prepended to the result. Examples:uint256 foo, bytes32 bar, address[] baz
fulfillRequest(bytes32 requestID, uint256 answer)
data
: a map of the values to be encoded. The task will make a best effort at converting values to the appropriate types.
Outputs
A byte array.
Example
encode [type="ethabiencode"
abi="fulfillRequest(bytes32 requestID, uint256 answer)"
data="{\\"requestID\\": $(foo), \\"answer\\": $(bar)}"
]
ETH Call task
Makes a non-mutating contract call to the specified contract with the specified data payload.
Parameters
contract
: the address of the contract to call.data
: the data to attach to the call (including the function selector).gas
: the amount of gas to attach to the transaction.from
: The from address with which the call should be made. Defaults to zero address.gasPrice
: The gasPrice for the call. Defaults to zero.gasTipCap
: The gasTipCap (EIP-1559) for the call. Defaults to zero.gasFeeCap
: The gasFeeCap (EIP-1559) for the call. Defaults to zero.gasUnlimited
: A boolean indicating if unlimited gas should be provided for the call. If set to true, do not pass thegas
parameter.evmChainID
: Set this optional parameter to transmit on the given chain. You must have the chain configured with RPC nodes for this to work. If left blank, it will use the default chain.
Outputs
An ABI-encoded byte array containing the return value of the contract function.
Example
encode_call [type="ethabiencode"
abi="checkUpkeep(bytes data)"
data="{ \\"data\\": $(upkeep_data) }"]
call [type="ethcall"
contract="0xa36085F69e2889c224210F603D836748e7dC0088"
data="$(encode_call)"
gas="1000"]
decode_result [type="ethabidecode"
abi="bool upkeepNeeded, bytes performData"
data="$(call)"]
encode_call -> call -> decode_result
ETH Tx task
Makes a mutating transaction to the specified contract with the specified data payload. The transaction is guaranteed to succeed eventually.
Parameters
from
: one or more addresses of the externally-owned account from which to send the transaction. If left blank, it will select a random address on every send for the given chain ID.to
: the address of the contract to make a transaction to.data
: the data to attach to the call (including the function selector). Most likely, this will be the output of anethabiencode
task.gasLimit
: the amount of gas to attach to the transaction.txMeta
: a map of metadata that is saved into the database for debugging.minConfirmations
: minimum number of confirmations required before this task will continue. Set to zero to continue immediately. Note that this does not affect transaction inclusion. All transactions will always be included in the chain up to the configured finality depth.evmChainID
: set this optional parameter to transmit on the given chain. You must have the chain configured with RPC nodes for this to work. If left blank, it will use the default chain.failOnRevert
: an optional parameter, a boolean, that allows a ChainLink node operator's UI to display and color the status of the task within a job's pipeline depending on a transaction status. default: false.
Outputs
The hash of the transaction attempt that eventually succeeds (after potentially going through a gas bumping process to ensure confirmation).
Example
encode_tx [type="ethabiencode"
abi="performUpkeep(bytes performData)"
data="{ \\"data\\": $(upkeep_data) }"]
submit_tx [type="ethtx"
to="0xa36085F69e2889c224210F603D836748e7dC0088"
data="$(encode_tx)"
failOnRevert="true"]
encode_tx -> submit_tx
Hex Decode task
Accepts a hexadecimal encoded string and returns decoded bytes.
Parameters
input
: a hexadecimal encoded string, must have prefix0x
.
Outputs
Decoded bytes.
Example
my_hexdecode_task [type="hexdecode" input="0x12345678"]
Given the input 0x12345678
, the task will return [0x12, 0x34, 0x56, 0x78]
.
Hex Encode task
Encodes bytes/string/integer into a hexadecimal string.
Parameters
input
: Byte array, string or integer to be encoded.
Outputs
Hexadecimal string prefixed with "0x" (or empty string if input was empty).
Example
my_hexencode_task [type="hexencode" input="xyz"]
Given the input string "xyz", the task will return "0x78797a", which are the ascii values of characters in the string.
HTTP task
HTTP tasks make HTTP requests to arbitrary URLs.
Parameters
method
: the HTTP method that the request should use.url
: the URL to make the HTTP request to.requestData
(optional): a statically-defined payload to be sent to the external adapter.allowUnrestrictedNetworkAccess
(optional): permits the task to access a URL atlocalhost
, which could present a security risk. Note that Bridge tasks allow this by default.headers
(optional): an array of strings. The number of strings must be even. Example:foo [type=http headers="[\\"X-Header-1\\", \\"value1\\", \\"X-Header-2\\", \\"value2\\"]"]
Outputs
A string containing the response body.
Example
my_http_task [type="http"
method=PUT
url="http://chain.link"
requestData="{\\"foo\\": $(foo), \\"bar\\": $(bar), \\"jobID\\": 123}"
allowUnrestrictedNetworkAccess=true
]
JSON Parse task
JSON Parse tasks parse a JSON payload and extract a value at a given keypath.
Parameters
data
: the JSON string. Can be:- string
- byte array
path
: the keypath to extract. Must be a comma-delimited list of keys, or specify a customseparator
alternative.separator
: (optional) custompath
key separator. Defaults to comma (,
).lax
(optional): if false (or omitted), and the keypath doesn't exist, the task will error. If true, the task will returnnil
to the next task.
Outputs
The value at the provided keypath.
Example
my_json_task [type="jsonparse"
data="$(http_fetch_result)"
path="data,0,price"]
This task returns 123.45
(float64) when given the following example data
value:
{
"data": [{ "price": 123.45 }, { "price": 678.9 }]
}
Length task
Returns the length of a byte array or string.
Parameters
input
: Byte array, or string to get the length for.
Outputs
The length of the byte array or string.
Note: For strings containing multi-byte unicode characters, the output is the length in bytes and not number of characters.
Example
my_length_task [type="length" input="xyz"]
Given the input string "xyz", the task will return 3, length of the string.
Less Than task
Returns a boolean, result of computing left LESS_THAN right
.
Parameters
left
: the left hand side of comparison. Possible values:- number
- stringified number
- bytes-ified number
$(variable)
right
: the right hand side of comparison. Possible values:- number
- stringified number
- bytes-ified number
$(variable)
Outputs
The result of less than comparison.
Example
my_lessthan_task [type="lessthan" left="3" right="10"]
the task will return true which is the result of 3 LESS_THAN 10
Lowercase task
Accepts a string and returns a lowercase string.
Parameters
input
: a string.
Outputs
Lowercase string.
Example
my_lowercase_task [type="lowercase" input="Hello World!"]
Given the input Hello World!
, the task will return hello world!
.
Mean task
Accepts multiple numerical inputs and returns the mean (average) of them.
Parameters
values
: an array of values to be averaged.allowedFaults
(optional): the maximum number of input tasks that can error without the Mean task erroring. If not specified, this value defaults toN - 1
, whereN
is the number of inputs.precision
: the number of decimal places in the result.
Outputs
The average of the values in the values
array.
Example
my_mean_task [type="mean"
values=<[ $(fetch1), $(fetch2), $(fetch3) ]>
precision=2
allowedFaults=1]
Given the inputs 2
, 5
, and 20
, the task will return 9
.
Median task
Accepts multiple numerical inputs and returns the median of them.
Parameters
values
: an array of values from which to select a median.allowedFaults
(optional): the maximum number of input tasks that can error without the Median task erroring. If not specified, this value defaults toN - 1
, whereN
is the number of inputs.
Outputs
The median of the values in the values
array.
Example
my_median_task [type="median"
values=<[ $(fetch1), $(fetch2), $(fetch3) ]>
allowedFaults=1]
Given the inputs 2
, 5
, and 20
, the task will return 5
.
Memo task
The memo
task returns its value as a result.
Parameters
value
: value to return. Possible values:- number
- boolean
- float
- string
- array
Outputs
The value.
Example
memo [type="memo" value="10"]
The task will return the value 10
Merge task
Merge task returns the merged value of two maps.
Parameters
left
: The left map.right
: The right map, which overwrites the left side.
Outputs
Returns the combined map of left and right. If the merged map is invalid, it returns null
.
Example
merge [type="merge" left="{\\"foo\\":\\"abc\\", \\"bar\\":\\"123\\"}" right="{\\"bar\\":\\"xyz\\", \\"biz\\":\\"buzz\\"}"]
This example task returns the following map:
{ "foo": "abc", "bar": "xyz", "biz": "buzz" }
Mode task
Accepts multiple numerical inputs and returns the mode (most common) of them. If more than one value occur the maximum number of times, it returns all of them.
Parameters
values
: an array of values from which to select a mode.allowedFaults
(optional): the maximum number of input tasks that can error without the Mode task erroring. If not specified, this value defaults toN - 1
, whereN
is the number of inputs.
Outputs
A map containing two keys:
{
"results": [ ... ], // An array containing all of the values that occurred the maximum number of times
"occurrences": ..., // The number of times those values occurred
}
Example
my_mode_task [type="mode"
values=<[ $(fetch1), $(fetch2), $(fetch3), $(fetch4), $(fetch5), $(fetch6), $(fetch7), $(fetch8) ]>
allowedFaults=3]
This task can handle arrays with mixed types. For example, given a values
array containing both strings and ints like [ 2, 5, 2, "foo", "foo" "bar", "foo", 2 ]
, the task returns the following JSON:
{
"occurrences": 3,
"results": [2, "foo"]
}
To encode the results array into the ethabiencode
task, specify that the data is an array in the abi
and point the data parameter to the results from your mode task. Because argument encoding enforces types, all of the values in the array must be of the same type. As an example, you can encode the results of a mode
task with an array of integers:
mode_task [type="mode" values=<[ 1, 2, 2, 3, 1 ]>]
encode_mode_task [type="ethabiencode" abi="(bytes32 requestId, uint64 occurrences, uint256[] results)" data="{\\"requestId\\": $(decode_log.requestId), \\"occurrences\\": $(mode_task.occurrences), \\"results\\": $(mode_task.results) }"]
In this example, the mode
task returns the following result:
{
"occurrences": 2,
"results": [2, 1]
}
The ethabiencode
task encodes results
as a uint256[]
array.
Multiply task
Multiplies the provided input
and times
values.
Parameters
input
: the value to be multiplied. Possible values:- number
- stringified number
- bytes-ified number
$(variable)
times
: the value to multiply the input with.- number
- stringified number
- bytes-ified number
$(variable)
Outputs
The result of the multiplication.
Example
my_multiply_task [type="multiply" input="$(json_parse_result)" times=3]
Given the input 10
, the task will return 30
.
Sum Task
Accepts multiple numerical inputs and returns the sum of them.
Parameters
values
: an array of values to sum.allowedFaults
(optional): the maximum number of input tasks that can error without the Sum task erroring. If not specified, this value defaults toN - 1
, whereN
is the number of inputs.
Outputs
The sum of the values in the values
array.
Example
my_sum_task [type="sum"
values=<[ $(fetch1), $(fetch2), $(fetch3) ]>
allowedFaults=1]
Given the inputs 2
, 5
, and 20
, the task will return 27
.
Uppercase task
Accepts a string and returns an uppercase string.
Parameters
input
: a string.
Outputs
Uppercase string.
Example
my_uppercase_task [type="uppercase" input="Hello World!"]
Given the input Hello World!
, the task will return HELLO WORLD!
.