From a6330b5d3c58a79dc1536837b57750e6dd8f8f59 Mon Sep 17 00:00:00 2001 From: "zhoujun.ma" Date: Wed, 5 Apr 2023 05:49:51 -0700 Subject: [PATCH] rename module to crypt_algebra --- .../framework/aptos-stdlib/doc/algebra.md | 1722 ----------------- .../aptos-stdlib/doc/crypt_algebra.md | 1722 +++++++++++++++++ ..._bls12381.md => crypt_algebra_bls12381.md} | 152 +- .../framework/aptos-stdlib/doc/overview.md | 4 +- .../{algebra.move => crypt_algebra.move} | 2 +- ...ebra.spec.move => crypt_algebra.spec.move} | 2 +- ...12381.move => crypt_algebra_bls12381.move} | 8 +- .../src/natives/cryptography/algebra/mod.rs | 30 +- aptos-move/framework/src/natives/mod.rs | 2 +- .../groth16_example/sources/groth16.move | 6 +- 10 files changed, 1825 insertions(+), 1825 deletions(-) delete mode 100644 aptos-move/framework/aptos-stdlib/doc/algebra.md create mode 100644 aptos-move/framework/aptos-stdlib/doc/crypt_algebra.md rename aptos-move/framework/aptos-stdlib/doc/{algebra_bls12381.md => crypt_algebra_bls12381.md} (64%) rename aptos-move/framework/aptos-stdlib/sources/cryptography/{algebra.move => crypt_algebra.move} (99%) rename aptos-move/framework/aptos-stdlib/sources/cryptography/{algebra.spec.move => crypt_algebra.spec.move} (98%) rename aptos-move/framework/aptos-stdlib/sources/cryptography/{algebra_bls12381.move => crypt_algebra_bls12381.move} (99%) diff --git a/aptos-move/framework/aptos-stdlib/doc/algebra.md b/aptos-move/framework/aptos-stdlib/doc/algebra.md deleted file mode 100644 index 4c326428fafb9..0000000000000 --- a/aptos-move/framework/aptos-stdlib/doc/algebra.md +++ /dev/null @@ -1,1722 +0,0 @@ - - - -# Module `0x1::algebra` - -This module provides generic structs/functions for operations of algebraic structures (e.g. fields and groups), -which can be used to build generic cryptographic schemes atop. -E.g., a Groth16 ZK proof verifier can be built to work over any pairing supported in this module. - -In general, every structure implements basic operations like (de)serialization, equality check, random sampling. - -A group may also implement the following operations. (Additive group notation is assumed.) -- order() for getting the group order. -- zero() for getting the group identity. -- one() for getting the group generator (if exists). -- neg() for group element inversion. -- add() for group operation (i.e., a group addition). -- sub() for group element subtraction. -- double() for efficient doubling. -- scalar_mul() for group scalar multiplication. -- multi_scalar_mul() for efficient group multi-scalar multiplication. -- hash_to() for hash-to-group. - -A field may also implement the following operations. -- zero() for getting the field additive identity. -- one() for getting the field multiplicative identity. -- add() for field addition. -- sub() for field subtraction. -- mul() for field multiplication. -- div() for field division. -- neg() for field negation. -- inv() for field inversion. -- sqr() for efficient field element squaring. -- from_u64() for quick conversion from u64 to field element. - -For 3 groups that admit a bilinear map, pairing() and multi_pairing() may be implemented. - -For a subset/superset relationship between 2 structures, upcast() and downcast() may be implemented. -E.g., in BLS12-381 pairing, since Gt is a subset of Fq12, -upcast<Gt, Fq12>() and downcast<Fq12, Gt>() will be supported. - -See algebra_*.move for currently implemented algebraic structures. - - -- [Struct `Element`](#0x1_algebra_Element) -- [Constants](#@Constants_0) -- [Function `eq`](#0x1_algebra_eq) -- [Function `from_u64`](#0x1_algebra_from_u64) -- [Function `zero`](#0x1_algebra_zero) -- [Function `one`](#0x1_algebra_one) -- [Function `neg`](#0x1_algebra_neg) -- [Function `add`](#0x1_algebra_add) -- [Function `sub`](#0x1_algebra_sub) -- [Function `mul`](#0x1_algebra_mul) -- [Function `div`](#0x1_algebra_div) -- [Function `sqr`](#0x1_algebra_sqr) -- [Function `inv`](#0x1_algebra_inv) -- [Function `double`](#0x1_algebra_double) -- [Function `multi_scalar_mul`](#0x1_algebra_multi_scalar_mul) -- [Function `scalar_mul`](#0x1_algebra_scalar_mul) -- [Function `multi_pairing`](#0x1_algebra_multi_pairing) -- [Function `pairing`](#0x1_algebra_pairing) -- [Function `deserialize`](#0x1_algebra_deserialize) -- [Function `serialize`](#0x1_algebra_serialize) -- [Function `order`](#0x1_algebra_order) -- [Function `upcast`](#0x1_algebra_upcast) -- [Function `downcast`](#0x1_algebra_downcast) -- [Function `hash_to`](#0x1_algebra_hash_to) -- [Function `abort_unless_cryptography_algebra_natives_enabled`](#0x1_algebra_abort_unless_cryptography_algebra_natives_enabled) -- [Function `handles_from_elements`](#0x1_algebra_handles_from_elements) -- [Function `add_internal`](#0x1_algebra_add_internal) -- [Function `deserialize_internal`](#0x1_algebra_deserialize_internal) -- [Function `div_internal`](#0x1_algebra_div_internal) -- [Function `double_internal`](#0x1_algebra_double_internal) -- [Function `downcast_internal`](#0x1_algebra_downcast_internal) -- [Function `from_u64_internal`](#0x1_algebra_from_u64_internal) -- [Function `eq_internal`](#0x1_algebra_eq_internal) -- [Function `hash_to_internal`](#0x1_algebra_hash_to_internal) -- [Function `inv_internal`](#0x1_algebra_inv_internal) -- [Function `mul_internal`](#0x1_algebra_mul_internal) -- [Function `multi_pairing_internal`](#0x1_algebra_multi_pairing_internal) -- [Function `multi_scalar_mul_internal`](#0x1_algebra_multi_scalar_mul_internal) -- [Function `neg_internal`](#0x1_algebra_neg_internal) -- [Function `one_internal`](#0x1_algebra_one_internal) -- [Function `order_internal`](#0x1_algebra_order_internal) -- [Function `pairing_internal`](#0x1_algebra_pairing_internal) -- [Function `scalar_mul_internal`](#0x1_algebra_scalar_mul_internal) -- [Function `serialize_internal`](#0x1_algebra_serialize_internal) -- [Function `sqr_internal`](#0x1_algebra_sqr_internal) -- [Function `sub_internal`](#0x1_algebra_sub_internal) -- [Function `upcast_internal`](#0x1_algebra_upcast_internal) -- [Function `zero_internal`](#0x1_algebra_zero_internal) -- [Specification](#@Specification_1) - - [Function `add_internal`](#@Specification_1_add_internal) - - [Function `deserialize_internal`](#@Specification_1_deserialize_internal) - - [Function `div_internal`](#@Specification_1_div_internal) - - [Function `double_internal`](#@Specification_1_double_internal) - - [Function `downcast_internal`](#@Specification_1_downcast_internal) - - [Function `from_u64_internal`](#@Specification_1_from_u64_internal) - - [Function `eq_internal`](#@Specification_1_eq_internal) - - [Function `hash_to_internal`](#@Specification_1_hash_to_internal) - - [Function `inv_internal`](#@Specification_1_inv_internal) - - [Function `mul_internal`](#@Specification_1_mul_internal) - - [Function `multi_pairing_internal`](#@Specification_1_multi_pairing_internal) - - [Function `multi_scalar_mul_internal`](#@Specification_1_multi_scalar_mul_internal) - - [Function `neg_internal`](#@Specification_1_neg_internal) - - [Function `one_internal`](#@Specification_1_one_internal) - - [Function `order_internal`](#@Specification_1_order_internal) - - [Function `pairing_internal`](#@Specification_1_pairing_internal) - - [Function `scalar_mul_internal`](#@Specification_1_scalar_mul_internal) - - [Function `serialize_internal`](#@Specification_1_serialize_internal) - - [Function `sqr_internal`](#@Specification_1_sqr_internal) - - [Function `sub_internal`](#@Specification_1_sub_internal) - - [Function `upcast_internal`](#@Specification_1_upcast_internal) - - [Function `zero_internal`](#@Specification_1_zero_internal) - - -
use 0x1::error;
-use 0x1::features;
-use 0x1::option;
-
- - - - - -## Struct `Element` - -This struct represents an element of a structure S. - - -
struct Element<S> has copy, drop
-
- - - -
-Fields - - -
-
-handle: u64 -
-
- -
-
- - -
- - - -## Constants - - - - - - -
const E_NON_EQUAL_LENGTHS: u64 = 2;
-
- - - - - - - -
const E_NOT_IMPLEMENTED: u64 = 1;
-
- - - - - -## Function `eq` - -Check if x == y for elements x and y of a structure S. - - -
public fun eq<S>(x: &algebra::Element<S>, y: &algebra::Element<S>): bool
-
- - - -
-Implementation - - -
public fun eq<S>(x: &Element<S>, y: &Element<S>): bool {
-    abort_unless_cryptography_algebra_natives_enabled();
-    eq_internal<S>(x.handle, y.handle)
-}
-
- - - -
- - - -## Function `from_u64` - -Convert a u64 to an element of a structure S. - - -
public fun from_u64<S>(value: u64): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun from_u64<S>(value: u64): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: from_u64_internal<S>(value)
-    }
-}
-
- - - -
- - - -## Function `zero` - -Return the additive identity of field S, or the identity of group S. - - -
public fun zero<S>(): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun zero<S>(): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: zero_internal<S>()
-    }
-}
-
- - - -
- - - -## Function `one` - -Return the multiplicative identity of field S, or a fixed generator of group S. - - -
public fun one<S>(): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun one<S>(): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: one_internal<S>()
-    }
-}
-
- - - -
- - - -## Function `neg` - -Compute -x for an element x of a structure S. - - -
public fun neg<S>(x: &algebra::Element<S>): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun neg<S>(x: &Element<S>): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: neg_internal<S>(x.handle)
-    }
-}
-
- - - -
- - - -## Function `add` - -Compute x + y for elements x and y of structure S. - - -
public fun add<S>(x: &algebra::Element<S>, y: &algebra::Element<S>): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun add<S>(x: &Element<S>, y: &Element<S>): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: add_internal<S>(x.handle, y.handle)
-    }
-}
-
- - - -
- - - -## Function `sub` - -Compute x - y for elements x and y of a structure S. - - -
public fun sub<S>(x: &algebra::Element<S>, y: &algebra::Element<S>): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun sub<S>(x: &Element<S>, y: &Element<S>): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: sub_internal<S>(x.handle, y.handle)
-    }
-}
-
- - - -
- - - -## Function `mul` - -Compute x * y for elements x and y of a structure S. - - -
public fun mul<S>(x: &algebra::Element<S>, y: &algebra::Element<S>): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun mul<S>(x: &Element<S>, y: &Element<S>): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: mul_internal<S>(x.handle, y.handle)
-    }
-}
-
- - - -
- - - -## Function `div` - -Try computing x / y for elements x and y of a structure S. -Return none if y does not have a multiplicative inverse in the structure S -(e.g., when S is a field, and y is zero). - - -
public fun div<S>(x: &algebra::Element<S>, y: &algebra::Element<S>): option::Option<algebra::Element<S>>
-
- - - -
-Implementation - - -
public fun div<S>(x: &Element<S>, y: &Element<S>): Option<Element<S>> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    let (succ, handle) = div_internal<S>(x.handle, y.handle);
-    if (succ) {
-        some(Element<S> { handle })
-    } else {
-        none()
-    }
-}
-
- - - -
- - - -## Function `sqr` - -Compute x^2 for an element x of a structure S. Faster and cheaper than mul(x, x). - - -
public fun sqr<S>(x: &algebra::Element<S>): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun sqr<S>(x: &Element<S>): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: sqr_internal<S>(x.handle)
-    }
-}
-
- - - -
- - - -## Function `inv` - -Try computing x^(-1) for an element x of a structure S. -Return none if x does not have a multiplicative inverse in the structure S -(e.g., when S is a field, and x is zero). - - -
public fun inv<S>(x: &algebra::Element<S>): option::Option<algebra::Element<S>>
-
- - - -
-Implementation - - -
public fun inv<S>(x: &Element<S>): Option<Element<S>> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    let (succeeded, handle) = inv_internal<S>(x.handle);
-    if (succeeded) {
-        let scalar = Element<S> { handle };
-        some(scalar)
-    } else {
-        none()
-    }
-}
-
- - - -
- - - -## Function `double` - -Compute 2*P for an element P of a structure S. Faster and cheaper than add(P, P). - - -
public fun double<S>(element_p: &algebra::Element<S>): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun double<S>(element_p: &Element<S>): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<S> {
-        handle: double_internal<S>(element_p.handle)
-    }
-}
-
- - - -
- - - -## Function `multi_scalar_mul` - -Compute k[0]*P[0]+...+k[n-1]*P[n-1], where -P[] are n elements of group G represented by parameter elements, and -k[] are n elements of the scalarfield S of group G represented by parameter scalars. - -Abort with code std::error::invalid_argument(E_NON_EQUAL_LENGTHS) if the sizes of elements and scalars do not match. - - -
public fun multi_scalar_mul<G, S>(elements: &vector<algebra::Element<G>>, scalars: &vector<algebra::Element<S>>): algebra::Element<G>
-
- - - -
-Implementation - - -
public fun multi_scalar_mul<G, S>(elements: &vector<Element<G>>, scalars: &vector<Element<S>>): Element<G> {
-    let element_handles = handles_from_elements(elements);
-    let scalar_handles = handles_from_elements(scalars);
-    Element<G> {
-        handle: multi_scalar_mul_internal<G, S>(element_handles, scalar_handles)
-    }
-}
-
- - - -
- - - -## Function `scalar_mul` - -Compute k*P, where P is an element of a group G and k is an element of the scalar field S associated to the group G. - - -
public fun scalar_mul<G, S>(element_p: &algebra::Element<G>, scalar_k: &algebra::Element<S>): algebra::Element<G>
-
- - - -
-Implementation - - -
public fun scalar_mul<G, S>(element_p: &Element<G>, scalar_k: &Element<S>): Element<G> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<G> {
-        handle: scalar_mul_internal<G, S>(element_p.handle, scalar_k.handle)
-    }
-}
-
- - - -
- - - -## Function `multi_pairing` - -Efficiently compute e(P[0],Q[0])+...+e(P[n-1],Q[n-1]), -where e: (G1,G2) -> (Gt) is the pairing function from groups (G1,G2) to group Gt, -P[] are n elements of group G1 represented by parameter g1_elements, and -Q[] are n elements of group G2 represented by parameter g2_elements. - -Abort with code std::error::invalid_argument(E_NON_EQUAL_LENGTHS) if the sizes of g1_elements and g2_elements do not match. - -NOTE: we are viewing the target group Gt of the pairing as an additive group, -rather than a multiplicative one (which is typically the case). - - -
public fun multi_pairing<G1, G2, Gt>(g1_elements: &vector<algebra::Element<G1>>, g2_elements: &vector<algebra::Element<G2>>): algebra::Element<Gt>
-
- - - -
-Implementation - - -
public fun multi_pairing<G1,G2,Gt>(g1_elements: &vector<Element<G1>>, g2_elements: &vector<Element<G2>>): Element<Gt> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    let g1_handles = handles_from_elements(g1_elements);
-    let g2_handles = handles_from_elements(g2_elements);
-    Element<Gt> {
-        handle: multi_pairing_internal<G1,G2,Gt>(g1_handles, g2_handles)
-    }
-}
-
- - - -
- - - -## Function `pairing` - -Compute the pairing function (a.k.a., bilinear map) on a G1 element and a G2 element. -Return an element in the target group Gt. - - -
public fun pairing<G1, G2, Gt>(element_1: &algebra::Element<G1>, element_2: &algebra::Element<G2>): algebra::Element<Gt>
-
- - - -
-Implementation - - -
public fun pairing<G1,G2,Gt>(element_1: &Element<G1>, element_2: &Element<G2>): Element<Gt> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<Gt> {
-        handle: pairing_internal<G1,G2,Gt>(element_1.handle, element_2.handle)
-    }
-}
-
- - - -
- - - -## Function `deserialize` - -Try deserializing a byte array to an element of an algebraic structure S using a given serialization format F. -Return none if the deserialization failed. - - -
public fun deserialize<S, F>(bytes: &vector<u8>): option::Option<algebra::Element<S>>
-
- - - -
-Implementation - - -
public fun deserialize<S, F>(bytes: &vector<u8>): Option<Element<S>> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    let (succeeded, handle) = deserialize_internal<S, F>(bytes);
-    if (succeeded) {
-        some(Element<S> { handle })
-    } else {
-        none()
-    }
-}
-
- - - -
- - - -## Function `serialize` - -Serialize an element of an algebraic structure S to a byte array using a given serialization format F. - - -
public fun serialize<S, F>(element: &algebra::Element<S>): vector<u8>
-
- - - -
-Implementation - - -
public fun serialize<S, F>(element: &Element<S>): vector<u8> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    serialize_internal<S, F>(element.handle)
-}
-
- - - -
- - - -## Function `order` - -Get the order of structure S, a big integer little-endian encoded as a byte array. - - -
public fun order<S>(): vector<u8>
-
- - - -
-Implementation - - -
public fun order<S>(): vector<u8> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    order_internal<S>()
-}
-
- - - -
- - - -## Function `upcast` - -Cast an element of a structure S to a parent structure L. - - -
public fun upcast<S, L>(element: &algebra::Element<S>): algebra::Element<L>
-
- - - -
-Implementation - - -
public fun upcast<S,L>(element: &Element<S>): Element<L> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element<L> {
-        handle: upcast_internal<S,L>(element.handle)
-    }
-}
-
- - - -
- - - -## Function `downcast` - -Try casting an element x of a structure L to a sub-structure S. -Return none if x is not a member of S. - -NOTE: Membership check in S is performed inside, which can be expensive, depending on the structures L and S. - - -
public fun downcast<L, S>(element_x: &algebra::Element<L>): option::Option<algebra::Element<S>>
-
- - - -
-Implementation - - -
public fun downcast<L,S>(element_x: &Element<L>): Option<Element<S>> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    let (succ, new_handle) = downcast_internal<L,S>(element_x.handle);
-    if (succ) {
-        some(Element<S> { handle: new_handle })
-    } else {
-        none()
-    }
-}
-
- - - -
- - - -## Function `hash_to` - -Hash an arbitrary-length byte array msg into structure S with a domain separation tag dst -using the given hash-to-structure suite H. - -NOTE: some hashing methods do not accept a dst and will abort if a non-empty one is provided. - - -
public fun hash_to<S, H>(dst: &vector<u8>, msg: &vector<u8>): algebra::Element<S>
-
- - - -
-Implementation - - -
public fun hash_to<S, H>(dst: &vector<u8>, msg: &vector<u8>): Element<S> {
-    abort_unless_cryptography_algebra_natives_enabled();
-    Element {
-        handle: hash_to_internal<S, H>(dst, msg)
-    }
-}
-
- - - -
- - - -## Function `abort_unless_cryptography_algebra_natives_enabled` - - - -
fun abort_unless_cryptography_algebra_natives_enabled()
-
- - - -
-Implementation - - -
fun abort_unless_cryptography_algebra_natives_enabled() {
-    if (features::cryptography_algebra_enabled()) return;
-    abort(std::error::not_implemented(0))
-}
-
- - - -
- - - -## Function `handles_from_elements` - - - -
fun handles_from_elements<S>(elements: &vector<algebra::Element<S>>): vector<u64>
-
- - - -
-Implementation - - -
fun handles_from_elements<S>(elements: &vector<Element<S>>): vector<u64> {
-    let num_elements = std::vector::length(elements);
-    let element_handles = std::vector::empty();
-    let i = 0;
-    while (i < num_elements) {
-        std::vector::push_back(&mut element_handles, std::vector::borrow(elements, i).handle);
-        i = i + 1;
-    };
-    element_handles
-}
-
- - - -
- - - -## Function `add_internal` - - - -
fun add_internal<S>(handle_1: u64, handle_2: u64): u64
-
- - - -
-Implementation - - -
native fun add_internal<S>(handle_1: u64, handle_2: u64): u64;
-
- - - -
- - - -## Function `deserialize_internal` - - - -
fun deserialize_internal<S, F>(bytes: &vector<u8>): (bool, u64)
-
- - - -
-Implementation - - -
native fun deserialize_internal<S, F>(bytes: &vector<u8>): (bool, u64);
-
- - - -
- - - -## Function `div_internal` - - - -
fun div_internal<F>(handle_1: u64, handle_2: u64): (bool, u64)
-
- - - -
-Implementation - - -
native fun div_internal<F>(handle_1: u64, handle_2: u64): (bool, u64);
-
- - - -
- - - -## Function `double_internal` - - - -
fun double_internal<G>(element_handle: u64): u64
-
- - - -
-Implementation - - -
native fun double_internal<G>(element_handle: u64): u64;
-
- - - -
- - - -## Function `downcast_internal` - - - -
fun downcast_internal<L, S>(handle: u64): (bool, u64)
-
- - - -
-Implementation - - -
native fun downcast_internal<L,S>(handle: u64): (bool, u64);
-
- - - -
- - - -## Function `from_u64_internal` - - - -
fun from_u64_internal<S>(value: u64): u64
-
- - - -
-Implementation - - -
native fun from_u64_internal<S>(value: u64): u64;
-
- - - -
- - - -## Function `eq_internal` - - - -
fun eq_internal<S>(handle_1: u64, handle_2: u64): bool
-
- - - -
-Implementation - - -
native fun eq_internal<S>(handle_1: u64, handle_2: u64): bool;
-
- - - -
- - - -## Function `hash_to_internal` - - - -
fun hash_to_internal<S, H>(dst: &vector<u8>, bytes: &vector<u8>): u64
-
- - - -
-Implementation - - -
native fun hash_to_internal<S, H>(dst: &vector<u8>, bytes: &vector<u8>): u64;
-
- - - -
- - - -## Function `inv_internal` - - - -
fun inv_internal<F>(handle: u64): (bool, u64)
-
- - - -
-Implementation - - -
native fun inv_internal<F>(handle: u64): (bool, u64);
-
- - - -
- - - -## Function `mul_internal` - - - -
fun mul_internal<F>(handle_1: u64, handle_2: u64): u64
-
- - - -
-Implementation - - -
native fun mul_internal<F>(handle_1: u64, handle_2: u64): u64;
-
- - - -
- - - -## Function `multi_pairing_internal` - - - -
fun multi_pairing_internal<G1, G2, Gt>(g1_handles: vector<u64>, g2_handles: vector<u64>): u64
-
- - - -
-Implementation - - -
native fun multi_pairing_internal<G1,G2,Gt>(g1_handles: vector<u64>, g2_handles: vector<u64>): u64;
-
- - - -
- - - -## Function `multi_scalar_mul_internal` - - - -
fun multi_scalar_mul_internal<G, S>(element_handles: vector<u64>, scalar_handles: vector<u64>): u64
-
- - - -
-Implementation - - -
native fun multi_scalar_mul_internal<G, S>(element_handles: vector<u64>, scalar_handles: vector<u64>): u64;
-
- - - -
- - - -## Function `neg_internal` - - - -
fun neg_internal<F>(handle: u64): u64
-
- - - -
-Implementation - - -
native fun neg_internal<F>(handle: u64): u64;
-
- - - -
- - - -## Function `one_internal` - - - -
fun one_internal<S>(): u64
-
- - - -
-Implementation - - -
native fun one_internal<S>(): u64;
-
- - - -
- - - -## Function `order_internal` - - - -
fun order_internal<G>(): vector<u8>
-
- - - -
-Implementation - - -
native fun order_internal<G>(): vector<u8>;
-
- - - -
- - - -## Function `pairing_internal` - - - -
fun pairing_internal<G1, G2, Gt>(g1_handle: u64, g2_handle: u64): u64
-
- - - -
-Implementation - - -
native fun pairing_internal<G1,G2,Gt>(g1_handle: u64, g2_handle: u64): u64;
-
- - - -
- - - -## Function `scalar_mul_internal` - - - -
fun scalar_mul_internal<G, S>(element_handle: u64, scalar_handle: u64): u64
-
- - - -
-Implementation - - -
native fun scalar_mul_internal<G, S>(element_handle: u64, scalar_handle: u64): u64;
-
- - - -
- - - -## Function `serialize_internal` - - - -
fun serialize_internal<S, F>(handle: u64): vector<u8>
-
- - - -
-Implementation - - -
native fun serialize_internal<S, F>(handle: u64): vector<u8>;
-
- - - -
- - - -## Function `sqr_internal` - - - -
fun sqr_internal<G>(handle: u64): u64
-
- - - -
-Implementation - - -
native fun sqr_internal<G>(handle: u64): u64;
-
- - - -
- - - -## Function `sub_internal` - - - -
fun sub_internal<G>(handle_1: u64, handle_2: u64): u64
-
- - - -
-Implementation - - -
native fun sub_internal<G>(handle_1: u64, handle_2: u64): u64;
-
- - - -
- - - -## Function `upcast_internal` - - - -
fun upcast_internal<S, L>(handle: u64): u64
-
- - - -
-Implementation - - -
native fun upcast_internal<S,L>(handle: u64): u64;
-
- - - -
- - - -## Function `zero_internal` - - - -
fun zero_internal<S>(): u64
-
- - - -
-Implementation - - -
native fun zero_internal<S>(): u64;
-
- - - -
- - - -## Specification - - - - -### Function `add_internal` - - -
fun add_internal<S>(handle_1: u64, handle_2: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `deserialize_internal` - - -
fun deserialize_internal<S, F>(bytes: &vector<u8>): (bool, u64)
-
- - - - -
pragma opaque;
-
- - - - - -### Function `div_internal` - - -
fun div_internal<F>(handle_1: u64, handle_2: u64): (bool, u64)
-
- - - - -
pragma opaque;
-
- - - - - -### Function `double_internal` - - -
fun double_internal<G>(element_handle: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `downcast_internal` - - -
fun downcast_internal<L, S>(handle: u64): (bool, u64)
-
- - - - -
pragma opaque;
-
- - - - - -### Function `from_u64_internal` - - -
fun from_u64_internal<S>(value: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `eq_internal` - - -
fun eq_internal<S>(handle_1: u64, handle_2: u64): bool
-
- - - - -
pragma opaque;
-
- - - - - -### Function `hash_to_internal` - - -
fun hash_to_internal<S, H>(dst: &vector<u8>, bytes: &vector<u8>): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `inv_internal` - - -
fun inv_internal<F>(handle: u64): (bool, u64)
-
- - - - -
pragma opaque;
-
- - - - - -### Function `mul_internal` - - -
fun mul_internal<F>(handle_1: u64, handle_2: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `multi_pairing_internal` - - -
fun multi_pairing_internal<G1, G2, Gt>(g1_handles: vector<u64>, g2_handles: vector<u64>): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `multi_scalar_mul_internal` - - -
fun multi_scalar_mul_internal<G, S>(element_handles: vector<u64>, scalar_handles: vector<u64>): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `neg_internal` - - -
fun neg_internal<F>(handle: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `one_internal` - - -
fun one_internal<S>(): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `order_internal` - - -
fun order_internal<G>(): vector<u8>
-
- - - - -
pragma opaque;
-
- - - - - -### Function `pairing_internal` - - -
fun pairing_internal<G1, G2, Gt>(g1_handle: u64, g2_handle: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `scalar_mul_internal` - - -
fun scalar_mul_internal<G, S>(element_handle: u64, scalar_handle: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `serialize_internal` - - -
fun serialize_internal<S, F>(handle: u64): vector<u8>
-
- - - - -
pragma opaque;
-
- - - - - -### Function `sqr_internal` - - -
fun sqr_internal<G>(handle: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `sub_internal` - - -
fun sub_internal<G>(handle_1: u64, handle_2: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `upcast_internal` - - -
fun upcast_internal<S, L>(handle: u64): u64
-
- - - - -
pragma opaque;
-
- - - - - -### Function `zero_internal` - - -
fun zero_internal<S>(): u64
-
- - - - -
pragma opaque;
-
- - -[move-book]: https://aptos.dev/guides/move-guides/book/SUMMARY diff --git a/aptos-move/framework/aptos-stdlib/doc/crypt_algebra.md b/aptos-move/framework/aptos-stdlib/doc/crypt_algebra.md new file mode 100644 index 0000000000000..9ff1d5650647b --- /dev/null +++ b/aptos-move/framework/aptos-stdlib/doc/crypt_algebra.md @@ -0,0 +1,1722 @@ + + + +# Module `0x1::crypt_algebra` + +This module provides generic structs/functions for operations of algebraic structures (e.g. fields and groups), +which can be used to build generic cryptographic schemes atop. +E.g., a Groth16 ZK proof verifier can be built to work over any pairing supported in this module. + +In general, every structure implements basic operations like (de)serialization, equality check, random sampling. + +A group may also implement the following operations. (Additive group notation is assumed.) +- order() for getting the group order. +- zero() for getting the group identity. +- one() for getting the group generator (if exists). +- neg() for group element inversion. +- add() for group operation (i.e., a group addition). +- sub() for group element subtraction. +- double() for efficient doubling. +- scalar_mul() for group scalar multiplication. +- multi_scalar_mul() for efficient group multi-scalar multiplication. +- hash_to() for hash-to-group. + +A field may also implement the following operations. +- zero() for getting the field additive identity. +- one() for getting the field multiplicative identity. +- add() for field addition. +- sub() for field subtraction. +- mul() for field multiplication. +- div() for field division. +- neg() for field negation. +- inv() for field inversion. +- sqr() for efficient field element squaring. +- from_u64() for quick conversion from u64 to field element. + +For 3 groups that admit a bilinear map, pairing() and multi_pairing() may be implemented. + +For a subset/superset relationship between 2 structures, upcast() and downcast() may be implemented. +E.g., in BLS12-381 pairing, since Gt is a subset of Fq12, +upcast<Gt, Fq12>() and downcast<Fq12, Gt>() will be supported. + +See algebra_*.move for currently implemented algebraic structures. + + +- [Struct `Element`](#0x1_crypt_algebra_Element) +- [Constants](#@Constants_0) +- [Function `eq`](#0x1_crypt_algebra_eq) +- [Function `from_u64`](#0x1_crypt_algebra_from_u64) +- [Function `zero`](#0x1_crypt_algebra_zero) +- [Function `one`](#0x1_crypt_algebra_one) +- [Function `neg`](#0x1_crypt_algebra_neg) +- [Function `add`](#0x1_crypt_algebra_add) +- [Function `sub`](#0x1_crypt_algebra_sub) +- [Function `mul`](#0x1_crypt_algebra_mul) +- [Function `div`](#0x1_crypt_algebra_div) +- [Function `sqr`](#0x1_crypt_algebra_sqr) +- [Function `inv`](#0x1_crypt_algebra_inv) +- [Function `double`](#0x1_crypt_algebra_double) +- [Function `multi_scalar_mul`](#0x1_crypt_algebra_multi_scalar_mul) +- [Function `scalar_mul`](#0x1_crypt_algebra_scalar_mul) +- [Function `multi_pairing`](#0x1_crypt_algebra_multi_pairing) +- [Function `pairing`](#0x1_crypt_algebra_pairing) +- [Function `deserialize`](#0x1_crypt_algebra_deserialize) +- [Function `serialize`](#0x1_crypt_algebra_serialize) +- [Function `order`](#0x1_crypt_algebra_order) +- [Function `upcast`](#0x1_crypt_algebra_upcast) +- [Function `downcast`](#0x1_crypt_algebra_downcast) +- [Function `hash_to`](#0x1_crypt_algebra_hash_to) +- [Function `abort_unless_cryptography_algebra_natives_enabled`](#0x1_crypt_algebra_abort_unless_cryptography_algebra_natives_enabled) +- [Function `handles_from_elements`](#0x1_crypt_algebra_handles_from_elements) +- [Function `add_internal`](#0x1_crypt_algebra_add_internal) +- [Function `deserialize_internal`](#0x1_crypt_algebra_deserialize_internal) +- [Function `div_internal`](#0x1_crypt_algebra_div_internal) +- [Function `double_internal`](#0x1_crypt_algebra_double_internal) +- [Function `downcast_internal`](#0x1_crypt_algebra_downcast_internal) +- [Function `from_u64_internal`](#0x1_crypt_algebra_from_u64_internal) +- [Function `eq_internal`](#0x1_crypt_algebra_eq_internal) +- [Function `hash_to_internal`](#0x1_crypt_algebra_hash_to_internal) +- [Function `inv_internal`](#0x1_crypt_algebra_inv_internal) +- [Function `mul_internal`](#0x1_crypt_algebra_mul_internal) +- [Function `multi_pairing_internal`](#0x1_crypt_algebra_multi_pairing_internal) +- [Function `multi_scalar_mul_internal`](#0x1_crypt_algebra_multi_scalar_mul_internal) +- [Function `neg_internal`](#0x1_crypt_algebra_neg_internal) +- [Function `one_internal`](#0x1_crypt_algebra_one_internal) +- [Function `order_internal`](#0x1_crypt_algebra_order_internal) +- [Function `pairing_internal`](#0x1_crypt_algebra_pairing_internal) +- [Function `scalar_mul_internal`](#0x1_crypt_algebra_scalar_mul_internal) +- [Function `serialize_internal`](#0x1_crypt_algebra_serialize_internal) +- [Function `sqr_internal`](#0x1_crypt_algebra_sqr_internal) +- [Function `sub_internal`](#0x1_crypt_algebra_sub_internal) +- [Function `upcast_internal`](#0x1_crypt_algebra_upcast_internal) +- [Function `zero_internal`](#0x1_crypt_algebra_zero_internal) +- [Specification](#@Specification_1) + - [Function `add_internal`](#@Specification_1_add_internal) + - [Function `deserialize_internal`](#@Specification_1_deserialize_internal) + - [Function `div_internal`](#@Specification_1_div_internal) + - [Function `double_internal`](#@Specification_1_double_internal) + - [Function `downcast_internal`](#@Specification_1_downcast_internal) + - [Function `from_u64_internal`](#@Specification_1_from_u64_internal) + - [Function `eq_internal`](#@Specification_1_eq_internal) + - [Function `hash_to_internal`](#@Specification_1_hash_to_internal) + - [Function `inv_internal`](#@Specification_1_inv_internal) + - [Function `mul_internal`](#@Specification_1_mul_internal) + - [Function `multi_pairing_internal`](#@Specification_1_multi_pairing_internal) + - [Function `multi_scalar_mul_internal`](#@Specification_1_multi_scalar_mul_internal) + - [Function `neg_internal`](#@Specification_1_neg_internal) + - [Function `one_internal`](#@Specification_1_one_internal) + - [Function `order_internal`](#@Specification_1_order_internal) + - [Function `pairing_internal`](#@Specification_1_pairing_internal) + - [Function `scalar_mul_internal`](#@Specification_1_scalar_mul_internal) + - [Function `serialize_internal`](#@Specification_1_serialize_internal) + - [Function `sqr_internal`](#@Specification_1_sqr_internal) + - [Function `sub_internal`](#@Specification_1_sub_internal) + - [Function `upcast_internal`](#@Specification_1_upcast_internal) + - [Function `zero_internal`](#@Specification_1_zero_internal) + + +
use 0x1::error;
+use 0x1::features;
+use 0x1::option;
+
+ + + + + +## Struct `Element` + +This struct represents an element of a structure S. + + +
struct Element<S> has copy, drop
+
+ + + +
+Fields + + +
+
+handle: u64 +
+
+ +
+
+ + +
+ + + +## Constants + + + + + + +
const E_NON_EQUAL_LENGTHS: u64 = 2;
+
+ + + + + + + +
const E_NOT_IMPLEMENTED: u64 = 1;
+
+ + + + + +## Function `eq` + +Check if x == y for elements x and y of a structure S. + + +
public fun eq<S>(x: &crypt_algebra::Element<S>, y: &crypt_algebra::Element<S>): bool
+
+ + + +
+Implementation + + +
public fun eq<S>(x: &Element<S>, y: &Element<S>): bool {
+    abort_unless_cryptography_algebra_natives_enabled();
+    eq_internal<S>(x.handle, y.handle)
+}
+
+ + + +
+ + + +## Function `from_u64` + +Convert a u64 to an element of a structure S. + + +
public fun from_u64<S>(value: u64): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun from_u64<S>(value: u64): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: from_u64_internal<S>(value)
+    }
+}
+
+ + + +
+ + + +## Function `zero` + +Return the additive identity of field S, or the identity of group S. + + +
public fun zero<S>(): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun zero<S>(): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: zero_internal<S>()
+    }
+}
+
+ + + +
+ + + +## Function `one` + +Return the multiplicative identity of field S, or a fixed generator of group S. + + +
public fun one<S>(): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun one<S>(): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: one_internal<S>()
+    }
+}
+
+ + + +
+ + + +## Function `neg` + +Compute -x for an element x of a structure S. + + +
public fun neg<S>(x: &crypt_algebra::Element<S>): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun neg<S>(x: &Element<S>): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: neg_internal<S>(x.handle)
+    }
+}
+
+ + + +
+ + + +## Function `add` + +Compute x + y for elements x and y of structure S. + + +
public fun add<S>(x: &crypt_algebra::Element<S>, y: &crypt_algebra::Element<S>): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun add<S>(x: &Element<S>, y: &Element<S>): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: add_internal<S>(x.handle, y.handle)
+    }
+}
+
+ + + +
+ + + +## Function `sub` + +Compute x - y for elements x and y of a structure S. + + +
public fun sub<S>(x: &crypt_algebra::Element<S>, y: &crypt_algebra::Element<S>): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun sub<S>(x: &Element<S>, y: &Element<S>): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: sub_internal<S>(x.handle, y.handle)
+    }
+}
+
+ + + +
+ + + +## Function `mul` + +Compute x * y for elements x and y of a structure S. + + +
public fun mul<S>(x: &crypt_algebra::Element<S>, y: &crypt_algebra::Element<S>): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun mul<S>(x: &Element<S>, y: &Element<S>): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: mul_internal<S>(x.handle, y.handle)
+    }
+}
+
+ + + +
+ + + +## Function `div` + +Try computing x / y for elements x and y of a structure S. +Return none if y does not have a multiplicative inverse in the structure S +(e.g., when S is a field, and y is zero). + + +
public fun div<S>(x: &crypt_algebra::Element<S>, y: &crypt_algebra::Element<S>): option::Option<crypt_algebra::Element<S>>
+
+ + + +
+Implementation + + +
public fun div<S>(x: &Element<S>, y: &Element<S>): Option<Element<S>> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    let (succ, handle) = div_internal<S>(x.handle, y.handle);
+    if (succ) {
+        some(Element<S> { handle })
+    } else {
+        none()
+    }
+}
+
+ + + +
+ + + +## Function `sqr` + +Compute x^2 for an element x of a structure S. Faster and cheaper than mul(x, x). + + +
public fun sqr<S>(x: &crypt_algebra::Element<S>): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun sqr<S>(x: &Element<S>): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: sqr_internal<S>(x.handle)
+    }
+}
+
+ + + +
+ + + +## Function `inv` + +Try computing x^(-1) for an element x of a structure S. +Return none if x does not have a multiplicative inverse in the structure S +(e.g., when S is a field, and x is zero). + + +
public fun inv<S>(x: &crypt_algebra::Element<S>): option::Option<crypt_algebra::Element<S>>
+
+ + + +
+Implementation + + +
public fun inv<S>(x: &Element<S>): Option<Element<S>> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    let (succeeded, handle) = inv_internal<S>(x.handle);
+    if (succeeded) {
+        let scalar = Element<S> { handle };
+        some(scalar)
+    } else {
+        none()
+    }
+}
+
+ + + +
+ + + +## Function `double` + +Compute 2*P for an element P of a structure S. Faster and cheaper than add(P, P). + + +
public fun double<S>(element_p: &crypt_algebra::Element<S>): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun double<S>(element_p: &Element<S>): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<S> {
+        handle: double_internal<S>(element_p.handle)
+    }
+}
+
+ + + +
+ + + +## Function `multi_scalar_mul` + +Compute k[0]*P[0]+...+k[n-1]*P[n-1], where +P[] are n elements of group G represented by parameter elements, and +k[] are n elements of the scalarfield S of group G represented by parameter scalars. + +Abort with code std::error::invalid_argument(E_NON_EQUAL_LENGTHS) if the sizes of elements and scalars do not match. + + +
public fun multi_scalar_mul<G, S>(elements: &vector<crypt_algebra::Element<G>>, scalars: &vector<crypt_algebra::Element<S>>): crypt_algebra::Element<G>
+
+ + + +
+Implementation + + +
public fun multi_scalar_mul<G, S>(elements: &vector<Element<G>>, scalars: &vector<Element<S>>): Element<G> {
+    let element_handles = handles_from_elements(elements);
+    let scalar_handles = handles_from_elements(scalars);
+    Element<G> {
+        handle: multi_scalar_mul_internal<G, S>(element_handles, scalar_handles)
+    }
+}
+
+ + + +
+ + + +## Function `scalar_mul` + +Compute k*P, where P is an element of a group G and k is an element of the scalar field S associated to the group G. + + +
public fun scalar_mul<G, S>(element_p: &crypt_algebra::Element<G>, scalar_k: &crypt_algebra::Element<S>): crypt_algebra::Element<G>
+
+ + + +
+Implementation + + +
public fun scalar_mul<G, S>(element_p: &Element<G>, scalar_k: &Element<S>): Element<G> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<G> {
+        handle: scalar_mul_internal<G, S>(element_p.handle, scalar_k.handle)
+    }
+}
+
+ + + +
+ + + +## Function `multi_pairing` + +Efficiently compute e(P[0],Q[0])+...+e(P[n-1],Q[n-1]), +where e: (G1,G2) -> (Gt) is the pairing function from groups (G1,G2) to group Gt, +P[] are n elements of group G1 represented by parameter g1_elements, and +Q[] are n elements of group G2 represented by parameter g2_elements. + +Abort with code std::error::invalid_argument(E_NON_EQUAL_LENGTHS) if the sizes of g1_elements and g2_elements do not match. + +NOTE: we are viewing the target group Gt of the pairing as an additive group, +rather than a multiplicative one (which is typically the case). + + +
public fun multi_pairing<G1, G2, Gt>(g1_elements: &vector<crypt_algebra::Element<G1>>, g2_elements: &vector<crypt_algebra::Element<G2>>): crypt_algebra::Element<Gt>
+
+ + + +
+Implementation + + +
public fun multi_pairing<G1,G2,Gt>(g1_elements: &vector<Element<G1>>, g2_elements: &vector<Element<G2>>): Element<Gt> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    let g1_handles = handles_from_elements(g1_elements);
+    let g2_handles = handles_from_elements(g2_elements);
+    Element<Gt> {
+        handle: multi_pairing_internal<G1,G2,Gt>(g1_handles, g2_handles)
+    }
+}
+
+ + + +
+ + + +## Function `pairing` + +Compute the pairing function (a.k.a., bilinear map) on a G1 element and a G2 element. +Return an element in the target group Gt. + + +
public fun pairing<G1, G2, Gt>(element_1: &crypt_algebra::Element<G1>, element_2: &crypt_algebra::Element<G2>): crypt_algebra::Element<Gt>
+
+ + + +
+Implementation + + +
public fun pairing<G1,G2,Gt>(element_1: &Element<G1>, element_2: &Element<G2>): Element<Gt> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<Gt> {
+        handle: pairing_internal<G1,G2,Gt>(element_1.handle, element_2.handle)
+    }
+}
+
+ + + +
+ + + +## Function `deserialize` + +Try deserializing a byte array to an element of an algebraic structure S using a given serialization format F. +Return none if the deserialization failed. + + +
public fun deserialize<S, F>(bytes: &vector<u8>): option::Option<crypt_algebra::Element<S>>
+
+ + + +
+Implementation + + +
public fun deserialize<S, F>(bytes: &vector<u8>): Option<Element<S>> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    let (succeeded, handle) = deserialize_internal<S, F>(bytes);
+    if (succeeded) {
+        some(Element<S> { handle })
+    } else {
+        none()
+    }
+}
+
+ + + +
+ + + +## Function `serialize` + +Serialize an element of an algebraic structure S to a byte array using a given serialization format F. + + +
public fun serialize<S, F>(element: &crypt_algebra::Element<S>): vector<u8>
+
+ + + +
+Implementation + + +
public fun serialize<S, F>(element: &Element<S>): vector<u8> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    serialize_internal<S, F>(element.handle)
+}
+
+ + + +
+ + + +## Function `order` + +Get the order of structure S, a big integer little-endian encoded as a byte array. + + +
public fun order<S>(): vector<u8>
+
+ + + +
+Implementation + + +
public fun order<S>(): vector<u8> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    order_internal<S>()
+}
+
+ + + +
+ + + +## Function `upcast` + +Cast an element of a structure S to a parent structure L. + + +
public fun upcast<S, L>(element: &crypt_algebra::Element<S>): crypt_algebra::Element<L>
+
+ + + +
+Implementation + + +
public fun upcast<S,L>(element: &Element<S>): Element<L> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element<L> {
+        handle: upcast_internal<S,L>(element.handle)
+    }
+}
+
+ + + +
+ + + +## Function `downcast` + +Try casting an element x of a structure L to a sub-structure S. +Return none if x is not a member of S. + +NOTE: Membership check in S is performed inside, which can be expensive, depending on the structures L and S. + + +
public fun downcast<L, S>(element_x: &crypt_algebra::Element<L>): option::Option<crypt_algebra::Element<S>>
+
+ + + +
+Implementation + + +
public fun downcast<L,S>(element_x: &Element<L>): Option<Element<S>> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    let (succ, new_handle) = downcast_internal<L,S>(element_x.handle);
+    if (succ) {
+        some(Element<S> { handle: new_handle })
+    } else {
+        none()
+    }
+}
+
+ + + +
+ + + +## Function `hash_to` + +Hash an arbitrary-length byte array msg into structure S with a domain separation tag dst +using the given hash-to-structure suite H. + +NOTE: some hashing methods do not accept a dst and will abort if a non-empty one is provided. + + +
public fun hash_to<S, H>(dst: &vector<u8>, msg: &vector<u8>): crypt_algebra::Element<S>
+
+ + + +
+Implementation + + +
public fun hash_to<S, H>(dst: &vector<u8>, msg: &vector<u8>): Element<S> {
+    abort_unless_cryptography_algebra_natives_enabled();
+    Element {
+        handle: hash_to_internal<S, H>(dst, msg)
+    }
+}
+
+ + + +
+ + + +## Function `abort_unless_cryptography_algebra_natives_enabled` + + + +
fun abort_unless_cryptography_algebra_natives_enabled()
+
+ + + +
+Implementation + + +
fun abort_unless_cryptography_algebra_natives_enabled() {
+    if (features::cryptography_algebra_enabled()) return;
+    abort(std::error::not_implemented(0))
+}
+
+ + + +
+ + + +## Function `handles_from_elements` + + + +
fun handles_from_elements<S>(elements: &vector<crypt_algebra::Element<S>>): vector<u64>
+
+ + + +
+Implementation + + +
fun handles_from_elements<S>(elements: &vector<Element<S>>): vector<u64> {
+    let num_elements = std::vector::length(elements);
+    let element_handles = std::vector::empty();
+    let i = 0;
+    while (i < num_elements) {
+        std::vector::push_back(&mut element_handles, std::vector::borrow(elements, i).handle);
+        i = i + 1;
+    };
+    element_handles
+}
+
+ + + +
+ + + +## Function `add_internal` + + + +
fun add_internal<S>(handle_1: u64, handle_2: u64): u64
+
+ + + +
+Implementation + + +
native fun add_internal<S>(handle_1: u64, handle_2: u64): u64;
+
+ + + +
+ + + +## Function `deserialize_internal` + + + +
fun deserialize_internal<S, F>(bytes: &vector<u8>): (bool, u64)
+
+ + + +
+Implementation + + +
native fun deserialize_internal<S, F>(bytes: &vector<u8>): (bool, u64);
+
+ + + +
+ + + +## Function `div_internal` + + + +
fun div_internal<F>(handle_1: u64, handle_2: u64): (bool, u64)
+
+ + + +
+Implementation + + +
native fun div_internal<F>(handle_1: u64, handle_2: u64): (bool, u64);
+
+ + + +
+ + + +## Function `double_internal` + + + +
fun double_internal<G>(element_handle: u64): u64
+
+ + + +
+Implementation + + +
native fun double_internal<G>(element_handle: u64): u64;
+
+ + + +
+ + + +## Function `downcast_internal` + + + +
fun downcast_internal<L, S>(handle: u64): (bool, u64)
+
+ + + +
+Implementation + + +
native fun downcast_internal<L,S>(handle: u64): (bool, u64);
+
+ + + +
+ + + +## Function `from_u64_internal` + + + +
fun from_u64_internal<S>(value: u64): u64
+
+ + + +
+Implementation + + +
native fun from_u64_internal<S>(value: u64): u64;
+
+ + + +
+ + + +## Function `eq_internal` + + + +
fun eq_internal<S>(handle_1: u64, handle_2: u64): bool
+
+ + + +
+Implementation + + +
native fun eq_internal<S>(handle_1: u64, handle_2: u64): bool;
+
+ + + +
+ + + +## Function `hash_to_internal` + + + +
fun hash_to_internal<S, H>(dst: &vector<u8>, bytes: &vector<u8>): u64
+
+ + + +
+Implementation + + +
native fun hash_to_internal<S, H>(dst: &vector<u8>, bytes: &vector<u8>): u64;
+
+ + + +
+ + + +## Function `inv_internal` + + + +
fun inv_internal<F>(handle: u64): (bool, u64)
+
+ + + +
+Implementation + + +
native fun inv_internal<F>(handle: u64): (bool, u64);
+
+ + + +
+ + + +## Function `mul_internal` + + + +
fun mul_internal<F>(handle_1: u64, handle_2: u64): u64
+
+ + + +
+Implementation + + +
native fun mul_internal<F>(handle_1: u64, handle_2: u64): u64;
+
+ + + +
+ + + +## Function `multi_pairing_internal` + + + +
fun multi_pairing_internal<G1, G2, Gt>(g1_handles: vector<u64>, g2_handles: vector<u64>): u64
+
+ + + +
+Implementation + + +
native fun multi_pairing_internal<G1,G2,Gt>(g1_handles: vector<u64>, g2_handles: vector<u64>): u64;
+
+ + + +
+ + + +## Function `multi_scalar_mul_internal` + + + +
fun multi_scalar_mul_internal<G, S>(element_handles: vector<u64>, scalar_handles: vector<u64>): u64
+
+ + + +
+Implementation + + +
native fun multi_scalar_mul_internal<G, S>(element_handles: vector<u64>, scalar_handles: vector<u64>): u64;
+
+ + + +
+ + + +## Function `neg_internal` + + + +
fun neg_internal<F>(handle: u64): u64
+
+ + + +
+Implementation + + +
native fun neg_internal<F>(handle: u64): u64;
+
+ + + +
+ + + +## Function `one_internal` + + + +
fun one_internal<S>(): u64
+
+ + + +
+Implementation + + +
native fun one_internal<S>(): u64;
+
+ + + +
+ + + +## Function `order_internal` + + + +
fun order_internal<G>(): vector<u8>
+
+ + + +
+Implementation + + +
native fun order_internal<G>(): vector<u8>;
+
+ + + +
+ + + +## Function `pairing_internal` + + + +
fun pairing_internal<G1, G2, Gt>(g1_handle: u64, g2_handle: u64): u64
+
+ + + +
+Implementation + + +
native fun pairing_internal<G1,G2,Gt>(g1_handle: u64, g2_handle: u64): u64;
+
+ + + +
+ + + +## Function `scalar_mul_internal` + + + +
fun scalar_mul_internal<G, S>(element_handle: u64, scalar_handle: u64): u64
+
+ + + +
+Implementation + + +
native fun scalar_mul_internal<G, S>(element_handle: u64, scalar_handle: u64): u64;
+
+ + + +
+ + + +## Function `serialize_internal` + + + +
fun serialize_internal<S, F>(handle: u64): vector<u8>
+
+ + + +
+Implementation + + +
native fun serialize_internal<S, F>(handle: u64): vector<u8>;
+
+ + + +
+ + + +## Function `sqr_internal` + + + +
fun sqr_internal<G>(handle: u64): u64
+
+ + + +
+Implementation + + +
native fun sqr_internal<G>(handle: u64): u64;
+
+ + + +
+ + + +## Function `sub_internal` + + + +
fun sub_internal<G>(handle_1: u64, handle_2: u64): u64
+
+ + + +
+Implementation + + +
native fun sub_internal<G>(handle_1: u64, handle_2: u64): u64;
+
+ + + +
+ + + +## Function `upcast_internal` + + + +
fun upcast_internal<S, L>(handle: u64): u64
+
+ + + +
+Implementation + + +
native fun upcast_internal<S,L>(handle: u64): u64;
+
+ + + +
+ + + +## Function `zero_internal` + + + +
fun zero_internal<S>(): u64
+
+ + + +
+Implementation + + +
native fun zero_internal<S>(): u64;
+
+ + + +
+ + + +## Specification + + + + +### Function `add_internal` + + +
fun add_internal<S>(handle_1: u64, handle_2: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `deserialize_internal` + + +
fun deserialize_internal<S, F>(bytes: &vector<u8>): (bool, u64)
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `div_internal` + + +
fun div_internal<F>(handle_1: u64, handle_2: u64): (bool, u64)
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `double_internal` + + +
fun double_internal<G>(element_handle: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `downcast_internal` + + +
fun downcast_internal<L, S>(handle: u64): (bool, u64)
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `from_u64_internal` + + +
fun from_u64_internal<S>(value: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `eq_internal` + + +
fun eq_internal<S>(handle_1: u64, handle_2: u64): bool
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `hash_to_internal` + + +
fun hash_to_internal<S, H>(dst: &vector<u8>, bytes: &vector<u8>): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `inv_internal` + + +
fun inv_internal<F>(handle: u64): (bool, u64)
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `mul_internal` + + +
fun mul_internal<F>(handle_1: u64, handle_2: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `multi_pairing_internal` + + +
fun multi_pairing_internal<G1, G2, Gt>(g1_handles: vector<u64>, g2_handles: vector<u64>): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `multi_scalar_mul_internal` + + +
fun multi_scalar_mul_internal<G, S>(element_handles: vector<u64>, scalar_handles: vector<u64>): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `neg_internal` + + +
fun neg_internal<F>(handle: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `one_internal` + + +
fun one_internal<S>(): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `order_internal` + + +
fun order_internal<G>(): vector<u8>
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `pairing_internal` + + +
fun pairing_internal<G1, G2, Gt>(g1_handle: u64, g2_handle: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `scalar_mul_internal` + + +
fun scalar_mul_internal<G, S>(element_handle: u64, scalar_handle: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `serialize_internal` + + +
fun serialize_internal<S, F>(handle: u64): vector<u8>
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `sqr_internal` + + +
fun sqr_internal<G>(handle: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `sub_internal` + + +
fun sub_internal<G>(handle_1: u64, handle_2: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `upcast_internal` + + +
fun upcast_internal<S, L>(handle: u64): u64
+
+ + + + +
pragma opaque;
+
+ + + + + +### Function `zero_internal` + + +
fun zero_internal<S>(): u64
+
+ + + + +
pragma opaque;
+
+ + +[move-book]: https://aptos.dev/guides/move-guides/book/SUMMARY diff --git a/aptos-move/framework/aptos-stdlib/doc/algebra_bls12381.md b/aptos-move/framework/aptos-stdlib/doc/crypt_algebra_bls12381.md similarity index 64% rename from aptos-move/framework/aptos-stdlib/doc/algebra_bls12381.md rename to aptos-move/framework/aptos-stdlib/doc/crypt_algebra_bls12381.md index 8a00bbb87043f..49f8076e161aa 100644 --- a/aptos-move/framework/aptos-stdlib/doc/algebra_bls12381.md +++ b/aptos-move/framework/aptos-stdlib/doc/crypt_algebra_bls12381.md @@ -1,17 +1,17 @@ - + -# Module `0x1::algebra_bls12381` +# Module `0x1::crypt_algebra_bls12381` This module defines marker types, constants and test cases for working with BLS12-381 curves -using the generic API defined in algebra.move. +using the generic API defined in algebra.move. See https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-pairing-friendly-curves-11#name-bls-curves-for-the-128-bit- for the full specification of BLS12-381 curves. -Currently-supported BLS12-381 structures include Fq12, Fr, G1, G2 and Gt, +Currently-supported BLS12-381 structures include Fq12, Fr, G1, G2 and Gt, along with their widely-used serialization formats, -the pairing between G1, G2 and Gt, -and the hash-to-curve operations for G1 and G2 defined in https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-16. +the pairing between G1, G2 and Gt, +and the hash-to-curve operations for G1 and G2 defined in https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-16. Other unimplemented BLS12-381 structures and serialization formats are also listed here, as they help define some of the currently supported structures. @@ -60,28 +60,28 @@ under the elliptic curve point addition. It contains the prime-order subgroup $G_2$ used in pairing. -- [Struct `Fq12`](#0x1_algebra_bls12381_Fq12) -- [Struct `FormatFq12LscLsb`](#0x1_algebra_bls12381_FormatFq12LscLsb) -- [Struct `G1`](#0x1_algebra_bls12381_G1) -- [Struct `FormatG1Uncompr`](#0x1_algebra_bls12381_FormatG1Uncompr) -- [Struct `FormatG1Compr`](#0x1_algebra_bls12381_FormatG1Compr) -- [Struct `G2`](#0x1_algebra_bls12381_G2) -- [Struct `FormatG2Uncompr`](#0x1_algebra_bls12381_FormatG2Uncompr) -- [Struct `FormatG2Compr`](#0x1_algebra_bls12381_FormatG2Compr) -- [Struct `Gt`](#0x1_algebra_bls12381_Gt) -- [Struct `FormatGt`](#0x1_algebra_bls12381_FormatGt) -- [Struct `Fr`](#0x1_algebra_bls12381_Fr) -- [Struct `FormatFrLsb`](#0x1_algebra_bls12381_FormatFrLsb) -- [Struct `FormatFrMsb`](#0x1_algebra_bls12381_FormatFrMsb) -- [Struct `HashG1XmdSha256SswuRo`](#0x1_algebra_bls12381_HashG1XmdSha256SswuRo) -- [Struct `HashG2XmdSha256SswuRo`](#0x1_algebra_bls12381_HashG2XmdSha256SswuRo) +- [Struct `Fq12`](#0x1_crypt_algebra_bls12381_Fq12) +- [Struct `FormatFq12LscLsb`](#0x1_crypt_algebra_bls12381_FormatFq12LscLsb) +- [Struct `G1`](#0x1_crypt_algebra_bls12381_G1) +- [Struct `FormatG1Uncompr`](#0x1_crypt_algebra_bls12381_FormatG1Uncompr) +- [Struct `FormatG1Compr`](#0x1_crypt_algebra_bls12381_FormatG1Compr) +- [Struct `G2`](#0x1_crypt_algebra_bls12381_G2) +- [Struct `FormatG2Uncompr`](#0x1_crypt_algebra_bls12381_FormatG2Uncompr) +- [Struct `FormatG2Compr`](#0x1_crypt_algebra_bls12381_FormatG2Compr) +- [Struct `Gt`](#0x1_crypt_algebra_bls12381_Gt) +- [Struct `FormatGt`](#0x1_crypt_algebra_bls12381_FormatGt) +- [Struct `Fr`](#0x1_crypt_algebra_bls12381_Fr) +- [Struct `FormatFrLsb`](#0x1_crypt_algebra_bls12381_FormatFrLsb) +- [Struct `FormatFrMsb`](#0x1_crypt_algebra_bls12381_FormatFrMsb) +- [Struct `HashG1XmdSha256SswuRo`](#0x1_crypt_algebra_bls12381_HashG1XmdSha256SswuRo) +- [Struct `HashG2XmdSha256SswuRo`](#0x1_crypt_algebra_bls12381_HashG2XmdSha256SswuRo)
- + ## Struct `Fq12` @@ -89,7 +89,7 @@ The finite field $F_{q^12}$ used in BLS12-381 curves, which is an extension field of Fq6 (defined in the module documentation), constructed as $F_{q^12}=F_{q^6}[w]/(w^2-v)$. -
struct Fq12
+
struct Fq12
 

 
 
@@ -110,11 +110,11 @@ which is an extension field of Fq6 (defined in the module documenta
 
 
 
-
+
 
 ## Struct `FormatFq12LscLsb`
 
-A serialization scheme for Fq12 elements,
+A serialization scheme for Fq12 elements,
 where an element $(c_0+c_1\cdot w)$ is represented by a byte array b[] of size 576,
 which is a concatenation of its coefficients serialized, with the least significant coefficient (LSC) coming first.
 - b[0..288] is $c_0$ serialized using FormatFq6LscLsb (defined in the module documentation).
@@ -123,7 +123,7 @@ which is a concatenation of its coefficients serialized, with the least signific
 NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
-
struct FormatFq12LscLsb
+
struct FormatFq12LscLsb
 

 
 
@@ -144,17 +144,17 @@ NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
 
-
+
 
 ## Struct `G1`
 
 The group $G_1$ in BLS12-381-based pairing $G_1 \times G_2 \rightarrow G_t$.
 It is a subgroup of G1Full (defined in the module documentation) with a prime order $r$
 equal to 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001.
-(so Fr is the associated scalar field).
+(so Fr is the associated scalar field).
 
 
-
struct G1
+
struct G1
 

 
 
@@ -175,21 +175,21 @@ equal to 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001.
 
 
 
-
+
 
 ## Struct `FormatG1Uncompr`
 
-A serialization scheme for G1 elements derived from
+A serialization scheme for G1 elements derived from
 https://www.ietf.org/archive/id/draft-irtf-cfrg-pairing-friendly-curves-11.html#name-zcash-serialization-format-.
 
-Below is the serialization procedure that takes a G1 element p and outputs a byte array of size 96.
+Below is the serialization procedure that takes a G1 element p and outputs a byte array of size 96.
 1. Let (x,y) be the coordinates of p if p is on the curve, or (0,0) otherwise.
 1. Serialize x and y into b_x[] and b_y[] respectively using FormatFqMsb (defined in the module documentation).
 1. Concatenate b_x[] and b_y[] into b[].
 1. If p is the point at infinity, set the infinity bit: b[0]: = b[0] | 0x40.
 1. Return b[].
 
-Below is the deserialization procedure that takes a byte array b[] and outputs either a G1 element or none.
+Below is the deserialization procedure that takes a byte array b[] and outputs either a G1 element or none.
 1. If the size of b[] is not 96, return none.
 1. Compute the compression flag as b[0] & 0x80 != 0.
 1. If the compression flag is true, return none.
@@ -204,7 +204,7 @@ Below is the deserialization procedure that takes a byte array b[]
 NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
-
struct FormatG1Uncompr
+
struct FormatG1Uncompr
 

 
 
@@ -225,14 +225,14 @@ NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
 
-
+
 
 ## Struct `FormatG1Compr`
 
-A serialization scheme for G1 elements derived from
+A serialization scheme for G1 elements derived from
 https://www.ietf.org/archive/id/draft-irtf-cfrg-pairing-friendly-curves-11.html#name-zcash-serialization-format-.
 
-Below is the serialization procedure that takes a G1 element p and outputs a byte array of size 48.
+Below is the serialization procedure that takes a G1 element p and outputs a byte array of size 48.
 1. Let (x,y) be the coordinates of p if p is on the curve, or (0,0) otherwise.
 1. Serialize x into b[] using FormatFqMsb (defined in the module documentation).
 1. Set the compression bit: b[0] := b[0] | 0x80.
@@ -240,7 +240,7 @@ Below is the serialization procedure that takes a G1 element or none.
+Below is the deserialization procedure that takes a byte array b[] and outputs either a G1 element or none.
 1. If the size of b[] is not 48, return none.
 1. Compute the compression flag as b[0] & 0x80 != 0.
 1. If the compression flag is false, return none.
@@ -256,7 +256,7 @@ Below is the deserialization procedure that takes a byte array b[]
 NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
-
struct FormatG1Compr
+
struct FormatG1Compr
 

 
 
@@ -277,17 +277,17 @@ NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
 
-
+
 
 ## Struct `G2`
 
 The group $G_2$ in BLS12-381-based pairing $G_1 \times G_2 \rightarrow G_t$.
 It is a subgroup of G2Full (defined in the module documentation) with a prime order $r$ equal to
 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001.
-(so Fr is the scalar field).
+(so Fr is the scalar field).
 
 
-
struct G2
+
struct G2
 

 
 
@@ -308,21 +308,21 @@ It is a subgroup of G2Full (defined in the module documentation) wi
 
 
 
-
+
 
 ## Struct `FormatG2Uncompr`
 
-A serialization scheme for G2 elements derived from
+A serialization scheme for G2 elements derived from
 https://www.ietf.org/archive/id/draft-irtf-cfrg-pairing-friendly-curves-11.html#name-zcash-serialization-format-.
 
-Below is the serialization procedure that takes a G2 element p and outputs a byte array of size 192.
+Below is the serialization procedure that takes a G2 element p and outputs a byte array of size 192.
 1. Let (x,y) be the coordinates of p if p is on the curve, or (0,0) otherwise.
 1. Serialize x and y into b_x[] and b_y[] respectively using FormatFq2MscMsb (defined in the module documentation).
 1. Concatenate b_x[] and b_y[] into b[].
 1. If p is the point at infinity, set the infinity bit in b[]: b[0]: = b[0] | 0x40.
 1. Return b[].
 
-Below is the deserialization procedure that takes a byte array b[] and outputs either a G2 element or none.
+Below is the deserialization procedure that takes a byte array b[] and outputs either a G2 element or none.
 1. If the size of b[] is not 192, return none.
 1. Compute the compression flag as b[0] & 0x80 != 0.
 1. If the compression flag is true, return none.
@@ -337,7 +337,7 @@ Below is the deserialization procedure that takes a byte array b[]
 NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
-
struct FormatG2Uncompr
+
struct FormatG2Uncompr
 

 
 
@@ -358,14 +358,14 @@ NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
 
-
+
 
 ## Struct `FormatG2Compr`
 
-A serialization scheme for G2 elements derived from
+A serialization scheme for G2 elements derived from
 https://www.ietf.org/archive/id/draft-irtf-cfrg-pairing-friendly-curves-11.html#name-zcash-serialization-format-.
 
-Below is the serialization procedure that takes a G2 element p and outputs a byte array of size 96.
+Below is the serialization procedure that takes a G2 element p and outputs a byte array of size 96.
 1. Let (x,y) be the coordinates of p if p is on the curve, or (0,0) otherwise.
 1. Serialize x into b[] using FormatFq2MscMsb (defined in the module documentation).
 1. Set the compression bit: b[0] := b[0] | 0x80.
@@ -373,7 +373,7 @@ Below is the serialization procedure that takes a G2 element or none.
+Below is the deserialization procedure that takes a byte array b[] and outputs either a G2 element or none.
 1. If the size of b[] is not 96, return none.
 1. Compute the compression flag as b[0] & 0x80 != 0.
 1. If the compression flag is false, return none.
@@ -389,7 +389,7 @@ Below is the deserialization procedure that takes a byte array b[]
 NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
-
struct FormatG2Compr
+
struct FormatG2Compr
 

 
 
@@ -410,18 +410,18 @@ NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
 
-
+
 
 ## Struct `Gt`
 
 The group $G_t$ in BLS12-381-based pairing $G_1 \times G_2 \rightarrow G_t$.
-It is a multiplicative subgroup of Fq12,
+It is a multiplicative subgroup of Fq12,
 with a prime order $r$ equal to 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001.
-(so Fr is the scalar field).
-The identity of Gt is 1.
+(so Fr is the scalar field).
+The identity of Gt is 1.
 
 
-
struct Gt
+
struct Gt
 

 
 
@@ -442,20 +442,20 @@ The identity of Gt
 
-
+
 
 ## Struct `FormatGt`
 
-A serialization scheme for Gt elements.
+A serialization scheme for Gt elements.
 
-To serialize, it treats a Gt element p as an Fq12 element and serialize it using FormatFq12LscLsb.
+To serialize, it treats a Gt element p as an Fq12 element and serialize it using FormatFq12LscLsb.
 
-To deserialize, it uses FormatFq12LscLsb to try deserializing to an Fq12 element then test the membership in Gt.
+To deserialize, it uses FormatFq12LscLsb to try deserializing to an Fq12 element then test the membership in Gt.
 
 NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
-
struct FormatGt
+
struct FormatGt
 

 
 
@@ -476,7 +476,7 @@ NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0.
 
 
 
-
+
 
 ## Struct `Fr`
 
@@ -484,7 +484,7 @@ The finite field $F_r$ that can be used as the scalar fields
 associated with the groups $G_1$, $G_2$, $G_t$ in BLS12-381-based pairing.
 
 
-
struct Fr
+
struct Fr
 

 
 
@@ -505,17 +505,17 @@ associated with the groups $G_1$, $G_2$, $G_t$ in BLS12-381-based pairing.
 
 
 
-
+
 
 ## Struct `FormatFrLsb`
 
-A serialization format for Fr elements,
+A serialization format for Fr elements,
 where an element is represented by a byte array b[] of size 32 with the least significant byte (LSB) coming first.
 
 NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0, blst-0.3.7.
 
 
-
struct FormatFrLsb
+
struct FormatFrLsb
 

 
 
@@ -536,17 +536,17 @@ NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0, blst-0.3.7
 
 
 
-
+
 
 ## Struct `FormatFrMsb`
 
-A serialization scheme for Fr elements,
+A serialization scheme for Fr elements,
 where an element is represented by a byte array b[] of size 32 with the most significant byte (MSB) coming first.
 
 NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0, blst-0.3.7.
 
 
-
struct FormatFrMsb
+
struct FormatFrMsb
 

 
 
@@ -567,16 +567,16 @@ NOTE: other implementation(s) using this format: ark-bls12-381-0.4.0, blst-0.3.7
 
 
 
-
+
 
 ## Struct `HashG1XmdSha256SswuRo`
 
-The hash-to-curve suite BLS12381G1_XMD:SHA-256_SSWU_RO_ that hashes a byte array into G1 elements.
+The hash-to-curve suite BLS12381G1_XMD:SHA-256_SSWU_RO_ that hashes a byte array into G1 elements.
 
 Full specification is defined in https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-16#name-bls12-381-g1.
 
 
-
struct HashG1XmdSha256SswuRo
+
struct HashG1XmdSha256SswuRo
 

 
 
@@ -597,16 +597,16 @@ Full specification is defined in https://datatracker.ietf.org/doc/html/draft-irt
 
 
 
-
+
 
 ## Struct `HashG2XmdSha256SswuRo`
 
-The hash-to-curve suite BLS12381G2_XMD:SHA-256_SSWU_RO_ that hashes a byte array into G2 elements.
+The hash-to-curve suite BLS12381G2_XMD:SHA-256_SSWU_RO_ that hashes a byte array into G2 elements.
 
 Full specification is defined in https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-16#name-bls12-381-g2.
 
 
-
struct HashG2XmdSha256SswuRo
+
struct HashG2XmdSha256SswuRo
 

 
 
diff --git a/aptos-move/framework/aptos-stdlib/doc/overview.md b/aptos-move/framework/aptos-stdlib/doc/overview.md
index e056a60f1981a..e735b00215442 100644
--- a/aptos-move/framework/aptos-stdlib/doc/overview.md
+++ b/aptos-move/framework/aptos-stdlib/doc/overview.md
@@ -12,8 +12,6 @@ This is the reference documentation of the Aptos standard library.
 ## Index
 
 
--  [`0x1::algebra`](algebra.md#0x1_algebra)
--  [`0x1::algebra_bls12381`](algebra_bls12381.md#0x1_algebra_bls12381)
 -  [`0x1::any`](any.md#0x1_any)
 -  [`0x1::aptos_hash`](hash.md#0x1_aptos_hash)
 -  [`0x1::big_vector`](big_vector.md#0x1_big_vector)
@@ -21,6 +19,8 @@ This is the reference documentation of the Aptos standard library.
 -  [`0x1::capability`](capability.md#0x1_capability)
 -  [`0x1::comparator`](comparator.md#0x1_comparator)
 -  [`0x1::copyable_any`](copyable_any.md#0x1_copyable_any)
+-  [`0x1::crypt_algebra`](crypt_algebra.md#0x1_crypt_algebra)
+-  [`0x1::crypt_algebra_bls12381`](crypt_algebra_bls12381.md#0x1_crypt_algebra_bls12381)
 -  [`0x1::debug`](debug.md#0x1_debug)
 -  [`0x1::ed25519`](ed25519.md#0x1_ed25519)
 -  [`0x1::fixed_point64`](fixed_point64.md#0x1_fixed_point64)
diff --git a/aptos-move/framework/aptos-stdlib/sources/cryptography/algebra.move b/aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra.move
similarity index 99%
rename from aptos-move/framework/aptos-stdlib/sources/cryptography/algebra.move
rename to aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra.move
index 09d468cac55e7..628e6efced7c7 100644
--- a/aptos-move/framework/aptos-stdlib/sources/cryptography/algebra.move
+++ b/aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra.move
@@ -35,7 +35,7 @@
 /// `upcast()` and `downcast()` will be supported.
 ///
 /// See `algebra_*.move` for currently implemented algebraic structures.
-module aptos_std::algebra {
+module aptos_std::crypt_algebra {
     use std::option::{Option, some, none};
     use std::features;
 
diff --git a/aptos-move/framework/aptos-stdlib/sources/cryptography/algebra.spec.move b/aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra.spec.move
similarity index 98%
rename from aptos-move/framework/aptos-stdlib/sources/cryptography/algebra.spec.move
rename to aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra.spec.move
index dc8902a4a5cc0..bf9fb1d4bebd2 100644
--- a/aptos-move/framework/aptos-stdlib/sources/cryptography/algebra.spec.move
+++ b/aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra.spec.move
@@ -1,4 +1,4 @@
-spec aptos_std::algebra {
+spec aptos_std::crypt_algebra {
     spec add_internal(handle_1: u64, handle_2: u64): u64 {
         pragma opaque;
     }
diff --git a/aptos-move/framework/aptos-stdlib/sources/cryptography/algebra_bls12381.move b/aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra_bls12381.move
similarity index 99%
rename from aptos-move/framework/aptos-stdlib/sources/cryptography/algebra_bls12381.move
rename to aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra_bls12381.move
index 781c92a5fd5b7..61613ffc5ebae 100644
--- a/aptos-move/framework/aptos-stdlib/sources/cryptography/algebra_bls12381.move
+++ b/aptos-move/framework/aptos-stdlib/sources/cryptography/crypt_algebra_bls12381.move
@@ -53,7 +53,7 @@
 /// `G2Full`: a group constructed by the points on a curve $E'(F_{q^2}): y^2=x^3+4(u+1)$ and the point at infinity,
 /// under the elliptic curve point addition.
 /// It contains the prime-order subgroup $G_2$ used in pairing.
-module aptos_std::algebra_bls12381 {
+module aptos_std::crypt_algebra_bls12381 {
     //
     // Marker types + serialization formats begin.
     //
@@ -627,7 +627,7 @@ module aptos_std::algebra_bls12381 {
     }
 
     #[test_only]
-    use aptos_std::algebra::{zero, one, from_u64, eq, deserialize, serialize, neg, add, sub, mul, div, inv, rand_insecure, sqr, order, scalar_mul, multi_scalar_mul, double, hash_to, upcast, enable_cryptography_algebra_natives, pairing, multi_pairing, downcast, Element};
+    use aptos_std::crypt_algebra::{zero, one, from_u64, eq, deserialize, serialize, neg, add, sub, mul, div, inv, rand_insecure, sqr, order, scalar_mul, multi_scalar_mul, double, hash_to, upcast, enable_cryptography_algebra_natives, pairing, multi_pairing, downcast, Element};
 
     #[test_only]
     const FR_VAL_0_SERIALIZED_LSB: vector = x"0000000000000000000000000000000000000000000000000000000000000000";
@@ -753,7 +753,7 @@ module aptos_std::algebra_bls12381 {
     }
 
     #[test(fx = @std)]
-    #[expected_failure(abort_code = 0x010002, location = aptos_std::algebra)]
+    #[expected_failure(abort_code = 0x010002, location = aptos_std::crypt_algebra)]
     fun test_multi_pairing_should_abort_when_sizes_mismatch(fx: signer) {
         enable_cryptography_algebra_natives(&fx);
         let g1_elements = vector[rand_insecure()];
@@ -762,7 +762,7 @@ module aptos_std::algebra_bls12381 {
     }
 
     #[test(fx = @std)]
-    #[expected_failure(abort_code = 0x010002, location = aptos_std::algebra)]
+    #[expected_failure(abort_code = 0x010002, location = aptos_std::crypt_algebra)]
     fun test_multi_scalar_mul_should_abort_when_sizes_mismatch(fx: signer) {
         enable_cryptography_algebra_natives(&fx);
         let elements = vector[rand_insecure()];
diff --git a/aptos-move/framework/src/natives/cryptography/algebra/mod.rs b/aptos-move/framework/src/natives/cryptography/algebra/mod.rs
index 22e394b48ebea..75dd50c5892b6 100644
--- a/aptos-move/framework/src/natives/cryptography/algebra/mod.rs
+++ b/aptos-move/framework/src/natives/cryptography/algebra/mod.rs
@@ -71,11 +71,11 @@ impl TryFrom for Structure {
 
     fn try_from(value: TypeTag) -> Result {
         match value.to_string().as_str() {
-            "0x1::algebra_bls12381::Fr" => Ok(Structure::BLS12381Fr),
-            "0x1::algebra_bls12381::Fq12" => Ok(Structure::BLS12381Fq12),
-            "0x1::algebra_bls12381::G1" => Ok(Structure::BLS12381G1),
-            "0x1::algebra_bls12381::G2" => Ok(Structure::BLS12381G2),
-            "0x1::algebra_bls12381::Gt" => Ok(Structure::BLS12381Gt),
+            "0x1::crypt_algebra_bls12381::Fr" => Ok(Structure::BLS12381Fr),
+            "0x1::crypt_algebra_bls12381::Fq12" => Ok(Structure::BLS12381Fq12),
+            "0x1::crypt_algebra_bls12381::G1" => Ok(Structure::BLS12381G1),
+            "0x1::crypt_algebra_bls12381::G2" => Ok(Structure::BLS12381G2),
+            "0x1::crypt_algebra_bls12381::Gt" => Ok(Structure::BLS12381Gt),
             _ => Err(()),
         }
     }
@@ -107,20 +107,20 @@ impl TryFrom for SerializationFormat {
 
     fn try_from(value: TypeTag) -> Result {
         match value.to_string().as_str() {
-            "0x1::algebra_bls12381::FormatFq12LscLsb" => {
+            "0x1::crypt_algebra_bls12381::FormatFq12LscLsb" => {
                 Ok(SerializationFormat::BLS12381Fq12LscLsb)
             },
-            "0x1::algebra_bls12381::FormatG1Uncompr" => {
+            "0x1::crypt_algebra_bls12381::FormatG1Uncompr" => {
                 Ok(SerializationFormat::BLS12381G1Uncompressed)
             },
-            "0x1::algebra_bls12381::FormatG1Compr" => Ok(SerializationFormat::BLS12381G1Compressed),
-            "0x1::algebra_bls12381::FormatG2Uncompr" => {
+            "0x1::crypt_algebra_bls12381::FormatG1Compr" => Ok(SerializationFormat::BLS12381G1Compressed),
+            "0x1::crypt_algebra_bls12381::FormatG2Uncompr" => {
                 Ok(SerializationFormat::BLS12381G2Uncompressed)
             },
-            "0x1::algebra_bls12381::FormatG2Compr" => Ok(SerializationFormat::BLS12381G2Compressed),
-            "0x1::algebra_bls12381::FormatGt" => Ok(SerializationFormat::BLS12381Gt),
-            "0x1::algebra_bls12381::FormatFrLsb" => Ok(SerializationFormat::BLS12381FrLsb),
-            "0x1::algebra_bls12381::FormatFrMsb" => Ok(SerializationFormat::BLS12381FrMsb),
+            "0x1::crypt_algebra_bls12381::FormatG2Compr" => Ok(SerializationFormat::BLS12381G2Compressed),
+            "0x1::crypt_algebra_bls12381::FormatGt" => Ok(SerializationFormat::BLS12381Gt),
+            "0x1::crypt_algebra_bls12381::FormatFrLsb" => Ok(SerializationFormat::BLS12381FrLsb),
+            "0x1::crypt_algebra_bls12381::FormatFrMsb" => Ok(SerializationFormat::BLS12381FrMsb),
             _ => Err(()),
         }
     }
@@ -138,10 +138,10 @@ impl TryFrom for HashToStructureSuite {
 
     fn try_from(value: TypeTag) -> Result {
         match value.to_string().as_str() {
-            "0x1::algebra_bls12381::HashG1XmdSha256SswuRo" => {
+            "0x1::crypt_algebra_bls12381::HashG1XmdSha256SswuRo" => {
                 Ok(HashToStructureSuite::Bls12381g1XmdSha256SswuRo)
             },
-            "0x1::algebra_bls12381::HashG2XmdSha256SswuRo" => {
+            "0x1::crypt_algebra_bls12381::HashG2XmdSha256SswuRo" => {
                 Ok(HashToStructureSuite::Bls12381g2XmdSha256SswuRo)
             },
             _ => Err(()),
diff --git a/aptos-move/framework/src/natives/mod.rs b/aptos-move/framework/src/natives/mod.rs
index 490ca001f3a30..0a76b3b88f2e1 100644
--- a/aptos-move/framework/src/natives/mod.rs
+++ b/aptos-move/framework/src/natives/mod.rs
@@ -305,7 +305,7 @@ pub fn all_natives(
         )
     );
     add_natives_from_module!(
-        "algebra",
+        "crypt_algebra",
         cryptography::algebra::make_all(
             gas_params.algebra.clone(),
             sha256_gas_params,
diff --git a/aptos-move/move-examples/groth16_example/sources/groth16.move b/aptos-move/move-examples/groth16_example/sources/groth16.move
index 13fc9fd1c998f..0e246df0281dc 100644
--- a/aptos-move/move-examples/groth16_example/sources/groth16.move
+++ b/aptos-move/move-examples/groth16_example/sources/groth16.move
@@ -2,7 +2,7 @@
 /// Actual proof verifiers can be constructed using the pairings supported in the generic algebra module.
 /// See the test cases in this module for an example of constructing with BLS12-381 curves.
 module groth16_example::groth16 {
-    use aptos_std::algebra::{Element, from_u64, multi_scalar_mul, eq, multi_pairing, upcast, pairing, add, zero};
+    use aptos_std::crypt_algebra::{Element, from_u64, multi_scalar_mul, eq, multi_pairing, upcast, pairing, add, zero};
 
     /// Proof verification as specified in the original paper,
     /// with the following input (in the original paper notations).
@@ -77,9 +77,9 @@ module groth16_example::groth16 {
     }
 
     #[test_only]
-    use aptos_std::algebra::{deserialize, enable_cryptography_algebra_natives};
+    use aptos_std::crypt_algebra::{deserialize, enable_cryptography_algebra_natives};
     #[test_only]
-    use aptos_std::algebra_bls12381::{Fr, FormatFrLsb, FormatG1Compr, FormatG2Compr, FormatFq12LscLsb, G1, G2, Gt, Fq12, FormatGt};
+    use aptos_std::crypt_algebra_bls12381::{Fr, FormatFrLsb, FormatG1Compr, FormatG2Compr, FormatFq12LscLsb, G1, G2, Gt, Fq12, FormatGt};
 
     #[test(fx = @std)]
     fun test_verify_proof_with_bls12381(fx: signer) {