pp-phragmen 0.1.0__py3-none-any.whl

pp_phragmen-0.1.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: pp-phragmen
+Version: 0.1.0
+Summary: Privacy-Preserving Phragmén Voting via Secure Multi-Party Computation
+Author-email: Liran Shem-Tov <liranst13@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/liranst13/Phragmen_Voting
+Requires-Python: >=3.10
+Requires-Dist: mpc-secret-shares>=0.2.0

pp_phragmen-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+protocol/__init__.py,sha256=bM6PzNTHCypxU6yI6Uc8d5AGce3foao77t0yDBpqWYo,53
+protocol/algorithm1_permutation.py,sha256=VD_3Ex9DlkgSA2Bbd-okOdyNUwMpBCCr_CDMm1zv844,5501
+protocol/algorithm2_validation.py,sha256=ojsJQe-GukJ9vUkk8ZgLDWgIUeqLJdMJURmrogMCsNk,3756
+protocol/algorithm3_initialization.py,sha256=uyfIRaSWMBL8iPz2H0xIVVIDEGVKS-38FdVMz9NxJXc,1861
+protocol/algorithm4_score.py,sha256=iBqSF8U1tu723cbbbesR5G3t6ZnIj91gmz7QBsSgc0w,4442
+protocol/algorithm5_find_min.py,sha256=YVJTnLhdTp0KYQmcb9ZJrGx314PTUA5qUIk96zVLFoo,3789
+protocol/algorithm6_one_hot.py,sha256=trCZmnNjIWCFCdJojA8-tKQf7X6Y3uo5QgBgI4gLejU,5509
+protocol/algorithm7_wallet_update.py,sha256=omWdPS5lUY7WbRqUnqW3-55zihkMTzZ1rQekPWq0d3g,5991
+protocol/algorithm8_reconstruct_winner.py,sha256=_VebyU6ClNEvFuDoZtV-nNSpJ7CyViBJEJ5FuVxnHk0,3285
+protocol/state_manager.py,sha256=Wx9K_68Ix31IW_xPGrP-up8KTC57MVJSB2v6htzXkRg,4831
+protocol/types.py,sha256=wVANfsSPTGgpHtZK7SZJBHlX_vqwOA_58qoGeRDE6to,527
+pp_phragmen-0.1.0.dist-info/METADATA,sha256=lltZBU52UnAlst2QD6k-oax2I3Cu2SD7k6a8sdL-Y2M,340
+pp_phragmen-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pp_phragmen-0.1.0.dist-info/top_level.txt,sha256=uy1jQLBxIt2TPgpqghfyarfAM3CLAYNky5SOdYnPSCg,9
+pp_phragmen-0.1.0.dist-info/RECORD,,

pp_phragmen-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pp_phragmen-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+protocol

protocol/__init__.py

@@ -0,0 +1 @@
+# PP-Phragmén voting protocol — Algorithms 1–8.

protocol/algorithm1_permutation.py

@@ -0,0 +1,147 @@
+"""Algorithm 1 — Oblivious Candidate Permutation.
+
+Reference: Algorithm 1 in "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting", Section 5.1 (page 8).  Run once at setup, before any
+election period.  No MPC secure operations are required.
+
+Each tallying party P_d (d ∈ [D]):
+  1. Samples a secret random seed s_d ← {0,1}^λ.
+  2. Broadcasts a commitment com_d = SHA-256(s_d ‖ d).
+  3. Reveals s_d; all other parties verify the commitment.
+
+The shared seed is s = s_1 ⊕ … ⊕ s_D, and the public permutation is
+derived by running a Fisher-Yates shuffle seeded with s.
+"""
+
+import hashlib
+import os
+import random
+from typing import List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers (exposed for unit-testing)
+# ---------------------------------------------------------------------------
+
+def _commitment(seed: bytes, party_index: int) -> bytes:
+    """Return SHA-256(seed ‖ party_index) as defined in Algorithm 1, Line 3.
+
+    Args:
+        seed: The party's random seed bytes.
+        party_index: Zero-based party index, encoded as a big-endian 4-byte
+            unsigned integer before hashing.
+
+    Returns:
+        32-byte SHA-256 digest.
+    """
+    return hashlib.sha256(seed + party_index.to_bytes(4, "big")).digest()
+
+
+def _verify_commitments(seeds: List[bytes], commitments: List[bytes]) -> None:
+    """Verify every revealed seed against its published commitment.
+
+    Implements the verification step in Algorithm 1, Lines 6–8.
+
+    Args:
+        seeds: Revealed seeds, one per party (zero-indexed).
+        commitments: Published commitments in the same order.
+
+    Raises:
+        ValueError: If any seed does not reproduce its commitment.
+    """
+    for d, (seed, com) in enumerate(zip(seeds, commitments)):
+        if _commitment(seed, d) != com:
+            raise ValueError(
+                f"commitment mismatch for party {d}: "
+                "revealed seed does not match published commitment"
+            )
+
+
+def _fisher_yates(combined_seed: bytes, num_candidates: int) -> List[int]:
+    """Produce a uniformly random permutation of [0, M) via Fisher-Yates.
+
+    Implements Algorithm 1, Line 10.  The combined seed is converted to an
+    integer and used to seed Python's Mersenne-Twister PRNG, which then
+    drives `random.shuffle` (a Fisher-Yates implementation).
+
+    Args:
+        combined_seed: XOR of all party seeds (Algorithm 1, Line 9).
+        num_candidates: M — size of the candidate set.
+
+    Returns:
+        A permutation of [0, M) as a list of length M.
+    """
+    seed_int = int.from_bytes(combined_seed, "big")
+    rng = random.Random(seed_int)
+    pi = list(range(num_candidates))
+    rng.shuffle(pi)
+    return pi
+
+
+# ---------------------------------------------------------------------------
+# Algorithm 1
+# ---------------------------------------------------------------------------
+
+def algorithm_1_oblivious_candidate_permutation(
+    security_bits: int,
+    num_candidates: int,
+    num_parties: int,
+    seeds: Optional[List[bytes]] = None,
+) -> List[int]:
+    """Generate a public uniformly random permutation of candidates.
+
+    Algorithm 1 of "Fairness Without Exposure: Privacy-Preserving Phragmén
+    Voting", Section 5.1.
+
+    Each party commits to a random seed via SHA-256, then reveals it.  The
+    combined (XOR) seed drives a Fisher-Yates shuffle that produces the
+    oblivious permutation π used by Algorithm 6 for tie-breaking.
+
+    Args:
+        security_bits: λ — bit-length of each party's random seed.
+            Must be a positive multiple of 8.
+        num_candidates: M — number of candidates to permute.
+        num_parties: D (= n in MPC notation) — number of tallying parties.
+        seeds: Optional list of D byte-strings each of length
+            ``security_bits // 8``.  When None every party samples a fresh
+            random seed.  Supply explicit seeds only in tests to obtain
+            deterministic output.
+
+    Returns:
+        A permutation π of [0, M) as a list of M distinct integers.
+
+    Raises:
+        ValueError: If ``seeds`` has wrong length or wrong element sizes.
+        ValueError: If any revealed seed does not match its commitment
+            (simulates an abort on cheating during the reveal phase).
+    """
+    seed_len = security_bits // 8
+
+    # Lines 1-3: every party samples a seed and publishes a commitment.
+    if seeds is None:
+        seeds = [os.urandom(seed_len) for _ in range(num_parties)]
+    else:
+        if len(seeds) != num_parties:
+            raise ValueError(
+                f"expected {num_parties} seeds, got {len(seeds)}"
+            )
+        for d, s in enumerate(seeds):
+            if len(s) != seed_len:
+                raise ValueError(
+                    f"seed for party {d} has length {len(s)}, "
+                    f"expected {seed_len} (security_bits={security_bits})"
+                )
+
+    commitments = [_commitment(s, d) for d, s in enumerate(seeds)]  # Line 3
+
+    # Lines 4-8: reveal phase — every party broadcasts its seed and all
+    # others verify it against the stored commitment.
+    _verify_commitments(seeds, commitments)  # Lines 6-8
+
+    # Line 9: derive the shared seed by XOR-ing all party seeds.
+    combined = seeds[0]
+    for s in seeds[1:]:
+        combined = bytes(a ^ b for a, b in zip(combined, s))
+
+    # Lines 10-11: Fisher-Yates shuffle seeded with the combined seed.
+    return _fisher_yates(combined, num_candidates)

