A Finite Field which implements Rijndael's Finite Field operations. Operates on values less than 256 and is used to generate sbox values on the fly Its most important for providing non-linearity within the AES encryption scheme

Hierarchy

  • UnreducedForeignField<this>
    • RijndaelFiniteField

Constructors

  • Create a new ForeignField from a bigint, number, string or another ForeignField.

    Parameters

    • x: string | number | bigint | ForeignField | Field3

    Returns RijndaelFiniteField

    let x = new ForeignField(5);
    

    Note: Inputs must be range checked if they originate from a different field with a different modulus or if they are not constants.

    • When constructing from another ForeignField instance, ensure the modulus matches. If not, check the modulus using Gadgets.ForeignField.assertLessThan() and handle appropriately.
    • When constructing from a Field3 array, ensure all elements are valid Field elements and range checked.
    • Ensure constants are correctly reduced to the modulus of the field.

Properties

type: "Unreduced" | "AlmostReduced" | "FullyReduced"
value: Field3

The internal representation of a foreign field element, as a tuple of 3 limbs.

_Bigint:
    | undefined
    | {
        inverse: (x: bigint) => undefined | bigint;
        M: bigint;
        modulus: bigint;
        sizeInBits: number;
        t: bigint;
        twoadicRoot: bigint;
        add(x: bigint, y: bigint): bigint;
        div(x: bigint, y: bigint): undefined | bigint;
        dot(x: bigint[], y: bigint[]): bigint;
        equal(x: bigint, y: bigint): boolean;
        fromBigint(x: bigint): bigint;
        fromNumber(x: number): bigint;
        isEven(x: bigint): boolean;
        isSquare(x: bigint): boolean;
        leftShift(x: bigint, bits: number, maxBitSize?: number): bigint;
        mod(x: bigint): bigint;
        mul(x: bigint, y: bigint): bigint;
        negate(x: bigint): bigint;
        not(x: bigint, bits: number): bigint;
        power(x: bigint, n: bigint): bigint;
        random(): bigint;
        rightShift(x: bigint, bits: number): bigint;
        rot(
            x: bigint,
            bits: bigint,
            direction?: "left" | "right",
            maxBits?: bigint,
        ): bigint;
        sqrt(x: bigint): undefined | bigint;
        square(x: bigint): bigint;
        sub(x: bigint, y: bigint): bigint;
    }
_modulus: undefined | bigint
_provable:
    | undefined
    | ProvablePureExtended<UnreducedForeignField, bigint, string>
_variants:
    | undefined
    | {
        almostReduced: typeof AlmostForeignField;
        canonical: typeof CanonicalForeignField;
        unreduced: typeof UnreducedForeignField;
    }

Sibling classes that represent different ranges of field elements.

Accessors

  • get Constructor(): typeof ForeignField

    Returns typeof ForeignField

  • get modulus(): bigint

    Returns bigint

  • get AlmostReduced(): typeof AlmostForeignField

    Constructor for field elements that are "almost reduced", i.e. lie in the range [0, 2^ceil(log2(p))).

    Returns typeof AlmostForeignField

  • get Bigint(): {
        inverse: (x: bigint) => undefined | bigint;
        M: bigint;
        modulus: bigint;
        sizeInBits: number;
        t: bigint;
        twoadicRoot: bigint;
        add(x: bigint, y: bigint): bigint;
        div(x: bigint, y: bigint): undefined | bigint;
        dot(x: bigint[], y: bigint[]): bigint;
        equal(x: bigint, y: bigint): boolean;
        fromBigint(x: bigint): bigint;
        fromNumber(x: number): bigint;
        isEven(x: bigint): boolean;
        isSquare(x: bigint): boolean;
        leftShift(x: bigint, bits: number, maxBitSize?: number): bigint;
        mod(x: bigint): bigint;
        mul(x: bigint, y: bigint): bigint;
        negate(x: bigint): bigint;
        not(x: bigint, bits: number): bigint;
        power(x: bigint, n: bigint): bigint;
        random(): bigint;
        rightShift(x: bigint, bits: number): bigint;
        rot(
            x: bigint,
            bits: bigint,
            direction?: "left" | "right",
            maxBits?: bigint,
        ): bigint;
        sqrt(x: bigint): undefined | bigint;
        square(x: bigint): bigint;
        sub(x: bigint, y: bigint): bigint;
    }

    Returns {
        inverse: (x: bigint) => undefined | bigint;
        M: bigint;
        modulus: bigint;
        sizeInBits: number;
        t: bigint;
        twoadicRoot: bigint;
        add(x: bigint, y: bigint): bigint;
        div(x: bigint, y: bigint): undefined | bigint;
        dot(x: bigint[], y: bigint[]): bigint;
        equal(x: bigint, y: bigint): boolean;
        fromBigint(x: bigint): bigint;
        fromNumber(x: number): bigint;
        isEven(x: bigint): boolean;
        isSquare(x: bigint): boolean;
        leftShift(x: bigint, bits: number, maxBitSize?: number): bigint;
        mod(x: bigint): bigint;
        mul(x: bigint, y: bigint): bigint;
        negate(x: bigint): bigint;
        not(x: bigint, bits: number): bigint;
        power(x: bigint, n: bigint): bigint;
        random(): bigint;
        rightShift(x: bigint, bits: number): bigint;
        rot(
            x: bigint,
            bits: bigint,
            direction?: "left" | "right",
            maxBits?: bigint,
        ): bigint;
        sqrt(x: bigint): undefined | bigint;
        square(x: bigint): bigint;
        sub(x: bigint, y: bigint): bigint;
    }

  • get Canonical(): typeof CanonicalForeignField

    Constructor for field elements that are fully reduced, i.e. lie in the range [0, p).

    Returns typeof CanonicalForeignField

  • get modulus(): bigint

    Returns bigint

  • get provable(): ProvablePureExtended<UnreducedForeignField, bigint, string>

    Provable<ForeignField>, see Provable

    Returns ProvablePureExtended<UnreducedForeignField, bigint, string>

  • get sizeInBits(): number

    Returns number

  • get Unreduced(): typeof UnreducedForeignField

    Constructor for unreduced field elements.

    Returns typeof UnreducedForeignField

