Voting documentation

source/mainnet/net/index.rst

@@ -56,3 +56,12 @@ index
 
    Smart contract tutorials <../smart-contracts/tutorials/index>
    Using ID tutorial <guides/gallery/index>
+
+.. toctree::
+   :includehidden:
+   :caption: Governance Committee Voting
+
+   voting/gc-voting
+   voting/coordinator
+   voting/voting
+   voting/guardians

source/mainnet/net/installation/downloads.rst

@@ -296,6 +296,18 @@ Download the block separately to inspect it or to run a node in a custom configu
 
       - SHA256 checksum of the download: ``69db4360f0a16414db86a920513600cfe29241c0c713a07d8e79dad19103e91d``
 
+.. _downloads-voting-tools:
+
+Voting tools
+============
+
+Coordinator tool
+Windows
+Mac
+Ubuntu
+
+The Guardian app, voting dApp, and election smart contract are created by the election coordinator during the setup phase of the election.
+
 .. _downloads-auxiliary-tools:
 
 Auxiliary tools

source/mainnet/net/resources/glossary.rst

@@ -20,6 +20,15 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       A certificate derived from the :term:`identity object` that proves that the owner has been verified by an identity provider. The key feature of the credential is that it **does not** identify the owner to the identity provider, nor to any other single entity, however it contains enough information to allow anonymity revokers in concert with the identity provider to find the owner.
 
+
+   Account weight
+
+      The Account weight of an account corresponds to the weight this account has for voting. In the 2024 election, this is computed as the average amount of CCD on the account between the 1st of March and 31st of May 2024.
+
+   Accumulated weight
+
+      The weight of a vote is the weight assigned to that vote when tallying, i.e., the sum of all account weights that delegated to the account that cast the vote + the weight of the account that cast the vote (unless that account delegated its own weight to another account, but voted anyway).
+
    Alias
 
       A kind of sub-account structure that can be created. An account owner can create different aliases for different uses to keep track of transfers and assign them meaning. Each account has 16777216 addresses, namely a so-called canonical account address together with matching account aliases. The canonical account address is derived when an account is created on chain. The other 16 million addresses with matching initial 29 bytes are referred to as account aliases for the same account. Thus, accounts can be referred to by any address whose initial 29 bytes match.
@@ -28,6 +37,10 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       An authority who has power to know the identity of a participant. The anonymity revokers and :term:`identity provider` can work together to determine the owner of an account and determine which accounts belong to the same owner. (They should only do so when legally obliged to, such as by a court order.) Anonymity revocation is a two-stage process, requiring cooperation of multiple parties.
 
+   Approval voting
+
+      Approval voting is a single-winner electoral system in which the voter can choose or approve any number of candidates, effectively assigning a 0 or a 1 to every candidate. The winner is the single candidate approved by the largest number of voters. Approval voting can be achieved by setting the selection limit to the total number of options in a contest.
+
    Attributes
 
       User data, such as date of birth or country of residence, that is associated with a user :term:`identity`. Users can choose which attributes should be revealed in each of their accounts.
@@ -60,6 +73,10 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       Command to take a smart contract module written in Rust and create a Wasm module that can be deployed on chain. The command is run from :term:`cargo-concordium`.
 
+   Candidate
+
+      Option on the official list of candidates for the election. Since there are only 10 places for the 2024 election, not all nominees are necessarily candidates.
+
    cargo-concordium
 
       An extension of Rust's ``cargo`` tool. It can be used for compiling and testing smart contracts, and enables features such as building contract schemas.
@@ -138,14 +155,32 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       Dual to :term:`encryption key`. In contrast to the encryption key, which is public, this key is only known to the account holder.
 
+   Decryption share
+
+      A guardian's partial share of a ballot decryption or tally decryption for an election.
+
+   Delegated weight
+
+      Sum of account weights that delegated to an account. Delegated weight is made up of the account weight of each account that delegated a vote to the account that cast a ballot.
+
    Delegator
 
       An account that contributes stake to a staking pool, or to passive delegation. When an account becomes a delegator, the delegated amount of CCD is locked so that it cannot be spent or transferred while it is delegated. Delegators earn rewards, minus a commission to the validator, in proportion to their delegated stake.
 
+      For delegation in an election, see :term:`Vote delegation`.
+
    Deploy
 
       Command that takes the built :term:`Wasm<webassembly>` file for a smart contract module and deploys it on chain. This command is run from :term:`Concordium client`.
 
