Saltar para o conteúdo
Condorcet.vote Alpha
← Documentação técnica

Blockchain (protocolo)

Tudo o que um verificador independente precisa para ler, verificar e voltar a apurar a cadeia de uma eleição, sem nos pedir nada.

Cada eleição publica o seu registo como uma sequência de ficheiros JSON, encadeados por hash e assinados pela plataforma. Esta página é a referência desse formato: o envelope comum, os quatro tipos de bloco campo a campo, as regras byte a byte e os esquemas JSON com que a plataforma valida cada bloco antes de o selar, disponíveis para descarregar abaixo.

A versão fica ligada a cada eleição para sempre e repete-se em cada bloco. Uma alteração de formato exigiria uma nova versão, com o seu próprio conjunto de esquemas.

Protocolo v1

Descarregamentos

Os esquemas JSON usados para selar os blocos.

JSON Schema draft 2020-12, um ficheiro por tipo de bloco, mais o envelope do boletim assinado. São exatamente os ficheiros que a plataforma usa: nunca é aceite nenhuma propriedade adicional, e cada esquema é servido no URL canónico indicado no seu $id.

Envelope

Cinco campos em cada bloco.

Seja qual for o tipo, um bloco começa sempre pelo mesmo envelope, por esta ordem de leitura. O hash e a assinatura do bloco nunca estão dentro do JSON (um documento não pode conter o seu próprio hash): circulam à parte.

protocol_version inteiro
Sempre 1 nesta versão; idêntico em todos os blocos de uma cadeia.
type string
Um de: configuration, rings, votes, closure.
election_id UUID v4, minúsculas
O identificador da eleição, o mesmo em todos os blocos, e o parâmetro election_id de cada assinatura em anel.
block_number inteiro ≥ 0
Consecutivo por eleição, a partir de 0 para o bloco de configuração.
previous_hash null ou 128 caracteres hex
SHA3-512 dos bytes armazenados do bloco anterior, em hex minúsculo; null apenas no bloco 0.
Envelope · 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 bloco

Um ciclo de vida fixo, da configuração ao encerramento.

Um bloco de configuração no início, um bloco de anéis para os anéis de lançamento, um bloco de anéis por cada anel de emergência criado durante a votação, blocos de votos por lotes e um único bloco de encerramento, que termina a cadeia. O resultado nunca é um bloco: volta a calcular-se a partir dos boletins publicados.

Bloco 0 · génese

configuration · a definição fixada

O que já não pode mudar depois de aberta a votação. A apresentação visual (logótipo, fotografias, mensagem de agradecimento) fica deliberadamente fora do bloco e não entra no hash.

title, description?, organizer_name strings
Contexto informativo, assinado com o bloco, mas nunca usado no apuramento.
election_type preferential | fptp
Classificação (métodos de Condorcet) ou escolha única.
method Schulze Winning | Schulze Margin | Ranked Pairs Winning | Ranked Pairs Margin | Copeland | Dodgson Quick | FPTP
O método oficial, aquele cuja classificação constitui o resultado. Lista fechada: cada valor é o nome exato do método na biblioteca julien-boudry/condorcet. FPTP se e só se election_type for fptp. A cadeia não publica nenhum resultado: este recalcula-se com o método indicado.
seats inteiro ≥ 1
Lugares a preencher.
voter_access_mode string
closed_nominative_list na versão 1.
enrolment_mandatory booleano
Se verdadeiro, só são aceites chaves depositadas pelos próprios eleitores (BYO-only); se falso, são permitidas chaves geradas pelo servidor.
non_anonymous_voting, nominative_participation, weighted_voting booleanos
As três opções de privacidade e de ponderação. non_anonymous_voting = true obriga a nominative_participation = true (imposto pelo esquema).
adoption_threshold objeto, facultativo
Só em eleições de escolha única; ausente se não houver limiar. form (percent ou fraction, conforme definido pelo organizador), numerator / denominator (inteiros, nunca simplificados; exatamente 100 para uma percentagem), comparison (at_least ou more_than), base (expressed ou electoral_roll). Um candidato só é eleito se score × denominator ≥ numerator × base (> para more_than): um cálculo exato em inteiros, sem arredondamentos.
max_ring_size inteiro ≥ 1
O tamanho máximo dos anéis desta eleição: nenhum anel o ultrapassa, e cada anel de emergência tem exatamente este tamanho.
initial_electoral_roll_size inteiro ≥ 0
O tamanho do caderno eleitoral na abertura. Podem ser adicionados eleitores durante a votação; o caderno publicado no encerramento dá o tamanho final, por isso o número de adições é público, mas nunca quem foi adicionado.
ballot_rules objeto
ties_allowed, partial_ranking_allowed, blank_allowed, full_ranking_required: os parâmetros do boletim de que se derivam deterministicamente as restrições do apuramento.
candidates[].label array de 2 a 30 objetos
Etiquetas únicas, de 1 a 64 caracteres, ordenadas por etiqueta (ordem dos bytes). A etiqueta é o único identificador do candidato.
Bloco 1 · depois um por anel de emergência

