Ir al contenido
Condorcet.vote Alpha
← Documentación técnica

Blockchain

Todo lo que necesita un verificador independiente para leer, comprobar y recontar la cadena de una elección sin pedirnos nada.

Cada elección publica su registro como una serie de archivos JSON encadenados por hash y firmados por la plataforma. Esta página es la referencia de ese formato: el sobre común, los cuatro tipos de bloque campo por campo, las reglas byte a byte y los esquemas JSON con los que la plataforma valida cada bloque antes de sellarlo. Puede descargar esos esquemas más abajo.

La versión queda vinculada a cada elección para siempre y se repite en cada bloque; un cambio de formato exigiría una nueva versión con su propio juego de esquemas.

Protocolo v1

Sobre

Cinco campos en cada bloque.

Sea cual sea su tipo, un bloque empieza con el mismo sobre, en este orden de lectura. El hash y la firma del bloque nunca figuran en el JSON (un documento no puede contener su propio hash): viajan junto a él.

protocol_version entero
Siempre 1 en esta versión; idéntico en todos los bloques de una cadena.
type cadena
Uno de estos valores: configuration, rings, votes, closure.
election_id UUID v4, en minúsculas
El identificador de la elección, el mismo en cada bloque, y el parámetro election_id de cada firma de anillo.
block_number entero ≥ 0
Consecutivo dentro de cada elección, empezando en 0 con el bloque de configuración.
previous_hash null o 128 caracteres hex
SHA3-512 de los bytes almacenados del bloque anterior, en hexadecimal en minúsculas; null solo en el bloque 0.
Sobre · block.*.json
{
  "protocol_version": 1,
  "type": "configuration | rings | votes | closure",
  "election_id": "0c2e7e2a-5df3-4c0e-9d2b-3f6a8f0c9e21",
  "block_number": 0,
  "previous_hash": null,
  ...
}
Tipos de bloque

Un ciclo de vida fijo, de la configuración al cierre.

Un bloque de configuración al principio, un bloque de anillos para los anillos de lanzamiento, un bloque de anillos por cada anillo de emergencia creado durante la votación, bloques de votos por lotes y un único bloque de cierre que termina la cadena. El resultado nunca es un bloque: se recalcula a partir de las papeletas publicadas.

Bloque 0 · génesis

configuration · la definición bloqueada

Lo que ya no cambiará una vez abierta la votación. La presentación estética (logotipo, fotos, mensaje de agradecimiento) queda deliberadamente fuera del bloque y no entra en el hash.

title, description?, organizer_name cadenas
Contexto informativo, firmado con el bloque pero nunca utilizado en el escrutinio.
election_type preferential | fptp
Clasificación (métodos de Condorcet) u opción única.
method Schulze Winning | Schulze Margin | Ranked Pairs Winning | Ranked Pairs Margin | Copeland | Dodgson Quick | FPTP
El método oficial, aquel cuya clasificación constituye el resultado. Lista cerrada: cada valor es el nombre exacto del método en la biblioteca julien-boudry/condorcet. FPTP si y solo si election_type vale fptp. La cadena no publica ningún resultado: se recalcula con este método.
seats entero ≥ 1
Escaños por cubrir.
voter_access_mode cadena
closed_nominative_list en la versión 1.
enrolment_mandatory booleano
Si es verdadero, solo se admiten claves aportadas por los votantes (BYO-only); si es falso, también se admiten claves generadas por el servidor.
non_anonymous_voting, nominative_participation, weighted_voting booleanos
Las tres opciones de privacidad y de ponderación. non_anonymous_voting = true obliga a nominative_participation = true (lo impone el esquema).
adoption_threshold objeto, opcional
Solo en elecciones de opción única; ausente si no hay umbral. form (percent o fraction, según lo configuró el organizador), numerator / denominator (enteros, nunca simplificados; exactamente 100 para un porcentaje), comparison (at_least o more_than), base (expressed o electoral_roll). Un candidato solo resulta elegido si score × denominator ≥ numerator × base (> con more_than), un cálculo exacto con enteros y sin redondeo.
max_ring_size entero ≥ 1
El tope de tamaño de anillo de esta elección: ningún anillo lo supera y cada anillo de emergencia tiene exactamente ese tamaño.
initial_electoral_roll_size entero ≥ 0
El tamaño del censo electoral en la apertura. Se pueden añadir votantes durante la votación y el censo del cierre da el tamaño final, así que el número de votantes añadidos es público, pero nunca su identidad.
ballot_rules objeto
ties_allowed, partial_ranking_allowed, blank_allowed, full_ranking_required: los parámetros de la papeleta de los que se derivan, de forma determinista, las restricciones del escrutinio.
candidates[].label array de 2 a 30 objetos
Etiquetas únicas, de 1 a 64 caracteres, ordenadas por etiqueta (orden de bytes). La etiqueta es el único identificador del candidato.
Bloque 1 · y luego uno por anillo de emergencia