protocol/algorithm2_validation.py

@@ -0,0 +1,95 @@
+"""Algorithm 2 — Input Validation, Sanitization & Compaction.
+
+Reference: Algorithm 2 in "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting", Section 5.2 (page 9).  Run once at setup (or per period
+if ballots are re-submitted).
+
+For each ballot entry B_{n,m} the protocol verifies B_{n,m} ∈ {0, 1} by
+checking that B_{n,m}·(B_{n,m} − 1) = 0 using a single SecureMult followed
+by a public Reconstruct.  Voters whose ballot fails this check are flagged as
+cheaters and removed; the remaining honest-voter rows are compacted into a
+fresh matrix B̂ of size N_valid × M.
+"""
+
+from typing import List, Tuple
+
+from mpc_secret_shares import (
+    reconstruct,
+    secure_mult,
+    shares_one,
+    shares_sub,
+)
+from protocol.types import BallotMatrix, Shares
+
+
+def algorithm_2_input_validation(
+    B_shares: BallotMatrix,
+    n: int,
+    t: int,
+    p: int,
+) -> Tuple[BallotMatrix, int]:
+    """Validate ballot entries, remove cheating voters, and compact the matrix.
+
+    Algorithm 2 of "Fairness Without Exposure: Privacy-Preserving Phragmén
+    Voting", Section 5.2.
+
+    For each entry B_{n,m} the protocol computes
+    ``[[u]] = SecureMult([[B]], [[B]] − [[1]])``
+    and reconstructs u publicly.  Because u = B·(B−1) equals 0 if and only
+    if B ∈ {0, 1}, a non-zero u identifies voter n as a cheater.  The first
+    invalid entry short-circuits the inner loop (Lines 7–8 of the paper).
+
+    Args:
+        B_shares: An N × M matrix of (t,n)-sharings, where
+            ``B_shares[voter][candidate]`` is the sharing of B_{n,m}.
+            Voters are zero-indexed; the paper uses 1-indexed notation.
+        n: Number of MPC parties (talliers).
+        t: Reconstruction threshold.
+        p: Prime field modulus.
+
+    Returns:
+        A tuple ``(B_hat, n_valid)`` where:
+
+        * ``B_hat`` is an N_valid × M matrix of (t,n)-sharings containing
+          only the rows of honest voters, in their original relative order
+          and re-indexed from 0.
+        * ``n_valid`` is the count of honest voters (public after this step).
+    """
+    num_voters = len(B_shares)
+    num_candidates = len(B_shares[0]) if num_voters > 0 else 0
+
+    cheaters: set[int] = set()
+    one_shares: Shares = shares_one(n)  # [[1]] — shared public constant
+
+    # Lines 2-8: for each voter, check every ballot entry until a violation
+    # is found.  The inner loop breaks on the first detected cheat (Line 8).
+    for voter in range(num_voters):                                  # Line 2
+        for cand in range(num_candidates):                           # Line 3
+            b_nm: Shares = B_shares[voter][cand]
+
+            # Line 4: [[u]] = SecureMult([[B]], [[B]] − [[1]])
+            # [[B]] − [[1]] is a local operation (affine subtraction).
+            b_minus_one: Shares = shares_sub(b_nm, one_shares, p)
+            u_shares: Shares = secure_mult(
+                b_nm, b_minus_one, n, t, p
+            )
+
+            # Line 5: u ← Reconstruct([[u]])  — publicly revealed.
+            u_val: int = reconstruct(u_shares[:t], p)
+
+            # Lines 6-8: non-zero u means B ∉ {0, 1} → voter is a cheater.
+            if u_val != 0:                                           # Line 6
+                cheaters.add(voter)                                  # Line 7
+                break                                                # Line 8
+
+    # Line 9: N_valid = N − |Cheaters|.
+    n_valid: int = num_voters - len(cheaters)
+
+    # Lines 10-15: compact honest voters into B_hat, preserving row order.
+    B_hat: BallotMatrix = [
+        B_shares[voter]
+        for voter in range(num_voters)
+        if voter not in cheaters
+    ]
+
+    return B_hat, n_valid                                            # Line 16

