monitor

README

Monitor package

This package contains all engines that will monitor the sanity of the markets currently running. If something goes awry, these engines will suspend the "normal" trading mode of markets, and trigger an auction. What it means to change the way a market trades is beyond the domain of the engines, just like the market itself shouldn't be aware of how the determination is made whether or not an auction ought to be triggered.

That's where the AuctionState in this package comes in.

Glorified DTO

At its core, the AuctionState is little more than a DTO. It keeps track of what trading mode a given market is in, what its default trading mode is, and why it is in the mode it is in. If a market opens, a new AuctionState object is created for it. The state will immediately be set to reflect a market in opening auction. The start and end times will be set, and the state object will have a flag set that this auction period has just been triggered.

The market will then check if its auction-state has been updated (AuctionState.AuctionStart()), and if it has, the market calls EnterAuction(). This function will do whatever a market has to do to enter an auction (update the orderbook, for example), and finally acknowledge the auction was started by calling AuctionState.AuctionStarted(). This function returns an auction event that the market will send to the broker.

Every market.OnChainTimeUpdate(), the market checks whether it is currently trading in an auction. If it's an opening auction, we're dealing with a simple time-limited auction, and the market will check to see whether or not the auction period has expired. If it has, the market calls AuctionState.SetReadyToLeave(), performs everything it has to do to terminate the auction (updating the orderbook, uncrossing auction orders, ...), and then finally AuctionState.Left() is called. Like the AuctionStarted() call, this returns an event to push to the broker.

For the monitor sub-packages

Each monitor sub-package will have a slightly different interface definition for the AuctionState type. Specific calls like StartPriceAuction() are used by the price monitoring engine in case the mark price exceeds the expected range, but this call is meaningless to any other monitoring engines. What monitoring engines can do, however is extend an auction period if needed. This is the reason why auction starts and endings require 2 calls (one returning a boolean value indicating an auction is starting/ending, the other for the market to confirm it has done so).

One monitoring engine could find that it's safe to end an auction it triggered, but we don't want to leave this auction if another monitoring engine would immediately trigger a new auction period. In code, it could look something like this:

func (m *Market) inMarket() {
    if m.as.InAuction() {
        // see if price auction has anything to say/do with this auction
        m.price.CheckAuction(m.as)
        // same, but liquidity monitoring
        m.liquidity.CheckAuction(m.as)
        // any other monitoring engines we decide to add
        m.parties.CheckAuction(m.as)
        // monitoring engines have determined we can/should leave the auction
        if m.as.CanLeave() {
            m.LeaveAuction()
        }
    }
}
// in monitoring engines:
func (p *Price) CheckAuction(as AuctionState) {
    // clearly, this monitoring engine only cares about auctions it started
    if !as.IsPriceAuction() {
        return
    }
    if as.AuctionStart().Before(as.CanLeave()) {
        // auction has expired - mark auction as over
        // this can be determined in different ways, that's up to the engine itself
        // for example: auctions bound by traded volume
        as.SetReadyToLeave()
    }
    // auction carries on as per usual
}

func (l *Liquidity) CheckAuction(as AuctionSate) {
    if as.IsOpeningAuction() {
        // an opening auction is not something we check
        return
    }
    if as.IsLiquidityAuction() {
        // auction was started by this engine
        // check if auction expired according to internal logic
        if l.checkSaysStop {
            as.SetReadyToLeave()
        }
        return // we've checked auction we started
    }
    // not a liquidity or opening auction, but it's the end of this auction
    if as.CanLeave() {
        // check internal logic, see if this auction can safely terminate
        if l.auctionNeeded() {
            as.ExtendAuction(params) // extend auction by some parameters based on internal logic
        }
    }
}

Price sub-package

Price subpackage contains the price monitoring engine. It's used to determine if the price movement exceeded the bounds implied by the risk model over a specified horizon at a specified probability level. If that's the case, the price monitoring engine modifies the AuctionState to indicate that the price monitoring auction should commence. Once in auction, the engine checks if the auction time has elapsed, and if so if the resulting auction uncrossing price falls within the price monitoring bounds, if that condition is met the AuctionState object gets modified to indicate that price monitoring auction should finish, otherwise the AuctionState object gets modified to indicate that the auction should be extended.

Below is the signature of the price monitoring constructor:

func NewMonitor(riskModel RangeProvider, settings types.PriceMonitoringSettings) (*Engine, error)

where:

