Skip to main content

Field

Defined in: lib/provable/field.ts:74

A Field is an element of a prime order finite field. Every other provable type is built using the Field type.

The field is the pasta base field of order 2^254 + 0x224698fc094cf91b992d30ed00000001 (Field.ORDER).

You can create a new Field from everything "field-like" (bigint, integer number, decimal string, Field).

Examples

Field(10n); // Field construction from a big integer
Field(100); // Field construction from a number
Field("1"); // Field construction from a decimal string

Beware: Fields cannot be constructed from fractional numbers or alphanumeric strings:

Field(3.141); // ERROR: Cannot convert a float to a field element
Field("abc"); // ERROR: Invalid argument "abc"

Creating a Field from a negative number can result in unexpected behavior if you are not familiar with modular arithmetic.

const x = Field(-1); // Valid Field construction from negative number
const y = Field(Field.ORDER - 1n); // equivalent to `x`

Important: All the functions defined on a Field (arithmetic, logic, etc.) take their arguments as "field-like". A Field itself is also defined as a "field-like" element.

Param

the value to convert to a Field

Constructors

new Field()

new Field(x: string | number | bigint | FieldConst | FieldVar | Field): Field

Defined in: lib/provable/field.ts:86

Coerce anything "field-like" (bigint, number, string, and Field) to a Field.

Parameters

x

string | number | bigint | FieldConst | FieldVar | Field

Returns

Field

Properties

value

value: FieldVar;

Defined in: lib/provable/field.ts:75


ORDER

static ORDER: bigint = Fp.modulus;

Defined in: lib/provable/field.ts:81

The order of the pasta curve that Field type build on as a bigint. Order of the Field is 28948022309329048855892746252171976963363056481941560715954676764349967630337.


sizeInBits

static sizeInBits: number = Fp.sizeInBits;

Defined in: lib/provable/field.ts:1100

The size of a Field element in bits - 255.


sizeInBytes

static sizeInBytes: number = BinableFp.sizeInBytes;

Defined in: lib/provable/field.ts:1095

The size of a Field element in bytes - 32.

Methods

add()

add(y: string | number | bigint | Field): Field

Defined in: lib/provable/field.ts:239

Add a field-like value to this Field element.

Parameters

y

a "field-like" value to add to the Field.

string | number | bigint | Field

Returns

Field

A Field element equivalent to the modular addition of the two value.

Examples

const x = Field(3);
const sum = x.add(5);

sum.assertEquals(Field(8));

Warning: This is a modular addition in the pasta field.

const x = Field(1);
const sum = x.add(Field(-7));

// If you try to print sum - `console.log(sum.toBigInt())` - you will realize that it prints a very big integer because this is modular arithmetic, and 1 + (-7) circles around the field to become p - 6.
// You can use the reverse operation of addition (subtraction) to prove the sum is calculated correctly.

sum.sub(x).assertEquals(Field(-7));
sum.sub(Field(-7)).assertEquals(x);

assertBool()

assertBool(message?: string): Bool

Defined in: lib/provable/field.ts:767

Prove that this Field is equal to 0 or 1. Returns the Field wrapped in a Bool.

If the assertion fails, the code throws an error.

Parameters

message?

string

a string error message to print if the assertion fails, optional.

Returns

Bool


assertEquals()

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

Defined in: lib/provable/field.ts:197

Assert that this Field is equal another "field-like" value. Calling this function is equivalent to Field(...).equals(...).assertEquals(Bool(true)). See Field.equals for more details.

Important: If an assertion fails, the code throws an error.

Parameters

y

the "field-like" value to compare & assert with this Field.

string | number | bigint | Field

message?

string

a string error message to print if the assertion fails, optional.

Returns

void


assertGreaterThan()

assertGreaterThan(y: string | number | bigint | Field, message?: string): void

Defined in: lib/provable/field.ts:701

Assert that this Field is greater than another "field-like" value.

Note: This uses fewer constraints than x.greaterThan(y).assertTrue(). See Field.greaterThan for more details.

Important: If an assertion fails, the code throws an error.

