-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Bilinear pairings
--   
--   Optimal Ate pairing over Barreto-Naehrig curves
@package pairing
@version 0.4.2

module Pairing.ByteRepr
class ByteRepr a
mkRepr :: ByteRepr a => ByteOrderLength -> a -> Maybe ByteString
fromRepr :: ByteRepr a => ByteOrderLength -> a -> ByteString -> Maybe a
calcReprLength :: ByteRepr a => a -> ElementLength -> Int
toBytes :: Integer -> ByteString
toPaddedBytes :: ByteOrderLength -> Integer -> Maybe ByteString
fromBytesToInteger :: ByteOrder -> ByteString -> Integer
data ByteOrder
MostSignificantFirst :: ByteOrder
LeastSignificantFirst :: ByteOrder
data ByteOrderLength
ByteOrderLength :: ByteOrder -> ElementLength -> ByteOrderLength
[byteOrder] :: ByteOrderLength -> ByteOrder
[lenPerElement] :: ByteOrderLength -> ElementLength

module Pairing.CyclicGroup
class AsInteger a
asInteger :: AsInteger a => a -> Integer
class Monoid g => CyclicGroup g
generator :: CyclicGroup g => g
order :: CyclicGroup g => Proxy g -> Integer
expn :: (CyclicGroup g, AsInteger e) => g -> e -> g
inverse :: CyclicGroup g => g -> g
random :: (CyclicGroup g, MonadRandom m) => m g
class FromX a
yFromX :: FromX a => a -> (a -> a -> a) -> Maybe a
isOdd :: FromX a => a -> Bool
class Validate a
isValidElement :: Validate a => a -> Bool

-- | Sum all the elements of some container according to its group
--   structure.
sumG :: (Foldable t, CyclicGroup g) => t g -> g
instance Pairing.CyclicGroup.AsInteger GHC.Types.Int
instance Pairing.CyclicGroup.AsInteger GHC.Integer.Type.Integer
instance Pairing.CyclicGroup.AsInteger (PrimeField.PrimeField p)


-- | Parameters chosen for the pairing. The parameters chosen here
--   correspond to the BN128 curve (aka CurveSNARK).
--   
--   <pre>
--   a = 0
--   b = 3
--   k = 12
--   t = 4965661367192848881
--   q = 21888242871839275222246405745257275088696311157297823662689037894645226208583
--   r = 21888242871839275222246405745257275088548364400416034343698204186575808495617
--   ξ = 9 + u
--   </pre>
module Pairing.Params

-- | Elliptic curve coefficent
_a :: Integer

-- | Elliptic curve coefficent
_b :: Integer

-- | Characteristic of the finite fields we work with
_q :: Integer

-- | Order of elliptic curve E(Fq) G1, and therefore also the
--   characteristic of the prime field we choose our exponents from
_r :: Integer

-- | Embedding degree
_k :: Integer

-- | Quadratic nonresidue in Fq
_nqr :: Integer

-- | Parameter used to define the twisted curve over Fq, with xi = xi_a +
--   xi_b * i
_xiA :: Integer

-- | Parameter used to define the twisted curve over Fq, with xi = xi_a +
--   xi_b * i
_xiB :: Integer