• RangeProvider exposes the method PriceRange(price, yearFraction, probability float64) (float64, float64) which returns the minimum (minPrice) and maximum (maxPrice) valid price per current price (price), the time horizon expressed as year fraction (yearFraction) and probability level (probability). price, minPrice, maxPrice are then used to imply MinMoveDown and MaxMoveUp over yearFraction at probability level probability as: MinMoveDown=minPrice - price, MaxMoveUp: maxPrice - price.
• PriceMonitoringSettings contains:
  • a list of yearFraction, probability and auctionExtension tuples, where yearFraction, probability are used in a call to the risk model and auctionExtension is the period in seconds by which the current auction should be extended (or initial period of new auction if currently market is in its "normal" trading mode) should the actual price movement over min(yearFraction,t), where t is the time since last auction expressed as a year fraction, violate the bounds implied by the RangeProvider (MinMoveDown, MaxMoveUp),

Documentation

Index

• type AuctionState
  • func NewAuctionState(mkt *types.Market, now time.Time) *AuctionState
  • func NewAuctionStateFromSnapshot(mkt *types.Market, as *types.AuctionState) *AuctionState
  • func (a *AuctionState) AuctionExtended(ctx context.Context, now time.Time) *events.Auction
  • func (a AuctionState) AuctionStart() bool
  • func (a *AuctionState) AuctionStarted(ctx context.Context, now time.Time) *events.Auction
  • func (a AuctionState) CanLeave() bool
  • func (a AuctionState) Changed() bool
  • func (a AuctionState) Duration() types.AuctionDuration
  • func (a *AuctionState) EndGovernanceSuspensionAuction()
  • func (a *AuctionState) ExceededMaxOpening(now time.Time) bool
  • func (a AuctionState) ExpiresAt() *time.Time
  • func (a *AuctionState) ExtendAuction(delta types.AuctionDuration)
  • func (a *AuctionState) ExtendAuctionPrice(delta types.AuctionDuration)
  • func (a *AuctionState) ExtendAuctionSuspension(delta types.AuctionDuration)
  • func (a AuctionState) ExtensionTrigger() types.AuctionTrigger
  • func (a *AuctionState) GetAuctionBegin() *time.Time
  • func (a *AuctionState) GetAuctionEnd() *time.Time
  • func (a *AuctionState) GetState() *types.AuctionState
  • func (a AuctionState) InAuction() bool
  • func (a AuctionState) IsFBA() bool
  • func (a AuctionState) IsMonitorAuction() bool
  • func (a AuctionState) IsOpeningAuction() bool
  • func (a AuctionState) IsPriceAuction() bool
  • func (a AuctionState) IsPriceExtension() bool
  • func (a *AuctionState) Left(ctx context.Context, now time.Time) *events.Auction
  • func (a AuctionState) Mode() types.MarketTradingMode
  • func (a *AuctionState) SetReadyToLeave()
  • func (a AuctionState) Start() time.Time
  • func (a *AuctionState) StartGovernanceSuspensionAuction(t time.Time)
  • func (a *AuctionState) StartLiquidityAuctionUnmetTarget(t time.Time, d *types.AuctionDuration)
  • func (a *AuctionState) StartOpeningAuction(t time.Time, d *types.AuctionDuration)
  • func (a *AuctionState) StartPriceAuction(t time.Time, d *types.AuctionDuration)
  • func (a AuctionState) Trigger() types.AuctionTrigger
  • func (a *AuctionState) UpdateMaxDuration(_ context.Context, d time.Duration)
  • func (a *AuctionState) UpdateMinDuration(ctx context.Context, d time.Duration) *events.Auction

Types

type AuctionState

type AuctionState struct {
	// contains filtered or unexported fields
}

func NewAuctionState

func NewAuctionState(mkt *types.Market, now time.Time) *AuctionState

func NewAuctionStateFromSnapshot

func NewAuctionStateFromSnapshot(mkt *types.Market, as *types.AuctionState) *AuctionState

func (*AuctionState) AuctionExtended

func (a *AuctionState) AuctionExtended(ctx context.Context, now time.Time) *events.Auction

AuctionExtended - called to confirm we will not leave auction, returns the event to be sent or nil if the auction wasn't extended.

func (AuctionState) AuctionStart

func (a AuctionState) AuctionStart() bool

AuctionStart bool indicates something has already triggered an auction to start, we can skip other monitoring potentially and we know to create an auction event.

func (*AuctionState) AuctionStarted

func (a *AuctionState) AuctionStarted(ctx context.Context, now time.Time) *events.Auction

AuctionStarted is called by the execution package to set flags indicating the market has started the auction.

func (AuctionState) CanLeave

func (a AuctionState) CanLeave() bool