rings · as chaves autorizadas a assinar

A lista completa das chaves públicas de cada anel. O bloco 1 contém os anéis de lançamento; qualquer bloco de anéis posterior contém um anel de emergência, o que se deduz da sua posição. Depois de publicado, o conjunto de membros de um anel fica fixado para sempre.

rings[].ring_id UUID
O identificador do anel, referido por cada boletim assinado com esse anel; anéis ordenados por ring_id.
rings[].ring_digest ring_<64 hex>_<8 hex>
O resumo cryptoVote canónico do conjunto de membros do anel, independente da ordem. Como deriva de public_keys, um verificador recalcula-o; é publicado para que um eleitor o possa comparar com o resumo que o seu navegador calculou a partir do anel recebido.
rings[].public_keys[] pk_<64 hex>_<8 hex>
Chaves públicas com prefixo e soma de verificação, por ordem crescente, sem repetições; no máximo max_ring_size por anel.

Os anéis de lançamento têm todos o mesmo tamanho numa dada eleição (entre o mínimo de 100 chaves e o máximo); os anéis de emergência têm exatamente o tamanho máximo; os anéis de uma eleição BYO-only contêm as chaves depositadas pelos seus eleitores, repartidas equitativamente.

Blocos seguintes · por lotes

votes · os boletins assinados

Os boletins são publicados em lotes de pelo menos 600 (o remanescente no encerramento), nunca um a um, e ordenados por imagem de chave dentro de cada bloco, sem data, hora ou ordem de chegada.

ballots[].ring_id UUID
O anel cujas chaves públicas servem para verificar a assinatura.
ballots[].key_image ki_<64 hex>_<8 hex>
A imagem de chave, própria da eleição: única por eleição. Um segundo boletim com a mesma imagem é um voto duplo, visível publicamente. Chave de ordenação do bloco.
ballots[].signature blsag_…
A assinatura em anel ligável (variante bLSAG sobre Ristretto255) dos bytes exatos do payload.
ballots[].payload string (JSON opaco)
O documento assinado, sem alterações: {"v":1,"election":"…","ballot":"A>B=C","weight":1[,"voter":"…"]}. Nunca é serializado de novo (ver o esquema do payload).

O campo ballot é uma string simples na sintaxe de classificação CEF (ou o valor sentinela /EMPTY_RANKING/). O seu conteúdo não é validado, de propósito: uma expressão mal formada é classificada como boletim nulo no apuramento, segundo uma regra publicada e reproduzível.

Bloco final · fim da cadeia

closure · totais e registo de participação

Exatamente um, o último, sem nada depois dele. Ter o bloco de encerramento assinado prova que a cadeia está completa. O registo de participação aparece aqui uma única vez, nunca durante a votação.

totals objeto de inteiros
block_count, ballot_count, ring_count, voted_count, voted_weight, que se podem conferir com a própria cadeia.
electoral_roll[].voter_id UUID v4
O ID de eleitor publicado (um pseudónimo aleatório); o caderno no encerramento, ordenado por voter_id, uma linha por eleitor, sem nenhuma marcada como adicionada.
electoral_roll[].key_provisioning_mode string
server_generated, organizer_imported ou voter_enrolled. Saber se a plataforma alguma vez teve a chave deste eleitor é um facto público.
electoral_roll[].ring_id UUID ou null
O anel em que o eleitor votou; null se não votou. A ligação verificável eleitor → anel.
electoral_roll[].distribution_count inteiro ≥ 0
O número de chaves distribuídas ao eleitor (no máximo 3 por predefinição; as distribuições adicionais concedidas pelo organizador continuam visíveis).
electoral_roll[].has_voted, weight booleano, inteiro ≥ 1
Indicador de participação e peso de referência do boletim (1, exceto com weighted_voting).
electoral_roll[].voter_name, email_digest strings, opcionais
Só com registo de participação nominal, e apenas para os eleitores que votaram: nome em claro e SHA3-256(election_id ‖ e-mail normalizado).
Serialização

