diff options
author | Leonid <logvinov.leon@gmail.com> | 2017-06-10 21:08:26 +0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-06-10 21:08:26 +0800 |
commit | 88de98080cda4933ed8b15246c59891aa182d31e (patch) | |
tree | 96293ee6e3970cb948abee2b52ae8a49b8454ce6 /src | |
parent | 10e8e89fee0cb36e2c5c06255cb65e2b8b9eced8 (diff) | |
parent | 4c812c99c2d55dcae6c2ac5d0547ebcafc8521be (diff) | |
download | dexon-0x-contracts-88de98080cda4933ed8b15246c59891aa182d31e.tar dexon-0x-contracts-88de98080cda4933ed8b15246c59891aa182d31e.tar.gz dexon-0x-contracts-88de98080cda4933ed8b15246c59891aa182d31e.tar.bz2 dexon-0x-contracts-88de98080cda4933ed8b15246c59891aa182d31e.tar.lz dexon-0x-contracts-88de98080cda4933ed8b15246c59891aa182d31e.tar.xz dexon-0x-contracts-88de98080cda4933ed8b15246c59891aa182d31e.tar.zst dexon-0x-contracts-88de98080cda4933ed8b15246c59891aa182d31e.zip |
Merge branch 'master' into error-decorator
Diffstat (limited to 'src')
-rw-r--r-- | src/0x.js.ts | 58 | ||||
-rw-r--r-- | src/contract_wrappers/exchange_wrapper.ts | 72 | ||||
-rw-r--r-- | src/contract_wrappers/token_registry_wrapper.ts | 4 | ||||
-rw-r--r-- | src/contract_wrappers/token_wrapper.ts | 29 |
4 files changed, 139 insertions, 24 deletions
diff --git a/src/0x.js.ts b/src/0x.js.ts index 143ad8e1f..b1e4e25ff 100644 --- a/src/0x.js.ts +++ b/src/0x.js.ts @@ -23,6 +23,11 @@ import {orderSchema} from './schemas/order_schemas'; bigNumberConfigs.configure(); export class ZeroEx { + /** + * When creating an order without a specified taker or feeRecipient you must supply the Solidity + * address null type (as opposed to Javascripts `null`, `undefined` or empty string). We expose + * this constant for your convenience. + */ public static NULL_ADDRESS = constants.NULL_ADDRESS; public exchange: ExchangeWrapper; @@ -32,6 +37,10 @@ export class ZeroEx { /** * Verifies that the elliptic curve signature `signature` was generated * by signing `dataHex` with the private key corresponding to the `signerAddressHex` address. + * @param dataHex The hex encoded data signed by the supplied signature. + * @param signature A JS object containing the elliptic curve signature parameters. + * @param signerAddressHex The hex encoded address that signed the dataHex, producing the supplied signature. + * @return Whether the signature is valid for the supplied signerAddressHex and dataHex. */ public static isValidSignature(dataHex: string, signature: ECSignature, signerAddressHex: string): boolean { assert.isHexString('dataHex', dataHex); @@ -53,9 +62,10 @@ export class ZeroEx { } } /** - * Generates pseudo-random 256 bit salt. - * The salt is used to ensure that the 0x order generated has a unique orderHash that does - * not collide with any other outstanding orders. + * Generates a pseudo-random 256-bit salt. + * The salt can be included in an 0x order, ensuring that the order generates a unique orderHash + * and will not collide with other outstanding orders that are identical in all other parameters. + * @return A pseudo-random 256-bit number that can be used as a salt. */ public static generatePseudoRandomSalt(): BigNumber.BigNumber { // BigNumber.random returns a pseudo-random number between 0 & 1 with a passed in number of decimal places. @@ -68,6 +78,9 @@ export class ZeroEx { /** * Checks if the supplied hex encoded order hash is valid. * Note: Valid means it has the expected format, not that an order with the orderHash exists. + * Use this method when processing orderHashes submitted as user input. + * @param orderHashHex Hex encoded orderHash. + * @return Whether the supplied orderHashHex has the expected format. */ public static isValidOrderHash(orderHashHex: string): boolean { // Since this method can be called to check if any arbitrary string conforms to an orderHash's @@ -80,12 +93,15 @@ export class ZeroEx { * A unit amount is defined as the amount of a token above the specified decimal places (integer part). * E.g: If a currency has 18 decimal places, 1e18 or one quintillion of the currency is equivalent * to 1 unit. + * @param amount The amount in baseUnits that you would like converted to units. + * @param decimals The number of decimal places the unit amount has. + * @return The amount in units. */ - public static toUnitAmount(amount: BigNumber.BigNumber, numDecimals: number): BigNumber.BigNumber { + public static toUnitAmount(amount: BigNumber.BigNumber, decimals: number): BigNumber.BigNumber { assert.isBigNumber('amount', amount); - assert.isNumber('numDecimals', numDecimals); + assert.isNumber('decimals', decimals); - const aUnit = new BigNumber(10).pow(numDecimals); + const aUnit = new BigNumber(10).pow(decimals); const unit = amount.div(aUnit); return unit; } @@ -93,15 +109,24 @@ export class ZeroEx { * A baseUnit is defined as the smallest denomination of a token. An amount expressed in baseUnits * is the amount expressed in the smallest denomination. * E.g: 1 unit of a token with 18 decimal places is expressed in baseUnits as 1000000000000000000 + * @param amount The amount of units that you would like converted to baseUnits. + * @param decimals The number of decimal places the unit amount has. + * @return The amount in baseUnits. */ - public static toBaseUnitAmount(amount: BigNumber.BigNumber, numDecimals: number): BigNumber.BigNumber { + public static toBaseUnitAmount(amount: BigNumber.BigNumber, decimals: number): BigNumber.BigNumber { assert.isBigNumber('amount', amount); - assert.isNumber('numDecimals', numDecimals); + assert.isNumber('decimals', decimals); - const unit = new BigNumber(10).pow(numDecimals); + const unit = new BigNumber(10).pow(decimals); const baseUnitAmount = amount.times(unit); return baseUnitAmount; } + /** + * Instantiates a new ZeroEx instance that provides the public interface to the 0x.js library. + * @param web3 The Web3.js instance you would like the 0x.js library to use for interacting with + * the Ethereum network. + * @return An instance of the 0x.js ZeroEx class. + */ constructor(web3: Web3) { this.web3Wrapper = new Web3Wrapper(web3); this.token = new TokenWrapper(this.web3Wrapper); @@ -109,7 +134,9 @@ export class ZeroEx { this.tokenRegistry = new TokenRegistryWrapper(this.web3Wrapper); } /** - * Sets a new provider for the web3 instance used by 0x.js + * Sets a new provider for the web3 instance used by 0x.js. Updating the provider will stop all + * subscriptions so you will need to re-subscribe to all events relevant to your app after this call. + * @param provider The Web3.Provider you would like the 0x.js library to use from now on. */ public async setProviderAsync(provider: Web3.Provider) { this.web3Wrapper.setProvider(provider); @@ -118,14 +145,17 @@ export class ZeroEx { this.token.invalidateContractInstances(); } /** - * Get addresses via the supplied web3 instance available for sending transactions. + * Get addresses available throught the supplied web3 instance available for sending transactions. + * @return An array of Ethereum addresses available. */ public async getAvailableAddressesAsync(): Promise<string[]> { const availableAddresses = await this.web3Wrapper.getAvailableAddressesAsync(); return availableAddresses; } /** - * Computes the orderHash for a given order and returns it as a hex encoded string. + * Computes the orderHash for a supplied order. + * @param order A JS object that conforms to the Order or SignedOrder interface definitions. + * @return The resulting orderHash from hashing the supplied order. */ public async getOrderHashHexAsync(order: Order|SignedOrder): Promise<string> { assert.doesConformToSchema('order', order, orderSchema); @@ -137,6 +167,10 @@ export class ZeroEx { /** * Signs an orderHash and returns it's elliptic curve signature. * This method currently supports TestRPC, Geth and Parity above and below V1.6.6 + * @param orderHashHex Hex encoded orderHash to sign. + * @param signerAddress The hex encoded Ethereum address you wish to sign it with. This address + * must be available via the Web3.Provider supplied to 0x.js. + * @return A JS object containing the Elliptic curve signature parameters generated by signing the orderHashHex. */ public async signOrderHashAsync(orderHashHex: string, signerAddress: string): Promise<ECSignature> { assert.isHexString('orderHashHex', orderHashHex); diff --git a/src/contract_wrappers/exchange_wrapper.ts b/src/contract_wrappers/exchange_wrapper.ts index b03e55d8c..e3044042e 100644 --- a/src/contract_wrappers/exchange_wrapper.ts +++ b/src/contract_wrappers/exchange_wrapper.ts @@ -80,6 +80,9 @@ export class ExchangeWrapper extends ContractWrapper { * Returns the unavailable takerAmount of an order. Unavailable amount is defined as the total * amount that has been filled or cancelled. The remaining takerAmount can be calculated by * subtracting the unavailable amount from the total order takerAmount. + * @param orderHashHex The hex encoded orderHash for which you would like to retrieve the + * unavailable takerAmount. + * @return The amount of the order (in taker tokens) that has either been filled or canceled. */ public async getUnavailableTakerAmountAsync(orderHashHex: string): Promise<BigNumber.BigNumber> { assert.isValidOrderHash('orderHashHex', orderHashHex); @@ -92,6 +95,8 @@ export class ExchangeWrapper extends ContractWrapper { } /** * Retrieve the takerAmount of an order that has already been filled. + * @param orderHashHex The hex encoded orderHash for which you would like to retrieve the filled takerAmount. + * @return The amount of the order (in taker tokens) that has already been filled. */ public async getFilledTakerAmountAsync(orderHashHex: string): Promise<BigNumber.BigNumber> { assert.isValidOrderHash('orderHashHex', orderHashHex); @@ -104,6 +109,9 @@ export class ExchangeWrapper extends ContractWrapper { } /** * Retrieve the takerAmount of an order that has been cancelled. + * @param orderHashHex The hex encoded orderHash for which you would like to retrieve the + * cancelled takerAmount. + * @return The amount of the order (in taker tokens) that has been cancelled. */ public async getCanceledTakerAmountAsync(orderHashHex: string): Promise<BigNumber.BigNumber> { assert.isValidOrderHash('orderHashHex', orderHashHex); @@ -120,7 +128,13 @@ export class ExchangeWrapper extends ContractWrapper { * could arise where a users balance or allowance changes before the fillOrder executes. Because of this, * we allow you to specify `shouldCheckTransfer`. If true, the smart contract will not throw if while * executing, the parties do not have sufficient balances/allowances, preserving gas costs. Setting it to - * false forgoes this check and causes the smart contract to throw instead. + * false forgoes this check and causes the smart contract to throw (using all the gas supplied) instead. + * @param signedOrder A JS object that conforms to the SignedOrder interface. + * @param takerTokenFillAmount The amount of the order (in taker tokens baseUnits) that you wish to fill. + * @param shouldCheckTransfer Whether or not you wish for the contract call to throw if upon + * execution the tokens cannot be transferred. + * @param takerAddress The user Ethereum address who would like to fill this order. + * Must be available via the supplied Web3.Provider passed to 0x.js. */ @decorators.contractCallErrorHandler public async fillOrderAsync(signedOrder: SignedOrder, takerTokenFillAmount: BigNumber.BigNumber, @@ -166,6 +180,15 @@ export class ExchangeWrapper extends ContractWrapper { * Sequentially and atomically fills signedOrders up to the specified takerTokenFillAmount. * If the fill amount is reached - it succeeds and does not fill the rest of the orders. * If fill amount is not reached - it fills as much of the fill amount as possible and succeeds. + * @param signedOrders The array of signedOrders that you would like to fill until + * takerTokenFillAmount is reached. + * @param takerTokenFillAmount The total amount of the takerTokens you would like to fill. + * @param shouldCheckTransfer Whether or not you wish for the contract call to throw if upon + * execution any of the tokens cannot be transferred. If set to false, + * the call will continue to fill subsequent signedOrders even when + * some cannot be filled. + * @param takerAddress The user Ethereum address who would like to fill these orders. + * Must be available via the supplied Web3.Provider passed to 0x.js. */ @decorators.contractCallErrorHandler public async fillOrdersUpToAsync(signedOrders: SignedOrder[], takerTokenFillAmount: BigNumber.BigNumber, @@ -231,6 +254,13 @@ export class ExchangeWrapper extends ContractWrapper { * Executes multiple fills atomically in a single transaction. * If shouldCheckTransfer is set to true, it will continue filling subsequent orders even when earlier ones fail. * When shouldCheckTransfer is set to false, if any fill fails, the entire batch fails. + * @param orderFillRequests An array of JS objects that conform to the OrderFillRequest interface. + * @param shouldCheckTransfer Whether or not you wish for the contract call to throw if upon + * execution any of the tokens cannot be transferred. If set to false, + * the call will continue to fill subsequent signedOrders even when some + * cannot be filled. + * @param takerAddress The user Ethereum address who would like to fill these orders. + * Must be available via the supplied Web3.Provider passed to 0x.js. */ @decorators.contractCallErrorHandler public async batchFillOrderAsync(orderFillRequests: OrderFillRequest[], @@ -291,26 +321,31 @@ export class ExchangeWrapper extends ContractWrapper { /** * Attempts to fill a specific amount of an order. If the entire amount specified cannot be filled, * the fill order is abandoned. + * @param signedOrder A JS object that conforms to the SignedOrder interface. The + * signedOrder you wish to fill. + * @param takerTokenFillAmount The total amount of the takerTokens you would like to fill. + * @param takerAddress The user Ethereum address who would like to fill this order. + * Must be available via the supplied Web3.Provider passed to 0x.js. */ @decorators.contractCallErrorHandler - public async fillOrKillOrderAsync(signedOrder: SignedOrder, fillTakerAmount: BigNumber.BigNumber, - takerAddress: string) { + public async fillOrKillOrderAsync(signedOrder: SignedOrder, takerTokenFillAmount: BigNumber.BigNumber, + takerAddress: string): Promise<void> { assert.doesConformToSchema('signedOrder', signedOrder, signedOrderSchema); - assert.isBigNumber('fillTakerAmount', fillTakerAmount); + assert.isBigNumber('takerTokenFillAmount', takerTokenFillAmount); await assert.isSenderAddressAsync('takerAddress', takerAddress, this.web3Wrapper); const exchangeInstance = await this.getExchangeContractAsync(); - await this.validateFillOrderAndThrowIfInvalidAsync(signedOrder, fillTakerAmount, takerAddress); + await this.validateFillOrderAndThrowIfInvalidAsync(signedOrder, takerTokenFillAmount, takerAddress); await this.validateFillOrKillOrderAndThrowIfInvalidAsync(signedOrder, exchangeInstance.address, - fillTakerAmount); + takerTokenFillAmount); const [orderAddresses, orderValues] = ExchangeWrapper.getOrderAddressesAndValues(signedOrder); const gas = await exchangeInstance.fillOrKill.estimateGas( orderAddresses, orderValues, - fillTakerAmount, + takerTokenFillAmount, signedOrder.ecSignature.v, signedOrder.ecSignature.r, signedOrder.ecSignature.s, @@ -321,7 +356,7 @@ export class ExchangeWrapper extends ContractWrapper { const response: ContractResponse = await exchangeInstance.fillOrKill( orderAddresses, orderValues, - fillTakerAmount, + takerTokenFillAmount, signedOrder.ecSignature.v, signedOrder.ecSignature.r, signedOrder.ecSignature.s, @@ -335,10 +370,13 @@ export class ExchangeWrapper extends ContractWrapper { /** * Batch version of fillOrKill. Allows a taker to specify a batch of orders that will either be atomically * filled (each to the specified fillAmount) or aborted. + * @param orderFillOrKillRequests An array of JS objects that conform to the OrderFillOrKillRequest interface. + * @param takerAddress The user Ethereum address who would like to fill there orders. + * Must be available via the supplied Web3.Provider passed to 0x.js. */ @decorators.contractCallErrorHandler public async batchFillOrKillAsync(orderFillOrKillRequests: OrderFillOrKillRequest[], - takerAddress: string) { + takerAddress: string): Promise<void> { await assert.isSenderAddressAsync('takerAddress', takerAddress, this.web3Wrapper); assert.doesConformToSchema('orderFillOrKillRequests', orderFillOrKillRequests, orderFillOrKillRequestsSchema); const exchangeInstance = await this.getExchangeContractAsync(); @@ -388,6 +426,9 @@ export class ExchangeWrapper extends ContractWrapper { } /** * Cancel a given fill amount of an order. Cancellations are cumulative. + * @param order A JS object that conforms to the Order or SignedOrder interface. + * The order you would like to cancel. + * @param takerTokenCancelAmount The amount (specified in taker tokens) that you would like to cancel. */ @decorators.contractCallErrorHandler public async cancelOrderAsync( @@ -422,6 +463,8 @@ export class ExchangeWrapper extends ContractWrapper { /** * Batch version of cancelOrderAsync. Atomically cancels multiple orders in a single transaction. * All orders must be from the same maker. + * @param orderCancellationRequests An array of JS objects that conform to the OrderCancellationRequest + * interface. */ @decorators.contractCallErrorHandler public async batchCancelOrderAsync(orderCancellationRequests: OrderCancellationRequest[]): Promise<void> { @@ -429,7 +472,8 @@ export class ExchangeWrapper extends ContractWrapper { assert.hasAtMostOneUniqueValue(makers, ExchangeContractErrs.MULTIPLE_MAKERS_IN_SINGLE_CANCEL_BATCH_DISALLOWED); const maker = makers[0]; await assert.isSenderAddressAsync('maker', maker, this.web3Wrapper); - assert.doesConformToSchema('orderCancellationRequests', orderCancellationRequests, orderCancellationRequestsSchema); + assert.doesConformToSchema('orderCancellationRequests', orderCancellationRequests, + orderCancellationRequestsSchema); for (const cancellationRequest of orderCancellationRequests) { await this.validateCancelOrderAndThrowIfInvalidAsync( cancellationRequest.order, cancellationRequest.takerTokenCancelAmount, @@ -469,9 +513,15 @@ export class ExchangeWrapper extends ContractWrapper { } /** * Subscribe to an event type emitted by the Exchange smart contract + * @param eventName The exchange contract event you would like to subscribe to. + * @param subscriptionOpts Subscriptions options that let you configure the subscription. + * @param indexFilterValues A JS object where the keys are indexed args returned by the event and + * the value is the value you are interested in. E.g `{maker: aUserAddressHex}` + * @param callback The callback that will be called everytime a matching event is found. */ public async subscribeAsync(eventName: ExchangeEvents, subscriptionOpts: SubscriptionOpts, - indexFilterValues: IndexFilterValues, callback: EventCallback) { + indexFilterValues: IndexFilterValues, callback: EventCallback): + Promise<void> { const exchangeContract = await this.getExchangeContractAsync(); let createLogEvent: CreateContractEvent; switch (eventName) { diff --git a/src/contract_wrappers/token_registry_wrapper.ts b/src/contract_wrappers/token_registry_wrapper.ts index 86bea1c5d..96346a7a4 100644 --- a/src/contract_wrappers/token_registry_wrapper.ts +++ b/src/contract_wrappers/token_registry_wrapper.ts @@ -13,6 +13,10 @@ export class TokenRegistryWrapper extends ContractWrapper { public invalidateContractInstance(): void { delete this.tokenRegistryContractIfExists; } + /** + * Retrieves all the tokens currently listed in the Token Registry smart contract + * @return An array of JS objects that conform to the Token interface. + */ public async getTokensAsync(): Promise<Token[]> { const tokenRegistryContract = await this.getTokenRegistryContractAsync(); diff --git a/src/contract_wrappers/token_wrapper.ts b/src/contract_wrappers/token_wrapper.ts index 4412b1299..bb79cac47 100644 --- a/src/contract_wrappers/token_wrapper.ts +++ b/src/contract_wrappers/token_wrapper.ts @@ -20,7 +20,9 @@ export class TokenWrapper extends ContractWrapper { this.tokenContractsByAddress = {}; } /** - * Returns an owner's ERC20 token balance. + * Retrieves an owner's ERC20 token balance. + * @param tokenAddress The hex encoded contract Ethereum address where the ERC20 token is deployed. + * @param ownerAddress The hex encoded user Ethereum address whose balance you would like to check. */ public async getBalanceAsync(tokenAddress: string, ownerAddress: string): Promise<BigNumber.BigNumber> { assert.isETHAddressHex('ownerAddress', ownerAddress); @@ -36,6 +38,11 @@ export class TokenWrapper extends ContractWrapper { /** * Sets the spender's allowance to a specified number of baseUnits on behalf of the owner address. * Equivalent to the ERC20 spec method `approve`. + * @param tokenAddress The hex encoded contract Ethereum address where the ERC20 token is deployed. + * @param ownerAddress The hex encoded user Ethereum address who would like to set an allowance + * for spenderAddress. + * @param spenderAddress The hex encoded user Ethereum address who will be able to spend the set allowance. + * @param amountInBaseUnits The allowance amount you would like to set. */ public async setAllowanceAsync(tokenAddress: string, ownerAddress: string, spenderAddress: string, amountInBaseUnits: BigNumber.BigNumber): Promise<void> { @@ -57,6 +64,10 @@ export class TokenWrapper extends ContractWrapper { } /** * Retrieves the owners allowance in baseUnits set to the spender's address. + * @param tokenAddress The hex encoded contract Ethereum address where the ERC20 token is deployed. + * @param ownerAddress The hex encoded user Ethereum address whose allowance to spenderAddress + * you would like to retrieve. + * @param spenderAddress The hex encoded user Ethereum address who can spend the allowance you are fetching. */ public async getAllowanceAsync(tokenAddress: string, ownerAddress: string, spenderAddress: string) { assert.isETHAddressHex('ownerAddress', ownerAddress); @@ -71,6 +82,8 @@ export class TokenWrapper extends ContractWrapper { } /** * Retrieves the owner's allowance in baseUnits set to the 0x proxy contract. + * @param tokenAddress The hex encoded contract Ethereum address where the ERC20 token is deployed. + * @param ownerAddress The hex encoded user Ethereum address whose proxy contract allowance we are retrieving. */ public async getProxyAllowanceAsync(tokenAddress: string, ownerAddress: string) { assert.isETHAddressHex('ownerAddress', ownerAddress); @@ -83,6 +96,10 @@ export class TokenWrapper extends ContractWrapper { /** * Sets the 0x proxy contract's allowance to a specified number of a tokens' baseUnits on behalf * of an owner address. + * @param tokenAddress The hex encoded contract Ethereum address where the ERC20 token is deployed. + * @param ownerAddress The hex encoded user Ethereum address who is setting an allowance + * for the Proxy contract. + * @param amountInBaseUnits The allowance amount specified in baseUnits. */ public async setProxyAllowanceAsync(tokenAddress: string, ownerAddress: string, amountInBaseUnits: BigNumber.BigNumber): Promise<void> { @@ -95,6 +112,10 @@ export class TokenWrapper extends ContractWrapper { } /** * Transfers `amountInBaseUnits` ERC20 tokens from `fromAddress` to `toAddress`. + * @param tokenAddress The hex encoded contract Ethereum address where the ERC20 token is deployed. + * @param fromAddress The hex encoded user Ethereum address that will send the funds. + * @param toAddress The hex encoded user Ethereum address that will receive the funds. + * @param amountInBaseUnits The amount (specified in baseUnits) of the token to transfer. */ public async transferAsync(tokenAddress: string, fromAddress: string, toAddress: string, amountInBaseUnits: BigNumber.BigNumber): Promise<void> { @@ -118,6 +139,12 @@ export class TokenWrapper extends ContractWrapper { * Transfers `amountInBaseUnits` ERC20 tokens from `fromAddress` to `toAddress`. * Requires the fromAddress to have sufficient funds and to have approved an allowance of * `amountInBaseUnits` for senderAddress. + * @param tokenAddress The hex encoded contract Ethereum address where the ERC20 token is deployed. + * @param fromAddress The hex encoded user Ethereum address that will send the funds. + * @param toAddress The hex encoded user Ethereum address that will receive the funds. + * @param senderAddress The hex encoded user Ethereum address whose funds are being sent. The senderAddress + * must have set an allowance to the fromAddress before this call. + * @param amountInBaseUnits The amount (specified in baseUnits) of the token to transfer. */ public async transferFromAsync(tokenAddress: string, fromAddress: string, toAddress: string, senderAddress: string, amountInBaseUnits: BigNumber.BigNumber): |