Helpers

AO Event Handlers & Helpers

All event handlers receive the same arguments: (instance = {}, ...args). The instance contains two objects, { state = {}, h = {} } with state being the current AO state, and h being a helper object.

The provided helpers are:

  • clearAllTimeouts() - clears all pending order submit/cancel timeouts

  • debug(str, ...args) - for logging information to the console, tagged by AO GID

  • emitSelf(eventName, ...args) - triggers an event on the 'self' section

  • emitSelfAsync(eventName, ...args) - same as emitSelf but operates on next tick

  • emit(eventName, ...args) - raw event emitter, i.e. emit('life:start')

  • emitAsync(eventName, ...args) - same as emit but operates on next tick

  • notifyUI(level, message) - generates and sends a notification which appears on the Bitfinex UI

  • cancelOrderWithDelay(state, delay, order) - takes current algo state, delay in ms

  • cancelAllOrdersWithDelay(state, delay) - cancels all active atomic orders on the AO state, delay in ms

  • submitOrderWithDelay(state, delay, order) - takes current algo state, submits a new order, delay in ms

  • declareEvent(instance, host, eventName, path) - declares an internal AO event, see section below

  • declareChannel(instance, host, channel, filter) - declares a required data channel, see section below

  • updateState(instance, update) - update the current state for an AO instance

Source:

Methods

(inner) cancelAllOrdersWithDelay(state, delay) → {object}

Source:

Cancels all orders currently on the AO state after the specified delay

Example
await cancelAllOrdersWithDelay(state, 100)
Parameters:
Name Type Description
state object

current AO instance state

delay number

in ms

Returns:

nextState

Type
object

(inner) cancelOrderWithDelay(state, delay, order) → {object}

Source:

Cancels the provided order after a delay, and removes it from the active order set.

Example
await cancelOrderWithDelay(state, 100, order)
Parameters:
Name Type Description
state object

current AO instance state

delay number

in ms

order object

order model or array

Returns:

nextState

Type
object

(inner) clearAllTimeouts()

Source:

Clear all timeouts for pending order submits/cancellations, called automatically by the algo host on teardown.

(inner) debug(str, …args)

Source:

Logs a string to the console, tagged by AO id/gid

Example
debug('submitting order %s in %dms', order.toString(), delay)
Parameters:
Name Type Attributes Description
str string

format string

args any <repeatable>

passed to debug()

(inner) declareChannel(instance, aoHost, channel, filter) → {object}

Source:

Assigns a data channel to the provided AO instance

Example
await declareChannel(instance, host, 'trades', { symbol })
Parameters:
Name Type Description
instance object

full AO instance, with state/h

aoHost object

unused, here for common signature

channel string

channel name, i.e. 'ticker'

filter object

channel spec, i.e. { symbol: 'tBTCUSD' }

Returns:

nextState

Type
object

(inner) declareEvent(instance, aoHost, eventName, path)

Source:

Hooks up the listener for a new event on the 'self' section

Example
declareEvent(instance, host, 'self:interval_tick', 'interval_tick')
Parameters:
Name Type Description
instance object

full AO instance, with state/h

aoHost object

algo host instance

eventName string

name of event to declare

path string

on the 'self' section

(inner) emit(eventName, …eventArgs) → {Promise}

Source:

Triggers a generic event

Example
await emit('exec:order:submit:all', gid, [order], submitDelay)
Parameters:
Name Type Attributes Description
eventName string

name of event to emit

eventArgs any <repeatable>

args passed to all handlers

Returns:

p - resolves when all handlers complete

Type
Promise

(inner) emitAsync(eventName, …eventArgs) → {Promise}

Source:

Like emit but operates after a timeout

Example
await emitAsync('exec:order:submit:all', gid, [order], submitDelay)
Parameters:
Name Type Attributes Description
eventName string

name of event to emit

eventArgs any <repeatable>

args passed to all handlers

Returns:

p - resolves when all handlers complete

Type
Promise

(inner) emitSelf(eventName, …eventArgs) → {Promise}

Source:

Triggeres an event on the 'self' section

Example
await emitSelf('submit_orders')
Parameters:
Name Type Attributes Description
eventName string

name of event to emit

eventArgs any <repeatable>

args passed to all handlers

Returns:

p - resolves when all handlers complete

Type
Promise

(inner) emitSelfAsync(eventName, …eventArgs) → {Promise}

Source:

Like emitSelf but operates after a timeout

Example
await emitSelfAsync('submit_orders')
Parameters:
Name Type Attributes Description
eventName string

name of event to emit

eventArgs any <repeatable>

args passed to all handlers

Returns:

p - resolves when all handlers complete

Type
Promise

(inner) notifyUI(level, message) → {Promise}

Source:

Triggers an UI notification, sent out via the active websocket connection

Example
await notifyUI('info', `Scheduled tick in ${delay}s`)
Parameters:
Name Type Description
level string

'info', 'success', 'error', 'warning'

message string

notification content

Returns:

p - resolves when all handlers complete

Type
Promise

(inner) submitOrderWithDelay(state, delay, order, attempt) → {object}

Source:

Submits an order after a delay, and adds it to the active order set on the AO state. Emits errors if the order fails to submit; retries up to MAX_SUBMIT_ATTEMPTS in the case of balance evaluation errors.

Example
await submitOrderWithDelay(state, 100, order)
Parameters:
Name Type Description
state object

current AO instance state

delay number

delay in milliseconds

order object

order model

attempt number

attempt count, max is 10 (set as a constant)

Returns:

nextState

Type
object

(inner) updateState(instance, update) → {object}

Source:

Updates the state for the provided AO instance

Example
await updateState(instance, { remainingAmount })
Parameters:
Name Type Description
instance object

full AO instance, with state/h

update object

new state

Returns:

nextState

Type
object