✨ Fix deserialization issues (#139)

* ✨ Create make method for ElectionContext

- Create functional style make method for ElectionContext
- Integrate it into Tests

* ✨ Create make method for CiphertextBallots

- Create make method for CiphertextAcceptedBallot and CiphertextBallot
- Update use cases
- Remove todo

* ✨ Add datetime to serialize / deserialize

* 🐛 Remove Proof serialization

* ✨ Allow conversion from str for mpz

- Cast str to int ahead of cast

* ✨ Alteration to dataclass usage

- Add equality statements
- Remove frozen 
- Use unsafe_hash to remove unnecessary hash function

* ♻️ Refactor all() for BallotStore

- Ballot store will now always return Ballots for all() method. This is the main use case and reduces the need to check for null around the store. Fixed attached integration test.

* ✅Deserialization Tests and Fixes

- ✨Remove InitVar for Plaintext Tally
- Remove InitVar for Selection
- Remove PostVar
- Plaintext Tally Changes
- Sample Generator Fixes

* 🐛 Handle incorrect from_json_file

* 🐛 Handle None deserialization

"None" created issues due Optional that also have custom deserialization. The solution for this is ensuring all NoneTypes are checked against a string before running default deserialization.
- Suppress Warning in serializable

* 📝Publish and Verify documentation

Author: keithrfung

README.md

@@ -81,6 +81,7 @@ Step-by-Step Process:
 2. [Encrypt Ballots]
 3. [Cast and Spoil]
 4. [Decrypt Tally]
+5. [Publish and Verify]
 
 ## Contributing
 
@@ -148,4 +149,6 @@ A huge thank you to those who helped to contribute to this project so far, inclu
 
 [Decrypt Tally]: https://github.com/microsoft/electionguard-python/blob/main/docs/4_Decrypt_Tally.md
 
+[Publish and Verify]: https://github.com/microsoft/electionguard-python/blob/main/docs/5_Publish_and_Verify.md)
+
 [MIT License]: https://github.com/microsoft/electionguard-python/blob/main/LICENSE

docs/5_Publish_and_Verify.md

@@ -0,0 +1,9 @@
+# Publish and Verify
+
+## Publish
+
+Publishing the election artifacts helps ensure third parties can verify the election. `publish.py` provides a publish method that serializes the key election artifacts. This makes use of the `Serializable` class exists to allow easy serializing to json files. These JSON files can then be shared and sent so others can verify. 
+
+## Verify
+
+Deserializing is the first step to verification. The `from_json` and `from_json_file` methods on `Serializable` are available to deserialize output JSON files back into their original classes. 

docs/index.md

@@ -78,6 +78,7 @@ Step-by-Step Process:
 2. [Encrypt Ballots](2_Encrypt_Ballots.md)
 3. [Cast and Spoil](3_Cast_and_Spoil.md)
 4. [Decrypt Tally](4_Decrypt_Tally.md)
+5. [Publish and Verify](5_Publish_and_Verify.md)
 
 ## ❓Questions
 

mkdocs.yml

@@ -19,4 +19,5 @@ nav:
         - 2. Encrypt Ballots: 2_Encrypt_Ballots.md
         - 3. Cast and Spoil: 3_Cast_and_Spoil.md
         - 4. Decrypt Tally: 4_Decrypt_Tally.md
+        - 5. Publish and Verify: 5_Publish_and_Verify.md
 theme: readthedocs

src/electionguard/ballot.py

@@ -1,8 +1,7 @@
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from datetime import datetime
 from distutils import util
 from enum import Enum
-from distutils import util
 from typing import Any, List, Optional, Protocol, runtime_checkable, Sequence
 
 from .chaum_pedersen import (
@@ -32,7 +31,7 @@ def _list_eq(
     )
 
 
-@dataclass
+@dataclass(eq=True, unsafe_hash=True)
 class ExtendedData(object):
     """
     ExtendedData represents any arbitrary data expressible as a string with a length.
@@ -43,18 +42,8 @@ class ExtendedData(object):
     value: str
     length: int
 
-    def __eq__(self, other: Any) -> bool:
-        return (
-            isinstance(other, ExtendedData)
-            and self.value == other.value
-            and self.length == other.length
-        )
 
-    def __ne__(self, other: Any) -> bool:
-        return not self.__eq__(other)
-
-
-@dataclass
+@dataclass(unsafe_hash=True)
 class PlaintextBallotSelection(ElectionObjectBase):
     """
     A BallotSelection represents an individual selection on a ballot.
@@ -128,6 +117,7 @@ def to_int(self) -> int:
     def __eq__(self, other: Any) -> bool:
         return (
             isinstance(other, PlaintextBallotSelection)
+            and self.object_id == other.object_id
             and self.vote == other.vote
             and self.is_placeholder_selection == other.is_placeholder_selection
             and self.extended_data == other.extended_data
@@ -152,7 +142,7 @@ class CiphertextSelection(Protocol):
     """The encrypted representation of the selection"""
 
 
-@dataclass
+@dataclass(eq=True, unsafe_hash=True)
 class CiphertextBallotSelection(
     ElectionObjectBase, CiphertextSelection, CryptoHashCheckable
 ):
@@ -312,7 +302,7 @@ def make_ciphertext_ballot_selection(
     )
 
 
-@dataclass
+@dataclass(unsafe_hash=True)
 class PlaintextBallotContest(ElectionObjectBase):
     """
     A PlaintextBallotContest represents the selections made by a voter for a specific ContestDescription
@@ -388,7 +378,7 @@ def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
 
-@dataclass
+@dataclass(unsafe_hash=True)
 class CiphertextBallotContest(ElectionObjectBase, CryptoHashCheckable):
     """
     A CiphertextBallotContest represents the selections made by a voter for a specific ContestDescription
@@ -423,6 +413,20 @@ class CiphertextBallotContest(ElectionObjectBase, CryptoHashCheckable):
     available selections for the contest, and that the proof was generated with the nonce
     """
 
+    def __eq__(self, other: Any) -> bool:
+        return (
+            isinstance(other, CiphertextBallotContest)
+            and self.object_id == other.object_id
+            and _list_eq(self.ballot_selections, other.ballot_selections)
+            and self.description_hash == other.description_hash
+            and self.crypto_hash == other.crypto_hash
+            and self.nonce == other.nonce
+            and self.proof == other.proof
+        )
+
+    def __ne__(self, other: Any) -> bool:
+        return not self.__eq__(other)
+
     def aggregate_nonce(self) -> Optional[ElementModQ]:
         """
         :return: an aggregate nonce for the contest composed of the nonces of the selections
@@ -578,7 +582,7 @@ def make_ciphertext_ballot_contest(
     )
 
 
-@dataclass
+@dataclass(unsafe_hash=True)
 class PlaintextBallot(ElectionObjectBase):
     """
     A PlaintextBallot represents a voters selections for a given ballot and ballot style
@@ -616,14 +620,16 @@ def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
 
-@dataclass
+@dataclass(unsafe_hash=True)
 class CiphertextBallot(ElectionObjectBase, CryptoHashCheckable):
     """
-    A CiphertextBallot represents a voters encrypted selections for a given ballot and ballot style
+    A CiphertextBallot represents a voters encrypted selections for a given ballot and ballot style.
 
     When a ballot is in it's complete, encrypted state, the `nonce` is the master nonce
     from which all other nonces can be derived to encrypt the ballot.  Allong with the `nonce`
     fields on `Ballotcontest` and `BallotSelection`, this value is sensitive.
+
+    Don't make this directly. Use `make_ciphertext_ballot` instead.
     :field object_id: A unique Ballot ID that is relevant to the external system
     """
 
@@ -639,22 +645,34 @@ class CiphertextBallot(ElectionObjectBase, CryptoHashCheckable):
     contests: List[CiphertextBallotContest]
     """List of contests for this ballot"""
 
-    tracking_hash: Optional[ElementModQ] = field(init=False)
+    tracking_hash: Optional[ElementModQ]
     """Unique ballot tracking hash for this ballot"""
 
-    timestamp: int = field(init=False)
+    timestamp: int
     """Timestamp at which the ballot encryption is generated in tick"""
 
-    crypto_hash: ElementModQ = field(init=False)
+    crypto_hash: ElementModQ
     """The hash of the encrypted ballot representation"""
 
-    nonce: Optional[ElementModQ] = field(default=None)
+    nonce: Optional[ElementModQ]
     """The nonce used to encrypt this ballot. Sensitive & should be treated as a secret"""
 
-    def __post_init__(self) -> None:
-        self.crypto_hash = self.crypto_hash_with(self.description_hash)
-        self.timestamp = to_ticks(datetime.utcnow())
-        self.generate_tracking(self.previous_tracking_hash)
+    def __eq__(self, other: Any) -> bool:
+        return (
+            isinstance(other, CiphertextBallot)
+            and self.object_id == other.object_id
+            and self.ballot_style == other.ballot_style
+            and self.description_hash == other.description_hash
+            and self.previous_tracking_hash == other.previous_tracking_hash
+            and _list_eq(self.contests, other.contests)
+            and self.tracking_hash == other.tracking_hash
+            and self.timestamp == other.timestamp
+            and self.crypto_hash == other.crypto_hash
+            and self.nonce == other.nonce
+        )
+
+    def __ne__(self, other: Any) -> bool:
+        return not self.__eq__(other)
 
     @staticmethod
     def nonce_seed(
@@ -680,16 +698,6 @@ def hashed_ballot_nonce(self) -> Optional[ElementModQ]:
 
         return self.nonce_seed(self.description_hash, self.object_id, self.nonce)
 
-    def generate_tracking(self, seed_hash: ElementModQ) -> None:
-        """
-        Generate a tracking hash from given hash and existing ballot hash
-        :param seed_hash: Seed hash whether starting or previous
-        """
-        self.previous_tracking_hash = seed_hash
-        self.tracking_hash = get_rotating_tracker_hash(
-            self.previous_tracking_hash, self.timestamp, self.crypto_hash
-        )
-
     def get_tracker_code(self) -> Optional[str]:
         """
         Get a tracker hash as a code in friendly readable words for sharing
@@ -787,51 +795,154 @@ class BallotBoxState(Enum):
     """
 
 
-@dataclass
+@dataclass(unsafe_hash=True)
 class CiphertextAcceptedBallot(CiphertextBallot):
     """
-    a `CiphertextAcceptedBallot` represents a ballot that is accepted for inclusion in election results.
-    an accepted ballot is or is about to be either cast or spoiled.
+    A `CiphertextAcceptedBallot` represents a ballot that is accepted for inclusion in election results.
+    An accepted ballot is or is about to be either cast or spoiled.
     The state supports the `BallotBoxState.UNKNOWN` enumeration to indicate that this object is mutable
     and has not yet been explicitly assigned a specific state.
 
-    note, additionally, this ballot includes all proofs but no nonces
+    Note, additionally, this ballot includes all proofs but no nonces.
+
+    Do not make this class directly. Use `make_ciphertext_accepted_ballot` or `from_ciphertext_ballot` instead.
     """
 
-    tracking_hash: Optional[ElementModQ] = None
-    timestamp: int = 0
-    state: BallotBoxState = field(default=BallotBoxState.UNKNOWN)
+    state: BallotBoxState
+
+    def __eq__(self, other: Any) -> bool:
+        return (
+            isinstance(other, CiphertextAcceptedBallot)
+            and super.__eq__(self, other)
+            and self.state == other.state
+        )
+
+    def __ne__(self, other: Any) -> bool:
+        return not self.__eq__(other)
+
+
+def make_ciphertext_ballot(
+    object_id: str,
+    ballot_style: str,
+    description_hash: ElementModQ,
+    previous_tracking_hash: Optional[ElementModQ],
+    contests: List[CiphertextBallotContest],
+    nonce: Optional[ElementModQ] = None,
+    timestamp: Optional[int] = None,
+    tracking_hash: Optional[ElementModQ] = None,
+) -> CiphertextBallot:
+    """
+    Makes a `CiphertextBallot`, initially in the state where it's neither been cast nor spoiled.
+
+    :param object_id: the object_id of this specific ballot
+    :param ballot_style: The `object_id` of the `BallotStyle` in the `Election` Manifest
+    :param description_hash: Hash of the election metadata
+    :param crypto_base_hash: Hash of the cryptographic election context
+    :param contests: List of contests for this ballot
+    :param timestamp: Timestamp at which the ballot encryption is generated in tick
+    :param previous_tracking_hash: Previous tracking hash or seed hash
+    :param nonce: optional nonce used as part of the encryption process
+    """
+
+    if len(contests) == 0:
+        log_warning(f"ciphertext ballot with no contests")
+
+    contest_hashes = [contest.crypto_hash for contest in contests]
+    contest_hash = hash_elems(object_id, description_hash, *contest_hashes)
+
+    timestamp = to_ticks(datetime.utcnow()) if timestamp is None else timestamp
+    if previous_tracking_hash is None:
+        previous_tracking_hash = description_hash
+    if tracking_hash is None:
+        tracking_hash = get_rotating_tracker_hash(
+            previous_tracking_hash, timestamp, contest_hash
+        )
+
+    return CiphertextBallot(
+        object_id=object_id,
+        ballot_style=ballot_style,
+        description_hash=description_hash,
+        previous_tracking_hash=previous_tracking_hash,
+        contests=contests,
+        tracking_hash=tracking_hash,
+        timestamp=timestamp,
+        nonce=nonce,
+        crypto_hash=contest_hash,
+    )
+
+
+def make_ciphertext_accepted_ballot(
+    object_id: str,
+    ballot_style: str,
+    description_hash: ElementModQ,
+    previous_tracking_hash: Optional[ElementModQ],
+    contests: List[CiphertextBallotContest],
+    tracking_hash: Optional[ElementModQ],
+    timestamp: Optional[int] = None,
+    state: BallotBoxState = BallotBoxState.UNKNOWN,
+) -> CiphertextAcceptedBallot:
     """
-    the state of the ballot
+    Makes a `CiphertextAcceptedBallot`, ensuring that no nonces are part of the contests.
+
+    :param object_id: the object_id of this specific ballot
+    :param ballot_style: The `object_id` of the `BallotStyle` in the `Election` Manifest
+    :param description_hash: Hash of the election metadata
+    :param previous_tracking_hash: Previous tracking hash or seed hash
+    :param contests: List of contests for this ballot
+    :param timestamp: Timestamp at which the ballot encryption is generated in tick
+    :param state: ballot box state
     """
 
-    def __post_init__(self,) -> None:
-        super().__post_init__()
+    if len(contests) == 0:
+        log_warning(f"ciphertext ballot with no contests")
 
-        # HACK: ISSUE: #45: Accepted ballots should not have a nonce assoiciated with them
+    contest_hashes = [contest.crypto_hash for contest in contests]
+    contest_hash = hash_elems(object_id, description_hash, *contest_hashes)
 
-        for contest in self.contests:
-            for selection in contest.ballot_selections:
-                selection.nonce = None
-            contest.nonce = None
+    timestamp = to_ticks(datetime.utcnow()) if timestamp is None else timestamp
+    if previous_tracking_hash is None:
+        previous_tracking_hash = description_hash
+    if tracking_hash is None:
+        tracking_hash = get_rotating_tracker_hash(
+            previous_tracking_hash, timestamp, contest_hash
+        )
 
-        self.nonce = None
+    # copy the contests and selections, removing all nonces
+    new_contests: List[CiphertextBallotContest] = []
+    for contest in contests:
+        new_selections = [
+            replace(selection, nonce=None) for selection in contest.ballot_selections
+        ]
+        new_contest = replace(contest, nonce=None, ballot_selections=new_selections)
+        new_contests.append(new_contest)
+
+    return CiphertextAcceptedBallot(
+        object_id=object_id,
+        ballot_style=ballot_style,
+        description_hash=description_hash,
+        previous_tracking_hash=previous_tracking_hash,
+        contests=new_contests,
+        tracking_hash=tracking_hash,
+        timestamp=timestamp,
+        crypto_hash=contest_hash,
+        nonce=None,
+        state=state,
+    )
 
 
 def from_ciphertext_ballot(
-    ballot: CiphertextBallot, state: BallotBoxState
+    ballot: CiphertextBallot, state: BallotBoxState = BallotBoxState.UNKNOWN
 ) -> CiphertextAcceptedBallot:
     """
-    Convert a `CiphertextBallot` into a `CiphertextAcceptedBallot` with the correct state
+    Convert a `CiphertextBallot` into a `CiphertextAcceptedBallot`, with all nonces removed.
     """
-
-    return CiphertextAcceptedBallot(
+    return make_ciphertext_accepted_ballot(
         object_id=ballot.object_id,
         ballot_style=ballot.ballot_style,
         description_hash=ballot.description_hash,
-        previous_tracking_hash=ballot.previous_tracking_hash,
         contests=ballot.contests,
-        tracking_hash=ballot.tracking_hash,
         timestamp=ballot.timestamp,
+        previous_tracking_hash=ballot.previous_tracking_hash,
+        tracking_hash=ballot.tracking_hash,
         state=state,
     )