Skip to main content

ForeignField

Defined in: lib/provable/foreign-field.ts:17

Extended by​

Constructors​

Constructor​

new ForeignField(x: string | number | bigint | Field3 | ForeignField): ForeignField;

Defined in: lib/provable/foreign-field.ts:123

Create a new ForeignField from a bigint, number, string, or another ForeignField.

Parameters​

x​

string | number | bigint | Field3 | ForeignField

Returns​

ForeignField

Example​

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.

  • When constructing from another ForeignField instance, ensure the modulus matches. If not, check the modulus using Gadgets.ForeignField.assertLessThan() and handle appropriately.
  • When constructing from a Field3 array, ensure all elements are valid Field elements and range checked.
  • Ensure constants are correctly reduced to the modulus of the field.

Properties​

value​

value: Field3;

Defined in: lib/provable/foreign-field.ts:40

The internal representation of a foreign field element, as a tuple of 3 limbs.

_Bigint​

static _Bigint: 
  | undefined
  | {
} = undefined;

Defined in: lib/provable/foreign-field.ts:18

_modulus​

static _modulus: undefined | bigint = undefined;

Defined in: lib/provable/foreign-field.ts:19

_provable​

static _provable: any = undefined;

Defined in: lib/provable/foreign-field.ts:431

_variants​

static _variants: 
  | undefined
  | {
  almostReduced: typeof AlmostForeignField;
  canonical: typeof CanonicalForeignField;
  unreduced: typeof UnreducedForeignField;
} = undefined;

Defined in: lib/provable/foreign-field.ts:79

Sibling classes that represent different ranges of field elements.

Accessors​

Constructor​

Get Signature​

get Constructor(): typeof ForeignField;

Defined in: lib/provable/foreign-field.ts:42

Returns​

typeof ForeignField

modulus​

Get Signature​

get modulus(): bigint;

Defined in: lib/provable/foreign-field.ts:30

Returns​

bigint

AlmostReduced​

Get Signature​

get static AlmostReduced(): typeof AlmostForeignField;

Defined in: lib/provable/foreign-field.ts:97

Constructor for field elements that are "almost reduced", i.e. lie in the range [0, 2^ceil(log2(p))).

Returns​

typeof AlmostForeignField

Bigint​

Get Signature​

get static Bigint(): {
};

Defined in: lib/provable/foreign-field.ts:22

Returns​
{
}

Canonical​

Get Signature​

get static Canonical(): typeof CanonicalForeignField;

Defined in: lib/provable/foreign-field.ts:104

Constructor for field elements that are fully reduced, i.e. lie in the range [0, p).

Returns​

typeof CanonicalForeignField

modulus​

Get Signature​

get static modulus(): bigint;

Defined in: lib/provable/foreign-field.ts:26

Returns​

bigint

provable​

Get Signature​

get static provable(): any;

Defined in: lib/provable/foreign-field.ts:436

Provable<ForeignField>, see Provable

Returns​

any

sizeInBits​

Get Signature​

get static sizeInBits(): number;

Defined in: lib/provable/foreign-field.ts:33

Returns​

number

Unreduced​

Get Signature​

get static Unreduced(): typeof UnreducedForeignField;

Defined in: lib/provable/foreign-field.ts:90

Constructor for unreduced field elements.

Returns​

typeof UnreducedForeignField

Unsafe​

Get Signature​

get static Unsafe(): {
  fromField: CanonicalForeignField;
};

Defined in: lib/provable/foreign-field.ts:49

Unsafe constructor methods for advanced usage.

Returns​
fromField()​
fromField(x: Field): CanonicalForeignField;

Converts a Field into a 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.

Parameters​
x​

Field

a Field

Returns​

CanonicalForeignField

Methods​

add()​

add(y: number | bigint | ForeignField): UnreducedForeignField;

Defined in: lib/provable/foreign-field.ts:241

Finite field addition

Parameters​

y​

number | bigint | ForeignField

Returns​

UnreducedForeignField

Example​

x.add(2); // x + 2 mod p

assertAlmostReduced()​

assertAlmostReduced(): AlmostForeignField;

Defined in: lib/provable/foreign-field.ts:196

Assert that this field element lies in the range [0, 2^k), where k = ceil(log2(p)) and p is the foreign field modulus.

Returns the field element as a AlmostForeignField.

For a more efficient version of this for multiple field elements, see assertAlmostReduced.

Note: this does not ensure that the field elements is in the canonical range [0, p). To assert that stronger property, there is assertCanonical. You should typically use assertAlmostReduced though, because it is cheaper to prove and sufficient for ensuring validity of all our non-native field arithmetic methods.

Returns​

AlmostForeignField

assertCanonical()​

assertCanonical(): CanonicalForeignField;

Defined in: lib/provable/foreign-field.ts:227

Assert that this field element is fully reduced, i.e. lies in the range [0, p), where p is the foreign field modulus.

Returns the field element as a CanonicalForeignField.

Returns​

CanonicalForeignField

assertEquals()​

Call Signature​

assertEquals(y: number | bigint | CanonicalForeignField, message?: string): CanonicalForeignField;

Defined in: lib/provable/foreign-field.ts:319

Assert equality with a ForeignField-like value

Parameters​
y​

number | bigint | CanonicalForeignField

message?​

string

Returns​

CanonicalForeignField

Examples​
x.assertEquals(0, "x is zero");

Since asserting equality can also serve as a range check, this method returns x with the appropriate type:

let xChecked = x.assertEquals(1, "x is 1");
xChecked satisfies CanonicalForeignField;

Call Signature​

assertEquals(y: AlmostForeignField, message?: string): AlmostForeignField;