module Pairing.Modular
withMod :: Integer -> (forall m. KnownNat m => Proxy m -> r) -> r
withModM :: Integer -> (forall n. KnownNat n => Proxy n -> m r) -> m r
withQ :: (forall m. KnownNat m => Proxy m -> r) -> r
withQM :: (forall n. KnownNat n => Proxy n -> m r) -> m r
withR :: (forall m. KnownNat m => Proxy m -> r) -> r
withRM :: (forall n. KnownNat n => Proxy n -> m r) -> m r
newMod :: forall m. KnownNat m => Integer -> Proxy m -> Mod m
toInteger :: Mod m -> Integer
modUnOp :: forall m. KnownNat m => Integer -> (Mod m -> Mod m) -> Proxy m -> Integer
modBinOp :: forall m. KnownNat m => Integer -> Integer -> (Mod m -> Mod m -> Mod m) -> Proxy m -> Integer
multInverse :: KnownNat m => Mod m -> Maybe (Mod m)
modUnOpM :: forall m a. (KnownNat m, Monad a) => Integer -> (Mod m -> a (Mod m)) -> Proxy m -> a Integer
modUnOpMTup :: forall m a. (KnownNat m, Monad a) => Integer -> (Mod m -> a (Mod m, Mod m)) -> Proxy m -> a (Integer, Integer)
threeModFourCongruence :: Integer -> Bool
isSquare :: forall m. KnownNat m => Proxy m -> Mod m -> Bool

-- | Picks the postive square root only |
sqrtOf :: forall m. KnownNat m => Mod m -> Maybe (Mod m)
bothSqrtOf :: forall m. KnownNat m => Mod m -> Maybe (Mod m, Mod m)
legendre :: Integer -> Integer
randomMod :: forall n m. (MonadRandom m, KnownNat n) => Proxy n -> m (Mod n)
fromBytes :: forall n. KnownNat n => ByteOrder -> ByteString -> Proxy n -> Mod n


-- | Prime field from which exponents should be chosen
module Pairing.Fr

-- | Prime field <tt>Fr</tt> with characteristic <tt>_r</tt>
type Fr = PrimeField 21888242871839275222246405745257275088548364400416034343698204186575808495617
isRootOfUnity :: Integer -> Fr -> Bool
isPrimitiveRootOfUnity :: Integer -> Fr -> Bool

-- | Compute primitive roots of unity for 2^0, 2^1, ..., 2^28. (2^28 is the
--   largest power of two that divides _r - 1, therefore there are no
--   primitive roots of unity for higher powers of 2 in Fr.)
primitiveRootOfUnity :: Int -> Fr
precompRootOfUnity :: Int -> Fr


-- | Prime field with characteristic _q, over which the elliptic curve is
--   defined and the other finite field extensions.
--   
--   <ul>
--   <li>Fq</li>
--   <li>Fq2 := Fq[u]/u^2 + 1</li>
--   <li>Fq6 := Fq2[v]/v^3 - (9 + u)</li>
--   <li>Fq12 := Fq6[w]/w^2 - v</li>
--   </ul>
module Pairing.Fq

-- | Prime field <tt>Fq</tt> with characteristic <tt>_q</tt>
type Fq = PrimeField 21888242871839275222246405745257275088696311157297823662689037894645226208583

-- | Quadratic extension field of <tt>Fq</tt> defined as <tt>Fq2 =
--   Fq[u]/<a>f(u)</a></tt>
type Fq2 = ExtensionField Fq PolynomialU

-- | Cubic extension field of <tt>Fq2</tt> defined as <tt>Fq6 =
--   Fq2[v]/<a>g(v)</a></tt>
type Fq6 = ExtensionField Fq2 PolynomialV

-- | Quadratic extension field of <tt>Fq6</tt> defined as <tt>Fq12 =
--   Fq6[w]/<a>h(w)</a></tt>
type Fq12 = ExtensionField Fq6 PolynomialW
fqSqrt :: (Fq -> Fq -> Fq) -> Fq -> Maybe Fq

-- | Square root of Fq2 are specified by
--   <a>https://eprint.iacr.org/2012/685.pdf</a>, Algorithm 9 with lots of
--   help from
--   <a>https://docs.rs/pairing/0.14.1/src/pairing/bls12_381/fq2.rs.html#162-222</a>
--   This implementation appears to return the larger square root so check
--   the return value and negate as necessary
fq2Sqrt :: Fq2 -> Maybe Fq2
fqYforX :: Fq -> (Fq -> Fq -> Fq) -> Maybe Fq
fq2YforX :: Fq2 -> (Fq2 -> Fq2 -> Fq2) -> Maybe Fq2

