Skip to main content

Field

o1js / Modules / Field

Class: Field

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 (ORDER).

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

Example

Field(10n); // Field contruction 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.

Example

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

Table of contents

Constructors

Properties

Methods

Constructors

constructor

new Field(x)

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

Parameters

NameType
xstring | number | bigint | Uint8Array | FieldVar | Field

Defined in

lib/field.ts:143

Properties

value

value: FieldVar

Defined in

lib/field.ts:132


ORDER

Static ORDER: bigint = Fp.modulus

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

Defined in

lib/field.ts:138

Methods

#compare

Private #compare(y): Object

Parameters

NameType
yFieldVar

Returns

Object

NameType
lessBool
lessOrEqualBool

Defined in

lib/field.ts:656


#toConstant

Private #toConstant(name): ConstantField

Parameters

NameType
namestring

Returns

ConstantField

Defined in

lib/field.ts:203


add

add(y): Field

Add a "field-like" value to this Field element.

Example

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

sum.assertEquals(Field(8));

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

Example

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 (substraction) to prove the sum is calculated correctly.

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

Parameters

NameType
ystring | number | bigint | Field

Returns

Field

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

Defined in

lib/field.ts:311


assertBool

assertBool(message?): void

Assert that this Field is equal to 1 or 0 as a "field-like" value. Calling this function is equivalent to Bool.or(Field(...).equals(1), Field(...).equals(0)).assertEquals(Bool(true)).

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

Parameters

NameType
message?string

Returns

void

Defined in

lib/field.ts:920


assertEquals

assertEquals(y, message?): void

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

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

Parameters

NameType
ystring | number | bigint | Field
message?string

Returns

void

Defined in

lib/field.ts:269


assertGreaterThan

assertGreaterThan(y, message?): void

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

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

Warning: Comparison methods only support Field elements of size <= 253 bits in provable code. The method will throw if one of the inputs exceeds 253 bits.

Parameters

NameType
ystring | number | bigint | Field
message?string

Returns

void

Defined in

lib/field.ts:861


assertGreaterThanOrEqual

assertGreaterThanOrEqual(y, message?): void

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

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

Warning: Comparison methods only support Field elements of size <= 253 bits in provable code. The method will throw if one of the inputs exceeds 253 bits.

Parameters

NameType
ystring | number | bigint | Field
message?string

Returns

void

Defined in

lib/field.ts:878


assertLessThan

assertLessThan(y, message?): void

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

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

Warning: Comparison methods only support Field elements of size <= 253 bits in provable code. The method will throw if one of the inputs exceeds 253 bits.

Parameters

NameType
ystring | number | bigint | Field
message?string

Returns

void

Defined in

lib/field.ts:805


assertLessThanOrEqual

assertLessThanOrEqual(y, message?): void

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

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

Warning: Comparison methods only support Field elements of size <= 253 bits in provable code. The method will throw if one of the inputs exceeds 253 bits.

Parameters

NameType
ystring | number | bigint | Field
message?string

Returns

void

Defined in

lib/field.ts:833


assertNotEquals

assertNotEquals(y, message?): void

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

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

Example

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

Parameters

NameType
ystring | number | bigint | Field
message?string

Returns

void

Defined in

lib/field.ts:895


div

div(y): Field

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

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

Example

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.

Example

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

Parameters

NameType
ystring | number | bigint | Field

Returns

Field

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

Defined in

lib/field.ts:524


equals

equals(y): Bool

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.

Example

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

Parameters

NameType
ystring | number | bigint | Field

Returns

Bool

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

Defined in

lib/field.ts:636


greaterThan

greaterThan(y): Bool

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.

Example

Field(5).greaterThan(3).assertEquals(Bool(true));

Warning: Comparison methods currently only support Field elements of size <= 253 bits in provable code. The method will throw if one of the inputs exceeds 253 bits.

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.

Example

Field(1).div(Field(2)).greaterThan(Field(1).div(Field(3))).assertEquals(Bool(true)); // This code will throw an error

Parameters

NameType
ystring | number | bigint | Field

Returns

Bool

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

Defined in

lib/field.ts:759


