#256 add validation process steps docs

Author: PropzSaladaz

docs/concepts/concepts-index.md

@@ -16,7 +16,7 @@ The reader is expected to have basic familiarity with the following concepts:
 ## Threshold Encryption
 
 - [High Level Client Integration Flow](./threshold-encryption/3-full-client-flow.md)  
-  Explains the client role in th full process. Includes detailed data structured used, but provides very little detail on the processes. Good if you just need to know the basics.
+  Explains the client role in the full process. Includes detailes about data structures used, but provides little detail on the underlying processes. Good if you just need to know the basics.
 
 - [Threshold Encryption: Full Flow](./threshold-encryption/2-te-full-flow.md)  
   End-to-end description of the API-exposed threshold encryption process involving key generation, encryption, and decryption. Includes all process details of all stages. Does not include details on the underlying mathematics. Good if you need to know how the entire process works, and how threshold encryption is used.

docs/concepts/threshold-encryption/1-threshold-encryption.md

@@ -100,9 +100,9 @@ This means that:
 r * Y = r * (s * P) = s * (r * P) = s * U
 ``` 
 
-Since we have access to `U`, we need to somehow `s`. This is what the decryption process is about - collecting enough private key shares in order to merge them into `s`. This is all done implicitely, without ever allowing any party to know `s`. That is, the decryption process results in the production of `r * Y = s * U`, without ever:
-- Knowing any private key share `s_i`
-- Knowing the sphemeral secret `r`
+Since we have access to `U`, we need to somehow compute `s`. This is what the decryption process is about - collecting enough private key shares in order to merge them into `s`. This is all done implicitly, without ever allowing any party to know `s`. That is, the decryption process results in the production of `r * Y = s * U`, without ever:
+- Knowing any private key share `s_i` (besides possibly its own)
+- Knowing the ephemeral secret `r`
 - Knowing the common private key `s`
 
 
@@ -191,9 +191,207 @@ and we get the original plaintext.
 
 ---
 
-# 3. Validation (soon)
+# 3. Validation 
+
+`libBLS` provides a validation step after each main step in the TE flow.  
+Below we describe the encryption-time validation in detail.
+
+## 3.1 Validate Encryption
+
+**Goal.** Prove that the ciphertext `{U, V, W}` was built consistently with a single randomness `r`, i.e., that the same `r` links `U` and `W`, and that `W` binds to `(U, V)`.
+
+**Setup.**  
+- Groups: `G1`, `G2` with a bilinear pairing `e : G1 × G2 → GT`.  
+- Generators: `P ∈ G2`.  
+- Types: `U ∈ G2`, `W ∈ G1`, `H(U,V) ∈ G1`.  
+- Construction: `U = r ⋅ P`, `W = r ⋅ H(U,V)`.
+
+**Verifier computation.**
+1. Recompute the hash-to-curve point:  
+   `H' = H(U, V) ∈ G1`.
+2. Check the pairing equation:
+$$
+e(W, P) \stackrel{?}{=} e(H', U)
+$$
+
+**Why it works (bilinear proof).**  
+Assuming honest formation with the *same* scalar `r`:
+- Left side: $e(W, P) = e(r ⋅ H, P) = e(H, P)^r$.
+- Right side: $e(H', U) = e(H, r ⋅ P) = e(H, P)^r$ (since $H' = H$).
+
+Thus both sides are equal **iff**:
+- `W` was formed as `r ⋅ H(U,V)` for the same `U`, and
+- `U` encodes the *same* scalar `r` as used in `W`.
+
+**What it guarantees.**
+- **Consistency of randomness:** `U` and `W` use the same `r`.  
+- **Binding to ciphertext:** Because `H` hashes `(U,V)`, any change to `U` or `V` alters `H` and breaks the check.  
+- **Public verifiability:** Anyone can verify without knowing `r` or the plaintext `m`.  
+- **No leakage:** The check reveals nothing about `r`, `s`, or `m`.
+
+**Failure modes caught.**
+- If an adversary swaps `U` or `V`, the recomputed `H'` changes and the equation fails.  
+- If `U` and `W` are created with different scalars, bilinearity no longer aligns and the equation fails.  
+- If `W` is random/forged, it will not satisfy the equality with overwhelming probability.
+
+ 
+
+## 3.2 Validate Each Decryption Share
+
+**Goal.** 
+
+Given a ciphertext `{U, V, W}` and a purported decryption share $D_i$ from node $i$, verify that $D_i$ was computed correctly from the node’s secret share $s_i$ and that it matches the same encryption randomness $r$ that binds `{U,V,W}`.
+
+
+**Setup.** 
+
+During encryption:
+$$
+U = rP \in G_2,\qquad
+W = r\,H(U,V) \in G_1,
+$$
+where $H(U,V)\in G_1$ is a hash-to-curve of `(U,V)`.  
+For node $i$:
+$$
+Y_i = s_i P \in G_2,\qquad
+D_i = s_i U = s_i (rP) = (r s_i) P \in G_2.
+$$
+Let $e: G_1 \times G_2 \to G_T$ be a bilinear pairing.
+
+
+**Validation equations.**
+
+1) **Ciphertext integrity (same $r$ across `U` and `W`).**
+   $$
+   e(W, P)\;\stackrel{?}{=}\;e(H(U,V), U).
+   $$
+   If true, then $W = r H(U,V)$ and $U = rP$ share the same randomness $r$. (Smae as we did in 3.1)
+
+2) **Per-share correctness (same $s_i$, same $r$).**
+   $$
+   e(W, Y_i)\;\stackrel{?}{=}\;e(H(U,V), D_i).
+   $$
+
+**Why it works.**
+
+- For 1), we have already seen why it works from 3.1.
+
+- For 2), for a valid share with $Y_i=s_iP$ and $D_i=s_iU=s_i(rP)$:
+  $$
+  e(W,Y_i)=e(rH, s_iP)=e(H,P)^{r s_i},\qquad
+  e(H,D_i)=e(H, s_i r P)=e(H,P)^{r s_i},
+  $$
+  so the second equality holds **iff** $D_i$ was computed from the *same* $r$ (via $U$) and the *correct* secret share $s_i$ (via $Y_i$).
+
+
+
+## 3.3 Validate Combined Decryption Shares
+
+**Goal.** 
+
+Verify that the decrypted message is mathematically consistent with the ciphertext `{U, V, W}` and the public key $Y$, ensuring that the random scalar $r'$ recovered from the decrypted data corresponds to the same randomness $r$ used during encryption.
+
+
+**Setup.** 
+
+During encryption:
+
+$$
+U = rP, \quad V = G(rY) \oplus m
+$$
+
+where  
+- $r \in \mathbb{F}_r$ is a random scalar,  
+- $Y = sP$ is the public key,  
+- $G: G_2 \rightarrow \{0,1\}^{32}$ is a key-derivation hash,  
+- $m$ is the AES-256 key (plaintext).
+
+After decryption, the payload reveals a candidate scalar $r'$, which should equal $r$ if the decryption shares were correctly combined.
+
+**Validation Equation.** 
+
+Compute:
+
+$$
+Y' = r'Y
+$$
+
+Derive:
+
+$$
+m' = V \oplus G(Y')
+$$
+
+and verify:
+
+$$
+m' = m
+$$
+
+**Why it works.** 
+
+If the combined decryption shares are correct, then $r' = r$.  
+Hence:
+
+$$
+Y' = r'Y = rY
+$$
+
+and
+
+$$
+G(Y') = G(rY)
+$$
+
+Substituting into the expression for $m'$ gives:
+
+$$
+m' = V \oplus G(rY) = (G(rY) \oplus m) \oplus G(rY) = m
+$$
+
+The equality holds **if and only if** $r'$ matches the original randomness $r$ and the ciphertext `{U, V}` was not tampered with. Any alteration in $r'$, $V$, or $Y$ breaks the equality, making the decryption invalid.
+
+## 3.4 Validate Deciphered Message
+
+**Goal.** 
+
+Verify that the AES key recovered from the decrypted payload is consistent with the ciphertext `{U, V, W}` and the public key $Y$, by confirming that the random scalar $r'$ extracted from the plaintext explains $V$.
+
+**Setup.** 
+
+During encryption:
+$$
+U = rP,\qquad V = G(rY)\oplus m,
+$$
+where $r\in\mathbb{F}_r$ is random, $Y=sP$ is the public key, $G: G_2\to\{0,1\}^{32}$ is a KDF/hash-to-key, and $m$ is the AES-256 key.
+
+After decryption of the outer AES-GCM payload, we obtain a candidate scalar $r'$ (encoded in the plaintext). The ciphertext component $V$ is available from `{U,V,W}`.
+
+
+**Validation Equation.** 
+
+Compute:
+$$
+Y' = r'Y,\qquad K' = G(Y'),\qquad m' = V \oplus K'.
+$$
+Accept iff:
+$$
+m' = m.
+$$
+
+
+**Why it works.** 
+
+If the decrypted payload is correct and the combine of shares was honest, then $r'=r$. Hence:
+$$
+Y' = r'Y = rY,\qquad K' = G(Y') = G(rY).
+$$
+Substitute into $m'$:
+$$
+m' = V \oplus G(rY) = (G(rY)\oplus m)\oplus G(rY) = m.
+$$
+Therefore the equality holds **iff** $r'$ matches the original randomness and $V$ was not altered.
 