Methods

  • Assert that this field element lies in the range [0, 2^k), where k = ceil(log2(p)) and p is the foreign field modulus.

    Returns the field element as a AlmostForeignField.

    For a more efficient version of this for multiple field elements, see assertAlmostReduced.

    Note: this does not ensure that the field elements is in the canonical range [0, p). To assert that stronger property, there is assertCanonical. You should typically use assertAlmostReduced though, because it is cheaper to prove and sufficient for ensuring validity of all our non-native field arithmetic methods.

    Returns AlmostForeignField

  • Assert that this field element is fully reduced, i.e. lies in the range [0, p), where p is the foreign field modulus.

    Returns the field element as a CanonicalForeignField.

    Returns CanonicalForeignField

  • Assert equality with a ForeignField-like value

    Parameters

    • y: number | bigint | CanonicalForeignField
    • Optionalmessage: string

    Returns CanonicalForeignField

    x.assertEquals(0, "x is zero");
    

    Since asserting equality can also serve as a range check, this method returns x with the appropriate type:

    let xChecked = x.assertEquals(1, "x is 1");
    xChecked satisfies CanonicalForeignField;
  • Assert equality with a ForeignField-like value

    Parameters

    • y: AlmostForeignField
    • Optionalmessage: string

    Returns AlmostForeignField

    x.assertEquals(0, "x is zero");
    

    Since asserting equality can also serve as a range check, this method returns x with the appropriate type:

    let xChecked = x.assertEquals(1, "x is 1");
    xChecked satisfies CanonicalForeignField;
  • Assert equality with a ForeignField-like value

    Parameters

    • y: ForeignField
    • Optionalmessage: string

    Returns ForeignField

    x.assertEquals(0, "x is zero");
    

    Since asserting equality can also serve as a range check, this method returns x with the appropriate type:

    let xChecked = x.assertEquals(1, "x is 1");
    xChecked satisfies CanonicalForeignField;
  • Assert that this field element is less than a constant c: x < c.

    The constant must satisfy 0 <= c < 2^264, otherwise an error is thrown.

    Parameters

    • c: number | bigint
    • Optionalmessage: string

    Returns void

    x.assertLessThan(10);
    
  • Checks whether this field element is a constant.

    See FieldVar to understand constants vs variables.

    Returns boolean

  • Finite field negation

    Returns AlmostForeignField

    x.neg(); // -x mod p = p - x
    
  • Finite field subtraction

    Parameters

    • y: number | bigint | ForeignField

    Returns UnreducedForeignField

    x.sub(1); // x - 1 mod p
    
  • Convert this field element to a bigint.

    Returns bigint

  • Unpack a field element to its bits, as a Bool[] array.

    This method is provable!

    Parameters

    • Optionallength: number

    Returns Bool[]

  • Convert this field element to a constant.

    See FieldVar to understand constants vs variables.

    Warning: This function is only useful in Provable.witness or Provable.asProver blocks, that is, in situations where the prover computes a value outside provable code.

    Returns ForeignField

  • Instance version of Provable<ForeignField>.toFields, see Provable.toFields

    Returns Field[]

  • Assert that one or more field elements lie in the range [0, 2^k), where k = ceil(log2(p)) and p is the foreign field modulus.

    This is most efficient than when checking a multiple of 3 field elements at once.

    Type Parameters

    • T extends Tuple<ForeignField>

    Parameters

    • ...xs: T

    Returns [...{ [i in string | number | symbol]: AlmostForeignField }[]]

  • Parameters

    • x: ForeignField

    Returns void

  • Coerce the input to a ForeignField.

    Parameters

    • x: string | number | bigint

    Returns CanonicalForeignField

  • Coerce the input to a ForeignField.

    Parameters

    • x: string | number | bigint | ForeignField

    Returns ForeignField

  • Create a field element from its bits, as a Bool[] array.

    This method is provable!

    Parameters

    • bits: Bool[]

    Returns AlmostForeignField

  • Returns CanonicalForeignField

  • Sum (or difference) of multiple finite field elements.

    Parameters

    • xs: (number | bigint | ForeignField)[]
    • operations: (-1 | 1)[]

    Returns UnreducedForeignField

    let z = ForeignField.sum([3, 2, 1], [-1, 1]); // 3 - 2 + 1
    z.assertEquals(2);

    This method expects a list of ForeignField-like values, x0,...,xn, and a list of "operations" op1,...,opn where every op is 1 or -1 (plus or minus), and returns

    x0 + op1*x1 + ... + opn*xn

    where the sum is computed in finite field arithmetic.

    Important: For more than two summands, this is significantly more efficient than chaining calls to ForeignField.add and ForeignField.sub.