Merge pull request #2322 from o1-labs/2025-07-foreign-field-from-field

Support Foreign Field Initialization from Field

Author: 45930

.husky/pre-commit

@@ -9,5 +9,5 @@ fi
 echo "⚠️   Husky pre-commit hook enabled. Disable it with: git config --unset husky.optin"
 
 # Filter for diffed (excluding deleted) js and ts files, and format them according to oxlint and prettier rules
-git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|js)$' | xargs npm run lint:fix
-git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|js)$' | xargs npm run format
+git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|js|md)$' | xargs npm run lint:fix
+git diff --cached --name-only --diff-filter=d | grep -E '\.(ts|js|md)$' | xargs npm run format

CHANGELOG.md

@@ -47,6 +47,11 @@ This project adheres to
 - Sourcemaps properly work with the .cjs distribution of `o1js` now.
   https://github.com/o1-labs/o1js/pull/2285
 
+### Added
+
+- Support for `Field` as an input type to `ForeignField.from`
+  https://github.com/o1-labs/o1js/pull/2322
+
 ## [2.7.0](https://github.com/o1-labs/o1js/compare/6b6d8b9...045b1ab) - 2025-07-23
 
 ### Added

flake.nix

@@ -103,8 +103,8 @@
           ((pkgs.rustChannelOf
             {
               channel = "nightly";
-              date = "2024-09-05";
-              sha256 = "sha256-3aoA7PuH09g8F+60uTUQhnHrb/ARDLueSOD08ZVsWe0=";
+              date = "2024-06-13";
+              sha256 = "sha256-s5nlYcYG9EuO2HK2BU3PkI928DZBKCTJ4U9bz3RX1t4=";
             }).rust.override
             {
               targets = [
@@ -205,7 +205,7 @@
             checkPhase = if pkgs.stdenv.isDarwin then "" else null;
             text =
               ''
-                if [ "$1" = run ] && { [ "$2" = nightly-2024-09-05 ] || [[ "$2" =~ 1.79-x86_64* ]]; }
+                if [ "$1" = run ] && { [ "$2" = nightly-2024-06-13 ] || [[ "$2" =~ 1.79-x86_64* ]]; }
                 then
                   echo using nix toolchain
                   ${rustup}/bin/rustup run nix "''${@:3}"

src/lib/provable/foreign-field.ts

@@ -6,6 +6,7 @@ import { Tuple, TupleMap, TupleN } from '../util/types.js';
 import { Gadgets } from './gadgets/gadgets.js';
 import { ForeignField as FF, Field3 } from './gadgets/foreign-field.js';
 import { assert } from './gadgets/common.js';
+import { fieldToField3 } from './gadgets/comparison.js';
 import { l3, l } from './gadgets/range-check.js';
 import { ProvablePureExtended } from './types/struct.js';
 
@@ -42,6 +43,36 @@ class ForeignField {
     return this.constructor as typeof ForeignField;
   }
 
+  /**
+   * Unsafe constructor methods for advanced usage.
+   */
+  static get Unsafe() {
+    const Constructor = this;
+    return {
+      /**
+       * Converts a {@link Field} into a {@link ForeignField}. This is an **unsafe** operation
+       * as the native Field size may be larger than the Foreign Field size, and changes in modulus
+       * can have unintended consequences.
+       *
+       * Only use this if you have already constrained the Field element to be within the foreign field modulus.
+       *
+       * @param x a {@link Field}
+       */
+      fromField(x: Field) {
+        const p = Constructor.modulus;
+        if (x.isConstant()) {
+          let value = x.toBigInt();
+          if (value >= p) {
+            throw new Error(
+              `Field value ${value} exceeds foreign field modulus ${p}. Please ensure the value is reduced to the modulus.`
+            );
+          }
+        }
+        return new Constructor.Canonical(fieldToField3(x));
+      },
+    };
+  }
+
   /**
    * Sibling classes that represent different ranges of field elements.
    */
@@ -76,10 +107,11 @@ class ForeignField {
   }
 
   /**
-   * Create a new {@link ForeignField} from a bigint, number, string or another ForeignField.
+   * Create a new {@link ForeignField} from a bigint, number, string, or another ForeignField.
    * @example
    * ```ts
    * let x = new ForeignField(5);
+   * let y = ForeignField.from(10n);
    * ```
    *
    * Note: Inputs must be range checked if they originate from a different field with a different modulus or if they are not constants.
@@ -110,6 +142,7 @@ class ForeignField {
 
   /**
    * Coerce the input to a {@link ForeignField}.
+   * @param x - The value to convert. Can be a {@link ForeignField}, bigint, number, or string.
    */
   static from(x: bigint | number | string): CanonicalForeignField;
   static from(x: ForeignField | bigint | number | string): ForeignField;
@@ -689,7 +722,7 @@ type Constructor<T> = new (...args: any[]) => T;
 function provable<
   F extends ForeignField & {
     type: 'Unreduced' | 'AlmostReduced' | 'FullyReduced';
-  },
+  }
 >(
   Class: Constructor<F> & { check(x: ForeignField): void }
 ): ProvablePureExtended<F, bigint, string> {

src/lib/provable/test/foreign-field.unit-test.ts

@@ -5,6 +5,7 @@ import { expect } from 'expect';
 import {
   bool,
   equivalentProvable as equivalent,
+  field,
   first,
   spec,
   throwError,
@@ -100,3 +101,69 @@ equivalent({ from: [f], to: f })(
     return ForeignScalar.fromBits(bits);
   }
 );
+
+// Field to ForeignField conversion tests
+
+console.log('Testing Field to ForeignField conversion...');
+
+// Test 1: Constant Field conversion
+{
+  let field = Field(123);
+  let foreignField = ForeignScalar.Unsafe.fromField(field);
+  expect(foreignField.toBigInt()).toBe(123n);
+  expect(foreignField.isConstant()).toBe(true);
+  console.log('✓ Constant Field conversion');
+}
+
+// Test 2: Constructor with Field
+{
+  let field = Field(456);
+  let foreignField = ForeignScalar.Unsafe.fromField(field);
+  expect(foreignField.toBigInt()).toBe(456n);
+  expect(foreignField.isConstant()).toBe(true);
+  console.log('✓ Constructor with Field');
+}
+
+// Test 3: Boundary values
+{
+  // Test zero
+  let zero = ForeignScalar.Unsafe.fromField(Field(0));
+  expect(zero.toBigInt()).toBe(0n);
+
+  // Test large valid value within native Field range
+  // Use a large value that fits in native Field (~2^254) rather than foreign field modulus (~2^259)
+  let largeValue = (1n << 254n) - 1n; // Safe value within native Field range
+  let large = Field(largeValue);
+  let foreignLarge = ForeignScalar.Unsafe.fromField(large);
+  expect(foreignLarge.toBigInt()).toBe(largeValue);
+  console.log('✓ Boundary values');
+}
+
+// Test 4: Small field modulus overflow error
+{
+  // Using SmallField (modulus 17) to easily test overflow
+  expect(() => {
+    SmallField.Unsafe.fromField(Field(18)); // 18 > 17 (modulus)
+  }).toThrow('exceeds foreign field modulus');
+  console.log('✓ Modulus overflow error');
+}
+
+// Test 5: Round-trip conversion
+{
+  let original = Field(12345);
+  let foreign = ForeignScalar.Unsafe.fromField(original);
+  let reconstructed = Field(foreign.toBigInt());
+  expect(reconstructed.toBigInt()).toBe(original.toBigInt());
+  console.log('✓ Round-trip conversion');
+}
+
+// Test 6: Variable Field conversion in provable context
+equivalent({
+  from: [field],
+  to: f,
+})(
+  (x) => x,
+  (field) => ForeignScalar.Unsafe.fromField(field)
+);
+
+console.log('✓ All Field conversion tests passed!');