Skip to main content

CanonicalForeignField

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

Extends​

  • ForeignFieldWithMul

Constructors​

Constructor​

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

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

Parameters​

x​

string | number | bigint | Field3 | CanonicalForeignField

Returns​

CanonicalForeignField

Overrides​

ForeignFieldWithMul.constructor

Properties​

type​

type: "FullyReduced";

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

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​

ForeignFieldWithMul.value

_Bigint​

static _Bigint: 
  | undefined
  | {
} = undefined;

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

Inherited from​

ForeignFieldWithMul._Bigint

_modulus​

static _modulus: undefined | bigint = undefined;

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

Inherited from​

ForeignFieldWithMul._modulus

_provable​

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

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

Overrides​

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

ForeignFieldWithMul._variants

Accessors​

Constructor​

Get Signature​

get Constructor(): typeof ForeignField;

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

Returns​

typeof ForeignField

Inherited from​

ForeignFieldWithMul.Constructor

modulus​

Get Signature​

get modulus(): bigint;

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

Returns​

bigint

Inherited from​

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

ForeignFieldWithMul.AlmostReduced

Bigint​

Get Signature​

get static Bigint(): {
};

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

Returns​
{
}

Inherited from​

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

ForeignFieldWithMul.Canonical

modulus​

Get Signature​

get static modulus(): bigint;

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

Returns​

bigint

Inherited from​

ForeignFieldWithMul.modulus

provable​

Get Signature​

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

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

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:33

Returns​

number

Inherited from​

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

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

ForeignFieldWithMul.Unsafe

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

Inherited from​

ForeignFieldWithMul.add

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

Inherited from​

ForeignFieldWithMul.assertAlmostReduced

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

Inherited from​

ForeignFieldWithMul.assertCanonical

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

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

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

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

Inherited from​

ForeignFieldWithMul.assertLessThan

div()​

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

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

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:580

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:464

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

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

Inherited from​

ForeignFieldWithMul.isConstant

mul()​

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

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

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:252

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:267

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:179

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:375

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

This method is provable!

Parameters​

length?​

number

Returns​

Bool[]

Inherited from​

ForeignFieldWithMul.toBits

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

Inherited from​

ForeignFieldWithMul.toConstant

toFields()​

toFields(): Field[];

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

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

Inherited from​

ForeignFieldWithMul.assertAlmostReduced

check()​

static check(x: ForeignField): void;

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

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: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​
ForeignFieldWithMul.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​
ForeignFieldWithMul.from

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

Inherited from​

ForeignFieldWithMul.fromBits

random()​

static random(): CanonicalForeignField;

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

Returns​

CanonicalForeignField

Inherited from​

ForeignFieldWithMul.random

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.

Inherited from​

ForeignFieldWithMul.sum

unsafeFrom()​

static unsafeFrom(x: ForeignField): CanonicalForeignField;

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

Coerce the input to a CanonicalForeignField without additional assertions.

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

Parameters​

x​

ForeignField

Returns​

CanonicalForeignField