Merge remote-tracking branch 'origin/development' into feature/utils/prettybignum

5 files changed, 501 insertions, 0 deletions

diff --git a/packages/asset-buyer/src/utils/assert.ts b/packages/asset-buyer/src/utils/assert.ts
new file mode 100644
index 000000000..2466f53a4
--- /dev/null
+++ b/packages/asset-buyer/src/utils/assert.ts
@@ -0,0 +1,39 @@
+import { assert as sharedAssert } from '@0x/assert';
+import { schemas } from '@0x/json-schemas';
+import * as _ from 'lodash';
+
+import { BuyQuote, BuyQuoteInfo, OrderProvider, OrderProviderRequest } from '../types';
+
+export const assert = {
+    ...sharedAssert,
+    isValidBuyQuote(variableName: string, buyQuote: BuyQuote): void {
+        sharedAssert.isHexString(`${variableName}.assetData`, buyQuote.assetData);
+        sharedAssert.doesConformToSchema(`${variableName}.orders`, buyQuote.orders, schemas.signedOrdersSchema);
+        sharedAssert.doesConformToSchema(`${variableName}.feeOrders`, buyQuote.feeOrders, schemas.signedOrdersSchema);
+        assert.isValidBuyQuoteInfo(`${variableName}.bestCaseQuoteInfo`, buyQuote.bestCaseQuoteInfo);
+        assert.isValidBuyQuoteInfo(`${variableName}.worstCaseQuoteInfo`, buyQuote.worstCaseQuoteInfo);
+        sharedAssert.isBigNumber(`${variableName}.assetBuyAmount`, buyQuote.assetBuyAmount);
+        if (!_.isUndefined(buyQuote.feePercentage)) {
+            sharedAssert.isNumber(`${variableName}.feePercentage`, buyQuote.feePercentage);
+        }
+    },
+    isValidBuyQuoteInfo(variableName: string, buyQuoteInfo: BuyQuoteInfo): void {
+        sharedAssert.isBigNumber(`${variableName}.ethPerAssetPrice`, buyQuoteInfo.ethPerAssetPrice);
+        sharedAssert.isBigNumber(`${variableName}.feeEthAmount`, buyQuoteInfo.feeEthAmount);
+        sharedAssert.isBigNumber(`${variableName}.totalEthAmount`, buyQuoteInfo.totalEthAmount);
+    },
+    isValidOrderProvider(variableName: string, orderFetcher: OrderProvider): void {
+        sharedAssert.isFunction(`${variableName}.getOrdersAsync`, orderFetcher.getOrdersAsync);
+    },
+    isValidOrderProviderRequest(variableName: string, orderFetcherRequest: OrderProviderRequest): void {
+        sharedAssert.isHexString(`${variableName}.makerAssetData`, orderFetcherRequest.makerAssetData);
+        sharedAssert.isHexString(`${variableName}.takerAssetData`, orderFetcherRequest.takerAssetData);
+    },
+    isValidPercentage(variableName: string, percentage: number): void {
+        assert.isNumber(variableName, percentage);
+        assert.assert(
+            percentage >= 0 && percentage <= 1,
+            `Expected ${variableName} to be between 0 and 1, but is ${percentage}`,
+        );
+    },
+};
diff --git a/packages/asset-buyer/src/utils/asset_data_utils.ts b/packages/asset-buyer/src/utils/asset_data_utils.ts
new file mode 100644
index 000000000..70f646902
--- /dev/null
+++ b/packages/asset-buyer/src/utils/asset_data_utils.ts
@@ -0,0 +1,12 @@
+import { ContractWrappers } from '@0x/contract-wrappers';
+import { assetDataUtils as sharedAssetDataUtils } from '@0x/order-utils';
+import * as _ from 'lodash';
+
+export const assetDataUtils = {
+    ...sharedAssetDataUtils,
+    getEtherTokenAssetData(contractWrappers: ContractWrappers): string {
+        const etherTokenAddress = contractWrappers.forwarder.etherTokenAddress;
+        const etherTokenAssetData = sharedAssetDataUtils.encodeERC20AssetData(etherTokenAddress);
+        return etherTokenAssetData;
+    },
+};
diff --git a/packages/asset-buyer/src/utils/buy_quote_calculator.ts b/packages/asset-buyer/src/utils/buy_quote_calculator.ts
new file mode 100644
index 000000000..6a67ed1ed
--- /dev/null
+++ b/packages/asset-buyer/src/utils/buy_quote_calculator.ts
@@ -0,0 +1,207 @@
+import { marketUtils, SignedOrder } from '@0x/order-utils';
+import { BigNumber } from '@0x/utils';
+import * as _ from 'lodash';
+
+import { constants } from '../constants';
+import { AssetBuyerError, BuyQuote, BuyQuoteInfo, OrdersAndFillableAmounts } from '../types';
+
+import { orderUtils } from './order_utils';
+
+// Calculates a buy quote for orders that have WETH as the takerAsset
+export const buyQuoteCalculator = {
+    calculate(
+        ordersAndFillableAmounts: OrdersAndFillableAmounts,
+        feeOrdersAndFillableAmounts: OrdersAndFillableAmounts,
+        assetBuyAmount: BigNumber,
+        feePercentage: number,
+        slippagePercentage: number,
+        isMakerAssetZrxToken: boolean,
+    ): BuyQuote {
+        const orders = ordersAndFillableAmounts.orders;
+        const remainingFillableMakerAssetAmounts = ordersAndFillableAmounts.remainingFillableMakerAssetAmounts;
+        const feeOrders = feeOrdersAndFillableAmounts.orders;
+        const remainingFillableFeeAmounts = feeOrdersAndFillableAmounts.remainingFillableMakerAssetAmounts;
+        const slippageBufferAmount = assetBuyAmount.mul(slippagePercentage).round();
+        // find the orders that cover the desired assetBuyAmount (with slippage)
+        const {
+            resultOrders,
+            remainingFillAmount,
+            ordersRemainingFillableMakerAssetAmounts,
+        } = marketUtils.findOrdersThatCoverMakerAssetFillAmount(orders, assetBuyAmount, {
+            remainingFillableMakerAssetAmounts,
+            slippageBufferAmount,
+        });
+        // if we do not have enough orders to cover the desired assetBuyAmount, throw
+        if (remainingFillAmount.gt(constants.ZERO_AMOUNT)) {
+            throw new Error(AssetBuyerError.InsufficientAssetLiquidity);
+        }
+        // if we are not buying ZRX:
+        // given the orders calculated above, find the fee-orders that cover the desired assetBuyAmount (with slippage)
+        // TODO(bmillman): optimization
+        // update this logic to find the minimum amount of feeOrders to cover the worst case as opposed to
+        // finding order that cover all fees, this will help with estimating ETH and minimizing gas usage
+        let resultFeeOrders = [] as SignedOrder[];
+        let feeOrdersRemainingFillableMakerAssetAmounts = [] as BigNumber[];
+        if (!isMakerAssetZrxToken) {
+            const feeOrdersAndRemainingFeeAmount = marketUtils.findFeeOrdersThatCoverFeesForTargetOrders(
+                resultOrders,
+                feeOrders,
+                {
+                    remainingFillableMakerAssetAmounts: ordersRemainingFillableMakerAssetAmounts,
+                    remainingFillableFeeAmounts,
+                },
+            );
+            // if we do not have enough feeOrders to cover the fees, throw
+            if (feeOrdersAndRemainingFeeAmount.remainingFeeAmount.gt(constants.ZERO_AMOUNT)) {
+                throw new Error(AssetBuyerError.InsufficientZrxLiquidity);
+            }
+            resultFeeOrders = feeOrdersAndRemainingFeeAmount.resultFeeOrders;
+            feeOrdersRemainingFillableMakerAssetAmounts =
+                feeOrdersAndRemainingFeeAmount.feeOrdersRemainingFillableMakerAssetAmounts;
+        }
+
+        // assetData information for the result
+        const assetData = orders[0].makerAssetData;
+        // compile the resulting trimmed set of orders for makerAsset and feeOrders that are needed for assetBuyAmount
+        const trimmedOrdersAndFillableAmounts: OrdersAndFillableAmounts = {
+            orders: resultOrders,
+            remainingFillableMakerAssetAmounts: ordersRemainingFillableMakerAssetAmounts,
+        };
+        const trimmedFeeOrdersAndFillableAmounts: OrdersAndFillableAmounts = {
+            orders: resultFeeOrders,
+            remainingFillableMakerAssetAmounts: feeOrdersRemainingFillableMakerAssetAmounts,
+        };
+        const bestCaseQuoteInfo = calculateQuoteInfo(
+            trimmedOrdersAndFillableAmounts,
+            trimmedFeeOrdersAndFillableAmounts,
+            assetBuyAmount,
+            feePercentage,
+            isMakerAssetZrxToken,
+        );
+        // in order to calculate the maxRate, reverse the ordersAndFillableAmounts such that they are sorted from worst rate to best rate
+        const worstCaseQuoteInfo = calculateQuoteInfo(
+            reverseOrdersAndFillableAmounts(trimmedOrdersAndFillableAmounts),
+            reverseOrdersAndFillableAmounts(trimmedFeeOrdersAndFillableAmounts),
+            assetBuyAmount,
+            feePercentage,
+            isMakerAssetZrxToken,
+        );
+        return {
+            assetData,
+            orders: resultOrders,
+            feeOrders: resultFeeOrders,
+            bestCaseQuoteInfo,
+            worstCaseQuoteInfo,
+            assetBuyAmount,
+            feePercentage,
+        };
+    },
+};
+
+function calculateQuoteInfo(
+    ordersAndFillableAmounts: OrdersAndFillableAmounts,
+    feeOrdersAndFillableAmounts: OrdersAndFillableAmounts,
+    assetBuyAmount: BigNumber,
+    feePercentage: number,
+    isMakerAssetZrxToken: boolean,
+): BuyQuoteInfo {
+    // find the total eth and zrx needed to buy assetAmount from the resultOrders from left to right
+    let ethAmountToBuyAsset = constants.ZERO_AMOUNT;
+    let ethAmountToBuyZrx = constants.ZERO_AMOUNT;
+    if (isMakerAssetZrxToken) {
+        ethAmountToBuyAsset = findEthAmountNeededToBuyZrx(ordersAndFillableAmounts, assetBuyAmount);
+    } else {
+        // find eth and zrx amounts needed to buy
+        const ethAndZrxAmountToBuyAsset = findEthAndZrxAmountNeededToBuyAsset(ordersAndFillableAmounts, assetBuyAmount);
+        ethAmountToBuyAsset = ethAndZrxAmountToBuyAsset[0];
+        const zrxAmountToBuyAsset = ethAndZrxAmountToBuyAsset[1];
+        // find eth amount needed to buy zrx
+        ethAmountToBuyZrx = findEthAmountNeededToBuyZrx(feeOrdersAndFillableAmounts, zrxAmountToBuyAsset);
+    }
+    /// find the eth amount needed to buy the affiliate fee
+    const ethAmountToBuyAffiliateFee = ethAmountToBuyAsset.mul(feePercentage).ceil();
+    const totalEthAmountWithoutAffiliateFee = ethAmountToBuyAsset.plus(ethAmountToBuyZrx);
+    const ethAmountTotal = totalEthAmountWithoutAffiliateFee.plus(ethAmountToBuyAffiliateFee);
+    // divide into the assetBuyAmount in order to find rate of makerAsset / WETH
+    const ethPerAssetPrice = totalEthAmountWithoutAffiliateFee.div(assetBuyAmount);
+    return {
+        totalEthAmount: ethAmountTotal,
+        feeEthAmount: ethAmountToBuyAffiliateFee,
+        ethPerAssetPrice,
+    };
+}
+
+// given an OrdersAndFillableAmounts, reverse the orders and remainingFillableMakerAssetAmounts properties
+function reverseOrdersAndFillableAmounts(ordersAndFillableAmounts: OrdersAndFillableAmounts): OrdersAndFillableAmounts {
+    const ordersCopy = _.clone(ordersAndFillableAmounts.orders);
+    const remainingFillableMakerAssetAmountsCopy = _.clone(ordersAndFillableAmounts.remainingFillableMakerAssetAmounts);
+    return {
+        orders: ordersCopy.reverse(),
+        remainingFillableMakerAssetAmounts: remainingFillableMakerAssetAmountsCopy.reverse(),
+    };
+}
+
+function findEthAmountNeededToBuyZrx(
+    feeOrdersAndFillableAmounts: OrdersAndFillableAmounts,
+    zrxBuyAmount: BigNumber,
+): BigNumber {
+    const { orders, remainingFillableMakerAssetAmounts } = feeOrdersAndFillableAmounts;
+    const result = _.reduce(
+        orders,
+        (acc, order, index) => {
+            const { totalEthAmount, remainingZrxBuyAmount } = acc;
+            const remainingFillableMakerAssetAmount = remainingFillableMakerAssetAmounts[index];
+            const makerFillAmount = BigNumber.min(remainingZrxBuyAmount, remainingFillableMakerAssetAmount);
+            const [takerFillAmount, adjustedMakerFillAmount] = orderUtils.getTakerFillAmountForFeeOrder(
+                order,
+                makerFillAmount,
+            );
+            const extraFeeAmount = remainingFillableMakerAssetAmount.greaterThanOrEqualTo(adjustedMakerFillAmount)
+                ? constants.ZERO_AMOUNT
+                : adjustedMakerFillAmount.sub(makerFillAmount);
+            return {
+                totalEthAmount: totalEthAmount.plus(takerFillAmount),
+                remainingZrxBuyAmount: BigNumber.max(
+                    constants.ZERO_AMOUNT,
+                    remainingZrxBuyAmount.minus(makerFillAmount).plus(extraFeeAmount),
+                ),
+            };
+        },
+        {
+            totalEthAmount: constants.ZERO_AMOUNT,
+            remainingZrxBuyAmount: zrxBuyAmount,
+        },
+    );
+    return result.totalEthAmount;
+}
+
+function findEthAndZrxAmountNeededToBuyAsset(
+    ordersAndFillableAmounts: OrdersAndFillableAmounts,
+    assetBuyAmount: BigNumber,
+): [BigNumber, BigNumber] {
+    const { orders, remainingFillableMakerAssetAmounts } = ordersAndFillableAmounts;
+    const result = _.reduce(
+        orders,
+        (acc, order, index) => {
+            const { totalEthAmount, totalZrxAmount, remainingAssetBuyAmount } = acc;
+            const remainingFillableMakerAssetAmount = remainingFillableMakerAssetAmounts[index];
+            const makerFillAmount = BigNumber.min(acc.remainingAssetBuyAmount, remainingFillableMakerAssetAmount);
+            const takerFillAmount = orderUtils.getTakerFillAmount(order, makerFillAmount);
+            const takerFeeAmount = orderUtils.getTakerFeeAmount(order, takerFillAmount);
+            return {
+                totalEthAmount: totalEthAmount.plus(takerFillAmount),
+                totalZrxAmount: totalZrxAmount.plus(takerFeeAmount),
+                remainingAssetBuyAmount: BigNumber.max(
+                    constants.ZERO_AMOUNT,
+                    remainingAssetBuyAmount.minus(makerFillAmount),
+                ),
+            };
+        },
+        {
+            totalEthAmount: constants.ZERO_AMOUNT,
+            totalZrxAmount: constants.ZERO_AMOUNT,
+            remainingAssetBuyAmount: assetBuyAmount,
+        },
+    );
+    return [result.totalEthAmount, result.totalZrxAmount];
+}
diff --git a/packages/asset-buyer/src/utils/order_provider_response_processor.ts b/packages/asset-buyer/src/utils/order_provider_response_processor.ts
new file mode 100644
index 000000000..28f684f3c
--- /dev/null
+++ b/packages/asset-buyer/src/utils/order_provider_response_processor.ts
@@ -0,0 +1,169 @@
+import { OrderAndTraderInfo, OrderStatus, OrderValidatorWrapper } from '@0x/contract-wrappers';
+import { sortingUtils } from '@0x/order-utils';
+import { RemainingFillableCalculator } from '@0x/order-utils/lib/src/remaining_fillable_calculator';
+import { SignedOrder } from '@0x/types';
+import { BigNumber } from '@0x/utils';
+import * as _ from 'lodash';
+
+import { constants } from '../constants';
+import {
+    AssetBuyerError,
+    OrderProviderRequest,
+    OrderProviderResponse,
+    OrdersAndFillableAmounts,
+    SignedOrderWithRemainingFillableMakerAssetAmount,
+} from '../types';
+
+import { orderUtils } from './order_utils';
+
+export const orderProviderResponseProcessor = {
+    throwIfInvalidResponse(response: OrderProviderResponse, request: OrderProviderRequest): void {
+        const { makerAssetData, takerAssetData } = request;
+        _.forEach(response.orders, order => {
+            if (order.makerAssetData !== makerAssetData || order.takerAssetData !== takerAssetData) {
+                throw new Error(AssetBuyerError.InvalidOrderProviderResponse);
+            }
+        });
+    },
+    /**
+     * Take the responses for the target orders to buy and fee orders and process them.
+     * Processing includes:
+     * - Drop orders that are expired or not open orders (null taker address)
+     * - If shouldValidateOnChain, attempt to grab fillable amounts from on-chain otherwise assume completely fillable
+     * - Sort by rate
+     */
+    async processAsync(
+        orderProviderResponse: OrderProviderResponse,
+        isMakerAssetZrxToken: boolean,
+        expiryBufferSeconds: number,
+        orderValidator?: OrderValidatorWrapper,
+    ): Promise<OrdersAndFillableAmounts> {
+        // drop orders that are expired or not open
+        const filteredOrders = filterOutExpiredAndNonOpenOrders(orderProviderResponse.orders, expiryBufferSeconds);
+        // set the orders to be sorted equal to the filtered orders
+        let unsortedOrders = filteredOrders;
+        // if an orderValidator is provided, use on chain information to calculate remaining fillable makerAsset amounts
+        if (!_.isUndefined(orderValidator)) {
+            // TODO(bmillman): improvement
+            // try/catch this request and throw a more domain specific error
+            const takerAddresses = _.map(filteredOrders, () => constants.NULL_ADDRESS);
+            const ordersAndTradersInfo = await orderValidator.getOrdersAndTradersInfoAsync(
+                filteredOrders,
+                takerAddresses,
+            );
+            // take orders + on chain information and find the valid orders and remaining fillable maker asset amounts
+            unsortedOrders = getValidOrdersWithRemainingFillableMakerAssetAmountsFromOnChain(
+                filteredOrders,
+                ordersAndTradersInfo,
+                isMakerAssetZrxToken,
+            );
+        }
+        // sort orders by rate
+        // TODO(bmillman): optimization
+        // provide a feeRate to the sorting function to more accurately sort based on the current market for ZRX tokens
+        const sortedOrders = isMakerAssetZrxToken
+            ? sortingUtils.sortFeeOrdersByFeeAdjustedRate(unsortedOrders)
+            : sortingUtils.sortOrdersByFeeAdjustedRate(unsortedOrders);
+        // unbundle orders and fillable amounts and compile final result
+        const result = unbundleOrdersWithAmounts(sortedOrders);
+        return result;
+    },
+};
+
+/**
+ * Given an array of orders, return a new array with expired and non open orders filtered out.
+ */
+function filterOutExpiredAndNonOpenOrders(
+    orders: SignedOrderWithRemainingFillableMakerAssetAmount[],
+    expiryBufferSeconds: number,
+): SignedOrderWithRemainingFillableMakerAssetAmount[] {
+    const result = _.filter(orders, order => {
+        return orderUtils.isOpenOrder(order) && !orderUtils.willOrderExpire(order, expiryBufferSeconds);
+    });
+    return result;
+}
+
+/**
+ * Given an array of orders and corresponding on-chain infos, return a subset of the orders
+ * that are still fillable orders with their corresponding remainingFillableMakerAssetAmounts.
+ */
+function getValidOrdersWithRemainingFillableMakerAssetAmountsFromOnChain(
+    inputOrders: SignedOrder[],
+    ordersAndTradersInfo: OrderAndTraderInfo[],
+    isMakerAssetZrxToken: boolean,
+): SignedOrderWithRemainingFillableMakerAssetAmount[] {
+    // iterate through the input orders and find the ones that are still fillable
+    // for the orders that are still fillable, calculate the remaining fillable maker asset amount
+    const result = _.reduce(
+        inputOrders,
+        (accOrders, order, index) => {
+            // get corresponding on-chain state for the order
+            const { orderInfo, traderInfo } = ordersAndTradersInfo[index];
+            // if the order IS NOT fillable, do not add anything to the accumulations and continue iterating
+            if (orderInfo.orderStatus !== OrderStatus.FILLABLE) {
+                return accOrders;
+            }
+            // if the order IS fillable, add the order and calculate the remaining fillable amount
+            const transferrableAssetAmount = BigNumber.min([traderInfo.makerAllowance, traderInfo.makerBalance]);
+            const transferrableFeeAssetAmount = BigNumber.min([
+                traderInfo.makerZrxAllowance,
+                traderInfo.makerZrxBalance,
+            ]);
+            const remainingTakerAssetAmount = order.takerAssetAmount.minus(orderInfo.orderTakerAssetFilledAmount);
+            const remainingMakerAssetAmount = orderUtils.getRemainingMakerAmount(order, remainingTakerAssetAmount);
+            const remainingFillableCalculator = new RemainingFillableCalculator(
+                order.makerFee,
+                order.makerAssetAmount,
+                isMakerAssetZrxToken,
+                transferrableAssetAmount,
+                transferrableFeeAssetAmount,
+                remainingMakerAssetAmount,
+            );
+            const remainingFillableAmount = remainingFillableCalculator.computeRemainingFillable();
+            // if the order does not have any remaining fillable makerAsset, do not add anything to the accumulations and continue iterating
+            if (remainingFillableAmount.lte(constants.ZERO_AMOUNT)) {
+                return accOrders;
+            }
+            const orderWithRemainingFillableMakerAssetAmount = {
+                ...order,
+                remainingFillableMakerAssetAmount: remainingFillableAmount,
+            };
+            const newAccOrders = _.concat(accOrders, orderWithRemainingFillableMakerAssetAmount);
+            return newAccOrders;
+        },
+        [] as SignedOrderWithRemainingFillableMakerAssetAmount[],
+    );
+    return result;
+}
+
+/**
+ * Given an array of orders with remaining fillable maker asset amounts. Unbundle into an instance of OrdersAndRemainingFillableMakerAssetAmounts.
+ * If an order is missing a corresponding remainingFillableMakerAssetAmount, assume it is completely fillable.
+ */
+function unbundleOrdersWithAmounts(
+    ordersWithAmounts: SignedOrderWithRemainingFillableMakerAssetAmount[],
+): OrdersAndFillableAmounts {
+    const result = _.reduce(
+        ordersWithAmounts,
+        (acc, orderWithAmount) => {
+            const { orders, remainingFillableMakerAssetAmounts } = acc;
+            const { remainingFillableMakerAssetAmount, ...order } = orderWithAmount;
+            // if we are still missing a remainingFillableMakerAssetAmount, assume the order is completely fillable
+            const newRemainingAmount = remainingFillableMakerAssetAmount || order.makerAssetAmount;
+            // if remaining amount is less than or equal to zero, do not add it
+            if (newRemainingAmount.lte(constants.ZERO_AMOUNT)) {
+                return acc;
+            }
+            const newAcc = {
+                orders: _.concat(orders, order),
+                remainingFillableMakerAssetAmounts: _.concat(remainingFillableMakerAssetAmounts, newRemainingAmount),
+            };
+            return newAcc;
+        },
+        {
+            orders: [] as SignedOrder[],
+            remainingFillableMakerAssetAmounts: [] as BigNumber[],
+        },
+    );
+    return result;
+}
diff --git a/packages/asset-buyer/src/utils/order_utils.ts b/packages/asset-buyer/src/utils/order_utils.ts
new file mode 100644
index 000000000..1cc2cf95f
--- /dev/null
+++ b/packages/asset-buyer/src/utils/order_utils.ts
@@ -0,0 +1,74 @@
+import { SignedOrder } from '@0x/types';
+import { BigNumber } from '@0x/utils';
+
+import { constants } from '../constants';
+
+export const orderUtils = {
+    isOrderExpired(order: SignedOrder): boolean {
+        return orderUtils.willOrderExpire(order, 0);
+    },
+    willOrderExpire(order: SignedOrder, secondsFromNow: number): boolean {
+        const millisecondsInSecond = 1000;
+        const currentUnixTimestampSec = new BigNumber(Date.now() / millisecondsInSecond).round();
+        return order.expirationTimeSeconds.lessThan(currentUnixTimestampSec.plus(secondsFromNow));
+    },
+    isOpenOrder(order: SignedOrder): boolean {
+        return order.takerAddress === constants.NULL_ADDRESS;
+    },
+    // given a remaining amount of takerAsset, calculate how much makerAsset is available
+    getRemainingMakerAmount(order: SignedOrder, remainingTakerAmount: BigNumber): BigNumber {
+        const remainingMakerAmount = remainingTakerAmount
+            .times(order.makerAssetAmount)
+            .div(order.takerAssetAmount)
+            .floor();
+        return remainingMakerAmount;
+    },
+    // given a desired amount of makerAsset, calculate how much takerAsset is required to fill that amount
+    getTakerFillAmount(order: SignedOrder, makerFillAmount: BigNumber): BigNumber {
+        // Round up because exchange rate favors Maker
+        const takerFillAmount = makerFillAmount
+            .mul(order.takerAssetAmount)
+            .div(order.makerAssetAmount)
+            .ceil();
+        return takerFillAmount;
+    },
+    // given a desired amount of takerAsset to fill, calculate how much fee is required by the taker to fill that amount
+    getTakerFeeAmount(order: SignedOrder, takerFillAmount: BigNumber): BigNumber {
+        // Round down because Taker fee rate favors Taker
+        const takerFeeAmount = takerFillAmount
+            .mul(order.takerFee)
+            .div(order.takerAssetAmount)
+            .floor();
+        return takerFeeAmount;
+    },
+    // given a desired amount of takerAsset to fill, calculate how much makerAsset will be filled
+    getMakerFillAmount(order: SignedOrder, takerFillAmount: BigNumber): BigNumber {
+        // Round down because exchange rate favors Maker
+        const makerFillAmount = takerFillAmount
+            .mul(order.makerAssetAmount)
+            .div(order.takerAssetAmount)
+            .floor();
+        return makerFillAmount;
+    },
+    // given a desired amount of makerAsset, calculate how much fee is required by the maker to fill that amount
+    getMakerFeeAmount(order: SignedOrder, makerFillAmount: BigNumber): BigNumber {
+        // Round down because Maker fee rate favors Maker
+        const makerFeeAmount = makerFillAmount
+            .mul(order.makerFee)
+            .div(order.makerAssetAmount)
+            .floor();
+        return makerFeeAmount;
+    },
+    // given a desired amount of ZRX from a fee order, calculate how much takerAsset is required to fill that amount
+    // also calculate how much ZRX needs to be bought in order fill the desired amount + takerFee
+    getTakerFillAmountForFeeOrder(order: SignedOrder, makerFillAmount: BigNumber): [BigNumber, BigNumber] {
+        // For each unit of TakerAsset we buy (MakerAsset - TakerFee)
+        const adjustedTakerFillAmount = makerFillAmount
+            .mul(order.takerAssetAmount)
+            .div(order.makerAssetAmount.sub(order.takerFee))
+            .ceil();
+        // The amount that we buy will be greater than makerFillAmount, since we buy some amount for fees.
+        const adjustedMakerFillAmount = orderUtils.getMakerFillAmount(order, adjustedTakerFillAmount);
+        return [adjustedTakerFillAmount, adjustedMakerFillAmount];
+    },
+};