package bls12-381

  1. Overview
  2. Docs

Module Bls12_381.FrSource

include Ff_sig.PRIME
include Ff_sig.BASE
Sourceexception Not_in_field of Bytes.t
Sourcetype t
Sourceval order : Z.t

The order of the finite field

Sourceval size_in_bytes : int

Minimal number of bytes required to encode a value of the field

Sourceval zero : t

The neutral element for the addition

Sourceval one : t

The neutral element for the multiplication

Sourceval is_zero : t -> bool

is_zero x returns true if x is the neutral element for the addition

Sourceval is_one : t -> bool

is_one x returns true if x is the neutral element for the multiplication

Sourceval random : ?state:Random.State.t -> unit -> t

Use carefully!

random () returns a random element of the field. A state for the PRNG can be given to initialize the PRNG in the requested state. If no state is given, no initialisation is performed.

To create a value of type Random.State.t, you can use Random.State.make [|42|].

Sourceval non_null_random : ?state:Random.State.t -> unit -> t

Use carefully!

non_null_random () returns a non null random element of the field. A state for the PRNG can be given to initialize the PRNG in the requested state. If no state is given, no initialisation is performed.

To create a value of type Random.State.t, you can use Random.State.make [|42|].

Sourceval add : t -> t -> t

add a b returns a + b mod order

Sourceval (+) : t -> t -> t

Infix operator for add

Sourceval sub : t -> t -> t

sub a b returns a - b mod order

Sourceval mul : t -> t -> t

mul a b returns a * b mod order

Sourceval (*) : t -> t -> t

Infix operator for mul

Sourceval eq : t -> t -> bool

eq a b returns true if a = b mod order, else false

Sourceval (=) : t -> t -> bool

Infix operator for eq

Sourceval negate : t -> t

negate x returns -x mod order. Equivalently, negate x returns the unique y such that x + y mod order = 0

Sourceval (-) : t -> t

Infix operator for negate

Sourceval inverse_exn : t -> t

inverse_exn x returns x^-1 mod order if x is not 0, else raise Division_by_zero. Equivalently, inverse_exn x returns the unique y such that x * y mod order = 1

Sourceval inverse_opt : t -> t option

inverse_opt x returns x^-1 mod order as an option if x is not 0, else returns None. Equivalently, inverse_opt x returns the unique y such that x * y mod order = 1

Sourceval div_exn : t -> t -> t

div_exn a b returns a * b^-1. Raise Division_by_zero if b = zero. Equivalently, div_exn returns the unique y such that b * y mod order = a

Sourceval div_opt : t -> t -> t option

div_opt a b returns a * b^-1 as an option. Return None if b = zero. Equivalently, div_opt returns the unique y such that b * y mod order = a

Sourceval (/) : t -> t -> t

Infix operator for div_exn

Sourceval square : t -> t

square x returns x^2 mod order

Sourceval double : t -> t

double x returns 2x mod order

Sourceval pow : t -> Z.t -> t

pow x n returns x^n mod order

Sourceval (**) : t -> Z.t -> t

Infix operator for pow

Sourceval of_bytes_exn : Bytes.t -> t

Construct a value of type t from the bytes representation in little endian of the field element. For non prime fields, the encoding starts with the coefficient of the constant monomial. Raise Not_in_field if the bytes do not represent an element in the field.

Sourceval of_bytes_opt : Bytes.t -> t option

From a predefined little endian bytes representation, construct a value of type t. The same representation than of_bytes_exn is used. Return None if the bytes do not represent an element in the field.

Sourceval to_bytes : t -> Bytes.t

Convert the value t to a bytes representation. The number of bytes is size_in_bytes and the encoding must be in little endian. For instance, the encoding of 1 in prime fields is always a bytes sequence of size size_in_bytes starting with the byte 0b00000001.

For non prime fields, the encoding starts with the coefficient of the constant monomial. For instance, an element a + b * X in GF(p^2) will be encoded as to_bytes a || to_bytes b where || is the concatenation of bytes

Sourceval factor_power_of_two : int * Z.t

Returns s, q such that p - 1 = 2^s * q

Sourceval of_string : string -> t

Create a value of type t from a predefined string representation. It is not required that to_string (of_string t) = t. By default, decimal representation of the number is used, modulo the order of the field

Sourceval to_string : t -> string

String representation of a value of type t. It is not required that to_string (of_string t) = t. By default, decimal representation of the number is used.

Sourceval of_z : Z.t -> t

of_z x builds an element of type t from the Zarith element x. mod p is applied if x >= p

Sourceval to_z : t -> Z.t

to_z x builds a Zarith element, using the decimal representation. Arithmetic on the result can be done using the modular functions on integers

Sourceval legendre_symbol : t -> Z.t

Returns the Legendre symbol of the parameter. Note it does not work for p = 2

Sourceval is_quadratic_residue : t -> bool

is_quadratic_residue x returns true if x is a quadratic residue i.e. if there exists n such that n^2 mod p = x

Sourceval sqrt_opt : t -> t option

sqrt_opt x returns a square root of x as an option if it does exist. If it does not exist, returns None. Equivalenty it returns a value y such that y^2 mod p = x.

Sourceval size_in_memory : int

Actual number of bytes allocated for a value of type t

Sourceval check_bytes : Bytes.t -> bool

Check if a point, represented as a byte array, is in the field *

Sourceval add_inplace : t -> t -> t -> unit

add_inplace res a b is the same than add but writes the result in res. No allocation happens.

Sourceval sub_inplace : t -> t -> t -> unit

sub_inplace res a b is the same than sub but writes the result in res. No allocation happens.

Sourceval mul_inplace : t -> t -> t -> unit

mul_inplace res a b is the same than sub but writes the result in res. No allocation happens.

Sourceval inverse_exn_inplace : t -> t -> unit

inverse_exn_inplace res a is the same than inverse_exn but writes the result in res. No allocation happens.

Sourceval double_inplace : t -> t -> unit

double_inplace res a is the same than double but writes the result in res. No allocation happens.

Sourceval square_inplace : t -> t -> unit

square_inplace res a is the same than square but writes the result in res. No allocation happens.

Sourceval negate_inplace : t -> t -> unit

negate_inplace res a is the same than negate but writes the result in res. No allocation happens.

Sourceval copy : t -> t

copy x return a fresh copy of x

Sourceval memcpy : t -> t -> unit

memcpy a b overwrites the content of a with the content of b.

Sourceval add_bulk : t list -> t

add_bulk xs returns the sum of the elements of xs by performing only one allocation for the output. This method is recommended to save the allocation overhead of using n times add.

Sourceval mul_bulk : t list -> t

mul_bulk xs returns the product of the elements of xs by performing only one allocation for the output. This method is recommended to save the allocation overhead of using n times mul.

Sourceval compare : t -> t -> int

compare a b compares the elements a and b based on their bytes representation

Sourceval inner_product_exn : t array -> t array -> t

inner_product_exn a b returns the inner product of a and b, i.e. sum(a_i * b_i). Raise Invalid_argument if the arguments are not of the same length. Only two allocations are used.

Sourceval inner_product_opt : t array -> t array -> t option

Same than inner_product_exn but returns an option instead of raising an exception.

Sourceval of_int : int -> t

of_int x is equivalent to of_z (Z.of_int x). If x is is negative, returns the element order - |x|.