Zum Inhalt springen
Condorcet.vote Alpha
← Technische Dokumentation

Blockchain

Alles, was ein unabhängiger Prüfer braucht, um die Kette einer Wahl zu lesen, zu kontrollieren und neu auszuzählen, ohne uns um irgendetwas bitten zu müssen.

Jede Wahl veröffentlicht ihr Register als Folge von JSON-Dateien, per Hash verkettet und von der Plattform signiert. Diese Seite ist die Referenz dieses Formats: der gemeinsame Umschlag, die vier Blocktypen Feld für Feld, die Regeln auf Byte-Ebene und die JSON-Schemas, gegen die die Plattform jeden Block validiert, bevor sie ihn versiegelt. Sie stehen unten zum Herunterladen bereit.

Die Version ist dauerhaft an jede Wahl gebunden und wird in jedem Block wiederholt. Eine Formatänderung käme als neue Version mit eigenen Schemas.

Protokoll v1

Downloads

Die JSON-Schemas, mit denen versiegelt wird.

JSON Schema draft 2020-12, eine Datei pro Blocktyp und dazu der Umschlag des signierten Stimmzettels. Es sind genau die Dateien, die die Plattform verwendet: Zusätzliche Eigenschaften werden nie akzeptiert, und jede Datei wird unter der kanonischen URL ausgeliefert, die in ihrem $id steht.

Umschlag

Fünf Felder in jedem Block.

Unabhängig vom Typ beginnt jeder Block mit demselben Umschlag, in dieser Lesereihenfolge. Hash und Signatur des Blocks stehen nie im JSON (ein Dokument kann seinen eigenen Hash nicht enthalten); sie werden getrennt mitgeliefert.

protocol_version Ganzzahl
Immer 1 für diese Version; in jedem Block einer Kette gleich.
type Zeichenkette
Einer der Werte configuration, rings, votes, closure.
election_id UUID v4, Kleinbuchstaben
Die Kennung der Wahl, in jedem Block dieselbe, und der Parameter election_id jeder Ringsignatur.
block_number Ganzzahl ≥ 0
Fortlaufend pro Wahl, beginnend mit 0 für den Konfigurationsblock.
previous_hash null oder 128 Hex-Zeichen
SHA3-512 der gespeicherten Bytes des vorherigen Blocks, Hex in Kleinbuchstaben; null nur in Block 0.
Umschlag · block.*.json
{
  "protocol_version": 1,
  "type": "configuration | rings | votes | closure",
  "election_id": "0c2e7e2a-5df3-4c0e-9d2b-3f6a8f0c9e21",
  "block_number": 0,
  "previous_hash": null,
  ...
}
Blocktypen

Ein fester Ablauf, von der Konfiguration bis zum Abschluss.

Am Anfang steht ein Konfigurationsblock, dann folgen ein Ring-Block für die Startringe, ein Ring-Block für jeden während der Stimmabgabe gebildeten Ausweichring, Stimmenblöcke in Stapeln und ein einziger Abschlussblock, der die Kette beendet. Das Ergebnis ist nie ein Block: Es wird aus den veröffentlichten Stimmzetteln neu berechnet.

Block 0 · Genesis

configuration · die fixierte Definition

Was sich nach Beginn der Stimmabgabe nicht mehr ändert. Die optische Gestaltung (Logo, Fotos, Dankesnachricht) liegt bewusst außerhalb des Blocks und wird nicht gehasht.

