feat: export pre-defined bignum types (#125)

Co-authored-by: Tom French <[email protected]>

Author: iAmMichaelConnor

README.md

@@ -15,15 +15,29 @@ bignum can evaluate large integer arithmetic by defining a modulus() that is a p
 
 ## High level overview
 
-This library provides modular arithmetic operations for big numbers. The Noir std library provides integers up to 128 bits and a field type up to 254 bits; this library supports arbitrary length numbers. 
+This library provides modular arithmetic operations for big numbers. The Noir std library provides integers up to 128 bits and a field type up to 254 bits; this library supports arbitrary length numbers.
+
+A number of pre-defined bignum and finite field types are provided. If you need a bignum or finite field that's not on this list, this repo also provides the tools you'll need to generate your own.
+
+See `./src/lib.nr` for the list of exported bignums.
+
+See `./src/fields/` for files which shows how those bignums were created; you can copy this approach to generate your own bignums.
 
 More details about this library are described in the rest of this document, this is just a quick high level overview. 
 
-To start using the library you need to do 2 things:
+To start using the library:
+
+If the bignum you need is in the pre-defined list, import it and use it:
+
+```rust
+use dep::bignum::U256;
+```
+
+If the bignum you need is not in the pre-defined list, you'll need to create it:
 1. Define or import a **parameter set** with info about your modulus
 2. Define the correct **type** for your big number
 
-For step 1, the library contains parameters for predefined fields or integer types. Otherwise, you can define your own parameters; instructions on how to do this can be found below.
+Instructions on how to do this can be found below.
 
 Step 2 depends on when you know your modulus; this can be either at compile-time or runtime. Use the correct type for your situation:
 * `BigNum`, if modulus is known at compile-time
@@ -48,34 +62,45 @@ In your _Nargo.toml_ file, add the version of this library you would like to ins
 bignum = { tag = "v0.4.2", git = "https://github.com/noir-lang/noir-bignum" }
 ```
 
-### Import
+### Import a pre-defined bignum:
 
 Add imports at the top of your Noir code, for example:
 
 ```rust
-use bignum::fields::U256::U256Params;
-use bignum::BigNum;
+use dep::bignum::U256;
 ```
-### Quick example: Addition in U256
 
-A simple 1 + 2 = 3 check in 256-bit unsigned integers. Note that for performing multiple arithmetic operations up to degree 2 it is recommended to use `evaluate_quadratic_expression` (see explanation below). 
+### Create a custom bignum:
 
-```rust
+> We use U256 as an illustrative example, even though it's actually a pre-defined bignum.
+
+Use the paramgen tool to generate your bignum's params (see below). Then define your custom bignum from those params:
 
-use bignum::fields::U256::U256Params;
-use bignum::BigNum;
+```rust
+use dep::bignum::fields::U256::U256Params;
+use dep::bignum::BigNum;
 
 // Define (compile-time) BigNum type
 // number of limbs, number of bits of modulus, parameter set
 type U256 = BigNum<3, 257, U256Params>;
+```
+
+### Quick example: Addition in U256
+
+A simple 1 + 2 = 3 check in 256-bit unsigned integers. Note that for performing multiple arithmetic operations up to degree 2 it is recommended to use `evaluate_quadratic_expression` (see explanation below). 
+
+```rust
+use dep::bignum::U256;
 
 fn main() {
-    let one: U256 = BigNum::from_slice([1, 0, 0]);
-    let two: U256 = BigNum::from_slice([2, 0, 0]);
-    let three: U256 = BigNum::from_slice([3, 0, 0]);
+    let one = U256::from_slice([1, 0, 0]);
+    let two = U256::from_slice([2, 0, 0]);
+    let three = U256::from_slice([3, 0, 0]);
     assert((one + two) == three);
 }
 ```
+
+
 ## Types
 
 ### `BigNum` / `RuntimeBigNum` definition

src/fields/U1024.nr

@@ -1,15 +1,18 @@
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
 pub struct U1024Params {}
 
+pub type U1024 = BigNum<9, 1025, U1024Params>;
+
 impl BigNumParamsGetter<9, 1025> for U1024Params {
     fn get_params() -> BigNumParams<9, 1025> {
         U1024_PARAMS
     }
 }
 
-global U1024_PARAMS: BigNumParams<9, 1025> = BigNumParams {
+pub global U1024_PARAMS: BigNumParams<9, 1025> = BigNumParams {
     has_multiplicative_inverse: false,
     modulus: [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x010000000000000000],
     double_modulus: [

src/fields/U2048.nr

@@ -1,15 +1,18 @@
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
 pub struct U2048Params {}
 
+pub type U2048 = BigNum<18, 2049, U2048Params>;
+
 impl BigNumParamsGetter<18, 2049> for U2048Params {
     fn get_params() -> BigNumParams<18, 2049> {
         U2048_PARAMS
     }
 }
 
-global U2048_PARAMS: BigNumParams<18, 2049> = BigNumParams {
+pub global U2048_PARAMS: BigNumParams<18, 2049> = BigNumParams {
     has_multiplicative_inverse: false,
     modulus: [
         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,

src/fields/U256.nr

@@ -1,15 +1,18 @@
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
 pub struct U256Params {}
 
+pub type U256 = BigNum<3, 257, U256Params>;
+
 impl BigNumParamsGetter<3, 257> for U256Params {
     fn get_params() -> BigNumParams<3, 257> {
         U256_PARAMS
     }
 }
 
-global U256_PARAMS: BigNumParams<3, 257> = BigNumParams {
+pub global U256_PARAMS: BigNumParams<3, 257> = BigNumParams {
     has_multiplicative_inverse: false,
     modulus: [0x00, 0x00, 0x010000],
     double_modulus: [

src/fields/U384.nr

@@ -1,15 +1,18 @@
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
-pub struct U384_Params {}
+pub struct U384Params {}
 
-impl BigNumParamsGetter<4, 385> for U384_Params {
+pub type U384 = BigNum<4, 385, U384Params>;
+
+impl BigNumParamsGetter<4, 385> for U384Params {
     fn get_params() -> BigNumParams<4, 385> {
         U384_PARAMS
     }
 }
 
-global U384_PARAMS: BigNumParams<4, 385> = BigNumParams {
+pub global U384_PARAMS: BigNumParams<4, 385> = BigNumParams {
     has_multiplicative_inverse: false,
     modulus: [0x00, 0x00, 0x00, 0x01000000],
     double_modulus: [

src/fields/U4096.nr

@@ -1,15 +1,18 @@
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
 pub struct U4096Params {}
 
+pub type U4096 = BigNum<35, 4097, U4096Params>;
+
 impl BigNumParamsGetter<35, 4097> for U4096Params {
     fn get_params() -> BigNumParams<35, 4097> {
         U4096_PARAMS
     }
 }
 
-global U4096_PARAMS: BigNumParams<35, 4097> = BigNumParams {
+pub global U4096_PARAMS: BigNumParams<35, 4097> = BigNumParams {
     has_multiplicative_inverse: false,
     modulus: [
         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,

src/fields/U512.nr

@@ -1,15 +1,18 @@
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
 pub struct U512Params {}
 
+pub type U512 = BigNum<5, 513, U512Params>;
+
 impl BigNumParamsGetter<5, 513> for U512Params {
     fn get_params() -> BigNumParams<5, 513> {
         U512_PARAMS
     }
 }
 
-global U512_PARAMS: BigNumParams<5, 513> = BigNumParams {
+pub global U512_PARAMS: BigNumParams<5, 513> = BigNumParams {
     has_multiplicative_inverse: false,
     modulus: [0x00, 0x00, 0x00, 0x00, 0x0100000000],
     double_modulus: [

src/fields/U768.nr

@@ -1,15 +1,18 @@
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
 pub struct U768Params {}
 
+pub type U768 = BigNum<7, 769, U768Params>;
+
 impl BigNumParamsGetter<7, 769> for U768Params {
     fn get_params() -> BigNumParams<7, 769> {
         U768_PARAMS
     }
 }
 
-global U768_PARAMS: BigNumParams<7, 769> = BigNumParams {
+pub global U768_PARAMS: BigNumParams<7, 769> = BigNumParams {
     has_multiplicative_inverse: false,
     modulus: [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01000000000000],
     double_modulus: [

src/fields/U8192.nr

@@ -1,8 +1,11 @@
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
 pub struct U8192Params {}
 
+pub type U8192 = BigNum<35, 4097, U8192Params>;
+
 impl BigNumParamsGetter<69, 8193> for U8192Params {
     fn get_params() -> BigNumParams<69, 8193> {
         U8192_PARAMS

src/fields/bls12_377Fq.nr

@@ -16,11 +16,14 @@
 //! * G1 curve equation: y^2 = x^3 + 1
 //! * G2 curve equation: y^2 = x^3 + B, where
 //!    * B = Fq2(0, 155198655607781456406391640216936120121836107652948796323930557600032281009004493664981332883744016074664192874906)
+use crate::bignum::BigNum;
 use crate::params::BigNumParams;
 use crate::params::BigNumParamsGetter;
 
 pub struct BLS12_377_Fq_Params {}
 
+pub type BLS12_377_Fq = BigNum<4, 377, BLS12_377_Fq_Params>;
+
 impl BigNumParamsGetter<4, 377> for BLS12_377_Fq_Params {
     fn get_params() -> BigNumParams<4, 377> {
         BLS12_377_Fq_PARAMS