Parameters

y

the "field-like" value to compare & assert with this Field.

string | number | bigint | Field

message?

string

a string error message to print if the assertion fails, optional.

Returns

void


assertGreaterThanOrEqual()

assertGreaterThanOrEqual(y: string | number | bigint | Field, message?: string): void

Defined in: lib/provable/field.ts:716

Assert that this Field is greater than or equal to another "field-like" value.

Note: This uses fewer constraints than x.greaterThanOrEqual(y).assertTrue(). See Field.greaterThanOrEqual for more details.

Important: If an assertion fails, the code throws an error.

Parameters

y

the "field-like" value to compare & assert with this Field.

string | number | bigint | Field

message?

string

a string error message to print if the assertion fails, optional.

Returns

void


assertLessThan()

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

Defined in: lib/provable/field.ts:651

Assert that this Field is less than another "field-like" value.

Note: This uses fewer constraints than x.lessThan(y).assertTrue(). See lessThan for more details.

Important: If an assertion fails, the code throws an error.

Parameters

y

the "field-like" value to compare & assert with this Field.

string | number | bigint | Field

message?

string

a string error message to print if the assertion fails, optional.

Returns

void


assertLessThanOrEqual()

assertLessThanOrEqual(y: string | number | bigint | Field, message?: string): void

Defined in: lib/provable/field.ts:676

Assert that this Field is less than or equal to another "field-like" value.

Note: This uses fewer constraints than x.lessThanOrEqual(y).assertTrue(). See Field.lessThanOrEqual for more details.

Important: If an assertion fails, the code throws an error.

Parameters

y

the "field-like" value to compare & assert with this Field.

string | number | bigint | Field

message?

string

a string error message to print if the assertion fails, optional.

Returns

void


assertNotEquals()

assertNotEquals(y: string | number | bigint | Field, message?: string): void

Defined in: lib/provable/field.ts:733

Assert that this Field does not equal another field-like value.

Note: This uses fewer constraints than x.equals(y).assertFalse().

Parameters

y

the "field-like" value to compare & assert with this Field.

string | number | bigint | Field

message?

string

a string error message to print if the assertion fails, optional.

Returns

void

Example

x.assertNotEquals(0, "expect x to be non-zero");

div()

div(y: string | number | bigint | Field): Field

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

Divide another "field-like" value through this Field.

Proves that the denominator is non-zero, or throws a "Division by zero" error.

Parameters

y

a "field-like" value to divide with the Field.

string | number | bigint | Field

Returns

Field

A Field element equivalent to the modular division of the two value.

Examples

const x = Field(6);
const quotient = x.div(Field(3));

quotient.assertEquals(Field(2));

Warning: This is a modular division in the pasta field. You can think this as the reverse operation of modular multiplication.

const x = Field(2);
const y = Field(5);

const quotient = x.div(y);

// If you try to print quotient - `console.log(quotient.toBigInt())` - you will realize that it prints a very big integer because this is a modular inverse.
// You can use the reverse operation of division (multiplication) to prove the quotient is calculated correctly.

quotient.mul(y).assertEquals(x);

equals()

equals(y: string | number | bigint | Field): Bool

Defined in: lib/provable/field.ts:509

Check if this Field is equal another "field-like" value. Returns a Bool, which is a provable type and can be used to prove the validity of this statement.

Parameters

y

the "field-like" value to compare with this Field.

string | number | bigint | Field

Returns

Bool

A Bool representing if this Field is equal another "field-like" value.

Example

Field(5).equals(5).assertEquals(Bool(true));

greaterThan()

greaterThan(y: string | number | bigint | Field): Bool

Defined in: lib/provable/field.ts:612

Check if this Field is greater than another "field-like" value. Returns a Bool, which is a provable type and can be used to prove the validity of this statement.

Parameters

y

the "field-like" value to compare with this Field.

string | number | bigint | Field

Returns

Bool

A Bool representing if this Field is greater than another "field-like" value.

Examples

let isTrue = Field(5).greaterThan(3);

