Keyless Workflow Syntax

Overview

The keyless workflow is written in YAML format which defines the structure of automated actions and sequences to execute.

Workflow Keywords

Keyless workflow configuration consists of:

Global Keywords are basic foundation of keyless workflows:

Keyword	Description
name	The workflow name
trigger	Define how to trigger the workflow
steps	Define steps of automated actions and behaviours

Trigger Keywords

Keyword	Description
type	Define the type of trigger
params	Define trigger type params
if	Define optional inline conditional check
conditions	Define multiple inline rules of `if`

Steps Keywords

Keyword	Description
params	Define trigger type params
action	Define action to execute for step type action
if	Define optional inline conditional check
conditions	Define multiple inline rules of `if`
using	specificies system/native/external plugin namespace

Blocks Keywords

Keyword	Description
paths	Define rule based path
if	Define optional inline conditional check
conditions	Define multiple inline rules of`if`

Paths Keywords

Keyword	Description
name	Define name of the Path
if	Define optional inline conditional check
steps	Define steps of automated actions and behaviours
conditions	Define multiple inline rules of `if`

Workflow Structure

The root of the workflow file should contain the following top-level keys:

yaml
name: <string>
trigger: <object>
steps: <object>

Trigger Structure

The trigger object should contain the following fields:

yaml
trigger:
  type: <string>
  params: <object>
  conditions: <array>
  if: <string>

type: determines the type of trigger e.g time, event, webhooks, manual

params: Parameters specific to the trigger type.

if: Define optional inline conditions

conditions: Define optional array of conditions that must be met to trigger the workflow.

Time Based Trigger

Time based trigger consists of different kind of ways to express how to trigger a workflow base on specific datetime or interval

Time Trigger (Cron)

yaml
trigger:
  type: time
  params: 
	  schedule: "0 12 * * *" # Daily at 12:00 PM

Time Trigger - (Recurring)

yaml
trigger:
  type: time
  params: 
	  interval: day | week | hour | month | mins | secs
	  value: 1
	  startDate: datetime
	  timeOfDay: time

Time Trigger - (DateTime)

yaml
trigger:
  type: time
  params: 
	  scheduleAt: datetime

Time Trigger - (DateTime Expression)

yaml
trigger:
  type: time
  params: 
	  expression: every tuesday | every month end | every weekday | every 5th monthly

Steps Structure

The steps object contains named step objects. Each step object should have the following structure:

yaml
steps:
  <step_name>:
    type: action
    action: <string>
    params: <object>
    if: <string>
    condtions: <array>

type: determines the type of step to carryout. e.g action, wait, condition

Action Type

action: native actions to carry out e.g transfer, swap, bridge, stake, contract_call, http_call and rpc_call

params: Parameters specific to the action type.

if: Define optional inline conditions

conditions: Define optional array of conditions that must be met to trigger the workflow.

Transfer Params:

yaml
params:
  from: <string>
  to: <string>
  value: <string>
  token: <string>

Swap Params:

yaml
params:
	from: <string>
	to: <string>
  from_token: <string>
  to_token: <string>
  value: <string>
  refund_address: <string>

Note: tois optional in most cases as the fromwill be used as the to address. However in cases where the chains and token differs, then towill be required.

Bridge Params:

yaml
params:
	from: <string>
	to: <string>
	from_chain: <string>
	to_chain: <string>
  from_token: <string>
  to_token: <string>
  value: <string>
  refund_address: <string>

Stake Params:

yaml
params:
  token: <string>
  value: <string>
  duration: <string>
  chain: <string>

Contract Call Params:

yaml
params:
  contract_address: <string>
  chain: <string>
  function: <string>
  abi: <string>
  args: <array>
  response: <object> | <string> | <boolean>

HTTP Call Params:

yaml
params:
  url: <string>
  method: <string>
  params: <object>
  body: <object>
  headers: <object>
  encoding: <string>
  response: <object> | <string> | <boolean>

RPC Call Params

yaml
params:
  url: <string>
  method: <string>
  params: <object>
  response: <object> | <string> | <boolean>

Wait Type

waitType: determines how the system should delay the execution of the next program either base on time or a specific. e.g waitFor, waitUntil

params: parameters specific to the wait type

waitFor

yaml
waitType: waitFor
params:
  interval: day | week  | hour | minute
  value: 1

waitUntil

yaml
waitType: waitUntil
params:
  dateTime: dateTime

Note: datetime can not be more than 1 month and if a date in the past is provided, wait is not applied as its already past.

Blocks Structure

The blocks object is a named collections of named steps. This is a very simple way to group similar steps.

yaml
blocks:
	<block_name>:
		steps:
		  <step_name>:
		    type: action
		    action: <string>
		    params: <object>
		    if: <string>
		    condtions: <array>

steps: a collection of steps to execute

paths: a rule based path to determine which steps to execute in a block

if: Define optional inline conditions

conditions: Define optional array of conditions that must be met to trigger the workflow.

Path Structure

The paths object is a named conditional collections of named steps. This is a very simple way to define rules based path. if keyword is required to be evaluated to true to determine whether the path will be executed or not.