title, description?, organizer_name Zeichenketten
Informativer Kontext: mit dem Block signiert, fließt aber nie in die Auszählung ein.
election_type preferential | fptp
Rangfolge (Condorcet-Methoden) oder relative Mehrheit (eine Stimme).
method Schulze Winning | Schulze Margin | Ranked Pairs Winning | Ranked Pairs Margin | Copeland | Dodgson Quick | FPTP
Die maßgebliche Methode, deren Rangfolge das Ergebnis bildet. Geschlossene Liste: Jeder Wert ist der genaue Name der Methode in der Bibliothek julien-boudry/condorcet. FPTP genau dann, wenn election_type den Wert fptp hat. Die Kette enthält kein Ergebnis: Es wird mit dieser Methode neu berechnet.
seats Ganzzahl ≥ 1
Zu vergebende Sitze.
voter_access_mode Zeichenkette
closed_nominative_list in Version 1.
enrolment_mandatory boolescher Wert
Bei true nur von den Wählern hinterlegte Schlüssel (BYO-only); bei false sind auch vom Server erzeugte Schlüssel zulässig.
non_anonymous_voting, nominative_participation, weighted_voting boolesche Werte
Die drei Optionen für Anonymität und Gewichtung. non_anonymous_voting = true erzwingt nominative_participation = true (vom Schema durchgesetzt).
adoption_threshold Objekt, optional
Nur bei Wahlen mit relativer Mehrheit; fehlt, wenn keine Schwelle festgelegt ist. form (percent oder fraction, wie vom Organisator eingestellt), numerator / denominator (Ganzzahlen, nie gekürzt; genau 100 bei einem Prozentsatz), comparison (at_least oder more_than), base (expressed oder electoral_roll). Ein Kandidat ist nur gewählt, wenn score × denominator ≥ numerator × base (> bei more_than): eine exakte Ganzzahlrechnung ohne Rundung.
max_ring_size Ganzzahl ≥ 1
Die Obergrenze der Ringgröße für diese Wahl: Kein Ring überschreitet sie, jeder Ausweichring hat genau diese Größe.
initial_electoral_roll_size Ganzzahl ≥ 0
Die Größe des Wählerverzeichnisses bei der Eröffnung. Während der Stimmabgabe können Wähler hinzukommen; das Verzeichnis im Abschlussblock nennt die endgültige Größe. Die Zahl der Nachträge ist damit öffentlich, nie aber, wer nachgetragen wurde.
ballot_rules Objekt
ties_allowed, partial_ranking_allowed, blank_allowed, full_ranking_required: die Stimmzettelparameter, aus denen die Bedingungen der Auszählung deterministisch abgeleitet werden.
candidates[].label Array aus 2 bis 30 Objekten
Eindeutige Bezeichnungen, 1 bis 64 Zeichen, nach Bezeichnung sortiert (Byte-Reihenfolge). Die Bezeichnung ist die einzige Kennung eines Kandidaten.
Block 1 · danach einer pro Ausweichring

rings · die zum Signieren berechtigten Schlüssel

Die vollständige Liste der öffentlichen Schlüssel jedes Rings. Block 1 enthält die Startringe; jeder spätere Ring-Block enthält einen Ausweichring, was sich aus seiner Position ergibt. Ist ein Ring veröffentlicht, bleibt die Menge seiner Mitglieder für immer fixiert.

rings[].ring_id UUID
Die Kennung des Rings, auf die jeder mit diesem Ring signierte Stimmzettel verweist; Ringe nach ring_id sortiert.
rings[].ring_digest ring_<64 hex>_<8 hex>
Der kanonische cryptoVote-Hashwert der Mitgliedermenge des Rings, unabhängig von der Reihenfolge. Er lässt sich aus public_keys ableiten, ein Prüfer berechnet ihn nach. Veröffentlicht wird er, damit ein Wähler ihn mit dem Hashwert vergleichen kann, den sein Browser aus dem erhaltenen Ring berechnet hat.
rings[].public_keys[] pk_<64 hex>_<8 hex>
Präfixierte öffentliche Schlüssel mit Prüfsumme, aufsteigend sortiert, eindeutig; höchstens max_ring_size pro Ring.

Die Startringe haben pro Wahl eine einheitliche Größe (zwischen der Untergrenze von 100 Schlüsseln und der Obergrenze); Ausweichringe haben genau die Obergrenze; bei einer BYO-only-Wahl enthalten die Ringe ihre Wahlberechtigten, gleichmäßig verteilt.

Folgende Blöcke · in Stapeln

votes · die signierten Stimmzettel

