chore: document big integers

docs/.markdownlint.json

@@ -0,0 +1,3 @@
+{
+    "no-missing-space-atx": false
+}

docs/docs/noir/standard_library/bigint.md

@@ -0,0 +1,105 @@
+---
+title: Big Integers
+description: How to use big integers from Noir standard library
+keywords:
+  [
+    Big Integer,
+    Noir programming language,
+    Noir libraries,
+  ]
+---
+
+The BigInt module in the standard library exposes some class of integers which do not fit (well) into a Noir native field. It implements modulo arithmetic, modulo a 'big' prime number.
+Currently only 6 class of integers (i.e 'big' prime numbers) are available throughout the module, namely:
+
+- BN254 Fq: Bn254Fq
+- BN254 Fr: Bn254Fr
+- Secp256k1 Fq: Secpk1Fq
+- Secp256k1 Fr: Secpk1Fr
+- Secp256r1 Fr: Secpr1Fr
+- Secp256r1 Fq: Secpr1Fq
+
+Where XXX Fq and XXX Fr denote respectively the order of the base and scalar field of the (usual) elliptic curve XXX.
+For instance the big integer 'Secpk1Fq' in the standard library refers to integers modulo $2^{256}-2^{32}-977$.
+
+Feel free to explore the source code for the other primes:
+
+#include_code curve_order_base noir_stdlib/src/bigint.nr rust
+
+## Example usage
+
+A common use-case is when constructing a big integer from its bytes representation, and performing arithmetic operations on it:
+
+```rust
+use dep::std::{bigint::Secpk1Fq, println};
+
+fn main() {
+ let a = Secpk1Fq::from_le_bytes([x, y, 0, 45, 2]);
+ let b = Secpk1Fq::from_le_bytes([y, x, 9]);
+ let c = (a + b)*b/a;
+ let d = c.to_le_bytes();
+ println(d[0]);
+}
+```
+
+## Methods
+
+The available operations for each big integer are:
+
+### from_le_bytes
+
+Construct a big integer from its little-endian bytes representation. Example:
+
+```rust
+ let a = Secpk1Fq::from_le_bytes([x, y, 0, 45, 2]);
+ ```
+
+Sure, here's the formatted version of the remaining methods:
+
+### to_le_bytes
+
+Return the little-endian bytes representation of a big integer. Example:
+
+```rust
+let bytes = a.to_le_bytes();
+```
+
+### add
+
+Add two big integers. Example:
+
+```rust
+let sum = a + b;
+```
+
+### sub
+
+Subtract two big integers. Example:
+
+```rust
+let difference = a - b;
+```
+
+### mul
+
+Multiply two big integers. Example:
+
+```rust
+let product = a * b;
+```
+
+### div
+
+Divide two big integers. Note that division is field division and not euclidean division. Example:
+
+```rust
+let quotient = a / b;
+```
+
+### eq
+
+Compare two big integers. Example:
+
+```rust
+let are_equal = a == b;
+```

noir_stdlib/src/bigint.nr

@@ -1,6 +1,7 @@
 use crate::ops::{Add, Sub, Mul, Div};
 use crate::cmp::Eq;
 
+// docs:start:curve_order_base
 global bn254_fq = [0x47, 0xFD, 0x7C, 0xD8, 0x16, 0x8C, 0x20, 0x3C, 0x8d, 0xca, 0x71, 0x68, 0x91, 0x6a, 0x81, 0x97,
                    0x5d, 0x58, 0x81, 0x81, 0xb6, 0x45, 0x50, 0xb8, 0x29, 0xa0, 0x31, 0xe1, 0x72, 0x4e, 0x64, 0x30];
 global bn254_fr = [0x01, 0x00, 0x00, 0x00, 0x3F, 0x59, 0x1F, 0x43, 0x09, 0x97, 0xB9, 0x79, 0x48, 0xE8, 0x33, 0x28, 
@@ -13,6 +14,7 @@ global secpr1_fq = [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
                     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF];
 global secpr1_fr = [0x51, 0x25, 0x63, 0xFC, 0xC2, 0xCA, 0xB9, 0xF3, 0x84, 0x9E, 0x17, 0xA7, 0xAD, 0xFA, 0xE6, 0xBC,
                     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00,0xFF, 0xFF, 0xFF, 0xFF];
+// docs:end:curve_order_base
 
 struct BigInt {
     pointer: u32,