protocol/algorithm3_initialization.py

@@ -0,0 +1,56 @@
+"""Algorithm 3 — Initialization.
+
+Reference: Algorithm 3 in "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting", Section 5.3 (page 9).  Run once, prior to the first
+election period only.
+
+Sets the global denominator Δ to 1 and every voter's scaled wallet W̃_i to 0,
+establishing the invariant w_n = W̃_n / Δ = 0 for all voters at the start.
+No MPC secure operations are required — both values are public constants.
+"""
+
+from typing import List, Tuple
+
+from mpc_secret_shares import (
+    shares_one,
+    shares_zero,
+)
+from protocol.types import Shares
+
+
+def algorithm_3_initialization(
+    n_valid: int,
+    n: int,
+    t: int,
+    p: int,
+) -> Tuple[Shares, List[Shares]]:
+    """Initialise the global denominator and all voter wallets to their
+    starting values.
+
+    Algorithm 3 of "Fairness Without Exposure: Privacy-Preserving Phragmén
+    Voting", Section 5.3.
+
+    At the start of the first period all rational wallet balances w_n are 0.
+    The protocol represents each balance as w_n = W̃_n / Δ, so initialising
+    Δ = 1 and W̃_n = 0 satisfies the invariant without any field division.
+
+    Args:
+        n_valid: N_valid — number of honest voters after Algorithm 2.
+        n: Number of MPC parties (talliers).
+        t: Reconstruction threshold.
+        p: Prime field modulus.
+
+    Returns:
+        A tuple ``(delta_shares, wallet_shares)`` where:
+
+        * ``delta_shares`` is a (t,n)-sharing of Δ = 1  (Algorithm 3, Line 1).
+        * ``wallet_shares`` is a list of N_valid (t,n)-sharings, each
+          encoding W̃_i = 0  (Algorithm 3, Lines 2–3).
+    """
+    # Line 1: [[Δ]] ← [[1]]
+    delta_shares: Shares = shares_one(n)
+
+    # Lines 2-3: [[W̃_i]] ← [[0]] for every honest voter i.
+    wallet_shares: List[Shares] = [shares_zero(n) for _ in range(n_valid)]
+
+    return delta_shares, wallet_shares

protocol/algorithm4_score.py

@@ -0,0 +1,116 @@
+"""Algorithm 4 — Oblivious Score Computation (Global Denominator).
+
+Reference: Algorithm 4 in "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting", Section 5.4 (pages 10–11).  Run every election period.
+
+Computes per-candidate scores in numerator/denominator form using the
+common-denominator strategy (Section 5, page 7):
+
+    Score_m = Score_m^num / Score_m^den
+            = (Δ − T̃_m) / (|A(m)| · Δ)
+
+where T̃_m = Σ_{i ∈ A(m)} W̃_i is the sum of scaled wallets of candidate
+m's supporters, and Δ is the shared global denominator.  This eliminates
+per-voter cross-multiplication from the critical path (O(MN) SecureMult
+instead of O(MN²)).
+
+Precondition (paper Section 5, page 8): at least one candidate must have
+|A(m)| > 0 (i.e. at least one voter approves at least one candidate).
+The degenerate all-zero ballot matrix is explicitly excluded by the paper;
+calling this function with n_valid=0 or all-zero ballots is outside the
+paper's guaranteed domain and will produce Score^den = 0 for every candidate,
+making Algorithm 5's comparison meaningless.
+"""
+
+from typing import List, Tuple
+
+from mpc_secret_shares import (
+    secure_mult,
+    shares_add,
+    shares_sub,
+    shares_zero,
+)
+from protocol.types import BallotMatrix, ScorePair, Shares
+
+
+def algorithm_4_score_computation(
+    B_hat: BallotMatrix,
+    wallet_shares: List[Shares],
+    delta_shares: Shares,
+    n_valid: int,
+    num_candidates: int,
+    n: int,
+    t: int,
+    p: int,
+) -> Tuple[List[ScorePair], List[Shares], List[Shares]]:
+    """Compute per-candidate scores and supporting data for the current period.
+
+    Algorithm 4 of "Fairness Without Exposure: Privacy-Preserving Phragmén
+    Voting", Section 5.4.
+
+    For each candidate m the algorithm accumulates:
+
+    * ``[[|A(m)|]]`` — supporter count (local additions of ballot bits).
+    * ``[[T̃_m]]`` — scaled wallet sum of supporters (SecureMult per voter).
+
+    Then it derives the score representation from Equation (4) of the paper:
+
+    * ``[[Score_m^num]] = [[Δ]] − [[T̃_m]]``       (local subtraction)
+    * ``[[Score_m^den]] = SecureMult([[Δ]], [[|A(m)|]])``
+
+    Args:
+        B_hat: N_valid × M matrix of (t,n)-sharings of B̂_{i,m} ∈ {0,1}.
+        wallet_shares: List of N_valid (t,n)-sharings of the scaled wallets
+            W̃_i.  Index matches the row index of B_hat.
+        delta_shares: (t,n)-sharing of the global denominator Δ.
+        n_valid: Number of valid voters N_valid.  Must equal len(B_hat).
+        num_candidates: Number of candidates M.
+        n: Number of MPC parties.
+        t: Reconstruction threshold.
+        p: Prime field modulus.
+
+    Returns:
+        A tuple ``(scores, A_shares, T_tilde_shares)`` where:
+
+        * ``scores[m]`` is ``(Score_m^num, Score_m^den)`` — a ScorePair of
+          (t,n)-sharings for candidate m (Algorithm 4, Lines 8–9).
+        * ``A_shares[m]`` is ``[[|A(m)|]]`` — supporter count for candidate m
+          (Line 5), needed by Algorithm 7.
+        * ``T_tilde_shares[m]`` is ``[[T̃_m]]`` — scaled wallet sum for
+          candidate m (Line 7), needed by Algorithm 7.
+    """
+    scores: List[ScorePair] = []
+    A_shares: List[Shares] = []
+    T_tilde_shares: List[Shares] = []
+
+    for m in range(num_candidates):                               # Line 1
+        A_m: Shares = shares_zero(n)                             # Line 2
+        T_m: Shares = shares_zero(n)                             # Line 3
+
+        for i in range(n_valid):                                  # Line 4
+            b_im: Shares = B_hat[i][m]
+
+            # Line 5: [[|A(m)|]] ← [[|A(m)|]] + [[B̂_{i,m}]]  (local)
+            A_m = shares_add(A_m, b_im, p)
+
+            # Line 6: [[contrib]] ← SecureMult([[B̂_{i,m}]], [[W̃_i]])
+            contrib: Shares = secure_mult(
+                b_im, wallet_shares[i], n, t, p
+            )
+
+            # Line 7: [[T̃_m]] ← [[T̃_m]] + [[contrib]]  (local)
+            T_m = shares_add(T_m, contrib, p)
+
+        # Line 8: [[Score_m^num]] ← [[Δ]] − [[T̃_m]]  (local)
+        score_num: Shares = shares_sub(delta_shares, T_m, p)
+
+        # Line 9: [[Score_m^den]] ← SecureMult([[Δ]], [[|A(m)|]])
+        score_den: Shares = secure_mult(
+            delta_shares, A_m, n, t, p
+        )
+
+        scores.append((score_num, score_den))
+        A_shares.append(A_m)
+        T_tilde_shares.append(T_m)
+
+    return scores, A_shares, T_tilde_shares