greaterThanOrEqual

greaterThanOrEqual(y): Bool

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.

Example

Field(3).greaterThanOrEqual(3).assertEquals(Bool(true));

Warning: Comparison methods only support Field elements of size <= 253 bits in provable code. The method will throw if one of the inputs exceeds 253 bits.

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.

Example

Field(1).div(Field(2)).greaterThanOrEqual(Field(1).div(Field(3))).assertEquals(Bool(true)); // This code will throw an error

Parameters

NameType
ystring | number | bigint | Field

Returns

Bool

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

Defined in

lib/field.ts:787


inv

inv(): Field

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.

Example

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

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

Returns

Field

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

Defined in

lib/field.ts:476


isConstant

isConstant(): this is Object

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.

Example

console.log(Field(42).isConstant()); // true

Example

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

Returns

this is Object

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

Defined in

lib/field.ts:199


isEven

isEven(): Bool

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

Example

let a = Field(5);
a.isEven(); // false
a.isEven().assertTrue(); // throws, as expected!

let b = Field(4);
b.isEven(); // true
b.isEven().assertTrue(); // does not throw, as expected!

Returns

Bool

Defined in

lib/field.ts:393


isZero

isZero(): Bool

Deprecated

use x.equals(0) which is equivalent

Returns

Bool

Defined in

lib/field.ts:596


lessThan

lessThan(y): Bool

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.

Example

Field(2).lessThan(3).assertEquals(Bool(true));

Warning: Comparison methods only support Field elements of size <= 253 bits in provable code. The method will throw if one of the inputs exceeds 253 bits.

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.

Example

Field(1).div(Field(3)).lessThan(Field(1).div(Field(2))).assertEquals(Bool(true)); // This code will throw an error

Parameters

NameType
ystring | number | bigint | Field

Returns

Bool

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

Defined in

lib/field.ts:699


lessThanOrEqual

lessThanOrEqual(y): Bool

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.

Example

Field(3).lessThanOrEqual(3).assertEquals(Bool(true));

Warning: Comparison methods only support Field elements of size <= 253 bits in provable code. The method will throw if one of the inputs exceeds 253 bits.

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.

Example

Field(1).div(Field(3)).lessThanOrEqual(Field(1).div(Field(2))).assertEquals(Bool(true)); // This code will throw an error

Parameters

NameType
ystring | number | bigint | Field

Returns

Bool

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

Defined in

lib/field.ts:729


mul

mul(y): Field

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

Example

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

product.assertEquals(Field(15));

Parameters

NameType
ystring | number | bigint | Field

Returns

Field

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

Defined in

lib/field.ts:437


neg

neg(): Field

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

Example

const negOne = Field(1).neg();
negOne.assertEquals(-1);

Example

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.

Returns

Field

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

Defined in

lib/field.ts:339


rangeCheckHelper

rangeCheckHelper(length): Field

Create a new Field element from the first length bits of this Field element.

The length has to be a multiple of 16, and has to be between 0 and 255, otherwise the method throws.

As Field elements are represented using little endian binary representation, the resulting Field element will equal the original one if it fits in length bits.

Parameters

NameTypeDescription
lengthnumberThe number of bits to take from this Field element.

Returns

Field

A Field element that is equal to the length of this Field element.

Defined in

lib/field.ts:1012


seal

seal(): Field

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

Field

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

Defined in

lib/field.ts:1040


sqrt

sqrt(): Field

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.

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.

Returns

Field

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

Defined in

lib/field.ts:574


square

square(): Field

Square this Field element.

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.

Returns

Field

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

Defined in

lib/field.ts:544


sub

sub(y): Field

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

Example

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

difference.assertEquals(Field(-2));

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

Example

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 substraction (addition) to prove the difference is calculated correctly.
difference.add(Field(2)).assertEquals(x);

Parameters

NameType
ystring | number | bigint | Field

Returns

Field

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

Defined in

lib/field.ts:375


toAuxiliary

toAuxiliary(): []

This function is the implementation of 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

[]

Defined in

lib/field.ts:1148


toBigInt

toBigInt(): bigint

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.

Example

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

Returns

bigint

