Added Safe.fromField and .max

rpanic · rpanic · commit d1e7788b5bdf · 2024-04-09T18:17:03.000+02:00
diff --git a/packages/library/src/math/PrecisionHelper.ts b/packages/library/src/math/PrecisionHelper.ts
diff --git a/packages/library/src/math/UInt.ts b/packages/library/src/math/UInt.ts
@@ -1,6 +1,6 @@
 // eslint-disable-next-line max-len
 /* eslint-disable @typescript-eslint/no-magic-numbers,prefer-const,id-length,no-underscore-dangle */
-import { Bool, Field, Provable, Struct } from "o1js";
+import { Bool, Field, Provable, Struct, UInt64 as O1UInt64 } from "o1js";
 import { assert } from "@proto-kit/protocol";
 // @ts-ignore
 import bigintSqrt from "bigint-isqrt";
@@ -15,16 +15,26 @@ const errors = {
 };
 
 export type UIntConstructor<BITS extends number> = {
-  // new(value: Field | { value: Field }): UIntX<BITS>;
   from(x: UInt<BITS> | bigint | number | string): UInt<BITS>;
   check(x: { value: Field }): void;
   get zero(): UInt<BITS>;
+  get max(): UInt<BITS>;
 
   Unsafe: {
     fromField(x: Field): UInt<BITS>;
   };
+  Safe: {
+    fromField(x: Field): UInt<BITS>;
+  };
 };
 
