Merge pull request #4 from ajrgrubbs/prep-1.0.0-api

Prep 1.0.0 api - big refactor to make this correct and usable
- Significant test improvements, including parity tests w/ Docker+Ganache
- Code coverage integration w/ TravisCI+Coveralls
- Several bugfixes

Author: ajrgrubbs

.gitignore

@@ -1,4 +1,7 @@
+.eggs/
 *.egg-info/
 dist/
 build/
 .pytest_cache/
+
+tests/contracts/build

.travis.yml

@@ -5,4 +5,10 @@ python:
   - "3.6"
   - "3.7"
 script:
-  - python setup.py test
+  - python setup.py test -a --cov=eip712_structs
+services:
+  - docker
+before_install:
+  - docker-compose up -d
+after_success:
+  - python setup.py coveralls

API.md

@@ -0,0 +1,17 @@
+# API
+
+### `class EIP712Struct`
+#### Important methods
+- `.to_message(domain: EIP712Struct)` - Convert the struct (and given domain struct) into the standard EIP-712 message structure.
+- `.signable_bytes(domain: EIP712Struct)` - Get the standard EIP-712 bytes hash, suitable for signing.
+- `.from_message(message_dict: dict)` **(Class method)** - Given a standard EIP-712 message dictionary (such as produced from `.to_message`), returns a NamedTuple containing the `message` and `domain` EIP712Structs.
+
+#### Other stuff
+- `.encode_value()` - Returns a `bytes` object containing the ordered concatenation of each members bytes32 representation.
+- `.encode_type()` **(Class method)** - Gets the "signature" of the struct class. Includes nested structs too!
+- `.type_hash()` **(Class method)** - The keccak256 hash of the result of `.encode_type()`.
+- `.hash_struct()` - Gets the keccak256 hash of the concatenation of `.type_hash()` and `.encode_value()`
+- `.get_data_value(member_name: str)` - Get the value of the given struct member
+- `.set_data_value(member_name: str, value: Any)` - Set the value of the given struct member
+- `.data_dict()` - Returns a dictionary with all data in this struct. Includes nested struct data, if exists.
+- `.get_members()` **(Class method)** - Returns a dictionary mapping each data member's name to it's type.

README.md

@@ -1,4 +1,4 @@
-# EIP-712 Structs  [![Build Status](https://travis-ci.org/ajrgrubbs/py-eip712-structs.svg?branch=master)](https://travis-ci.org/ajrgrubbs/py-eip712-structs)
+# EIP-712 Structs  [![Build Status](https://travis-ci.org/ajrgrubbs/py-eip712-structs.svg?branch=master)](https://travis-ci.org/ajrgrubbs/py-eip712-structs) [![Coverage Status](https://coveralls.io/repos/github/ajrgrubbs/py-eip712-structs/badge.svg?branch=master)](https://coveralls.io/github/ajrgrubbs/py-eip712-structs?branch=master)
 
 A python interface for simple EIP-712 struct construction.
 