+   Election manifest
+
+      The manifest is the information that uniquely specifies and describes the structure and type of the election, including geopolitical units, contests, candidates, ballot styles, etc. In the Guardian app, it is a file that is created before running an election. The internal manifest is a wrapper around the manifest used in programming code to simplify and avoid processing the same information twice. Unlike the manifest, the internal manifest is not meant for serialization.
+
+   Election phase
+
+      Time period during the election when voting is open, either directly or via delegation.
+
    Encryption key
 
       An `ElGamal`_ public key associated to an account which is used to encrypt all :term:`shielded amounts<shielded amount>` on the account.
@@ -170,6 +205,14 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       The first :term:`block` in a :term:`chain`. The genesis block establishes the starting state of the chain, before any transactions have occurred.
 
+   Governance committee member
+
+      Individual elected to the Concordium governance committee. Also known as member or committee member.
+
+   Guardian
+
+      One of a number of independent, trustworthy individuals who serve guardians in the election. All guardians must participate in a key ceremony to create a key to encrypt the election and may participate in the accompanying tally ceremony(s) to decrypt the tally(s). A guardian is available if they are available for the tally ceremony. A guardian is missing if they cannot attend the tally ceremony.
+
    Identity
 
       Before opening an account on the Concordium Platform, one's real-world identity must be verified and recorded by an :term:`identity provider`. A user’s identity is anonymous on-chain, however this anonymity can be revoked and their real-world identity revealed in response to a valid request from a government authority.
@@ -234,6 +277,10 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       A participant in the Concordium network. Nodes receive blocks and transactions, and track the current state of the blockchain. A :term:`validator node<baker>` has cryptographic keys that enable it to take part in validation. A node without these keys is referred to as a *passive node*.
 
+   Nominee
+
+      Someone who has volunteered to be a candidate in an election.
+
    Nonce
 
       May refer to:
@@ -298,6 +345,10 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       Also known as a seed phrase, recovery phrase, mnemonic phrase, mnemonic seed, or backup phrase. A group of random words generated by the wallet that allows you to access the CCDs stored in it across devices or in case of non-functioning devices. Secret recovery phrase is supported by |mw-gen2|.
 
+   Setup phase
+
+      Time period prior to election start where setup of necessary election components occurs, candidates are nominated, guardians are selected, etc.
+
    Shielded amount
 
       An amount of :term:`CCD` that is encrypted with the public key of an account. Only the owner of the secret key can determine how many CCDs are contained in the encryption.
@@ -342,6 +393,20 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       A list presented to a wallet by a dApp or service whose items are either attributes to reveal, or properties of attributes to prove.
 
+   Tally
+
+      Tally (noun) is the number of votes obtained by every candidate computed by summing all weighted votes for every candidate. Also, tally (verb) is the process of calculating the number of votes.
+
+   Tally ceremony
+
+      The process of decrypting the encrypted tally to the decrypted tally. The guardians from the key ceremony who are available attend this ceremony. There must be at least enough guardians to meet the quorum. Each guardian will decrypt their decryption shares and their share for each missing guardian. These shares will then be combined to create the decrypted spoiled ballots and decrypted tally.
+
+      The tally ceremony is a part of the tally phase.
+
+   Tally phase
+
+      Time period after the election where voting is closed and guardians decrypt their share of the tally (tally ceremony is held) and the final election result is produced and registered.
+
    Testnet
 
       A test network run by Concordium to test its protocols and software. There can be several test networks in existence at the same time. All the features are tested on the testnet before they are released on the :term:`mainnet`.
@@ -399,6 +464,12 @@ Also see the Concordium `whitepaper`_ for more details on the terms described be
 
       Party that checks users' :term:`verifiable credentials<verifiable credential>`.
 
+   Vote delegation
+
+      Method whereby a user can add account weight of their account to another account that will cast the ballot. This is used by users of Desktop Wallet and Concordium Legacy Wallet to cast ballots in the 2024 election.
+
+      For delegation related to earning rewards on an account, see :term:`delegator`.
+
    Wallet
 
       A wallet is an app that allows cryptocurrency users to store and retrieve their digital assets, and manage identities and accounts. Concordium has four wallet types.

source/mainnet/net/voting/coordinator.rst

@@ -0,0 +1,123 @@
+.. _coordinator:
+.. include:: ../../variables.rst
+
+=========================
+Election coordinator tool
+=========================
+
+The coordinator tool is an administrative tool to coordinate the parts of the election that are not done by voters or guardians.
+
+The coordinator of the election is not trusted per se. All the actions it can do can be verified by any other party. The coordinator tool can be mostly run without access to any secrets to verify results of the election. However some commands take "admin keys" where the result of operations can be posted in the contract for everybody to see. If such a result is present in the contract and another user runs the coordinator tool, the tool will check that the result it computed and the one posted in the contract agree.
+
+Build and run
+=============
+
+To build the tool make sure you have the repository submodules initialized:
+
+.. code-block:: console
+
+    git submodule update --init --recursive
+
+Build the tool by running:
+
+.. code-block:: console
+
+    cargo build --release
+
+This will produce a single binary election-coordinator in target/release directory.
+
+Commands
+========
+
+The tool has the following subcommands. All commands have a ``--help`` option which explains the input and output parameters.
+
+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.
+
+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
+
+The weights are stored in the initial-weights.csv file.
+
+Create a new election instance
+------------------------------
+
+Use the ``new-election`` command to create the necessary files and the contract for a new election. In particular it will:
+
+- create an election manifest based on the inputs
+
+- create election parameters based on the inputs
+
+- create a new smart contract instance.
+
+.. 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' --delegation-string 'This is how you delegate' --manifest-out election-manifest.json --parameters-out election-parameters.json --voters-file initial-weights.csv --guardian 31bTNa42u1zZWag2bknEy7VraeJUozXsJMN1DFjQp7E5YR6a3G --guardian 4PF6BH8bKvM48b8KNYdvGW6Sv3B2nqVRiMnWTj9cvaNHJQeX3D --candidate 'http://localhost:7000/candidate1.json' --candidate 'http://localhost:7000/candidate2.json' --node 'https://grpc.testnet.concordium.com:20000' --base-url https://gcvoting.testnet.concordium.com`
+
+The options are:
+
+``--admin`` is the path to the keys that will be used to create the contract, and serve as the admin
+
+``--module`` is the path to the compiled election smart contract in wasm.v1 format
+
+``--threshold`` is the threshold for the number of guardians needed for decryption of the result of the election
+
+``--election-start`` and ``--election-end`` date and time for election start and end
+
+``--delegation-string`` is the string that will be used to determine vote delegations. This is the string users delegating a vote in a wallet must enter in a transaction memo.
+
+``--voters-file`` is the initial-weights.csv file for the election
+
+``--guardian`` (repeated) is guardian account addresses. At least one is needed.
+
+``--candidate`` (repeated) is a URL 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.
+
+``--base-url`` the URL where the election server is accessible, e.g., https://gcvoting.testnet.concordium.com
+
+The tool generates three things:
+
+- An election manifest which is output to the location specified by ``--manifest-out``
+
+- Election parameters which are output to the location specified by ``--parameters-out``
+
+- A new smart contract instance which is printed to stderr, for example, ``Deployed new contract instance with address <7838,0> using transaction hash 3b3e61a01fd3ecefddecbe6760c6ba3d951f4d0a8947d63990ffe9219249de27``.
+
+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 http://localhost:20001 final-weights --contract '<7795,0>' --initial-weights initial-weights.csv --final-weights final-weights.csv
+
+Tally the votes and register the encrypted tally in the contract
+----------------------------------------------------------------
+
+The ``tally`` command uses the final-weights.csv generated above to compute the encrypted tally of the election and optionally post 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 http://localhost:20001 tally --contract '<7795,0>' --final-weights final-weights.csv --admin-keys ../test-scripts/keys/2yJxX711aDXtit7zMu7PHqUMbtwQ8zm7emaikg24uyZtvLTysj.export
+
+The same command without the ``--admin-keys`` option will tally the votes and check that the tally matches what is registered in the contract.
+
+Decrypt the final result
+------------------------
+
+Use the ``final-result`` command after the guardians have each decrypted their share of the encrypted tally. This command can be used to combine the shares and post the result in the contract, or if the result is already posted, to check that it matches what you compute.
+
+.. code-block:: console
+
+    election-coordinator  --node http://localhost:20001 final-result --contract '<7795,0>' --admin-keys ../test-scripts/keys/2yJxX711aDXtit7zMu7PHqUMbtwQ8zm7emaikg24uyZtvLTysj.export```
+
+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.
+
+If the ``admin-keys`` are not provided the command will do everything else as with the keys, except it will check if the result in the contract matches or not, and report the result.