----
 
 ## Next Steps
 

docs/concepts/threshold-encryption/2-te-full-flow.md

@@ -130,7 +130,7 @@ Next we explain the decryption process without delving into math details. If you
 In the threshold decryption process, each node uses its private key share to compute a **partial decryption** of the ciphertext and broadcasts this decryption share to the network. Once a supermajority (i.e., at least the threshold number of valid shares) is received, any node can combine these shares to reconstruct the original plaintext, without needing the full private key.
 
 Since only the `CipheredKey` structure was ciphered using threshold encryption, only this needs to be merged using threshold encryption semantics.
-The **result of such merging will not be the original ciphertext, but the deciphered `AESKey`**
+The **result of such merging will not be the original plaintext, but the deciphered `AESKey`**
 
 The process is shown below:
 
@@ -143,7 +143,7 @@ The process is shown below:
 
 The **merge** process itself is detailed [here](./1-threshold-encryption.md).
 
-Having seen the threshold encryption decryption process to get the `AESKey`, we see next how we can use this to get the original plaintext `T` from the `Ciphertext` struct:
+Having seen the threshold encryption-decryption process to get the `AESKey`, we see next how we can use this to get the original plaintext `T` from the `Ciphertext` struct:
 
 
 <br>
@@ -161,6 +161,7 @@ Although the `r` field is not used during decryption, it is essential for valida
 
 # 3. Validation
 