@@ -17,47 +17,43 @@ https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md
 pip install eip712-structs
 ```
 
-## Basic Usage
-
-Our desired struct:
-```
-struct Message {
-    address to;
-    string contents;
+## Quickstart
+Say we want to represent the following struct, convert it to a message and sign it:
+```text
+struct MyStruct {
+    string some_string;
+    uint some_number;
 }
 ```
 
-Python representation:
+With this module:
 ```python
-from eip712_structs import EIP712Struct, Address, String, make_domain, struct_to_message
-
-class Message(EIP712Struct):
-    to = Address()
-    contents = String()
-    
-enctyp = Message.encode_type()  # 'Mail(address to,string contents)'
+# Make a unique domain
+from eip712_structs import make_domain
+domain = make_domain(name='Some name', version='1.0.0')
 
-msg = Message(to='0xdead...beef', contents='hello world')
-msg.encode_data()  # The struct's data in encoded form
+# Define your struct type
+from eip712_structs import EIP712Struct, String, Uint
+class MyStruct(EIP712Struct):
+    some_string = String()
+    some_number = Uint(256)
 
-domain = make_domain(name='example')
-msg_body, signable_bytes = struct_to_message(msg, domain)
+# Create an instance with some data
+mine = MyStruct(some_string='hello world', some_number=1234)
 
-# msg_body is a standardized dict with keys primaryType, types, domain, and message
-# suitable for converting to JSON for making requests
+# Into a message dict (serializable to JSON) - domain required
+my_msg = mine.to_message(domain)
 
-# `signable bytes` is a deterministic bytes representation of the struct
-# Suitable for hashing or signing
-#   bytes 0-1: b'\x19\x01'
-#   bytes 2-33: domain separator (hash of domain type and data)
-#   bytes 34-65: hash of struct type and data
+# Into signable bytes - domain required
+my_bytes = mine.signable_bytes(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
+from eip712_structs import EIP712Struct, Address
 class Message(EIP712Struct):
     pass
 
@@ -66,27 +62,15 @@ setattr(Message, 'from', Address())
 ```
 
 #### The domain separator
-Messages also require a domain struct. A helper method exists for this purpose.
+EIP-712 specifies a domain struct, to differentiate between identical structs that may be unrelated.
+A helper method exists for this purpose.
 All values to the `make_domain()`
 function are optional - but at least one must be defined. If omitted, the resulting
 domain struct's definition leaves out the parameter entirely.
 
 The full signature: <br/>
 `make_domain(name: string, version: string, chainId: uint256, verifyingContract: address, salt: bytes32)`
 
-```python
-from eip712_structs import EIP712Struct, String, make_domain, struct_to_message
-
-domain = make_domain(name='my_domain')
-
-class Foo(EIP712Struct):
-    bar = String()
-
-foo = Foo(bar='baz')
-
-message_dict, message_hash = struct_to_message(foo, domain)
-```
-
 
 ## Member Types
 
@@ -107,6 +91,8 @@ Uint(N)    # 'uintN' - N must be a multiple of 8, from 8 to 256
 
 Use like:
 ```python
+from eip712_structs import EIP712Struct, Address, Bytes
+
 class Foo(EIP712Struct):
     member_name_0 = Address()
     member_name_1 = Bytes(5)
@@ -119,6 +105,8 @@ Usage is almost the same - the difference is you don't "instantiate" the class.
 
 Example:
 ```python
+from eip712_structs import EIP712Struct, String
+
 class Dog(EIP712Struct):
     name = String()
     breed = String()
@@ -127,20 +115,23 @@ class Person(EIP712Struct):
     name = String()
     dog = Dog  # Take note - no parentheses!
 
+# Dog "stands alone"
 Dog.encode_type()     # Dog(string name,string breed)
+
+# But Person knows how to include Dog
 Person.encode_type()  # Person(string name,Dog dog)Dog(string name,string breed)
 ```
 
-Instantiating the structs with nested values may be done like:
+Instantiating the structs with nested values may be done a couple different ways:
 
 ```python
 # Method one: set it to a struct
 dog = Dog(name='Mochi', breed='Corgi')
-person = Person(name='Ed', dog=dog)
+person = Person(name='E.M.', dog=dog)
 
 # Method two: set it to a dict - the underlying struct is built for you
 person = Person(
-    name='Ed',
+    name='E.M.',
     dog={
         'name': 'Mochi',
         'breed': 'Corgi',
@@ -173,3 +164,6 @@ Install dependencies:
 
 Run tests:
 - `python setup.py test`
+- Some tests expect an active local ganache chain. Compile contracts and start the chain using docker:
+    - `docker-compose up -d`
+    - If the chain is not detected, then they are skipped.

docker-compose.yml

@@ -0,0 +1,17 @@
+---
+version: "3"
+services:
+  ganache:
+    image: "trufflesuite/ganache-cli:latest"
+    # Corresponding account address: 0xD68D840e1e971750E6d45049ff579925456d5893
+    command: "--account=\"0x3660582119566511de16f4dcf397fa324b27bd6247f653cf0298a0993f3432ed,100000000000000000000\""
+    ports:
+      - "8545:8545"
+    depends_on:
+      - compiler
+
+  compiler:
+    image: "ethereum/solc:stable"
+    command: "--abi --bin -o /tmp/contracts/build --overwrite /tmp/contracts/hash_test_contract.sol"
+    volumes:
+      - ./tests/contracts:/tmp/contracts

eip712_structs/__init__.py

@@ -1,5 +1,5 @@
 from eip712_structs.domain_separator import make_domain
-from eip712_structs.struct import EIP712Struct, struct_from_message, struct_to_message
+from eip712_structs.struct import EIP712Struct
 from eip712_structs.types import Address, Array, Boolean, Bytes, Int, String, Uint
 
 name = 'eip712-structs'

eip712_structs/domain_separator.py

@@ -8,7 +8,7 @@ def make_domain(name=None, version=None, chainId=None, verifyingContract=None, s
     """
 
     if all(i is None for i in [name, version, chainId, verifyingContract, salt]):
-        raise ValueError('At least on argument must be given.')
+        raise ValueError('At least one argument must be given.')
 
     class EIP712Domain(eip712_structs.EIP712Struct):
         pass