Cardano Ballot is a user-friendly, hybrid on- and off-chain voting system developed by the Cardano Foundation. Cardano Ballot leverages a set of backend services combined with frontend applications to facilitate voting within the Cardano Ecosystem.
Most recently, stake-based voting was introduced into Cardano Ballot inorder to support IOG with CIP-1694 Pre-ratification polling events. Currently, Cardano Ballot supports user-based (1 x user, 1 x vote) and stake-based (weighted) voting events. The modularised backend services make the process of organising, deploying, and auditing a Cardano Ballot event more decentralized and user-friendly.
In 2023, Hydra and Aiken Smart Contracts were also introduced into Cardano Ballot. The first implementation of this was a final Hydra tally of all votes submitted for the Cardano Summit Awards 2023.
| Event Types | Backend Service Modules | Cardano Standards, Libraries and Components | ||
|---|---|---|---|---|
| User-based | Admin | CIP-45 - Decentralized WebRTC d'App Wallet Communication | ||
| Stake-based | Voting App | CIP-93 - Authenticated Web3 HTTP Requests | ||
| Ledger Follower | CIP-30 - Cardano dApp-Wallet Web Bridge | |||
| Vote Commitment | CIP-08 - Message Signing | |||
| Vote Verification | Cardano Foundation - cardano-connect-with-wallet | |||
| User Verification | Bloxbean Projects | |||
| Hydra Tally | Aiken - A Modern Smart Contract Platform for Cardano | |||
| Hydra - Head Protocol |
- Node.js 18.x LTS
- Java 17 LTS
- Postgres DB 14.x or H2 file db (local development / community running)
- Docker
-
backend-services - Contains various backend services:
- hydra-tally-app - A CLI application which contains logic to connect to the Hydra network. Application demonstrates usage of smart contracts (Aiken) to perform counting (tally) of the votes and providing results.
- user-verification-service - A Spring Boot application that verifies user wallets using their phone number (via SMS OTP one time password) or Discord account.
- vote-commitment-app - Service that reads active events from ledger-follower-service and individual votes from database constructs merkle tree and at periodic, configurable intervals sends it to the Cardano blockchain.
- voting-admin-app - Application to be used by the organisers to create events and proposals.
- voting-app - Voting Application that allows users to submit votes, receive vote receipts, and access leaderboard data.
- voting-ledger-follower-app - Ledger Follower Application that is listening to the Cardano blockchain to fetch information about event data and user stake amounts in case of stake-based voting.
- voting-verification-app - Application to be used by the community / voters to independently verify and check vote proofs.
- keri-ballot-verifier - A Python microservice to verify the votes from Cardano Ballot signed using KERI identifiers.
-
ui - Contains React applications for Cardano Ballopt event user interfaces:
- cip-1694 - Frontend application for the CIP-1694 pre-ratification polling event.
- summit-2023 - Frontend application for the Cardano Summit 2023 Awards voting.
- verification-app - A generic frontend application for the verification / validation of the vote proof within a certain Cardano Ballot Event.
By default all backend apps are working with Cardano Pre-Production network.
cd cf-cardano-ballot/backend-services/voting-admin-app
./gradlew bootRunInstructions on how to create a new voting event can be found here.
By default all backend apps are working with Cardano Pre-Production network.
cd cf-cardano-ballot/backend-services/voting-ledger-follower-app
./gradlew bootRunThis will launch main voting-ledger-follower-app on port: 9090 by default. For a detailed description and interactive interface of the API, visit the Swagger UI documentation here: http://localhost:9090/swagger-ui/index.html
cd cf-cardano-ballot/backend-services/voting-app
./gradlew bootRunThis will launch main voting-app on port: 9091 by default. For a detailed description and interactive interface of the API, visit the Swagger UI documentation here: http://localhost:9091/swagger-ui/index.html
cd cf-cardano-ballot/backend-services/voting-verification-app
./gradlew bootRunThis will launch voting-verification-app on port: 9092 by default. For a detailed description and interactive interface of the API, visit the Swagger UI documentation here: http://localhost:9092/swagger-ui/index.html
Instructions on how to run the Vote Verification app can be found here.
cd cf-cardano-ballot/backend-services/vote-commitment-app
cp .env.template .env
# Update .env with required values (e.g. organiser's mnemonic)
# Run the service locally via:
./gradlew bootRunexport AWS_SNS_ACCESS_KEY_ID=...
export AWS_SNS_SECRET_ACCESS_KEY=...
cd cf-cardano-ballot/backend-services/user-verification-service
./gradlew bootRunThis will launch user-verification-app on port: 9093 by default. http://localhost:9093/swagger-ui/index.html
Note: user-verification-service is only needed for Cardano Summit 2023.
Note: binding PORT can be changed via SERVER_PORT env variable.
e.g.
SERVER_PORT=8888 ./gradlew bootRun
Use setupProxy.js to proxy services urls.
More instructions on the README of the microservice.
Copy the .env.example file and rename it as .env.
Then run:
cd cf-cardano-ballot/ui/summit-2023
cp .env.example .env
npm i
npm run startAll backend apps will generate TypeScript types for the frontend by using the following command:
As an example:
cd cf-cardano-ballot/backend-services/voting-app
./gradlew buildAndCopyTypescriptTypes -Pui_project_name=summit-2023This will generate TypeScript types in the ui/summit-2023/build/typescript-generator/voting-app-types.ts
For your own project you will need to replace summit-2023 with your respective project ui directory name.
All contributions are welcome! Please feel free to open a new thread on the issue tracker or submit a new pull request.
Please read Contributing first. Thank you for contributing.