-- | Quadratic non-residue
fqNqr :: Fq

-- | Cubic non-residue in <tt>Fq2</tt>
xi :: Fq2

-- | Multiply by <tt>xi</tt> (cubic nonresidue in <tt>Fq2</tt>) and reorder
--   coefficients
mulXi :: Fq6 -> Fq6

-- | Conjugation
fq2Conj :: Fq2 -> Fq2

-- | Multiplication by a scalar in <tt>Fq</tt>
fq2ScalarMul :: Fq -> Fq2 -> Fq2

-- | Create a new value in <tt>Fq12</tt> by providing a list of twelve
--   coefficients in <tt>Fq</tt>, should be used instead of the
--   <tt>Fq12</tt> constructor.
construct :: [Fq] -> Fq12

-- | Deconstruct a value in <tt>Fq12</tt> into a list of twelve
--   coefficients in <tt>Fq</tt>.
deconstruct :: Fq12 -> [Fq]

-- | Conjugation
fq12Conj :: Fq12 -> Fq12

-- | Iterated Frobenius automorphism
fq12Frobenius :: Int -> Fq12 -> Fq12
instance Pairing.ByteRepr.ByteRepr Pairing.Fq.Fq12
instance ExtensionField.IrreducibleMonic Pairing.Fq.Fq6 Pairing.Fq.PolynomialW
instance Pairing.ByteRepr.ByteRepr Pairing.Fq.Fq6
instance ExtensionField.IrreducibleMonic Pairing.Fq.Fq2 Pairing.Fq.PolynomialV
instance Pairing.CyclicGroup.FromX Pairing.Fq.Fq2
instance Pairing.ByteRepr.ByteRepr Pairing.Fq.Fq2
instance ExtensionField.IrreducibleMonic Pairing.Fq.Fq Pairing.Fq.PolynomialU
instance Pairing.CyclicGroup.FromX Pairing.Fq.Fq
instance Pairing.ByteRepr.ByteRepr Pairing.Fq.Fq


-- | Affine point arithmetic defining the group operation on an elliptic
--   curve E(F), for some field F. In our case the field F is given as some
--   type t with Num and Fractional instances.
module Pairing.Point

-- | Points on a curve over a field <tt>a</tt> represented as either affine
--   coordinates or as a point at infinity.
data Point a

-- | Affine point
Point :: a -> a -> Point a

-- | Point at infinity
Infinity :: Point a

-- | Point doubling
gDouble :: GaloisField k => Point k -> Point k

-- | Point addition, provides a group structure on an elliptic curve with
--   the point at infinity as its unit.
gAdd :: GaloisField k => Point k -> Point k -> Point k

-- | Negation (flipping the y component)
gNeg :: GaloisField k => Point k -> Point k

-- | Multiplication by a scalar
gMul :: (Integral a, GaloisField k) => Point k -> a -> Point k
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Pairing.Point.Point a)
instance GHC.Generics.Generic (Pairing.Point.Point a)
instance GHC.Base.Functor Pairing.Point.Point
instance GHC.Show.Show a => GHC.Show.Show (Pairing.Point.Point a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Pairing.Point.Point a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Pairing.Point.Point a)


-- | Jacobian representation of points on an elliptic curve.
--   
--   In Jacobian coordinates the triple <tt>(x, y, z)</tt> represents the
--   affine point <tt>(X <i> Z^2, Y </i> Z^3)</tt>. Curve operations are
--   more optimal in Jacobian coordinates when the time complexity for
--   underlying field inversions is significantly higher than field
--   multiplications.
module Pairing.Jacobian

-- | Jacobian coordinates for points on an elliptic curve over a field
--   <tt>k</tt>.
type JPoint k = (k, k, k)

-- | Convert affine coordinates to Jacobian coordinates
toJacobian :: GaloisField k => Point k -> JPoint k

