From a79dfc496ec7f76ac31b9b779b75a7d5f1ba192e Mon Sep 17 00:00:00 2001 From: cedoor Date: Wed, 17 Apr 2024 18:10:23 +0200 Subject: [PATCH] docs(utils): update comments about input values within the field re #241 --- packages/utils/src/f1-field.ts | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/packages/utils/src/f1-field.ts b/packages/utils/src/f1-field.ts index a2b745eeb..9321c609f 100644 --- a/packages/utils/src/f1-field.ts +++ b/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. */