# AccumulateDistribute

### Members

#### (inner) generateOrder

Source:
  - accumulate_distribute/util/generate_order.js, line 8

Generates an atomic order to fill one slice of an AccumulateDistribute instance.

### Methods

#### (async, static) declareChannels(instance, host) → {Promise}

Source:
  - accumulate_distribute/meta/declare_channels.js, line 25
See:
  - module:AccumulateDistribute.hasOBRequirement
  - module:AccumulateDistribute.hasTradeRequirement
  - module:AccumulateDistribute.hasIndicatorCap
  - module:AccumulateDistribute.hasIndicatorOffset

Declares necessary data channels for price offset & cap calculations. The instance may require a `trades` channel, `book` channel, or multiple `candle` channels depending on the execution parameters.

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state
`host` | AOHost | algo host instance for declaring channel requirements

##### Returns:

p

Type
  Promise

#### (static) declareEvents(instance, host)

Source:
  - accumulate_distribute/meta/declare_events.js, line 14

Declares internal `self:submit_order` and `self:interval_tick` event handlers to the host for event routing.

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state
`host` | AOHost | algo host instance for event mapping

#### (static) generateOrderAmounts(args) → {Array.<number>}

Source:
  - accumulate_distribute/util/gen_order_amounts.js, line 20

Generates an array of order slices which add up to the total configured amount. Randomizes them if `amountDistortion` is finite and non-zero.

##### Parameters:

Name | Type | Description
--- | --- | ---

`args`

object

order parameters

###### Properties

Name | Type | Description
--- | --- | ---
`amount` | number | total order amount
`sliceAmount` | number | individual slice amount
`amountDistortion` | number | desired distortion in %

##### Returns:

orderAmounts

Type
  Array.<number>

#### (static) genOrderLabel(state) → {string}

Source:
  - accumulate_distribute/meta/gen_order_label.js, line 15

Generates a label for an AccumulateDistribute instance for rendering in an UI.

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---

`state`

object

source instance state

###### Properties

Name | Type | Description
--- | --- | ---
`args` | object | source instance execution parameters

##### Returns:

label

Type
  string

#### (static) genPreview(args) → {Array.<object>}

Source:
  - accumulate_distribute/meta/gen_preview.js, line 19

Generates an array of preview orders which show what could be expected if an instance of AccumulateDistribute was executed with the specified parameters.

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---
`args` | object | instance parameters

##### Returns:

previewOrders

Type
  Array.<object>

#### (static) getUIDef() → {AOUIDefinition}

Source:
  - accumulate_distribute/meta/get_ui_def.js, line 11

Returns the UI layout definition for AccumulateDistribute, with a field for each parameter.

Part of the `meta` handler section.

##### Returns:

uiDef

Type
  AOUIDefinition

#### (static) hasIndicatorCap(args) → {boolean}

Source:
  - accumulate_distribute/util/has_indicator_cap.js, line 11

Utility function that checks if a set of execution parameters require an indicator for price cap calculation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`args` | object | instance execution parameters

##### Returns:

hasIndicatorCap

Type
  boolean

#### (static) hasIndicatorOffset(args) → {boolean}

Source:
  - accumulate_distribute/util/has_indicator_offset.js, line 11

Utility function that checks if a set of execution parameters require an indicator for price offset calculation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`args` | object | instance execution parameters

##### Returns:

hasIndicatorOffset

Type
  boolean

#### (static) hasOBRequirement(args) → {boolean}

Source:
  - accumulate_distribute/util/has_ob_requirement.js, line 11

Utility function that checks if a set of execution parameters require order book data for price cap or offset calculation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`args` | object | instance execution parameters

##### Returns:

hasOBRequirement

Type
  boolean

#### (static) hasTradeRequirement(args) → {boolean}

Source:
  - accumulate_distribute/util/has_trade_requirement.js, line 11

Utility function that checks if a set of execution parameters require trade data for price cap or offset calculation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`args` | object | instance execution parameters

##### Returns:

hasTradeRequirement

Type
  boolean

#### (static) initState(args) → {object}

Source:
  - accumulate_distribute/meta/init_state.js, line 20

Creates an initial state object for an AccumulateDistribute instance to begin executing with. Generates randomized order amounts depending on the execution parameters and resets the order timeline (orders behind, etc).

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---
`args` | object | instance execution parameters

##### Returns:

initialState

Type
  object

#### (async, static) onDataManagedBook(instance, book, meta) → {Promise}

Source:
  - accumulate_distribute/events/data_managed_book.js, line 18
See:
  - module:AccumulateDistribute.hasOBRequirement

