From aa1f4d0205ebd1a99552334f89f66072a0143da5 Mon Sep 17 00:00:00 2001 From: Andrew Twyman Date: Fri, 20 Dec 2024 16:25:53 -0800 Subject: [PATCH 1/3] Fix Typedoc --- .../src/routing/routes/pcdIssuanceRoutes.ts | 4 +- .../pipelines/CSVPipeline/makeMessagePCD.ts | 2 +- .../test/generic-issuance/util.ts | 4 +- apps/zupoll-client/src/api/prismaTypes.ts | 2 +- packages/lib/client-shared/src/util.ts | 4 +- packages/lib/gpc/src/gpc.ts | 6 +-- packages/lib/gpc/src/gpcJSON.ts | 21 ++++---- packages/lib/gpc/src/gpcTypes.ts | 53 +++++++++++-------- packages/lib/gpc/src/gpcUtil.ts | 2 +- packages/lib/gpc/tsconfig.json | 16 ++---- packages/lib/gpcircuits/src/proto-pod-gpc.ts | 6 +-- packages/lib/gpcircuits/src/types.ts | 11 ++++ packages/lib/gpcircuits/tsconfig.cjs.json | 2 +- packages/lib/gpcircuits/tsconfig.esm.json | 2 +- packages/lib/gpcircuits/tsconfig.json | 13 +---- packages/lib/passport-crypto/src/utils.ts | 2 +- packages/lib/pcd-types/src/pcd.ts | 10 ++-- packages/lib/pod/src/podCrypto.ts | 2 +- packages/lib/pod/src/podTypes.ts | 7 --- packages/lib/pod/src/podUtil.ts | 6 +-- .../podbox-shared/src/PODPipeline/updates.ts | 3 +- packages/lib/util/src/strings.ts | 2 +- packages/pcd/gpc-pcd/src/GPCPCD.ts | 17 +++--- packages/pcd/gpc-pcd/src/json.ts | 2 - packages/pcd/pod-pcd/src/PODPCD.ts | 17 +++--- .../pcd/pod-ticket-pcd/src/PODTicketPCD.ts | 8 +-- 26 files changed, 110 insertions(+), 114 deletions(-) diff --git a/apps/passport-server/src/routing/routes/pcdIssuanceRoutes.ts b/apps/passport-server/src/routing/routes/pcdIssuanceRoutes.ts index d73a876109..aaab77acfd 100644 --- a/apps/passport-server/src/routing/routes/pcdIssuanceRoutes.ts +++ b/apps/passport-server/src/routing/routes/pcdIssuanceRoutes.ts @@ -26,8 +26,8 @@ export function initPCDIssuanceRoutes( logger("[INIT] initializing PCD issuance routes"); /** - * If either of the {@code process.env.SERVER_RSA_PRIVATE_KEY_BASE64} or - * {@code process.env.SERVER_EDDSA_PRIVATE_KEY} are not initialized properly, + * If either of the `process.env.SERVER_RSA_PRIVATE_KEY_BASE64` or + * `process.env.SERVER_EDDSA_PRIVATE_KEY` are not initialized properly, * then this server won't have an {@link IssuanceService}. It'll continue * to work, except users won't get any 'issued' tickets - Devconnect, * Zuconnect, Zuzalu, etc. diff --git a/apps/passport-server/src/services/generic-issuance/pipelines/CSVPipeline/makeMessagePCD.ts b/apps/passport-server/src/services/generic-issuance/pipelines/CSVPipeline/makeMessagePCD.ts index af692181fa..091eae9599 100644 --- a/apps/passport-server/src/services/generic-issuance/pipelines/CSVPipeline/makeMessagePCD.ts +++ b/apps/passport-server/src/services/generic-issuance/pipelines/CSVPipeline/makeMessagePCD.ts @@ -6,7 +6,7 @@ import { traced } from "../../../telemetryService"; /** * Given a CSV row uploaded by a user to a {@link CSVPipeline}, * generates an {@link MessagePCD} containing {@link }signed - * {@code process.env.GENERIC_ISSUANCE_EDDSA_PRIVATE_KEY} + * `process.env.GENERIC_ISSUANCE_EDDSA_PRIVATE_KEY` * * * - `title`: gets displayed in the title of the PCD diff --git a/apps/passport-server/test/generic-issuance/util.ts b/apps/passport-server/test/generic-issuance/util.ts index 32465e5f08..2f6aedef55 100644 --- a/apps/passport-server/test/generic-issuance/util.ts +++ b/apps/passport-server/test/generic-issuance/util.ts @@ -173,7 +173,7 @@ export function getTicketsFromFeedResponse( export async function requestTicketsFromPipeline( expectedFolder: string, /** - * Generated by {@code makeGenericIssuanceFeedUrl}. + * Generated by `makeGenericIssuanceFeedUrl`. */ feedUrl: string, feedId: string, @@ -216,7 +216,7 @@ export async function requestTicketsFromPipeline( export async function requestTicketsFromPipelineWithEmailPCDs( expectedFolder: string, /** - * Generated by {@code makeGenericIssuanceFeedUrl}. + * Generated by `makeGenericIssuanceFeedUrl`. */ feedUrl: string, feedId: string, diff --git a/apps/zupoll-client/src/api/prismaTypes.ts b/apps/zupoll-client/src/api/prismaTypes.ts index a3a70ffc0f..0c332407bd 100644 --- a/apps/zupoll-client/src/api/prismaTypes.ts +++ b/apps/zupoll-client/src/api/prismaTypes.ts @@ -39,7 +39,7 @@ export type Poll = { createdAt: Date; body: string; /** - * Either a string or a {@code JSON.stringify}'d {@link ObjectOption} + * Either a string or a `JSON.stringify`'d {@link ObjectOption} */ options: string[]; expiry: Date; diff --git a/packages/lib/client-shared/src/util.ts b/packages/lib/client-shared/src/util.ts index b15ad4d5de..64a409474d 100644 --- a/packages/lib/client-shared/src/util.ts +++ b/packages/lib/client-shared/src/util.ts @@ -1,7 +1,7 @@ import { emptyStrToUndefined } from "@pcd/util"; /** - * Settings for calling {@link gpcArtifactDownloadURL} as parsed from an + * Settings for calling {@link @pcd/gpc!gpcArtifactDownloadURL} as parsed from an * environment variable by {@link parseGPCArtifactsConfig}. */ export type GPCArtifactsConfigEnv = { @@ -15,7 +15,7 @@ export type GPCArtifactsConfigEnv = { * environment variable, or provides default values if not set. * * @param envConfig environment variable value for override - * @returns config variables suitable for calling {@link gpcArtifactDownloadURL}. + * @returns config variables suitable for calling {@link @pcd/gpc!gpcArtifactDownloadURL}. * @throws if the input string isn't in the correct JSON format */ export function parseGPCArtifactsConfig( diff --git a/packages/lib/gpc/src/gpc.ts b/packages/lib/gpc/src/gpc.ts index 7cabc6dbd5..e211c925f2 100644 --- a/packages/lib/gpc/src/gpc.ts +++ b/packages/lib/gpc/src/gpc.ts @@ -148,7 +148,7 @@ export function gpcCheckProvable( /** * Performs only the preparatory steps of {@link gpcProve}, returning all of * the circuit-related info needed to generate a proof using the - * {@link @pcd/gpcircuits} package, or another user-supplied proving stack. + * {@link "@pcd/gpcircuits"} package, or another user-supplied proving stack. * * Inputs will be fully validated for structural soundness in the same way as * when generating a proof. See {@link gpcProve} for more details on inputs @@ -192,7 +192,7 @@ export function gpcPreProve( /** * Performs only the post-processing steps of {@link gpcProve}, taking in a - * proof already genereated using the {@link @pcd/gpcircuits} package, or + * proof already genereated using the {@link "@pcd/gpcircuits"} package, or * another user-supplied proving stack. The circuit-specific outputs are * processed into the {@link GPCRevealedClaims} to produce the normal output * of {@link gpcProve}. @@ -296,7 +296,7 @@ export async function gpcProve( /** * Performs only the preparatory steps of {@link gpcVerify}, returning all of * the circuit-related info needed to verify a proof using the - * {@link @pcd/gpcircuits} package, or another user-supplied verification stack. + * {@link "@pcd/gpcircuits"} package, or another user-supplied verification stack. * * Inputs will be fully validated for structural soundness, but not * cryptographically. See {@link gpcVerify} for more details on inputs and diff --git a/packages/lib/gpc/src/gpcJSON.ts b/packages/lib/gpc/src/gpcJSON.ts index f845ce5dba..c17257a728 100644 --- a/packages/lib/gpc/src/gpcJSON.ts +++ b/packages/lib/gpc/src/gpcJSON.ts @@ -22,8 +22,8 @@ import { * safe to serialize directly using `JSON.stringify`. * * This is identical to the TypeScript type except that `bigint` and - * {@link PODValue} elements are replaced by JSON-compatible representations - * defined by {@link JSONBigInt} and {@link JSONPODValue} respectively. + * {@link @pcd/pod!PODValue} elements are replaced by JSON-compatible representations + * defined by {@link @pcd/pod!JSONBigInt} and {@link JSONPODValue} respectively. * * Use {@link proofConfigToJSON} and {@link proofConfigFromJSON} to convert * between JSON and TypeScript represenations. @@ -49,7 +49,7 @@ export function proofConfigToJSON(config: GPCProofConfig): JSONProofConfig { * potentially received directly from `JSON.parse`. See {@link JSONProofConfig} * for information about the format. * - * @param config the JSON representation + * @param jsonConfig the JSON representation * @returns a config object * @throws if the config is invalid */ @@ -66,8 +66,9 @@ export function proofConfigFromJSON( * safe to serialize directly using `JSON.stringify`. * * This is identical to the TypeScript type except that `bigint` and - * {@link PODValue} elements are replaced by JSON-compatible representations - * defined by {@link JSONBigInt} and {@link JSONPODValue} respectively. + * {@link @pcd/pod!PODValue} elements are replaced by JSON-compatible + * representations defined by {@link @pcd/pod!JSONBigInt} and + * {@link @pcd/pod!JSONPODValue} respectively. * * Use {@link boundConfigToJSON} and {@link boundConfigFromJSON} to convert * between JSON and TypeScript represenations. @@ -93,7 +94,7 @@ export function boundConfigToJSON(config: GPCBoundConfig): JSONBoundConfig { * potentially received directly from `JSON.parse`. See {@link JSONProofConfig} * for information about the format. * - * @param config the JSON representation + * @param jsonConfig the JSON representation * @returns a config object * @throws if the config is invalid */ @@ -110,8 +111,8 @@ export function boundConfigFromJSON( * safe to serialize directly using `JSON.stringify`. * * This is identical to the TypeScript type except that `bigint` and - * {@link PODValue} elements are replaced by JSON-compatible representations - * defined by {@link JSONBigInt} and {@link JSONPODValue} respectively. + * {@link @pcd/pod!PODValue} elements are replaced by JSON-compatible representations + * defined by {@link @pcd/pod!JSONBigInt} and {@link JSONPODValue} respectively. * * Use {@link boundConfigToJSON} and {@link boundConfigFromJSON} to convert * between JSON and TypeScript represenations. @@ -123,7 +124,7 @@ export type JSONRevealedClaims = ValibotRevealedClaims.JSONType; * which can be serialized directly using `JSON.stringify`. See * {@link JSONRevealedClaims} for information about the format. * - * @param config the config object to convert + * @param claims the claims object to convert * @returns a JSON representation * @throws if the config is invalid */ @@ -139,7 +140,7 @@ export function revealedClaimsToJSON( * potentially received directly from `JSON.parse`. See * {@link JSONRevealedClaims} for information about the format. * - * @param config the JSON representation + * @param jsonClaims the JSON representation * @returns a config object * @throws if the config is invalid */ diff --git a/packages/lib/gpc/src/gpcTypes.ts b/packages/lib/gpc/src/gpcTypes.ts index d4dc37f0b3..46bc5b8cf7 100644 --- a/packages/lib/gpc/src/gpcTypes.ts +++ b/packages/lib/gpc/src/gpcTypes.ts @@ -6,7 +6,8 @@ import type { Groth16Proof } from "snarkjs"; /** * String specifying a named entry, virtual or otherwise, in a named object, in * the format `objectName.entryName`. Each of the sub-parts should be a valid - * PODName, checked by {@link POD_NAME_REGEX} or {@link POD_VIRTUAL_NAME_REGEX}. + * PODName, checked by {@link @pcd/pod!POD_NAME_REGEX} or + * {@link POD_VIRTUAL_NAME_REGEX}. * * Examples: "ticket1.eventID", "award.$signerPublicKey" */ @@ -48,14 +49,21 @@ export const POD_VIRTUAL_NAME_REGEX = new RegExp( */ export type PODMembershipLists = Record; -// Single source of truth for tuple prefix (used internally). -// This should not be a valid {@link PODName} to avoid name clashes. +/** + * Single source of truth for tuple prefix (used internally). + * This should not be a valid {@link PODName} to avoid name clashes. + */ export const TUPLE_PREFIX = "$tuple"; -type TuplePrefix = typeof TUPLE_PREFIX; + +/** + * Type representation of the tuple prefix string "$tuple". + */ +export type TuplePrefix = typeof TUPLE_PREFIX; /** * String specifying a named tuple in the format `tuple.tupleName`. - * `tupleName` should be a valid PODName checked by {@link POD_NAME_REGEX}. + * `tupleName` should be a valid PODName checked by + * {@link @pcd/pod!POD_NAME_REGEX}. */ export type TupleIdentifier = `${TuplePrefix}.${PODName}`; @@ -101,7 +109,7 @@ export type GPCProofEntryConfigCommon = { * used to find the entry in one of the pods in {@link GPCProofInputs}. * * Comparison in the proof circuit is based on the hash produced by - * {@link podValueHash}. This means values of different types can be + * {@link @pcd/pod!podValueHash}. This means values of different types can be * considered equal if they are treated in the same way by circuits. * * If undefined, there is no equality constraint. @@ -119,7 +127,7 @@ export type GPCProofEntryConfigCommon = { * find the entry in one of the pods in {@link GPCProofInputs}. * * Comparison in the proof circuit is based on the hash produced by - * {@link podValueHash}. This means values of different types can be + * {@link @pcd/pod!podValueHash}. This means values of different types can be * considered equal if they are treated in the same way by circuits. * * If undefined, there is no inequality constraint. @@ -229,7 +237,7 @@ export type GPCProofEntryConfig = GPCProofEntryConfigCommon & * their identity commitment. * * Comparison in the proof circuit is based on the hash produced by - * {@link podValueHash}. This means values of different types can be + * {@link @pcd/pod!podValueHash}. This means values of different types can be * considered equal if they are treated in the same way by circuits. * * If undefined, there is no owner-related constraint on this entry. @@ -326,7 +334,7 @@ export type GPCProofConfig = { * will pick the smallest supported circuit which can handle this * configuration. * - * See {@link ProtoPODGPC.CIRCUIT_FAMILY} for supported circuits.) + * See {@link "@pcd/gpcircuits"!ProtoPODGPC.CIRCUIT_FAMILY} for supported circuits.) */ circuitIdentifier?: GPCIdentifier; @@ -399,7 +407,7 @@ export type GPCBoundConfig = GPCProofConfig & { * and verifying. Same meaning as in {@link GPCProofConfig} except here it * is a required field. * - * See {@link ProtoPODGPC.CIRCUIT_FAMILY} for supported circuits.) + * See {@link "@pcd/gpcircuits"!ProtoPODGPC.CIRCUIT_FAMILY} for supported circuits.) */ circuitIdentifier: GPCIdentifier; }; @@ -420,13 +428,13 @@ export type GPCProof = Groth16Proof; export type GPCProofOwnerInputs = { /** * The owner's identity using Semaphore V3. This need not be specified if no - * entry has {@link isOwnerID} equal to "SemaphoreV3". + * entry has {@link GPCProofEntryConfig.isOwnerID} equal to "SemaphoreV3". */ semaphoreV3?: IdentityV3; /** * The owner's identity using Semaphore V4. This need not be specified if no - * entry has {@link isOwnerID} equal to "SemaphoreV4". + * entry has {@link GPCProofEntryConfig.isOwnerID} equal to "SemaphoreV4". */ semaphoreV4?: IdentityV4; @@ -436,11 +444,11 @@ export type GPCProofOwnerInputs = { * owner's private identity. This allows identifying duplicate proofs (e.g. * to avoid double spending or voting) without de-anonymizing the owner. * - * This field can be a {@link PODValue} of any type, and will be represented + * This field can be a {@link @pcd/pod!PODValue} of any type, and will be represented * in the circuit as a number or a hash as appropriate. When the proof * is verified, the external nullifier is also verified (as a public input). * - * This field cannot be set if no entry is marked with {@link isOwnerID}, + * This field cannot be set if no entry is marked with {@link GPCProofEntryConfig.isOwnerID}, * because such a nullifier would not be cryptographically tied to anything * verifiable. */ @@ -482,7 +490,7 @@ export type GPCProofInputs = { * to allow identifying duplicate proofs without de-anonymizing. * * This field can be omitted if an owner is not needed for any entry - * an entry with {@link isOwnerID} set. + * an entry with {@link GPCProofEntryConfig.isOwnerID} set. */ owner?: GPCProofOwnerInputs; @@ -502,7 +510,7 @@ export type GPCProofInputs = { * avoid reuse. Unlike a nullifier, this watermark is not cryptographically * tied to any specific input data. * - * This field can be a {@link PODValue} of any type, and will be represented + * This field can be a {@link @pcd/pod!PODValue} of any type, and will be represented * in the circuit as a number or a hash as appropriate. When the proof * is verified, the watermark is also verified (as a public input). */ @@ -545,12 +553,13 @@ export type GPCRevealedObjectClaims = { export type GPCRevealedOwnerClaims = { /** * If this field is set, it matches the corresponding field in - * {@link GPCProofInputs}, and {@link nullifierHash} will also be set. The - * hash is uniquely tied to this value, and to the owner's private identity. - * This allows identifying duplicate proofs (e.g. to avoid double spending - * or voting) without de-anonymizing the owner. + * {@link GPCProofInputs}, and {@link nullifierHashV3} or + * {@link nullifierHashV4} will also be set. The hash is uniquely tied to + * this value, and to the owner's private identity. This allows identifying + * duplicate proofs (e.g. to avoid double spending or voting) without + * de-anonymizing the owner. * - * This field can be a {@link PODValue} of any type, and will be represented + * This field can be a {@link @pcd/pod!PODValue} of any type, and will be represented * in the circuit as a number or a hash as appropriate. When the proof * is verified, the external nullifier is also verified (as a public input). */ @@ -621,7 +630,7 @@ export type GPCRevealedClaims = { * specific use case, to avoid reuse. Unlike a nullifier, this watermark is * not cryptographically tied to any specific input data. * - * This field can be a {@link PODValue} of any type, and will be represented + * This field can be a {@link @pcd/pod!PODValue} of any type, and will be represented * in the circuit as a number or a hash as appropriate. When the proof * is verified, the watermark is also verified (as a public input). */ diff --git a/packages/lib/gpc/src/gpcUtil.ts b/packages/lib/gpc/src/gpcUtil.ts index a996f2e773..e9640acaf4 100644 --- a/packages/lib/gpc/src/gpcUtil.ts +++ b/packages/lib/gpc/src/gpcUtil.ts @@ -311,7 +311,7 @@ function canonicalizeTupleConfig( /** * Checks that the input matches the proper format for an entry name, virtual or - * ortherwise, as given by {@link POD_NAME_REGEX} and {@link + * ortherwise, as given by {@link @pcd/pod!POD_NAME_REGEX} and {@link * POD_VIRTUAL_NAME_REGEX}. * * @param name the string to check diff --git a/packages/lib/gpc/tsconfig.json b/packages/lib/gpc/tsconfig.json index 4d07496bba..37a284776c 100644 --- a/packages/lib/gpc/tsconfig.json +++ b/packages/lib/gpc/tsconfig.json @@ -1,25 +1,15 @@ { "extends": "@pcd/tsconfig/ts-library.json", "compilerOptions": { - "lib": [ - "dom" - ], + "lib": ["dom"], "outDir": "dist", "declarationDir": "dist/types", // Include all source files, including tests "rootDir": "." }, // Some artifact-including packages need to import a JSON file - "include": [ - "src", - "test", - "artifacts/*.json" - ], - "exclude": [ - "dist", - "build", - "node_modules" - ], + "include": ["src", "test", "artifacts/*.json", "scripts"], + "exclude": ["dist", "build", "node_modules"], // DO NOT MODIFY MANUALLY BEYOND THIS POINT // References are automatically maintained by `yarn fix-references` "references": [ diff --git a/packages/lib/gpcircuits/src/proto-pod-gpc.ts b/packages/lib/gpcircuits/src/proto-pod-gpc.ts index f71e4edaac..4811f32f78 100644 --- a/packages/lib/gpcircuits/src/proto-pod-gpc.ts +++ b/packages/lib/gpcircuits/src/proto-pod-gpc.ts @@ -394,9 +394,9 @@ export class ProtoPODGPC { * * @param inputs full inputs (public and private) * @param wasmPath path to wasm file for witness generation. - * See {@link artifactPaths}. + * See {@link CircuitArtifactPaths}. * @param pkeyPath path to file containing proving key. - * See {@link artifactPaths}. + * See {@link CircuitArtifactPaths}. * @returns Groth16 proof, circuit outputs, and full set of public signals * (primarily for verification in tests). */ @@ -430,7 +430,7 @@ export class ProtoPODGPC { * Verify a proof for a circuit in this library. * * @param vkeyPath path to verification key as a JSON file. - * See {@link artifactPaths}. + * See {@link CircuitArtifactPaths}. * @param proof Groth16 proof. * @param publicInputs claimed public inputs to the circuit. * See {@link filterPublicInputs} diff --git a/packages/lib/gpcircuits/src/types.ts b/packages/lib/gpcircuits/src/types.ts index e9ddfad5ae..5454e78b5f 100644 --- a/packages/lib/gpcircuits/src/types.ts +++ b/packages/lib/gpcircuits/src/types.ts @@ -9,8 +9,19 @@ export type CircuitSignal = `${number}` | bigint; * Paths to circuit artifacts (files) required for proving and verifying. */ export type CircuitArtifactPaths = { + /** + * path to wasm file for witness generation. + */ wasmPath: string; + + /** + * path to JSON file containing the proving key. + */ pkeyPath: string; + + /** + * path to JSON file containing the verification key. + */ vkeyPath: string; }; diff --git a/packages/lib/gpcircuits/tsconfig.cjs.json b/packages/lib/gpcircuits/tsconfig.cjs.json index dd86535c21..3150d76e0d 100644 --- a/packages/lib/gpcircuits/tsconfig.cjs.json +++ b/packages/lib/gpcircuits/tsconfig.cjs.json @@ -6,7 +6,7 @@ "tsBuildInfoFile": "./tsconfig.cjs.tsbuildinfo" }, // For CJS/ESM builds, do not include test files - "include": ["src", "src/circuitParameters.json"], + "include": ["src", "scripts", "circomKit.json", "src/circuitParameters.json"], // DO NOT MODIFY MANUALLY BEYOND THIS POINT // References are automatically maintained by `yarn fix-references` "references": [ diff --git a/packages/lib/gpcircuits/tsconfig.esm.json b/packages/lib/gpcircuits/tsconfig.esm.json index 4c46d4da3f..bf77d36476 100644 --- a/packages/lib/gpcircuits/tsconfig.esm.json +++ b/packages/lib/gpcircuits/tsconfig.esm.json @@ -6,7 +6,7 @@ "tsBuildInfoFile": "./tsconfig.esm.tsbuildinfo" }, // For CJS/ESM builds, do not include test files - "include": ["src", "src/circuitParameters.json"], + "include": ["src", "scripts", "circomKit.json", "src/circuitParameters.json"], // DO NOT MODIFY MANUALLY BEYOND THIS POINT // References are automatically maintained by `yarn fix-references` "references": [ diff --git a/packages/lib/gpcircuits/tsconfig.json b/packages/lib/gpcircuits/tsconfig.json index c46f47278b..291f7c5e86 100644 --- a/packages/lib/gpcircuits/tsconfig.json +++ b/packages/lib/gpcircuits/tsconfig.json @@ -8,17 +8,8 @@ "rootDir": "." }, // Some artifact-including packages need to import a JSON file - "include": [ - "src", - "test", - "src/*.json", - "scripts" - ], - "exclude": [ - "dist", - "build", - "node_modules" - ], + "include": ["src", "test", "src/*.json", "scripts", "circomKit.json"], + "exclude": ["dist", "build", "node_modules"], // DO NOT MODIFY MANUALLY BEYOND THIS POINT // References are automatically maintained by `yarn fix-references` "references": [ diff --git a/packages/lib/passport-crypto/src/utils.ts b/packages/lib/passport-crypto/src/utils.ts index 1972cf63b3..b67bb6437a 100644 --- a/packages/lib/passport-crypto/src/utils.ts +++ b/packages/lib/passport-crypto/src/utils.ts @@ -70,7 +70,7 @@ export function base64ToArrayBuffer(base64: string): Uint8Array { /** * Converts an ArrayBuffer into a base64 string - * @param buffer + * @param arrayBuffer - a buffer of bytes */ export function arrayBufferToBase64(arrayBuffer: ArrayBuffer): string { return to_base64(Buffer.from(arrayBuffer), base64_variants.ORIGINAL); diff --git a/packages/lib/pcd-types/src/pcd.ts b/packages/lib/pcd-types/src/pcd.ts index 44063cd319..de91a930b2 100644 --- a/packages/lib/pcd-types/src/pcd.ts +++ b/packages/lib/pcd-types/src/pcd.ts @@ -55,12 +55,12 @@ export interface PCD { * * @typeParam {@link A} - the type of the arguments passed into {@link PCDPackage#prove} * to instantiate a new {@link PCD}. It is important that {@link A} can be serialized - * and deserialized using {@code JSON.stringify} {@code JSON.parse}, because these arguments + * and deserialized using `JSON.stringify` and `JSON.parse`, because these arguments * should be able to be passed over the wire trivially. This may cause the type of {@link A} - * to be less convenient that desired. Eg. you may have to pass {@code BigInt}s in as strings, + * to be less convenient that desired. Eg. you may have to pass `BigInt`s in as strings, * etc. Another important note about {@link A} is that each of its fields must implement the * {@link Argument} interface. This is important because it enables Zupass to introspect the - * arguments, and to implement useful features like the {@code GenericProveScreen}, which is + * arguments, and to implement useful features like the `GenericProveScreen`, which is * a screen that automatically builds a UI which lets a user input all the arguments required to * instantiate a new instance of a particular {@link PCD} based on the request it gets from a * third party. @@ -210,7 +210,7 @@ export interface Argument< /** * This is the type of the params that are passed into the validator function * of the argument. It is important that this type is serializable and - * deserializable using {@code JSON.stringify} and {@code JSON.parse}, because + * deserializable using `JSON.stringify` and `JSON.parse`, because * these arguments should be able to be passed over the wire trivially. */ ValidatorParams = Record @@ -246,7 +246,7 @@ export interface Argument< /** * Fields of the object passed into {@link PCDPackage.prove} can only represent * one of the following types. {@link Unknown} is included to be used in a similar - * way as {@code unknown} is used in TypeScript. + * way as `unknown` is used in TypeScript. */ export enum ArgumentTypeName { String = "String", diff --git a/packages/lib/pod/src/podCrypto.ts b/packages/lib/pod/src/podCrypto.ts index de539dcb94..0d9764ce17 100644 --- a/packages/lib/pod/src/podCrypto.ts +++ b/packages/lib/pod/src/podCrypto.ts @@ -142,7 +142,7 @@ export function encodePublicKey( } /** - * Decodes a public key packed by {@encodePublicKey}. The input must be + * Decodes a public key packed by {@link encodePublicKey}. The input must be * 32 bytes, represented as hex or Base64. Base64 padding is optional. * * @param publicKey the public key string to decode diff --git a/packages/lib/pod/src/podTypes.ts b/packages/lib/pod/src/podTypes.ts index 06cbd837cc..533c8e859c 100644 --- a/packages/lib/pod/src/podTypes.ts +++ b/packages/lib/pod/src/podTypes.ts @@ -22,13 +22,6 @@ export type POD_VALUE_STRING_TYPE_IDENTIFIER = */ export const EDDSA_PUBKEY_TYPE_STRING = "eddsa_pubkey"; -/** - * Regex matching legal values for types encoded as strings by - * {@link podValueToRawValue}. This matches strings of the form - * `pod_${PODName}:${string}`. - */ -export const POD_STRING_TYPE_REGEX = new RegExp(/pod_([A-Za-z_]\w*):(.*)$/); - /** * POD value for a user-specififed string. String values can contain any * string. They are not limited like names. diff --git a/packages/lib/pod/src/podUtil.ts b/packages/lib/pod/src/podUtil.ts index 091d1f0d07..e8db354c0e 100644 --- a/packages/lib/pod/src/podUtil.ts +++ b/packages/lib/pod/src/podUtil.ts @@ -34,7 +34,7 @@ export function getPODValueForCircuit(podValue: PODValue): bigint | undefined { * of a numeric type. * * @param podValue the value to convert - * @param nameForErrorMessages the name of this value, which is used only for + * @param nameForErrorMesages the name of this value, which is used only for * error messages (not checked for legality). * @returns the numeric value, or undefined if this value cannot be represented * in a circuit @@ -106,7 +106,7 @@ export function printPODValue(podValue: PODValue | undefined): string { * but also handles the case where the whole value is undefined (but not * undefined values inside of a tuple). * - * @param podValue the POD value (or undefined) to print + * @param value the POD value (or undefined) to print * @returns a human-readable string * @throws if the POD value is malformed */ @@ -215,7 +215,7 @@ export function decodeBytesRaw( * @param encodingPattern a regex which matches valid encodings of bytes with * an expected fixed size. This pattern is expected to have groups * separately matching each of the supported encodings. See - * {@link PRIVATE_KEY_REGEX} for an example. + * {@link @pcd/pod!PRIVATE_KEY_REGEX} for an example. * @param encodingGroups a description of the match groups in the regex, * in the order they should be checked. * @param errorMessage human-readable message for error thrown if decoding diff --git a/packages/lib/podbox-shared/src/PODPipeline/updates.ts b/packages/lib/podbox-shared/src/PODPipeline/updates.ts index d5ae1ddeda..240dc3ce4a 100644 --- a/packages/lib/podbox-shared/src/PODPipeline/updates.ts +++ b/packages/lib/podbox-shared/src/PODPipeline/updates.ts @@ -38,7 +38,8 @@ function stringifyCSV( /** * Parses the CSV string into a 2D array of strings. * - * @param options The options to use for parsing. + * @param csv the input + * @param columns the columns used for parsing * @returns The parsed CSV data. */ export function parseCSV( diff --git a/packages/lib/util/src/strings.ts b/packages/lib/util/src/strings.ts index 00121e79c6..5158c4b02b 100644 --- a/packages/lib/util/src/strings.ts +++ b/packages/lib/util/src/strings.ts @@ -47,7 +47,7 @@ export function flattenObject( } /** - * Shorthand for {@code JSON.stringify} + * Shorthand for `JSON.stringify` */ export function str(val: unknown): string { return JSON.stringify(val, null, 2); diff --git a/packages/pcd/gpc-pcd/src/GPCPCD.ts b/packages/pcd/gpc-pcd/src/GPCPCD.ts index eb56d01145..46c4b4cf4b 100644 --- a/packages/pcd/gpc-pcd/src/GPCPCD.ts +++ b/packages/pcd/gpc-pcd/src/GPCPCD.ts @@ -100,7 +100,7 @@ export type PODPCDArgValidatorParams = { /** * JSON-formatted proof configuration used to narrow down the selection of * POD PCDs. This should coincide with the proof config supplied in the - * `GPCPCDArgs`. May be parsed using {@link proofConfigFromJSON}. + * `GPCPCDArgs`. May be parsed using {@link @pcd/gpc!proofConfigFromJSON}. */ proofConfig?: JSONProofConfig; @@ -109,7 +109,7 @@ export type PODPCDArgValidatorParams = { * to those satisfying the list membership check specified in the proof * config. This should coincide with the membership lists supplied in * the `GPCPCDArgs` (if any). May be parsed using - * {@link podMembershipListsFromJSON} + * {@link @pcd/gpc!podMembershipListsFromJSON} */ membershipLists?: JSONPODMembershipLists; @@ -139,7 +139,7 @@ export type GPCPCDArgs = { * See {@link GPCProofConfig} for more information. * * This is formatted in a JSON-compatible format which can be parsed - * using {@link proofConfigFromJSON}. + * using {@link @pcd/gpc!proofConfigFromJSON}. */ proofConfig: ObjectArgument; @@ -166,7 +166,7 @@ export type GPCPCDArgs = { * of this value and owner identity. This can be used to avoid duplicate * actions by the same user, without revealing the user's identity. * - * You can use {@link podValueToJSON} to produce this format. + * You can use {@link @pcd/pod!podValueToJSON} to produce this format. */ externalNullifier: ObjectArgument; @@ -174,7 +174,7 @@ export type GPCPCDArgs = { * Optional membership lists, if needed by the proof configuration. This is * always revealed. * - * You can use {@link podMembershipListsToJSON} to produce this format. + * You can use {@link @pcd/gpc!podMembershipListsToJSON} to produce this format. */ membershipLists: ObjectArgument; @@ -183,7 +183,7 @@ export type GPCPCDArgs = { * the proof and cryptographically verified. This can be used to avoid reuse * of the same proof. * - * You can use {@link podValueToJSON} to produce this format. + * You can use {@link @pcd/pod!podValueToJSON} to produce this format. */ watermark: ObjectArgument; @@ -204,9 +204,8 @@ export type GPCPCDArgs = { */ export interface GPCPCDClaim { /** - * The entries of this POD, in sorted order as they are Merklized. - * See the {@link pod} accessor on {@link GPCPCD} if you need to manipulate - * these entries as a POD object. + * The configuration used to generate this proof, including the identifier + * of the specific circuit used. */ config: GPCBoundConfig; diff --git a/packages/pcd/gpc-pcd/src/json.ts b/packages/pcd/gpc-pcd/src/json.ts index 89d5b6c685..2ebf122aea 100644 --- a/packages/pcd/gpc-pcd/src/json.ts +++ b/packages/pcd/gpc-pcd/src/json.ts @@ -32,8 +32,6 @@ export function fixedPODEntriesFromJSON( * safely serialized using `JSON.stringify`. * * @param fixedPODEntries the prescribed values to serialize - * @param space pretty-printing configuration, as defined by the corresponding - * argument to JSON.stringify. * @returns a string representation */ export function fixedPODEntriesToJSON( diff --git a/packages/pcd/pod-pcd/src/PODPCD.ts b/packages/pcd/pod-pcd/src/PODPCD.ts index 095454f023..4f283bebe8 100644 --- a/packages/pcd/pod-pcd/src/PODPCD.ts +++ b/packages/pcd/pod-pcd/src/PODPCD.ts @@ -25,14 +25,15 @@ export type PODPCDInitArgs = unknown; */ export type PODPCDArgs = { /** - * A {@link ITicketData} object containing ticket information that is encoded into this PCD. + * A {@link JSONPODEntries} object containing the entries (name/value pairs) + * to include in the new POD. */ entries: ObjectArgument; /** * The signer's EdDSA private key. This is a 32-byte value used to sign the - * message. {@link newEdDSAPrivateKey} is recommended for generating highly - * secure private keys. + * message. See {@link @pcd/pod!decodePrivateKey} in `@pcd/pod` if you need + * to manipulate or convert this value. */ privateKey: StringArgument; @@ -55,15 +56,15 @@ export type PODPCDArgs = { export interface PODPCDClaim { /** * The entries of this POD, in sorted order as they are Merklized. - * See the {@link pod} accessor on {@link PODPCD} if you need to manipulate - * these entries as a POD object. + * See the {@link PODPCD.pod} accessor on {@link PODPCD} if you need to + * manipulate these entries as a POD object. */ entries: PODEntries; /** * The EdDSA public key of the signer of this pod, in a packed string form. - * See {@link decodePublicKey} in `@pcd/pod` if you need to manipulate or - * convert this value. + * See {@link @pcd/pod!decodePublicKey} in `@pcd/pod` if you need to + * manipulate or convert this value. */ signerPublicKey: string; } @@ -75,7 +76,7 @@ export interface PODPCDClaim { export interface PODPCDProof { /** * The EdDSA signature of this POD's content ID, in a packed string form. - * See {@link decodeSignature} in `@pcd/pod` if you need to manipulate + * See {@link @pcd/pod!decodeSignature} in `@pcd/pod` if you need to manipulate * or convert this value. */ signature: string; diff --git a/packages/pcd/pod-ticket-pcd/src/PODTicketPCD.ts b/packages/pcd/pod-ticket-pcd/src/PODTicketPCD.ts index 0eb2f9eba6..509a9bcd3c 100644 --- a/packages/pcd/pod-ticket-pcd/src/PODTicketPCD.ts +++ b/packages/pcd/pod-ticket-pcd/src/PODTicketPCD.ts @@ -8,7 +8,8 @@ import type { IPODTicketData } from "./schema"; export const PODTicketPCDTypeName = "pod-ticket-pcd"; /** - * Copied from {@link TicketCategory} in {@link EdDSATicketPCD}. + * Copied from {@link @pcd/eddsa-ticket-pcd!TicketCategory} in + * {@link @pcd/eddsa-ticket-pcd!EdDSATicketPCD}. */ export enum TicketCategory { ZuConnect = 0, @@ -23,8 +24,9 @@ export enum TicketCategory { */ export type PODTicketPCDArgs = { /** - * The EdDSA private key is a 32-byte value used to sign the message. - * {@link newEdDSAPrivateKey} is recommended for generating highly secure private keys. + * The signer's EdDSA private key. This is a 32-byte value used to sign the + * message. See {@link @pcd/pod!decodePrivateKey} in `@pcd/pod` if you need + * to manipulate or convert this value. */ privateKey: StringArgument; From 40bc6cd20727ec131fcf2e4cb5891d58e59a97ea Mon Sep 17 00:00:00 2001 From: Andrew Twyman Date: Fri, 20 Dec 2024 18:24:30 -0800 Subject: [PATCH 2/3] Linux filenames are case-sensitive --- packages/lib/gpcircuits/tsconfig.cjs.json | 2 +- packages/lib/gpcircuits/tsconfig.esm.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/lib/gpcircuits/tsconfig.cjs.json b/packages/lib/gpcircuits/tsconfig.cjs.json index 3150d76e0d..f9a2fedf36 100644 --- a/packages/lib/gpcircuits/tsconfig.cjs.json +++ b/packages/lib/gpcircuits/tsconfig.cjs.json @@ -6,7 +6,7 @@ "tsBuildInfoFile": "./tsconfig.cjs.tsbuildinfo" }, // For CJS/ESM builds, do not include test files - "include": ["src", "scripts", "circomKit.json", "src/circuitParameters.json"], + "include": ["src", "scripts", "circomkit.json", "src/circuitParameters.json"], // DO NOT MODIFY MANUALLY BEYOND THIS POINT // References are automatically maintained by `yarn fix-references` "references": [ diff --git a/packages/lib/gpcircuits/tsconfig.esm.json b/packages/lib/gpcircuits/tsconfig.esm.json index bf77d36476..1cf5013d3b 100644 --- a/packages/lib/gpcircuits/tsconfig.esm.json +++ b/packages/lib/gpcircuits/tsconfig.esm.json @@ -6,7 +6,7 @@ "tsBuildInfoFile": "./tsconfig.esm.tsbuildinfo" }, // For CJS/ESM builds, do not include test files - "include": ["src", "scripts", "circomKit.json", "src/circuitParameters.json"], + "include": ["src", "scripts", "circomkit.json", "src/circuitParameters.json"], // DO NOT MODIFY MANUALLY BEYOND THIS POINT // References are automatically maintained by `yarn fix-references` "references": [ From 9a363fcf2bb23156d3cf335701509fbb97be2fb8 Mon Sep 17 00:00:00 2001 From: Andrew Twyman Date: Fri, 20 Dec 2024 23:56:03 -0800 Subject: [PATCH 3/3] Another case-sensitivity fix --- packages/lib/gpcircuits/tsconfig.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/lib/gpcircuits/tsconfig.json b/packages/lib/gpcircuits/tsconfig.json index 291f7c5e86..251e680324 100644 --- a/packages/lib/gpcircuits/tsconfig.json +++ b/packages/lib/gpcircuits/tsconfig.json @@ -8,7 +8,7 @@ "rootDir": "." }, // Some artifact-including packages need to import a JSON file - "include": ["src", "test", "src/*.json", "scripts", "circomKit.json"], + "include": ["src", "test", "src/*.json", "scripts", "circomkit.json"], "exclude": ["dist", "build", "node_modules"], // DO NOT MODIFY MANUALLY BEYOND THIS POINT // References are automatically maintained by `yarn fix-references`