跳至主要内容
Condorcet.vote Alpha
← 技术文档

区块链

独立验证者读取、检查一场选举的链并重新计票所需的一切,都在这里,无需向我们索取。

每场选举都把自己的登记簿发布为一系列 JSON 文件,以哈希前后链接,并由平台签名。本页是这一格式的参考规范:通用信封、逐字段说明的四种区块类型、精确到字节的规则,以及平台封存每个区块前用来校验它的 JSON Schema(可在下方下载)。

协议版本与每场选举永久绑定,并在每个区块中重复写明;格式如有变更,会以新版本发布,并配有一套新的 Schema。

协议 v1

下载

封存区块所用的 JSON Schema 原件

JSON Schema draft 2020-12,每种区块类型一个文件,另加已签名选票的信封。这些正是平台实际使用的文件:从不接受任何额外属性;每个文件的规范 URL 写在它的 $id 中,文件也从这个 URL 提供。

信封

每个区块都有这五个字段

无论类型如何,区块都以同一个信封开头,字段按此阅读顺序排列。区块自身的哈希和签名从不写在 JSON 中(文档无法包含自身的哈希),而是作为单独的文件随区块提供。

protocol_version 整数
此版本始终为 1;同一条链上的每个区块都相同。
type 字符串
取 configuration、rings、votes、closure 之一。
election_id UUID v4,小写
选举标识符,每个区块都相同,也是每个环签名的 election_id 参数。
block_number 整数 ≥ 0
在每场选举内连续编号,configuration 区块为 0。
previous_hash null 或 128 个十六进制字符
前一个区块已存储字节的 SHA3-512,小写十六进制;只有区块 0 为 null。
信封 · block.*.json
{
  "protocol_version": 1,
  "type": "configuration | rings | votes | closure",
  "election_id": "0c2e7e2a-5df3-4c0e-9d2b-3f6a8f0c9e21",
  "block_number": 0,
  "previous_hash": null,
  ...
}
区块类型

固定的生命周期,从配置区块到结束区块

链首是一个 configuration 区块;启动时建立的环(启动环)放在一个 rings 区块中;投票期间每新建一个应急环,就增加一个 rings 区块;选票分批写入 votes 区块;最后由唯一的 closure 区块结束整条链。结果从不单独成块:它由已公布的选票重新计算得出。

区块 0 · 创世

configuration · 锁定的选举定义

投票开启后不再改变的内容。外观展示(Logo、照片、致谢语)有意不放入区块,也不参与哈希。

title, description?, organizer_name 字符串
说明性信息,随区块一起签名,但从不作为计票输入。
election_type preferential | fptp
排序投票(孔多塞方法)或单选。
method Schulze Winning | Schulze Margin | Ranked Pairs Winning | Ranked Pairs Margin | Copeland | Dodgson Quick | FPTP
正式计票方法,它得出的排名就是结果。封闭列表:每个取值都是 julien-boudry/condorcet 库中该方法的确切名称。当且仅当 election_type 为 fptp 时取 FPTP。链中从不公布结果:用这一方法即可重新计算。
seats 整数 ≥ 1
待选席位数。
voter_access_mode 字符串
版本 1 中为 closed_nominative_list。
enrolment_mandatory 布尔值
为 true 时只接受投票人自备的密钥(BYO-only);为 false 时允许使用服务器生成的密钥。
non_anonymous_voting, nominative_participation, weighted_voting 布尔值
隐私与加权的三个选项。non_anonymous_voting = true 时,nominative_participation 必须为 true(由 Schema 强制)。
adoption_threshold 对象,可选
仅限单选选举,未设置时省略。form(percent 或 fraction,与组织者的设置一致),numerator / denominator(整数,从不约分;百分比时 denominator 恰为 100),comparison(at_least 或 more_than),base(expressed 或 electoral_roll)。仅当 score × denominator ≥ numerator × base(more_than 时为 >)时,候选人才当选:整数精确运算,不做任何舍入。
max_ring_size 整数 ≥ 1
本场选举的环大小上限:任何环都不超过它,每个应急环的大小恰好等于它。
initial_electoral_roll_size 整数 ≥ 0
投票开启时选民名册的规模。投票期间可以新增选民;结束时的名册给出最终规模,因此新增人数是公开的,新增的是谁则从不公开。
ballot_rules 对象
ties_allowed、partial_ranking_allowed、blank_allowed、full_ranking_required:计票约束由这些选票参数确定性地推导得出。
candidates[].label 包含 2 至 30 个对象的数组
标签互不重复,长度 1 至 64 个字符,按标签排序(字节顺序)。标签是候选人的唯一标识。
区块 1 · 之后每个应急环一个

rings · 允许签名的密钥

每个环的完整公钥列表。区块 1 包含启动环;之后的每个 rings 区块包含一个应急环,这一点可从区块位置推知。环的成员集合一经公布即永久锁定。

rings[].ring_id UUID
环标识符,凡是用这个环签名的选票都会引用它;各环按 ring_id 排序。
rings[].ring_digest ring_<64 hex>_<8 hex>
环成员集合的规范 cryptoVote 摘要,与顺序无关。它可由 public_keys 推导,验证者会重新计算;公布它,是为了让投票人与自己浏览器根据收到的环算出的摘要比对。
rings[].public_keys[] pk_<64 hex>_<8 hex>
带前缀和校验和的公钥,升序排列,互不重复;每个环最多 max_ring_size 个。

同一场选举的启动环大小统一(介于 100 个密钥的下限与上限之间);应急环的大小恰好等于上限;BYO-only 选举的环由其登记选民组成,平均分配。

后续区块 · 分批

votes · 已签名选票

选票分批公布,每批至少 600 张(结束时为剩余的选票),从不逐张公布;每个区块内按密钥镜像排序,不带时间戳,也不保留到达顺序。