rings · las claves autorizadas para firmar

La lista completa de claves públicas de cada anillo. El bloque 1 contiene los anillos de lanzamiento; cualquier bloque de anillos posterior contiene un anillo de emergencia, como se deduce de su posición. Una vez publicado, el conjunto de miembros de un anillo queda bloqueado para siempre.

rings[].ring_id UUID
El identificador de anillo al que remite cada papeleta firmada en ese anillo; los anillos se ordenan por ring_id.
rings[].ring_digest ring_<64 hex>_<8 hex>
La huella canónica cryptoVote del conjunto de miembros del anillo, independiente del orden. Se deriva de public_keys y un verificador la recalcula; se publica para que un votante pueda compararla con la que su navegador calculó a partir del anillo recibido.
rings[].public_keys[] pk_<64 hex>_<8 hex>
Claves públicas con prefijo y suma de verificación, en orden ascendente y sin repetir; como máximo max_ring_size por anillo.

Los anillos de lanzamiento comparten un mismo tamaño en cada elección (entre el mínimo de 100 claves y el tope); los anillos de emergencia tienen exactamente el tamaño del tope; los anillos de una elección BYO-only contienen a sus inscritos, repartidos de forma equitativa.

Bloques siguientes · por lotes

votes · las papeletas firmadas

Las papeletas se publican por lotes de al menos 600 (salvo el resto, al cierre), nunca una a una, y se ordenan por imagen de clave dentro de cada bloque, sin marca de tiempo ni orden de llegada.

ballots[].ring_id UUID
El anillo con cuyas claves públicas se verifica la firma.
ballots[].key_image ki_<64 hex>_<8 hex>
La imagen de clave propia de la elección: única en cada elección. Una segunda papeleta con la misma imagen es un doble voto a la vista de todos. Es la clave de ordenación del bloque.
ballots[].signature blsag_…
La firma de anillo enlazable (variante bLSAG sobre Ristretto255) sobre los bytes exactos del payload.
ballots[].payload cadena (JSON opaco)
El documento firmado, tal cual: {"v":1,"election":"…","ballot":"A>B=C","weight":1[,"voter":"…"]}. Nunca se vuelve a serializar (véase el esquema del payload).

El campo ballot es una cadena plana con la sintaxis de clasificación CEF (o el centinela /EMPTY_RANKING/). Su contenido no se valida a propósito: una expresión mal formada se clasifica como papeleta nula en el escrutinio, según una regla publicada y reproducible.

Bloque final · terminador

closure · totales y registro de participación

Exactamente uno, el último, y nada después. Tener el bloque de cierre firmado demuestra que una cadena está completa. El registro de participación aparece aquí una sola vez, nunca durante la votación.

totals objeto de enteros
block_count, ballot_count, ring_count, voted_count, voted_weight, que se pueden cotejar con la propia cadena.
electoral_roll[].voter_id UUID v4
El ID de votante publicado (un seudónimo aleatorio); el censo al cierre, ordenado por voter_id, una línea por votante y ninguna marcada como añadida.
electoral_roll[].key_provisioning_mode cadena
server_generated, organizer_imported o voter_enrolled. Cualquiera puede saber así si la plataforma tuvo alguna vez la clave de este votante.
electoral_roll[].ring_id UUID o null
El anillo en el que votó el votante; null si no votó. Es el vínculo verificable votante → anillo.
electoral_roll[].distribution_count entero ≥ 0
El número de claves entregadas al votante (3 como máximo por defecto; las ampliaciones concedidas por el organizador quedan a la vista).
electoral_roll[].has_voted, weight booleano, entero ≥ 1
Indicador de participación y peso de referencia de la papeleta (1 salvo con weighted_voting).
electoral_roll[].voter_name, email_digest cadenas, opcionales
Solo con el registro de participación nominativo, y únicamente para los votantes que han votado: nombre en claro y SHA3-256(election_id ‖ correo electrónico normalizado).
Serialización