Os bytes são o contrato.

  • Armazenado = servido = assinado. O ficheiro do bloco é escrito uma vez e nunca é serializado de novo. Não há nenhuma etapa de JSON canónico: o que entra no hash e na assinatura é o ficheiro tal como é servido.
  • JSON UTF-8, um elemento por linha. O objeto exterior é indentado; cada elemento das coleções grandes (candidates, rings, ballots, electoral_roll) é um objeto compacto na sua própria linha. As barras e o Unicode não são escapados.
  • Ordem determinística, byte a byte. candidates por label, public_keys por ordem crescente, ballots por key_image, electoral_roll por voter_id, rings por ring_id: comparação direta dos bytes, nunca uma ordenação linguística.
  • Só inteiros, sem datas. protocol_version, block_number, seats, tamanhos e totais são inteiros não negativos; qualquer outro valor é uma string. Nenhum bloco tem data, nenhum boletim tem ordem de chegada.
  • Sem propriedades adicionais nem chaves duplicadas. Cada esquema proíbe campos desconhecidos. Um verificador deve rejeitar um bloco cujo JSON repita uma chave, porque os analisadores divergem quanto ao valor que prevalece.
Integridade

Hash, assinatura, selo temporal.

  • Encadeamento SHA3-512. O hash de um bloco é o SHA3-512 dos seus bytes armazenados, em 128 caracteres hex minúsculos; é o previous_hash do bloco seguinte. Recalcule-o com openssl dgst -sha3-512.
  • Assinatura OpenPGP v6 destacada. A chave Ed25519 da plataforma (RFC 9580) assina os bytes exatos de cada bloco, numa assinatura destacada ASCII-armored guardada no ficheiro .sig. A data de criação da assinatura é o signed_at do bloco; uma notação domain@condorcet.vote = chain-block/v1 impede que seja reutilizada noutra classe de artefacto.
  • A rotação das chaves continua verificável. Os certificados retirados continuam publicados com a respetiva data de expiração: as regras de validade OpenPGP padrão aceitam os blocos assinados durante o período de validade de uma chave e rejeitam os restantes.
  • Ancoragem OpenTimestamps. O SHA-256 simples de cada bloco é ancorado na blockchain do Bitcoin. O ficheiro .ots é servido pendente ou completo e verifica-se offline com as ferramentas padrão.
  • Ficheiros autoidentificáveis. Os artefactos armazenados têm o identificador da eleição no nome ({election}_{n}.json e ficheiros complementares), por isso um ficheiro replicado em espelho continua identificável mesmo separado do seu URL.
A selagem temporal OpenTimestamps em pormenor
Endpoints

Ficheiros simples, sem API.

Tudo é servido como ficheiros que podem ser guardados em cache e replicados em espelho, no domínio principal, desde a abertura da votação até a eleição ser arquivada. Uma eleição cancelada retira o seu registo.

/elections/{election}/chain
O manifesto: lista ordenada dos blocos com tipo, hash, signed_at, URL dos artefactos e estado do selo temporal.
/elections/{election}/chain/{n}.json
O bloco n, com os bytes armazenados exatos.
/elections/{election}/chain/{n}.json.sig
A assinatura OpenPGP destacada (armored) do bloco n.
/elections/{election}/chain/{n}.json.ots
A prova OpenTimestamps do bloco n, pendente ou completa.
/.well-known/blockchain-signing-key
Os certificados de assinatura da plataforma, ativos e retirados, concatenados (application/pgp-keys).
/schemas/blockchain/block.{type}.schema.json
Os esquemas JSON acima, nos respetivos URL canónicos $id.
O procedimento de verificação completo, controlo a controlo

Escolha o que o Condorcet.Vote mede nas páginas públicas. A sua escolha fica guardada neste dispositivo e pode ser alterada a qualquer momento.

Essenciais Sempre ativos

Idioma, tema e memorização destas opções.