Foreign curve and ECDSA

src/lib/foreign-curve.ts

@@ -62,12 +62,13 @@ type ForeignCurveClass = ReturnType<typeof createForeignCurve>;
  * @param options
  * - `unsafe: boolean` determines whether `ForeignField` elements are constrained to be valid on creation.
  */
-function createForeignCurve(curve: CurveParams) {
+function createForeignCurve(curve: CurveParams, { unsafe = false } = {}) {
   const curveParamsMl = Snarky.foreignCurve.create(MlCurveParams(curve));
   const curveName = curve.name;
+  const hasCofactor = curve.cofactor !== undefined && curve.cofactor !== 1n;
 
-  class BaseField extends createForeignField(curve.modulus) {}
-  class ScalarField extends createForeignField(curve.order) {}
+  class BaseField extends createForeignField(curve.modulus, { unsafe }) {}
+  class ScalarField extends createForeignField(curve.order, { unsafe }) {}
 
   // this is necessary to simplify the type of ForeignCurve, to avoid
   // TS7056: The inferred type of this node exceeds the maximum length the compiler will serialize.
@@ -81,8 +82,11 @@ function createForeignCurve(curve: CurveParams) {
     generator: curve.gen,
   });
 
-  function toConstant(x: ForeignCurve) {
-    return { ...x.toBigint(), infinity: false };
+  function toBigint(g: Affine) {
+    return { x: g.x.toBigInt(), y: g.y.toBigInt() };
+  }
+  function toConstant(g: Affine) {
+    return { ...toBigint(g), infinity: false };
   }
 
   class ForeignCurve extends Affine {
@@ -117,6 +121,9 @@ function createForeignCurve(curve: CurveParams) {
       if (this.isConstant()) this.assertOnCurve();
     }
 
+    /**
+     * Coerce the input to a {@link ForeignCurve}.
+     */
     static from(
       g:
         | ForeignCurve
@@ -128,6 +135,9 @@ function createForeignCurve(curve: CurveParams) {
 
     static #curveParamsMlVar: unknown | undefined;
 
+    /**
+     * Initialize usage of the curve. This function has to be called oncel per provable method to use the curve.
+     */
     static initialize() {
       if (!inCheckedComputation()) return;
       ForeignCurve.#curveParamsMlVar =
@@ -145,14 +155,25 @@ function createForeignCurve(curve: CurveParams) {
 
     static generator = new ForeignCurve(curve.gen);
 
+    /**
+     * Checks whether this curve point is constant.
+     *
+     * See {@link FieldVar} to understand constants vs variables.
+     */
     isConstant() {
       return isConstant(ForeignCurve, this);
     }
 
+    /**
+     * Convert this curve point to a point with bigint coordinates.
+     */
     toBigint() {
       return { x: this.x.toBigInt(), y: this.y.toBigInt() };
     }
 
+    /**
+     * Elliptic curve addition.
+     */
     add(
       h:
         | ForeignCurve
@@ -168,6 +189,9 @@ function createForeignCurve(curve: CurveParams) {
       return new ForeignCurve(p);
     }
 
+    /**
+     * Elliptic curve doubling.
+     */
     double() {
       if (this.isConstant()) {
         let z = ConstantCurve.double(toConstant(this));
@@ -178,6 +202,9 @@ function createForeignCurve(curve: CurveParams) {
       return new ForeignCurve(p);
     }
 
+    /**
+     * Elliptic curve negation.
+     */
     negate() {
       if (this.isConstant()) {
         let z = ConstantCurve.negate(toConstant(this));
@@ -188,24 +215,34 @@ function createForeignCurve(curve: CurveParams) {
       return new ForeignCurve(p);
     }
 
-    assertOnCurve() {
-      if (this.isConstant()) {
-        let isOnCurve = ConstantCurve.isOnCurve(toConstant(this));
+    static #assertOnCurve(g: Affine) {
+      if (isConstant(ForeignCurve, g)) {
+        let isOnCurve = ConstantCurve.isOnCurve(toConstant(g));
         if (!isOnCurve)
           throw Error(
-            `${this.constructor.name}.assertOnCurve(): ${JSON.stringify(
-              ForeignCurve.toJSON(this)
+            `${this.name}.assertOnCurve(): ${JSON.stringify(
+              ForeignCurve.toJSON(g)
             )} is not on the curve.`
           );
         return;
       }
-      let curve = ForeignCurve._getParams(
-        `${this.constructor.name}.assertOnCurve`
-      );
-      Snarky.foreignCurve.assertOnCurve(toMl(this), curve);
+      let curve = ForeignCurve._getParams(`${this.name}.assertOnCurve`);
+      Snarky.foreignCurve.assertOnCurve(toMl(g), curve);
+    }
+
+    /**
+     * Assert that this point lies on the elliptic curve, which means it satisfies the equation
+     * y^2 = x^3 + ax + b
+     */
+    assertOnCurve() {
+      ForeignCurve.#assertOnCurve(this);
     }
 
     // TODO wrap this in a `Scalar` type which is a Bool array under the hood?
+    /**
+     * Elliptic curve scalar multiplication, where the scalar is represented as a little-endian
+     * array of bits, and each bit is represented by a {@link Bool}.
+     */
     scale(scalar: Bool[]) {
       if (this.isConstant() && scalar.every((b) => b.isConstant())) {
         let scalar0 = scalar.map((b) => b.toBoolean());
@@ -221,19 +258,41 @@ function createForeignCurve(curve: CurveParams) {
       return new ForeignCurve(p);
     }
 
-    assertInSubgroup() {
-      if (this.isConstant()) {
-        let isInGroup = ConstantCurve.isInSubgroup(toConstant(this));
+    static #assertInSubgroup(g: Affine) {
+      if (isConstant(Affine, g)) {
+        let isInGroup = ConstantCurve.isInSubgroup(toConstant(g));
         if (!isInGroup)
           throw Error(
-            `${this.constructor.name}.assertInSubgroup(): ${JSON.stringify(
-              this
+            `${this.name}.assertInSubgroup(): ${JSON.stringify(
+              g
             )} is not in the target subgroup.`
           );
         return;
       }
-      let curve = ForeignCurve._getParams(`${curveName}.assertInSubgroup`);
-      Snarky.foreignCurve.checkSubgroup(toMl(this), curve);
+      let curve_ = ForeignCurve._getParams(`${curveName}.assertInSubgroup`);
+      Snarky.foreignCurve.checkSubgroup(toMl(g), curve_);
+    }
+
+    /**
+     * Assert than this point lies in the subgroup defined by order*P = 0,
+     * by performing the scalar multiplication.
+     */
+    assertInSubgroup() {
+      ForeignCurve.#assertInSubgroup(this);
+    }
+
+    /**
+     * Check that this is a valid element of the target subgroup of the curve:
+     * - Use {@link assertOnCurve()} to check that the point lies on the curve
+     * - If the curve has cofactor unequal to 1, use {@link assertInSubgroup()}.
+     *
+     * **Exception**: If {@link createForeignCurve} is called with `{ unsafe: true }`,
+     * we don't check that curve elements are valid by default.
+     */
+    static check(g: Affine) {
+      if (unsafe) return;
+      ForeignCurve.#assertOnCurve(g);
+      if (hasCofactor) ForeignCurve.#assertInSubgroup(g);
     }
 
     static BaseField = BaseField;
@@ -260,6 +319,12 @@ type CurveParams = {
    * Scalar field modulus = group order
    */
   order: bigint;
+  /**
+   * Cofactor = size of EC / order
+   *
+   * This can be left undefined if the cofactor is 1.
+   */
+  cofactor?: bigint;
   /**
    * The `a` parameter in the curve equation y^2 = x^3 + ax + b
    */