AlmostForeignField

o1js / Modules / AlmostForeignField

Class: AlmostForeignField

Hierarchy

• ForeignFieldWithMul

  ↳ AlmostForeignField

Table of contents

Constructors

• constructor

Properties

• type
• value
• _Bigint
• _modulus
• _provable
• _variants

Accessors

• Constructor
• modulus
• AlmostReduced
• Bigint
• Canonical
• Unreduced
• modulus
• provable
• sizeInBits

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 AlmostForeignField(x)

Parameters

Name	Type
x	string | number | bigint | Field3 | AlmostForeignField

Overrides

ForeignFieldWithMul.constructor

Defined in

lib/foreign-field.ts:472

Properties

type

• type: "AlmostReduced" | "FullyReduced" = 'AlmostReduced'

Defined in

lib/foreign-field.ts:470

---

value

• value: Field3

The internal representation of a foreign field element, as a tuple of 3 limbs.

Inherited from

ForeignFieldWithMul.value

Defined in

lib/foreign-field.ts:50

---

_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

lib/foreign-field.ts:28

---

_modulus

▪ Static _modulus: undefined | bigint = undefined

Inherited from

ForeignFieldWithMul._modulus

Defined in

lib/foreign-field.ts:29

---

_provable

▪ Static _provable: undefined | ProvablePureExtended\<AlmostForeignField, string> = undefined

Overrides

ForeignFieldWithMul._provable

Defined in

lib/foreign-field.ts:476

---

_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

lib/foreign-field.ts:59

Accessors

Constructor

• get Constructor(): typeof ForeignField

Returns

typeof ForeignField

Inherited from

ForeignFieldWithMul.Constructor

Defined in

lib/foreign-field.ts:52

---

modulus

• get modulus(): bigint

Returns

bigint

Inherited from

ForeignFieldWithMul.modulus

Defined in

lib/foreign-field.ts:40

---

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

lib/foreign-field.ts:77

---

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

lib/foreign-field.ts:32

---

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

lib/foreign-field.ts:84

---

Unreduced

• Static get Unreduced(): typeof UnreducedForeignField

Constructor for unreduced field elements.

Returns

typeof UnreducedForeignField

Inherited from

ForeignFieldWithMul.Unreduced

Defined in

lib/foreign-field.ts:70

---

modulus

• Static get modulus(): bigint

Returns

bigint

Inherited from

ForeignFieldWithMul.modulus

Defined in

lib/foreign-field.ts:36

---

provable

• Static get provable(): ProvablePureExtended\<AlmostForeignField, string>

Returns

ProvablePureExtended\<AlmostForeignField, string>

Overrides

ForeignFieldWithMul.provable

Defined in

lib/foreign-field.ts:479

---

sizeInBits

• Static get sizeInBits(): number

Returns

number

Inherited from

ForeignFieldWithMul.sizeInBits

Defined in

lib/foreign-field.ts:43

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

lib/foreign-field.ts:208

---

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

AlmostForeignField

Inherited from

ForeignFieldWithMul.assertAlmostReduced

Defined in

lib/foreign-field.ts:163

---

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

CanonicalForeignField

Inherited from

ForeignFieldWithMul.assertCanonical

Defined in

lib/foreign-field.ts:194

---

assertEquals

▸ assertEquals(y, message?): CanonicalForeignField

Assert equality with a ForeignField-like value

Parameters

Name	Type
y	number | bigint | CanonicalForeignField
message?	string

Returns

CanonicalForeignField

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

lib/foreign-field.ts:286

▸ assertEquals(y, message?): AlmostForeignField

Parameters

Name	Type
y	AlmostForeignField
message?	string

Returns

AlmostForeignField

Inherited from

ForeignFieldWithMul.assertEquals

Defined in

lib/foreign-field.ts:290

▸ assertEquals(y, message?): ForeignField

Parameters

Name	Type
y	ForeignField
message?	string

Returns

ForeignField

Inherited from

ForeignFieldWithMul.assertEquals

Defined in

lib/foreign-field.ts:291

---

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

lib/foreign-field.ts:333

---

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

AlmostForeignField

Example

let z = x.div(y); // x/y mod p
z.mul(y).assertEquals(x);

Inherited from

ForeignFieldWithMul.div

Defined in

lib/foreign-field.ts:446

---

equals

▸ equals(y): Bool

Check equality with a constant value.

Parameters

Name	Type
y	number | bigint

Returns

Bool

Example

let isXZero = x.equals(0);

Defined in

lib/foreign-field.ts:506

---

inv

▸ inv(): AlmostForeignField

Multiplicative inverse in the finite field

Returns

AlmostForeignField

Example

let z = x.inv(); // 1/x mod p
z.mul(x).assertEquals(1);

Inherited from

ForeignFieldWithMul.inv

Defined in

lib/foreign-field.ts:432

---

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

lib/foreign-field.ts:126

---

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

lib/foreign-field.ts:418

---

neg

▸ neg(): AlmostForeignField

Finite field negation

Returns

AlmostForeignField

Example

x.neg(); // -x mod p = p - x

Inherited from

ForeignFieldWithMul.neg

Defined in

lib/foreign-field.ts:219

---

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

lib/foreign-field.ts:234

---

toBigInt

▸ toBigInt(): bigint

Convert this field element to a bigint.

Returns

bigint

Inherited from

ForeignFieldWithMul.toBigInt

Defined in

lib/foreign-field.ts:146

---

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

lib/foreign-field.ts:352

---

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

ForeignField

Inherited from

ForeignFieldWithMul.toConstant

Defined in

lib/foreign-field.ts:138

---

toFields

▸ toFields(): Field[]

Instance version of Provable<ForeignField>.toFields, see toFields

Returns

Field[]

Inherited from

ForeignFieldWithMul.toFields

Defined in

lib/foreign-field.ts:391

---

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

lib/foreign-field.ts:177

---

check

▸ Static check(x): void

Parameters

Name	Type
x	ForeignField

Returns

void

Overrides

ForeignFieldWithMul.check

Defined in

lib/foreign-field.ts:484

---

from

▸ Static from(x): CanonicalForeignField

Coerce the input to a ForeignField.

Parameters

Name	Type
x	string | number | bigint

Returns

CanonicalForeignField

Inherited from

ForeignFieldWithMul.from

Defined in

lib/foreign-field.ts:114

▸ Static from(x): ForeignField

Parameters

Name	Type
x	string | number | bigint | ForeignField

Returns

ForeignField

Inherited from

ForeignFieldWithMul.from

Defined in

lib/foreign-field.ts:115

---

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

AlmostForeignField

Inherited from

ForeignFieldWithMul.fromBits

Defined in

lib/foreign-field.ts:373

---

random

▸ Static random(): CanonicalForeignField

Returns

CanonicalForeignField

Inherited from

ForeignFieldWithMul.random

Defined in

lib/foreign-field.ts:384

---

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

lib/foreign-field.ts:259

---

unsafeFrom

▸ Static unsafeFrom(x): AlmostForeignField

Coerce the input to an AlmostForeignField without additional assertions.

Warning: Only use if you know what you're doing.

Parameters

Name	Type
x	ForeignField

Returns

AlmostForeignField

Defined in

lib/foreign-field.ts:494