Saves the book on the instance state if it is needed for order generation, and it is for the configured symbol.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state
`book` | object | order book model
`meta` | EventMetaInformation | source channel information

##### Listens to Events:

- AOHost~event:dataManagedBook

##### Returns:

p - resolves on completion

Type
  Promise

#### (async, static) onDataManagedCandles(instance, candles, meta) → {Promise}

Source:
  - accumulate_distribute/events/data_managed_candles.js, line 22
See:
  - module:AccumulateDistribute.hasIndicatorOffset
  - module:AccumulateDistribute.hasIndicatorCap

If the instance has internal indicators, they are either seeded with the initial candle dataset or updated with new candles as they arrive. The candle dataset is saved on the instance state for order generation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state
`candles` | Array.<object> | array of incoming candles
`meta` | EventMetaInformation | source channel information

##### Listens to Events:

- AOHost~event:dataManagedCandles

##### Returns:

p

Type
  Promise

#### (async, static) onDataTrades(instance, trades, meta) → {Promise}

Source:
  - accumulate_distribute/events/data_trades.js, line 20
See:
  - module:AccumulateDistribute.hasTradeRequirement

Saves the received trade on the instance state if it is needed for order generation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state
`trades` | Array.<object> | array of incoming trades, only the most recent is used.
`meta` | EventMetaInformation | source channel information

##### Listens to Events:

- AOHost~event:dataTrades

##### Returns:

p

Type
  Promise

#### (async, static) onLifeStart(instance) → {Promise}

Source:
  - accumulate_distribute/events/life_start.js, line 23
See:
  - module:AccumulateDistribute.onSelfIntervalTick
  - module:AccumulateDistribute.hasIndicatorOffset
  - module:AccumulateDistribute.hasIndicatorCap

If needed, creates necessary indicators for price offset & cap calculation and saves them on the instance state.

Schedules the first tick of `self:interval_tick`.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state

##### Listens to Events:

- AOHost~event:lifeStart

##### Returns:

p

Type
  Promise

#### (async, static) onLifeStop(instance) → {Promise}

Source:
  - accumulate_distribute/events/life_stop.js, line 12

Clears the tick timeout in preperation for teardown

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state

##### Listens to Events:

- AOHost~event:lifeStop

##### Returns:

p

Type
  Promise

#### (async, static) onOrdersOrderCancel(instance, order) → {Promise}

Source:
  - accumulate_distribute/events/orders_order_cancel.js, line 14

Triggered on atomic order cancellation; clears the tick timeout and cancels any remaining orders, before triggering the `exec:stop` event & teardown

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state
`order` | object | the order that was cancelled externally

##### Listens to Events:

- AOHost~event:ordersOrderCancel

##### Returns:

p

Type
  Promise

#### (async, static) onOrdersOrderFill(instance, order) → {Promise}

Source:
  - accumulate_distribute/events/orders_order_fill.js, line 24
See:
  - module:AccumulateDistribute.scheduleTick

Called when an order fills. Updates the remaining amount & order timeline position (if behind, etc) on the instance state. If the instance is fully filled, the `exec:stop` event is triggered.

Otherwise, if `catchUp` is enabled and the instance is behind with order fills the next tick is re-scheduled to occur earlier in order to compensate.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state
`order` | object | the order that filled

##### Listens to Events:

- AOHost~event:ordersOrderFill

##### Returns:

p

Type
  Promise

#### (async, static) onSelfIntervalTick(instance) → {Promise}

Source:
  - accumulate_distribute/events/self_interval_tick.js, line 26
See:
  - module:AccumulateDistribute.scheduleTick

Mapped to the `self:interval_tick` event and triggered by the instance itself.

Schedules the next tick, and updates the orders-behind count on the instance state if an order is currently open (meaning it has not filled in its allocated window).

If `awaitFill` is `false`, the open order is cancelled and will be replaced by the new order on the next tick. Otherwise nothing is done in order to await a fill.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state

##### Fires:

- module:AccumulateDistribute~event:selfSubmitOrder

##### Listens to Events:

- module:AccumulateDistribute~event:selfIntervalTick

##### Returns:

p

Type
  Promise

#### (async, static) onSelfSubmitOrder(instance) → {Promise}

Source:
  - accumulate_distribute/events/self_submit_order.js, line 18
See:
  - module:AccumulateDistribute~generateOrder

Mapped to the `self:submit_order` event and triggered by the instance itself.

Generates an order and submits it if the necessary data was received for price offset & cap calculation.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance state

##### Listens to Events:

- module:AccumulateDistribute~event:selfSubmitOrder

##### Returns:

