diff options
Diffstat (limited to 'python-packages/order_utils/src/zero_ex/order_utils/__init__.py')
-rw-r--r-- | python-packages/order_utils/src/zero_ex/order_utils/__init__.py | 278 |
1 files changed, 204 insertions, 74 deletions
diff --git a/python-packages/order_utils/src/zero_ex/order_utils/__init__.py b/python-packages/order_utils/src/zero_ex/order_utils/__init__.py index 24c6bfd4e..39d411507 100644 --- a/python-packages/order_utils/src/zero_ex/order_utils/__init__.py +++ b/python-packages/order_utils/src/zero_ex/order_utils/__init__.py @@ -1,28 +1,29 @@ """Order utilities for 0x applications. -Some methods require the caller to pass in a `Web3.HTTPProvider` object. For -local testing one may construct such a provider pointing at an instance of +Some methods require the caller to pass in a `Web3.BaseProvider`:code: object. +For local testing one may construct such a provider pointing at an instance of `ganache-cli <https://www.npmjs.com/package/ganache-cli>`_ which has the 0x contracts deployed on it. For convenience, a docker container is provided for -just this purpose. To start it: ``docker run -d -p 8545:8545 0xorg/ganache-cli ---gasLimit 10000000 --db /snapshot --noVMErrorsOnRPCResponse -p 8545 ---networkId 50 -m "concert load couple harbor equip island argue ramp clarify -fence smart topic"``. +just this purpose. To start it: +`docker run -d -p 8545:8545 0xorg/ganache-cli:2.2.2`:code:. """ +from copy import copy from enum import auto, Enum import json -from typing import Dict, Tuple +from typing import cast, Dict, NamedTuple, Tuple from pkg_resources import resource_string from mypy_extensions import TypedDict -from eth_utils import keccak, to_bytes, to_checksum_address +from eth_utils import keccak, remove_0x_prefix, to_bytes, to_checksum_address from web3 import Web3 import web3.exceptions from web3.providers.base import BaseProvider from web3.utils import datatypes +from zero_ex.contract_addresses import NETWORK_TO_ADDRESSES, NetworkId +import zero_ex.contract_artifacts from zero_ex.dev_utils.type_assertions import ( assert_is_address, assert_is_hex_string, @@ -34,34 +35,6 @@ from zero_ex.json_schemas import assert_valid class _Constants: """Static data used by order utilities.""" - _contract_name_to_abi: Dict[str, Dict] = {} # class data, not instance - - @classmethod - def contract_name_to_abi(cls, contract_name: str) -> Dict: - """Return the ABI for the given contract name. - - First tries to get data from the class level storage - `_contract_name_to_abi`. If it's not there, loads it from disk, stores - it in the class data (for the next caller), and then returns it. - """ - try: - return cls._contract_name_to_abi[contract_name] - except KeyError: - cls._contract_name_to_abi[contract_name] = json.loads( - resource_string( - "zero_ex.contract_artifacts", - f"artifacts/{contract_name}.json", - ) - )["compilerOutput"]["abi"] - return cls._contract_name_to_abi[contract_name] - - network_to_exchange_addr: Dict[str, str] = { - "1": "0x4f833a24e1f95d70f028921e27040ca56e09ab0b", - "3": "0x4530c0483a1633c7a1c97d2c53721caff2caaaaf", - "42": "0x35dd2932454449b14cee11a94d3674a936d5d7b2", - "50": "0x48bacb9266a570d521063ef5dd96e61686dbe788", - } - null_address = "0x0000000000000000000000000000000000000000" eip191_header = b"\x19\x01" @@ -107,53 +80,195 @@ class _Constants: class Order(TypedDict): # pylint: disable=too-many-instance-attributes - """Object representation of a 0x order.""" + """A Web3-compatible representation of the Exchange.Order struct.""" makerAddress: str + """Address that created the order.""" + takerAddress: str + """Address that is allowed to fill the order. + + If set to 0, any address is allowed to fill the order. + """ + feeRecipientAddress: str + """Address that will recieve fees when order is filled.""" + senderAddress: str - makerAssetAmount: str - takerAssetAmount: str - makerFee: str - takerFee: str - expirationTimeSeconds: str - salt: str - makerAssetData: str - takerAssetData: str - exchangeAddress: str + """Address that is allowed to call Exchange contract methods that affect + this order. If set to 0, any address is allowed to call these methods. + """ + + makerAssetAmount: int + """Amount of makerAsset being offered by maker. Must be greater than 0.""" + + takerAssetAmount: int + """Amount of takerAsset being bid on by maker. Must be greater than 0.""" + + makerFee: int + """Amount of ZRX paid to feeRecipient by maker when order is filled. If + set to 0, no transfer of ZRX from maker to feeRecipient will be attempted. + """ + + takerFee: int + """Amount of ZRX paid to feeRecipient by taker when order is filled. If + set to 0, no transfer of ZRX from taker to feeRecipient will be attempted. + """ + + expirationTimeSeconds: int + """Timestamp in seconds at which order expires.""" + + salt: int + """Arbitrary number to facilitate uniqueness of the order's hash.""" + + makerAssetData: bytes + """Encoded data that can be decoded by a specified proxy contract when + transferring makerAsset. The last byte references the id of this proxy. + """ + + takerAssetData: bytes + """Encoded data that can be decoded by a specified proxy contract when + transferring takerAsset. The last byte references the id of this proxy. + """ def make_empty_order() -> Order: """Construct an empty order. - Initializes all strings to "0x0000000000000000000000000000000000000000" - and all numbers to 0. + Initializes all strings to "0x0000000000000000000000000000000000000000", + all numbers to 0, and all bytes to nulls. """ return { "makerAddress": _Constants.null_address, "takerAddress": _Constants.null_address, "senderAddress": _Constants.null_address, "feeRecipientAddress": _Constants.null_address, - "makerAssetData": _Constants.null_address, - "takerAssetData": _Constants.null_address, - "salt": "0", - "makerFee": "0", - "takerFee": "0", - "makerAssetAmount": "0", - "takerAssetAmount": "0", - "expirationTimeSeconds": "0", - "exchangeAddress": _Constants.null_address, + "makerAssetData": (b"\x00") * 20, + "takerAssetData": (b"\x00") * 20, + "salt": 0, + "makerFee": 0, + "takerFee": 0, + "makerAssetAmount": 0, + "takerAssetAmount": 0, + "expirationTimeSeconds": 0, } -def generate_order_hash_hex(order: Order) -> str: +def order_to_jsdict( + order: Order, exchange_address="0x0000000000000000000000000000000000000000" +) -> dict: + """Convert a Web3-compatible order struct to a JSON-schema-compatible dict. + + More specifically, do explicit decoding for the `bytes`:code: fields. + + >>> import pprint + >>> pprint.pprint(order_to_jsdict( + ... { + ... 'makerAddress': "0x0000000000000000000000000000000000000000", + ... 'takerAddress': "0x0000000000000000000000000000000000000000", + ... 'feeRecipientAddress': + ... "0x0000000000000000000000000000000000000000", + ... 'senderAddress': "0x0000000000000000000000000000000000000000", + ... 'makerAssetAmount': 1, + ... 'takerAssetAmount': 1, + ... 'makerFee': 0, + ... 'takerFee': 0, + ... 'expirationTimeSeconds': 1, + ... 'salt': 1, + ... 'makerAssetData': (0).to_bytes(1, byteorder='big') * 20, + ... 'takerAssetData': (0).to_bytes(1, byteorder='big') * 20, + ... }, + ... )) + {'exchangeAddress': '0x0000000000000000000000000000000000000000', + 'expirationTimeSeconds': 1, + 'feeRecipientAddress': '0x0000000000000000000000000000000000000000', + 'makerAddress': '0x0000000000000000000000000000000000000000', + 'makerAssetAmount': 1, + 'makerAssetData': '0x0000000000000000000000000000000000000000', + 'makerFee': 0, + 'salt': 1, + 'senderAddress': '0x0000000000000000000000000000000000000000', + 'takerAddress': '0x0000000000000000000000000000000000000000', + 'takerAssetAmount': 1, + 'takerAssetData': '0x0000000000000000000000000000000000000000', + 'takerFee': 0} + """ + jsdict = cast(Dict, copy(order)) + + # encode bytes fields + jsdict["makerAssetData"] = "0x" + order["makerAssetData"].hex() + jsdict["takerAssetData"] = "0x" + order["takerAssetData"].hex() + + jsdict["exchangeAddress"] = exchange_address + + assert_valid(jsdict, "/orderSchema") + + return jsdict + + +def jsdict_order_to_struct(jsdict: dict) -> Order: + r"""Convert a JSON-schema-compatible dict order to a Web3-compatible struct. + + More specifically, do explicit encoding of the `bytes`:code: fields. + + >>> import pprint + >>> pprint.pprint(jsdict_order_to_struct( + ... { + ... 'makerAddress': "0x0000000000000000000000000000000000000000", + ... 'takerAddress': "0x0000000000000000000000000000000000000000", + ... 'feeRecipientAddress': "0x0000000000000000000000000000000000000000", + ... 'senderAddress': "0x0000000000000000000000000000000000000000", + ... 'makerAssetAmount': 1000000000000000000, + ... 'takerAssetAmount': 1000000000000000000, + ... 'makerFee': 0, + ... 'takerFee': 0, + ... 'expirationTimeSeconds': 12345, + ... 'salt': 12345, + ... 'makerAssetData': "0x0000000000000000000000000000000000000000", + ... 'takerAssetData': "0x0000000000000000000000000000000000000000", + ... 'exchangeAddress': "0x0000000000000000000000000000000000000000", + ... }, + ... )) + {'expirationTimeSeconds': 12345, + 'feeRecipientAddress': '0x0000000000000000000000000000000000000000', + 'makerAddress': '0x0000000000000000000000000000000000000000', + 'makerAssetAmount': 1000000000000000000, + 'makerAssetData': b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00' + b'\x00\x00\x00\x00\x00\x00\x00\x00', + 'makerFee': 0, + 'salt': 12345, + 'senderAddress': '0x0000000000000000000000000000000000000000', + 'takerAddress': '0x0000000000000000000000000000000000000000', + 'takerAssetAmount': 1000000000000000000, + 'takerAssetData': b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00' + b'\x00\x00\x00\x00\x00\x00\x00\x00', + 'takerFee': 0} + """ # noqa: E501 (line too long) + assert_valid(jsdict, "/orderSchema") + + order = cast(Order, copy(jsdict)) + + order["makerAssetData"] = bytes.fromhex( + remove_0x_prefix(jsdict["makerAssetData"]) + ) + order["takerAssetData"] = bytes.fromhex( + remove_0x_prefix(jsdict["takerAssetData"]) + ) + + del order["exchangeAddress"] # type: ignore + # silence mypy pending release of + # https://github.com/python/mypy/issues/3550 + + return order + + +def generate_order_hash_hex(order: Order, exchange_address: str) -> str: """Calculate the hash of the given order as a hexadecimal string. :param order: The order to be hashed. Must conform to `the 0x order JSON schema <https://github.com/0xProject/0x-monorepo/blob/development/packages/json-schemas/schemas/order_schema.json>`_. :param exchange_address: The address to which the 0x Exchange smart contract has been deployed. - :rtype: A string, of ASCII hex digits, representing the order hash. + :returns: A string, of ASCII hex digits, representing the order hash. >>> generate_order_hash_hex( ... { @@ -167,14 +282,15 @@ def generate_order_hash_hex(order: Order) -> str: ... 'takerFee': "0", ... 'expirationTimeSeconds': "12345", ... 'salt': "12345", - ... 'makerAssetData': "0x0000000000000000000000000000000000000000", - ... 'takerAssetData': "0x0000000000000000000000000000000000000000", - ... 'exchangeAddress': "0x0000000000000000000000000000000000000000", + ... 'makerAssetData': (0).to_bytes(1, byteorder='big') * 20, + ... 'takerAssetData': (0).to_bytes(1, byteorder='big') * 20, ... }, + ... exchange_address="0x0000000000000000000000000000000000000000", ... ) '55eaa6ec02f3224d30873577e9ddd069a288c16d6fb407210eecbc501fa76692' """ # noqa: E501 (line too long) - assert_valid(order, "/orderSchema") + assert_is_address(exchange_address, "exchange_address") + assert_valid(order_to_jsdict(order, exchange_address), "/orderSchema") def pad_20_bytes_to_32(twenty_bytes: bytes): return bytes(12) + twenty_bytes @@ -184,7 +300,7 @@ def generate_order_hash_hex(order: Order) -> str: eip712_domain_struct_hash = keccak( _Constants.eip712_domain_struct_header - + pad_20_bytes_to_32(to_bytes(hexstr=order["exchangeAddress"])) + + pad_20_bytes_to_32(to_bytes(hexstr=exchange_address)) ) eip712_order_struct_hash = keccak( @@ -199,8 +315,8 @@ def generate_order_hash_hex(order: Order) -> str: + int_to_32_big_endian_bytes(int(order["takerFee"])) + int_to_32_big_endian_bytes(int(order["expirationTimeSeconds"])) + int_to_32_big_endian_bytes(int(order["salt"])) - + keccak(to_bytes(hexstr=order["makerAssetData"])) - + keccak(to_bytes(hexstr=order["takerAssetData"])) + + keccak(to_bytes(hexstr=order["makerAssetData"].hex())) + + keccak(to_bytes(hexstr=order["takerAssetData"].hex())) ) return keccak( @@ -210,20 +326,33 @@ def generate_order_hash_hex(order: Order) -> str: ).hex() +class OrderInfo(NamedTuple): + """A Web3-compatible representation of the Exchange.OrderInfo struct.""" + + order_status: str + """A `str`:code: describing the order's validity and fillability.""" + + order_hash: bytes + """A `bytes`:code: object representing the EIP712 hash of the order.""" + + order_taker_asset_filled_amount: int + """An `int`:code: indicating the amount that has already been filled.""" + + def is_valid_signature( provider: BaseProvider, data: str, signature: str, signer_address: str ) -> Tuple[bool, str]: """Check the validity of the supplied signature. - Check if the supplied ``signature`` corresponds to signing ``data`` with - the private key corresponding to ``signer_address``. + Check if the supplied `signature`:code: corresponds to signing `data`:code: + with the private key corresponding to `signer_address`:code:. :param provider: A Web3 provider able to access the 0x Exchange contract. :param data: The hex encoded data signed by the supplied signature. :param signature: The hex encoded signature. :param signer_address: The hex encoded address that signed the data to produce the supplied signature. - :rtype: Tuple consisting of a boolean and a string. Boolean is true if + :returns: Tuple consisting of a boolean and a string. Boolean is true if valid, false otherwise. If false, the string describes the reason. >>> is_valid_signature( @@ -241,12 +370,13 @@ def is_valid_signature( web3_instance = Web3(provider) # false positive from pylint: disable=no-member - network_id = web3_instance.net.version - contract_address = _Constants.network_to_exchange_addr[network_id] + contract_address = NETWORK_TO_ADDRESSES[ + NetworkId(int(web3_instance.net.version)) + ].exchange # false positive from pylint: disable=no-member contract: datatypes.Contract = web3_instance.eth.contract( address=to_checksum_address(contract_address), - abi=_Constants.contract_name_to_abi("Exchange"), + abi=zero_ex.contract_artifacts.abi_by_name("Exchange"), ) try: return ( @@ -337,8 +467,8 @@ def sign_hash( :param provider: A Web3 provider. :param signer_address: The address of the signing account. :param hash_hex: A hex string representing the hash, like that returned - from `generate_order_hash_hex()`. - :rtype: A string, of ASCII hex digits, representing the signature. + from `generate_order_hash_hex()`:code:. + :returns: A string, of ASCII hex digits, representing the signature. >>> provider = Web3.HTTPProvider("http://127.0.0.1:8545") >>> sign_hash( |