# PingPong

Ping/pong submits multiple 'ping' orders; once a ping order fills, an associated 'pong' order is submitted.

Multiple ping/pong pairs can be created by specifying an order count greater than 1, a suitable min/max ping price, and a pong distance. Multiple ping orders will be created between the specified min/max prices, with the associated pongs offset by the pong distance from the ping price.

When operating in 'endless' mode, new ping orders will be submitted when their associated pongs fill.

Source:
  - ping_pong/index.js, line 17

##### Example

    await host.startAO('bfx-ping_pong', {
      symbol: 'tBTCUSD',
      amount: 0.5,
      orderCount: 5,
      pingMinPrice: 6000,
      pingMaxPrice: 6700,
      pongDistance: 300,
      submitDelay: 150,
      cancelDelay: 150,
      _margin: false,
    })

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`endless` | boolean |  | if enabled, pong fill will trigger a new ping
`symbol` | string |  | symbol to trade on
`amount` | number |  | individual ping/pong order amount
`orderCount` | number |  | number of ping/pong pairs to create, 1 or more
`pingPrice` | number | <optional> | used for a single ping/pong pair
`pongPrice` | number | <optional> | used for a single ping/pong pair
`pingMinPrice` | number | <optional> | minimum price for ping orders
`pingMaxPrice` | number | <optional> | maximum price for ping orders
`pongDistance` | number | <optional> | pong offset from ping orders for multiple pairs

### Members

#### (static) genPingPongTable

Source:
  - ping_pong/util/gen_ping_pong_table.js, line 5

Generates a mapping between `ping` and `pong` prices as configured in the execution parameters.

### Methods

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

Source:
  - ping_pong/meta/gen_order_label.js, line 13

Generates a label for a PingPong 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:
  - ping_pong/meta/gen_preview.js, line 17

Generates an array of preview orders which show what could be expected if an instance of PingPong 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:
  - ping_pong/meta/get_ui_def.js, line 12

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

Part of the `meta` handler section.

##### Returns:

uiDef

Type
  AOUIDefinition

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

Source:
  - ping_pong/meta/init_state.js, line 17
See:
  - module:PingPong~genPingPongTable

Creates an initial state object for PingPong instance to begin executing with. Generates the ping-pong table price mapping.

Part of the `meta` handler section.

##### Parameters:

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

##### Returns:

initialState

Type
  object

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

Source:
  - ping_pong/events/life_start.js, line 17

Generates and submits initial `ping` orders, along with any `pongs` that need to be submitted due to the loaded execution state.

##### Parameters:

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

##### Listens to Events:

- AOHost~event:lifeStart

##### Returns:

p - resolves on completion

Type
  Promise

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

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

Cancels all open orders prior to teardown.

##### Parameters:

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

##### Listens to Events:

- AOHost~event:lifeStop

##### Returns:

p - resolves on completion

Type
  Promise

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

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

Triggered when an atomic order cancellation is detected, and cancels any open orders before emitting an `exec:stop` event to trigger teardown.

##### Parameters:

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

##### Listens to Events:

- AOHost~event:ordersOrderCancel

##### Returns:

p - resolves on completion

Type
  Promise

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

Source:
  - ping_pong/events/orders_order_fill.js, line 21

Triggered on atomic order fill. If it was a `ping`, the associated `pong` is submitted. Otherwise it if was a `pong` and the instance was configured as `endless`, the associated `ping` is submitted. If not `endless`, nothing is done.

##### Parameters:

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

##### Listens to Events:

- AOHost~event:ordersOrderFill

##### Returns:

p - resolves on completion

Type
  Promise

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

Source:
  - ping_pong/meta/process_params.js, line 15

Converts a raw parameters Object received from an UI into a parameters Object which can be used by a PingPong 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

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

Source:
  - ping_pong/meta/serialize.js, line 15
See:
  - module:PingPong.unserialize

Creates a POJO from an instance's state which can be stored as JSON in a database, and later loaded with the corresponding `module:PingPong~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:
  - ping_pong/meta/unserialize.js, line 13
See:
  - module:PingPong.serialize

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:
  - ping_pong/meta/validate_params.js, line 23

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

Part of the `meta` handler section.

##### Parameters:

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

`args`

object

incoming parameters

###### Properties

Name | Type | Attributes | Description
--- | --- | --- | ---
`amount` | number |  | individual ping/pong order amount
`orderCount` | number |  | number of ping/pong pairs to create, 1 or more
`pingPrice` | number | <optional> | used for a single ping/pong pair
`pongPrice` | number | <optional> | used for a single ping/pong pair
`pingMinPrice` | number | <optional> | minimum price for ping orders
`pingMaxPrice` | number | <optional> | maximum price for ping orders
`pongDistance` | number | <optional> | pong offset from ping orders for multiple pairs

##### Returns:

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

Type
  string