Warning: As this method compares the bigint value of a Field, it can result in unexpected behaviour when used with negative inputs or modular division.

let isFalse = Field(1).div(2).greaterThan(Field(1).div(3); // in fact, 1/3 > 1/2

greaterThanOrEqual()

greaterThanOrEqual(y: string | number | bigint | Field): Bool

Defined in: lib/provable/field.ts:636

Check if this Field is greater than or equal another "field-like" value. Returns a Bool, which is a provable type and can be used to prove the validity of this statement.

Parameters

y

the "field-like" value to compare with this Field.

string | number | bigint | Field

Returns

Bool

A Bool representing if this Field is greater than or equal another "field-like" value.

Examples

let isTrue = Field(3).greaterThanOrEqual(3);

Warning: As this method compares the bigint value of a Field, it can result in unexpected behaviour when used with negative inputs or modular division.

let isFalse = Field(1).div(2).greaterThanOrEqual(Field(1).div(3); // in fact, 1/3 > 1/2

inv()

inv(): Field

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

Modular inverse of this Field element. Equivalent to 1 divided by this Field, in the sense of modular arithmetic.

Proves that this Field is non-zero, or throws a "Division by zero" error.

Returns

Field

A Field element that is equivalent to one divided by this element.

Example

const someField = Field(42);
const inverse = someField.inv();
inverse.assertEquals(Field(1).div(someField)); // This statement is always true regardless of the value of `someField`

Warning: This is a modular inverse. See div method for more details.


isConstant()

isConstant(): this is { value: ConstantFieldVar }

Defined in: lib/provable/field.ts:131

Check whether this Field element is a hard-coded constant in the constraint system. If a Field is constructed outside a zkApp method, it is a constant.

Returns

this is { value: ConstantFieldVar }

A boolean showing if this Field is a constant or not.

Examples

console.log(Field(42).isConstant()); // true
\@method myMethod(x: Field) {
console.log(x.isConstant()); // false
}

isEven()

isEven(): Bool

Defined in: lib/provable/field.ts:328

Checks if this Field is even. Returns true for even elements and false for odd elements.

Returns

Bool

Example

let a = Field(5);
a.isEven(); // false

let b = Field(4);
b.isEven(); // true

isOdd()

isOdd(): Bool

Defined in: lib/provable/field.ts:312

Checks if this Field is odd. Returns true for odd elements and false for even elements.

See Field.isEven for examples.

Returns

Bool


lessThan()

lessThan(y: string | number | bigint | Field): Bool

Defined in: lib/provable/field.ts:558

Check if this Field is less than another "field-like" value. Returns a Bool, which is a provable type and can be used prove to the validity of this statement.

Parameters

y

the "field-like" value to compare with this Field.

string | number | bigint | Field

Returns

Bool

A Bool representing if this Field is less than another "field-like" value.

Examples

let isTrue = Field(2).lessThan(3);

Warning: As this method compares the bigint value of a Field, it can result in unexpected behavior when used with negative inputs or modular division.

let isFalse = Field(1).div(3).lessThan(Field(1).div(2)); // in fact, 1/3 > 1/2

lessThanOrEqual()

lessThanOrEqual(y: string | number | bigint | Field): Bool

Defined in: lib/provable/field.ts:585

Check if this Field is less than or equal to another "field-like" value. Returns a Bool, which is a provable type and can be used to prove the validity of this statement.

Parameters

y

the "field-like" value to compare with this Field.

string | number | bigint | Field

Returns

Bool

A Bool representing if this Field is less than or equal another "field-like" value.

Examples

let isTrue = Field(3).lessThanOrEqual(3);

Warning: As this method compares the bigint value of a Field, it can result in unexpected behaviour when used with negative inputs or modular division.

let isFalse = Field(1).div(3).lessThanOrEqual(Field(1).div(2)); // in fact, 1/3 > 1/2

mul()

mul(y: string | number | bigint | Field): Field

Defined in: lib/provable/field.ts:347

Multiply another "field-like" value with this Field element.

Parameters

y

a "field-like" value to multiply with the Field.

string | number | bigint | Field

Returns

Field

A Field element equivalent to the modular difference of the two value.

Example

const x = Field(3);
const product = x.mul(Field(5));

product.assertEquals(Field(15));

neg()

neg(): Field

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

Negate a Field. This is equivalent to multiplying the Field by -1.

Returns

Field

A Field element that is equivalent to the element multiplied by -1.

Examples

const negOne = Field(1).neg();
negOne.assertEquals(-1);
const someField = Field(42);
someField.neg().assertEquals(someField.mul(Field(-1))); // This statement is always true regardless of the value of `someField`

Warning: This is a modular negation. For details, see the sub method.


seal()

seal(): 
| VarField
| ConstantField

Defined in: lib/provable/field.ts:850

Warning: This function is mainly for internal use. Normally it is not intended to be used by a zkApp developer.

In o1js, addition and scaling (multiplication of variables by a constant) of variables is represented as an AST - abstract syntax tree. For example, the expression x.add(y).mul(2) is represented as Scale(2, Add(x, y)).

A new internal variable is created only when the variable is needed in a multiplicative or any higher level constraint (for example multiplication of two Field elements) to represent the operation.

The seal() function tells o1js to stop building an AST and create a new variable right away.

Returns

| VarField | ConstantField

A Field element that is equal to the result of AST that was previously on this Field element.


sqrt()

sqrt(): Field

Defined in: lib/provable/field.ts:481

Take the square root of this Field element.

Proves that the Field element has a square root in the finite field, or throws if it doesn't.

Returns

Field

A Field element equivalent to the square root of the Field element.

Example

let z = x.sqrt();
z.mul(z).assertEquals(x); // true for every `x`

Warning: This is a modular square root, which is any number z that satisfies z*z = x (mod p). Note that, if a square root z exists, there also exists a second one, -z (which is different if z != 0). Therefore, this method leaves an adversarial prover the choice between two different values to return.


square()

square(): Field

Defined in: lib/provable/field.ts:452

Square this Field element.

Returns

Field

A Field element equivalent to the multiplication of the Field element with itself.

Example

const someField = Field(7);
const square = someField.square();

square.assertEquals(someField.mul(someField)); // This statement is always true regardless of the value of `someField`

** Warning: This is a modular multiplication. See mul() method for more details.


sub()

sub(y: string | number | bigint | Field): Field

Defined in: lib/provable/field.ts:303

Subtract another "field-like" value from this Field element.

Parameters

y

a "field-like" value to subtract from the Field.

string | number | bigint | Field

Returns

Field

A Field element equivalent to the modular difference of the two value.

Examples

const x = Field(3);
const difference = x.sub(5);

difference.assertEquals(Field(-2));

Warning: This is a modular subtraction in the pasta field.

const x = Field(1);
const difference = x.sub(Field(2));

// If you try to print difference - `console.log(difference.toBigInt())` - you will realize that it prints a very big integer because this is modular arithmetic, and 1 - 2 circles around the field to become p - 1.
// You can use the reverse operation of subtraction (addition) to prove the difference is calculated correctly.
difference.add(Field(2)).assertEquals(x);

toAuxiliary()

toAuxiliary(): []

Defined in: lib/provable/field.ts:979

This function is the implementation of Provable.toAuxiliary for the Field type.

As the primitive Field type has no auxiliary data associated with it, this function will always return an empty array.

Returns

[]


toBigInt()

toBigInt(): bigint

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

Serialize the Field to a bigint, e.g. for printing. Trying to print a Field without this function will directly stringify the Field object, resulting in unreadable output.

Warning: This operation does not affect the circuit and can't be used to prove anything about the bigint representation of the Field. Use the operation only during debugging.

Returns

bigint

A bigint equivalent to the bigint representation of the Field.

Example

const someField = Field(42);
console.log(someField.toBigInt());

toBits()

toBits(length: number): Bool[]

Defined in: lib/provable/field.ts:794

Returns an array of Bool elements representing little endian binary representation of this Field element.

If you use the optional length argument, proves that the field element fits in length bits. The length has to be between 0 and 254 and the method throws if it isn't.

Warning: The cost of this operation in a zk proof depends on the length you specify, which by default is 254 bits. Prefer to pass a smaller length if possible.

Parameters

length

number = 254

the number of bits to fit the element. If the element does not fit in length bits, the functions throws an error.

Returns

Bool[]

An array of Bool element representing little endian binary representation of this Field.


toConstant()

toConstant(): ConstantField

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

Create a Field element equivalent to this Field element's value, but is a constant. See Field.isConstant for more information about what is a constant Field.

Returns

ConstantField

A constant Field element equivalent to this Field element.

Example

const someField = Field(42);
someField.toConstant().assertEquals(someField); // Always true

toFields()

toFields(): Field[]

Defined in: lib/provable/field.ts:970

This function is the implementation of Provable.toFields for the Field type.

The result will be always an array of length 1, where the first and only element equals the Field itself.

Returns

Field[]

A Field array of length 1 created from this Field.


toJSON()

toJSON(): string

Defined in: lib/provable/field.ts:1002

Serialize the Field to a JSON string, e.g. for printing. Trying to print a Field without this function will directly stringify the Field object, resulting in unreadable output.

Warning: This operation does not affect the circuit and can't be used to prove anything about the JSON string representation of the Field. Use the operation only during debugging.

Returns

string

A string equivalent to the JSON representation of the Field.

Example

const someField = Field(42);
console.log(someField.toJSON());

toString()

toString(): string

Defined in: lib/provable/field.ts:183

Serialize the Field to a string, e.g. for printing. Trying to print a Field without this function will directly stringify the Field object, resulting in unreadable output.

Warning: This operation does not affect the circuit and can't be used to prove anything about the string representation of the Field. Use the operation only during debugging.

Returns

string

A string equivalent to the string representation of the Field.

Example

const someField = Field(42);
console.log(someField.toString());

check()

static check(): void

Defined in: lib/provable/field.ts:940

This function is the implementation of Provable.check in Field type.

As any field element can be a Field, this function does not create any assertions, so it does nothing.

Returns

void


empty()

static empty(): Field

Defined in: lib/provable/field.ts:985

Returns

Field


from()

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

Defined in: lib/provable/field.ts:108

Parameters

x

string | number | bigint | Field

Returns

Field


fromBits()

static fromBits(bits: (boolean | Bool)[]): Field

Defined in: lib/provable/field.ts:821

Convert a bit array into a Field element using little endian binary representation

The method throws if the given bits do not fit in a single Field element. In this case, no more than 254 bits are allowed because some 255 bit integers do not fit into a single Field element.

Important: If the given bits array is an array of booleans or Bool elements that all are constant, the resulting Field element will be a constant as well. Or else, if the given array is a mixture of constants and variables of Bool type, the resulting Field will be a variable as well.

Parameters

bits

(boolean | Bool)[]

An array of Bool or boolean type.

Returns

Field

A Field element matching the little endian binary representation of the given bits array.


fromBytes()

static fromBytes(bytes: number[]): Field

Defined in: lib/provable/field.ts:1088

Coerce a new Field element using the little-endian representation of the given bytes array. Note that the given bytes array may have at most 32 elements as the Field is a finite-field in the order of Field.ORDER.

Warning: This operation does not affect the circuit and can't be used to prove anything about the byte representation of the Field.

Parameters

bytes

number[]

The bytes array to coerce the Field from.

Returns

Field

A new Field element created using the little-endian representation of the given bytes array.


fromFields()

static fromFields(fields: Field[]): Field

Defined in: lib/provable/field.ts:931

Implementation of Provable.fromFields for the Field type.

Warning: This function is designed for internal use. It is not intended to be used by a zkApp developer.

Creates a Field from an array of Fields of length 1.

Parameters

fields

Field[]

an array of length 1 serialized from Field elements.

Returns

Field

The first Field element of the given array.


fromJSON()

static fromJSON(json: string): Field

Defined in: lib/provable/field.ts:1034

Deserialize a JSON string containing a "field-like" value into a Field element.

Warning: This operation does not affect the circuit and can't be used to prove anything about the string representation of the Field.

Parameters

json

string

the "field-like" value to coerce the Field from.

Returns

Field

A Field coerced from the given JSON string.


fromValue()

static fromValue(x: string | number | bigint | Field): Field

Defined in: lib/provable/field.ts:959

Provable<Field>.fromValue()

Parameters

x

string | number | bigint | Field

Returns

Field


random()

static random(): Field

Defined in: lib/provable/field.ts:872

A random Field element.

Returns

Field

A random Field element.

Example

console.log(Field.random().toBigInt()); // Run this code twice!

readBytes()

static readBytes<N>(bytes: number[], offset: NonNegativeInteger<N>): [Field, number]

Defined in: lib/provable/field.ts:1074

Part of the Binable interface.

Warning: This function is for internal use. It is not intended to be used by a zkApp developer.

Type Parameters

N extends number

Parameters

bytes

number[]

offset

NonNegativeInteger<N>

Returns

[Field, number]


sizeInFields()

static sizeInFields(): number

Defined in: lib/provable/field.ts:916

This function is the implementation of Provable.sizeInFields for the Field type.

Size of the Field type is 1, as it is the primitive type. This function returns a regular number, so you cannot use it to prove something on chain. You can use it during debugging or to understand the memory complexity of some type.

Returns

number

A number representing the size of the Field type in terms of Field type itself.

Example

console.log(Field.sizeInFields()); // Prints 1

toAuxiliary()

static toAuxiliary(): []

Defined in: lib/provable/field.ts:899

This function is the implementation of Provable.toAuxiliary for the Field type.

As the primitive Field type has no auxiliary data associated with it, this function will always return an empty array.

Returns

[]


toBigint()

static toBigint(x: Field): bigint

Defined in: lib/provable/field.ts:952

Convert a Field element to a bigint.

Parameters

x

Field

Returns

bigint


toBytes()

static toBytes(value: Field): number[]

Defined in: lib/provable/field.ts:1065

Create an array of digits equal to the little-endian byte order of the given Field element. Note that the array has always 32 elements as the Field is a finite-field in the order of Field.ORDER.

Warning: This operation does not affect the circuit and can't be used to prove anything about the byte representation of the Field.

Parameters

value

Field

The Field element to generate the array of bytes of.

Returns

number[]

An array of digits equal to the little-endian byte order of the given Field element.


toFields()

static toFields(value: Field): Field[]

Defined in: lib/provable/field.ts:890

This function is the implementation of Provable.toFields for the Field type.

Static function to serializes a Field into an array of Field elements. This will be always an array of length 1, where the first and only element equals the given parameter itself.

Parameters

value

Field

the Field element to cast the array from.

Returns

Field[]

A Field array of length 1 created from this Field.


toInput()

static toInput(value: Field): {
fields: Field[];
}

Defined in: lib/provable/field.ts:1048

Warning: This function is mainly for internal use. Normally it is not intended to be used by a zkApp developer.

This function is the implementation of ProvableExtended.toInput() for the Field type.

Parameters

value

Field

The Field element to get the input array.

Returns

{
fields: Field[];
}

An object where the fields key is a Field array of length 1 created from this Field.

fields
fields: Field[];

toJSON()

static toJSON(value: Field): string

Defined in: lib/provable/field.ts:1021

Serialize the given Field element to a JSON string, e.g. for printing. Trying to print a Field without this function will directly stringify the Field object, resulting in unreadable output.

Warning: This operation does not affect the circuit and can't be used to prove anything about the JSON string representation of the Field. Use the operation only during debugging.

Parameters

value

Field

The JSON string to coerce the Field from.

Returns

string

A string equivalent to the JSON representation of the given Field.

Example

const someField = Field(42);
console.log(Field.toJSON(someField));

toValue()

static toValue(x: Field): bigint

Defined in: lib/provable/field.ts:945

Provable<Field>.toValue()

Parameters

x

Field

Returns

bigint