Die Stimmzettel werden in Stapeln von mindestens 600 veröffentlicht (zum Ende der Stimmabgabe der Rest), nie einzeln, und in jedem Block nach Schlüsselabbild sortiert, ohne Zeitstempel und ohne Eingangsreihenfolge.

ballots[].ring_id UUID
Der Ring, mit dessen öffentlichen Schlüsseln sich die Signatur prüfen lässt.
ballots[].key_image ki_<64 hex>_<8 hex>
Das an die Wahl gebundene Schlüsselabbild (key image): eindeutig pro Wahl. Ein zweiter Stimmzettel mit demselben Abbild ist eine doppelte Stimmabgabe und öffentlich erkennbar. Sortierschlüssel des Blocks.
ballots[].signature blsag_…
Die verknüpfbare Ringsignatur (bLSAG-Variante auf Ristretto255) über die exakten Bytes der Nutzdaten.
ballots[].payload Zeichenkette (opakes JSON)
Das signierte Dokument, unverändert: {"v":1,"election":"…","ballot":"A>B=C","weight":1[,"voter":"…"]}. Nie neu serialisiert (siehe Schema der Nutzdaten).

Das Feld ballot ist eine flache Zeichenkette in CEF-Rangfolgesyntax (oder der Sentinel-Wert /EMPTY_RANKING/). Sein Inhalt wird bewusst nicht validiert: Ein fehlerhafter Ausdruck wird bei der Auszählung nach einer veröffentlichten, reproduzierbaren Regel als ungültiger Stimmzettel eingestuft.

Letzter Block · Kettenende

closure · Summen und Teilnahmeliste

Genau einer, der letzte, danach nichts mehr. Wer den signierten Abschlussblock besitzt, hat den Beweis, dass eine Kette vollständig ist. Die Teilnahmeliste erscheint nur hier, einmalig und nie während der Stimmabgabe.

totals Objekt aus Ganzzahlen
block_count, ballot_count, ring_count, voted_count, voted_weight, mit der Kette selbst abgleichbar.
electoral_roll[].voter_id UUID v4
Die veröffentlichte Wähler-ID (ein zufälliges Pseudonym); das Verzeichnis zum Ende der Stimmabgabe, nach voter_id sortiert, eine Zeile pro Wähler, keine als nachgetragen markiert.
electoral_roll[].key_provisioning_mode Zeichenkette
server_generated, organizer_imported oder voter_enrolled. Ob die Plattform den Schlüssel dieses Wählers je besessen hat, ist damit öffentlich.
electoral_roll[].ring_id UUID oder null
Der Ring, in dem der Wähler abgestimmt hat; null, wenn er nicht abgestimmt hat. Die überprüfbare Verbindung Wähler → Ring.
electoral_roll[].distribution_count Ganzzahl ≥ 0
Die Zahl der an den Wähler ausgegebenen Schlüssel (standardmäßig höchstens 3; vom Organisator gewährte Zusatzschlüssel bleiben sichtbar).
electoral_roll[].has_voted, weight boolescher Wert, Ganzzahl ≥ 1
Teilnahme-Flag und maßgebliches Gewicht des Stimmzettels (1, außer bei weighted_voting).
electoral_roll[].voter_name, email_digest Zeichenketten, optional
Nur bei namentlicher Teilnahmeliste, für Wähler, die abgestimmt haben: Name im Klartext und SHA3-256(election_id ‖ normalisierte E-Mail-Adresse).
Serialisierung

