docs

Author: chfanghr

src/library/plugin/pluginType.ts

@@ -5,20 +5,26 @@ import z from 'zod';
 // Interfaces used on the server side.
 
 export interface IMinAuthPlugin<PublicInputsArgs, Output> {
+  // Verify a proof give the arguments for fetching public inputs, and return
+  // the output.
   verifyAndGetOutput(
     publicInputArgs: PublicInputsArgs,
     serializedProof: JsonProof): Promise<Output>;
 
+  // The schema of the arguments for fetching public inputs.
   readonly publicInputArgsSchema: z.ZodType<PublicInputsArgs>;
 
+  // TODO: enable plugins to invalidate a proof.
   // FIXME(Connor): I still have some questions regarding the validation functionality.
   // In particular, what if a plugin want to invalidate the proof once the public inputs change?
   // We have to at least pass PublicInputsArgs.
   //
   // checkOutputValidity(output: Output): Promise<boolean>;
 
+  // Custom routes and handlers. Will be installed under `/plugins/<plugin name>`
   readonly customRoutes: Record<string, RequestHandler>;
 
+  // The verification key of the underlying zk circuit.
   readonly verificationKey: string;
 }
 
@@ -27,6 +33,8 @@ export interface IMinAuthPluginFactory<
   T extends IMinAuthPlugin<PublicInputsArgs, Output>,
   Configuration, PublicInputsArgs, Output> {
 
+  // Initialize the plugin given the configuration. The underlying zk program is 
+  // typically compiled here.
   initialize(cfg: Configuration): Promise<T>;
 
   readonly configurationSchema: z.ZodType<Configuration>;

src/library/tools/pluginServer/config.ts

@@ -7,6 +7,9 @@ import { SimplePreimagePlugin } from "plugins/simplePreimage/plugin";
 import { SimplePasswordTreePlugin } from "plugins/passwordTree/plugin";
 
 // TODO: make use of heterogeneous lists
+/**
+ * All the available plugins and their names go here.
+ */
 export const untypedPlugins:
   Record<string,
     IMinAuthPluginFactory<IMinAuthPlugin<any, any>, any, any, any>>
@@ -31,6 +34,13 @@ const serverConfigurationsSchema = z.object({
 
 export type ServerConfigurations = z.infer<typeof serverConfigurationsSchema>;
 
+/**
+ * Load configurations from disk. The configuration is encoded in yaml and
+ * should conform to `serverConfigurationsSchema`. The location of the file can
+ * be specified using the `MINAUTH_CONFIG` environmental variable; if it's not
+ * set, `./config.yaml` will be used.
+ * @returns The decoded configurations for the server and plugins.
+ */
 export function readConfigurations(): ServerConfigurations {
   const configFile =
     env.get('MINAUTH_CONFIG')

src/library/tools/pluginServer/index.ts

@@ -6,6 +6,10 @@ import { readConfigurations, untypedPlugins } from './config';
 
 const configurations = readConfigurations();
 
+/**
+ * Construct plugins which are enabled in the configuration.
+ * @returns A record of plugin instances.
+ */
 async function initializePlugins():
   Promise<Record<string, IMinAuthPlugin<any, any>>> {
   console.log('compiling plugins');
@@ -20,37 +24,41 @@ async function initializePlugins():
 
 initializePlugins()
   .then((activePlugins) => {
+    // The type of `POST /verifyProof` requests' body.
     interface VerifyProofData {
       plugin: string;
       publicInputArgs: any;
       proof: JsonProof;
     }
 
+    // Use the appropriate plugin to verify the proof and return the output.
     async function verifyProof(data: VerifyProofData): Promise<any> {
       const pluginName = data.plugin;
       console.info(`verifying proof using plugin ${pluginName}`);
       const pluginInstance = activePlugins[pluginName];
       if (!pluginInstance)
         throw `plugin ${pluginName} not found`;
+      // Step 1: check that the proof was generated using a certain verification key.
       const proofValid = await verify(data.proof, pluginInstance.verificationKey);
       if (!proofValid)
         throw `invalid proof`;
+      // Step 2: use the plugin to extract the output. The plugin is also responsible
+      // for checking the legitimacy of the public inputs.
       const typedPublicInputArgs
         = pluginInstance.publicInputArgsSchema.parse(data.publicInputArgs);
       const output =
         await pluginInstance.verifyAndGetOutput(typedPublicInputArgs, data.proof);
-      if (!output)
-        throw `plugin ${pluginName} failed to verify the proof`;
       return output;
     }
 
     const app = express().use(bodyParser.json());
 
+    // Register all custom routes of active plugins under `/plugins/${pluginName}`.
     Object.entries(activePlugins).map(([name, plugin]) =>
       Object
         .entries(plugin.customRoutes)
         .map(([path, handler]) =>
-          app.use(`plugins/${name}/${path}`, handler)
+          app.use(`/plugins/${name}/${path}`, handler)
         )
     );