From ce7a8fda552d052a7cc01796c4909af56a945734 Mon Sep 17 00:00:00 2001
From: Paul Miller <paul@paulmillr.com>
Date: Thu, 14 Sep 2023 01:02:10 +0000
Subject: [PATCH] bls, bn: clarify their security level in comments

---
 src/bls12-381.ts | 27 +++++++++++++++------------
 src/bn254.ts     |  5 +++--
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/src/bls12-381.ts b/src/bls12-381.ts
index 7360673..85d12f7 100644
--- a/src/bls12-381.ts
+++ b/src/bls12-381.ts
@@ -1,15 +1,9 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 
-// bls12-381 pairing-friendly Barreto-Lynn-Scott elliptic curve construction allows to:
-// - Construct zk-SNARKs at the 128-bit security
-// - Use threshold signatures, which allows a user to sign lots of messages with one signature and
-//   verify them swiftly in a batch, using Boneh-Lynn-Shacham signature scheme.
-//
-// The library uses G1 for public keys and G2 for signatures. Support for G1 signatures is planned.
-// Compatible with Algorand, Chia, Dfinity, Ethereum, FIL, Zcash. Matches specs
-// [pairing-curves-11](https://tools.ietf.org/html/draft-irtf-cfrg-pairing-friendly-curves-11),
-// [bls-sigs-04](https:/cfrg-hash-to/tools.ietf.org/html/draft-irtf-cfrg-bls-signature-04),
-// [hash-to-curve-12](https://tools.ietf.org/html/draft-irtf--curve-12).
+// bls12-381 is pairing-friendly Barreto-Lynn-Scott elliptic curve construction allowing to:
+// - Construct zk-SNARKs at the 120-bit security
+// - Efficiently verify N aggregate signatures with 1 pairing and N ec additions:
+//   the Boneh-Lynn-Shacham signature scheme is orders of magnitude more efficient than Schnorr
 //
 // ### Summary
 // 1. BLS Relies on Bilinear Pairing (expensive)
@@ -25,8 +19,17 @@
 // - `S = pk x H(m)` - signing
 // - `e(P, H(m)) == e(G, S)` - verification using pairings
 // - `e(G, S) = e(G, SUM(n)(Si)) = MUL(n)(e(G, Si))` - signature aggregation
-// Filecoin uses little endian byte arrays for private keys -
-// so ensure to reverse byte order if you'll use it with FIL.
+//
+// ### Compatibility and notes
+// 1. It is compatible with Algorand, Chia, Dfinity, Ethereum, Filecoin, ZEC
+//    Filecoin uses little endian byte arrays for private keys - make sure to reverse byte order.
+// 2. Some projects use G2 for public keys and G1 for signatures. It's called "short signature"
+// 3. Curve security level is about 120 bits as per Barbulescu-Duquesne 2017
+//    https://hal.science/hal-01534101/file/main.pdf
+// 4. Compatible with specs:
+// [cfrg-pairing-friendly-curves-11](https://tools.ietf.org/html/draft-irtf-cfrg-pairing-friendly-curves-11),
+// [cfrg-bls-signature-05](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05),
+// [RFC 9380](https://www.rfc-editor.org/rfc/rfc9380).
 import { sha256 } from '@noble/hashes/sha256';
 import { randomBytes } from '@noble/hashes/utils';
 import { bls, CurveFn } from './abstract/bls.js';
diff --git a/src/bn254.ts b/src/bn254.ts
index 64ccfe0..0fe8585 100644
--- a/src/bn254.ts
+++ b/src/bn254.ts
@@ -6,8 +6,9 @@ import { Field } from './abstract/modular.js';
 /**
  * bn254 pairing-friendly curve.
  * Previously known as alt_bn_128, when it had 128-bit security.
- * Recent research shown it's weaker, the naming has been adjusted to its prime bit count.
- * https://github.com/zcash/zcash/issues/2502
+ * Barbulescu-Duquesne 2017 shown it's weaker: just about 100 bits,
+ * so the naming has been adjusted to its prime bit count
+ * https://hal.science/hal-01534101/file/main.pdf
  */
 export const bn254 = weierstrass({
   a: BigInt(0),