p

Type
  Promise

#### (static) processParams(data) → {object}

Source:
  - accumulate_distribute/meta/process_params.js, line 17

Converts a raw parameters Object received from an UI into a parameters Object which can be used by an AccumulateDistribute instance for execution.

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---
`data` | object | raw parameters from an UI

##### Returns:

parameters - ready to be passed to a fresh instance

Type
  object

#### (async, static) scheduleTick(instance) → {Promise}

Source:
  - accumulate_distribute/util/schedule_tick.js, line 20
See:
  - module:AccumulateDistribute~onSelfIntervalTick

Sets a timeout to emit the `self:interval_tick` event after the configured slice interval passes, taking into account the configured interval distortion for the AccumulateDistribute instance.

If `catchUp` was enabled and the instance is behind with order fills, the next tick is always scheduled in 200ms.

##### Parameters:

Name | Type | Description
--- | --- | ---
`instance` | AOInstance | AO instance

##### Fires:

- module:AccumulateDistribute.event:selfIntervalTick

##### Returns:

p - resolves on completion

Type
  Promise

#### (static) serialize(state) → {object}

Source:
  - accumulate_distribute/meta/serialize.js, line 14

Creates a POJO from an instance's state which can be stored as JSON in a database, and later loaded with the corresponding `module:AccumulateDistribute~unserialize` method.

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---
`state` | object | instance state to be serialized

##### Returns:

pojo - DB-ready plain JS object

Type
  object

#### (static) unserialize(loadedState) → {object}

Source:
  - accumulate_distribute/meta/unserialize.js, line 12

Converts a loaded POJO into a state object ready for live execution.

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---
`loadedState` | object | data from a DB

##### Returns:

instanceState - ready for execution

Type
  object

#### (static) validateParams(args) → {string}

Source:
  - accumulate_distribute/meta/validate_params.js, line 43

Verifies that a parameters Object is valid, and all parameters are within the configured boundaries for a valid AccumulateDistribute order.

Part of the `meta` handler section.

##### Parameters:

Name | Type | Description
--- | --- | ---

`args`

object

incoming parameters

###### Properties

Name | Type | Attributes | Description
--- | --- | --- | ---
`amount` | number |  | total order amount
`sliceAmount` | number |  | individual slice order amount
`sliceInterval` | number |  | delay in ms between slice orders
`intervalDistortion` | number | <optional> | slice interval distortion in %, default 0
`amountDistortion` | number | <optional> | slice amount distortion in %, default 0
`orderType` | string |  | LIMIT, MARKET, RELATIVE
`limitPrice` | number | <optional> | price for LIMIT orders
`catchUp` | boolean |  | if true, interval will be ignored if behind with filling slices
`awaitFill` | boolean |  | if true, slice orders will be kept open until filled

`relativeOffset`

object

<optional>

price reference for RELATIVE orders

###### Properties

Name | Type | Attributes | Description
--- | --- | --- | ---
`type` | string | <optional> | ask, bid, mid, last, ma, or ema
`delta` | number | <optional> | offset distance from price reference
`args` | Array.<number> | <optional> | MA or EMA indicator arguments [period]
`candlePrice` | string | <optional> | 'open', 'high', 'low', 'close' for MA or EMA indicators
`candleTimeFrame` | string | <optional> | '1m', '5m', '1D', etc, for MA or EMA indicators

`relativeCap`

object

<optional>

maximum price reference for RELATIVE orders

###### Properties

Name | Type | Attributes | Description
--- | --- | --- | ---
`type` | string | <optional> | ask, bid, mid, last, ma, or ema
`delta` | number | <optional> | cap distance from price reference
`args` | Array.<number> | <optional> | MA or EMA indicator arguments [period]
`candlePrice` | string | <optional> | 'open', 'high', 'low', 'close' for MA or EMA indicators
`candleTimeFrame` | string | <optional> | '1m', '5m', '1D', etc, for MA or EMA indicators

##### Returns:

error - null if parameters are valid, otherwise a description of which parameter is invalid.

Type
  string

### Events

#### selfIntervalTick

Source:
  - accumulate_distribute/util/schedule_tick.js, line 34

Triggers verification of the price target, and a potential atomic order submit.

##### Listeners of This Event:

- module:AccumulateDistribute.onSelfIntervalTick

#### selfSubmitOrder

Source:
  - accumulate_distribute/events/self_interval_tick.js, line 50
See:
  - module:AccumulateDistribute~generateOrder

Triggers generation of the configured atomic slice, and submits it

##### Listeners of This Event:

- module:AccumulateDistribute.onSelfSubmitOrder