yaml
blocks:
	<block_name>:
		paths:
			<path_name>:
				if: ${{ expression }}
				steps:
				  <step_name>:
				    type: action
				    action: <string>
				    params: <object>
				    if: <string>
				    condtions: <array>

steps: a collection of steps to execute

if: Define required inline conditions

conditions: Define optional array of conditions that must be met to trigger the workflow.

Notes: either of if or conditions must be provided and evaluates to true

Variables Structure

The variables object is a key-value pair of variable names and their values:

yaml
variables:
  <variable_name>: <string> | <object> | <number> | <boolean>

If <variable_name> is an object, we are assuming you want to expand the variable and it should be as follows:

yaml
variables:
  <variable_name>: 
	  value: <string> | <number> | <boolean>
	  description: Optional variable description

Resources Structure

The resources object is a key-value pair of resource names and their values:

yaml
resources:
  <resource_name>: <object>

Template Variables

Template variables can be used throughout the workflow file and are denoted by double curly braces:

yaml
${{ variables.VARIABLE_NAME }}
${{ resources.RESOURCE_NAME }}

Conditional Structure

Conditions are a type of flow control used to determine conditional statement in a workflow and can be used on trigger, steps or actions.

conditions accepts an array of conditions. Each conditions must have at least one of:

if

when

if: an inline conditional check

conditions:if

Use conditions:if clauses to specify an if statement. The conditions:if object should contain the following fields:

yaml
conditions:
  - if:
	    expression: balanceCheck(params.address)
	    operator: gt
	    value: 0

yaml
conditions:
  - if: ${{ steps.step2.outputs.address =='wwow' }}
	  when: failure

conditions:when - Debatable

Use conditions:when clause alongside if to control the conditions and result of an if statement.

when has three types of possible options:

always: it will always trigger regardless of the results

success: it will only trigger if the results of the conditional expression is true

failure: it will only trigger if the results of the conditional expression is false

Below is an example

yaml
conditions:
  - if:
	    expression: <string>
	    operator: <string>
	    value: <number>
	  when: always

Operators

Symbol	Shortname	Description
==	eq
≤	lte
≥	gte
≠	neq
<	lt
>	gt
&&	and
\|\|	or

Workflow Higher Order Functions

These are higher order functions that are made available in the workflow:

yaml
variables:
	ADDRESS: ${{ addressOf(resources.toPrivateKey) }}

addressOf in this case is a special function for getting the publicKey of a given privateKey. There are other functions like concat and so many more

Workflow Expressions

Expressions in a workflow allow you to programmatically perform binary/unary operations, access or manipulate variables, context, and call custom functions. They are powerful tools for setting environment variables, accessing step contexts, or making conditional decisions.

You need to tell Keyless when to evaluate an expression or reference a variable in a workflow context.

There are two modes of expression:

Standalone Expression: This is when only the express is provided as a value. e.g chain: $CHAIN, if: ${{ expression }}

Inline Expression: Inline expression is when this is provided as part of a string. e.g description: “Stake on $CHAIN” or description: “Stake on ${{ getChainByTokenContract(var.token) }}”

Types of Expressions

There are two main types of expressions: Variable Expressions and Evaluation Expressions.

Variable Expression

This type of expression is used for referencing and handling variables within a workflow context. It is represented by the dollar symbol $ followed by the variable name.

You can use this by specifying the dollar $ symbol followed by the variable:

yaml
$VARIABLE_NAME

Example:

yaml
chain: $CHAIN

Note: Variable expressions are specifically used for referencing variables and cannot evaluate expressions.

Evaluation Expression

Evaluation expressions allow you to evaluate complex expressions and return results. These expressions can include literals (strings, numbers, tuples), operators, function calls, or variable references. They are enclosed within double curly braces with a dollar sign ${{ ... }}.

They can be used in 2 ways:

Conditional

Used in if statements to evaluate an expression and return its truthy value. Truthy values include non-zero/negative numbers, non-empty strings, and non-empty tuples and dicts. Example:

yaml


// conditional
if: ${{ <expression> }}

if: ${{ getChainNetwork('ethereum-sepolia')=='testnet' }}

Value

Used to evaluate an expression and directly return its result as a value.

yaml

chainId: ${{ getChainId("ethereum-sepolia") }}

In summary:

Use Variable Expressions ($VARIABLE_NAME) to reference variables.

Use Evaluation Expressions (${{ <expression> }}) to evaluate and return results or make conditional decisions.

Workflow Plugins

Plugins are custom JavaScript code that extends the Keyless Platform with new features and abilities.

To load plugins into a workflow:

yaml
plugins:
  - custom-plugin
  - github.com/username/custom-plugin

Usage:

yaml
<step_name>:
  type: action
  using: custom-plugin
  action: <customActionUnderPlugin>
  params: <object>

Example:

yaml
<step_name>:
  type: action
  using: bitpowr-plugin
  action: generateAddress
  params: 
	  assetType: 
	  walletId: 
	  label: 
	extract:
		address: