From 528e147596ee59ca20d66706f794759b6687bc46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Wed, 20 Dec 2023 13:26:09 +0100 Subject: [PATCH] voting schemes readmes --- bulletin_board/server/README.md | 6 +++++- voting_schemes/dummy/ruby-adapter/README.md | 14 ++++++-------- .../electionguard/ruby-adapter/README.md | 19 +++++++++++-------- 3 files changed, 22 insertions(+), 17 deletions(-) diff --git a/bulletin_board/server/README.md b/bulletin_board/server/README.md index e5bcb828..a9f83464 100644 --- a/bulletin_board/server/README.md +++ b/bulletin_board/server/README.md @@ -9,7 +9,11 @@ The Bulletin Board is a service composed by an Encryption Engine and an Append-O - System dependencies: - Python gmpy2 package dependencies: libgmp, libmpfr and libmpc -The Bulletin Board is intended to use alongside a Decidim installation. It's main purpose is to provide a GraphQL interface to a secure, auditable and verifiable voting system. This is currently achieved by using the [ElectionGuard python implementation](https://github.com/microsoft/electionguard-python), developed by Microsoft. So this server acts as a wrapper to the ElectionGuard python code. +The Bulletin Board is intended to use alongside a Decidim installation. It's main purpose is to provide a GraphQL interface to a secure, auditable and verifiable voting system. This is currently achieved by using the [ElectionGuard python implementation](https://github.com/microsoft/electionguard-python), developed by Microsoft. So this server acts as a [wrapper to the ElectionGuard python code](../../voting_schemes/electionguard/python-wrapper). + +See how python code is executed using PyCall here: +- https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/server/app/services/voting_scheme/electionguard/voter.rb +- https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/server/app/services/voting_scheme/electionguard/bulletin_board.rb Please check the [main documentation](../../README.adoc) for this repository for more convenient ways to run the Bulletin Board. diff --git a/voting_schemes/dummy/ruby-adapter/README.md b/voting_schemes/dummy/ruby-adapter/README.md index 28738422..18d66201 100644 --- a/voting_schemes/dummy/ruby-adapter/README.md +++ b/voting_schemes/dummy/ruby-adapter/README.md @@ -1,8 +1,6 @@ # VotingSchemes::Dummy -Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/voting_schemes/dummy`. To experiment with that code, run `bin/console` for an interactive prompt. - -TODO: Delete this and the text above, and describe your gem +The Bulletin Board is a generic API for storing and retrieving ballots and tallies for elections. The final implementation of the protocol used for creating an election may vary. This gem provides a dummy implementation for testing purposes. ## Installation @@ -22,14 +20,14 @@ Or install it yourself as: ## Usage -TODO: Write usage instructions here +This implementation is intended for testing purposes only. It allows to test the Bulletin Board without the need to use a fully configured Decidim installation. +It also skips the encryption and decryption steps, so it is not suitable for production use. -## Development +You can [start the server](../../bulletin_board/server) in development mode and connect to the built-in testing admin sandbox at: -After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. +http://localhost:3000/sandbox -To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/voting_schemes-dummy. +Bug reports and pull requests are welcome on GitHub at https://github.com/decidim/decidim-bulletin-board/issues. diff --git a/voting_schemes/electionguard/ruby-adapter/README.md b/voting_schemes/electionguard/ruby-adapter/README.md index 92985a5e..bb6ee9d0 100644 --- a/voting_schemes/electionguard/ruby-adapter/README.md +++ b/voting_schemes/electionguard/ruby-adapter/README.md @@ -1,8 +1,13 @@ # VotingSchemes::Electionguard -Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/voting_schemes/electionguard`. To experiment with that code, run `bin/console` for an interactive prompt. +The Bulletin Board is a generic API for storing and retrieving ballots and tallies for elections. The final implementation of the protocol used for creating an election may vary. This gem provides the [Microsoft's ElectionGuard](https://github.com/microsoft/electionguard-python) Javascript implementation for production use in Decidim. -TODO: Delete this and the text above, and describe your gem +Note that the ElectionGuard implementation works by using two different wrappers around Electionguard: + +- A [Python Wrapper](../python-wrapper) for its use in the backend of the [GraphQL API server](../../../bulletin_board/server). +- A [Javascript Wrapper](../js-adapter) that compiles the whole Electionguard python app into web-assembly and allows to use it in the frontend (this ensure that the voting process is not tampered by sending any data to the backend). + +This gem provides a very simple gem that wraps the Javascript implementation and allows to use it in the frontend of a Decidim application (Elections module). ## Installation @@ -22,14 +27,12 @@ Or install it yourself as: ## Usage -TODO: Write usage instructions here - -## Development +You can see examples of usage by looking at the Decidim Elections module: -After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. +- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/packs/src/decidim/elections/voter/casting-vote.js +- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/packs/src/decidim/elections/election_log.js -To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/voting_schemes-electionguard. +Bug reports and pull requests are welcome on GitHub at https://github.com/decidim/decidim-bulletin-board.