protocol/algorithm5_find_min.py

@@ -0,0 +1,109 @@
+"""Algorithm 5 — Find Minimum Score.
+
+Reference: Algorithm 5 in "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting", Section 5.5 (page 12).  Run every election period.
+
+Finds the winning (minimum) score among all M candidates using a sequential
+left-to-right reduction.  At each step the running best is compared against
+the next candidate via cross-multiplication to avoid division:
+
+    Score_m < Score_best  iff  Score_m^num · best^den < best^num · Score_m^den
+
+Both cross-products are non-negative (Lemma 7.1), so SecureLT is valid.
+
+Round complexity: O(M) — this sequential chain is the dominant latency
+bottleneck of the per-period loop (paper Remark 6.1).
+"""
+
+from typing import List, Tuple
+
+from mpc_secret_shares import (
+    secure_mult,
+    secure_lt,
+    shares_add,
+    shares_sub,
+)
+from protocol.types import ScorePair, Shares
+
+
+def algorithm_5_find_minimum_score(
+    scores: List[ScorePair],
+    n: int,
+    t: int,
+    p: int,
+) -> ScorePair:
+    """Find the shared winning (minimum) score across all candidates.
+
+    Algorithm 5 of "Fairness Without Exposure: Privacy-Preserving Phragmén
+    Voting", Section 5.5.
+
+    Maintains a running best ``(best^num, best^den)`` initialised to the
+    first candidate's score (Lines 1–2).  For each subsequent candidate m
+    (Lines 3–8) the algorithm:
+
+    1. Computes two cross-products to compare scores without division
+       (Lines 4–5).
+    2. Calls SecureLT to get a shared bit β_m = 1_{Score_m < Score_best}
+       (Line 6).
+    3. Updates the running best via a multiplexer:
+       ``best ← best + β_m · (Score_m − best)``
+       which selects Score_m when β_m = 1 and leaves best unchanged when 0
+       (Lines 7–8).
+
+    Args:
+        scores: List of M ScorePairs ``(Score_m^num, Score_m^den)`` produced
+            by Algorithm 4.  Must contain at least one entry.
+        n: Number of MPC parties.
+        t: Reconstruction threshold.
+        p: Prime field modulus.
+
+    Returns:
+        A ScorePair ``(Score*^num, Score*^den)`` — a (t,n)-sharing of the
+        minimum score among all candidates.
+
+    Raises:
+        ValueError: If ``scores`` is empty (no candidates).
+    """
+    if not scores:
+        raise ValueError("scores must be non-empty: at least one candidate required")
+
+    # Lines 1-2: initialise the running best to the first candidate's score.
+    best_num: Shares = scores[0][0]
+    best_den: Shares = scores[0][1]
+
+    # Lines 3-8: compare each subsequent candidate against the running best.
+    for m in range(1, len(scores)):                                  # Line 3
+        score_num: Shares = scores[m][0]
+        score_den: Shares = scores[m][1]
+
+        # Line 4: cross_a = Score_m^num · best^den
+        cross_a: Shares = secure_mult(
+            score_num, best_den, n, t, p
+        )
+
+        # Line 5: cross_b = best^num · Score_m^den
+        cross_b: Shares = secure_mult(
+            best_num, score_den, n, t, p
+        )
+
+        # Line 6: β_m = SecureLT(cross_a, cross_b)
+        # β_m = 1  iff  Score_m < Score_best  (candidate m is a better winner)
+        beta_m: Shares = secure_lt(cross_a, cross_b, n, t, p)
+
+        # Line 7: best^num ← best^num + β_m · (Score_m^num − best^num)
+        diff_num: Shares = shares_sub(score_num, best_num, p)
+        best_num = shares_add(
+            best_num,
+            secure_mult(beta_m, diff_num, n, t, p),
+            p,
+        )
+
+        # Line 8: best^den ← best^den + β_m · (Score_m^den − best^den)
+        diff_den: Shares = shares_sub(score_den, best_den, p)
+        best_den = shares_add(
+            best_den,
+            secure_mult(beta_m, diff_den, n, t, p),
+            p,
+        )
+
+    return best_num, best_den                                        # Lines 9-10

