Tutorial: Order Matching Bot

7min

Introduction
Order Matching Bots (Matching Bots) are responsible for matching two orders that cross or a taker order against the DAMM. Specifically, this includes: 
Market Orders: Market Buy and Market Sell
Limit Orders: Limit Buy and Limit Sell 
Matching Bots receive a small compensation for each order that they successfully fill.
See Keepers & Decentralised Orderbook﻿ for a technical explanation of how the decentralised orderbook (DLOB) and matching incentives work.
Matching Bots are similar to Tutorial: Order Trigger Bot﻿ in that they:
also maintain a local copy of the Decentralised Limit Orderbook (DLOB);
do not require the operator to manage collateral; and
receive a small reward for performing their duties.
Getting Started
The reference implementation of the Order Matching Bot is available here.
Follow the instructions at Keeper Bots﻿ to set the required environment variables and make sure a ClearingHouseUser is initialized.
Start the Matching Bot:
Shell
yarn run dev:filler
yarn run dev:filler
﻿
﻿
Technical Explanation
1. Get nodes from the DLOB that are ready to be filled
Market orders that are sent on the Drift Protocol first go through the Just-In-Time (JIT) Auctions﻿. After the auction period, Matching Bots step in to fill orders for a small reward. 
The DLOB implementation includes a method for getting orders ready to be filled:
TypeScript
const market = this.clearingHouse.getMarketAccounts()[0]; // get a MarketAccount

const oraclePriceData =
    this.driftClient.getOracleDataForMarket(marketIndex);
const oracleIsValid = isOracleValid(
    market.amm,
    oraclePriceData,
    this.driftClient.getStateAccount().oracleGuardRails,
    this.slotSubscriber.getSlot()
);

const vAsk = calculateAskPrice(market, oraclePriceData);
const vBid = calculateBidPrice(market, oraclePriceData);

const nodesToFill = this.dlob.findNodesToFill(
    marketIndex,
    vBid,
    vAsk,
    this.slotSubscriber.getSlot(),
    oracleIsValid ? oraclePriceData : undefined
);
const market = this.clearingHouse.getMarketAccounts()[0]; // get a MarketAccount

const oraclePriceData =
    this.driftClient.getOracleDataForMarket(marketIndex);
const oracleIsValid = isOracleValid(
    market.amm,
    oraclePriceData,
    this.driftClient.getStateAccount().oracleGuardRails,
    this.slotSubscriber.getSlot()
);

const vAsk = calculateAskPrice(market, oraclePriceData);
const vBid = calculateBidPrice(market, oraclePriceData);

const nodesToFill = this.dlob.findNodesToFill(
    marketIndex,
    vBid,
    vAsk,
    this.slotSubscriber.getSlot(),
    oracleIsValid ? oraclePriceData : undefined
);
﻿
2. Filter for Fillable Nodes
To avoid trying to fill orders that aren't ready to be filled, filter out orders that are too small to fill
TypeScript
if (
    !nodeToFill.makerNode &&
    (isVariant(nodeToFill.node.order.orderType, 'limit') ||
        isVariant(nodeToFill.node.order.orderType, 'triggerLimit'))
) {
    const baseAssetAmountMarketCanExecute =
        calculateBaseAssetAmountMarketCanExecute(
            market,
            nodeToFill.node.order,
            oraclePriceData
        );

    if (
        baseAssetAmountMarketCanExecute.lt(
            market.amm.baseAssetAmountStepSize
        )
    ) {
        // skip order
        continue;
    }
}
if (
    !nodeToFill.makerNode &&
    (isVariant(nodeToFill.node.order.orderType, 'limit') ||
        isVariant(nodeToFill.node.order.orderType, 'triggerLimit'))
) {
    const baseAssetAmountMarketCanExecute =
        calculateBaseAssetAmountMarketCanExecute(
            market,
            nodeToFill.node.order,
            oraclePriceData
        );

    if (
        baseAssetAmountMarketCanExecute.lt(
            market.amm.baseAssetAmountStepSize
        )
    ) {
        // skip order
        continue;
    }
}
﻿
3. Call fill_order on DriftClient 
TypeScript
const user = this.userMap.get(nodeToFill.node.userAccount.toString());
const txSig = await this.driftClient.fillOrder(
    nodeToFill.node.userAccount,
    user.getUserAccount(),
    nodeToFill.node.order,
    undefined,
);
const user = this.userMap.get(nodeToFill.node.userAccount.toString());
const txSig = await this.driftClient.fillOrder(
    nodeToFill.node.userAccount,
    user.getUserAccount(),
    nodeToFill.node.order,
    undefined,
);
﻿
﻿