SuperAPI AI Directory

vocdoni-ballot-protocol

General & other

View repository

Updated 11-04 17:19

About this skill

Vocdoni Ballot Protocol

A small, deliberate specification for how Vocdoni encodes ballots and accumulates results. Everything the SDK does ends up serialised into this shape — knowing it makes the SDK's IVoteType fields make sense and lets you debug "why does my vote array produce those results" without guessing.

This is the data model under the API. Read [[vocdoni-sdk]] for the SDK call surface that produces and consumes these ballots.

Core idea

A voting process has one or more fields. Each field is either:

  • a question (single-choice-multiquestion elections — Vote([q1_choice, q2_choice, …])), or
  • an option of a single question (approval, multichoice, budget, quadratic, ranked — Vote([opt1_value, opt2_value, …])).

A ballot is an array of natural numbers, one entry per field. Each entry is the voter's value for that field.

Results are accumulated in a matrix:

  • rows = fields
  • columns = possible values for that field (0, 1, …, maxValue)
  • cell results[i][j] = number of voters who put value j in field i

So results are not a per-option vote count — they're a histogram over (field, value) pairs. To get a per-option tally, the client applies an interpretation (index-weighted or discrete-counting; see below).

Protocol parameters

These are stored on-chain per election and constrain what ballots are valid.

Parameter Type Meaning
maxCount uint8 Number of fields per ballot. Range: 1 ≤ maxCount ≤ 100.
maxValue uint8 Maximum value any field may take. 0 is a special marker meaning "values are amounts to aggregate" (budget/quadratic).
minValue uint8 Minimum value any field may take.
uniqueValues bool If true, no value may appear twice in a single ballot (used by ranked voting).
maxTotalCost uint16 Upper bound on Σ(value[i] ^ costExponent). 0 means "no limit / not applicable".
minTotalCost uint16 Lower bound on the same sum. 0 means "no limit".
costExponent uint16 Exponent applied per-value when computing the total cost. Stored scaled by 10 000 on chain (see "costExponent scaling" below).

Cost formula

totalCost = Σ (value[i] ^ costExponent)

A ballot is valid only if minTotalCost ≤ totalCost ≤ maxTotalCost (each bound ignored when set to 0).

For quadratic voting (costExponent = 2):

Vote([2, 2, 2, 0])  cost = 2² + 2² + 2² + 0² = 12
Vote([1, 1, 2, 2])  cost = 1² + 1² + 2² + 2² = 10
Vote([0, 3, 1, 1])  cost = 0² + 3² + 1² + 1² = 11

costExponent scaling

On chain, costExponent is stored as exp × 10 000 so that fractional exponents are representable:

Stored value Effective exponent
0 0.0000
10 000 1.0000
20 000 2.0000
65 535 6.5535 (max)

The SDK's IVoteType.costExponent accepts either form depending on context; recipes and the QuadraticElection variant use the human-readable form (2 for quadratic). When in doubt, read what the variant class sets, not the raw protocol value.

SDK ↔ protocol mapping

