implementation plan

Author: curiecrypt

docs/leios-design/README.md

@@ -505,13 +505,12 @@ Non-persistent voters, on the other hand, are selected independently for each EB
 Registered voters can generate and cast votes, each including an `endorser_block_hash` field that uniquely identifies the target EB. 
 Collected votes are then aggregated into a compact certificate.
 
-#### Leios Voting in a Nutshell
+**Leios Voting in a Nutshell**
 - **Key Generation**  
   - A secret key ($sk$) is created to generate signatures for the corresponding signature scheme.  
   - The public key ($pk$) is securely derived from $sk$ and used to verify the corresponding signatures.  
   - A proof of possession ($PoP$) is generated for $sk$ to ensure key ownership.  
   > Note that keys are not rotated periodically, as forward security is not required for IBs, EBs, or votes.
-
 - **Key Registration**  
   - The registration process is responsible for storing public keys and verifying proof of possession.  
   - Each stake pool registers with the following information:  
@@ -520,17 +519,14 @@ Collected votes are then aggregated into a compact certificate.
     - $PoP$  
     - A KES signature over the Pool ID, $pk$, and $PoP$  
   - Nodes verify the $PoP$s of all received $pk$s to confirm their validity.
-
 - **Voter Determination**  
   - For each epoch, *persistent voters* are selected based on the stake distribution and participate in every election during that epoch.  
   - Within the same epoch, *non-persistent voters* are chosen randomly and independently for each election.
-
 - **Voting**  
   - Voters sign the election ID and the EB hash with their $sk$.  
   - Each vote includes the election ID, the EB hash, and the corresponding signature.  
   - Persistent votes additionally include an epoch-specific identifier of the stake pool.  
   - Non-persistent votes include the Pool ID and an eligibility signature on the election ID.
-
 - **Certificate Generation**  
   - Upon receiving votes, both voter identities and their signatures are verified.  
   - Non-persistent votes are further validated for eligibility.  
@@ -541,7 +537,8 @@ Collected votes are then aggregated into a compact certificate.
     - Eligibility proofs for non-persistent voters  
     - An aggregate signature combining all individual voter signatures
 
-#### Requirements
+**Requirements**
+
 The voting and certificate scheme in Leios must satisfy key requirements to ensure security, efficiency, and practical deployability.
 
 Key registration should be lightweight, requiring minimal data exchange or coordination among participants. 
@@ -563,7 +560,7 @@ The large size of Praos KES signatures makes them unsuitable, highlighting the n
 Lastly, the cryptographic operations for eligibility verification, vote generation, and certificate validation must be highly efficient. 
 The total workload should stay well within the CPU budget for Leios stages, ensuring strong performance and scalability under real-world conditions.
 
-#### Design Choices
+**Design Choices**
 
 Several certificate schemes were evaluated for Leios, including ALBA variants, SNARK-based voting schemes, and BLS-based certificates, with the goal of identifying a design that best satisfies the security, efficiency, and deployability requirements described above. 
 After comparison, BLS certificates based on the *Fait Accompli* sortition scheme were selected as the preferred approach. 
@@ -577,6 +574,42 @@ This approach is advantageous because it enables the aggregation of public keys
 Beyond Leios, the BLS mechanism is also relevant to other Cardano subsystems; Mithril already employs BLS-based aggregation, and Peras is expected to adopt a similar approach in future implementations.
 
 #### Implementation Plan
+To implement the linear Leios design, efficient BLS signature functionality is essential for achieving fast and compact certificate generation. 
+With the adoption of [CIP-0381](https://cips.cardano.org/cip/CIP-0381), `cardano-base` already provides foundational utilities for BLS operations, offering a solid basis for this integration. 
+Building on these capabilities, the implementation plan introduces additional bindings and helper modules to ensure smooth interaction with the Leios protocol within the Haskell node. 
+
+This section presents the implementation plan for extending `cardano-base` with BLS signature support and outlines the modifications required to satisfy Leios-specific needs. 
+The requirements are organized into two main categories: **core functionality**, which defines the essential BLS operations needed, and **performance and quality**, which ensures the implementation meets the expected efficiency, reliability, and maintainability standards.
+
+**Core functionality**
+- **BLS types:** The `BLS12_381.Internal` module in `cardano-base` already provides a comprehensive set of types designed for safe interaction with the linked C functions from the `blst` library. As part of the integration effort, it is necessary to evaluate which additional types should be introduced beyond those already defined, ensuring full support for the BLS functionality required by Leios.
+- **Key generation:** 
+  - Secure key generation must ensure strong randomness and resilience against side-channel attacks. To achieve this, an integration with the `blst` library through a FFI is required. This involves adding the necessary foreign function imports to the `BLS12_381.Internal` module and implementing the corresponding `SecretKey` type to enable safe and efficient handling of secret keys within the Haskell environment.
+  - The `blst` library exposes a key-generation function [`blst_keygen`](https://github.com/supranational/blst/blob/e7f90de551e8df682f3cc99067d204d8b90d27ad/bindings/blst.h#L330) 
+    ```C
+    void blst_keygen(blst_scalar *out_SK, const byte *IKM, size_t IKM_len, const byte *info DEFNULL, size_t info_len DEFNULL);
+    ```
+    which derives a secret key from input keying material (IKM) and optional `info`. To use this safely in `cardano-base`, we need to clarify the security guarantees of this construction: what qualifies as a cryptographically secure IKM (length, entropy, generation source) and how `info` should be used (additional entropy vs. domain/context bytes). In parallel, we should examine how `cardano-base` currently sources seeds for other schemes in the `DSIGN` class, review the `blst` keygen C implementation to assess robustness and side-channel posture, align our requirements with the IETF BLS draft’s guidance on key generation (see the “KeyGen” section in the CFRG draft), and determine whether `info` is treated as entropy input or merely contextual/domain-separation data; documenting these findings will let us standardize secure IKM generation and `info` usage for BLS within `cardano-base`.
+- **Proof-of-Possession:** The `blst` C library does not provide a direct interface for generating a proof of possession ($PoP$). Therefore, this functionality must be implemented manually in `cardano-base`, leveraging the existing `blst` bindings to construct a $PoP$ from the available primitives.
+- **Public key derivation:** Implement deterministic derivation of the public key ($pk$) from the corresponding secret key ($sk$) for the selected BLS variant. This requires adding a FFI binding to the `blst` library to enable secure and efficient key derivation within `cardano-base`.
+- **Signature:** Implement signature generation and verification APIs that are variant-agnostic and support domain separation, with DST provided by the caller. 
+- **Aggregation**
+- **Batch verification**
+- **DSIGN integration**
+- **Serialization**
+- **Conformance vectors**
+
+**Performance and quality**
+- **Performance benchmarks**
+- **Rust parity**
+- **Determinism portability**
+- **Documentation**
+
+**Other utilities**
+- **Registration**
+- **Fa sortition**
+- **Local sortition**
+- ...
 
 #### BLS12-381 Integration (New)