Defined in: lib/provable/foreign-field.ts:320

Assert equality with a ForeignField-like value

Parameters​
y​

AlmostForeignField

message?​

string

Returns​

AlmostForeignField

Examples​
x.assertEquals(0, "x is zero");

Since asserting equality can also serve as a range check, this method returns x with the appropriate type:

let xChecked = x.assertEquals(1, "x is 1");
xChecked satisfies CanonicalForeignField;

Call Signature​

assertEquals(y: ForeignField, message?: string): ForeignField;

Defined in: lib/provable/foreign-field.ts:321

Assert equality with a ForeignField-like value

Parameters​
y​

ForeignField

message?​

string

Returns​

ForeignField

Examples​
x.assertEquals(0, "x is zero");

Since asserting equality can also serve as a range check, this method returns x with the appropriate type:

let xChecked = x.assertEquals(1, "x is 1");
xChecked satisfies CanonicalForeignField;

assertLessThan()​

assertLessThan(c: number | bigint, message?: string): void;

Defined in: lib/provable/foreign-field.ts:356

Assert that this field element is less than a constant c: x < c.

The constant must satisfy 0 <= c < 2^264, otherwise an error is thrown.

Parameters​

c​

number | bigint

message?​

string

Returns​

void

Example​

x.assertLessThan(10);

isConstant()​

isConstant(): boolean;

Defined in: lib/provable/foreign-field.ts:159

Checks whether this field element is a constant.

See FieldVar to understand constants vs variables.

Returns​

boolean

neg()​

neg(): AlmostForeignField;

Defined in: lib/provable/foreign-field.ts:252

Finite field negation

Returns​

AlmostForeignField

Example​

x.neg(); // -x mod p = p - x

sub()​

sub(y: number | bigint | ForeignField): UnreducedForeignField;

Defined in: lib/provable/foreign-field.ts:267

Finite field subtraction

Parameters​

y​

number | bigint | ForeignField

Returns​

UnreducedForeignField

Example​

x.sub(1); // x - 1 mod p

toBigInt()​

toBigInt(): bigint;

Defined in: lib/provable/foreign-field.ts:179

Convert this field element to a bigint.

Returns​

bigint

toBits()​

toBits(length?: number): Bool[];

Defined in: lib/provable/foreign-field.ts:375

Unpack a field element to its bits, as a Bool[] array.

This method is provable!

Parameters​

length?​

number

Returns​

Bool[]

toConstant()​

toConstant(): ForeignField;

Defined in: lib/provable/foreign-field.ts:171

Convert this field element to a constant.

See FieldVar to understand constants vs variables.

Warning: This function is only useful in Provable.witness or Provable.asProver blocks, that is, in situations where the prover computes a value outside provable code.

Returns​

ForeignField

toFields()​

toFields(): Field[];

Defined in: lib/provable/foreign-field.ts:423

Instance version of Provable<ForeignField>.toFields, see Provable.toFields

Returns​

Field[]

assertAlmostReduced()​

static assertAlmostReduced<T>(...xs: T): [...{ [i in string | number | symbol]: AlmostForeignField }[]];

Defined in: lib/provable/foreign-field.ts:210

Assert that one or more field elements lie in the range [0, 2^k), where k = ceil(log2(p)) and p is the foreign field modulus.

This is most efficient than when checking a multiple of 3 field elements at once.

Type Parameters​

T​

T extends Tuple<ForeignField>

Parameters​

xs​

...T

Returns​

[...{ [i in string | number | symbol]: AlmostForeignField }[]]

check()​

static check(_: ForeignField): void;

Defined in: lib/provable/foreign-field.ts:427

Parameters​

_​

ForeignField

Returns​

void

from()​

Call Signature​

static from(x: string | number | bigint): CanonicalForeignField;

Defined in: lib/provable/foreign-field.ts:147

Coerce the input to a ForeignField.

Parameters​
x​

The value to convert. Can be a ForeignField, bigint, number, or string.

string | number | bigint

Returns​

CanonicalForeignField

Call Signature​

static from(x: string | number | bigint | ForeignField): ForeignField;

Defined in: lib/provable/foreign-field.ts:148

Coerce the input to a ForeignField.

Parameters​
x​

The value to convert. Can be a ForeignField, bigint, number, or string.

string | number | bigint | ForeignField

Returns​

ForeignField

fromBits()​

static fromBits(bits: Bool[]): AlmostForeignField;

Defined in: lib/provable/foreign-field.ts:405

Create a field element from its bits, as a Bool[] array.

This method is provable!

Parameters​

bits​

Bool[]

Returns​

AlmostForeignField

random()​

static random(): CanonicalForeignField;

Defined in: lib/provable/foreign-field.ts:416

Returns​

CanonicalForeignField

sum()​

static sum(xs: (number | bigint | ForeignField)[], operations: (-1 | 1)[]): UnreducedForeignField;

Defined in: lib/provable/foreign-field.ts:292

Sum (or difference) of multiple finite field elements.

Parameters​

xs​

(number | bigint | ForeignField)[]

operations​

(-1 | 1)[]

Returns​

UnreducedForeignField

Example​

let z = ForeignField.sum([3, 2, 1], [-1, 1]); // 3 - 2 + 1
z.assertEquals(2);

This method expects a list of ForeignField-like values, x0,...,xn, and a list of "operations" op1,...,opn where every op is 1 or -1 (plus or minus), and returns

x0 + op1*x1 + ... + opn*xn

where the sum is computed in finite field arithmetic.

Important: For more than two summands, this is significantly more efficient than chaining calls to ForeignField.add and ForeignField.sub.