# package bls12-381

Library

Module

Module type

Parameter

Class

Class type

Elliptic curve built over the field `Fq^2`

and the equation ```
y^2 = x^3 + 4(u
+ 1)
```

`include CURVE`

`exception Not_on_curve of Bytes.t`

The type of the element on the curve and in the prime subgroup. The point is given in jacobian coordinates

`affine_of_jacobian p`

creates a new value of type `affine`

representing the point `p`

in affine coordinates

`jacobian_of_affine p`

creates a new value of type `t`

representing the point `p`

in jacobian coordinates

`val to_affine_array : t array -> affine_array`

`to_affine_array pts`

builds a contiguous C array and populate it with the points `pts`

in affine coordinates. Use it with `pippenger_with_affine_array`

to get better performance.

`val of_affine_array : affine_array -> t array`

Build a OCaml array of `t`

values from the contiguous C array

`val size_of_affine_array : affine_array -> int`

Return the number of elements in the array

`module Scalar : Ff_sig.PRIME with type t = Fr.t`

`val check_bytes : Bytes.t -> bool`

Check if a point, represented as a byte array, is on the curve and in the prime subgroup. The bytes must be of length `size_in_bytes`

.

Attempt to construct a point from a byte array of length `size_in_bytes`

.

Attempt to construct a point from a byte array of length `size_in_bytes`

. Raise `Not_on_curve`

if the point is not on the curve

Allocates a new point from a byte of length `size_in_bytes / 2`

array representing a point in compressed form.

Allocates a new point from a byte array of length `size_in_bytes / 2`

representing a point in compressed form. Raise `Not_on_curve`

if the point is not on the curve.

`val zero : t`

Zero of the elliptic curve

`val one : t`

A fixed generator of the elliptic curve

`val is_zero : t -> bool`

Return `true`

if the given element is zero

`val random : ?state:Random.State.t -> unit -> t`

Generate a random element. The function ensures the element is on the curve and in the prime subgroup.

The routines in the module `Random.State`

are used to generate the elements. A state can be given to the function to be used. If no state is given, `Random.get_state`

is used.

To create a value of type `Random.State.t`

, you can use ```
Random.State.make
[|42|]
```

.

`add_inplace a b`

is the same than `add`

but writes the output in `a`

. No allocation happens.

`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`

.

`mul_inplace g x`

is the same than `mul`

but writes the output in `g`

. No allocation happens.

`fft ~domain ~points`

performs a Fourier transform on `points`

using `domain`

The domain should be of the form `w^{i}`

where `w`

is a principal root of unity. If the domain is of size `n`

, `w`

must be a `n`

-th principal root of unity. The number of points can be smaller than the domain size, but not larger. The complexity is in `O(n log(m))`

where `n`

is the domain size and `m`

the number of points. A new array of size `n`

is allocated and is returned. The parameters are not modified.

`fft_inplace ~domain ~points`

performs a Fourier transform on `points`

using `domain`

The domain should be of the form `w^{i}`

where `w`

is a principal root of unity. If the domain is of size `n`

, `w`

must be a `n`

-th principal root of unity. The number of points must be in the same size than the domain. It does not return anything but modified the points directly. It does only perform one allocation of a scalar for the FFT. It is recommended to use this function if side-effect is acceptable.

`ifft ~domain ~points`

performs an inverse Fourier transform on `points`

using `domain`

. The domain should be of the form `w^{-i}`

(i.e the "inverse domain") where `w`

is a principal root of unity. If the domain is of size `n`

, `w`

must be a `n`

-th principal root of unity. The domain size must be exactly the same than the number of points. The complexity is O(n log(n)) where `n`

is the domain size. A new array of size `n`

is allocated and is returned. The parameters are not modified.

`ifft_inplace ~domain ~points`

is the same than `ifft`

but modifies the array `points`

instead of returning a new array

`hash_to_curve msg dst`

follows the standard Hashing to Elliptic Curves applied to BLS12-381

`pippenger ?start ?len pts scalars`

computes the multi scalar exponentiation/multiplication. The scalars are given in `scalars`

and the points in `pts`

. If `pts`

and `scalars`

are not of the same length, perform the computation on the first `n`

points where `n`

is the smallest size. Arguments `start`

and `len`

can be used to take advantages of multicore OCaml. Default value for `start`

(resp. `len`

) is `0`

(resp. the length of the array `scalars`

).

```
val pippenger_with_affine_array :
?start:int ->
?len:int ->
affine_array ->
Scalar.t array ->
t
```

`pippenger_with_affine_array ?start ?len pts scalars`

computes the multi scalar exponentiation/multiplication. The scalars are given in `scalars`

and the points in `pts`

. If `pts`

and `scalars`

are not of the same length, perform the computation on the first `n`

points where `n`

is the smallest length. The differences with `pippenger`

are 1. the points are loaded in a contiguous C array to speed up the access to the elements by relying on the CPU cache 2. and the points are in affine coordinates, the form expected by the algorithm implementation, avoiding new allocations and field inversions required to convert from jacobian (representation of a points of type `t`

, as expected by `pippenger`

) to affine coordinates. Expect a speed improvement around 20% compared to `pippenger`

, and less allocation on the C heap. A value of `affine_array`

can be built using `to_affine_array`

. Arguments `start`

and `len`

can be used to take advantages of multicore OCaml. Default value for `start`

(resp. `len`

) is `0`

(resp. the length of the array `scalars`

).

Create a point from the coordinates. If the point is not on the curve and in the prime subgroup, returns `None`

. The points must be given modulo the order of `Fq`

. The points are in the form `(c0, c1)`

where `x = c1 * X + c0`

and ```
y = c1 * X
+ c0
```

. To create the point at infinity, use `zero`