-- | Convert Jacobian coordinates to affine coordinates
fromJacobian :: GaloisField k => JPoint k -> Point k

module Pairing.Hash

-- | Encodes a given byte string to a point on the BN curve. The
--   implemenation uses the Shallue van de Woestijne encoding to BN curves
--   as specifed in Section 6 of Indifferentiable Hashing to Barreto
--   Naehrig Curves by Pierre-Alain Fouque and Mehdi Tibouchi. This
--   function evaluates an empty bytestring or one that contains NUL to
--   zero which according to Definiton 2 of the paper is sent to an
--   arbitrary point on the curve
swEncBN :: MonadRandom m => ByteString -> m (Maybe (Point Fq))


-- | Base API for Point serialisation for G1, G2 and GT
module Pairing.Serialize.Types
class MkCompressedForm a

-- | The serialisation may fail if y cannot be obtained from x
serializeCompressed :: (MkCompressedForm a, ByteRepr b, FromX b, Ord b) => a -> Point b -> Maybe LByteString
class MkUncompressedForm a
serializePointUncompressed :: (MkUncompressedForm a, ByteRepr b, FromX b, Eq b) => a -> Point b -> Maybe LByteString
serializeUncompressed :: (MkUncompressedForm a, ByteRepr c) => a -> c -> Maybe LByteString
class FromSerialisedForm a
unserializePoint :: (FromSerialisedForm a, ByteRepr b, FromX b, Ord b, Show b, Validate (Point b)) => a -> Point b -> LByteString -> Either Text (Point b)
class FromUncompressedForm a
unserialize :: (FromUncompressedForm a, ByteRepr b, Validate b, Eq b, Show b) => a -> b -> LByteString -> Either Text b
minReprLength :: Int
buildPoint :: ByteRepr a => a -> ByteOrderLength -> ByteString -> ByteOrderLength -> ByteString -> Maybe (Point a)
parseBS :: (Validate a, Show a) => Get (Maybe a) -> LByteString -> Either Text a


-- | MCL WASM (https:/<i>github.com</i>herumi/mcl-wasm) serialisation
--   support MCL WASM uses the following algorithm to serialise P = (x, y)
--   in G1 if P.isZero() then 64-bytes zero. otherwise, d = x.serialize()
--   if (y.isOdd()) d[MSB] |= 0x80 On analysis of the GT format, each
--   element of GT is simply LSB serialised and appended as a continuous
--   bytestring, using the element length to split each point
module Pairing.Serialize.MCLWasm
data MCLWASM
MCLWASM :: MCLWASM
instance GHC.Show.Show Pairing.Serialize.MCLWasm.MCLWASM
instance GHC.Classes.Eq Pairing.Serialize.MCLWasm.MCLWASM
instance Pairing.Serialize.Types.MkCompressedForm Pairing.Serialize.MCLWasm.MCLWASM
instance Pairing.Serialize.Types.FromSerialisedForm Pairing.Serialize.MCLWasm.MCLWASM


-- | Point serialisation using
--   <a>https://tools.ietf.org/id/draft-jivsov-ecc-compact-05.html</a> It
--   is unclear if 02 is smallest y or not so the following is used in the
--   first 2 bytes 01 - Point at infinity 02 - Compressed repr i.e. x only
--   but use smallest y on decode 03 - Compressed repr i.e. x only but use
--   largest y on decode 04 -- Uncompressed repr i.e. x &amp; y
module Pairing.Serialize.Jivsov
data Jivsov
Jivsov :: Jivsov
instance Pairing.Serialize.Types.MkCompressedForm Pairing.Serialize.Jivsov.Jivsov
instance Pairing.Serialize.Types.MkUncompressedForm Pairing.Serialize.Jivsov.Jivsov
instance Pairing.Serialize.Types.FromSerialisedForm Pairing.Serialize.Jivsov.Jivsov
instance Pairing.Serialize.Types.FromUncompressedForm Pairing.Serialize.Jivsov.Jivsov


