@kosu/create-portal-helper

Create

Helper methods for building the Paradigm "Create" portal.

Kind: global class

Create
- new Create()
- .init()
- .createAndSignOrder(options)
- .signAndPost(signedZeroExOrder)
- .convertToWei(etherAmount) ⇒ Promise.<string>
- .convertFromWei(weiAmount) ⇒ Promise.<string>
- .isValidAddress(address) ⇒ boolean
- .userHasBond(userAddress) ⇒ Promise.<boolean>
- .awaitTransactionSuccessOrThrow(txID) ⇒
- .getUserWethBalance(userAddress) ⇒ Promise.<BigNumber>
- .getUserWethAllowance(userAddress) ⇒ Promise.<BigNumber>
- .setProxyAllowanceWeth(userAddress) ⇒ string
- .getUserZrxBalance(userAddress) ⇒ Promise.<BigNumber>
- .getUserZrxAllowance(userAddress) ⇒ Promise.<BigNumber>
- .setProxyAllowanceZrx(userAddress) ⇒ Promise.<string>
- .getUserDaiBalance(userAddress) ⇒ Promise.<BigNumber>
- .getUserDaiAllowance(userAddress) ⇒ Promise.<BigNumber>
- .setProxyAllowanceDai(userAddress) ⇒ Promise.<string>
- .getUserCustomBalance(tokenAddress, userAddress) ⇒ Promise.<BigNumber>
- .getUserCustomAllowance(tokenAddress, userAddress) ⇒ Promise.<BigNumber>
- .setProxyAllowanceCustom(tokenAddress, userAddress) ⇒ Promise.<string>

new Create()

Construct a new Create instance. Accepts no arguments, and returns an un-initialized instance.

Most instance methods require init() to be called prior to use.

create.init()

Must be called prior to using most library functionality. Calling init will trigger a Metamask pop-up prompting the user to approve access to the web page.

As such, init() should be the function call associated with the UX "Connect to Metamask" button.

Catching promise rejections from init() is required, and indicates some bad user configuration. Certain rejections can be used to update front-end state.

Rejection cases:

"wrong network": the user is not on the Ethereum main-network
"user denied site access": the user clicked "deny" on Metamask pop-up
"non-ethereum browser detected": user does not have a web3 browser

Kind: instance method of Create

create.createAndSignOrder(options)

Generate and sign a 0x order. Will prompt user for a MetaMask signature.

Kind: instance method of Create

Param Type Description

options

Param	Type	Description
options	`object`	object with the following properties: makerAssetAddress: either ("WETH/DAI/ZRX") or a full 42 char hex address takerAssetAddress: either ("WETH/DAI/ZRX") or a full 42 char hex address makerAssetAmount: units are wei, value can be string/number or BigNumber takerAssetAmount: units are wei, value can be string/number or BigNumber orderDuration: the number of seconds the order should be valid for makerAddress: can be provided to override `coinbase`, but shouldn't

object

object with the following properties:

makerAssetAddress: either ("WETH/DAI/ZRX") or a full 42 char hex address
takerAssetAddress: either ("WETH/DAI/ZRX") or a full 42 char hex address
makerAssetAmount: units are wei, value can be string/number or BigNumber
takerAssetAmount: units are wei, value can be string/number or BigNumber
orderDuration: the number of seconds the order should be valid for
makerAddress: can be provided to override coinbase, but shouldn't

Example

// create an order for 0.5 WETH <> 80 custom token, valid for 10 minutes
let order = await create.createAndSignOrder({
    makerAssetAddress: "WETH",
    takerAssetAddress: "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2",
    makerAssetAmount: create.convertToWei("0.5"),
    takerAssetAmount: create.convertToWei("80"),
    orderDuration: 600,
});

create.signAndPost(signedZeroExOrder)

Signs a (already signed) 0x order as the Kosu poster, and posts and order to the Kosu network. Requires the poster to have a bonded amount of KOSU in the PosterRegistry contract.

Kind: instance method of Create
Todo:: - undo split-network ugly-ness

don't pull makerArguments from subcontract if provided
ability to use direct kosu.js to sign

Param	Type	Description
signedZeroExOrder	`object`	as outputted from `createAndSignOrder`

create.convertToWei(etherAmount) ⇒ `Promise.<string>`

Converts a number (assumed to be number of tokens) as a string to units of wei, which must be used for generating 0x orders.

Kind: instance method of Create
Returns: Promise.<string> -

the same amount in wei

Param	Type	Description
etherAmount	`string` \| `BigNumber`	a number of tokens in full units (ether)

Example

// convert 100 tokens (as entered by user) to wei
create.convertToWei("100"); // > "100000000000000000000" (BigNumber)
create.convertToWei(100); // > "100000000000000000000" (BigNumber)

create.convertFromWei(weiAmount) ⇒ `Promise.<string>`

Converts a number (assumed to be number of tokens in wei) as a string to units of ether, which is more common to display to users.

Kind: instance method of Create
Returns: Promise.<string> -

the same amount in ether

Param	Type	Description
weiAmount	`string` \| `BigNumber`	a number of tokens in smallest units (wei)

Example

// convert 100 tokens (as received as balance or allowance) to tokens
create.convertToWei("100000000000000000000"); // > "100" (BigNumber)
create.convertToWei(100000000000000000000); // > "100" (BigNumber)

create.isValidAddress(address) ⇒ `boolean`

Returns true if the inputted string is a valid Ethereum address, otherwise returns false.

Kind: instance method of Create
Returns: boolean -

