---

Cardano Foundation | Cardano Ballot

[](https://opensource.org/licenses/MPL-2.0) [](https://conventionalcommits.org)   [](https://github.com/cardano-foundation/cf-cardano-ballot/actions/workflows/publish.yaml) [](https://github.com/cardano-foundation/cf-cardano-ballot/actions/workflows/voting-verification-app-build.yml) [](https://github.com/cardano-foundation/cf-cardano-ballot/actions/workflows/user-verification-app-build.yml) [](https://github.com/cardano-foundation/cf-cardano-ballot/actions/workflows/ui-cypress-tests.yaml)

---

Overview

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.

Features

Getting Started

Requirements

• Node.js 18.x LTS
• Java 17 LTS
• Postgres DB 14.x or H2 file db (local development / community running)
• Docker

Repository Structure

• 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.

Creating a Cardano Ballot Event

Voting Admin App

By default all backend apps are working with Cardano Pre-Production network.

cd cf-cardano-ballot/backend-services/voting-admin-app
./gradlew bootRun

Instructions on how to create a new voting event can be found here.

Running the Backend Services

Ledger Follower

By default all backend apps are working with Cardano Pre-Production network.

cd cf-cardano-ballot/backend-services/voting-ledger-follower-app
./gradlew bootRun

This 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

Voting App

cd cf-cardano-ballot/backend-services/voting-app
./gradlew bootRun

This 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

Voting Verification

cd cf-cardano-ballot/backend-services/voting-verification-app
./gradlew bootRun

This 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.

Voting Commitment App

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 bootRun

User Verification App

export AWS_SNS_ACCESS_KEY_ID=...
export AWS_SNS_SECRET_ACCESS_KEY=...
cd cf-cardano-ballot/backend-services/user-verification-service
./gradlew bootRun

This 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.

KERI Ballot Verifier

More instructions on the README of the microservice.

Running the Frontend (User Interface)

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 start

Backend -> Frontend Types Generation

All 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-2023

This 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.

Contributing

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.

Additional Docs

• Code of Conduct
• Security
• Changelog