Skip to main content

UnreducedForeignField

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

Extends​

Extended by​

Constructors​

Constructor​

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

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​

UnreducedForeignField

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.

Inherited from​

ForeignField.constructor

Properties​

type​

type: "Unreduced" | "AlmostReduced" | "FullyReduced" = 'Unreduced';

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

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.

Inherited from​

ForeignField.value

_Bigint​

static _Bigint: 
  | undefined
  | {
} = undefined;

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

Inherited from​

ForeignField._Bigint

_modulus​

static _modulus: undefined | bigint = undefined;

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

Inherited from​

ForeignField._modulus

_provable​

static _provable: 
  | undefined
  | ProvablePureExtended<UnreducedForeignField, bigint, string> = undefined;

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

Overrides​

ForeignField._provable

_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.

Inherited from​

ForeignField._variants

Accessors​

Constructor​

Get Signature​

get Constructor(): typeof ForeignField;

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

Returns​

typeof ForeignField

Inherited from​

ForeignField.Constructor

modulus​

Get Signature​

get modulus(): bigint;

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

Returns​

bigint

Inherited from​

ForeignField.modulus

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

Inherited from​

ForeignField.AlmostReduced

Bigint​

Get Signature​

get static Bigint(): {
};

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

Returns​
{
}

Inherited from​

ForeignField.Bigint

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

Inherited from​

ForeignField.Canonical

modulus​

Get Signature​

get static modulus(): bigint;

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

Returns​

bigint

Inherited from​

ForeignField.modulus

provable​

Get Signature​

get static provable(): ProvablePureExtended<UnreducedForeignField, bigint, string>;

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

Provable<ForeignField>, see Provable

Returns​

ProvablePureExtended<UnreducedForeignField, bigint, string>

Overrides​

ForeignField.provable

sizeInBits​

Get Signature​

get static sizeInBits(): number;

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

Returns​

number

Inherited from​

ForeignField.sizeInBits

Unreduced​

Get Signature​

get static Unreduced(): typeof UnreducedForeignField;

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

Constructor for unreduced field elements.

Returns​

typeof UnreducedForeignField

Inherited from​

ForeignField.Unreduced

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

Inherited from​

ForeignField.Unsafe

Methods​

add()​

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

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

Finite field addition

Parameters​

y​

number | bigint | ForeignField

Returns​

UnreducedForeignField

Example​

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

Inherited from​

ForeignField.add

assertAlmostReduced()​

assertAlmostReduced(): AlmostForeignField;

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

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

Inherited from​

ForeignField.assertAlmostReduced

assertCanonical()​

assertCanonical(): CanonicalForeignField;

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

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

Inherited from​

ForeignField.assertCanonical

assertEquals()​

Call Signature​

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

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

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;
Inherited from​

ForeignField.assertEquals

Call Signature​

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

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

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;
Inherited from​

ForeignField.assertEquals

Call Signature​

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

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

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;
Inherited from​

ForeignField.assertEquals

assertLessThan()​

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

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

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);

Inherited from​

ForeignField.assertLessThan

neg()​

neg(): AlmostForeignField;

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

Finite field negation

Returns​

AlmostForeignField

Example​

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

Inherited from​

ForeignField.neg

sub()​

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

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

Finite field subtraction

Parameters​

y​

number | bigint | ForeignField

Returns​

UnreducedForeignField

Example​

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

Inherited from​

ForeignField.sub

toBigInt()​

toBigInt(): bigint;

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

Convert this field element to a bigint.

Returns​

bigint

Inherited from​

ForeignField.toBigInt

toBits()​

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

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

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

This method is provable!

Parameters​

length?​

number

Returns​

Bool[]

Inherited from​

ForeignField.toBits

toFields()​

toFields(): Field[];

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

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

Returns​

Field[]

Inherited from​

ForeignField.toFields

assertAlmostReduced()​

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

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

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 }[]]

Inherited from​

ForeignField.assertAlmostReduced

check()​

static check(x: ForeignField): void;

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

Parameters​

x​

ForeignField

Returns​

void

Overrides​

ForeignField.check

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

Inherited from​

ForeignField.from

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

Inherited from​

ForeignField.from

fromBits()​

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

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

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

This method is provable!

Parameters​

bits​

Bool[]

Returns​

AlmostForeignField

Inherited from​

ForeignField.fromBits

random()​

static random(): CanonicalForeignField;

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

Returns​

CanonicalForeignField

Inherited from​

ForeignField.random

sum()​

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

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

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.

Inherited from​

ForeignField.sum