CIP Draft

docs/cddl/diffs/common/endorser-blocks.md

@@ -0,0 +1,87 @@
+# Endorser Blocks - Leios CDDL
+
+Endorser Blocks (EBs) are new block types in Leios that aggregate multiple Input Blocks from the current pipeline.
+
+## Endorser Block Sortition
+
+**Single EB Limit**: Each producer can generate **at most one Endorser Block per pipeline**, following the crypto-benchmarks implementation approach rather than the full Poisson sortition used in simulations.
+
+**VRF Lottery**: Eligibility uses the simplified probability model:
+
+$$P = 1 - e^{-f_{EB} \cdot \sigma}$$
+
+Where $f_{EB}$ is the per-pipeline EB generation rate and $\sigma$ is the producer's stake fraction.
+
+> [!Important]
+> **Precision Requirements**: This computation MUST be performed using machine precision-independent arithmetic to ensure deterministic results across all implementations. The exponential function SHALL be computed using rational arithmetic (e.g., `num_rational::Ratio<BigInt>`) with a Taylor series expansion to a predefined precision (minimum 34 decimal places as implemented in crypto-benchmarks). This prevents floating-point precision variations between different hardware architectures and ensures consensus consistency.
+
+Sources: [Crypto-benchmarks Sortition](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/Specification.md#L63-L65), [Rust Simulation EB Generation](https://github.com/input-output-hk/ouroboros-leios/blob/main/sim-rs/sim-core/src/sim/node.rs#L606-L641), [Rational Arithmetic Implementation](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/src/sortition.rs#L1-L25), [Technical Report - Deterministic Computation](https://github.com/input-output-hk/ouroboros-leios/blob/main/docs/technical-report-1.md?plain=1#L510-L513)
+
+## Block Structure
+
+```diff
++ endorser_block =
++   [ eb_header         : eb_header
++   , eb_body           : eb_body
++   ]
+```
+
+## Header Structure
+
+```diff
++ eb_header =
++   [ eb_header_body       : eb_header_body
++   , body_signature       : kes_signature
++   ]
++ 
++ eb_header_body =
++   [ slot                 : slot_no                                  ; Slot when EB was created
++   , producer             : pool_id                                  ; Block producer identifier
++   , ? vrf_proof          : vrf_cert                                 ; VRF proof of eligibility to produce EB
++   ]
+```
+Sources: [Haskell Simulation EndorserBlock](https://github.com/input-output-hk/ouroboros-leios/blob/main/simulation/src/LeiosProtocol/Common.hs#L160-L171), [Rust Simulation EndorserBlock](https://github.com/input-output-hk/ouroboros-leios/blob/main/sim-rs/sim-core/src/model.rs#L167-L176), [Formal Spec EndorserBlockOSig](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Blocks.agda#L97-L106)
+
+## Body Structure
+
+**Design Rationale**: The block references are separated into the body to align with the network protocol design. At high TPS, the combined size of IB and EB references could exceed TCP MTU, making separate header/body transmission essential for efficient network diffusion.
+
+```diff
++ eb_body =
++   [ input_blocks         : [* ib_reference]                         ; References to input blocks
++   , ? endorser_blocks    : [* eb_reference]                         ; References to earlier endorser blocks (Full Leios)
++   ]
+```
+Sources: [Network Specification - Relay Protocol](https://github.com/input-output-hk/ouroboros-leios/blob/main/docs/technical-report-2.md#relay-mini-protocol), [Network Specification - Fetch Protocol](https://github.com/input-output-hk/ouroboros-leios/blob/main/docs/technical-report-2.md#fetch-mini-protocol)
+
+## Input Block Reference Structure
+
+```diff
++ ; References to input blocks within endorser blocks
++ ib_reference             = hash32                                               ; Hash identifier of the input block
+```
+
+**Design Rationale**: IB references contain only the hash identifier, following the principle that references should include only what's needed for unique identification. Producer and slot information can be obtained by fetching the block header when needed. This aligns with the formal specification's `IBRef = Hash` approach.
+
+Sources: [Haskell Simulation - InputBlockId](https://github.com/input-output-hk/ouroboros-leios/blob/main/simulation/src/LeiosProtocol/Common.hs#L100-L105), [Rust Simulation - InputBlockId](https://github.com/input-output-hk/ouroboros-leios/blob/main/sim-rs/sim-core/src/model.rs#L98-L105), [Formal Spec - IBRef](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Blocks.agda#L33), [Formal Spec - ibRefs](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Blocks.agda#L101)
+
+## Endorser Block Reference Structure
+
+```diff
++ ; References to earlier endorser blocks (for Full Leios)
++ eb_reference             = hash32                                               ; Hash identifier of the endorser block
+```
+Sources: [Haskell Simulation](https://github.com/input-output-hk/ouroboros-leios/blob/main/simulation/src/LeiosProtocol/Common.hs#L161-L163), [Rust Simulation](https://github.com/input-output-hk/ouroboros-leios/blob/main/sim-rs/sim-core/src/model.rs#L148-L152), [Formal Spec](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Blocks.agda#L34)
+
+## Supporting Types
+
+```diff
++ pool_id               = bytes .size 28                              ; Stake pool identifier (28 bytes)
++ slot_no               = uint64                                      ; Slot number
++ hash32                = bytes .size 32                              ; 32-byte hash
++ vrf_cert              = bytes                                       ; VRF certificate/proof
++ kes_signature         = bytes                                       ; KES signature
+```
+
+## Next
+**→ [Input Block - CDDL](input-blocks.md)**

docs/cddl/diffs/common/input-blocks.md

@@ -0,0 +1,55 @@
+# Input Blocks - Leios CDDL
+
+**Single IB Limit**: Each producer can generate **at most one Input Block per slot**, following the crypto-benchmarks implementation approach rather than the full Poisson sortition used in simulations.
+
+**VRF Lottery**: Eligibility uses the simplified probability model:
+
+$$P = 1 - e^{-f_{IB} \cdot \sigma}$$
+
+Where $f_{IB}$ is the per-slot IB generation rate and $\sigma$ is the producer's stake fraction.
+
+Sources: [Crypto-benchmarks Sortition](https://github.com/input-output-hk/ouroboros-leios/blob/main/crypto-benchmarks.rs/Specification.md?plain=1#L64), [Rust Simulation IB Generation](https://github.com/input-output-hk/ouroboros-leios/blob/main/sim-rs/sim-core/src/sim/node.rs#L561-L597)
+
+## Block Structure
+
+```diff
++ input_block =
++   [ ib_header                  : ib_header
++   , transaction_bodies         : [* transaction_body]
++   , transaction_witness_sets   : [* transaction_witness_set]
++   , auxiliary_data_set         : {* transaction_index => auxiliary_data}
++   , invalid_transactions       : [* transaction_index]
++   ]
+```
+Sources: [Formal Spec](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Blocks.agda#L40-L57), [Haskell Simulation](https://github.com/input-output-hk/ouroboros-leios/blob/main/simulation/src/LeiosProtocol/Common.hs#L138-L142), [Rust Simulation](https://github.com/input-output-hk/ouroboros-leios/blob/main/sim-rs/sim-core/src/model.rs#L136-L141)
+
+## Header Structure
+
+```diff
++ ib_header =
++   [ ib_header_body       : ib_header_body
++   , body_signature       : kes_signature
++   ]
++ 
++ ib_header_body =
++   [ slot                 : slot_no                                  ; Slot when IB was created
++   , producer_id          : pool_id                                  ; Block producer identifier
++   , vrf_proof            : vrf_cert                                 ; VRF proof of eligibility to produce IB
++   , ranking_block_ref    : hash32                                   ; Reference to ranking block for ledger state
++   ]
+```
+Sources: [Formal Spec](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Blocks.agda#L40-L45), [Haskell Simulation](https://github.com/input-output-hk/ouroboros-leios/blob/main/simulation/src/LeiosProtocol/Common.hs#L114-L124), [Rust Simulation](https://github.com/input-output-hk/ouroboros-leios/blob/main/sim-rs/sim-core/src/model.rs#L127-L133)
+
+## Supporting Types
+
+```diff
++ ; Block identifiers
++ ib_id = hash32                                                      ; Input block identifier (hash)
++ 
++ ; Basic types
++ pool_id = bytes                                                     ; Pool/producer identifier
++ slot_no = uint64                                                    ; Slot number
++ hash32 = bytes .size 32                                             ; 32-byte hash
++ vrf_cert = bytes                                                    ; VRF certificate/proof
++ kes_signature = bytes                                               ; KES signature
+``` 

docs/cddl/diffs/common/ranking-blocks.md

@@ -0,0 +1,20 @@
+# Ranking Blocks - Leios CDDL
+
+Ranking Blocks (RBs) are extended Praos blocks that include optional Leios certificates.
+
+## Block Structure - (Conway) Extension
+
+```diff
+ ranking_block =
+   [ header                   : block_header
+   , transaction_bodies       : [* transaction_body]
+   , transaction_witness_sets : [* transaction_witness_set]
+   , auxiliary_data_set       : {* transaction_index => auxiliary_data}
+   , invalid_transactions     : [* transaction_index]
++  , ? leios_cert             : leios_certificate
+   ]
+```
+Sources: [Conway Base](https://github.com/IntersectMBO/cardano-ledger/blob/master/eras/conway/impl/cddl-files/conway.cddl#L8-L14), [Leios Base](https://github.com/input-output-hk/ouroboros-leios-formal-spec/blob/main/formal-spec/Leios/Base.agda#L21-L22)
+
+## Next
+**→ [Votes and Certificates - CDDL](votes-certificates.md)**

docs/cddl/diffs/common/votes-certificates.md

@@ -0,0 +1,106 @@
+# Votes and Certificates - Leios CDDL
+
+Leios introduces a new BLS-based voting system with certificates for endorser block validation.
+
+## Certificate Structure
+
+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:
+
+```cddl
+; Complete Leios certificate structure (from crypto-benchmarks implementation)
+leios_certificate =
+  [ election_id            : election_id                             ; 8-byte election identifier (EID)
+  , endorser_block_hash    : hash32                                  ; Hash of the endorsed block (EB)  
+  , persistent_voters      : [* persistent_voter_id]                 ; Set of persistent voter IDs
+  , nonpersistent_voters   : {* pool_id => bls_signature}            ; Non-persistent voters with eligibility proofs
+  , ? aggregate_elig_sig   : bls_signature                           ; Aggregate eligibility signature (present when non-persistent voters exist)
+  , aggregate_vote_sig     : bls_signature                           ; Aggregate BLS signature on (election_id || endorser_block_hash)
+  ]
+```
+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)
+
+## Vote Structure
+
+The Leios voting system supports two types of voters: persistent voters (selected per epoch) and non-persistent voters (selected per election via local sortition).
+
+> [!Note]
+> 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.
+
+```cddl
+; Vote bundle containing votes for multiple endorser blocks from same voter
+leios_vote_bundle = persistent_vote_bundle / non_persistent_vote_bundle
+
+persistent_vote_bundle =
+  [ 0                        ; Vote type identifier for persistent voter
+  , election_id              ; 8-byte election identifier  
+  , persistent_voter_id      ; 2-byte epoch-specific pool identifier
+  , vote_entries             ; Map of endorser blocks to signatures
+  ]
+
+non_persistent_vote_bundle =
+  [ 1                        ; Vote type identifier for non-persistent voter
+  , election_id              ; 8-byte election identifier
+  , pool_id                  ; 28-byte pool identifier
+  , eligibility_signature    ; 48-byte BLS signature proving eligibility
+  , vote_entries             ; Map of endorser blocks to signatures
+  ]
+
+vote_entries = {* endorser_block_hash => vote_signature}
+```
+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)
+
+## BLS Key Registration
+
+For pools to participate in Leios voting, they must register BLS keys in their operational certificates:
+
+```diff
+ operational_cert = 
+   [ hot_vkey          : kes_vkey    
+   , sequence_number   : uint .size 8
+   , kes_period        : uint        
+   , sigma             : signature   
++  , ? bls_key_reg     : bls_key_registration
+   ]
+```
+Sources: [Conway Base](https://github.com/IntersectMBO/cardano-ledger/blob/master/eras/conway/impl/cddl-files/conway.cddl#L114-L119)
+
+```cddl
+; BLS key registration for voting (included in operational certificates)
+bls_key_registration =
+  [ pool_id               : pool_id                                    ; Pool identifier (28 bytes)
+  , bls_public_key        : bls_vkey                                   ; BLS12-381 G2 public key (96 bytes)
+  , proof_of_possession   : bls_proof_of_possession                    ; Proof of secret key possession (96 bytes)
+  , kes_signature         : kes_signature                              ; KES signature over the registration (448 bytes)
+  ]
+
+; Total size: 28 + 96 + 96 + 448 = 668 bytes
+```
+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)
+
+## Cryptographic Types
+
+```cddl
+; Core BLS cryptographic primitives
+bls_signature           = bytes .size 48                             ; BLS12-381 G1 signature (compressed)
+bls_vkey                = bytes .size 96                             ; BLS12-381 G2 public key (compressed)  
+bls_proof_of_possession =
+  [ mu1                 : bls_signature                              ; Signature on public key
+  , mu2                 : bls_signature                              ; Signature on empty message  
+  ]
+
+; Leios-specific identifiers  
+election_id             = bytes .size 8                              ; Slot-based election identifier
+persistent_voter_id     = uint .size 2                               ; Epoch-specific voter identifier (0-65535)
+pool_id                 = bytes .size 28                             ; Stake pool identifier
+endorser_block_hash     = bytes .size 32                             ; Hash of endorser block
+
+; Additional Cardano types used
+kes_signature           = bytes .size 448                            ; KES signature
+hash32                  = bytes .size 32                             ; 32-byte hash (used for endorser_block_hash)
+```
+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)
+
+
+
+## Next
+**→ [Endorser Block - CDDL](endorser-blocks.md)**

docs/cddl/diffs/eb-only/endorser-blocks.md

@@ -0,0 +1,22 @@
+# Endorser Blocks - Eb-Only Leios
+
+This file specifies the CDDL modifications for Endorser Blocks in Stracciatella Leios, which contain transaction references directly instead of introducing input blocks (IBs).
+
+## EB Extensions
+
+Stracciatella Leios extends the common endorser block structure from [Common Endorser Blocks](../common/endorser-blocks.md):
+
+```diff
+ eb_body =
+   [ 
+-    input_blocks         : [* ib_reference]                         ; References to input blocks
+   , ? endorser_blocks    : [* eb_reference]                         ; References to earlier endorser blocks (Full Leios)
++  , transaction_references: [* tx_reference]                        ; Transaction references instead of full transactions
+   ]
+```
+
+## Transaction Reference Structure
+
+```cddl
+tx_reference = bytes .size 32,                                       ; Transaction ID (hash)
+```

docs/cddl/diffs/full-sharding/README.md

@@ -0,0 +1,41 @@
+# Full Sharding - Leios
+
+This directory contains CDDL specifications for the **full sharding** approach to Leios ledger design.
+
+## Sharding Approaches
+
+The full sharding design provides two complementary mechanisms that **prevent transaction conflicts and duplicates** by ensuring potentially conflicting transactions are processed sequentially within the same shard rather than concurrently across different shards:
+
+### 1. UTxO Sharding ([Spec](./utxo.md))
+
+- **Mechanism**: Explicit `shard_label` field in transaction outputs matches implicit IB `shard` derived by its VRF proof
+- **Shard Assignment**: IB shard derived from VRF proof:
+
+  $$\text{shardId} = \text{vrf\_value} \bmod \text{totalShards}$$
+- **Network Overhead**: +2 bytes per labeled output
+
+### 2. Reward Account Sharding ([Spec](./reward-account.md))
+
+- **Mechanism**: Implicit shard assignment where transactions using reward accounts for collateral/withdrawals must match the IB's shard
+- **Shard Assignment**: Reward account shard derived from hash function:
+
+  $$\text{shardId} = \text{hash}(\text{rewardAccount}) \bmod \text{totalShards}$$
+- **Network Overhead**: 0 bytes (computed on-demand)
+
+## Sharding Benefits
+
+Both mechanisms contribute to the broader sharding strategy that:
+- **Prevents conflicts** by processing potentially conflicting transactions sequentially within the same shard
+- **Reduces duplicates** through per-shard mempool segmentation  
+
+## Comparison
+
+| Aspect | UTxO Sharding | Reward Account Sharding |
+|--------|---------------|------------------------|
+| **Explicitness** | Explicit `shard_label` field | Implicit hash-based |
+| **Network Overhead** | +2 bytes per output | 0 bytes |
+| **Flexibility** | Can choose shard | Deterministic shard |
+| **Bootstrapping** | Requires labeled UTxOs | Immediate availability |
+
+> [!Note]
+> **Design Rationale**: These approaches serve different purposes and can be used together or independently. Reward account sharding enables immediate onboarding while UTxO sharding provides operational control.