ForeignField
Class: ForeignField
Table of contents
Constructors
Properties
Accessors
Methods
- add
- assertAlmostReduced
- assertCanonical
- assertEquals
- assertLessThan
- isConstant
- neg
- sub
- toBigInt
- toBits
- toConstant
- toFields
- assertAlmostReduced
- check
- from
- fromBits
- random
- sum
Constructors
constructor
• new ForeignField(x)
Create a new ForeignField from a bigint, number, string or another ForeignField.
Parameters
| Name | Type |
|---|---|
x | string | number | bigint | Field3 | ForeignField |
Example
let x = new ForeignField(5);
Defined in
Properties
value
• value: Field3
The internal representation of a foreign field element, as a tuple of 3 limbs.
Defined in
_Bigint
▪ Static _Bigint: undefined | { M: bigint = twoadicity; inverse: (x: bigint) => undefined | bigint = exportedInverse; 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 ; 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
Defined in
_modulus
▪ Static _modulus: undefined | bigint = undefined
Defined in
_provable
▪ Static _provable: any = undefined
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.
Defined in
Accessors
Constructor
• get Constructor(): typeof ForeignField
Returns
typeof ForeignField
Defined in
modulus
• get modulus(): bigint
Returns
bigint
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
Defined in
Bigint
• Static get Bigint(): Object
Returns
Object
| Name | Type |
|---|---|
M | bigint |
inverse | (x: bigint) => undefined | 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 |
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 |
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
Defined in
Unreduced
• Static get Unreduced(): typeof UnreducedForeignField
Constructor for unreduced field elements.
Returns
typeof UnreducedForeignField
Defined in
modulus
• Static get modulus(): bigint
Returns
bigint
Defined in
provable
• Static get provable(): any
Provable<ForeignField>, see Provable
Returns
any
Defined in
sizeInBits
• Static get sizeInBits(): number
Returns
number
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
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
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
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;
Defined in
▸ assertEquals(y, message?): AlmostForeignField
Parameters
| Name | Type |
|---|---|
y | AlmostForeignField |
message? | string |
Returns
Defined in
▸ assertEquals(y, message?): ForeignField
Parameters
| Name | Type |
|---|---|
y | ForeignField |
message? | string |
Returns
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);
Defined in
isConstant
▸ isConstant(): boolean
Checks whether this field element is a constant.
See FieldVar to understand constants vs variables.
Returns
boolean
Defined in
neg
▸ neg(): AlmostForeignField
Finite field negation
Returns
Example
x.neg(); // -x mod p = p - x
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
Defined in
toBigInt
▸ toBigInt(): bigint
Convert this field element to a bigint.
Returns
bigint
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[]
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
Defined in
toFields
▸ toFields(): Field[]
Instance version of Provable<ForeignField>.toFields, see toFields
Returns
Field[]
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 }[]]
Defined in
check
▸ Static check(_): void
Parameters
| Name | Type |
|---|---|
_ | ForeignField |
Returns
void
Defined in
from
▸ Static from(x): CanonicalForeignField
Coerce the input to a ForeignField.
Parameters
| Name | Type |
|---|---|
x | string | number | bigint |
Returns
Defined in
▸ Static from(x): ForeignField
Parameters
| Name | Type |
|---|---|
x | string | number | bigint | ForeignField |
Returns
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
Defined in
random
▸ Static random(): CanonicalForeignField
Returns
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.