add gadgets to API surface, UInt32, UInt64, implement rot32

src/examples/zkprogram/gadgets.ts

@@ -3,8 +3,8 @@ import { Field, Provable, Gadgets, ZkProgram } from 'o1js';
 let cs = Provable.constraintSystem(() => {
   let f = Provable.witness(Field, () => Field(12));
 
-  let res1 = Gadgets.rotate(f, 2, 'left');
-  let res2 = Gadgets.rotate(f, 2, 'right');
+  let res1 = Gadgets.rotate64(f, 2, 'left');
+  let res2 = Gadgets.rotate64(f, 2, 'right');
 
   res1.assertEquals(Field(48));
   res2.assertEquals(Field(3));
@@ -21,8 +21,8 @@ const BitwiseProver = ZkProgram({
       privateInputs: [],
       method: () => {
         let a = Provable.witness(Field, () => Field(48));
-        let actualLeft = Gadgets.rotate(a, 2, 'left');
-        let actualRight = Gadgets.rotate(a, 2, 'right');
+        let actualLeft = Gadgets.rotate64(a, 2, 'left');
+        let actualRight = Gadgets.rotate64(a, 2, 'right');
 
         let expectedLeft = Field(192);
         actualLeft.assertEquals(expectedLeft);

src/lib/gadgets/arithmetic.ts

@@ -0,0 +1,39 @@
+import { Field } from '../core.js';
+import { Provable } from '../provable.js';
+import { rangeCheck32 } from './range-check.js';
+
+export { divMod32, addMod32 };
+
+function divMod32(n: Field) {
+  if (n.isConstant()) {
+    let nBigInt = n.toBigInt();
+    let q = nBigInt / (1n << 32n);
+    let r = nBigInt - q * (1n << 32n);
+    return {
+      remainder: new Field(r),
+      quotient: new Field(q),
+    };
+  }
+
+  let qr = Provable.witness(Provable.Array(Field, 2), () => {
+    let nBigInt = n.toBigInt();
+    let q = nBigInt / (1n << 32n);
+    let r = nBigInt - q * (1n << 32n);
+    return [new Field(q), new Field(r)];
+  });
+  let [quotient, remainder] = qr;
+
+  rangeCheck32(quotient);
+  rangeCheck32(remainder);
+
+  n.assertEquals(quotient.mul(1n << 32n).add(remainder));
+
+  return {
+    remainder,
+    quotient,
+  };
+}
+
+function addMod32(x: Field, y: Field) {
+  return divMod32(x.add(y)).remainder;
+}

src/lib/gadgets/bitwise.ts

@@ -10,9 +10,10 @@ import {
   divideWithRemainder,
   toVar,
 } from './common.js';
-import { rangeCheck64 } from './range-check.js';
+import { rangeCheck32, rangeCheck64 } from './range-check.js';
+import { divMod32 } from './arithmetic.js';
 
-export { xor, not, rotate, and, rightShift, leftShift };
+export { xor, not, rotate64, rotate32, and, rightShift, leftShift };
 
 function not(a: Field, length: number, checked: boolean = false) {
   // check that input length is positive
@@ -196,7 +197,7 @@ function and(a: Field, b: Field, length: number) {
   return outputAnd;
 }
 
-function rotate(
+function rotate64(
   field: Field,
   bits: number,
   direction: 'left' | 'right' = 'left'
@@ -209,16 +210,42 @@ function rotate(
 
   if (field.isConstant()) {
     assert(
-      field.toBigInt() < 2n ** BigInt(MAX_BITS),
+      field.toBigInt() < 1n << BigInt(MAX_BITS),
       `rotation: expected field to be at most 64 bits, got ${field.toBigInt()}`
     );
     return new Field(Fp.rot(field.toBigInt(), bits, direction));
   }
-  const [rotated] = rot(field, bits, direction);
+  const [rotated] = rot64(field, bits, direction);
+  return rotated;
+}
+
+function rotate32(
+  field: Field,
+  bits: number,
+  direction: 'left' | 'right' = 'left'
+) {
+  assert(bits <= 32 && bits > 0, 'bits must be between 0 and 32');
+
+  if (field.isConstant()) {
+    assert(
+      field.toBigInt() < 1n << 32n,
+      `rotation: expected field to be at most 32 bits, got ${field.toBigInt()}`
+    );
+    return new Field(Fp.rot(field.toBigInt(), bits, direction, 32));
+  }
+
+  let { quotient: excess, remainder: shifted } = divMod32(
+    field.mul(1n << BigInt(direction === 'left' ? bits : 32 - bits))
+  );
+
+  let rotated = shifted.add(excess);
+
+  rangeCheck32(rotated);
+
   return rotated;
 }
 
-function rot(
+function rot64(
   field: Field,
   bits: number,
   direction: 'left' | 'right' = 'left'
@@ -296,7 +323,7 @@ function rightShift(field: Field, bits: number) {
     );
     return new Field(Fp.rightShift(field.toBigInt(), bits));
   }
-  const [, excess] = rot(field, bits, 'right');
+  const [, excess] = rot64(field, bits, 'right');
   return excess;
 }
 
@@ -313,6 +340,6 @@ function leftShift(field: Field, bits: number) {
     );
     return new Field(Fp.leftShift(field.toBigInt(), bits));
   }
-  const [, , shifted] = rot(field, bits, 'left');
+  const [, , shifted] = rot64(field, bits, 'left');
   return shifted;
 }

src/lib/gadgets/bitwise.unit-test.ts

@@ -57,10 +57,16 @@ let Bitwise = ZkProgram({
         return Gadgets.and(a, b, 64);
       },
     },
-    rot: {
+    rot32: {
       privateInputs: [Field],
       method(a: Field) {
-        return Gadgets.rotate(a, 12, 'left');
+        return Gadgets.rotate32(a, 12, 'left');
+      },
+    },
+    rot64: {
+      privateInputs: [Field],
+      method(a: Field) {
+        return Gadgets.rotate64(a, 12, 'left');
       },
     },
     leftShift: {
@@ -104,7 +110,7 @@ await Bitwise.compile();
 [2, 4, 8, 16, 32, 64].forEach((length) => {
   equivalent({ from: [uint(length)], to: field })(
     (x) => Fp.rot(x, 12, 'left'),
-    (x) => Gadgets.rotate(x, 12, 'left')
+    (x) => Gadgets.rotate64(x, 12, 'left')
   );
   equivalent({ from: [uint(length)], to: field })(
     (x) => Fp.leftShift(x, 12),
@@ -116,6 +122,13 @@ await Bitwise.compile();
   );
 });
 
+[2, 4, 8, 16, 32].forEach((length) => {
+  equivalent({ from: [uint(length)], to: field })(
+    (x) => Fp.rot(x, 12, 'left', 32),
+    (x) => Gadgets.rotate32(x, 12, 'left')
+  );
+});
+
 await equivalentAsync({ from: [uint(64), uint(64)], to: field }, { runs: 3 })(
   (x, y) => {
     return x ^ y;
@@ -167,7 +180,18 @@ await equivalentAsync({ from: [field], to: field }, { runs: 3 })(
     return Fp.rot(x, 12, 'left');
   },
   async (x) => {
-    let proof = await Bitwise.rot(x);
+    let proof = await Bitwise.rot64(x);
+    return proof.publicOutput;
+  }
+);
+
+await equivalentAsync({ from: [field], to: field }, { runs: 3 })(
+  (x) => {
+    if (x >= 2n ** 32n) throw Error('Does not fit into 32 bits');
+    return Fp.rot(x, 12, 'left', 32);
+  },
+  async (x) => {
+    let proof = await Bitwise.rot32(x);
     return proof.publicOutput;
   }
 );
@@ -229,6 +253,6 @@ let isJustRotate = ifNotAllConstant(
   and(contains(rotChain), withoutGenerics(equals(rotChain)))
 );
 
-constraintSystem.fromZkProgram(Bitwise, 'rot', isJustRotate);
+constraintSystem.fromZkProgram(Bitwise, 'rot64', isJustRotate);
 constraintSystem.fromZkProgram(Bitwise, 'leftShift', isJustRotate);
 constraintSystem.fromZkProgram(Bitwise, 'rightShift', isJustRotate);

src/lib/gadgets/gadgets.ts

@@ -5,10 +5,20 @@ import {
   compactMultiRangeCheck,
   multiRangeCheck,
   rangeCheck64,
+  rangeCheck32,
 } from './range-check.js';
-import { not, rotate, xor, and, leftShift, rightShift } from './bitwise.js';
+import {
+  not,
+  rotate32,
+  rotate64,
+  xor,
+  and,
+  leftShift,
+  rightShift,
+} from './bitwise.js';
 import { Field } from '../core.js';
 import { ForeignField, Field3 } from './foreign-field.js';
+import { divMod32, addMod32 } from './arithmetic.js';
 
 export { Gadgets };
 
@@ -39,6 +49,33 @@ const Gadgets = {
   rangeCheck64(x: Field) {
     return rangeCheck64(x);
   },
+
+  /**
+   * Asserts that the input value is in the range [0, 2^32).
+   *
+   * This function proves that the provided field element can be represented with 32 bits.
+   * If the field element exceeds 32 bits, an error is thrown.
+   *
+   * @param x - The value to be range-checked.
+   *
+   * @throws Throws an error if the input value exceeds 32 bits.
+   *
+   * @example
+   * ```ts
+   * const x = Provable.witness(Field, () => Field(12345678n));
+   * Gadgets.rangeCheck32(x); // successfully proves 32-bit range
+   *
+   * const xLarge = Provable.witness(Field, () => Field(12345678901234567890123456789012345678n));
+   * Gadgets.rangeCheck32(xLarge); // throws an error since input exceeds 32 bits
+   * ```
+   *
+   * **Note**: Small "negative" field element inputs are interpreted as large integers close to the field size,
+   * and don't pass the 32-bit check. If you want to prove that a value lies in the int64 range [-2^31, 2^31),
+   * you could use `rangeCheck32(x.add(1n << 31n))`.
+   */
+  rangeCheck32(x: Field) {
+    return rangeCheck32(x);
+  },
   /**
    * A (left and right) rotation operates similarly to the shift operation (`<<` for left and `>>` for right) in JavaScript,
    * with the distinction that the bits are circulated to the opposite end of a 64-bit representation rather than being discarded.
@@ -52,7 +89,7 @@ const Gadgets = {
    * **Important:** The gadget assumes that its input is at most 64 bits in size.
    *
    * If the input exceeds 64 bits, the gadget is invalid and fails to prove correct execution of the rotation.
-   * To safely use `rotate()`, you need to make sure that the value passed in is range-checked to 64 bits;
+   * To safely use `rotate64()`, you need to make sure that the value passed in is range-checked to 64 bits;
    * for example, using {@link Gadgets.rangeCheck64}.
    *
    * You can find more details about the implementation in the [Mina book](https://o1-labs.github.io/proof-systems/specs/kimchi.html?highlight=gates#rotation)
@@ -66,17 +103,55 @@ const Gadgets = {
    * @example
    * ```ts
    * const x = Provable.witness(Field, () => Field(0b001100));
-   * const y = Gadgets.rotate(x, 2, 'left'); // left rotation by 2 bits
-   * const z = Gadgets.rotate(x, 2, 'right'); // right rotation by 2 bits
+   * const y = Gadgets.rotate64(x, 2, 'left'); // left rotation by 2 bits
+   * const z = Gadgets.rotate64(x, 2, 'right'); // right rotation by 2 bits
+   * y.assertEquals(0b110000);
+   * z.assertEquals(0b000011);
+   *
+   * const xLarge = Provable.witness(Field, () => Field(12345678901234567890123456789012345678n));
+   * Gadgets.rotate64(xLarge, 32, "left"); // throws an error since input exceeds 64 bits
+   * ```
+   */
+  rotate64(field: Field, bits: number, direction: 'left' | 'right' = 'left') {
+    return rotate64(field, bits, direction);
+  },
+  /**
+   * A (left and right) rotation operates similarly to the shift operation (`<<` for left and `>>` for right) in JavaScript,
+   * with the distinction that the bits are circulated to the opposite end of a 32-bit representation rather than being discarded.
+   * For a left rotation, this means that bits shifted off the left end reappear at the right end.
+   * Conversely, for a right rotation, bits shifted off the right end reappear at the left end.
+   *
+   * It’s important to note that these operations are performed considering the big-endian 32-bit representation of the number,
+   * where the most significant (32th) bit is on the left end and the least significant bit is on the right end.
+   * The `direction` parameter is a string that accepts either `'left'` or `'right'`, determining the direction of the rotation.
+   *
+   * **Important:** The gadget assumes that its input is at most 32 bits in size.
+   *
+   * If the input exceeds 32 bits, the gadget is invalid and fails to prove correct execution of the rotation.
+   * To safely use `rotate32()`, you need to make sure that the value passed in is range-checked to 32 bits;
+   * for example, using {@link Gadgets.rangeCheck32}.
+   *
+   *
+   * @param field {@link Field} element to rotate.
+   * @param bits amount of bits to rotate this {@link Field} element with.
+   * @param direction left or right rotation direction.
+   *
+   * @throws Throws an error if the input value exceeds 32 bits.
+   *
+   * @example
+   * ```ts
+   * const x = Provable.witness(Field, () => Field(0b001100));
+   * const y = Gadgets.rotate32(x, 2, 'left'); // left rotation by 2 bits
+   * const z = Gadgets.rotate32(x, 2, 'right'); // right rotation by 2 bits
    * y.assertEquals(0b110000);
    * z.assertEquals(0b000011);
    *
    * const xLarge = Provable.witness(Field, () => Field(12345678901234567890123456789012345678n));
-   * Gadgets.rotate(xLarge, 32, "left"); // throws an error since input exceeds 64 bits
+   * Gadgets.rotate32(xLarge, 32, "left"); // throws an error since input exceeds 32 bits
    * ```
    */
-  rotate(field: Field, bits: number, direction: 'left' | 'right' = 'left') {
-    return rotate(field, bits, direction);
+  rotate32(field: Field, bits: number, direction: 'left' | 'right' = 'left') {
+    return rotate32(field, bits, direction);
   },
   /**
    * Bitwise XOR gadget on {@link Field} elements. Equivalent to the [bitwise XOR `^` operator in JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_XOR).
@@ -420,6 +495,38 @@ const Gadgets = {
    * **Note:** This interface does not contain any provable methods.
    */
   Field3,
+  /**
+   * Division modulo 2^32. The operation decomposes a {@link Field} element into two 32-bit limbs, `remainder` and `quotient`, using the following equation: `n = quotient * 2^32 + remainder`.
+   *
+   * Asserts that both `remainder` and `quotient` are in the range [0, 2^32) using {@link Gadgets.rangeCheck32}.
+   *
+   * @example
+   * ```ts
+   * let n = Field((1n << 32n) + 8n)
+   * let { remainder, quotient } = Gadgets.divMod32(n);
+   * // remainder = 8, quotient = 1
+   *
+   * n.assertEquals(quotient.mul(1n << 32n).add(remainder));
+   * ```
+   */
+  divMod32,
+
+  /**
+   * Addition modulo 2^32. The operation adds two {@link Field} elements and returns the result modulo 2^32.
+   *
+   * Asserts that the result is in the range [0, 2^32) using {@link Gadgets.rangeCheck32}.
+   *
+   * It uses {@link Gadgets.divMod32} internally by adding the two {@link Field} elements and then decomposing the result into `remainder` and `quotient` and returning the `remainder`.
+   *
+   * @example
+   * ```ts
+   * let a = Field(8n);
+   * let b = Field(1n << 32n);
+   *
+   * Gadgets.addMod32(a, b).assertEquals(Field(8n));
+   * ```
+   *    */
+  addMod32,
 };
 
 export namespace Gadgets {