ForeignField
Class: ForeignField
Table of contents
Constructors
Properties
Accessors
Methods
- add
- assertAlmostReduced
- assertCanonical
- assertEquals
- assertLessThan
- equals
- isConstant
- neg
- sub
- toBigInt
- toBits
- toConstant
- toFields
- assertAlmostReduced
- check
- from
- fromBits
- sum
- toLimbs
Constructors
constructor
• new ForeignField(x)
Create a new ForeignField from a bigint, number, string or another ForeignField.
Example
let x = new ForeignField(5);
Parameters
| Name | Type |
|---|---|
x | string | number | bigint | Field3 | ForeignField |
Defined in
Properties
value
• value: Field3
The internal representation of a foreign field element, as a tuple of 3 limbs.
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
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
Example
x.add(2); // x + 2 mod p
Parameters
| Name | Type |
|---|---|
y | number | bigint | ForeignField |
Returns
UnreducedForeignField
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
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
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.
Example
x.assertLessThan(10);
Parameters
| Name | Type |
|---|---|
c | number | bigint |
message? | string |
Returns
void
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
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(): UnreducedForeignField
Finite field negation
Example
x.neg(); // -x mod p = p - x
Returns
UnreducedForeignField
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
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
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
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
Defined in
toLimbs
▸ Static Private toLimbs(x): Field3
Parameters
| Name | Type |
|---|---|
x | string | number | bigint | ForeignField |
Returns
Field3