---

Cardano Foundation | Cardano Ballot

---

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

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

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.

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

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