ballots[].ring_id UUID
验证签名所用公钥所在的环。
ballots[].key_image ki_<64 hex>_<8 hex>
限定于本场选举的密钥镜像:每场选举内唯一。第二张带有相同密钥镜像的选票就是重复投票,任何人都能看出。也是区块的排序键。
ballots[].signature blsag_…
对载荷确切字节所作的可链接环签名(基于 Ristretto255 的 bLSAG 变体)。
ballots[].payload 字符串(不透明 JSON)
原样保留的已签名文档:{"v":1,"election":"…","ballot":"A>B=C","weight":1[,"voter":"…"]}。从不重新序列化(参见载荷 Schema)。

ballot 字段是采用 CEF 排序语法的扁平字符串(或哨兵值 /EMPTY_RANKING/)。它的内容有意不做校验:格式错误的表达式会在计票时按一条公开、可复现的规则归为废票。

最后一个区块 · 终止

closure · 汇总数据与投票签到簿

恰好一个,位于最后,之后不再有任何区块。持有已签名的结束区块,即可证明一条链是完整的。投票签到簿只在这里出现一次,投票期间从不公布。

totals 由整数组成的对象
block_count、ballot_count、ring_count、voted_count、voted_weight,可与链本身交叉核对。
electoral_roll[].voter_id UUID v4
公布的选民编号(随机假名);内容为投票结束时的名册,按 voter_id 排序,每名选民一行,不标注哪些是新增的。
electoral_roll[].key_provisioning_mode 字符串
server_generated、organizer_imported 或 voter_enrolled。平台是否曾经持有这名选民的密钥,是公开的事实。
electoral_roll[].ring_id UUID 或 null
选民投票时所在的环;未投票则为 null。这是可验证的“选民 → 环”关联。
electoral_roll[].distribution_count 整数 ≥ 0
分发给这名选民的密钥数量(默认最多 3 个;组织者额外准许的次数仍然可见)。
electoral_roll[].has_voted, weight 布尔值,整数 ≥ 1
参与标记,以及作为核对依据的选票权重(未启用 weighted_voting 时为 1)。
electoral_roll[].voter_name, email_digest 字符串,可选
仅在启用实名签到簿时出现,且只针对已投票的选民:明文姓名和 SHA3-256(election_id ‖ 规范化的邮箱地址)。
序列化

字节即契约

  • 存储 = 提供 = 签名。 区块文件只写入一次,从不重新序列化。没有规范化 JSON 这一步:被哈希和签名的,就是对外提供的那个文件本身。
  • UTF-8 JSON,每行一项。 外层对象带缩进;大型集合(candidates、rings、ballots、electoral_roll)中的每一项都是独占一行的紧凑对象。斜杠和 Unicode 字符不转义。
  • 确定性排序,按字节顺序。 candidates 按 label,public_keys 升序,ballots 按 key_image,electoral_roll 按 voter_id,rings 按 ring_id:一律直接比较字节,从不使用语言排序规则。
  • 只用整数,不含时间戳。 protocol_version、block_number、seats、各类大小和汇总数都是非负整数;其他值一律为字符串。区块不带日期,选票也不带到达顺序。
  • 不允许额外属性和重复键。 每个 Schema 都禁止未知字段;JSON 中某个键重复出现的区块,验证者必须拒绝,因为各个解析器保留哪个值并不一致。
完整性

哈希、签名、时间戳

  • SHA3-512 哈希链接。 区块的哈希是其已存储字节的 SHA3-512,即 128 个小写十六进制字符;它就是下一个区块的 previous_hash。可用 openssl dgst -sha3-512 重新计算。
  • OpenPGP v6 分离式签名。 每个区块都由平台的 Ed25519 密钥(RFC 9580)对其确切字节签名,以 ASCII-armored 分离式签名的形式存放在 .sig 文件中。签名的创建时间就是区块的 signed_at;注记 domain@condorcet.vote = chain-block/v1 可防止签名被重放到其他类别的产物上。
  • 密钥轮换后仍可验证。 已停用的证书连同过期时间继续公开:按照标准 OpenPGP 有效性规则,在密钥有效期内签名的区块会被接受,其余的会被拒绝。
  • OpenTimestamps 锚定。 每个区块的普通 SHA-256 哈希都会锚定到比特币区块链上;.ots 文件无论处于等待状态还是已补全都会提供,并可用标准工具离线验证。
  • 自带标识的文件。 存储的产物以选举标识符命名({election}_{n}.json 及其附属文件),因此镜像文件即使脱离原 URL,也能识别出属于哪场选举。
OpenTimestamps 时间戳详解
端点

纯文件,没有 API

从投票开启到选举归档,所有内容都以文件形式在主域名上提供,可直接缓存,也可建立镜像。已取消的选举会撤下其登记簿。

/elections/{election}/chain
清单:按顺序列出各区块,含类型、哈希、signed_at、各产物的 URL 以及时间戳状态。
/elections/{election}/chain/{n}.json
区块 n,即已存储的确切字节。
/elections/{election}/chain/{n}.json.sig
区块 n 的 armored 分离式 OpenPGP 签名。
/elections/{election}/chain/{n}.json.ots
区块 n 的 OpenTimestamps 证明,等待中或已补全。
/.well-known/blockchain-signing-key
平台的签名证书(有效的和已停用的),拼接为一个文件(application/pgp-keys)。
/schemas/blockchain/block.{type}.schema.json
上文的 JSON Schema,位于各自 $id 中的规范 URL。
完整验证流程,逐项说明

选择允许 Condorcet.Vote 在公开页面上统计哪些数据。您的选择保存在本设备上,随时可以修改。

必要功能 始终启用

语言、主题,以及记住这些选择。