Die Bytes sind der Vertrag.

  • Gespeichert = ausgeliefert = signiert. Die Blockdatei wird einmal geschrieben und nie neu serialisiert. Einen Schritt mit kanonischem JSON gibt es nicht: Gehasht und signiert wird die Datei so, wie sie ausgeliefert wird.
  • UTF-8-JSON, ein Element pro Zeile. Das äußere Objekt ist eingerückt; jedes Element der großen Sammlungen (candidates, rings, ballots, electoral_roll) ist ein kompaktes Objekt in einer eigenen Zeile. Schrägstriche und Unicode werden nicht maskiert.
  • Deterministische Byte-Sortierung. candidates nach label, public_keys aufsteigend, ballots nach key_image, electoral_roll nach voter_id, rings nach ring_id: reiner Bytevergleich, nie eine sprachabhängige Sortierung.
  • Nur Ganzzahlen, keine Zeitstempel. protocol_version, block_number, seats, Größen und Summen sind nicht negative Ganzzahlen; alle anderen Werte sind Zeichenketten. Kein Block trägt ein Datum, kein Stimmzettel eine Eingangsreihenfolge.
  • Keine zusätzlichen Eigenschaften, keine doppelten Schlüssel. Jedes Schema verbietet unbekannte Felder. Ein Prüfer muss einen Block ablehnen, dessen JSON einen Schlüssel wiederholt, weil Parser unterschiedlich entscheiden, welcher Wert gilt.
Integrität

Hash, Signatur, Zeitstempel.

  • Verkettung per SHA3-512. Der Hash eines Blocks ist der SHA3-512 seiner gespeicherten Bytes, 128 Hex-Zeichen in Kleinbuchstaben; er ist der previous_hash des nächsten Blocks. Berechnen Sie ihn mit openssl dgst -sha3-512 nach.
  • Abgetrennte OpenPGP-v6-Signatur. Jeder Block wird über seine exakten Bytes mit dem Ed25519-Schlüssel der Plattform signiert (RFC 9580), als abgetrennte Signatur im Format ASCII-armored in der Datei .sig. Ihr Erstellungszeitpunkt ist das signed_at des Blocks; eine Notation domain@condorcet.vote = chain-block/v1 verhindert, dass sie für eine andere Art von Artefakt wiederverwendet wird.
  • Die Schlüsselrotation bleibt überprüfbar. Außer Dienst gestellte Zertifikate bleiben mit ihrem Ablaufdatum veröffentlicht: Nach den üblichen OpenPGP-Gültigkeitsregeln werden Blöcke akzeptiert, die im Gültigkeitszeitraum eines Schlüssels signiert wurden, alle anderen abgelehnt.
  • OpenTimestamps-Verankerung. Der einfache SHA-256-Hash jedes Blocks wird in der Bitcoin-Blockchain festgeschrieben; die .ots-Datei wird ausstehend oder vervollständigt ausgeliefert und lässt sich mit den üblichen Werkzeugen offline prüfen.
  • Selbstidentifizierende Dateien. Die gespeicherten Artefakte tragen die Kennung der Wahl im Namen ({election}_{n}.json und Sidecar-Dateien). Eine gespiegelte Datei bleibt so auch ohne ihre URL zuordenbar.
Die Zeitstempelung mit OpenTimestamps im Detail
Endpunkte

Rohdateien, keine API.

Alles wird als direkt cachefähige und spiegelbare Dateien auf der Hauptdomain ausgeliefert, von der Eröffnung der Stimmabgabe bis zur Archivierung der Wahl. Bei einer annullierten Wahl wird das Register zurückgezogen.

/elections/{election}/chain
Das Manifest: geordnete Liste der Blöcke mit Typ, Hash, signed_at, URLs der Artefakte und Status des Zeitstempels.
/elections/{election}/chain/{n}.json
Block n, die exakt gespeicherten Bytes.
/elections/{election}/chain/{n}.json.sig
Die abgetrennte OpenPGP-Signatur (armored) von Block n.
/elections/{election}/chain/{n}.json.ots
Der OpenTimestamps-Nachweis von Block n, ausstehend oder vervollständigt.
/.well-known/blockchain-signing-key
Die Signaturzertifikate der Plattform, aktive und außer Dienst gestellte, aneinandergehängt (application/pgp-keys).
/schemas/blockchain/block.{type}.schema.json
Die obigen JSON-Schemas unter ihren kanonischen $id-URLs.
Das vollständige Prüfverfahren, Schritt für Schritt

Legen Sie fest, was Condorcet.Vote auf seinen öffentlichen Seiten misst. Ihre Auswahl wird auf diesem Gerät gespeichert und lässt sich jederzeit ändern.

Notwendig Immer aktiv

Sprache, Design und Speicherung dieser Auswahl.