diff --git a/src/lib/mina/account-update.ts b/src/lib/mina/account-update.ts index 6f145e81c..de77ca242 100644 --- a/src/lib/mina/account-update.ts +++ b/src/lib/mina/account-update.ts @@ -531,6 +531,8 @@ interface Body extends AccountUpdateBody { publicKey: PublicKey; /** + * @internal + * * Specify {@link Update}s to tweakable pieces of the account record backing * this address in the ledger. */ @@ -556,6 +558,8 @@ interface Body extends AccountUpdateBody { */ events: Events; /** + * @internal + * * Recent {@link Action}s emitted from this account. * Actions can be collected by archive nodes and used in combination with * a {@link Reducer}. diff --git a/src/lib/mina/transaction.ts b/src/lib/mina/transaction.ts index 844b47254..43e6c1c73 100644 --- a/src/lib/mina/transaction.ts +++ b/src/lib/mina/transaction.ts @@ -129,11 +129,15 @@ type Transaction< * await tx.send(); * ``` */ - setFee(newFee:UInt64) : TransactionPromise; + setFee(newFee: UInt64): TransactionPromise; /** + * @internal + * * setFeePerSnarkCost behaves identically to {@link Transaction.setFee} but the fee is given per estimated cost of snarking the transition as given by {@link getTotalTimeRequired}. This is useful because it should reflect what snark workers would charge in times of network contention. */ - setFeePerSnarkCost(newFeePerSnarkCost:number) : TransactionPromise; + setFeePerSnarkCost( + newFeePerSnarkCost: number + ): TransactionPromise; } & (Proven extends false ? { /** @@ -274,11 +278,15 @@ type PendingTransaction = Pick< /** * setFee is the same as {@link Transaction.setFee(newFee)} but for a {@link PendingTransaction}. */ - setFee(newFee:UInt64):TransactionPromise; + setFee(newFee: UInt64): TransactionPromise; /** + * @internal + * * setFeePerSnarkCost is the same as {@link Transaction.setFeePerSnarkCost(newFeePerSnarkCost)} but for a {@link PendingTransaction}. */ - setFeePerSnarkCost(newFeePerSnarkCost:number):TransactionPromise; + setFeePerSnarkCost( + newFeePerSnarkCost: number + ): TransactionPromise; }; /** @@ -573,24 +581,28 @@ function newTransaction(transaction: ZkappCommand, proofsEnabled?: boolean) { } return pendingTransaction; }, - setFeePerSnarkCost(newFeePerSnarkCost:number) { - let {totalTimeRequired} = getTotalTimeRequired(transaction.accountUpdates); - return this.setFee(new UInt64(Math.round(totalTimeRequired * newFeePerSnarkCost))); + setFeePerSnarkCost(newFeePerSnarkCost: number) { + let { totalTimeRequired } = getTotalTimeRequired( + transaction.accountUpdates + ); + return this.setFee( + new UInt64(Math.round(totalTimeRequired * newFeePerSnarkCost)) + ); }, - setFee(newFee:UInt64) { - return toTransactionPromise(async () => - { - self = self as Transaction; - self.transaction.accountUpdates.forEach( au => { - if (au.body.useFullCommitment.toBoolean()) - { + setFee(newFee: UInt64) { + return toTransactionPromise(async () => { + self = self as Transaction; + self.transaction.accountUpdates.forEach((au) => { + if (au.body.useFullCommitment.toBoolean()) { au.authorization.signature = undefined; - au.lazyAuthorization = {kind:'lazy-signature'}; + au.lazyAuthorization = { kind: 'lazy-signature' }; } - }); + }); self.transaction.feePayer.body.fee = newFee; - self.transaction.feePayer.lazyAuthorization = {kind : 'lazy-signature'}; - return self + self.transaction.feePayer.lazyAuthorization = { + kind: 'lazy-signature', + }; + return self; }); }, }; diff --git a/src/lib/proof-system/proof.ts b/src/lib/proof-system/proof.ts index 44e9fc134..994de311a 100644 --- a/src/lib/proof-system/proof.ts +++ b/src/lib/proof-system/proof.ts @@ -234,7 +234,7 @@ let sideloadedKeysCounter = 0; * NOTE: In the case of `DynamicProof`s, the circuit makes no assertions about the verificationKey used on its own. * This is the responsibility of the application developer and should always implement appropriate checks. * This pattern differs a lot from the usage of normal `Proof`, where the verification key is baked into the compiled circuit. - * @see {@link src/examples/zkprogram/dynamic-keys-merkletree.ts} for an example of how this can be done using merkle trees + * @see `src/examples/zkprogram/dynamic-keys-merkletree.ts` for an example of how this can be done using merkle trees * * Assertions generally only happen using the vk hash that is part of the `VerificationKey` struct along with the raw vk data as auxiliary data. * When using verify() on a `DynamicProof`, Pickles makes sure that the verification key data matches the hash. diff --git a/src/lib/provable/crypto/foreign-curve.ts b/src/lib/provable/crypto/foreign-curve.ts index a0fbc3adf..7ab28c92c 100644 --- a/src/lib/provable/crypto/foreign-curve.ts +++ b/src/lib/provable/crypto/foreign-curve.ts @@ -18,7 +18,7 @@ import { Bytes } from '../bytes.js'; export { createForeignCurve, ForeignCurve }; // internal API -export { toPoint, FlexiblePoint }; +export { toPoint, FlexiblePoint, ForeignCurveNotNeeded }; type FlexiblePoint = { x: AlmostForeignField | Field3 | bigint | number; @@ -205,6 +205,7 @@ class ForeignCurve { } /** + * @internal * Checks whether this curve point is constant. * * See {@link FieldVar} to understand constants vs variables. @@ -398,6 +399,9 @@ class ForeignCurve { } } +/** + * @see: {@link ForeignCurve} + */ class ForeignCurveNotNeeded extends ForeignCurve { constructor(g: { x: AlmostForeignField | Field3 | bigint | number; @@ -421,7 +425,7 @@ class ForeignCurveNotNeeded extends ForeignCurve { * const Curve = createForeignCurve(Crypto.CurveParams.Secp256k1); * ``` * - * `createForeignCurve(params)` takes curve parameters {@link CurveParams} as input. + * `createForeignCurve(params)` takes curve parameters `CurveParams` as input. * We support `modulus` and `order` to be prime numbers up to 259 bits. * * The returned {@link ForeignCurveNotNeeded} class represents a _non-zero curve point_ and supports standard diff --git a/src/lib/provable/foreign-field.ts b/src/lib/provable/foreign-field.ts index e13911a54..051a5f1a3 100644 --- a/src/lib/provable/foreign-field.ts +++ b/src/lib/provable/foreign-field.ts @@ -91,11 +91,11 @@ class ForeignField { * ```ts * let x = new ForeignField(5); * ``` - * + * * Note: Inputs must be range checked if they originate from a different field with a different modulus or if they are not constants. - * + * * - When constructing from another {@link ForeignField} instance, ensure the modulus matches. If not, check the modulus using `Gadgets.ForeignField.assertLessThan()` and handle appropriately. - * - When constructing from a {@link Field3} array, ensure all elements are valid Field elements and range checked. + * - When constructing from a `Field3` array, ensure all elements are valid Field elements and range checked. * - Ensure constants are correctly reduced to the modulus of the field. */ constructor(x: ForeignField | Field3 | bigint | number | string) { @@ -129,6 +129,7 @@ class ForeignField { } /** + * @internal * Checks whether this field element is a constant. * * See {@link FieldVar} to understand constants vs variables. @@ -138,6 +139,7 @@ class ForeignField { } /** + * @internal * Convert this field element to a constant. * * See {@link FieldVar} to understand constants vs variables. diff --git a/src/lib/provable/gadgets/common.ts b/src/lib/provable/gadgets/common.ts index 4c8c1ddca..8e2b565bf 100644 --- a/src/lib/provable/gadgets/common.ts +++ b/src/lib/provable/gadgets/common.ts @@ -19,6 +19,7 @@ export { }; /** + * @internal * Given a Field, collapse its AST to a pure Var. See {@link FieldVar}. * * This is useful to prevent rogue Generic gates added in the middle of gate chains, diff --git a/src/lib/provable/gadgets/foreign-field.ts b/src/lib/provable/gadgets/foreign-field.ts index 57519f148..db6d7a306 100644 --- a/src/lib/provable/gadgets/foreign-field.ts +++ b/src/lib/provable/gadgets/foreign-field.ts @@ -585,6 +585,8 @@ function assertMul( } /** + * @internal + * * Lazy sum of {@link Field3} elements, which can be used as input to `Gadgets.ForeignField.assertMul()`. */ class Sum { diff --git a/src/lib/provable/gadgets/gadgets.ts b/src/lib/provable/gadgets/gadgets.ts index a1dfda563..297a26f03 100644 --- a/src/lib/provable/gadgets/gadgets.ts +++ b/src/lib/provable/gadgets/gadgets.ts @@ -439,7 +439,7 @@ const Gadgets = { * Bitwise AND gadget on {@link Field} elements. Equivalent to the [bitwise AND `&` operator in JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_AND). * The AND gate works by comparing two bits and returning `1` if both bits are `1`, and `0` otherwise. * - * It can be checked by a double generic gate that verifies the following relationship between the values + * It can be checked by a double generic gate that verifies the following relationship between the values * below (in the process it also invokes the {@link Gadgets.xor} gadget which will create additional constraints depending on `length`). * * The generic gate verifies:\ @@ -452,7 +452,7 @@ const Gadgets = { * You can find more details about the implementation in the [Mina book](https://o1-labs.github.io/proof-systems/specs/kimchi.html?highlight=gates#and) * * The `length` parameter lets you define how many bits should be compared. `length` is rounded - * to the nearest multiple of 16, `paddedLength = ceil(length / 16) * 16`, and both input values + * to the nearest multiple of 16, `paddedLength = ceil(length / 16) * 16`, and both input values * are constrained to fit into `paddedLength` bits. The output is guaranteed to have at most `paddedLength` bits as well. * * **Note:** Specifying a larger `length` parameter adds additional constraints. @@ -476,8 +476,8 @@ const Gadgets = { * Bitwise OR gadget on {@link Field} elements. Equivalent to the [bitwise OR `|` operator in JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_OR). * The OR gate works by comparing two bits and returning `1` if at least one bit is `1`, and `0` otherwise. * - * The `length` parameter lets you define how many bits should be compared. `length` is rounded - * to the nearest multiple of 16, `paddedLength = ceil(length / 16) * 16`, and both input values + * The `length` parameter lets you define how many bits should be compared. `length` is rounded + * to the nearest multiple of 16, `paddedLength = ceil(length / 16) * 16`, and both input values * are constrained to fit into `paddedLength` bits. The output is guaranteed to have at most `paddedLength` bits as well. * * **Note:** Specifying a larger `length` parameter adds additional constraints. @@ -685,6 +685,8 @@ const Gadgets = { }, /** + * @internal + * * Foreign field multiplication: `x * y mod f` * * The modulus `f` does not need to be prime, but has to be smaller than 2^259. @@ -722,6 +724,8 @@ const Gadgets = { }, /** + * @internal + * * Foreign field inverse: `x^(-1) mod f` * * See {@link Gadgets.ForeignField.mul} for assumptions on inputs and usage examples. @@ -733,6 +737,8 @@ const Gadgets = { }, /** + * @internal + * * Foreign field division: `x * y^(-1) mod f` * * See {@link Gadgets.ForeignField.mul} for assumptions on inputs and usage examples. @@ -746,6 +752,8 @@ const Gadgets = { }, /** + * @internal + * * Optimized multiplication of sums in a foreign field, for example: `(x - y)*z = a + b + c mod f` * * Note: This is much more efficient than using {@link Gadgets.ForeignField.add} and {@link Gadgets.ForeignField.sub} separately to @@ -789,6 +797,8 @@ const Gadgets = { }, /** + * @internal + * * Lazy sum of {@link Field3} elements, which can be used as input to {@link Gadgets.ForeignField.assertMul}. */ Sum(x: Field3) { @@ -796,6 +806,8 @@ const Gadgets = { }, /** + * @internal + * * Prove that each of the given {@link Field3} elements is "almost" reduced modulo f, * i.e., satisfies the assumptions required by {@link Gadgets.ForeignField.mul} and other gadgets: * - each limb is in the range [0, 2^88) diff --git a/src/lib/provable/int.ts b/src/lib/provable/int.ts index 325978dd2..13b83f4f3 100644 --- a/src/lib/provable/int.ts +++ b/src/lib/provable/int.ts @@ -77,7 +77,7 @@ class UInt64 extends CircuitValue { return this.value.toString(); } /** - * Turns the {@link UInt64} into a {@link BigInt}. + * Turns the {@link UInt64} into a BigInt. * @returns */ toBigInt() { @@ -575,7 +575,7 @@ class UInt32 extends CircuitValue { return this.value.toString(); } /** - * Turns the {@link UInt32} into a {@link BigInt}. + * Turns the {@link UInt32} into a BigInt. */ toBigint() { return this.value.toBigInt(); @@ -1214,7 +1214,7 @@ class Int64 extends CircuitValue implements BalanceChange { } /** - * Turns the {@link Int64} into a {@link BigInt}. + * Turns the {@link Int64} into a BigInt. */ toBigint() { let abs = this.magnitude.toBigInt(); @@ -1287,8 +1287,8 @@ class Int64 extends CircuitValue implements BalanceChange { * Int64.from(5).neg(); * ``` * - * @see {@link Int64#from} for creating Int64 instances - * @see {@link Int64#zero} for the zero constant + * @see {@link Int64.from} for creating Int64 instances + * @see {@link Int64.zero} for the zero constant * * @throws {Error} Implicitly, if the internal Provable.if condition fails */ diff --git a/src/lib/provable/provable.ts b/src/lib/provable/provable.ts index a0db0f959..e8009ed3f 100644 --- a/src/lib/provable/provable.ts +++ b/src/lib/provable/provable.ts @@ -148,6 +148,7 @@ const Provable = { */ Array: provableArray, /** + * @internal * Check whether a value is constant. * See {@link FieldVar} for more information about constants and variables. * diff --git a/src/lib/provable/scalar.ts b/src/lib/provable/scalar.ts index 8810e2cd5..edd081a22 100644 --- a/src/lib/provable/scalar.ts +++ b/src/lib/provable/scalar.ts @@ -52,6 +52,7 @@ class Scalar implements ShiftedScalar { } /** + * @internal * Provable method to convert a {@link ShiftedScalar} to a {@link Scalar}. */ static fromShiftedScalar(s: ShiftedScalar) { @@ -78,6 +79,7 @@ class Scalar implements ShiftedScalar { } /** + * @internal * Convert this {@link Scalar} into a constant if it isn't already. * * If the scalar is a variable, this only works inside `asProver` or `witness` blocks. diff --git a/src/lib/provable/types/provable-intf.ts b/src/lib/provable/types/provable-intf.ts index e12a128b9..703741e39 100644 --- a/src/lib/provable/types/provable-intf.ts +++ b/src/lib/provable/types/provable-intf.ts @@ -49,7 +49,7 @@ type Provable = { /** * A function that returns an element of type `T` from the given provable and "auxiliary" data. * - * This function is the reverse operation of calling {@link toFields} and {@link toAuxilary} methods on an element of type `T`. + * This function is the reverse operation of calling {@link toFields} and {@link toAuxiliary} methods on an element of type `T`. * * @param fields - an array of {@link Field} elements describing the provable data of the new `T` element. * @param aux - an array of any type describing the "auxiliary" data of the new `T` element, optional. diff --git a/typedoc.json b/typedoc.json index 22d5b0c11..ec0007035 100644 --- a/typedoc.json +++ b/typedoc.json @@ -19,7 +19,10 @@ }, "entryPoints": [ "src/index.ts", + "src/lib/mina/account-update.ts", + "src/lib/provable/crypto/foreign-curve.ts", "src/lib/provable/field.ts", + "src/lib/provable/foreign-field.ts", "src/lib/provable/bool.ts", "src/lib/provable/group.ts", "src/lib/provable/int.ts",