protocol/algorithm6_one_hot.py

@@ -0,0 +1,135 @@
+"""Algorithm 6 — One-Hot Winner Identification with Permuted Tie-Break.
+
+Reference: Algorithm 6 in "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting", Section 5.6 (pages 12–13).  Run every election period.
+
+Produces a one-hot shared indicator {[[χ_m]]}_{m ∈ [M]} with χ_{m*} = 1 for
+the unique elected candidate m* and χ_m = 0 for all others.
+
+Two sequential passes:
+
+Pass 1 (Lines 1–4, O(1) rounds — all M triples are independent and batched):
+  For each candidate m, test whether Score_m equals the winning score Score*
+  via cross-multiplication followed by SecureIsZero:
+      α_m = Score_m^num · Score*^den
+      β_m = Score*^num · Score_m^den
+      e_m = SecureIsZero(α_m − β_m)       ← 1 iff Score_m = Score*
+
+Pass 2 (Lines 5–11, O(M) rounds — sequential prefix scan):
+  Walk the candidates in the public permutation order π.  The running prefix
+  accumulator [[s]] starts at 0; the first π-ordered candidate m with e_m = 1
+  gets χ_m = 1 and sets s = 1, suppressing all subsequent matches via
+      χ_m = SecureMult(e_m, [[1]] − [[s]])
+
+The permutation π (from Algorithm 1) breaks ties uniformly at random while
+keeping the winner's identity secret until Algorithm 8.
+
+Round complexity: O(M) dominated by the prefix scan (paper Remark 6.1).
+Communication: 2M + (M−1) SecureMult and M SecureIsZero per period.
+"""
+
+from typing import List
+
+from mpc_secret_shares import (
+    secure_mult,
+    is_zero,
+    shares_add,
+    shares_one,
+    shares_sub,
+)
+from protocol.types import ScorePair, Shares
+
+
+def algorithm_6_one_hot_winner(
+    scores: List[ScorePair],
+    winning_score: ScorePair,
+    pi: List[int],
+    n: int,
+    t: int,
+    p: int,
+) -> List[Shares]:
+    """Compute a one-hot shared indicator for the winning candidate.
+
+    Algorithm 6 of "Fairness Without Exposure: Privacy-Preserving Phragmén
+    Voting", Section 5.6.
+
+    Args:
+        scores: List of M ScorePairs ``(Score_m^num, Score_m^den)`` from
+            Algorithm 4.  ``scores[m]`` corresponds to candidate m (0-indexed).
+        winning_score: The minimum score ``(Score*^num, Score*^den)`` from
+            Algorithm 5.
+        pi: Public permutation of ``[0, M)`` from Algorithm 1 (0-indexed).
+            Used to break ties obliviously; ``pi[0]`` is the highest-priority
+            candidate in case of a tie.
+        n: Number of MPC parties.
+        t: Reconstruction threshold.
+        p: Prime field modulus.  Cross-products Score_m^num · Score*^den must
+            not exceed p (paper Section 7).
+
+    Returns:
+        ``chi`` — a list of M (t,n)-sharings where ``chi[m] = [[χ_m]]``.
+        Exactly one entry encodes the secret 1; all others encode 0.
+
+    Raises:
+        ValueError: If ``scores`` is empty or ``pi`` has wrong length.
+    """
+    m_count = len(scores)
+    if m_count == 0:
+        raise ValueError("scores must be non-empty: at least one candidate required")
+    if len(pi) != m_count:
+        raise ValueError(
+            f"pi has length {len(pi)}, expected {m_count} (one entry per candidate)"
+        )
+
+    star_num: Shares = winning_score[0]
+    star_den: Shares = winning_score[1]
+    one: Shares = shares_one(n)
+
+    # ------------------------------------------------------------------
+    # Lines 1-4: compute e_m = SecureIsZero(α_m − β_m) for each candidate.
+    # All M triples (SecureMult, SecureMult, SecureIsZero) are mutually
+    # independent → they can be batched in O(1) rounds.
+    # ------------------------------------------------------------------
+    e: List[Shares] = []
+    for m in range(m_count):                                         # Line 1
+        score_num, score_den = scores[m]
+
+        # Line 2: α_m = SecureMult([[Score_m^num]], [[Score*^den]])
+        alpha_m: Shares = secure_mult(
+            score_num, star_den, n, t, p
+        )
+
+        # Line 3: β_m = SecureMult([[Score*^num]], [[Score_m^den]])
+        beta_m: Shares = secure_mult(
+            star_num, score_den, n, t, p
+        )
+
+        # Line 4: e_m = SecureIsZero([[α_m]] − [[β_m]])
+        # α_m − β_m = 0  iff  Score_m = Score*  (same fraction)
+        diff: Shares = shares_sub(alpha_m, beta_m, p)
+        e.append(is_zero(diff, n, t, p))
+
+    # ------------------------------------------------------------------
+    # Lines 5-11: prefix scan in permutation order π.
+    # chi is pre-allocated and filled by candidate index (not π-order).
+    # ------------------------------------------------------------------
+    chi: List[Shares] = [None] * m_count  # type: ignore[list-item]
+
+    # Lines 5-7: initialise with the first candidate in π-order.
+    m1: int = pi[0]                                                  # Line 5
+    chi[m1] = e[m1]                                                  # Line 6
+    s: Shares = e[m1]                                                # Line 7
+
+    # Lines 8-11: suppress all but the first π-ordered tie-winner.
+    for k in range(1, m_count):                                      # Line 8
+        m = pi[k]                                                    # Line 9
+
+        # Line 10: [[χ_m]] = SecureMult([[e_m]], [[1]] − [[s]])
+        # [[1]] − [[s]] is local (affine subtraction of public 1).
+        one_minus_s: Shares = shares_sub(one, s, p)
+        chi[m] = secure_mult(e[m], one_minus_s, n, t, p)  # Line 10
+
+        # Line 11: [[s]] ← [[s]] + [[χ_m]]  (local)
+        s = shares_add(s, chi[m], p)                                 # Line 11
+
+    return chi

