Skip to main content
Version: 2.4.0

CanonicalForeignField

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

Extends​

  • ForeignFieldWithMul

Constructors​

new CanonicalForeignField()​

new CanonicalForeignField(x: 
  | string
  | number
  | bigint
  | Field3
  | CanonicalForeignField): CanonicalForeignField

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

Parameters​

x​

string | number | bigint | Field3 | CanonicalForeignField

Returns​

CanonicalForeignField

Overrides​

ForeignFieldWithMul.constructor

Properties​

type​

type: "FullyReduced";

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

value​

value: Field3;

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

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

Inherited from​

ForeignFieldWithMul.value

_Bigint​

static _Bigint: undefined | {} = undefined;

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

Inherited from​

ForeignFieldWithMul._Bigint

_modulus​

static _modulus: undefined | bigint = undefined;

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

Inherited from​

ForeignFieldWithMul._modulus

_provable​

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

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

Overrides​

ForeignFieldWithMul._provable

_variants​

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

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

Sibling classes that represent different ranges of field elements.

Inherited from​

ForeignFieldWithMul._variants

Accessors​

Constructor​

Get Signature​

get Constructor(): typeof ForeignField

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

Returns​

typeof ForeignField

Inherited from​

ForeignFieldWithMul.Constructor

modulus​

Get Signature​

get modulus(): bigint

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

Returns​

bigint

Inherited from​

ForeignFieldWithMul.modulus

AlmostReduced​

Get Signature​

get static AlmostReduced(): typeof AlmostForeignField

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

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

Returns​

typeof AlmostForeignField

Inherited from​

ForeignFieldWithMul.AlmostReduced

Bigint​

Get Signature​

get static Bigint(): {}

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

Returns​
{}

Inherited from​

ForeignFieldWithMul.Bigint

Canonical​

Get Signature​

get static Canonical(): typeof CanonicalForeignField

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

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

Returns​

typeof CanonicalForeignField

Inherited from​

ForeignFieldWithMul.Canonical

modulus​

Get Signature​

get static modulus(): bigint

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

Returns​

bigint

Inherited from​

ForeignFieldWithMul.modulus

provable​

Get Signature​

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

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

Provable<ForeignField>, see Provable

Returns​

ProvablePureExtended<CanonicalForeignField, bigint, string>

Overrides​

ForeignFieldWithMul.provable

sizeInBits​

Get Signature​

get static sizeInBits(): number

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

Returns​

number

Inherited from​

ForeignFieldWithMul.sizeInBits

Unreduced​

Get Signature​

get static Unreduced(): typeof UnreducedForeignField

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

Constructor for unreduced field elements.

Returns​

typeof UnreducedForeignField

Inherited from​

ForeignFieldWithMul.Unreduced

Methods​

add()​

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

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

Finite field addition

Parameters​

y​

number | bigint | ForeignField

Returns​

UnreducedForeignField

Example​

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

Inherited from​

ForeignFieldWithMul.add

assertAlmostReduced()​

assertAlmostReduced(): AlmostForeignField

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

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​

ForeignFieldWithMul.assertAlmostReduced

assertCanonical()​

assertCanonical(): CanonicalForeignField

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

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​

ForeignFieldWithMul.assertCanonical

assertEquals()​

Call Signature​

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

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

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​
ForeignFieldWithMul.assertEquals

Call Signature​

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

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

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​
ForeignFieldWithMul.assertEquals

Call Signature​

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

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

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​
ForeignFieldWithMul.assertEquals

assertLessThan()​

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

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

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​

ForeignFieldWithMul.assertLessThan

div()​

div(y: number | bigint | AlmostForeignField): AlmostForeignField

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

Division in the finite field, i.e. x*y^(-1) mod p where y^(-1) is the finite field inverse.

Parameters​

y​

number | bigint | AlmostForeignField

Returns​

AlmostForeignField

Example​

let z = x.div(y); // x/y mod p
z.mul(y).assertEquals(x);

Inherited from​

ForeignFieldWithMul.div

equals()​

equals(y: number | bigint | CanonicalForeignField): Bool

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

Check equality with a ForeignField-like value.

Parameters​

y​

number | bigint | CanonicalForeignField

Returns​

Bool

Example​

let isEqual = x.equals(y);

Note: This method only exists on canonical fields; on unreduced fields, it would be easy to misuse, because not being exactly equal does not imply being unequal modulo p.

inv()​

inv(): AlmostForeignField

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

Multiplicative inverse in the finite field

Returns​

AlmostForeignField

Example​

let z = x.inv(); // 1/x mod p
z.mul(x).assertEquals(1);

Inherited from​

ForeignFieldWithMul.inv

mul()​

mul(y: number | bigint | AlmostForeignField): UnreducedForeignField

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

Finite field multiplication

Parameters​

y​

number | bigint | AlmostForeignField

Returns​

UnreducedForeignField

Example​

x.mul(y); // x*y mod p

Inherited from​

ForeignFieldWithMul.mul

neg()​

neg(): AlmostForeignField

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

Finite field negation

Returns​

AlmostForeignField

Example​

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

Inherited from​

ForeignFieldWithMul.neg

sub()​

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

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

Finite field subtraction

Parameters​

y​

number | bigint | ForeignField

Returns​

UnreducedForeignField

Example​

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

Inherited from​

ForeignFieldWithMul.sub

toBigInt()​

toBigInt(): bigint

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

Convert this field element to a bigint.

Returns​

bigint

Inherited from​

ForeignFieldWithMul.toBigInt

toBits()​

toBits(length?: number): Bool[]

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

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

This method is provable!

Parameters​

length?​

number

Returns​

Bool[]

Inherited from​

ForeignFieldWithMul.toBits

toFields()​

toFields(): Field[]

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

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

Returns​

Field[]

Inherited from​

ForeignFieldWithMul.toFields

assertAlmostReduced()​

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

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

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 extends Tuple<ForeignField>

Parameters​

xs​

...T

Returns​

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

Inherited from​

ForeignFieldWithMul.assertAlmostReduced

check()​

static check(x: ForeignField): void

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

Parameters​

x​

ForeignField

Returns​

void

Overrides​

ForeignFieldWithMul.check

from()​

Call Signature​

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

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

Coerce the input to a ForeignField.

Parameters​
x​

string | number | bigint

Returns​

CanonicalForeignField

Inherited from​
ForeignFieldWithMul.from

Call Signature​

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

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

Coerce the input to a ForeignField.

Parameters​
x​

string | number | bigint | ForeignField

Returns​

ForeignField

Inherited from​
ForeignFieldWithMul.from

fromBits()​

static fromBits(bits: Bool[]): AlmostForeignField

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

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

This method is provable!

Parameters​

bits​

Bool[]

Returns​

AlmostForeignField

Inherited from​

ForeignFieldWithMul.fromBits

random()​

static random(): CanonicalForeignField

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

Returns​

CanonicalForeignField

Inherited from​

ForeignFieldWithMul.random

sum()​

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

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

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​

ForeignFieldWithMul.sum

unsafeFrom()​

static unsafeFrom(x: ForeignField): CanonicalForeignField

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

Coerce the input to a CanonicalForeignField without additional assertions.

Warning: Only use if you know what you're doing.

Parameters​

x​

ForeignField

Returns​

CanonicalForeignField