These are the corresponding IVoteType fields in @vocdoni/sdk (see [[vocdoni-sdk]]'s elections.md):

Protocol SDK IVoteType field Notes
maxCount maxCount SDK auto-fills as questions.length (multi-question) or choices.length (single-question).
maxValue maxValue SDK auto-fills as max(choices.length - 1) across questions. Set to 0 for budget/quadratic.
minValue (no direct field) The SDK enforces non-negativity; explicit minima come via election variants.
uniqueValues uniqueChoices Renamed for human clarity. Required by ranked elections.
maxTotalCost maxTotalCost Election variants set this from maxBudget (budget/quadratic).
minTotalCost (set by variants) BudgetElection's forceFullBudget enforces equality via min = max.
costExponent costExponent 1 (linear) or 2 (quadratic) in the SDK's human form.
costFromWeight costFromWeight SDK-only convenience; toggles whether maxTotalCost is 0 (use census weight as budget).

The SDK's variant classes (ApprovalElection, MultiChoiceElection, BudgetElection, QuadraticElection) exist precisely to set the right protocol parameters for common shapes — they're presets, not new on-chain features.

Results matrix — how to read it

results[fieldIndex][value] = number of voters who chose value for that field.

Worked example: rate 3 candidates 0..2

maxCount = 3, maxValue = 2, three voters:

Vote([2,1,2])  → Lennon=2, Hendrix=1, Joplin=2
Vote([0,1,2])  → Lennon=0, Hendrix=1, Joplin=2
Vote([0,0,0])  → all zeros

After accumulation:

results = [
  [2, 0, 1],   // field 0 (Lennon):  value 0 chosen by 2 voters, value 1 by 0, value 2 by 1
  [1, 2, 0],   // field 1 (Hendrix): value 0 by 1, value 1 by 2, value 2 by 0
  [1, 0, 2],   // field 2 (Joplin):  value 0 by 1, value 1 by 0, value 2 by 2
]

Interpretation (index-weighted): for each field, multiply each count by its column index and sum:

Lennon  = 2·0 + 0·1 + 1·2 = 2
Hendrix = 1·0 + 2·1 + 0·2 = 2
Joplin  = 1·0 + 0·1 + 2·2 = 4
Total ballots = (2+0+1) = (1+2+0) = (1+0+2) = 3

That's the score per candidate. The on-chain matrix is the raw histogram; the score is computed off-chain by clients.

Result interpretation modes

The scrutinizer returns the raw histogram; clients pick one of two aggregations driven by election metadata:

"results": {
  "aggregation": "index-weighted",  // or "discrete-counting"
  "display": "rating"                // "rating" | "simple-question" | "multiple-choice" | "linear-weighted" | "quadratic-voting" | "multiple-question" | "raw"
}

index-weighted — single-question-style

For each field, multiply counts by column index, sum. Works for: rating, single choice, multiple choice, quadratic, linear-weighted ranked.

[[1,0,1], [2,0,0], [0,1,1]]
  → [0·1 + 1·0 + 2·1,   0·2 + 1·0 + 2·0,   0·0 + 1·1 + 2·1]
  → [2, 0, 3]

Field 0: 2 points, field 1: 0 points, field 2: 3 points.

discrete-counting — multi-question-style

Field values are just counted (each cell stands on its own; no positional weight). Only valid when each field is a separate question with at most one yes/no per ballot field.

[[1,2,0], [0,1,2], [1,1,1]]
  → field 1: choice0 = 1, choice1 = 2, choice2 = 0
     field 2: choice0 = 0, choice1 = 1, choice2 = 2
     field 3: choice0 = 1, choice1 = 1, choice2 = 1

Use only with the basic multi-question / single-choice configuration. Quadratic / budget / approval cannot use this mode.

Common parameter recipes (with the protocol values)

Each row shows the canonical parameter combination for a familiar election shape, and what the ballot/results look like.

Rate a product 0..5

Voters give a star rating from 0 to 5.

maxCount minValue maxValue minTotalCost maxTotalCost costExponent uniqueValues
1 0 5 — — — false

Ballots: [2], [5], [2] → results: [ [0,0,2,0,0,1] ] (two votes for 2 stars, one for 5).

Rate N candidates 0..M, ranks may not repeat

Three candidates, scores 0..2 — but each score used at most once (ranking).

maxCount minValue maxValue minTotalCost maxTotalCost costExponent uniqueValues
3 0 2 — — — true

Ballots: [2,1,2], [0,1,2], [0,0,0] → see worked example above.

Single choice (out of three)

Pick exactly one of three options.

maxCount minValue maxValue minTotalCost maxTotalCost costExponent uniqueValues
3 0 1 1 1 — false

Ballot shape: [v0, v1, v2] where each v_i ∈ {0, 1} and Σ v_i = 1. (i.e. exactly one of the positions is 1.)

Ballots: [0,1,0], [0,1,0], [0,0,1] → results: [ [3,0,0], [1,2,0], [2,1,0] ].

Per-option (index-weighted): [0·3 + 1·0 + 2·0, 0·1 + 1·2 + 2·0, 0·2 + 1·1 + 2·0] = [0, 2, 1].

Approval voting

"Choose any subset of N options." 5 options, between 0 and N approvals (or with a min/max budget on the count itself).

maxCount minValue maxValue minTotalCost maxTotalCost costExponent uniqueValues
5 0 1 3 3 — false

The minTotalCost = maxTotalCost = 3 forces exactly 3 approvals. Set both to 0 for unlimited.

Ballots: [1,1,1,0,0], [0,1,1,1,0], [1,1,1,0,0] → results: [ [1,2], [0,3], [0,3], [2,1], [3,0] ]. Approval count per option: [2, 3, 3, 1, 0].

Linear weighted (ranked) choice

Sort 5 options; rank 0..4, each used once.

maxCount minValue maxValue minTotalCost maxTotalCost costExponent uniqueValues
5 0 4 — — — true

The uniqueValues = true enforces "no rank used twice".

Quadratic voting

Distribute 12 credits across 4 NGOs; cost = value².

maxCount minValue maxValue minTotalCost maxTotalCost costExponent uniqueValues
4 0 0 * 0 12 2 false

* maxValue = 0 here is the "values are aggregable amounts" marker — the upper bound on each individual value comes from maxTotalCost and costExponent.

Example ballots and their costs:

[2,2,2,0]   cost = 4 + 4 + 4 + 0 = 12 ✓
[1,1,2,2]   cost = 1 + 1 + 4 + 4 = 10 ✓
[0,3,1,1]   cost = 0 + 9 + 1 + 1 = 11 ✓
[3,3,0,0]   cost = 9 + 9 + 0 + 0 = 18 ✗ (over 12)

Multi-question, single choice per question

3 positions (CEO, COO, CFO), 5 candidates per position.

maxCount minValue maxValue minTotalCost maxTotalCost costExponent uniqueValues
3 0 4 — — — false

Ballots: [4,3,2], [4,2,3], [0,1,4] → results [ [1,0,0,0,2], [0,1,1,1,0], [0,0,1,1,1] ].

This is the case to use discrete-counting: read each field as "votes per candidate for this position", not as "weighted points".

Why this matters for the SDK user

  1. Vote-shape errors stop being mysterious. Vote([…]) is exactly the on-chain ballot. When the SDK throws Invalid vote, the message is about violating one of maxCount / maxValue / uniqueValues / maxTotalCost. Look at the protocol params; the SDK is just a thin checker around them.
  2. Results are a histogram, not a tally. If you console.log(election.results) and see a matrix instead of a per-option count, it's not a bug. Pick the right interpretation (index-weighted or discrete-counting) for the election type — see "Result interpretation modes".
  3. Variants are presets, not new primitives. ApprovalElection, MultiChoiceElection, BudgetElection, QuadraticElection set protocol parameters for you. Knowing the underlying parameters helps you (a) understand why the variant is constrained the way it is, and (b) build a custom shape via the base Election.from(...) when no variant fits.
  4. maxValue = 0 is a flag, not zero. It means "field values are aggregable amounts whose cap comes from maxTotalCost and costExponent" — used by budget and quadratic. Don't read it as "each value can be at most 0".

Cross-references

  • [[vocdoni-sdk]] — the SDK that produces and consumes ballots of this shape.
    • references/elections.md — IVoteType fields that map to these protocol parameters.
    • references/election-types.md — which preset (Approval/MultiChoice/Budget/Quadratic) sets which parameters.
    • references/voting.md — Vote([…]) shape per election kind.
    • references/results.md — reading election.results matrices.
  • Vocdoni blog post: https://blog.vocdoni.io/vocdoni-ballot-protocol/