Merge pull request #1974 from o1-labs/2025-01-touch-up-doc-comments

Add doc comments to ZkProgram et al

Author: 45930

CHANGELOG.md

@@ -19,6 +19,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 - `setFee` and `setFeePerSnarkCost` for `Transaction` and `PendingTransaction` https://github.com/o1-labs/o1js/pull/1968
+- Doc comments for various ZkProgram methods https://github.com/o1-labs/o1js/pull/1974
 
 ### Changed
 - Sort order for actions now includes the transaction sequence number and the exact account id sequence https://github.com/o1-labs/o1js/pull/1917

src/lib/proof-system/proof.ts

@@ -3,7 +3,7 @@ import {
   initializeBindings,
   withThreadPool,
 } from '../../snarky.js';
-import { Pickles } from '../../snarky.js';
+import { Pickles, Base64ProofString } from '../../snarky.js';
 import { Field, Bool } from '../provable/wrapped.js';
 import type {
   FlexibleProvable,
@@ -121,7 +121,10 @@ class ProofBase<Input = any, Output = any> {
     return (this.constructor as typeof ProofBase).publicFields(this);
   }
 
-  static _proofFromBase64(proofString: string, maxProofsVerified: 0 | 1 | 2) {
+  static _proofFromBase64(
+    proofString: Base64ProofString,
+    maxProofsVerified: 0 | 1 | 2
+  ) {
     assertBindingsInitialized();
     return Pickles.proofOfBase64(proofString, maxProofsVerified)[1];
   }

src/lib/proof-system/zkprogram.ts

@@ -1,5 +1,11 @@
 import { EmptyUndefined, EmptyVoid } from '../../bindings/lib/generic.js';
-import { Snarky, initializeBindings, withThreadPool } from '../../snarky.js';
+import {
+  Base64ProofString,
+  Base64VerificationKeyString,
+  Snarky,
+  initializeBindings,
+  withThreadPool,
+} from '../../snarky.js';
 import { Pickles, Gate } from '../../snarky.js';
 import { Field } from '../provable/wrapped.js';
 import {
@@ -118,9 +124,16 @@ function createProgramState() {
   };
 }
 
+/**
+ * Initializes Pickles bindings, serializes the input proof and verification key for use in OCaml, then calls into the Pickles verify function and returns the result.
+ *
+ * @param proof Either a `Proof` instance or a serialized JSON proof
+ * @param verificationKey Either a base64 serialized verification key or a `VerificationKey` instance which will be base64 serialized for use in the bindings.
+ * @returns A promise that resolves to a boolean indicating whether the proof is valid.
+ */
 async function verify(
   proof: ProofBase<any, any> | JsonProof,
-  verificationKey: string | VerificationKey
+  verificationKey: Base64VerificationKeyString | VerificationKey
 ) {
   await initializeBindings();
   let picklesProof: Pickles.Proof;
@@ -155,11 +168,16 @@ async function verify(
   );
 }
 
+/**
+ * Serializable representation of a Pickles proof, useful for caching compiled proofs.
+ */
 type JsonProof = {
+  /** Array of string, where each string is a `Field` in the publicInput of this proof */
   publicInput: string[];
+  /** Array of string, where each string is a `Field` in the publicOutput of this proof */
   publicOutput: string[];
   maxProofsVerified: 0 | 1 | 2;
-  proof: string;
+  proof: Base64ProofString;
 };
 type CompiledTag = unknown;
 
@@ -183,6 +201,33 @@ let SideloadedTag = {
   },
 };
 
+/**
+ * Wraps config + provable code into a program capable of producing {@link Proof}s.
+ *
+ * @example
+ * ```ts
+ * const ExampleProgram = ZkProgram({
+ *   name: 'ExampleProgram',
+ *   publicOutput: Int64,
+ *   methods: {
+ *     // Prove that I know 2 numbers less than 100 each, whose product is greater than 1000
+ *     provableMultiply: {
+ *       privateInputs: [Int64, Int64],
+ *       method: async (n1: Int64, n2: Int64) => {
+ *         n1.assertLessThan(100);
+ *         n2.assertLessThan(100);
+ *         const publicOutput = n1.mul(n2);
+ *         publicOutput.assertGreaterThan(1000);
+ *         return { publicOutput: n1.mul(n2) }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @param config The configuration of the program, describing the type of the public input and public output, as well as defining the methods which can be executed provably.
+ * @returns an object that can be used to compile, prove, and verify the program.
+ */
 function ZkProgram<
   Config extends {
     publicInput?: ProvableType;
@@ -591,6 +636,33 @@ type ZkProgram<
   }
 > = ReturnType<typeof ZkProgram<Config, Methods>>;
 
+/**
+ * A class representing the type of Proof produced by the {@link ZkProgram} in which it is used.
+ *
+ * @example
+ * ```ts
+ * const ExampleProgram = ZkProgram({
+ *   name: 'ExampleProgram',
+ *   publicOutput: Field,
+ *   methods: {
+ *     baseCase: {
+ *       privateInputs: [],
+ *       method: async () => {
+ *         return { publicOutput: Field(0) }
+ *       }
+ *     },
+ *     add: {
+ *       privateInputs: [SelfProof, Field],
+ *       // `previous` is the type of proof produced by ExampleProgram
+ *       method: async (previous: SelfProof<undefined, Field>, f: Field) => {
+ *         previous.verify();
+ *         return { publicOutput: previous.publicOutput.add(f) }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
 class SelfProof<PublicInput, PublicOutput> extends Proof<
   PublicInput,
   PublicOutput

src/snarky.d.ts

@@ -48,10 +48,22 @@ export {
   MlPublicKeyVar,
   MlFeatureFlags,
   areBindingsInitialized,
+  Base64ProofString,
+  Base64VerificationKeyString,
 };
 
 declare let areBindingsInitialized: boolean;
 
+/**
+ * A string representation of a Pickles proof in base64 encoding, used for communication between OCaml and TypeScript and for JSON serialization.
+ */
+type Base64ProofString = string;
+
+/**
+ * A string representation of a constraint system's verification key in base64 encoding, used for communication between OCaml and TypeScript and for JSON serialization.
+ */
+type Base64VerificationKeyString = string;
+
 type WasmModule = typeof wasm;
 
 type MlGroup = MlPair<FieldVar, FieldVar>;
@@ -700,13 +712,15 @@ declare const Pickles: {
     /**
      * @returns (base64 vk, hash)
      */
-    getVerificationKey: () => Promise<[_: 0, data: string, hash: FieldConst]>;
+    getVerificationKey: () => Promise<
+      [_: 0, data: Base64VerificationKeyString, hash: FieldConst]
+    >;
   };
 
   verify(
     statement: Pickles.Statement<FieldConst>,
     proof: Pickles.Proof,
-    verificationKey: string
+    verificationKey: Base64VerificationKeyString
   ): Promise<boolean>;
 
   loadSrsFp(): WasmFpSrs;
@@ -720,12 +734,16 @@ declare const Pickles: {
   /**
    * @returns (base64 vk, hash)
    */
-  dummyVerificationKey: () => [_: 0, data: string, hash: FieldConst];
+  dummyVerificationKey: () => [
+    _: 0,
+    data: Base64VerificationKeyString,
+    hash: FieldConst
+  ];
 
   encodeVerificationKey: (vk: MlWrapVerificationKey) => string;
   decodeVerificationKey: (vk: string) => MlWrapVerificationKey;
 
-  proofToBase64: (proof: [0 | 1 | 2, Pickles.Proof]) => string;
+  proofToBase64: (proof: [0 | 1 | 2, Pickles.Proof]) => Base64ProofString;
   proofOfBase64: <N extends 0 | 1 | 2>(
     base64: string,
     maxProofsVerified: N
@@ -745,7 +763,10 @@ declare const Pickles: {
     // Instantiate the verification key inside the circuit (required).
     inCircuit: (tag: unknown, verificationKey: unknown) => undefined;
     // Instantiate the verification key in prover-only logic (also required).
-    inProver: (tag: unknown, verificationKey: string) => undefined;
+    inProver: (
+      tag: unknown,
+      verificationKey: Base64VerificationKeyString
+    ) => undefined;
     // Create an in-circuit representation of a verification key
     vkToCircuit: (
       verificationKey: () => string