protocol/algorithm7_wallet_update.py

@@ -0,0 +1,149 @@
+"""Algorithm 7 — Wallet Update (Global Denominator Scaling).
+
+Reference: Algorithm 7 in "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting", Section 5.7 (pages 13–14).  Run every election period.
+
+Updates every voter's scaled wallet W̃_i and the global denominator Δ after
+the winner m* is chosen, maintaining the central invariant (paper Eq. 6):
+
+    w_n = W̃_n / Δ    for all n ∈ [N_valid], all periods.
+
+The update rule (paper Eq. 2) for a voter V_n is:
+
+    w_n ← 0                                  if n ∈ A(m*)   (supporter: reset)
+    w_n ← w_n + Score*                        if n ∉ A(m*)   (non-supporter: gain)
+
+where Score* = (Δ − T̃*) / (|A(m*)| · Δ).
+
+To avoid any field division the algorithm scales all wallet values by |A(m*)|
+and increments the global denominator by the same factor:
+
+    New W̃_i (supporter)     = 0
+    New W̃_i (non-supporter) = W̃_i · |A(m*)| + κ*        where κ* = Δ − T̃*
+    New Δ                   = Δ · |A(m*)|
+
+Invariant verification:
+    New w_n = New W̃_n / New Δ
+    For supporters:     0 / (Δ · |A(m*)|)   = 0                         ✓
+    For non-supporters: (W̃_n · |A(m*)| + κ*) / (Δ · |A(m*)|)
+                      = W̃_n/Δ + κ*/(Δ · |A(m*)|)
+                      = w_n + Score*                                     ✓
+"""
+
+from typing import List, Tuple
+
+from mpc_secret_shares import (
+    secure_mult,
+    shares_add,
+    shares_one,
+    shares_sub,
+    shares_zero,
+)
+from protocol.types import BallotMatrix, Shares
+
+
+def algorithm_7_wallet_update(
+    B_hat: BallotMatrix,
+    chi: List[Shares],
+    wallet_shares: List[Shares],
+    delta_shares: Shares,
+    A_shares: List[Shares],
+    T_tilde_shares: List[Shares],
+    n_valid: int,
+    num_candidates: int,
+    n: int,
+    t: int,
+    p: int,
+) -> Tuple[List[Shares], Shares]:
+    """Update voter wallets and the global denominator after electing a winner.
+
+    Algorithm 7 of "Fairness Without Exposure: Privacy-Preserving Phragmén
+    Voting", Section 5.7.
+
+    Precondition: at least one voter supports the elected candidate
+    (paper Section 5, page 8 — guaranteed by the protocol assumptions).
+
+    Args:
+        B_hat: N_valid × M ballot matrix of (t,n)-sharings.
+        chi: List of M (t,n)-sharings — the one-hot winner indicator from
+            Algorithm 6.  Exactly one entry encodes 1.
+        wallet_shares: List of N_valid (t,n)-sharings of the current W̃_i.
+        delta_shares: (t,n)-sharing of the current global denominator Δ.
+        A_shares: List of M (t,n)-sharings of |A(m)| from Algorithm 4.
+        T_tilde_shares: List of M (t,n)-sharings of T̃_m from Algorithm 4.
+        n_valid: Number of honest voters N_valid.
+        num_candidates: Number of candidates M.
+        n: Number of MPC parties.
+        t: Reconstruction threshold.
+        p: Prime field modulus.
+
+    Returns:
+        A tuple ``(new_wallet_shares, new_delta_shares)`` where:
+
+        * ``new_wallet_shares[i]`` is the updated (t,n)-sharing of W̃_i.
+        * ``new_delta_shares`` is the updated (t,n)-sharing of Δ.
+
+        The invariant w_n = W̃_n / Δ is preserved for every honest voter.
+    """
+    one: Shares = shares_one(n)
+
+    # ------------------------------------------------------------------
+    # Lines 1-5: extract the winner's supporter count and load sum.
+    # The χ-weighted sums isolate the winner's row from Algorithm 4 output.
+    # ------------------------------------------------------------------
+    A_star: Shares = shares_zero(n)   # [[|A(m*)|]]            Line 1
+    T_star: Shares = shares_zero(n)   # [[T̃*]]                 Line 2
+
+    for m in range(num_candidates):                            # Line 3
+        # Line 4: [[|A(m*)|]] ← [[|A(m*)|]] + SecureMult([[χ_m]], [[|A(m)|]])
+        A_star = shares_add(
+            A_star,
+            secure_mult(chi[m], A_shares[m], n, t, p),
+            p,
+        )
+        # Line 5: [[T̃*]] ← [[T̃*]] + SecureMult([[χ_m]], [[T̃_m]])
+        T_star = shares_add(
+            T_star,
+            secure_mult(chi[m], T_tilde_shares[m], n, t, p),
+            p,
+        )
+
+    # Line 6: [[κ*]] ← [[Δ]] − [[T̃*]]   (= Score*^num, local)
+    kappa_star: Shares = shares_sub(delta_shares, T_star, p)
+
+    # ------------------------------------------------------------------
+    # Lines 7-13: per-voter wallet update.
+    # γ_i = 1 iff voter i supports the winner; 0 otherwise.
+    # Supporters are reset (× 0); non-supporters are incremented (× 1).
+    # ------------------------------------------------------------------
+    new_wallets: List[Shares] = []
+
+    for i in range(n_valid):                                   # Line 7
+        # Lines 8-10: [[γ_i]] = Σ_m SecureMult([[B̂_{i,m}]], [[χ_m]])
+        gamma_i: Shares = shares_zero(n)                      # Line 8
+        for m in range(num_candidates):                        # Line 9
+            gamma_i = shares_add(
+                gamma_i,
+                secure_mult(B_hat[i][m], chi[m], n, t, p),
+                p,
+            )                                                  # Line 10
+
+        # Line 11: [[μ_i]] ← SecureMult([[W̃_i]], [[|A(m*)|]])
+        mu_i: Shares = secure_mult(
+            wallet_shares[i], A_star, n, t, p
+        )
+
+        # Line 12: [[ν_i]] ← [[μ_i]] + [[κ*]]  (local)
+        nu_i: Shares = shares_add(mu_i, kappa_star, p)
+
+        # Line 13: [[W̃_i]] ← SecureMult([[1]] − [[γ_i]], [[ν_i]])
+        # [[1]] − [[γ_i]] is local.  Supporters (γ_i=1) → 0; others → ν_i.
+        one_minus_gamma: Shares = shares_sub(one, gamma_i, p)
+        new_wallets.append(
+            secure_mult(one_minus_gamma, nu_i, n, t, p)
+        )                                                      # Line 13
+
+    # Line 14: [[Δ]] ← SecureMult([[Δ]], [[|A(m*)|]])
+    new_delta: Shares = secure_mult(delta_shares, A_star, n, t, p)
+
+    return new_wallets, new_delta                              # Line 14

