include: add description of range proofs

include/secp256k1_rangeproof.h

@@ -10,6 +10,41 @@ extern "C" {
 
 #include <stdint.h>
 
+/** This module implements a variant of Back-Maxwell range proofs as described
+ * in the Confidential Assets paper (https://blockstream.com/bitcoin17-final41.pdf).
+ * The construction is based on Borromean ring signatures.
+ * (https://nt4tn.net/papers/borromean_draft_0.01_34241bb.pdf)
+ *
+ * This implementation differs from the variant in the paper mainly in that it
+ * omits an optimization that saves one scalar per ring. This optimization complicates
+ * the protocol and security analysis, as it requires differentiating cases where
+ * the i-th bit v_i = 0 versus otherwise, and makes calculating response points R_i less
+ * straightforward. The implemented version uses Borromean ring signatures in
+ * an unmodified way.
+ *
+ * Another difference is that the implementation omits the last ring's commitment
+ * from the proof and recovered by the verifier by subtracting all other digit
+ * commitments from the total, reducing proof size by one group element.
+ *
+ * Furthermore, in the implementation every hash calculation includes a message
+ * m=SHA256(C||H||header||C_0||...||C_(n-2)||extra_commit), binding the commitment C,
+ * generator H, proof header, the n-1 explicit digit commitments, and any extra data.
+ * This prevents an attack that would compromise non-malleability. In the paper's
+ * version of the protocol, a prover could pick distinct indices i, j and a scalar y,
+ * and modify digit commitments in the original proof by setting C'_i = C_i + yG and
+ * C'_j = C_j - yG, obtaining a different valid proof for the same commitment and
+ * witness.
+ *
+ * In the current implementation, up to 3968 bytes of message data can be
+ * embedded and recovered within maximally-sized proofs. The implemented embedding
+ * method using the forged parts of ring signatures could also be applied to the
+ * construction in the paper, but is not mentioned there. Message embedding is used
+ * in Confidential Assets to transmit values and blinding factors of the corresponding
+ * commitments. This is possible because randomness is generated by seeding HMAC-DRBG
+ * with the shared ECDH key, allowing the receiver to rewind the proof using the same
+ * random values the sender used.
+ */
+
 /** Length of a message that can be embedded into a maximally-sized rangeproof
  *
  * It is not be possible to fit a message of this size into a non-maximally-sized