CanonicalForeignField
o1js / Exports / CanonicalForeignField
Class: CanonicalForeignField
Hierarchy
ForeignFieldWithMul↳
CanonicalForeignField
Table of contents
Constructors
Properties
Accessors
Methods
- add
- assertAlmostReduced
- assertCanonical
- assertEquals
- assertLessThan
- div
- equals
- inv
- isConstant
- mul
- neg
- sub
- toBigInt
- toBits
- toConstant
- toFields
- assertAlmostReduced
- check
- from
- fromBits
- sum
- unsafeFrom
Constructors
constructor
• new CanonicalForeignField(x)
Parameters
| Name | Type |
|---|---|
x | string | number | bigint | Field3 | CanonicalForeignField |
Overrides
ForeignFieldWithMul.constructor
Defined in
Properties
type
• type: "FullyReduced"
Defined in
value
• value: Field3
The internal representation of a foreign field element, as a tuple of 3 limbs.
Inherited from
ForeignFieldWithMul.value
Defined in
_modulus
▪ Static _modulus: undefined | bigint = undefined
Inherited from
ForeignFieldWithMul._modulus
Defined in
_provable
▪ Static _provable: undefined | ProvablePure<CanonicalForeignField> = undefined
Overrides
ForeignFieldWithMul._provable
Defined in
_variants
▪ Static _variants: undefined | { almostReduced: typeof AlmostForeignField ; canonical: typeof CanonicalForeignField ; unreduced: typeof UnreducedForeignField } = undefined
Sibling classes that represent different ranges of field elements.
Inherited from
ForeignFieldWithMul._variants
Defined in
Accessors
Constructor
• get Constructor(): typeof ForeignField
Returns
typeof ForeignField
Inherited from
ForeignFieldWithMul.Constructor
Defined in
modulus
• get modulus(): bigint
Returns
bigint
Inherited from
ForeignFieldWithMul.modulus
Defined in
AlmostReduced
• Static get AlmostReduced(): typeof AlmostForeignField
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
Defined in
Canonical
• Static get Canonical(): typeof CanonicalForeignField
Constructor for field elements that are fully reduced, i.e. lie in the range [0, p).
Returns
typeof CanonicalForeignField
Inherited from
ForeignFieldWithMul.Canonical
Defined in
Unreduced
• Static get Unreduced(): typeof UnreducedForeignField
Constructor for unreduced field elements.
Returns
typeof UnreducedForeignField
Inherited from
ForeignFieldWithMul.Unreduced
Defined in
modulus
• Static get modulus(): bigint
Returns
bigint
Inherited from
ForeignFieldWithMul.modulus
Defined in
provable
• Static get provable(): ProvablePure<CanonicalForeignField>
Returns
ProvablePure<CanonicalForeignField>
Overrides
ForeignFieldWithMul.provable
Defined in
sizeInBits
• Static get sizeInBits(): number
Returns
number
Inherited from
ForeignFieldWithMul.sizeInBits
Defined in
Methods
add
▸ add(y): UnreducedForeignField
Finite field addition
Example
x.add(2); // x + 2 mod p
Parameters
| Name | Type |
|---|---|
y | number | bigint | ForeignField |
Returns
UnreducedForeignField
Inherited from
ForeignFieldWithMul.add
Defined in
assertAlmostReduced
▸ assertAlmostReduced(): AlmostForeignField
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
Inherited from
ForeignFieldWithMul.assertAlmostReduced
Defined in
assertCanonical
▸ assertCanonical(): CanonicalForeignField
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
Inherited from
ForeignFieldWithMul.assertCanonical
Defined in
assertEquals
▸ assertEquals(y, message?): CanonicalForeignField
Assert equality with a ForeignField-like value
Example
x.assertEquals(0, "x is zero");
Since asserting equality can also serve as a range check,
this method returns x with the appropriate type:
Example
let xChecked = x.assertEquals(1, "x is 1");
xChecked satisfies CanonicalForeignField;
Parameters
| Name | Type |
|---|---|
y | number | bigint | CanonicalForeignField |
message? | string |
Returns
Inherited from
ForeignFieldWithMul.assertEquals
Defined in
▸ assertEquals(y, message?): AlmostForeignField
Parameters
| Name | Type |
|---|---|
y | AlmostForeignField |
message? | string |
Returns
Inherited from
ForeignFieldWithMul.assertEquals
Defined in
▸ assertEquals(y, message?): ForeignField
Parameters
| Name | Type |
|---|---|
y | ForeignField |
message? | string |
Returns
Inherited from
ForeignFieldWithMul.assertEquals
Defined in
assertLessThan
▸ assertLessThan(c, message?): void
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.
Example
x.assertLessThan(10);
Parameters
| Name | Type |
|---|---|
c | number | bigint |
message? | string |
Returns
void
Inherited from
ForeignFieldWithMul.assertLessThan
Defined in
div
▸ div(y): AlmostForeignField
Division in the finite field, i.e. x*y^(-1) mod p where y^(-1) is the finite field inverse.
Example
let z = x.div(y); // x/y mod p
z.mul(y).assertEquals(x);
Parameters
| Name | Type |
|---|---|
y | number | bigint | AlmostForeignField |
Returns
Inherited from
ForeignFieldWithMul.div
Defined in
equals
▸ equals(y): Bool
Check equality with a ForeignField-like value
Example
let isXZero = x.equals(0);
Parameters
| Name | Type |
|---|---|
y | number | bigint | ForeignField |
Returns
Bool
Inherited from
ForeignFieldWithMul.equals
Defined in
inv
▸ inv(): AlmostForeignField
Multiplicative inverse in the finite field
Example
let z = x.inv(); // 1/x mod p
z.mul(x).assertEquals(1);
Returns
Inherited from
ForeignFieldWithMul.inv
Defined in
isConstant
▸ isConstant(): boolean
Checks whether this field element is a constant.
See FieldVar to understand constants vs variables.
Returns
boolean
Inherited from
ForeignFieldWithMul.isConstant
Defined in
mul
▸ mul(y): UnreducedForeignField
Finite field multiplication
Example
x.mul(y); // x*y mod p
Parameters
| Name | Type |
|---|---|
y | number | bigint | AlmostForeignField |
Returns
UnreducedForeignField
Inherited from
ForeignFieldWithMul.mul
Defined in
neg
▸ neg(): UnreducedForeignField
Finite field negation
Example
x.neg(); // -x mod p = p - x
Returns
UnreducedForeignField
Inherited from
ForeignFieldWithMul.neg
Defined in
sub
▸ sub(y): UnreducedForeignField
Finite field subtraction
Example
x.sub(1); // x - 1 mod p
Parameters
| Name | Type |
|---|---|
y | number | bigint | ForeignField |
Returns
UnreducedForeignField
Inherited from
ForeignFieldWithMul.sub
Defined in
toBigInt
▸ toBigInt(): bigint
Convert this field element to a bigint.
Returns
bigint
Inherited from
ForeignFieldWithMul.toBigInt
Defined in
toBits
▸ toBits(length?): Bool[]
Unpack a field element to its bits, as a Bool[] array.
This method is provable!
Parameters
| Name | Type |
|---|---|
length? | number |
Returns
Bool[]
Inherited from
ForeignFieldWithMul.toBits
Defined in
toConstant
▸ toConstant(): ForeignField
Convert this field element to a constant.
See FieldVar to understand constants vs variables.
Warning: This function is only useful in witness or asProver blocks, that is, in situations where the prover computes a value outside provable code.
Returns
Inherited from
ForeignFieldWithMul.toConstant
Defined in
toFields
▸ toFields(): Field[]
Instance version of Provable<ForeignField>.toFields, see toFields
Returns
Field[]
Inherited from
ForeignFieldWithMul.toFields
Defined in
assertAlmostReduced
▸ Static assertAlmostReduced<T>(...xs): [...{ [i in string | number | symbol]: AlmostForeignField }[]]
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
| Name | Type |
|---|---|
T | extends Tuple<ForeignField> |
Parameters
| Name | Type |
|---|---|
...xs | T |
Returns
[...{ [i in string | number | symbol]: AlmostForeignField }[]]
Inherited from
ForeignFieldWithMul.assertAlmostReduced
Defined in
check
▸ Static check(x): void
Parameters
| Name | Type |
|---|---|
x | ForeignField |
Returns
void
Overrides
ForeignFieldWithMul.check
Defined in
from
▸ Static from(x): CanonicalForeignField
Coerce the input to a ForeignField.
Parameters
| Name | Type |
|---|---|
x | string | number | bigint |
Returns
Inherited from
ForeignFieldWithMul.from
Defined in
fromBits
▸ Static fromBits(bits): AlmostForeignField
Create a field element from its bits, as a Bool[] array.
This method is provable!
Parameters
| Name | Type |
|---|---|
bits | Bool[] |
Returns
Inherited from
ForeignFieldWithMul.fromBits
Defined in
sum
▸ Static sum(xs, operations): UnreducedForeignField
Sum (or difference) of multiple finite field elements.
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 add and sub.
Parameters
| Name | Type |
|---|---|
xs | (number | bigint | ForeignField)[] |
operations | (1 | -1)[] |
Returns
UnreducedForeignField
Inherited from
ForeignFieldWithMul.sum
Defined in
unsafeFrom
▸ Static unsafeFrom(x): CanonicalForeignField
Coerce the input to a CanonicalForeignField without additional assertions.
Warning: Only use if you know what you're doing.
Parameters
| Name | Type |
|---|---|
x | ForeignField |