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 (Field.ORDER).
You can create a new Field from everything "field-like" (bigint
, integer number
, decimal string
, Field
).
Example
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.
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
Constructors
new Field()
new Field(x:
| string
| number
| bigint
| FieldConst
| FieldVar
| Field): Field
Coerce anything "field-like" (bigint, number, string, and Field) to a Field.
Parameters
• x:
| string
| number
| bigint
| FieldConst
| FieldVar
| Field
Returns
Source
Properties
value
value: FieldVar;
Source
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.
Source
sizeInBits
static sizeInBits: number = Fp.sizeInBits;
The size of a Field element in bits - 255.
Source
sizeInBytes
static sizeInBytes: number = BinableFp.sizeInBytes;
The size of a Field element in bytes - 32.
Source
Methods
add()
add(y: string | number | bigint | Field): Field
Add a field-like value to this Field element.
Parameters
• y: string
| number
| bigint
| Field
Returns
A Field element equivalent to the modular addition of the two value.
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 (subtraction) to prove the sum is calculated correctly.
sum.sub(x).assertEquals(Field(-7));
sum.sub(Field(-7)).assertEquals(x);
Source
assertBool()
assertBool(message?: string): Bool
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
Returns
Source
assertEquals()
assertEquals(y: string | number | bigint | Field, message?: string): void
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: string
| number
| bigint
| Field
• message?: string
Returns
void
Source
assertGreaterThan()
assertGreaterThan(y: string | number | bigint | Field, message?: string): void
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: string
| number
| bigint
| Field
• message?: string
Returns
void
Source
assertGreaterThanOrEqual()
assertGreaterThanOrEqual(y: string | number | bigint | Field, message?: string): void
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: string
| number
| bigint
| Field
• message?: string
Returns
void
Source
assertLessThan()
assertLessThan(y: string | number | bigint | Field, message?: string): void
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: string
| number
| bigint
| Field
• message?: string
Returns
void
Source
assertLessThanOrEqual()
assertLessThanOrEqual(y: string | number | bigint | Field, message?: string): void
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: string
| number
| bigint
| Field
• message?: string
Returns
void
Source
assertNotEquals()
assertNotEquals(y: string | number | bigint | Field, message?: string): void
Assert that this Field does not equal another field-like value.
Note: This uses fewer constraints than x.equals(y).assertFalse()
.
Parameters
• y: string
| number
| bigint
| Field
• message?: string
Returns
void
Example
x.assertNotEquals(0, "expect x to be non-zero");
Source
div()
div(y: string | number | bigint | Field): Field
Divide another "field-like" value through this Field.
Proves that the denominator is non-zero, or throws a "Division by zero" error.
Parameters
• y: string
| number
| bigint
| Field
Returns
A Field element equivalent to the modular division of the two value.
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);
Source
equals()
equals(y: string | number | bigint | Field): 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.
Parameters
• y: string
| number
| bigint
| Field
Returns
A Bool representing if this Field is equal another "field-like" value.
Example
Field(5).equals(5).assertEquals(Bool(true));
Source
greaterThan()
greaterThan(y: string | number | bigint | Field): 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.
Parameters
• y: string
| number
| bigint
| Field
Returns
A Bool representing if this Field is greater than another "field-like" value.
Example
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.
Example
let isFalse = Field(1).div(2).greaterThan(Field(1).div(3); // in fact, 1/3 > 1/2
Source
greaterThanOrEqual()
greaterThanOrEqual(y: string | number | bigint | Field): 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.
Parameters
• y: string
| number
| bigint
| Field
Returns
A Bool representing if this Field is greater than or equal another "field-like" value.
Example
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.
Example
let isFalse = Field(1).div(2).greaterThanOrEqual(Field(1).div(3); // in fact, 1/3 > 1/2
Source
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.
Returns
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.
Source
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.
Returns
this is Object
A boolean
showing if this Field is a constant or not.
Example
console.log(Field(42).isConstant()); // true
Example
\@method myMethod(x: Field) {
console.log(x.isConstant()); // false
}
Source
isEven()
isEven(): Bool
Checks if this Field is even. Returns true
for even elements and false
for odd elements.
Returns
Example
let a = Field(5);
a.isEven(); // false
let b = Field(4);
b.isEven(); // true
Source
isOdd()
isOdd(): Bool
Checks if this Field is odd. Returns true
for odd elements and false
for even elements.
See Field.isEven for examples.
Returns
Source
lessThan()
lessThan(y: string | number | bigint | Field): 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.
Parameters
• y: string
| number
| bigint
| Field
Returns
A Bool representing if this Field is less than another "field-like" value.
Example
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.
Example
let isFalse = Field(1).div(3).lessThan(Field(1).div(2)); // in fact, 1/3 > 1/2
Source
lessThanOrEqual()
lessThanOrEqual(y: string | number | bigint | Field): 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.
Parameters
• y: string
| number
| bigint
| Field
Returns
A Bool representing if this Field is less than or equal another "field-like" value.
Example
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.
Example
let isFalse = Field(1).div(3).lessThanOrEqual(Field(1).div(2)); // in fact, 1/3 > 1/2
Source
mul()
mul(y: string | number | bigint | Field): Field
Multiply another "field-like" value with this Field element.
Parameters
• y: string
| number
| bigint
| Field
Returns
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));
Source
neg()
neg(): Field
Negate a Field. This is equivalent to multiplying the Field by -1.
Returns
A Field element that is equivalent to the element multiplied 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.
Source
seal()
seal(): VarField | ConstantField
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
A Field element that is equal to the result of AST that was previously on this Field element.
Source
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.
Returns
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.
Source
square()
square(): Field
Square this Field element.
Returns
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.
Source
sub()
sub(y: string | number | bigint | Field): Field
Subtract another "field-like" value from this Field element.
Parameters
• y: string
| number
| bigint
| Field
Returns
A Field element equivalent to the modular difference of the two value.
Example
const x = Field(3);
const difference = x.sub(5);
difference.assertEquals(Field(-2));
Warning: This is a modular subtraction 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 subtraction (addition) to prove the difference is calculated correctly.
difference.add(Field(2)).assertEquals(x);
Source
toAuxiliary()
toAuxiliary(): []
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
[]
Source
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.
Returns
bigint
A bigint equivalent to the bigint representation of the Field.
Example
const someField = Field(42);
console.log(someField.toBigInt());
Source
toBits()
toBits(length: number): 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 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.
Source
toConstant()
toConstant(): ConstantField
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
A constant Field element equivalent to this Field element.
Example
const someField = Field(42);
someField.toConstant().assertEquals(someField); // Always true
Source
toFields()
toFields(): Field[]
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.
Source
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.
Returns
string
A string equivalent to the JSON representation of the Field.
Example
const someField = Field(42);
console.log(someField.toJSON());