+This section explains the validation checkpoints exposed by libBLS at a high level. Mathematical details are explain [here](./1-threshold-encryption.md)
 
 ## Overview
 
@@ -175,10 +176,10 @@ The validation stages are positioned at critical transition points - usually aft
 
 - **After Encryption**: Validates that the received ciphertext was properly formed before starting the decryption process.
 - **After Share Generation**: Ensures each decryption share is authentic upon receival, thus, before merging.
-- **After Share Combination**: Verifies the merged result before final decryption.
+- **After Share Merging**: Verifies the merged result before final decryption.
 - **After Final Decryption**: Confirms end-to-end integrity of the entire process.
 
-This creates a defense-in-depth strategy where each validation stage guards against different types of failures or attacks. By validating at these specific points, we prevent corrupted or malicious data from advancing to subsequent stages where it could cause otherwise have delayed the system into detecting the corrupted data only at the final stage.
+This creates a defense-in-depth strategy where each validation stage guards against different types of failures or attacks. By validating at these specific points, we prevent corrupted or malicious data from advancing to subsequent stages where it could otherwise have delayed the system into detecting the corrupted data only at the final stage.
 
 ## Validation Stages
 
@@ -229,3 +230,4 @@ The layered validation approach provides several key security benefits:
 **System Reliability**: The validations catch not just malicious behavior but also honest errors, hardware failures, and software bugs, making the entire system more robust and reliable.
 
 **Auditability**: Each validation stage provides a clear checkpoint where system integrity can be verified, making it easier to audit the system's behavior and troubleshoot any issues that arise.
+

docs/concepts/threshold-encryption/3-full-client-flow.md

@@ -6,6 +6,8 @@ This document does not cover the details of encryption / decryption. These can b
 
 ---
 
+The following diagram shows the flow process, as well as some details on the ciphertext structure. The steps are all explained below the diagram.
+
 <img src="../../diagrams/threshold-encryption/full-client-flow.svg" alt="Diagram" style="width: 100%; max-width: 1200px;" />
 
 <br>
@@ -25,8 +27,12 @@ The client begins by querying the network to obtain the current threshold encryp
 
 This dual-key mechanism allows the client to encrypt data such that it is decryptable by either the current or the upcoming committee. This is essential during periods when both committees must temporarily coexist.
 
+Note that this method is not provided by libBLS. It should be implemented by the application using libBLS. libBLS only deals with the two keys sent to the library. 
+
 ### 1.2. Encrypt Data
 
+From this step on, eveything is implemented by libBLS.
+
 The client generates:
 - A **symmetric key** `m` (AES key).
 - A **random scalar** `r` used as input to the threshold encryption scheme.
@@ -93,7 +99,7 @@ At this stage, the decryption is started. Each node first computes one decryptio
 
 <img src="../../diagrams/threshold-encryption/simplified-process-overview.svg" alt="Diagram" style="width: 100%; max-width: 1200px;" />
 
-At this stage, we have already gone through the `Ciphering` part on the left of the diagram, and we are exactly at the middle.
+At this stage, we have already gone through the `Ciphering` part ( **m** being the message, and $Y_1$ being the group's public key) on the left of the diagram, and we are exactly at the middle.
 
 
 ### 3.1. Compute Decryption Shares