A bigint equivalent to the bigint representation of the Field.

Defined in

lib/field.ts:237


toBits

toBits(length?): Bool[]

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 255 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 255 bits. Prefer to pass a smaller length if possible.

Parameters

NameTypeDescription
length?numberthe 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.

Defined in

lib/field.ts:957


toConstant

toConstant(): ConstantField

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

Example

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

Returns

ConstantField

A constant Field element equivalent to this Field element.

Defined in

lib/field.ts:220


toFields

toFields(): Field[]

This function is the implementation of 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.

Defined in

lib/field.ts:1139


toJSON

toJSON(): string

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.

Example

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

Returns

string

A string equivalent to the JSON representation of the Field.

Defined in

lib/field.ts:1167


toString

toString(): string

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.

Example

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

Returns

string

A string equivalent to the string representation of the Field.

Defined in

lib/field.ts:255


#checkBitLength

Static Private #checkBitLength(name, length): void

Parameters

NameType
namestring
lengthnumber

Returns

void

Defined in

lib/field.ts:935


#isField

Static Private #isField(x): x is Field

Parameters

NameType
xstring | number | bigint | Uint8Array | FieldVar | Field

Returns

x is Field

Defined in

lib/field.ts:163


#toConst

Static Private #toConst(x): Uint8Array

Parameters

NameType
xstring | number | bigint | ConstantField

Returns

Uint8Array

Defined in

lib/field.ts:168


#toVar

Static Private #toVar(x): FieldVar

Parameters

NameType
xstring | number | bigint | Field

Returns

FieldVar

Defined in

lib/field.ts:172


check

Static check(): void

This function is the implementation of 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

Defined in

lib/field.ts:1130


from

Static from(x): Field

Parameters

NameType
xstring | number | bigint | Field

Returns

Field

Defined in

lib/field.ts:176


fromBits

Static fromBits(bits): Field

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. A Field element can be at most 255 bits.

Important: If the given bytes 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

NameType
bits(boolean | Bool)[]

Returns

Field

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

Defined in

lib/field.ts:983


fromBytes

Static fromBytes(bytes): Field

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

NameTypeDescription
bytesnumber[]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.

Defined in

lib/field.ts:1254


fromFields

Static fromFields(fields): Field

Implementation of 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

NameTypeDescription
fieldsField[]an array of length 1 serialized from Field elements.

Returns

Field

The first Field element of the given array.

Defined in

lib/field.ts:1119


fromJSON

Static fromJSON(json): Field

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

NameType
jsonstring

Returns

Field

A Field coerced from the given JSON string.

Defined in

lib/field.ts:1199


random

Static random(): Field

A random Field element.

Example

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

Returns

Field

A random Field element.

Defined in

lib/field.ts:1058


readBytes

Static readBytes<N>(bytes, offset): [value: Field, offset: number]

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

NameType
Nextends number

Parameters

NameType
bytesnumber[]
offsetNonNegativeInteger<N>

Returns

[value: Field, offset: number]

Defined in

lib/field.ts:1237


sizeInBytes

Static sizeInBytes(): number

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

As all Field elements have 31 bits, this function returns 31.

Returns

number

The size of a Field element - 31.

Defined in

lib/field.ts:1265


sizeInFields

Static sizeInFields(): number

This function is the implementation of 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.

Example

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

Returns

number

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

Defined in

lib/field.ts:1104


toAuxiliary

Static toAuxiliary(): []

This function is the implementation of 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

[]

Defined in

lib/field.ts:1087


toBytes

Static toBytes(x): number[]

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

Parameters

NameType
xField

Returns

number[]

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

Defined in

lib/field.ts:1228


toFields

Static toFields(x): Field[]

This function is the implementation of 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

NameType
xField

Returns

Field[]

A Field array of length 1 created from this Field.

Defined in

lib/field.ts:1076


toInput

Static toInput(x): Object

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

NameType
xField

Returns

Object

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

NameType
fieldsField[]

Defined in

lib/field.ts:1213


toJSON

Static toJSON(x): string

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.

Example

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

Parameters

NameType
xField

Returns

string

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

Defined in

lib/field.ts:1186