-- | Definitions of the groups the pairing is defined on
module Pairing.Group
class Monoid g => CyclicGroup g
generator :: CyclicGroup g => g
order :: CyclicGroup g => Proxy g -> Integer
expn :: (CyclicGroup g, AsInteger e) => g -> e -> g
inverse :: CyclicGroup g => g -> g
random :: (CyclicGroup g, MonadRandom m) => m g

-- | G1 is E(Fq) defined by y^2 = x^3 + b
type G1 = Point Fq

-- | G2 is E'(Fq2) defined by y^2 = x^3 + b / xi
type G2 = Point Fq2

-- | GT is subgroup of _r-th roots of unity of the multiplicative group of
--   Fq12
type GT = Fq12

-- | Parameter for curve on Fq
b1 :: Fq

-- | Parameter for twisted curve over Fq2
b2 :: Fq2

-- | Generator for G1
g1 :: G1

-- | Generator for G2
g2 :: G2
groupFromX :: (Validate (Point a), FromX a) => (a -> a -> a) -> a -> Maybe (Point a)
hashToG1 :: MonadRandom m => ByteString -> m (Maybe G1)

-- | Test whether a value is an _r-th root of unity
isInGT :: GT -> Bool

-- | Test whether a value in G1 satisfies the corresponding curve equation
isOnCurveG1 :: G1 -> Bool

-- | Test whether a value in G2 satisfies the corresponding curve equation
isOnCurveG2 :: G2 -> Bool
fromByteStringG1 :: FromSerialisedForm u => u -> LByteString -> Either Text G1
fromByteStringG2 :: FromSerialisedForm u => u -> LByteString -> Either Text G2
fromByteStringGT :: FromUncompressedForm u => u -> LByteString -> Either Text GT
instance GHC.Base.Semigroup Pairing.Group.GT
instance GHC.Base.Monoid Pairing.Group.GT
instance Pairing.CyclicGroup.CyclicGroup Pairing.Group.GT
instance Pairing.CyclicGroup.Validate Pairing.Group.GT
instance GHC.Base.Semigroup Pairing.Group.G2
instance GHC.Base.Monoid Pairing.Group.G2
instance Pairing.CyclicGroup.CyclicGroup Pairing.Group.G2
instance Pairing.CyclicGroup.Validate Pairing.Group.G2
instance Test.QuickCheck.Arbitrary.Arbitrary Pairing.Group.G2
instance GHC.Base.Semigroup Pairing.Group.G1
instance GHC.Base.Monoid Pairing.Group.G1
instance Pairing.CyclicGroup.CyclicGroup Pairing.Group.G1
instance Pairing.CyclicGroup.Validate Pairing.Group.G1
instance Test.QuickCheck.Arbitrary.Arbitrary Pairing.Group.G1


-- | Implementation of the optimal Ate pairing on the curve BN128
module Pairing.Pairing

-- | Optimal Ate pairing (including final exponentiation step)
reducedPairing :: G1 -> G2 -> GT

-- | Optimal Ate pairing without the final exponentiation step
atePairing :: G1 -> G2 -> Fq12

-- | A faster way of performing the final exponentiation step
finalExponentiation :: Fq12 -> GT

-- | Naive implementation of the final exponentiation step
finalExponentiationNaive :: Fq12 -> GT

-- | Iterated frobenius morphisms on fields of characteristic _q,
--   implemented naively
frobeniusNaive :: Num a => Int -> a -> a

-- | Binary expansion (missing the most-significant bit) representing the
--   number 6 * _t + 2.
--   
--   <pre>
--   29793968203157093288
--   = 0b11001110101111001011100000011100110111110011101100011101110101000
--   </pre>
ateLoopCountBinary :: [Bool]
instance GHC.Classes.Eq Pairing.Pairing.EllCoeffs
instance GHC.Show.Show Pairing.Pairing.EllCoeffs