Merge pull request #1008 from Concordium/election-verification

Document third party verification flow + adapt coordinator tool docs

Author: soerenbf

README.md

@@ -64,7 +64,7 @@ pip3 install pipenv
 
 To install the python dependencies run:
 ```
-pipenv sync
+pipenv sync --dev
 ```
 
 Install `graphviz`:
@@ -77,7 +77,7 @@ On macOS
 ```
 brew install python3 graphviz
 pip3 install pipenv
-pipenv sync
+pipenv sync --dev
 ```
 
 ### Windows
@@ -89,7 +89,7 @@ Download and run the launcher. Make sure to select "Add Python to PATH" at the b
 After that from a terminal run
 ```
 pip3 install pipenv
-pipenv sync
+pipenv sync --dev
 ```
 from the root of this repository.
 

source/mainnet/net/index.rst

@@ -65,3 +65,4 @@ index
    voting/coordinator
    voting/voting
    voting/guardians
+   voting/verify-election-result

source/mainnet/net/voting/coordinator.rst

@@ -34,15 +34,15 @@ The tool has the following subcommands. All commands have a ``--help`` option wh
 Get the list of initial weights
 -------------------------------
 
-Use the ``initial-weights`` command to gather the average amount of CCD on an account in the given period. The intention is that this command is used to produce the initial weights of each account prior to the election starting. The output of this command is a CSV file used in the ``final-weights`` command after the election.
+Use the ``initial-weights generate`` command to gather the average amount of CCD on an account in the given period. The intention is that this command is used to produce the initial weights of each account prior to the election starting. The output of this command is a CSV file used in the ``final-weights`` command after the election.
 
 Example
 
 .. code-block:: console
 
-    election-coordinator --node http://localhost:20001 initial-weights  --start 2024-01-01T00:00:00Z --end 2024-01-03T00:00:00Z --out initial-weights.csv
+    election-coordinator --node http://localhost:20001 initial-weights --out . generate --start 2024-01-01T00:00:00Z --end 2024-01-03T00:00:00Z
 
-The weights are stored in the initial-weights.csv file.
+The weights are stored in the initial-weights.csv file, and the corresponding parameters used to compute them are stored in initial-weights-params.json file in the current path directory.
 
 Create a new election instance
 ------------------------------
@@ -57,7 +57,7 @@ Use the ``new-election`` command to create the necessary files and the contract
 
 .. code-block:: console
 
-    election-coordinator new-election --module ../contracts/concordium-governance-committee-election/concordium-out/module.wasm.v1 --threshold 1 --admin ../test-scripts/keys/2yJxX711aDXtit7zMu7PHqUMbtwQ8zm7emaikg24uyZtvLTysj.export --election-start '2024-02-01T00:00:00Z' --election-end '2024-02-07T00:00:00Z' --decryption-deadline '2024-02-08T00:00:00Z' --delegation-string 'delegatevote2024' --out election --voters-file initial-weights.csv --guardian 31bTNa42u1zZWag2bknEy7VraeJUozXsJMN1DFjQp7E5YR6a3G --guardian 4PF6BH8bKvM48b8KNYdvGW6Sv3B2nqVRiMnWTj9cvaNHJQeX3D --candidate candidate1.json --candidate https://some.url/candidate2.json --node 'https://grpc.testnet.concordium.com:20000' --base-url https://gcvoting.testnet.concordium.com`
+    election-coordinator new-election --module ../contracts/concordium-governance-committee-election/concordium-out/module.wasm.v1 --threshold 1 --admin ../test-scripts/keys/2yJxX711aDXtit7zMu7PHqUMbtwQ8zm7emaikg24uyZtvLTysj.export --election-start '2024-02-01T00:00:00Z' --election-end '2024-02-07T00:00:00Z' --decryption-deadline '2024-02-08T00:00:00Z' --delegation-string 'delegatevote2024' --out election --voters-file initial-weights.csv --voters-params-file initial-weights-params.json --guardian 31bTNa42u1zZWag2bknEy7VraeJUozXsJMN1DFjQp7E5YR6a3G --guardian 4PF6BH8bKvM48b8KNYdvGW6Sv3B2nqVRiMnWTj9cvaNHJQeX3D --candidate candidate1.json --candidate https://some.url/candidate2.json --node 'https://grpc.testnet.concordium.com:20000' --base-url https://gcvoting.testnet.concordium.com`
 
 The options are:
 
@@ -75,6 +75,8 @@ The options are:
 
 ``--voters-file`` is the initial-weights.csv file for the election
 
+``--voters-params-file`` is the initial-weights-params.json file for the election, containing the params used to compute the initial weights.
+
 ``--guardian`` (repeated) is guardian account addresses. At least one is needed.
 
 ``--candidate`` (repeated) is a URL or a path to a candidate. The order here matters, since that will be the order of selections in the election. The link is to the candidate metadata. The hash of the metadata will be embedded in the contract.

source/mainnet/net/voting/verify-election-result.rst

@@ -0,0 +1,63 @@
+.. _verify-election-result:
+.. include:: ../../variables.rst
+
+======================
+Verify election result
+======================
+
+To verify that the result of an election is correctly computed as a third party, it is possible to execute a sequence of commands using the ``election-coordinator`` tool.
+
+In general, all the commands listed require specification of the concordium node and contract address to target:
+
+- The ``--node`` argument for all commands should specify the address of a node on the network the election exists on.
+
+- The ``--contract`` argument for all commands should specify the contract address of the election you want to verify.
+
+Commands
+========
+
+The tool has the following subcommands. All commands have a ``--help`` option which explains the input and output parameters.
+
+Verify the list of initial weights
+----------------------------------
+
+Use the ``initial-weights verify`` command to gather the average amount of CCD on an account in the given period. The intention is that this command is used to produce the initial weights of each account prior to the election starting and verify these against the weights registered in the contract. The output of this command is a CSV file used in the ``final-weights`` command after the election.
+
+Example
+
+.. code-block:: console
+
+    election-coordinator --node https://grpc.testnet.concordium.com:20000 initial-weights --out . verify --contract "<8836,0>"
+
+The weights are stored in the initial-weights.csv file, and the corresponding parameters used to compute them are stored in initial-weights-params.json file in the current path directory.
+
+Get the final weights
+---------------------
+
+Use the ``final-weights`` command to compute the final weights taking into account the delegation. It takes initial weights in the initial-weights.csv into account and any delegations during the election period, outputting the result to final-weights.csv. The output of this command is used in the tally command.
+
+Example
+
+.. code-block:: console
+
+    election-coordinator --node https://grpc.testnet.concordium.com:20000 final-weights --contract "<8836,0>" --initial-weights initial-weights.csv --final-weights final-weights.csv
+
+Verify the encrypted tally registered in the contract
+-----------------------------------------------------
+
+The ``tally`` command uses the final-weights.csv generated above to compute the encrypted tally of the election and optionally posts it in the smart contract. This sums up all the votes during the election period and scales them according to the specified weights.
+
+.. code-block:: console
+
+    election-coordinator --node https://grpc.testnet.concordium.com:20000 tally --contract "<8836,0>" --final-weights final-weights.csv
+
+Verify the election result
+--------------------------
+
+Use the ``final-result`` command after the guardians have each decrypted their share of the encrypted tally. This command will be used to combine the shares and check that it matches what you compute.
+
+.. code-block:: console
+
+    election-coordinator --node https://grpc.testnet.concordium.com:20000 final-result --contract "<8836,0>"
+
+This will look up all the decryption shares provided by the guardians, check that they are valid, and if there are enough of the valid ones, it will decrypt the final result and publish it in the smart contract.