protocol/algorithm8_reconstruct_winner.py

@@ -0,0 +1,79 @@
+"""Algorithm 8 — Winner Reconstruction.
+
+Reference: Algorithm 8 in "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting", Section 5.8 (page 14).  Run every election period as the
+final step, after Algorithm 7 has updated the wallets.
+
+Reconstructs the one-hot indicator {[[χ_m]]}_{m∈[M]} produced by Algorithm 6
+into a publicly revealed winner index m*.  This is the only step in the
+per-period loop that reveals information: the identity of the elected
+candidate.  All ballots, wallets, and intermediate scores remain secret.
+
+The two consistency checks (Lines 3–6) guard against upstream protocol
+failures; they abort rather than silently return a wrong winner.
+
+No MPC secure operations are performed — Reconstruct is local Lagrange
+interpolation on already-held shares.
+"""
+
+from typing import List
+
+from mpc_secret_shares import reconstruct
+from protocol.types import Shares
+
+
+def algorithm_8_reconstruct_winner(
+    chi: List[Shares],
+    t: int,
+    p: int,
+) -> int:
+    """Reconstruct and reveal the winning candidate index from the one-hot indicator.
+
+    Algorithm 8 of "Fairness Without Exposure: Privacy-Preserving Phragmén
+    Voting", Section 5.8.
+
+    Each sharing [[χ_m]] is reconstructed publicly using t shares.  The
+    results must form a valid one-hot vector: every entry in {0, 1} and
+    exactly one entry equal to 1.  Any deviation indicates an upstream
+    protocol failure and causes an immediate abort.
+
+    Args:
+        chi: List of M (t,n)-sharings of χ_m ∈ {0, 1}, produced by
+            Algorithm 6.  ``chi[m]`` corresponds to candidate m (0-indexed).
+        t: Reconstruction threshold — the number of shares used for
+            Lagrange interpolation.
+        p: Prime field modulus.
+
+    Returns:
+        The 0-indexed winner m* — the unique m ∈ [0, M) with χ_m = 1.
+
+    Raises:
+        ValueError: If any χ_m ∉ {0, 1} (Lines 3–4 of the paper).
+        ValueError: If Σ χ_m ≠ 1 — either no winner or multiple winners
+            (Lines 5–6 of the paper).
+        ValueError: If ``chi`` is empty.
+    """
+    if not chi:
+        raise ValueError("chi must be non-empty: at least one candidate required")
+
+    # Lines 1-4: reconstruct every χ_m publicly and validate each value.
+    chi_plain: List[int] = []
+    for m, shares in enumerate(chi):                                 # Line 1
+        val: int = reconstruct(shares[:t], p)             # Line 2
+        if val not in (0, 1):                                        # Line 3
+            raise ValueError(
+                f"χ_{m} = {val} is not in {{0, 1}}: "
+                "one-hot vector is malformed (upstream protocol failure)"
+            )                                                        # Line 4
+        chi_plain.append(val)
+
+    # Lines 5-6: verify exactly one candidate received χ = 1.
+    total = sum(chi_plain)
+    if total != 1:                                                   # Line 5
+        raise ValueError(
+            f"Σ χ_m = {total} ≠ 1: expected exactly one winner "
+            f"(got {total})"
+        )                                                            # Line 6
+
+    # Lines 7-8: return the unique winner index.
+    return chi_plain.index(1)                                        # Lines 7-8

protocol/state_manager.py

