docs(utils): update comments about input values within the field

re #241

packages/utils/src/f1-field.ts

@@ -7,8 +7,8 @@ import * as scalar from "./scalar"
  * and inversion, all performed modulo the field's order. It's designed to work with bigints,
  * supporting large numbers for cryptographic purposes and other applications requiring
  * modular arithmetic.
- * Note that even if the outputs of the functions are always within the field,
- * the inputs must be checked externally. Functions always expect input values within the field.
+ * Note that the outputs of the functions will always be within the field if and only if
+ * the input values are within the field. Devs need to make sure of that.
  *
  * @property one Represents the scalar value 1 in the field.
  * @property zero Represents the scalar value 0 in the field.
@@ -53,7 +53,8 @@ export default class F1Field {
     }
 
     /**
-     * Subtracts one bigint from another under modulus, ensuring the result is within the field.
+     * Subtracts one bigint from another under modulus.
+     * It ensures the result is within the field if and only if the input values are within the field.
      * @param a The value from which to subtract.
      * @param b The value to be subtracted.
      * @returns The difference of 'a' and 'b' modulo the field's order.
@@ -63,7 +64,8 @@ export default class F1Field {
     }
 
     /**
-     * Adds two bigint values together under modulus, ensuring the result is within the field.
+     * Adds two bigint values together under modulus.
+     * It ensures the result is within the field if and only if the input values are within the field.
      * @param a The first value.
      * @param b The second value.
      * @returns The sum of 'a' and 'b' modulo the field's order.
@@ -115,6 +117,7 @@ export default class F1Field {
 
     /**
      * Checks if two bigint values are equal within the context of the field.
+     * It ensures the result is within the field if and only if the input values are within the field.
      * @param a The first value to compare.
      * @param b The second value to compare.
      * @returns True if 'a' equals 'b', false otherwise.
@@ -127,6 +130,7 @@ export default class F1Field {
      * Squares a bigint value within the field.
      * This is a specific case of multiplication where the value is multiplied by itself,
      * optimized for performance where applicable.
+     * It ensures the result is within the field if and only if the input values are within the field.
      * @param a The value to square.
      * @returns The square of 'a' modulo the field's order.
      */
@@ -137,6 +141,7 @@ export default class F1Field {
     /**
      * Compares two bigint values to determine if the first is less than the second,
      * taking into account the field's order for modular comparison.
+     * It ensures the result is within the field if and only if the input values are within the field.
      * @param a The first value to compare.
      * @param b The second value to compare.
      * @returns True if 'a' is less than 'b', false otherwise.
@@ -151,6 +156,7 @@ export default class F1Field {
     /**
      * Compares two bigint values to determine if the first is greater than or equal to the second,
      * considering the field's modular context.
+     * It ensures the result is within the field if and only if the input values are within the field.
      * @param a The first value to compare.
      * @param b The second value to compare.
      * @returns True if 'a' is greater than or equal to 'b', false otherwise.
@@ -166,6 +172,7 @@ export default class F1Field {
      * Computes the negation of a bigint value within the field.
      * The result is the modular additive inverse that, when added to the original value,
      * yields zero in the field's modulus.
+     * It ensures the result is within the field if and only if the input values are within the field.
      * @param a The value to negate.
      * @returns The negation of 'a' modulo the field's order.
      */