CanonicalForeignField
o1js / Modules / 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
- random
- 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
_Bigint
▪ Static _Bigint: undefined | { M: bigint = twoadicity; modulus: bigint = p; sizeInBits: number ; t: bigint = oddFactor; twoadicRoot: bigint ; add: (x: bigint, y: bigint) => bigint ; div: (x: bigint, y: bigint) => undefined | bigint ; dot: (x: bigint[], y: bigint[]) => bigint ; equal: (x: bigint, y: bigint) => boolean ; fromBigint: (x: bigint) => bigint ; fromNumber: (x: number) => bigint ; inverse: (x: bigint) => undefined | bigint ; isEven: (x: bigint) => boolean ; isSquare: (x: bigint) => boolean ; leftShift: (x: bigint, bits: number, maxBitSize: number) => bigint ; mod: (x: bigint) => bigint ; mul: (x: bigint, y: bigint) => bigint ; negate: (x: bigint) => bigint ; not: (x: bigint, bits: number) => bigint ; power: (x: bigint, n: bigint) => bigint ; random: () => bigint ; rightShift: (x: bigint, bits: number) => bigint ; rot: (x: bigint, bits: bigint, direction: "left" | "right", maxBits: bigint) => bigint ; sqrt: (x: bigint) => undefined | bigint ; square: (x: bigint) => bigint ; sub: (x: bigint, y: bigint) => bigint } = undefined
Inherited from
ForeignFieldWithMul._Bigint
Defined in
_modulus
▪ Static _modulus: undefined | bigint = undefined
Inherited from
ForeignFieldWithMul._modulus
Defined in
_provable
▪ Static _provable: undefined | ProvablePureExtended\<CanonicalForeignField, string> = 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
Bigint
• Static get Bigint(): Object
Returns
Object
| Name | Type |
|---|---|
M | bigint |
modulus | bigint |
sizeInBits | number |
t | bigint |
twoadicRoot | bigint |
add | (x: bigint, y: bigint) => bigint |
div | (x: bigint, y: bigint) => undefined | bigint |
dot | (x: bigint[], y: bigint[]) => bigint |
equal | (x: bigint, y: bigint) => boolean |
fromBigint | (x: bigint) => bigint |
fromNumber | (x: number) => bigint |
inverse | (x: bigint) => undefined | bigint |
isEven | (x: bigint) => boolean |
isSquare | (x: bigint) => boolean |
leftShift | (x: bigint, bits: number, maxBitSize: number) => bigint |
mod | (x: bigint) => bigint |
mul | (x: bigint, y: bigint) => bigint |
negate | (x: bigint) => bigint |
not | (x: bigint, bits: number) => bigint |
power | (x: bigint, n: bigint) => bigint |
random | () => bigint |
rightShift | (x: bigint, bits: number) => bigint |
rot | (x: bigint, bits: bigint, direction: "left" | "right", maxBits: bigint) => bigint |
sqrt | (x: bigint) => undefined | bigint |
square | (x: bigint) => bigint |
sub | (x: bigint, y: bigint) => bigint |
Inherited from
ForeignFieldWithMul.Bigint
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(): ProvablePureExtended\<CanonicalForeignField, string>
Returns
ProvablePureExtended\<CanonicalForeignField, string>
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
Parameters
| Name | Type |
|---|---|
y | number | bigint | ForeignField |
Returns
UnreducedForeignField
Example
x.add(2); // x + 2 mod p
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
Parameters
| Name | Type |
|---|---|
y | number | bigint | CanonicalForeignField |
message? | string |
Returns
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;
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.
Parameters
| Name | Type |
|---|---|
c | number | bigint |
message? | string |
Returns
void
Example
x.assertLessThan(10);
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.
Parameters
| Name | Type |
|---|---|
y | number | bigint | AlmostForeignField |
Returns
Example
let z = x.div(y); // x/y mod p
z.mul(y).assertEquals(x);
Inherited from
ForeignFieldWithMul.div
Defined in
equals
▸ equals(y): Bool
Check equality with a ForeignField-like value.
Parameters
| Name | Type |
|---|---|
y | number | bigint | CanonicalForeignField |
Returns
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.
Defined in
inv
▸ inv(): AlmostForeignField
Multiplicative inverse in the finite field
Returns
Example
let z = x.inv(); // 1/x mod p
z.mul(x).assertEquals(1);
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
Parameters
| Name | Type |
|---|---|
y | number | bigint | AlmostForeignField |
Returns
UnreducedForeignField
Example
x.mul(y); // x*y mod p
Inherited from
ForeignFieldWithMul.mul
Defined in
neg
▸ neg(): AlmostForeignField
Finite field negation
Returns
Example
x.neg(); // -x mod p = p - x
Inherited from
ForeignFieldWithMul.neg
Defined in
sub
▸ sub(y): UnreducedForeignField
Finite field subtraction
Parameters
| Name | Type |
|---|---|
y | number | bigint | ForeignField |
Returns
UnreducedForeignField
Example
x.sub(1); // x - 1 mod p
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
▸ Static from(x): ForeignField
Parameters
| Name | Type |
|---|---|
x | string | number | bigint | ForeignField |
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
random
▸ Static random(): CanonicalForeignField
Returns
Inherited from
ForeignFieldWithMul.random
Defined in
sum
▸ Static sum(xs, operations): UnreducedForeignField
Sum (or difference) of multiple finite field elements.
Parameters
| Name | Type |
|---|---|
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 add and sub.
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 |