Adapt & Improve the SDK Examples with new voting types

[jpaulet]

We need to update and improve our examples in the SDK regarding the new voting types and how they work.

• Define how the examples should work
• Create/update the example of the "Single Choice"
• Create/update the example of the "Multichoice"
• Update the example of the "Approval"
• Correct the "appoval" example to represent approval voting (right now is "multichoice" in the example)
• Create/update the example of the "Ranked voting"
• Create/update the example of the "Quadratic voting"
• Create/update the example of the "Weighted voting"
• Create/Update the example of the "Budget Voting"

This is an example on how it should look (the structure), logically, the code examples should be replaced to adapt to the SDK and after each little example, a link to the "complete tutorial", in a specific file.

Voting Types

This guide explains the different types of voting supported by the SDK, including how they work, code examples, and implementation tips using the SDK.

The Vocdoni SDK is designed to support various democratic voting processes, giving developers the flexibility to implement simple, complex, and token-based voting systems.

1. Single-Choice Voting

Description:
Participants can select only one option. Commonly used for elections where a single winner is chosen, such as a candidate election.

How It Works:
Voters choose one option from a set of predefined candidates.
Example: “Vote for the best project of the year.”

Code Example:

const election = createElection({
  title: "Best Project of the Year",
  type: VotingType.SingleChoice,
  options: ["Project A", "Project B", "Project C"],
});

Usage:
Single-choice voting fits scenarios where only one valid answer is expected, such as elections or polls.

2. Multiple-Choice Voting

Description:
Voters can select multiple options, with a limit on how many they can pick. Useful in scenarios like board member selections where multiple candidates are elected.

How It Works:
Define a minimum and maximum number of options voters can select.
Example: “Select up to 3 candidates for the board.”

Code Example:

const election = createElection({
  title: "Board Member Election",
  type: VotingType.MultipleChoice,
  options: ["Alice", "Bob", "Carol", "David"],
  minChoices: 1,
  maxChoices: 3,
});

Usage:
Ideal for scenarios where multiple winners are needed, such as board elections.

3. Approval Voting

Description:
Voters can select any number of options they approve of. This method is useful when participants want to express approval for multiple options.

How It Works:
Voters are allowed to select as many options as they want.
Example: “Approve the candidates you support.”

Code Example:

const election = createElection({
  title: "Executive Team Selection",
  type: VotingType.Approval,
  options: ["Alice", "Bob", "Carol"],
});

Usage:
Great for selecting multiple viable candidates or options where more than one selection can have value.

4. Ranked-Choice Voting

Description:
Voters rank options in order of preference, each option get's a score based on their order (i.e 4 points for the first, 3 points the 2nd, 2 points the 3rd, 1 point the 4th and 0 points the 5th.).

How It Works:
Voters assign a rank to each option. The first option gets X points,... the last 0 points.
Example: “Rank the candidates based on your preference.”

Code Example:

const election = createElection({
  title: "Favorite Programming Language",
  type: VotingType.RankedChoice,
  options: ["JavaScript", "Python", "Rust", "Go"],
});

Usage:
This method is used in elections where preferences matter, such as government or leadership elections.

5. Quadratic Voting

Description:
Participants are given a limited number of points to allocate across options. The cost of assigning points increases quadratically (e.g., 1 point = 1 cost, 2 points = 4 cost, etc.).

How It Works:
Useful for situations where expressing intensity of preference matters.
Example: Allocate your 9 points across projects to indicate which one should receive more funding.

Code Example:

const election = createElection({
  title: "Budget Allocation",
  type: VotingType.Quadratic,
  options: ["Healthcare", "Education", "Infrastructure"],
  totalPoints: 9,
});

Quadratic Cost Function:
1 point = 1 cost
2 points = 4 cost
3 points = 9 cost

Usage:
Great for participatory budgeting or where decision-makers need to express varying degrees of preference.

6. Weighted Voting

Description:
In Weighted Voting, votes are not equal. Voters (can) have different weights, such as proportional to shares owned or token holdings in a blockchain setting. This system ensures that those with a larger stake in the issue have a proportionate say.

How It Works:
Each voter is assigned a weight or number of votes.
The vote result is calculated by summing the weighted values for each option.
Example Use Case:
Shareholder Voting: A shareholder's vote is weighted by the number of shares they own.

Code Example:

const election = createElection({
  title: "Shareholder Vote on Mergers",
  type: VotingType.Weighted,
  options: ["Approve", "Reject"],
  weights: {
    "voter1": 100,  // 100 shares
    "voter2": 200,  // 200 shares
    "voter3": 50    // 50 shares
  },
});

Usage:
Ideal for corporate governance, shareholder resolutions, or token-based decisions.

7. Participatory Budgeting

Description:
This voting type allows voters to distribute a set number of points across multiple options. Unlike quadratic voting, the cost is linear, meaning each point spent counts equally. This system is ideal for allocating community or public funds.

How It Works:
Voters have a fixed number of points to distribute across the available options.
The options receiving the most points are allocated the corresponding share of the budget.
Example Use Case:
Community Budget Allocation: A community decides how to spend funds on public services.

Code Example:

const election = createElection({
  title: "Community Fund Allocation",
  type: VotingType.ParticipatoryBudgeting,
  options: ["Park Renovation", "Library Expansion", "Sports Equipment"],
  totalPoints: 100,
});

Usage:
Participatory budgeting is perfect for public or organizational budgets where multiple stakeholders need to express preferences on how funds should be allocated.