package bls12-381

  1. Overview
  2. Docs
exception Not_on_curve of Bytes.t
type t

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

type affine

An element on the curve and in the prime subgroup, in affine coordinates

val affine_of_jacobian : t -> affine

affine_of_jacobian p creates a new value of type affine representing the point p in affine coordinates

val jacobian_of_affine : affine -> t

jacobian_of_affine p creates a new value of type t representing the point p in jacobian coordinates

type affine_array

Contiguous C array containing points in affine 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

val size_in_memory : int

Actual number of bytes allocated for a value of type t

val size_in_bytes : int

The size of a point representation, in bytes

module Scalar : Ff_sig.PRIME with type t = Fr.t
val empty : unit -> t

Create an empty value to store an element of the curve. DO NOT USE THIS TO DO COMPUTATIONS WITH, UNDEFINED BEHAVIORS MAY HAPPEN

val check_bytes : Bytes.t -> bool

Check if a point, represented as a byte array, is on the curve *

val of_bytes_opt : Bytes.t -> t option

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

val of_bytes_exn : Bytes.t -> t

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

val of_compressed_bytes_opt : Bytes.t -> t option

Allocates a new point from a byte of length size_in_bytes / 2 array representing a point in compressed form.

val of_compressed_bytes_exn : Bytes.t -> t

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 to_bytes : t -> Bytes.t

Return a representation in bytes

val to_compressed_bytes : t -> Bytes.t

Return a compressed bytes representation

val copy : t -> t

copy x return a fresh copy of x

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 element is on the curve and in the prime subgroup.

val add : t -> t -> t

Return the addition of two element

val add_inplace : t -> t -> unit
val add_bulk : t list -> t
val double : t -> t

double g returns 2g

val negate : t -> t

Return the opposite of the element

val eq : t -> t -> bool

Return true if the two elements are algebraically the same

val mul : t -> Scalar.t -> t

Multiply an element by a scalar

val mul_inplace : t -> Scalar.t -> unit
val fft : domain:Scalar.t array -> points:t array -> t array

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.

val fft_inplace : domain:Scalar.t array -> points:t array -> unit

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.

val ifft : domain:Scalar.t array -> points:t array -> t array

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.

val ifft_inplace : domain:Scalar.t array -> points:t array -> unit
val hash_to_curve : Bytes.t -> Bytes.t -> t
val of_z_opt : x:(Z.t * Z.t) -> y:(Z.t * Z.t) -> t option

Create a point from the coordinates. If the point is not on the curve, None is return. 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 ()

val pippenger : ?start:int -> ?len:int -> t array -> Scalar.t array -> t

pippenger ?start ?len pts scalars computes the multi scalar exponentiation/multiplication. The scalars are given in scalars and the points in pts. 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).

  • raises Invalid_argument

    if the arguments pts and scalars are not of the same length or if start or len would infer out of bounds array access.

    Perform allocations on the C heap to convert scalars to bytes and to convert the points pts in affine coordinates as values of type t are in jacobian coordinates.

    Warning. Undefined behavior if the point to infinity is in the array

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. 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).

  • raises Invalid_argument

    if the arguments pts and scalars are not of the same length or if start or len would infer out of bounds array access.

    Perform allocations on the C heap to convert scalars to bytes.

    Warning. Undefined behavior if the point to infinity is in the array