true if valid Ethereum address, otherwise false

Param	Type	Description
address	`string`	a string to be validated as an Ethereum address

Example

create.isValidAddress("0x4f833a24e1f95d70f028921e27040ca56e09ab0b"); // > true
create.isValidAddress("4f833a24e1f95d70f028921e27040ca56e09ab0b"); // > false
create.isValidAddress("0x4f833a24e1f95d70f028921e27040ca56e09ab0"); // > false

create.userHasBond(userAddress) ⇒ `Promise.<boolean>`

Check if the user (by their coinbase address) is allowed to post to the Kosu network. Returns true if they are, and false if they are not.

Kind: instance method of Create
Returns: Promise.<boolean> -

true if user has active bond, false otherwise

Param	Type	Description
userAddress	`string`	can be provided to override coinbase, but shouldn't

create.awaitTransactionSuccessOrThrow(txID) ⇒

Async function that returns a promise that resolves when the supplied txID is mined and executed successfully. If the transaction fails, the promise will reject. The resolved object is a full receipt that can usually be ignored. The purpose of this method is to simply wait until a transaction is successfully mined.

Kind: instance method of Create
Returns:

the full decoded transaction receipt (usually will not need)

Param	Type	Description
txID	`string`	32 byte (64-char) 0x-prefixed transaction hash

Example

const txId = await create.setProxyAllowanceWeth();

// wait for the transaction to be mined, show loading icon, etc.
await create.awaitTransactionSuccessOrThrow(txId);

create.getUserWethBalance(userAddress) ⇒ `Promise.<BigNumber>`

Returns a BigNumber representing the users WETH balance (in wei).

Kind: instance method of Create
Returns: Promise.<BigNumber> -

the user's WETH balance in wei

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.getUserWethAllowance(userAddress) ⇒ `Promise.<BigNumber>`

Returns a BigNumber representing the users WETH allowance for the 0x contract system.

Kind: instance method of Create
Returns: Promise.<BigNumber> -

the user's 0x proxy WETH allowance in wei

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.setProxyAllowanceWeth(userAddress) ⇒ `string`

Sets an unlimited allowance for the 0x contract system for WETH.

Kind: instance method of Create
Returns: string -

the transaction hash of the resulting tx

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.getUserZrxBalance(userAddress) ⇒ `Promise.<BigNumber>`

Returns a BigNumber representing the users ZRX balance (in wei).

Kind: instance method of Create
Returns: Promise.<BigNumber> -

the user's ZRX balance in wei

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.getUserZrxAllowance(userAddress) ⇒ `Promise.<BigNumber>`

Returns a BigNumber representing the users ZRX allowance for the 0x contract system.

Kind: instance method of Create
Returns: Promise.<BigNumber> -

the user's 0x proxy ZRX allowance in wei

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.setProxyAllowanceZrx(userAddress) ⇒ `Promise.<string>`

Sets an unlimited allowance for the 0x contract system for ZRX.

Kind: instance method of Create
Returns: Promise.<string> -

the transaction hash of the resulting tx

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.getUserDaiBalance(userAddress) ⇒ `Promise.<BigNumber>`

Returns a BigNumber representing the users DAI balance (in wei).

Kind: instance method of Create
Returns: Promise.<BigNumber> -

the user's DAI balance in wei

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.getUserDaiAllowance(userAddress) ⇒ `Promise.<BigNumber>`

Returns a BigNumber representing the users DAI allowance for the 0x contract system.

Kind: instance method of Create
Returns: Promise.<BigNumber> -

the user's 0x proxy DAI allowance in wei

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.setProxyAllowanceDai(userAddress) ⇒ `Promise.<string>`

Sets an unlimited allowance for the 0x contract system for DAI.

Kind: instance method of Create
Returns: Promise.<string> -

the transaction hash of the resulting tx

Param	Type	Description
userAddress	`string`	override user's detected coinbase address

create.getUserCustomBalance(tokenAddress, userAddress) ⇒ `Promise.<BigNumber>`

Returns a BigNumber representing the users balance of a custom token, provided by token address.

Kind: instance method of Create
Returns: Promise.<BigNumber> -

the user's balance in wei of custom token

Param	Type	Description
tokenAddress	`string`	0x-prefixed address of the custom token
userAddress	`string`	override user's detected coinbase address

Example

const balance = await create.getUserCustomBalance("0x4f833a24e1f95d70f028921e27040ca56e09ab0b");

create.getUserCustomAllowance(tokenAddress, userAddress) ⇒ `Promise.<BigNumber>`

Returns a BigNumber representing the users allowance for the 0x contract system of a custom token, provided by tokenAddress.

Kind: instance method of Create
Returns: Promise.<BigNumber> -

the user's 0x proxy allowance in wei for custom token

Param	Type	Description
tokenAddress	`string`	0x-prefixed address of the custom token
userAddress	`string`	override user's detected coinbase address

Example

const allowance = await create.getUserCustomAllowance("0x4f833a24e1f95d70f028921e27040ca56e09ab0b");

create.setProxyAllowanceCustom(tokenAddress, userAddress) ⇒ `Promise.<string>`

Sets an unlimited allowance for the 0x contract system for the provided custom token address (tokenAddress).

Kind: instance method of Create
Returns: Promise.<string> -

the transaction hash of the resulting tx

Param	Type	Description
tokenAddress	`string`	0x-prefixed address of the custom token
userAddress	`string`	override user's detected coinbase address

Example

await create.setProxyAllowanceCustom("0x4f833a24e1f95d70f028921e27040ca56e09ab0b");