Cleanup time - update readme, docs, methods for humans

Author: ajrgrubbs

README.md

@@ -25,7 +25,7 @@ struct Message {
 
 Python representation:
 ```python
-from eip712_structs import EIP712Struct, Address, String, make_domain_separator, create_message
+from eip712_structs import EIP712Struct, Address, String, make_domain, struct_to_dict
 
 class Message(EIP712Struct):
     to = Address()
@@ -36,8 +36,36 @@ enctyp = Message.encode_type()  # 'Mail(address to,string contents)'
 msg = Message(to='0xdead...beef', contents='hello world')
 msg.encode_data()  # The struct's data in encoded form
 
-domain = make_domain_separator(name='example')
-msg_body, msg_hash = create_message(domain, msg)
+domain = make_domain(name='example')
+msg_body, msg_hash = struct_to_dict(msg, domain)
+```
+
+#### Dynamic construction
+Attributes may be added dynamically as well. This may be necessary if you
+want to use a reserved keyword like `from`.
+
+```python
+class Message(EIP712Struct):
+    pass
+
+Message.to = Address()
+setattr(Message, 'from', Address())
+```
+
+#### Creating Messages and Hashing
+Messages also require a domain struct. A helper method exists for this purpose.
+
+```python
+from eip712_structs import EIP712Struct, String, make_domain, struct_to_dict
+
+domain = make_domain(name='my_domain')  # Also accepts kwargs: version, chainId, verifyingContract, salt
+
+class Foo(EIP712Struct):
+    bar = String()
+
+foo = Foo(bar='baz')
+
+message_dict, message_hash = struct_to_dict(foo, domain)
 ```
 
 ## Member Types

eip712_structs/__init__.py

@@ -1,6 +1,6 @@
-from eip712_structs.domain_separator import make_domain_separator
-from eip712_structs.struct import EIP712Struct, struct_to_json, struct_from_json
+from eip712_structs.domain_separator import make_domain
+from eip712_structs.struct import EIP712Struct, struct_to_dict, struct_from_dict
 from eip712_structs.types import Address, Array, Boolean, Bytes, Int, String, Uint
 
 name = 'eip712-structs'
-version = '0.1.1'
+version = '0.1.2'

eip712_structs/domain_separator.py

@@ -1,22 +1,28 @@
 import eip712_structs
 
 
-def make_domain_separator(name=None, version=None, chainId=None, verifyingContract=None, salt=None):
+def make_domain(name=None, version=None, chainId=None, verifyingContract=None, salt=None):
     """Helper method to create the standard EIP712Domain struct for you.
+
+    Per the standard, if a value is not used then the parameter is omitted from the struct entirely.
     """
+
+    if all(i is None for i in [name, version, chainId, verifyingContract, salt]):
+        raise ValueError('At least on argument must be given.')
+
     class EIP712Domain(eip712_structs.EIP712Struct):
         pass
 
     kwargs = dict()
     if name is not None:
         EIP712Domain.name = eip712_structs.String()
-        kwargs['name'] = name
+        kwargs['name'] = str(name)
     if version is not None:
         EIP712Domain.version = eip712_structs.String()
-        kwargs['version'] = version
+        kwargs['version'] = str(version)
     if chainId is not None:
         EIP712Domain.chainId = eip712_structs.Uint(256)
-        kwargs['chainId'] = chainId
+        kwargs['chainId'] = int(chainId)
     if verifyingContract is not None:
         EIP712Domain.verifyingContract = eip712_structs.Address()
         kwargs['verifyingContract'] = verifyingContract

eip712_structs/struct.py

@@ -1,9 +1,10 @@
+import re
 from collections import OrderedDict, defaultdict
 from typing import List, Tuple
 
 from eth_utils.crypto import keccak
 
-from eip712_structs.types import EIP712Type, from_solidity_type
+from eip712_structs.types import Array, EIP712Type, from_solidity_type
 
 
 class OrderedAttributesMeta(type):
@@ -25,6 +26,16 @@ def __init_subclass__(cls, **kwargs):
 
 
 class EIP712Struct(_EIP712StructTypeHelper):
+    """A representation of an EIP712 struct. Subclass it to use it.
+
+    Example:
+        from eip712_structs import EIP712Struct, String
+
+        class MyStruct(EIP712Struct):
+            some_param = String()
+
+        struct_instance = MyStruct(some_param='some_value')
+    """
     def __init__(self, **kwargs):
         super(EIP712Struct, self).__init__(self.type_name)
         members = self.get_members()
@@ -36,20 +47,32 @@ def __init__(self, **kwargs):
             self.values[name] = value
 
     def encode_value(self, value=None):
+        """Returns the struct's encoded value.
+
+        A struct's encoded value is a concatenation of the bytes32 representation of each member of the struct.
+        Order is preserved.
+
+        :param value: This parameter is not used for structs.
+        """
         encoded_values = [typ.encode_value(self.values[name]) for name, typ in self.get_members()]
         return b''.join(encoded_values)
 
-    def encode_data(self):
-        return self.encode_value()
-
     def get_data_value(self, name):
+        """Get the value of the given struct parameter.
+        """
         return self.values.get(name)
 
     def set_data_value(self, name, value):
+        """Set the value of the given struct parameter.
+        """
         if name in self.values:
             self.values[name] = value
 
     def data_dict(self):
+        """Provide the entire data dictionary representing the struct.
+
+        Nested structs instances are also converted to dict form.
+        """
         result = dict()
         for k, v in self.values.items():
             if isinstance(v, EIP712Struct):
@@ -81,23 +104,51 @@ def _gather_reference_structs(cls, struct_set):
 
     @classmethod
     def encode_type(cls):
+        """Get the encoded type signature of the struct.
+
+        Nested structs are also encoded, and appended in alphabetical order.
+        """
         return cls._encode_type(True)
 
     @classmethod
     def type_hash(cls):
+        """Get the keccak hash of the struct's encoded type."""
         return keccak(text=cls.encode_type())
 
     def hash_struct(self):
+        """The hash of the struct.
+
+        hash_struct => keccak(type_hash || encode_data)
+        """
         return keccak(b''.join([self.type_hash(), self.encode_data()]))
 
     @classmethod
     def get_members(cls) -> List[Tuple[str, EIP712Type]]:
+        """A list of tuples of supported parameters.
+
+        Each tuple is (<parameter_name>, <parameter_type>). The list's order is determined by definition order.
+        """
         members = [m for m in cls.__dict__.items() if isinstance(m[1], EIP712Type)
                    or (isinstance(m[1], type) and issubclass(m[1], EIP712Struct))]
         return members
 
 
-def struct_to_json(domain: EIP712Struct, primary_struct: EIP712Struct):
+def struct_to_dict(primary_struct: EIP712Struct, domain: EIP712Struct):
+    """Convert a struct into a dictionary suitable for messaging.
+
+    Dictionary is of the form:
+        {
+            'primaryType': Name of the primary type,
+            'types': Definition of each included struct type (including the domain type)
+            'domain': Values for the domain struct,
+            'message': Values for the message struct,
+        }
+
+    The hash is constructed as:
+    `` b'\\x19\\x01' + domain_type_hash + struct_type_hash ``
+
+    :returns: A tuple in the form of: (message_dict, encoded_message_hash>)
+    """
     structs = {domain, primary_struct}
     primary_struct._gather_reference_structs(structs)
 
@@ -122,29 +173,46 @@ def struct_to_json(domain: EIP712Struct, primary_struct: EIP712Struct):
     return result, typed_data_hash
 
 
-def struct_from_json(json):
+def struct_from_dict(message_dict):
+    """Return the EIP712Struct object of the message and domain structs.
+
+    :returns: A tuple in the form of: (<primary struct>, <domain struct>)
+    """
     structs = dict()
     unfulfilled_struct_params = defaultdict(list)
 
-    for type_name in json['types']:
-        # Dynamically construct struct class from JSON
+    for type_name in message_dict['types']:
+        # Dynamically construct struct class from dict representation
         StructFromJSON = type(type_name, (EIP712Struct,), {})
 
-        for member in json['types'][type_name]:
+        for member in message_dict['types'][type_name]:
             # Either a basic solidity type is set, or None if referring to a reference struct (we'll fill that later)
             member_name = member['name']
             member_sol_type = from_solidity_type(member['type'])
             setattr(StructFromJSON, member_name, member_sol_type)
             if member_sol_type is None:
+                # Track the refs we'll need to set later.
                 unfulfilled_struct_params[type_name].append((member_name, member['type']))
 
         structs[type_name] = StructFromJSON
 
+    # Now that custom structs have been parsed, pass through again to set the references
     for struct_name, unfulfilled_member_names in unfulfilled_struct_params.items():
+        regex_pattern = r'([a-zA-Z0-9_]+)(\[(\d+)?\])?'
+
         struct_class = structs[struct_name]
         for name, type_name in unfulfilled_member_names:
-            ref_struct = structs[type_name]
-            setattr(struct_class, name, ref_struct)
+            match = re.match(regex_pattern, type_name)
+            base_type_name = match.group(1)
+            ref_struct = structs[base_type_name]
+            if match.group(2):
+                # The type is an array of the struct
+                arr_len = match.group(3) or 0  # length of 0 means the array is dynamically sized
+                setattr(struct_class, name, Array(ref_struct, arr_len))
+            else:
+                setattr(struct_class, name, ref_struct)
+
+    primary_struct = structs[message_dict['primaryType']]
+    domain_struct = structs['EIP712Domain']
 
-    primary_struct = structs[json['primaryType']]
-    return primary_struct(**json['message'])
+    return primary_struct(**message_dict['message']), domain_struct(**message_dict['domain'])

eip712_structs/types.py

@@ -1,10 +1,13 @@
 import re
+from typing import Union, Type
 
 from eth_utils.crypto import keccak
 from eth_utils.conversions import to_int
 
 
 class EIP712Type:
+    """The base type for members of a struct.
+    """
     def __init__(self, type_name: str):
         self.type_name = type_name
 
@@ -18,7 +21,7 @@ def encode_value(self, value) -> bytes:
 
 
 class Array(EIP712Type):
-    def __init__(self, member_type: EIP712Type, fixed_length: int = 0):
+    def __init__(self, member_type: Union[EIP712Type, Type[EIP712Type]], fixed_length: int = 0):
         if fixed_length == 0:
             type_name = f'{member_type.type_name}[]'
         else:
@@ -125,6 +128,7 @@ def encode_value(self, value: int):
 
 
 def from_solidity_type(solidity_type: str):
+    """Convert a string into the EIP712Type implementation. Basic types only."""
     pattern = r'([a-z]+)(\d+)?(\[(\d+)?\])?'
     match = re.match(pattern, solidity_type)
 
@@ -136,6 +140,9 @@ def from_solidity_type(solidity_type: str):
     is_array = match.group(3)
     array_len = match.group(4)
 
+    if type_name not in solidity_type_map:
+        return None
+
     base_type = solidity_type_map[type_name]
     if opt_len:
         type_instance = base_type(opt_len)

tests/test_domain_separator.py

@@ -1,11 +1,11 @@
 import os
-from eip712_structs import make_domain_separator
+from eip712_structs import make_domain
 from eth_utils.crypto import keccak
 
 
 def test_domain_sep_create():
     salt = os.urandom(32)
-    domain_struct = make_domain_separator(name='name', salt=salt)
+    domain_struct = make_domain(name='name', salt=salt)
 
     expected_result = 'EIP712Domain(string name,bytes32 salt)'
     assert domain_struct.encode_type() == expected_result
@@ -18,8 +18,8 @@ def test_domain_sep_types():
     salt = os.urandom(32)
     contract = os.urandom(20)
 
-    domain_struct = make_domain_separator(name='name', version='version', chainId=1,
-                                          verifyingContract=contract, salt=salt)
+    domain_struct = make_domain(name='name', version='version', chainId=1,
+                                verifyingContract=contract, salt=salt)
 
     encoded_data = [keccak(text='name'), keccak(text='version'), int(1).to_bytes(32, 'big', signed=False),
                     bytes(12) + contract, salt]

tests/test_message_json.py

@@ -1,11 +1,11 @@
-from eip712_structs import EIP712Struct, String, make_domain_separator, struct_to_json, struct_from_json
+from eip712_structs import EIP712Struct, String, make_domain, struct_to_dict, struct_from_dict
 
 
 def test_flat_struct_to_message():
     class Foo(EIP712Struct):
         s = String()
 
-    domain = make_domain_separator(name='domain')
+    domain = make_domain(name='domain')
     foo = Foo(s='foobar')
 
     expected_result = {
@@ -28,11 +28,11 @@ class Foo(EIP712Struct):
         }
     }
 
-    message, _ = struct_to_json(domain, foo)
+    message, _ = struct_to_dict(foo, domain)
     assert message == expected_result
 
     # Now test in reverse...
-    new_struct = struct_from_json(expected_result)
+    new_struct, domain = struct_from_dict(expected_result)
     assert new_struct.type_name == 'Foo'
 
     members_list = new_struct.get_members()
@@ -51,7 +51,7 @@ class Foo(EIP712Struct):
         s = String()
         bar = Bar
 
-    domain = make_domain_separator(name='domain')
+    domain = make_domain(name='domain')
 
     foo = Foo(
         s="foo",
@@ -88,11 +88,11 @@ class Foo(EIP712Struct):
         }
     }
 
-    message, _ = struct_to_json(domain, foo)
+    message, _ = struct_to_dict(foo, domain)
     assert message == expected_result
 
     # And test in reverse...
-    new_struct = struct_from_json(expected_result)
+    new_struct, new_domain = struct_from_dict(expected_result)
     assert new_struct.type_name == 'Foo'
 
     members = new_struct.get_members()