+/**
+ * UInt is a base class for all soft-failing UInt* implementations.
+ * It has to be overridden for every bitlength that should be available.
+ *
+ * For this, the developer has to create a subclass of UInt implementing the
+ * static methods from interface UIntConstructor
+ */
 export abstract class UInt<BITS extends number> extends Struct({
   value: Field,
 }) {
@@ -51,6 +61,18 @@ export abstract class UInt<BITS extends number> extends Struct({
     return Field((1n << BigInt(numBits)) - 1n);
   }
 
+  private checkConstant(x: Field) {
+    if (!x.isConstant()) return x;
+    let xBig = x.toBigInt();
+    const bits = this.numBits();
+    if (xBig < 0n || xBig >= 1n << BigInt(this.numBits())) {
+      throw Error(
+        `UInt${bits}: Expected number between 0 and 2^${bits} - 1, got ${xBig}`
+      );
+    }
+    return x;
+  }
+
   public constructor(value: { value: Field }) {
     super(value);
 
@@ -62,6 +84,8 @@ export abstract class UInt<BITS extends number> extends Struct({
     if (bits === 256) {
       throw errors.usageWith256BitsForbidden();
     }
+
+    this.checkConstant(value.value);
   }
 
   public abstract numBits(): BITS;
@@ -393,24 +417,29 @@ export abstract class UInt<BITS extends number> extends Struct({
     UInt.assertionFunction(this.equals(y), message);
   }
 
-  // /**
-  //  * Turns the {@link UIntX} into a {@link UInt64}, asserting that it fits in 32 bits.
-  //  */
-  // public toUInt64() {
-  //   let uint64 = new UInt64(this.value);
-  //   UInt64.check(uint64);
-  //   return uint64;
-  // }
-  //
-  // /**
-  //  * Turns the {@link UIntX} into a {@link UInt64}, clamping to the 64 bits range if it's too large.
-  //  */
-  // public toUInt64Clamped() {
-  //   let max = (1n << 64n) - 1n;
-  //   return Provable.if(
-  //     this.greaterThan(UIntX.from(max)),
-  //     UInt64.from(max),
-  //     new UInt64(this.value)
-  //   );
-  // }
+  /**
+   * Turns the {@link UInt} into a o1js {@link UInt64}, asserting that it fits in 32 bits.
+   */
+  public toO1UInt64() {
+    let uint64 = new O1UInt64(this.value);
+    O1UInt64.check(uint64);
+    return uint64;
+  }
+
+  /**
+   * Turns the {@link UInt} into a o1js {@link UInt64}, clamping to the 64 bits range if it's too large.
+   */
+  public toO1UInt64Clamped() {
+    if (this.numBits() <= 64) {
+      return new O1UInt64(this.value);
+    } else {
+      let max = (1n << 64n) - 1n;
+      return Provable.if(
+        // We know that BITS is >64 bits, so we can skip range checks for max
+        this.greaterThan(this.fromField(Field(max))),
+        O1UInt64.from(max),
+        new O1UInt64(this.value)
+      );
+    }
+  }
 }
diff --git a/packages/library/src/math/UInt112.ts b/packages/library/src/math/UInt112.ts
@@ -1,5 +1,6 @@
 import { Field } from "o1js";
 import { UIntConstructor, UInt } from "./UInt";
+import { UInt224 } from "./UInt224";
 
 export class UInt112 extends UInt<112> {
   public static Unsafe = {
@@ -8,20 +9,32 @@ export class UInt112 extends UInt<112> {
     },
   };
 
+  public static Safe = {
+    fromField(value: Field) {
+      const uint = new UInt112({ value });
+      UInt112.check(uint);
+      return uint;
+    },
+  };
+
   public static check(x: { value: Field }) {
     const actual = x.value.rangeCheckHelper(112);
     UInt.assertionFunction(actual.equals(x.value));
   }
 
-  public static from(x: UInt<112> | bigint | number | string): UInt112 {
-    if (x instanceof UInt) {
+  public static from(x: UInt112 | bigint | number | string): UInt112 {
+    if (x instanceof UInt112) {
       return x;
     }
     return new UInt112({ value: UInt.checkConstant(Field(x), 112) });
   }
 
   public static get zero() {
-    return UInt112.Unsafe.fromField(Field(0))
+    return UInt112.Unsafe.fromField(Field(0));
+  }
+
+  public static get max() {
+    return UInt112.Unsafe.fromField(UInt.maxIntField(112));
   }
 
   public constructorReference(): UIntConstructor<112> {
@@ -31,4 +44,8 @@ export class UInt112 extends UInt<112> {
   public numBits() {
     return 112 as const;
   }
+
+  public toUInt224(): UInt224 {
+    return UInt224.Unsafe.fromField(this.value);
+  }
 }
diff --git a/packages/library/src/math/UInt224.ts b/packages/library/src/math/UInt224.ts
@@ -1,4 +1,4 @@
-import { Field, UInt64 } from "o1js";
+import { Field } from "o1js";
 import { UIntConstructor, UInt } from "./UInt";
 
 export class UInt224 extends UInt<224> {
@@ -8,6 +8,14 @@ export class UInt224 extends UInt<224> {
     },
   };
 
+  public static Safe = {
+    fromField(value: Field) {
+      const uint = new UInt224({ value });
+      UInt224.check(uint);
+      return uint;
+    },
+  };
+
   public static check(x: { value: Field }) {
     const actual = x.value.rangeCheckHelper(224);
     UInt.assertionFunction(actual.equals(x.value));
@@ -21,7 +29,11 @@ export class UInt224 extends UInt<224> {
   }
 
   public static get zero() {
-    return UInt224.Unsafe.fromField(Field(0))
+    return UInt224.Unsafe.fromField(Field(0));
+  }
+
+  public static get max() {
+    return UInt224.Unsafe.fromField(UInt.maxIntField(224));
   }
 
   public constructorReference(): UIntConstructor<224> {
diff --git a/packages/library/src/math/UInt32.ts b/packages/library/src/math/UInt32.ts
@@ -1,5 +1,6 @@
 import { Field } from "o1js";
 import { UIntConstructor, UInt } from "./UInt";
+import { UInt64 } from "./UInt64";
 
 export class UInt32 extends UInt<32> {
   public static Unsafe = {
@@ -8,6 +9,14 @@ export class UInt32 extends UInt<32> {
     },
   };
 
+  public static Safe = {
+    fromField(value: Field) {
+      const uint = new UInt32({ value });
+      UInt32.check(uint);
+      return uint;
+    },
+  };
+
   public static check(x: { value: Field }) {
     const actual = x.value.rangeCheckHelper(32);
     UInt.assertionFunction(actual.equals(x.value));
@@ -21,7 +30,11 @@ export class UInt32 extends UInt<32> {
   }
 
   public static get zero() {
-    return UInt32.Unsafe.fromField(Field(0))
+    return UInt32.Unsafe.fromField(Field(0));
+  }
+
+  public static get max() {
+    return UInt32.Unsafe.fromField(UInt.maxIntField(32));
   }
 
   public constructorReference(): UIntConstructor<32> {
@@ -31,4 +44,8 @@ export class UInt32 extends UInt<32> {
   public numBits(): 32 {
     return 32;
   }
+
+  public toUInt64(): UInt64 {
+    return UInt64.Unsafe.fromField(this.value);
+  }
 }
diff --git a/packages/library/src/math/UInt64.ts b/packages/library/src/math/UInt64.ts
@@ -8,6 +8,14 @@ export class UInt64 extends UInt<64> {
     },
   };
 
+  public static Safe = {
+    fromField(value: Field) {
+      const uint = new UInt64({ value });
+      UInt64.check(uint);
+      return uint;
+    },
+  };
+
   public static check(x: { value: Field }) {
     const actual = x.value.rangeCheckHelper(64);
     UInt.assertionFunction(actual.equals(x.value));
@@ -21,7 +29,11 @@ export class UInt64 extends UInt<64> {
   }
 
   public static get zero() {
-    return UInt64.Unsafe.fromField(Field(0))
+    return UInt64.Unsafe.fromField(Field(0));
+  }
+
+  public static get max() {
+    return UInt64.Unsafe.fromField(UInt.maxIntField(64));
   }
 
   public constructorReference(): UIntConstructor<64> {
