|
| 1 | +# Votes and Certificates - Leios CDDL |
| 2 | + |
| 3 | +Leios introduces a new BLS-based voting system with certificates for endorser block validation. |
| 4 | + |
| 5 | +## Certificate Structure |
| 6 | + |
| 7 | +Leios certificates are embedded in Ranking Blocks as described in [Ranking Block - CDDL](ranking-blocks.md). These certificates attest to the validity of Endorser Blocks as described in [Endorser Block - CDDL](endorser-blocks.md). Here is the complete certificate structure: |
| 8 | + |
| 9 | +```cddl |
| 10 | +; Complete Leios certificate structure (from crypto-benchmarks implementation) |
| 11 | +leios_certificate = |
| 12 | + [ election_id : election_id ; 8-byte election identifier (EID) |
| 13 | + , endorser_block_hash : hash32 ; Hash of the endorsed block (EB) |
| 14 | + , persistent_voters : [* persistent_voter_id] ; Set of persistent voter IDs |
| 15 | + , nonpersistent_voters : {* pool_id => bls_signature} ; Non-persistent voters with eligibility proofs |
| 16 | + , ? aggregate_elig_sig : bls_signature ; Aggregate eligibility signature (present when non-persistent voters exist) |
| 17 | + , aggregate_vote_sig : bls_signature ; Aggregate BLS signature on (election_id || endorser_block_hash) |
| 18 | + ] |
| 19 | +``` |
| 20 | +Sources: [Certificate Reference Implementation](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/cert.rs#L13-L21), [Certificate Abstract Interface](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Base.agda#L24-L28) |
| 21 | + |
| 22 | +## Vote Structure |
| 23 | + |
| 24 | +The Leios voting system supports two types of voters: persistent voters (selected per epoch) and non-persistent voters (selected per election via local sortition). |
| 25 | + |
| 26 | +> [!Note] |
| 27 | +> Individual votes are ephemeral data structures used during the voting process. They are aggregated into certificates and do not appear on the ledger or persistent storage. Only the resulting certificates are stored permanently. |
| 28 | +
|
| 29 | +```cddl |
| 30 | +; Vote bundle containing votes for multiple endorser blocks from same voter |
| 31 | +leios_vote_bundle = persistent_vote_bundle / non_persistent_vote_bundle |
| 32 | +
|
| 33 | +persistent_vote_bundle = |
| 34 | + [ 0 ; Vote type identifier for persistent voter |
| 35 | + , election_id ; 8-byte election identifier |
| 36 | + , persistent_voter_id ; 2-byte epoch-specific pool identifier |
| 37 | + , vote_entries ; Map of endorser blocks to signatures |
| 38 | + ] |
| 39 | +
|
| 40 | +non_persistent_vote_bundle = |
| 41 | + [ 1 ; Vote type identifier for non-persistent voter |
| 42 | + , election_id ; 8-byte election identifier |
| 43 | + , pool_id ; 28-byte pool identifier |
| 44 | + , eligibility_signature ; 48-byte BLS signature proving eligibility |
| 45 | + , vote_entries ; Map of endorser blocks to signatures |
| 46 | + ] |
| 47 | +
|
| 48 | +vote_entries = {* endorser_block_hash => vote_signature} |
| 49 | +``` |
| 50 | +Sources: [Vote Reference Implementation](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/vote.rs#L13-L27), [Formal Specification - Vote Abstract Interface](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Abstract.agda#L24-L27), [Haskell Bundle Usage](https://github.com/input-output-hk/ouroboros-leios/blob/main/simulation/src/LeiosProtocol/Short.hs#L231-L234), [Rust Vote Bundle](https://github.com/input-output-hk/ouroboros-leios/blob/main/sim-rs/sim-core/src/model.rs#L208-L212) |
| 51 | + |
| 52 | +## BLS Key Registration |
| 53 | + |
| 54 | +For pools to participate in Leios voting, they must register BLS keys in their operational certificates: |
| 55 | + |
| 56 | +```diff |
| 57 | + operational_cert = |
| 58 | + [ hot_vkey : kes_vkey |
| 59 | + , sequence_number : uint .size 8 |
| 60 | + , kes_period : uint |
| 61 | + , sigma : signature |
| 62 | ++ , ? bls_key_reg : bls_key_registration |
| 63 | + ] |
| 64 | +``` |
| 65 | +Sources: [Conway Base](https://github.com/IntersectMBO/cardano-ledger/blob/master/eras/conway/impl/cddl-files/conway.cddl#L114-L119) |
| 66 | + |
| 67 | +```cddl |
| 68 | +; BLS key registration for voting (included in operational certificates) |
| 69 | +bls_key_registration = |
| 70 | + [ pool_id : pool_id ; Pool identifier (28 bytes) |
| 71 | + , bls_public_key : bls_vkey ; BLS12-381 G2 public key (96 bytes) |
| 72 | + , proof_of_possession : bls_proof_of_possession ; Proof of secret key possession (96 bytes) |
| 73 | + , kes_signature : kes_signature ; KES signature over the registration (448 bytes) |
| 74 | + ] |
| 75 | +
|
| 76 | +; Total size: 28 + 96 + 96 + 448 = 668 bytes |
| 77 | +``` |
| 78 | +Sources: [Registration Struct](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/key.rs#L156-L162), [Proof Generation](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/bls_vote.rs#L19-L23) |
| 79 | + |
| 80 | +## Cryptographic Types |
| 81 | + |
| 82 | +```cddl |
| 83 | +; Core BLS cryptographic primitives |
| 84 | +bls_signature = bytes .size 48 ; BLS12-381 G1 signature (compressed) |
| 85 | +bls_vkey = bytes .size 96 ; BLS12-381 G2 public key (compressed) |
| 86 | +bls_proof_of_possession = |
| 87 | + [ mu1 : bls_signature ; Signature on public key |
| 88 | + , mu2 : bls_signature ; Signature on empty message |
| 89 | + ] |
| 90 | +
|
| 91 | +; Leios-specific identifiers |
| 92 | +election_id = bytes .size 8 ; Slot-based election identifier |
| 93 | +persistent_voter_id = uint .size 2 ; Epoch-specific voter identifier (0-65535) |
| 94 | +pool_id = bytes .size 28 ; Stake pool identifier |
| 95 | +endorser_block_hash = bytes .size 32 ; Hash of endorser block |
| 96 | +
|
| 97 | +; Additional Cardano types used |
| 98 | +kes_signature = bytes .size 448 ; KES signature |
| 99 | +hash32 = bytes .size 32 ; 32-byte hash (used for endorser_block_hash) |
| 100 | +``` |
| 101 | +Sources: [Sig](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/key.rs#L100), [PubKey](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/key.rs#L62), [PoP](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/key.rs#L139-L143), [Eid](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/primitive.rs#L76), [PersistentId](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/registry.rs#L14), [PoolKeyhash](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/primitive.rs#L14), [EbHash](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/primitive.rs#L117), [KesSig](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/primitive.rs#L170) |
| 102 | + |
| 103 | + |
| 104 | + |
| 105 | +## Next |
| 106 | +**→ [Endorser Block - CDDL](endorser-blocks.md)** |
0 commit comments