crowetic/protocol
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add and improve comments

Browse Source
This commit is contained in:
Fabio Berger 2017-06-16 16:30:35 +02:00
parent 225ec50645
commit fe63a81f6a
4 changed files with 43 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
src/0x.ts
View File

@ -22,6 +22,10 @@ import {orderSchema} from './schemas/order_schemas';
// Customize our BigNumber instances
bigNumberConfigs.configure();
/**
* The ZeroEx class is the single entry-point into the 0x.js library. It contains all of the library's functionality
* and all calls to the library should be made through a ZeroEx instance.
*/
export class ZeroEx {
/**
* When creating an order without a specified taker or feeRecipient you must supply the Solidity
@ -30,15 +34,24 @@ export class ZeroEx {
*/
public static NULL_ADDRESS = constants.NULL_ADDRESS;
/**
* An instance of the ExchangeWrapper class containing methods for interacting with the 0x Exchange smart contract.
*/
public exchange: ExchangeWrapper;
/**
* An instance of the TokenRegistryWrapper class containing methods for interacting with the 0x TokenRegistry smart contract.
*/
public tokenRegistry: TokenRegistryWrapper;
/**
* An instance of the TokenWrapper class containing methods for interacting with any ERC20 token smart contract.
*/
public token: TokenWrapper;
private _web3Wrapper: Web3Wrapper;
/**
* Verifies that the elliptic curve signature `signature` was generated
* by signing `data` with the private key corresponding to the `signerAddress` address.
* @param data The hex encoded data signed by the supplied signature.
* @param signature A JS object containing the elliptic curve signature parameters.
* @param signature An object containing the elliptic curve signature parameters.
* @param signerAddress The hex encoded address that signed the data, producing the supplied signature.
* @return Whether the signature is valid for the supplied signerAddress and data.
*/
@ -145,8 +158,8 @@ export class ZeroEx {
this.token.invalidateContractInstances();
}
/**
* Get addresses available throught the supplied web3 instance available for sending transactions.
* @return An array of Ethereum addresses available.
* Get user Ethereum addresses available through the supplied web3 instance available for sending transactions.
* @return An array of available user Ethereum addresses.
*/
public async getAvailableAddressesAsync(): Promise<string[]> {
const availableAddresses = await this._web3Wrapper.getAvailableAddressesAsync();
@ -154,7 +167,7 @@ export class ZeroEx {
}
/**
* Computes the orderHash for a supplied order.
* @param order A JS object that conforms to the Order or SignedOrder interface definitions.
* @param order An 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> {
@ -170,7 +183,7 @@ export class ZeroEx {
* @param orderHash 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 orderHash.
* @return An object containing the Elliptic curve signature parameters generated by signing the orderHash.
*/
public async signOrderHashAsync(orderHash: string, signerAddress: string): Promise<ECSignature> {
assert.isHexString('orderHash', orderHash);

18
src/contract_wrappers/exchange_wrapper.ts
View File

@ -37,6 +37,10 @@ import {constants} from '../utils/constants';
import {TokenWrapper} from './token_wrapper';
import {decorators} from '../utils/decorators';
/**
* This class includes all the functionality related to calling methods and subscribing to
* events of the 0x Exchange smart contract.
*/
export class ExchangeWrapper extends ContractWrapper {
private _exchangeContractErrCodesToMsg = {
[ExchangeContractErrCodes.ERROR_FILL_EXPIRED]: ExchangeContractErrs.ORDER_FILL_EXPIRED,
@ -129,7 +133,7 @@ export class ExchangeWrapper extends ContractWrapper {
* 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 (using all the gas supplied) instead.
* @param signedOrder A JS object that conforms to the SignedOrder interface.
* @param signedOrder An 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.
@ -254,7 +258,7 @@ 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 orderFillRequests An array of 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
@ -321,7 +325,7 @@ 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
* @param signedOrder An 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.
@ -370,7 +374,7 @@ 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 orderFillOrKillRequests An array of 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.
*/
@ -426,7 +430,7 @@ 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.
* @param order An 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.
*/
@ -463,7 +467,7 @@ 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
* @param orderCancellationRequests An array of objects that conform to the OrderCancellationRequest
* interface.
*/
@decorators.contractCallErrorHandler
@ -515,7 +519,7 @@ 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
* @param indexFilterValues An 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}`
* @return ContractEventEmitter object
*/

5
src/contract_wrappers/token_registry_wrapper.ts
View File

@ -5,6 +5,9 @@ import {assert} from '../utils/assert';
import {ContractWrapper} from './contract_wrapper';
import * as TokenRegistryArtifacts from '../artifacts/TokenRegistry.json';
/**
* This class includes all the functionality related to interacting with the 0x Token Registry smart contract.
*/
export class TokenRegistryWrapper extends ContractWrapper {
private _tokenRegistryContractIfExists?: TokenRegistryContract;
constructor(web3Wrapper: Web3Wrapper) {
@ -15,7 +18,7 @@ export class TokenRegistryWrapper extends ContractWrapper {
}
/**
* Retrieves all the tokens currently listed in the Token Registry smart contract
* @return An array of JS objects that conform to the Token interface.
* @return An array of objects that conform to the Token interface.
*/
public async getTokensAsync(): Promise<Token[]> {
const tokenRegistryContract = await this._getTokenRegistryContractAsync();

14
src/contract_wrappers/token_wrapper.ts
View File

@ -10,6 +10,11 @@ import {TokenContract, ZeroExError} from '../types';
const ALLOWANCE_TO_ZERO_GAS_AMOUNT = 45730;
/**
* This class includes all the functionality related to interacting with ERC20 token contracts.
* All ERC20 method calls are supported, along with some convenience methods for getting/setting allowances
* to the 0x Proxy smart contract.
*/
export class TokenWrapper extends ContractWrapper {
private _tokenContractsByAddress: {[address: string]: TokenContract};
constructor(web3Wrapper: Web3Wrapper) {
@ -138,12 +143,13 @@ 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.
* `amountInBaseUnits` to `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 fromAddress The hex encoded user Ethereum address whose funds are being sent.
* @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 senderAddress The hex encoded user Ethereum address whose initiates the fund transfer. The
* `fromAddress` must have set an allowance to the `senderAddress`
* before this call.
* @param amountInBaseUnits The amount (specified in baseUnits) of the token to transfer.
*/
public async transferFromAsync(tokenAddress: string, fromAddress: string, toAddress: string,