add a Math.inv function that inverse a number in Z/nZ

contracts/utils/math/Math.sol

@@ -218,6 +218,33 @@ library Math {
         return result;
     }
 
+    /**
+     * @notice Calculate the inverse of a in Z/nZ.
+     *
+     * If p is a prime, then we Z/nZ is a field commonly noted Fp. In that case all elements are inversible, expect 0.
+     * If p is not a prime, then Z/nZ is not a field, and some elements might not be inversible.
+     *
+     * When trying to inverse a value that is not invesible, 0 is returned.
+     */
+    function inv(uint256 a, uint256 p) internal pure returns (uint256) {
+        uint256 r1 = a % p;
+        if (r1 == 0) return 0;
+        uint256 r2 = p;
+        uint256 t1 = 0;
+        uint256 t2 = 1;
+        while (r1 != 0) {
+            uint256 q = r2 / r1;
+            (t1, t2, r2, r1) = (
+                t2,
+                addmod(t1, uint256(p - mulmod(t2, q, p)), p),
+                r1,
+                addmod(r2, uint256(p - mulmod(r1, q, p)), p)
+            );
+        }
+        if (r2 != 1) return 0;
+        return t1;
+    }
+
     /**
      * @dev Returns the square root of a number. If the number is not a perfect square, the value is rounded
      * towards zero.

test/utils/math/Math.t.sol

@@ -55,6 +55,31 @@ contract MathTest is Test {
         return value * value < ref;
     }
 
+    // INV
+    function testInv(uint256 seed) public {
+        uint256 p;
+        uint256 value;
+        uint256 inverse;
+
+        // 17 is a prime
+        p = 17;
+        value = bound(seed, 1, p - 1);
+        inverse = Math.inv(value, p);
+        assertEq(mulmod(value, inverse, p), 1);
+
+        // 65537 is a prime
+        p = 65537;
+        value = bound(seed, 1, p - 1);
+        inverse = Math.inv(value, p);
+        assertEq(mulmod(value, inverse, p), 1);
+
+        // 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff is a prime
+        p = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff;
+        value = bound(seed, 1, p - 1);
+        inverse = Math.inv(value, p);
+        assertEq(mulmod(value, inverse, p), 1);
+    }
+
     // LOG2
     function testLog2(uint256 input, uint8 r) public {
         Math.Rounding rounding = _asRounding(r);

test/utils/math/Math.test.js

@@ -5,6 +5,7 @@ const { PANIC_CODES } = require('@nomicfoundation/hardhat-chai-matchers/panic');
 
 const { Rounding } = require('../../helpers/enums');
 const { min, max } = require('../../helpers/math');
+const { randomArray, generators } = require('../../helpers/random');
 
 const RoundingDown = [Rounding.Floor, Rounding.Trunc];
 const RoundingUp = [Rounding.Ceil, Rounding.Expand];
@@ -298,6 +299,41 @@ describe('Math', function () {
     });
   });
 
+  describe.only('inv', function () {
+    for (const factors of [
+      [17n],
+      [65537n],
+      [0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn],
+      [3n, 5n],
+      [3n, 7n],
+      [47n, 53n],
+    ]) {
+      const p = factors.reduce((acc, f) => acc * f, 1n);
+
+      describe(`using p=${p} which is ${factors.length > 1 ? 'not ' : ''}a prime`, function () {
+        it('trying to inverse 0 reverts', async function () {
+          expect(await this.mock.$inv(0, p)).to.equal(0n);
+        });
+
+        it('trying to inverse p reverts', async function () {
+          expect(await this.mock.$inv(p, p)).to.equal(0n);
+        });
+
+        for (const value of randomArray(generators.uint256, 16)) {
+          const isInversible = factors.every(f => value % f);
+          it(`tring to inverse ${value}`, async function () {
+            const result = await this.mock.$inv(value, p);
+            if (isInversible) {
+              expect((value * result) % p).to.equal(1n);
+            } else {
+              expect(result).to.equal(0n);
+            }
+          });
+        }
+      });
+    }
+  });
+
   describe('sqrt', function () {
     it('rounds down', async function () {
       for (const rounding of RoundingDown) {