spec: describe new trade suspension mechanics

[buck54321]

The suspend request is a DEX-originating request that informs the client that a market will be suspending operation. There are a number of issues with the system proposed in the specification. These issues are being addressed in #287, but the specification is no longer accurate.

Plan

Based on discussion from #287 and on matrix, my understanding is that the current plan is to 1) send an indiscriminate broadcast to all connected clients at the time the operator schedules the suspension, and 2) add a new field to the 'config' route response payload (i.e. msgjson.ConfigResult) that describes any scheduled market suspensions.

Part 1 is documented incorrectly because it does not account for individual markets and does not have a response specified. The request needs to specify an acknowledgement, or become a notification instead of a request. The payload needs a marketid field.

Part 2 is as yet undocumented.

Order book subscriber notification

While a notification through an order book subscription feed is insufficient as a solution to track the suspension state, the book feed might need to add notifications so that the book can be properly maintained, especially in the case when persist is false.

While I'm fairly certain a client could keep the order book maintained based on only the messaging in the plan above, it would certainly make order book maintenance simpler if the feed had it's own notifications. A risk is that an uninformed developer would come to rely on the order book feed notifications as the source of tracking suspension state, which we've already deemed insufficient.

If we do decide to send order book feed notifications for suspensions, they need to be documented in the spec too.

[chappjc]

Agree the with assessment of the suspend ntfns. It needs to be a notification, and should include market id. The currently proposed msgjson type:

eef7a43#diff-9a36b4e081b2c1cc9032524815e5d57cR704-R711

// TradeSuspension is the SuspensionRoute notification payload. It is part of
// the orderbook subscription.
type TradeSuspension struct {
	MarketID    string `json:"marketid"`
	FinalEpoch  uint64 `json:"finalepoch"`
	SuspendTime uint64 `json:"suspendtime"`
	Persist     bool   `json:"persistbook"`
}

When PR #287 is wrapped up today, I'll circle back here with any modifications. This is just what I have in mind now.