CanLeave bool indicating whether auction should be closed or not, if true, we can still extend the auction but when the market takes over (after monitoring engines), the auction will be closed.

func (AuctionState) Changed

func (a AuctionState) Changed() bool

func (AuctionState) Duration

func (a AuctionState) Duration() types.AuctionDuration

Duration returns a copy of the current auction duration object.

func (*AuctionState) EndGovernanceSuspensionAuction

func (a *AuctionState) EndGovernanceSuspensionAuction()

func (*AuctionState) ExceededMaxOpening

func (a *AuctionState) ExceededMaxOpening(now time.Time) bool

func (AuctionState) ExpiresAt

func (a AuctionState) ExpiresAt() *time.Time

ExpiresAt returns end as time -> if nil, the auction duration either isn't determined by time or we're simply not in an auction.

func (*AuctionState) ExtendAuction

func (a *AuctionState) ExtendAuction(delta types.AuctionDuration)

ExtendAuction extends the current auction.

func (*AuctionState) ExtendAuctionPrice

func (a *AuctionState) ExtendAuctionPrice(delta types.AuctionDuration)

ExtendAuctionPrice - call from price monitoring to extend the auction sets the extension trigger field accordingly.

func (*AuctionState) ExtendAuctionSuspension

func (a *AuctionState) ExtendAuctionSuspension(delta types.AuctionDuration)

func (AuctionState) ExtensionTrigger

func (a AuctionState) ExtensionTrigger() types.AuctionTrigger

ExtensionTrigger returns what extended an auction.

func (*AuctionState) GetAuctionBegin

func (a *AuctionState) GetAuctionBegin() *time.Time

func (*AuctionState) GetAuctionEnd

func (a *AuctionState) GetAuctionEnd() *time.Time

func (*AuctionState) GetState

func (a *AuctionState) GetState() *types.AuctionState

func (AuctionState) InAuction

func (a AuctionState) InAuction() bool

InAuction returns bool if the market is in auction for any reason Returns false if auction is triggered, but not yet started by market (execution).

func (AuctionState) IsFBA

func (a AuctionState) IsFBA() bool

func (AuctionState) IsMonitorAuction

func (a AuctionState) IsMonitorAuction() bool

IsMonitorAuction - quick way to determine whether or not we're in an auction triggered by a monitoring engine.

func (AuctionState) IsOpeningAuction

func (a AuctionState) IsOpeningAuction() bool

func (AuctionState) IsPriceAuction

func (a AuctionState) IsPriceAuction() bool

func (AuctionState) IsPriceExtension

func (a AuctionState) IsPriceExtension() bool

func (*AuctionState) Left

func (a *AuctionState) Left(ctx context.Context, now time.Time) *events.Auction

Left is called by execution to update internal state indicating this auction was closed.

func (AuctionState) Mode

func (a AuctionState) Mode() types.MarketTradingMode

Mode returns current trading mode.

func (*AuctionState) SetReadyToLeave

func (a *AuctionState) SetReadyToLeave()

SetReadyToLeave is called by monitoring engines to mark if an auction period has expired.

func (AuctionState) Start

func (a AuctionState) Start() time.Time

Start - returns time pointer of the start of the auction (nil if not in auction).

func (*AuctionState) StartGovernanceSuspensionAuction

func (a *AuctionState) StartGovernanceSuspensionAuction(t time.Time)

func (*AuctionState) StartLiquidityAuctionUnmetTarget

func (a *AuctionState) StartLiquidityAuctionUnmetTarget(t time.Time, d *types.AuctionDuration)

func (*AuctionState) StartOpeningAuction

func (a *AuctionState) StartOpeningAuction(t time.Time, d *types.AuctionDuration)

StartOpeningAuction - set the state to start an opening auction (used for testing) @TODO these functions will be removed once the types are in proto.

func (*AuctionState) StartPriceAuction

func (a *AuctionState) StartPriceAuction(t time.Time, d *types.AuctionDuration)

StartPriceAuction - set the state to start a price triggered auction @TODO these functions will be removed once the types are in proto.

func (AuctionState) Trigger

func (a AuctionState) Trigger() types.AuctionTrigger

Trigger returns what triggered an auction.

func (*AuctionState) UpdateMaxDuration

func (a *AuctionState) UpdateMaxDuration(_ context.Context, d time.Duration)

func (*AuctionState) UpdateMinDuration

func (a *AuctionState) UpdateMinDuration(ctx context.Context, d time.Duration) *events.Auction

UpdateMinDuration - see if we need to update the end value for current auction duration (if any) if the auction duration increases, an auction event will be returned.