@@ -0,0 +1,139 @@
+"""State persistence between election periods for tallying parties.
+
+Reference: "Fairness Without Exposure: Privacy-Preserving Phragmén Voting",
+Section 5 — the protocol operates *periodically*; talliers retain the shared
+wallet state from one period to the next.
+
+Architecture note
+-----------------
+The entities that hold persistent state are the **talliers** P_1 … P_D, not
+voters and not candidates.  Each tallier P_d stores only its own share index
+(the d-th component) from every (t,n)-sharing:
+
+    delta_share_d  = delta_shares[d-1]           — one Tuple[int, int]
+    wallet_d[i]    = wallet_shares[i][d-1]        — one Tuple[int, int] per voter
+
+Voters submit **fresh ballots** each period and may vote for different
+candidates.  Only the scaled-wallet state carries over.
+
+Workflow
+--------
+End of period r:
+    for d in 1..n:
+        save_tallier_state(d, delta_r, wallets_r, path_d)
+
+Start of period r+1:
+    states = [load_tallier_state(d, path_d) for d in 1..n]
+    delta_r, wallets_r = combine_tallier_states(states)
+    # then run Algorithm 2 on the *new* ballots, Algorithms 4-8 as usual
+"""
+
+import json
+from typing import List, Tuple
+
+from protocol.types import Shares
+
+# One party's contribution to a single sharing: (party_id, share_value).
+SingleShare = Tuple[int, int]
+
+
+def save_tallier_state(
+    tallier_id: int,
+    delta_shares: Shares,
+    wallet_shares: List[Shares],
+    path: str,
+) -> None:
+    """Persist tallier d's individual shares to a JSON file.
+
+    Extracts the d-th entry from each (t,n)-sharing and writes it to disk.
+    No other party's data is included; the file contains only what P_d
+    would hold in a real distributed deployment.
+
+    Args:
+        tallier_id: 1-based party index d ∈ {1, …, n}.
+        delta_shares: Full (t,n)-sharing of the global denominator Δ.
+        wallet_shares: List of N_valid full (t,n)-sharings of W̃_i.
+        path: Destination file path.  Parent directory must exist.
+    """
+    idx = tallier_id - 1   # 0-based index into the Shares list
+
+    state = {
+        "tallier_id": tallier_id,
+        "n_valid": len(wallet_shares),
+        "delta_share": list(delta_shares[idx]),
+        "wallet_shares": [list(ws[idx]) for ws in wallet_shares],
+    }
+
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(state, fh)
+
+
+def load_tallier_state(
+    tallier_id: int,
+    path: str,
+) -> Tuple[SingleShare, List[SingleShare]]:
+    """Load tallier d's individual shares from a JSON file.
+
+    Args:
+        tallier_id: 1-based party index d — must match the value stored in
+            the file, otherwise a ValueError is raised.
+        path: Source file path.
+
+    Returns:
+        A tuple ``(delta_share_d, wallet_shares_d)`` where:
+
+        * ``delta_share_d``   is ``(d, Δ_d)``   — tallier d's share of Δ.
+        * ``wallet_shares_d`` is ``[(d, W̃_i_d) for i in range(n_valid)]``
+          — tallier d's share of each voter's wallet.
+
+    Raises:
+        ValueError: If the stored tallier_id does not match the argument.
+        FileNotFoundError: If the path does not exist.
+    """
+    with open(path, "r", encoding="utf-8") as fh:
+        state = json.load(fh)
+
+    stored_id = state["tallier_id"]
+    if stored_id != tallier_id:
+        raise ValueError(
+            f"File {path!r} contains state for tallier {stored_id}, "
+            f"but tallier_id={tallier_id} was requested"
+        )
+
+    delta_share: SingleShare = tuple(state["delta_share"])           # type: ignore[assignment]
+    wallet_shares_d: List[SingleShare] = [
+        tuple(ws) for ws in state["wallet_shares"]                   # type: ignore[misc]
+    ]
+    return delta_share, wallet_shares_d
+
+
+def combine_tallier_states(
+    tallier_states: List[Tuple[SingleShare, List[SingleShare]]],
+) -> Tuple[Shares, List[Shares]]:
+    """Reconstruct full (t,n)-Shares objects from all talliers' individual shares.
+
+    In a real deployment each tallier sends its share to an agreed
+    reconstruction point; in the simulation all shares are available locally.
+
+    Args:
+        tallier_states: List of ``(delta_share_d, wallet_shares_d)`` tuples,
+            one per tallier, ordered by tallier index 1 … n
+            (``tallier_states[0]`` = P_1's state, etc.).
+
+    Returns:
+        ``(delta_shares, wallet_shares)`` — full (t,n)-sharings ready for
+        use by Algorithms 4–8 in the next period.
+    """
+    n = len(tallier_states)
+
+    # delta_shares = [(1, Δ_1), (2, Δ_2), …, (n, Δ_n)]
+    delta_shares: Shares = [tallier_states[d][0] for d in range(n)]
+
+    # wallet_shares[i] = [(1, W̃_i_1), …, (n, W̃_i_n)]
+    n_valid = len(tallier_states[0][1])
+    wallet_shares: List[Shares] = [
+        [tallier_states[d][1][i] for d in range(n)]
+        for i in range(n_valid)
+    ]
+
+    return delta_shares, wallet_shares

protocol/types.py

@@ -0,0 +1,16 @@
+"""Shared type aliases used across all PP-Phragmén protocol modules.
+
+Reference: Section 5 of "Fairness Without Exposure: Privacy-Preserving
+Phragmén Voting."
+"""
+
+from typing import List, Tuple
+
+Shares = List[Tuple[int, int]]
+"""A (t,n)-Shamir sharing: [(party_id, share_value), ...] of length n."""
+
+BallotMatrix = List[List[Shares]]
+"""N_valid × M matrix; BallotMatrix[i][m] is the (t,n)-sharing of B̂_{i,m}."""
+
+ScorePair = Tuple[Shares, Shares]
+"""Candidate score as (Score^num, Score^den) — both (t,n)-sharings."""