From 343cd05363166a7a93fca361d5547b39f3e83d99 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 3 Aug 2018 21:27:01 +0200 Subject: Add missing comments --- ...abstract_balance_and_proxy_allowance_fetcher.ts | 17 +++++++ .../abstract_order_filled_cancelled_fetcher.ts | 15 ++++++ packages/order-utils/src/eip712_utils.ts | 28 +++++++++--- .../order-utils/src/exchange_transfer_simulator.ts | 9 ++++ packages/order-utils/src/order_state_utils.ts | 53 +++++++++++----------- packages/order-utils/src/order_validation_utils.ts | 50 ++++++++++++++++++++ .../balance_and_proxy_allowance_lazy_store.ts | 43 ++++++++++++++++++ .../src/store/order_filled_cancelled_lazy_store.ts | 45 ++++++++++++++++++ 8 files changed, 228 insertions(+), 32 deletions(-) (limited to 'packages/order-utils/src') diff --git a/packages/order-utils/src/abstract/abstract_balance_and_proxy_allowance_fetcher.ts b/packages/order-utils/src/abstract/abstract_balance_and_proxy_allowance_fetcher.ts index b2760d98e..7cb859ca7 100644 --- a/packages/order-utils/src/abstract/abstract_balance_and_proxy_allowance_fetcher.ts +++ b/packages/order-utils/src/abstract/abstract_balance_and_proxy_allowance_fetcher.ts @@ -1,6 +1,23 @@ import { BigNumber } from '@0xproject/utils'; +/**l + * An abstract class to be implemented in order to use OrderStateUtils. The class that + * implements this interface must be capable of fetching the balance and proxyAllowance + * for an Ethereum address and assetData + */ export abstract class AbstractBalanceAndProxyAllowanceFetcher { + /** + * Get balance of assetData for userAddress + * @param assetData AssetData for which to fetch the balance + * @param userAddress Ethereum address for which to fetch the balance + * @return Balance amount in base units + */ public abstract async getBalanceAsync(assetData: string, userAddress: string): Promise; + /** + * Get the 0x asset proxy allowance of assetData for userAddress + * @param assetData AssetData for which to fetch the allowance + * @param userAddress Ethereum address for which to fetch the allowance + * @return Allowance amount in base units + */ public abstract async getProxyAllowanceAsync(assetData: string, userAddress: string): Promise; } diff --git a/packages/order-utils/src/abstract/abstract_order_filled_cancelled_fetcher.ts b/packages/order-utils/src/abstract/abstract_order_filled_cancelled_fetcher.ts index 865ea4e43..d2b01c359 100644 --- a/packages/order-utils/src/abstract/abstract_order_filled_cancelled_fetcher.ts +++ b/packages/order-utils/src/abstract/abstract_order_filled_cancelled_fetcher.ts @@ -1,7 +1,22 @@ import { BigNumber } from '@0xproject/utils'; +/**l + * An abstract class to be implemented in order to use OrderStateUtils. The class that + * implements this interface must be capable of fetching the amount filled of an order + * and whether it's been cancelled. + */ export abstract class AbstractOrderFilledCancelledFetcher { + /** + * Get the amount of the order's takerToken amount already filled + * @param orderHash OrderHash of order we are interested in + * @return FilledTakerAmount + */ public abstract async getFilledTakerAmountAsync(orderHash: string): Promise; + /** + * Whether an order is cancelled + * @param orderHash OrderHash of order we are interested in + * @return Whether or not the order is cancelled + */ public abstract async isOrderCancelledAsync(orderHash: string): Promise; public abstract getZRXAssetData(): string; } diff --git a/packages/order-utils/src/eip712_utils.ts b/packages/order-utils/src/eip712_utils.ts index 2594e6d6d..c7b20f824 100644 --- a/packages/order-utils/src/eip712_utils.ts +++ b/packages/order-utils/src/eip712_utils.ts @@ -40,15 +40,37 @@ export const EIP712Utils = { const messageBuff = crypto.solSHA3([EIP191_PREFIX, domainSeparatorHashBuffer, hashStruct]); return messageBuff; }, + /** + * Pad an address to 32 bytes + * @param address Address to pad + * @return padded address + */ pad32Address(address: string): Buffer { const addressBuffer = ethUtil.toBuffer(address); const addressPadded = EIP712Utils.pad32Buffer(addressBuffer); return addressPadded; }, + /** + * Pad an buffer to 32 bytes + * @param buffer Address to pad + * @return padded buffer + */ pad32Buffer(buffer: Buffer): Buffer { const bufferPadded = ethUtil.setLengthLeft(buffer, EIP712_VALUE_LENGTH); return bufferPadded; }, + /** + * Hash together a EIP712 schema with the corresponding data + * @param schema EIP712-compliant schema + * @param data Data the complies to the schema + * @return A buffer containing the SHA256 hash of the schema and encoded data + */ + structHash(schema: EIP712Schema, data: { [key: string]: any }): Buffer { + const encodedData = EIP712Utils._encodeData(schema, data); + const schemaHash = EIP712Utils.compileSchema(schema); + const hashBuffer = crypto.solSHA3([schemaHash, ...encodedData]); + return hashBuffer; + }, _getDomainSeparatorSchemaBuffer(): Buffer { return EIP712Utils.compileSchema(EIP712_DOMAIN_SCHEMA); }, @@ -84,10 +106,4 @@ export const EIP712Utils = { } return encodedValues; }, - structHash(schema: EIP712Schema, data: { [key: string]: any }): Buffer { - const encodedData = EIP712Utils._encodeData(schema, data); - const schemaHash = EIP712Utils.compileSchema(schema); - const hashBuffer = crypto.solSHA3([schemaHash, ...encodedData]); - return hashBuffer; - }, }; diff --git a/packages/order-utils/src/exchange_transfer_simulator.ts b/packages/order-utils/src/exchange_transfer_simulator.ts index c3a4f9c2a..81c849c64 100644 --- a/packages/order-utils/src/exchange_transfer_simulator.ts +++ b/packages/order-utils/src/exchange_transfer_simulator.ts @@ -33,6 +33,10 @@ const ERR_MSG_MAPPING = { }, }; +/** + * An exchange transfer simulator which simulates asset transfers exactly how the + * 0x exchange contract would do them. + */ export class ExchangeTransferSimulator { private readonly _store: AbstractBalanceAndProxyAllowanceLazyStore; private static _throwValidationError( @@ -43,6 +47,11 @@ export class ExchangeTransferSimulator { const errMsg = ERR_MSG_MAPPING[failureReason][tradeSide][transferType]; throw new Error(errMsg); } + /** + * Instantiate a ExchangeTransferSimulator + * @param store A class that implements AbstractBalanceAndProxyAllowanceLazyStore + * @return an instance of ExchangeTransferSimulator + */ constructor(store: AbstractBalanceAndProxyAllowanceLazyStore) { this._store = store; } diff --git a/packages/order-utils/src/order_state_utils.ts b/packages/order-utils/src/order_state_utils.ts index 189bf4180..cb08c5ae2 100644 --- a/packages/order-utils/src/order_state_utils.ts +++ b/packages/order-utils/src/order_state_utils.ts @@ -91,6 +91,14 @@ export class OrderStateUtils { throw new Error(ExchangeContractErrs.OrderFillRoundingError); } } + /** + * Instantiate OrderStateUtils + * @param balanceAndProxyAllowanceFetcher A class that is capable of fetching balances + * and proxyAllowances for Ethereum addresses. It must implement AbstractBalanceAndProxyAllowanceFetcher + * @param orderFilledCancelledFetcher A class that is capable of fetching whether an order + * is cancelled and how much of it has been filled. It must implement AbstractOrderFilledCancelledFetcher + * @return Instance of OrderStateUtils + */ constructor( balanceAndProxyAllowanceFetcher: AbstractBalanceAndProxyAllowanceFetcher, orderFilledCancelledFetcher: AbstractOrderFilledCancelledFetcher, @@ -98,6 +106,14 @@ export class OrderStateUtils { this._balanceAndProxyAllowanceFetcher = balanceAndProxyAllowanceFetcher; this._orderFilledCancelledFetcher = orderFilledCancelledFetcher; } + /** + * Get the orderState for an "open" order (i.e where takerAddress=NULL_ADDRESS) + * This method will only check the maker's balance/allowance to calculate the + * OrderState. + * @param signedOrder The order of interest + * @return State relevant to the signedOrder, as well as whether the signedOrder is "valid". + * Validity is defined as a non-zero amount of the order can still be filled. + */ public async getOpenOrderStateAsync(signedOrder: SignedOrder): Promise { const orderRelevantState = await this.getOpenOrderRelevantStateAsync(signedOrder); const orderHash = orderHashUtils.getOrderHashHex(signedOrder); @@ -127,6 +143,11 @@ export class OrderStateUtils { return orderState; } } + /** + * Get state relevant to an order (i.e makerBalance, makerAllowance, filledTakerAssetAmount, etc... + * @param signedOrder Order of interest + * @return An instance of OrderRelevantState + */ public async getOpenOrderRelevantStateAsync(signedOrder: SignedOrder): Promise { const isMaker = true; const sidedOrderRelevantState = await this._getSidedOrderRelevantStateAsync( @@ -149,6 +170,12 @@ export class OrderStateUtils { }; return orderRelevantState; } + /** + * Get the max amount of the supplied order's takerAmount that could still be filled + * @param signedOrder Order of interest + * @param takerAddress Hypothetical taker of the order + * @return fillableTakerAssetAmount + */ public async getMaxFillableTakerAssetAmountAsync( signedOrder: SignedOrder, takerAddress: string, @@ -181,32 +208,6 @@ export class OrderStateUtils { return fillableTakerAssetAmount; } - public async getMaxFillableTakerAssetAmountForFailingOrderAsync( - signedOrder: SignedOrder, - takerAddress: string, - ): Promise { - // Get min of taker balance & allowance - const takerAssetBalanceOfTaker = await this._balanceAndProxyAllowanceFetcher.getBalanceAsync( - signedOrder.takerAssetData, - takerAddress, - ); - const takerAssetAllowanceOfTaker = await this._balanceAndProxyAllowanceFetcher.getProxyAllowanceAsync( - signedOrder.takerAssetData, - takerAddress, - ); - const minTakerAssetAmount = BigNumber.min([takerAssetBalanceOfTaker, takerAssetAllowanceOfTaker]); - - // get remainingFillAmount - const orderHash = orderHashUtils.getOrderHashHex(signedOrder); - const filledTakerAssetAmount = await this._orderFilledCancelledFetcher.getFilledTakerAmountAsync(orderHash); - const remainingFillTakerAssetAmount = signedOrder.takerAssetAmount.minus(filledTakerAssetAmount); - - if (minTakerAssetAmount.gte(remainingFillTakerAssetAmount)) { - return remainingFillTakerAssetAmount; - } else { - return minTakerAssetAmount; - } - } private async _getSidedOrderRelevantStateAsync( isMakerSide: boolean, signedOrder: SignedOrder, diff --git a/packages/order-utils/src/order_validation_utils.ts b/packages/order-utils/src/order_validation_utils.ts index ccc6e653f..972e6f6d6 100644 --- a/packages/order-utils/src/order_validation_utils.ts +++ b/packages/order-utils/src/order_validation_utils.ts @@ -12,8 +12,18 @@ import { orderHashUtils } from './order_hash'; import { signatureUtils } from './signature_utils'; import { utils } from './utils'; +/** + * A utility class for validating orders + */ export class OrderValidationUtils { private readonly _orderFilledCancelledFetcher: AbstractOrderFilledCancelledFetcher; + /** + * A Typescript implementation mirroring the implementation of isRoundingError in the + * Exchange smart contract + * @param numerator Numerator value. When used to check an order, pass in `takerAssetFilledAmount` + * @param denominator Denominator value. When used to check an order, pass in `order.takerAssetAmount` + * @param target Target value. When used to check an order, pass in `order.makerAssetAmount` + */ public static isRoundingError(numerator: BigNumber, denominator: BigNumber, target: BigNumber): boolean { // Solidity's mulmod() in JS // Source: https://solidity.readthedocs.io/en/latest/units-and-global-variables.html#mathematical-and-cryptographic-functions @@ -31,6 +41,15 @@ export class OrderValidationUtils { const isError = errPercentageTimes1000000.gt(1000); return isError; } + /** + * Validate that the maker & taker have sufficient balances/allowances + * to fill the supplied order to the fillTakerAssetAmount amount + * @param exchangeTradeEmulator ExchangeTradeEmulator to use + * @param signedOrder SignedOrder to test + * @param fillTakerAssetAmount Amount of takerAsset to fill the signedOrder + * @param senderAddress Sender of the fillOrder tx + * @param zrxAssetData AssetData for the ZRX token + */ public static async validateFillOrderBalancesAllowancesThrowIfInvalidAsync( exchangeTradeEmulator: ExchangeTransferSimulator, signedOrder: SignedOrder, @@ -104,9 +123,22 @@ export class OrderValidationUtils { throw new Error(RevertReason.OrderUnfillable); } } + /** + * Instantiate OrderValidationUtils + * @param orderFilledCancelledFetcher A module that implements the AbstractOrderFilledCancelledFetcher + * @return An instance of OrderValidationUtils + */ constructor(orderFilledCancelledFetcher: AbstractOrderFilledCancelledFetcher) { this._orderFilledCancelledFetcher = orderFilledCancelledFetcher; } + /** + * Validate if the supplied order is fillable, and throw if it isn't + * @param exchangeTradeEmulator ExchangeTradeEmulator instance + * @param signedOrder SignedOrder of interest + * @param zrxAssetData ZRX assetData + * @param expectedFillTakerTokenAmount If supplied, this call will make sure this amount is fillable. + * If it isn't supplied, we check if the order is fillable for a non-zero amount + */ public async validateOrderFillableOrThrowAsync( exchangeTradeEmulator: ExchangeTransferSimulator, signedOrder: SignedOrder, @@ -132,6 +164,15 @@ export class OrderValidationUtils { zrxAssetData, ); } + /** + * Validate a call to FillOrder and throw if it wouldn't succeed + * @param exchangeTradeEmulator ExchangeTradeEmulator to use + * @param provider Web3 provider to use for JSON RPC requests + * @param signedOrder SignedOrder of interest + * @param fillTakerAssetAmount Amount we'd like to fill the order for + * @param takerAddress The taker of the order + * @param zrxAssetData ZRX asset data + */ public async validateFillOrderThrowIfInvalidAsync( exchangeTradeEmulator: ExchangeTransferSimulator, provider: Provider, @@ -187,6 +228,15 @@ export class OrderValidationUtils { } return filledTakerTokenAmount; } + /** + * Validate a call to fillOrKillOrder and throw if it would fail + * @param exchangeTradeEmulator ExchangeTradeEmulator to use + * @param provider Web3 provider to use for JSON RPC requests + * @param signedOrder SignedOrder of interest + * @param fillTakerAssetAmount Amount we'd like to fill the order for + * @param takerAddress The taker of the order + * @param zrxAssetData ZRX asset data + */ public async validateFillOrKillOrderThrowIfInvalidAsync( exchangeTradeEmulator: ExchangeTransferSimulator, provider: Provider, diff --git a/packages/order-utils/src/store/balance_and_proxy_allowance_lazy_store.ts b/packages/order-utils/src/store/balance_and_proxy_allowance_lazy_store.ts index 5a2c1d7ff..8a65178b0 100644 --- a/packages/order-utils/src/store/balance_and_proxy_allowance_lazy_store.ts +++ b/packages/order-utils/src/store/balance_and_proxy_allowance_lazy_store.ts @@ -21,11 +21,21 @@ export class BalanceAndProxyAllowanceLazyStore implements AbstractBalanceAndProx [userAddress: string]: BigNumber; }; }; + /** + * Instantiates a BalanceAndProxyAllowanceLazyStore + * @param balanceAndProxyAllowanceFetcher Class the implements the AbstractBalanceAndProxyAllowanceFetcher + * @return Instance of BalanceAndProxyAllowanceLazyStore + */ constructor(balanceAndProxyAllowanceFetcher: AbstractBalanceAndProxyAllowanceFetcher) { this._balanceAndProxyAllowanceFetcher = balanceAndProxyAllowanceFetcher; this._balance = {}; this._proxyAllowance = {}; } + /** + * Get a users balance of an asset + * @param assetData AssetData of interest + * @param userAddress Ethereum address of interest + */ public async getBalanceAsync(assetData: string, userAddress: string): Promise { if (_.isUndefined(this._balance[assetData]) || _.isUndefined(this._balance[assetData][userAddress])) { const balance = await this._balanceAndProxyAllowanceFetcher.getBalanceAsync(assetData, userAddress); @@ -34,12 +44,22 @@ export class BalanceAndProxyAllowanceLazyStore implements AbstractBalanceAndProx const cachedBalance = this._balance[assetData][userAddress]; return cachedBalance; } + /** + * Set the balance of an asset for a user + * @param assetData AssetData of interest + * @param userAddress Ethereum address of interest + */ public setBalance(assetData: string, userAddress: string, balance: BigNumber): void { if (_.isUndefined(this._balance[assetData])) { this._balance[assetData] = {}; } this._balance[assetData][userAddress] = balance; } + /** + * Clear the balance of an asset for a user + * @param assetData AssetData of interest + * @param userAddress Ethereum address of interest + */ public deleteBalance(assetData: string, userAddress: string): void { if (!_.isUndefined(this._balance[assetData])) { delete this._balance[assetData][userAddress]; @@ -48,6 +68,11 @@ export class BalanceAndProxyAllowanceLazyStore implements AbstractBalanceAndProx } } } + /** + * Get the 0x asset proxy allowance + * @param assetData AssetData of interest + * @param userAddress Ethereum address of interest + */ public async getProxyAllowanceAsync(assetData: string, userAddress: string): Promise { if ( _.isUndefined(this._proxyAllowance[assetData]) || @@ -62,12 +87,22 @@ export class BalanceAndProxyAllowanceLazyStore implements AbstractBalanceAndProx const cachedProxyAllowance = this._proxyAllowance[assetData][userAddress]; return cachedProxyAllowance; } + /** + * Set the 0x asset proxy allowance + * @param assetData AssetData of interest + * @param userAddress Ethereum address of interest + */ public setProxyAllowance(assetData: string, userAddress: string, proxyAllowance: BigNumber): void { if (_.isUndefined(this._proxyAllowance[assetData])) { this._proxyAllowance[assetData] = {}; } this._proxyAllowance[assetData][userAddress] = proxyAllowance; } + /** + * Clear the 0x asset proxy allowance + * @param assetData AssetData of interest + * @param userAddress Ethereum address of interest + */ public deleteProxyAllowance(assetData: string, userAddress: string): void { if (!_.isUndefined(this._proxyAllowance[assetData])) { delete this._proxyAllowance[assetData][userAddress]; @@ -76,6 +111,11 @@ export class BalanceAndProxyAllowanceLazyStore implements AbstractBalanceAndProx } } } + /** + * Clear all ERC721 0x proxy allowances a user has on all items of a specific ERC721 contract + * @param tokenAddress ERc721 token address + * @param userAddress Owner Ethereum address + */ public deleteAllERC721ProxyAllowance(tokenAddress: string, userAddress: string): void { for (const assetData in this._proxyAllowance) { if (this._proxyAllowance.hasOwnProperty(assetData)) { @@ -90,6 +130,9 @@ export class BalanceAndProxyAllowanceLazyStore implements AbstractBalanceAndProx } } } + /** + * Delete all balances & allowances + */ public deleteAll(): void { this._balance = {}; this._proxyAllowance = {}; diff --git a/packages/order-utils/src/store/order_filled_cancelled_lazy_store.ts b/packages/order-utils/src/store/order_filled_cancelled_lazy_store.ts index 336c6d0ba..6155c2064 100644 --- a/packages/order-utils/src/store/order_filled_cancelled_lazy_store.ts +++ b/packages/order-utils/src/store/order_filled_cancelled_lazy_store.ts @@ -15,11 +15,21 @@ export class OrderFilledCancelledLazyStore implements AbstractOrderFilledCancell private _isCancelled: { [orderHash: string]: boolean; }; + /** + * Instantiate a OrderFilledCancelledLazyStore + * @param orderFilledCancelledFetcher Class instance that implements the AbstractOrderFilledCancelledFetcher + * @returns An instance of OrderFilledCancelledLazyStore + */ constructor(orderFilledCancelledFetcher: AbstractOrderFilledCancelledFetcher) { this._orderFilledCancelledFetcher = orderFilledCancelledFetcher; this._filledTakerAmount = {}; this._isCancelled = {}; } + /** + * Get the filledTakerAssetAmount of an order + * @param orderHash OrderHash from order of interest + * @return filledTakerAssetAmount + */ public async getFilledTakerAmountAsync(orderHash: string): Promise { if (_.isUndefined(this._filledTakerAmount[orderHash])) { const filledTakerAmount = await this._orderFilledCancelledFetcher.getFilledTakerAmountAsync(orderHash); @@ -28,12 +38,26 @@ export class OrderFilledCancelledLazyStore implements AbstractOrderFilledCancell const cachedFilledTakerAmount = this._filledTakerAmount[orderHash]; return cachedFilledTakerAmount; } + /** + * Set the filledTakerAssetAmount of an order + * @param orderHash OrderHash from order of interest + * @param filledTakerAmount Desired filledTakerAssetAmount + */ public setFilledTakerAmount(orderHash: string, filledTakerAmount: BigNumber): void { this._filledTakerAmount[orderHash] = filledTakerAmount; } + /** + * Clear the filledTakerAssetAmount of an order + * @param orderHash OrderHash from order of interest + */ public deleteFilledTakerAmount(orderHash: string): void { delete this._filledTakerAmount[orderHash]; } + /** + * Check if an order has been cancelled + * @param orderHash OrderHash from order of interest + * @return Whether the order has been cancelled + */ public async getIsCancelledAsync(orderHash: string): Promise { if (_.isUndefined(this._isCancelled[orderHash])) { const isCancelled = await this._orderFilledCancelledFetcher.isOrderCancelledAsync(orderHash); @@ -42,22 +66,43 @@ export class OrderFilledCancelledLazyStore implements AbstractOrderFilledCancell const cachedIsCancelled = this._isCancelled[orderHash]; // tslint:disable-line:boolean-naming return cachedIsCancelled; } + /** + * Set whether an order has been cancelled or not + * @param orderHash OrderHash from order of interest + * @param isCancelled Whether this order should be cancelled or not + */ public setIsCancelled(orderHash: string, isCancelled: boolean): void { this._isCancelled[orderHash] = isCancelled; } + /** + * Clear whether the order has been cancelled if already set + * @param orderHash OrderHash from order of interest + */ public deleteIsCancelled(orderHash: string): void { delete this._isCancelled[orderHash]; } + /** + * Clear all filled/cancelled state + */ public deleteAll(): void { this.deleteAllFilled(); this.deleteAllIsCancelled(); } + /** + * Clear all cancelled state + */ public deleteAllIsCancelled(): void { this._isCancelled = {}; } + /** + * Clear all filled state + */ public deleteAllFilled(): void { this._filledTakerAmount = {}; } + /** + * Get the ZRX assetData + */ public getZRXAssetData(): string { const zrxAssetData = this._orderFilledCancelledFetcher.getZRXAssetData(); return zrxAssetData; -- cgit