add CHANGELOG + doc + basic DST to G2 module.

Author: KtorZ

CHANGELOG.md

@@ -8,6 +8,9 @@
   - [`aiken/crypto/int224`](https://aiken-lang.github.io/stdlib/aiken/crypto/int224.html)
   - [`aiken/crypto/int256`](https://aiken-lang.github.io/stdlib/aiken/crypto/int256.html)
 
+- New module wrapping BLS12-381 pairing features:
+  - [`aiken/crypto/bls12_381/pairing`](https://aiken-lang.github.io/stdlib/aiken/crypto/bls12_381/pairing.html)
+
 - [`aiken/collection/dict.{get_or_else}`](https://aiken-lang.github.io/stdlib/aiken/collection/list.html#get_or_else): to lookup a value from a dict, with a fallback.
 
 - [`aiken/collection/list.{foldl2}`](https://aiken-lang.github.io/stdlib/aiken/collection/list.html#foldl2): to left-fold over lists while accumulating two separate results. This is reasonably faster than constructing a list of pairs.

lib/aiken/crypto/bls12_381/g2.ak

@@ -21,6 +21,10 @@ use aiken/crypto/bls12_381/scalar.{Scalar}
 pub const generator: G2Element =
   #<Bls12_381, G2>"93e02b6052719f607dacd3a088274f65596bd0d09920b61ab5da61bbdc7f5049334cf11213945d57e5ac7d055d042b7e024aa2b2f08f0a91260805272dc51051c6e47ad4fa403b02b4510b647ae3d1770bac0326a805bbefd48056c8c121bdb8"
 
+/// Basic Domain Separation Tag as per the [IETF](https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-05.html#section-4.2.1).
+pub const domain_separation_tag_basic =
+  "BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_"
+
 test generator_1() {
   builtin.bls12_381_g2_scalar_mul(scalar.field_prime, generator) == #<Bls12_381, G2>"c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
 }

lib/aiken/crypto/bls12_381/pairing.ak

@@ -4,27 +4,59 @@ use aiken/crypto/bls12_381/g1
 use aiken/crypto/bls12_381/g2
 use aiken/crypto/bls12_381/scalar.{Scalar}
 
+/// Computes a MillerLoop over the elements `q` and `p`
 pub fn miller_loop(q: G1Element, p: G2Element) -> MillerLoopResult {
   bls12_381_miller_loop(q, p)
 }
 
+/// Final exponentiation against two `MillerLoopResult`.
+///
+/// ```aiken
+/// prove: e(q^x, p^m) == e(q, p^m*x)
+/// let secret: State<Scalar> = scalar.from_int(44203)
+///
+/// let public_value: G1Element = g1.generator |> g1.scale(secret)
+///
+/// let message: ByteArray = #"acab"
+///
+/// let challenge: G2Element =
+///   message |> g2.hash_to_group(g2.domain_separation_tag_basic)
+///
+/// let witness: G2Element =
+///   message
+///     |> g2.hash_to_group(g2.domain_separation_tag_basic)
+///     |> g2.scale(secret)
+///
+/// final_exponentiation(
+///   miller_loop(public_value, challenge),
+///   miller_loop(g1.generator, witness),
+/// )
+/// ```
 pub fn final_exponentiation(
   left: MillerLoopResult,
   right: MillerLoopResult,
 ) -> Bool {
   bls12_381_final_verify(left, right)
 }
 
+// prove: e(q^x, p^m) == e(q, p^m*x)
 test simple_miller_loop_with_final_exponentiation() {
-  // prove: e(q^x, p^m) == e(q, p^m*x)
   let secret: State<Scalar> = scalar.from_int(44203)
+
   let public_value: G1Element = g1.generator |> g1.scale(secret)
+
   let message: ByteArray = #"acab"
-  let domain_tag: ByteArray = "BLS-TEST"
-  let challenge: G2Element = g2.hash_to_group(message, domain_tag)
+
+  let challenge: G2Element =
+    message |> g2.hash_to_group(g2.domain_separation_tag_basic)
+
   let witness: G2Element =
-    g2.hash_to_group(message, domain_tag) |> g2.scale(secret)
-  let left: MillerLoopResult = miller_loop(public_value, challenge)
-  let right: MillerLoopResult = miller_loop(g1.generator, witness)
-  final_exponentiation(left, right)
+    message
+      |> g2.hash_to_group(g2.domain_separation_tag_basic)
+      |> g2.scale(secret)
+
+  final_exponentiation(
+    miller_loop(public_value, challenge),
+    miller_loop(g1.generator, witness),
+  )
 }