Los bytes son el contrato.

  • Almacenado = servido = firmado. El archivo del bloque se escribe una vez y nunca se vuelve a serializar. No hay ningún paso de JSON canónico: el hash y la firma se calculan sobre el archivo tal como se sirve.
  • JSON UTF-8, un elemento por línea. El objeto exterior va sangrado; cada elemento de las colecciones grandes (candidates, rings, ballots, electoral_roll) es un objeto compacto en su propia línea. Ni las barras ni los caracteres Unicode se escapan.
  • Orden determinista, por bytes. candidates por label, public_keys en orden ascendente, ballots por key_image, electoral_roll por voter_id, rings por ring_id. Se comparan los bytes en bruto, nunca con una ordenación lingüística.
  • Solo enteros, ninguna marca de tiempo. protocol_version, block_number, seats, tamaños y totales son enteros no negativos; cualquier otro valor es una cadena. Ningún bloque lleva fecha y ninguna papeleta lleva orden de llegada.
  • Ninguna propiedad adicional, ninguna clave duplicada. Cada esquema prohíbe los campos desconocidos. Un verificador debe rechazar un bloque cuyo JSON repita una clave, porque los analizadores no coinciden en qué valor conservan.
Integridad

Hash, firma, sello de tiempo.

  • Encadenamiento SHA3-512. El hash de un bloque es el SHA3-512 de sus bytes almacenados, 128 caracteres hexadecimales en minúsculas, y constituye el previous_hash del bloque siguiente. Puede recalcularlo con openssl dgst -sha3-512.
  • Firma OpenPGP v6 separada. Cada bloque se firma sobre sus bytes exactos con la clave Ed25519 de la plataforma (RFC 9580), como firma separada ASCII-armored en el archivo .sig. Su fecha de creación es el signed_at del bloque; una notación domain@condorcet.vote = chain-block/v1 impide reutilizarla en otra clase de artefacto.
  • La rotación de claves sigue siendo verificable. Los certificados retirados siguen publicados con su fecha de caducidad: las reglas de validez estándar de OpenPGP aceptan los bloques firmados dentro del periodo de validez de una clave y rechazan los demás.
  • Anclaje OpenTimestamps. El SHA-256 simple de cada bloque se ancla en la blockchain de Bitcoin. El archivo .ots se sirve tanto pendiente como completado y se verifica sin conexión con las herramientas estándar.
  • Archivos autoidentificativos. Los artefactos almacenados llevan el identificador de la elección ({election}_{n}.json y archivos sidecar), de modo que un archivo replicado sigue siendo identificable aunque se separe de su URL.
El sellado de tiempo OpenTimestamps en detalle
Puntos de acceso

Archivos en bruto, sin API.

Todo se sirve como archivos que se pueden almacenar en caché y replicar, en el dominio principal, desde la apertura de la votación hasta el archivado de la elección. Una elección anulada retira su registro.

/elections/{election}/chain
El manifiesto: lista ordenada de los bloques con su tipo, hash, signed_at, las URL de los artefactos y el estado del sellado de tiempo.
/elections/{election}/chain/{n}.json
El bloque n, con sus bytes almacenados exactos.
/elections/{election}/chain/{n}.json.sig
La firma OpenPGP separada (armored) del bloque n.
/elections/{election}/chain/{n}.json.ots
La prueba OpenTimestamps del bloque n, pendiente o completada.
/.well-known/blockchain-signing-key
Los certificados de firma de la plataforma, activos y retirados, concatenados (application/pgp-keys).
/schemas/blockchain/block.{type}.schema.json
Los esquemas JSON anteriores, en sus URL canónicas $id.
El procedimiento de verificación completo, comprobación por comprobación

Elija qué mide Condorcet.Vote en sus páginas públicas. Su elección se guarda en este dispositivo y puede cambiarla en cualquier momento.

Imprescindibles Siempre activos

Idioma, tema y conservación de estas opciones.