[INFO] API changes from @0x/contract-wrappers v10 -> v11

[xianny]

Our latest major version bump of @0x/contract-wrappers to 11.0.0 replaces contract wrappers with code generated from @0x/abi-gen. This will allow us to support changes to the 0x smart contracts more efficiently. This issue summarises the major public interface changes.

Detailed API documentation will be published shortly.

For code diffs see #2037

ContractWrappers

Convenience class to instantiate all the other contract wrappers. Constructor remains the same.

Summary of changes to instance members:

• exchange
• erc20Token -> REMOVED
• erc721Token -> REMOVED
• etherToken -> RENAMED to weth9
• erc20Proxy
• erc721Proxy
• forwarder
• orderValidator
• dutchAuction
• coordinator -> NO CHANGE

All other instance members have been converted from <ContractName>ContractWrapper classes to <ContractName>Contract classes.

Changes to Contract Wrappers

Contract wrappers use object literals to represent each function in a Solidity contract. Each Solidity function object literal contains methods for interacting with the contract. For example:

/// Exchange.sol

function fillOrder(
        Order memory order,
        uint256 takerAssetFillAmount,
        bytes memory signature
    )
...

results in:

// ExchangeContract

class ExchangeContract {
    public fillOrder = {
        callAsync(...) {
            ...
        },
        sendTransactionAsync(...) {
            ...
        },
        ...
}

Methods should now be called like this:

// earlier version
exchangeWrapper.fillOrderAsync(signedOrder)

// v11+
exchangeContract.fillOrder.sendTransactionAsync(signedOrder)

The available functions are:

• callAsync
• getABIEncodedTransactionData
• getABIDecodedTransactionData
• getABIDecodedReturnData

Additional functions for methods that are not pure or view in Solidity:

• sendTransactionAsync
• awaitTransactionSuccessAsync
• estimateGasAsync

The rest of this post will be a list of changes for individual contract wrappers.

DutchAuctionWrapper -> DutchAuctionContract

old method	new method	notes
abi	abi	-----
address	address	-----
decodeDutchAuctionData	-----	moved to @0x/order-utils
encodeDutchAuctionAssetData	-----	moved to @0x/order-utils
getAuctionDetailsAsync	getAuctionDetails	----
matchOrdersAsync	matchOrders	doesn't enforce matching assetData

ERC20ProxyWrapper -> ERC20ProxyContract

old method	new method	notes
abi	abi	-----
address	address	-----
getAuthorizedAddressesAsync	getAuthorizedAddresses	---
getProxyIdAsync: () => Promise<AssetProxyId>	getProxyId: () => Promise<string>	---
isAuthorizedAsync: (string) => Promise<boolean>	authorized: (string) => Promise<boolean>	* does not normalize exchangeContractAddress to lowercase. * Renames input param from exchangeContractAddress to input_0

ERC721ProxyWrapper -> ERC721ProxyContract

old method	new method	notes
abi	abi	-----
address	address	-----
getAuthorizedAddressesAsync	getAuthorizedAddresses	---
getProxyIdAsync: () => Promise<AssetProxyId>	getProxyId: () => Promise<string>	---
isAuthorizedAsync: (string) => Promise<boolean>	authorized: (string) => Promise<boolean>	* does not normalize exchangeContractAddress to lowercase. * Renames input param from exchangeContractAddress to input_0

ERC20TokenWrapper -> ERC20TokenContract

The old version of the ERC20TokenWrapper contained an index of multiple ERC20Token contracts. This will no longer be supported.
The new ERC20TokenContract class only wraps a single token. It will not be instantiated as part of the ContractWrappers class. It should be instantiated separately with the address for any desired token.

old method	new method	notes
UNLIMITED_ALLOWANCE_IN_BASE_UNITS	----	const, doesn't exist, available in contract-wrappers/utils/constants
abi	abi	-----
getAllowanceAsync	allowance	does not take tokenAddress as argument anymore
getBalanceAsync	balanceOf	* does not take tokenAddress as argument anymore * does not normalize ownerAddress to lower case
setAllowanceAsync	approve	ownerAddress is set as part of TxData instead of an arg
getProxyAllowanceAsync	-------	doesn't exist, convenience method for getAllowanceAsync
setProxyAllowanceAsync	-------	doesn't exist, convenience method for setAllowanceAsync
setUnlimitedAllowanceAsync	-------	doesn't exist, convenience method for setAllowanceAsync
setUnlimitedProxyAllowanceAsync	-------	doesn't exist, convenience method for setAllowanceAsync
transferAsync	transfer	doesn't check for insufficient balance
transferFromAsync	transferFrom	doesn't check for insufficient balance
getLogsAsync	getLogsAsync	-----
subscribe	subscribe	-----
unsubscribe	unsubscribe	-----
unsubscribeAll	unsubscribeAll	-----

ERC721TokenWrapper -> ERC721TokenContract

The old version of the ERC721TokenWrapper contained an index of multiple ERC721Token contracts. This will no longer be supported.
The new ERC721TokenContract class only wraps a single token. It will not be instantiated as part of the ContractWrappers class. It should be instantiated separately with the address for any desired token.

old method	new method	notes
abi	abi	-----
getApprovedIfExistsAsync	getApproved	returns the null address instead of undefined
getOwnerOfAsync	ownerOf	----
getTokenCountAsync	balanceOf	doesn't normalize ownerAddress to lowercase
isApprovedForAllAsync	isApprovedForAll	doesn't normalize owner and operator addresses to lower case
setApprovalAsync	approve	doesn't normalize approvedAddress to lowercase
setApprovalForAllAsync	setApprovalForAll	doesn't normalize operatorAddress to lowercase
isProxyApprovedAsync	----	doesn't exist, convenience method for getApprovedIfExistsAsync
isProxyApprovedForAllAsync	----	doesn't exist, convenience method for isApprovedForAllAsync
setProxyApprovalAsync	----	doesn't exist, convenience method for setApprovalAsync
setProxyApprovalForAllAsync	----	doesn't exist, convenience method for setApprovalForAllAsync
transferFromAsync	transferFrom	* doesn't check approvals * doesn't normalize addresses to lowercase
getLogsAsync	getLogsAsync	-----
subscribe	subscribe	-----
unsubscribe	unsubscribe	-----
unsubscribeAll	unsubscribeAll	-----

EtherTokenWrapper -> WETH9Contract

old method	new method	notes
abi	abi	-----
depositAsync	deposit	* doesn't normalize addresses to lowercase * doesn't enforce sufficient balance
withdrawAsync	withdraw	* doesn't normalize addresses to lowercase * doesn't enforce sufficient balance
getLogsAsync	getLogsAsync	-----
subscribe	subscribe	-----
unsubscribe	unsubscribe	-----
unsubscribeAll	unsubscribeAll	-----

ExchangeWrapper -> ExchangeContract

The old ExchangeWrapper used to check for a boolean shouldValidate to determine whether to use callAsync or sendTransactionAsync. This has been removed.

if (shouldValidate) {
	callAsync(...)
} else {
	sendTransactionAsync(...)
}

old method	new method	notes
abi	abi	-----
address	address	-----
zrxTokenAddress	-------	doesn't exist
batchCancelOrdersAsync	batchCancelOrders
batchFillOrKillOrdersAsync	batchFillOrKillOrders	----
batchFillOrdersAsync	batchFillOrders	----
batchFillOrdersNoThrowAsync	batchFillOrdersNoThrow	----
cancelOrderAsync	cancelOrder	----
cancelOrdersUpToAsync	cancelOrdersUpTo	----
executeTransactionAsync	executeTransaction	----
fillOrKillOrderAsync	fillOrKillOrder	----
fillOrderAsync	fillOrder	----
fillOrderNoThrowAsync	fillOrderNoThrow	----
getAssetProxyBySignatureAsync	getAssetProxy	----
getFilledTakerAssetAmountAsync	filled	----
getOrderEpochAsync	orderEpoch	* input args renamed * makerAddress => index_0 * senderAddress => index_1
getOrderInfoAsync	getOrderInfo	----
getOrdersInfoAsync	getOrdersInfo	----
getVersionAsync	VERSION	----
getZRXAssetData	----	* use encodeERC20AssetData() in @0x/order-utils instead
isAllowedValidatorAsync	allowedValidators	----
isCancelledAsync	cancelled	----
isPreSignedAsync	preSigned	----
isTransactionExecutedAsync	transactions	----
isValidSignatureAsync	isValidSignature	----
marketBuyOrdersAsync	marketBuyOrders	----
marketBuyOrdersNoThrowAsync	marketBuyOrdersNoThrow	----
marketSellOrdersAsync	marketSellOrders	----
marketSellOrdersNoThrowAsync	marketSellOrdersNoThrow	----
matchOrdersAsync	matchOrders	----
preSignAsync	preSign	----
setSignatureValidatorApprovalAsync	setSignatureValidatorApproval	----
transactionEncoderAsync	----	doesn't exist
validateFillOrderThrowIfInvalidAsync	-----	use fillOrder.callAsync instead
validateMakerTransferThrowIfInvalidAsync	-----	moved to @0x/order-utils
validateOrderFillableOrThrowAsync	----	moved to @0x/order-utils.OrderValidationUtils.simpleValidateOrderFillableOrThrowAsync
getLogsAsync	getLogsAsync	----
subscribe	subscribe	----
unsubscribe	unsubscribe	----
unsubscribeAll	unsubscribeAll	----

ForwarderWrapper -> ForwarderContract

old method	new method	notes
abi	abi	-----
address	address	-----
etherTokenAddress	-------	doesn't exist
zrxTokenAddress	-------	doesn't exist
marketBuyOrdersWithEthAsync	marketBuyOrdersWithEth	does not optimize orders
marketSellOrdersWithEthAsync	marketSellOrdersWithEth	does not optimize orders

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically closed because no activity occured in 7 days after being marked as stale. If it's still relevant - feel free to reopen. Thank you for your contributions.