Trade Class

Constructor

Instances of Trade cannot be constructed manually. They are only accessible as a return value of DEX.trade().

States and Events

During their lifetime, Trade instances traverse a fixed sequence of states where transitions between states are caused by events as depicted in Figure 1 (where states are represented as rectangles and event names are in red). The current state of a Trade instance is accessible via the Trade.state property and handlers may be attached/detached to events using the Trade.on(), Trade.once(), and Trade.off() methods. See below for details.

Figure 1: States and Events for Trade Instances

Instance Properties

String = trade.state

Returns the current state of the receiver. The return value is one of the state names in Figure 1.

Object = trade.parameters

Returns an Object containing all arguments to DEX.trade() (which were used to construct the receiver) plus current state and an error property. The return value has the following format:

{
order_id: String,
order_type: String,
sell_asset: String,
sell_qty: Number,
sell_ctx: Object
buy_asset: String,
buy_qty: Number, 
buy_ctx: Object,     // this and above are arguments given to Dex.trade()
state: String,       // current state as would be returned by trade.state
error: String        // message from most recent error or empty string
}

Instance Methods

trade = trade.on( event_name, handler )
trade = trade.once( event_name, handler )
trade = trade.off( event_name, handler, position )

Add or remove handler to be called when event_name occurs on receiver. Returns the receiver to allow chaining.

Argument	Type and Semantics
event_name	String (case sensitive). One of the event names in Figure 1.
handler	Function. Handler interface is handler( event_name, trade ) where trade is a reference to the Trade instance on which the event occurred.
position	String (case insensitive). One of: "first", "last", or "all". Specifies which instances of a handler are to be removed from the named event handler queue. If this argument is absent, "all" is the default value.

Upon construction of each Trade instance, an initially empty queue of handlers is associated with each event to which Trade responds. Upon the occurrence of an event, handlers are executed in queue order. trade.on() and trade.once() append the specified handler to the end of the specified queue. Handlers appended with trade.on() persist in the queue after each occurrence of an event; handlers appended with trade.once() are removed from the queue after being executed once. If the same handler is appended to the queue multiple times, it will be called multiple times in the order in which it appears in the queue. trade.off() removes the first, last, or all instances of a handler depending on the value of position - these are removed whether they were added with trade.on() or trade.once(). Anonymous handlers (lambdas) cannot be removed by trade.off().

If called with invalid arguments, these methods will throw the "error" event. The cause of the error can be determined by accessing the error property of the Trade instance which originated the error event.

trade = trade.clear( event_name )

Empty the event handler queue for the named event - including anonymous handlers. Returns the receiver to allow chaining.