cleanup and comment

yarn-project/circuits.js/src/structs/kernel/combined_accumulated_data.ts

@@ -456,15 +456,15 @@ export class FinalAccumulatedData {
 export class AccumulatedNonRevertibleData {
   constructor(
     /**
-     * The new commitments made in this transaction.
+     * The new non-revertible commitments made in this transaction.
      */
     public newCommitments: Tuple<SideEffect, typeof MAX_NEW_COMMITMENTS_PER_TX_META>,
     /**
-     * The new nullifiers made in this transaction.
+     * The new non-revertible nullifiers made in this transaction.
      */
     public newNullifiers: Tuple<SideEffectLinkedToNoteHash, typeof MAX_NEW_NULLIFIERS_PER_TX_META>,
     /**
-     * Current public call stack.
+     * Current public call stack that will produce non-revertible side effects.
      */
     public publicCallStack: Tuple<CallRequest, typeof MAX_PUBLIC_CALL_STACK_LENGTH_PER_TX_META>,
   ) {}

yarn-project/circuits.js/src/structs/kernel/private_kernel_inner_circuit_private_inputs.ts

@@ -9,7 +9,7 @@ import { PrivateKernelInnerData } from './private_kernel_inner_data.js';
 export class PrivateKernelInnerCircuitPrivateInputs {
   constructor(
     /**
-     * The previous kernel data (dummy if this is the first kernel).
+     * The previous kernel data
      */
     public previousKernel: PrivateKernelInnerData,
     /**

yarn-project/circuits.js/src/structs/kernel/private_kernel_inner_circuit_public_inputs.ts

@@ -5,14 +5,17 @@ import { AggregationObject } from '../aggregation_object.js';
 import { CombinedAccumulatedData } from './combined_accumulated_data.js';
 import { CombinedConstantData } from './combined_constant_data.js';
 
+/**
+ * Public inputs to the inner private kernel circuit
+ */
 export class PrivateKernelInnerCircuitPublicInputs {
   constructor(
     /**
      * Aggregated proof of all the previous kernel iterations.
      */
     public aggregationObject: AggregationObject, // Contains the aggregated proof of all previous kernel iterations
     /**
-     * The side effect counter that meta side effects are all beneath.
+     * The side effect counter that non-revertible side effects are all beneath.
      */
     public maxNonRevertibleSideEffectCounter: Fr,
     /**

yarn-project/circuits.js/src/structs/kernel/private_kernel_tail_circuit_private_inputs.ts

@@ -11,6 +11,9 @@ import { Fr, GrumpkinScalar } from '../index.js';
 import { SideEffect, SideEffectLinkedToNoteHash } from '../side_effects.js';
 import { PrivateKernelInnerData } from './private_kernel_inner_data.js';
 
+/**
+ * Input to the private kernel circuit - tail call.
+ */
 export class PrivateKernelTailCircuitPrivateInputs {
   constructor(
     /**

yarn-project/circuits.js/src/structs/kernel/private_kernel_tail_circuit_public_inputs.ts

@@ -4,6 +4,9 @@ import { AggregationObject } from '../aggregation_object.js';
 import { AccumulatedNonRevertibleData, FinalAccumulatedData } from './combined_accumulated_data.js';
 import { CombinedConstantData } from './combined_constant_data.js';
 
+/**
+ * Output from to the private kernel circuit - tail call.
+ */
 export class PrivateKernelTailCircuitPublicInputs {
   constructor(
     /**

yarn-project/circuits.js/src/structs/kernel/private_kernel_tail_data.ts

@@ -9,12 +9,12 @@ import { VerificationKey } from '../verification_key.js';
 import { PrivateKernelTailCircuitPublicInputs } from './private_kernel_tail_circuit_public_inputs.js';
 
 /**
- * Data of the previous kernel iteration in the chain of kernels.
+ * Data of the private kernel tail.
  */
 export class PrivateKernelTailData {
   constructor(
     /**
-     * Public inputs of the previous kernel.
+     * Outputs of the private kernel tail.
      */
     public publicInputs: PrivateKernelTailCircuitPublicInputs,
     /**

yarn-project/circuits.js/src/structs/kernel/public_kernel_circuit_public_inputs.ts

@@ -4,6 +4,10 @@ import { AggregationObject } from '../aggregation_object.js';
 import { AccumulatedNonRevertibleData, CombinedAccumulatedData } from './combined_accumulated_data.js';
 import { CombinedConstantData } from './combined_constant_data.js';
 
+/**
+ * Outputs from the public kernel circuits.
+ * All Public kernels use this shape for outputs.
+ */
 export class PublicKernelCircuitPublicInputs {
   constructor(
     /**

yarn-project/circuits.js/src/structs/kernel/public_kernel_data.ts

@@ -9,7 +9,7 @@ import { VerificationKey } from '../verification_key.js';
 import { PublicKernelCircuitPublicInputs } from './public_kernel_circuit_public_inputs.js';
 
 /**
- * Data of the previous kernel iteration in the chain of kernels.
+ * Data of the previous public kernel iteration in the chain of kernels.
  */
 export class PublicKernelData {
   constructor(

yarn-project/circuits.js/src/structs/private_circuit_public_inputs.ts

@@ -42,7 +42,7 @@ export class PrivateCircuitPublicInputs {
      */
     public returnValues: Tuple<Fr, typeof RETURN_VALUES_LENGTH>,
     /**
-     * The side-effect high watermark of the irrevertible part of the function call.
+     * The side-effect counter under which all side effects are non-revertible.
      */
     public maxNonRevertibleSideEffectCounter: Fr,
     /**

yarn-project/circuits.js/src/tests/factories.ts

@@ -289,11 +289,11 @@ export function makeFinalAccumulatedData(seed = 1, full = false): FinalAccumulat
 }
 
 /**
- * Creates arbitrary accumulated data for a Tx's meta phase.
+ * Creates arbitrary accumulated data for a Tx's non-revertible side effects.
  * @param seed - The seed to use for generating the data.
- * @returns An instance of AccumulatedMetaData.
+ * @returns An instance of AccumulatedNonRevertibleData.
  */
-export function makeAccumulatedMetaData(seed = 1, full = false): AccumulatedNonRevertibleData {
+export function makeAccumulatedNonRevertibleData(seed = 1, full = false): AccumulatedNonRevertibleData {
   const tupleGenerator = full ? makeTuple : makeHalfFullTuple;
 
   return new AccumulatedNonRevertibleData(
@@ -376,26 +376,26 @@ export function makePublicCircuitPublicInputs(
 }
 
 /**
- * Creates arbitrary kernel circuit public inputs.
+ * Creates arbitrary public kernel circuit public inputs.
  * @param seed - The seed to use for generating the kernel circuit public inputs.
- * @returns Kernel circuit public inputs.
+ * @returns Public kernel circuit public inputs.
  */
 export function makePublicKernelCircuitPublicInputs(
   seed = 1,
   fullAccumulatedData = true,
 ): PublicKernelCircuitPublicInputs {
   return new PublicKernelCircuitPublicInputs(
     makeAggregationObject(seed),
-    makeAccumulatedMetaData(seed, fullAccumulatedData),
+    makeAccumulatedNonRevertibleData(seed, fullAccumulatedData),
     makeAccumulatedData(seed, fullAccumulatedData),
     makeConstantData(seed + 0x100),
     true,
   );
 }
 /**
- * Creates arbitrary kernel circuit public inputs.
+ * Creates arbitrary private kernel inner circuit public inputs.
  * @param seed - The seed to use for generating the kernel circuit public inputs.
- * @returns Kernel circuit public inputs.
+ * @returns Private kernel circuit public inputs.
  */
 export function makePrivateKernelInnerCircuitPublicInputs(
   seed = 1,
@@ -411,14 +411,14 @@ export function makePrivateKernelInnerCircuitPublicInputs(
 }
 
 /**
- * Creates arbitrary kernel circuit public inputs.
+ * Creates arbitrary private kernel tail circuit public inputs.
  * @param seed - The seed to use for generating the kernel circuit public inputs.
- * @returns Kernel circuit public inputs.
+ * @returns Private kernel tail circuit public inputs.
  */
 export function makePrivateKernelTailCircuitPublicInputs(seed = 1, full = true): PrivateKernelTailCircuitPublicInputs {
   return new PrivateKernelTailCircuitPublicInputs(
     makeAggregationObject(seed),
-    makeAccumulatedMetaData(seed, full),
+    makeAccumulatedNonRevertibleData(seed, full),
     makeFinalAccumulatedData(seed, full),
     makeConstantData(seed + 0x100),
     true,
@@ -518,9 +518,9 @@ export function makeGrumpkinPrivateKey(seed = 1): GrumpkinPrivateKey {
 }
 
 /**
- * Makes arbitrary previous kernel data.
+ * Makes arbitrary public kernel data.
  * @param seed - The seed to use for generating the previous kernel data.
- * @param kernelPublicInputs - The kernel public inputs to use for generating the previous kernel data.
+ * @param kernelPublicInputs - The public kernel public inputs to use for generating the public kernel data.
  * @returns A previous kernel data.
  */
 export function makePublicKernelData(seed = 1, kernelPublicInputs?: PublicKernelCircuitPublicInputs): PublicKernelData {
@@ -536,7 +536,7 @@ export function makePublicKernelData(seed = 1, kernelPublicInputs?: PublicKernel
 /**
  * Makes arbitrary previous kernel data.
  * @param seed - The seed to use for generating the previous kernel data.
- * @param inputs - The kernel public inputs to use for generating the previous kernel data.
+ * @param inputs - The kernel public inputs to use for generating the private kernel inner data.
  * @returns A previous kernel data.
  */
 export function makePrivateKernelInnerData(
@@ -562,18 +562,18 @@ export function makeProof(seed = 1) {
 }
 
 /**
- * Makes arbitrary private kernel inputs - initial call.
+ * Makes arbitrary private kernel init private inputs
  * @param seed - The seed to use for generating the private kernel inputs.
- * @returns Private kernel inputs.
+ * @returns Private kernel init private inputs.
  */
 export function makePrivateKernelInitCircuitPrivateInputs(seed = 1): PrivateKernelInitCircuitPrivateInputs {
   return new PrivateKernelInitCircuitPrivateInputs(makeTxRequest(seed), makePrivateCallData(seed + 0x1000));
 }
 
 /**
- * Makes arbitrary private kernel inputs - inner call.
+ * Makes arbitrary private kernel inner private inputs
  * @param seed - The seed to use for generating the private kernel inputs.
- * @returns Private kernel inputs.
+ * @returns Private kernel inner private inputs.
  */
 export function makePrivateKernelInnerCircuitPrivateInputs(seed = 1): PrivateKernelInnerCircuitPrivateInputs {
   return new PrivateKernelInnerCircuitPrivateInputs(
@@ -644,7 +644,7 @@ export function makePublicKernelCircuitPrivateInputs(seed = 1): PublicKernelCirc
 }
 
 /**
- * Makes arbitrary public kernel inputs.
+ * Makes arbitrary public kernel private inputs.
  * @param seed - The seed to use for generating the public kernel inputs.
  * @param tweak - An optional function to tweak the output before computing hashes.
  * @returns Public kernel inputs.

yarn-project/noir-protocol-circuits/src/crates/public-kernel-lib/src/common.nr

@@ -54,35 +54,7 @@ pub fn validate_inputs(public_call: PublicCallData) {
     assert(public_call.bytecode_hash != 0, "Bytecode hash cannot be zero");
 }
 
-pub fn initialize_end_values_from_private_kernel_tail_data(
-    previous_kernel: PrivateKernelTailData,
-    circuit_outputs: &mut PublicKernelCircuitPublicInputsBuilder
-) {
-    // Initialises the circuit outputs with the end state of the previous iteration
-    circuit_outputs.constants = previous_kernel.public_inputs.constants;
-
-    // Ensure the arrays are the same as previously, before we start pushing more data onto them in other
-    // functions within this circuit:
-    let start = previous_kernel.public_inputs.end;
-
-    circuit_outputs.end.new_commitments = array_to_bounded_vec(start.new_commitments);
-    circuit_outputs.end.new_nullifiers = array_to_bounded_vec(start.new_nullifiers);
-
-    circuit_outputs.end.private_call_stack = array_to_bounded_vec(start.private_call_stack);
-    circuit_outputs.end.public_call_stack = array_to_bounded_vec(start.public_call_stack);
-    circuit_outputs.end.new_l2_to_l1_msgs = array_to_bounded_vec(start.new_l2_to_l1_msgs);
-
-    circuit_outputs.end.public_data_update_requests = BoundedVec::new(PublicDataUpdateRequest::empty());
-    circuit_outputs.end.public_data_reads = BoundedVec::new(PublicDataRead::empty());
-
-    // Public kernel does not modify encrypted logs values --> we just copy them to output
-    circuit_outputs.end.encrypted_logs_hash = start.encrypted_logs_hash;
-    circuit_outputs.end.encrypted_log_preimages_length = start.encrypted_log_preimages_length;
-
-    circuit_outputs.end.new_contracts = array_to_bounded_vec(previous_kernel.public_inputs.end.new_contracts);
-}
-
-pub fn initialize_end_values_from_public_kernel_data(
+pub fn initialize_end_values(
     previous_kernel: PublicKernelData,
     circuit_outputs: &mut PublicKernelCircuitPublicInputsBuilder
 ) {

yarn-project/noir-protocol-circuits/src/crates/public-kernel-lib/src/public_kernel_app_logic.nr

@@ -25,7 +25,7 @@ impl PublicKernelAppLogicCircuitPrivateInputs {
         let mut public_inputs: PublicKernelCircuitPublicInputsBuilder = unsafe::zeroed();
 
         // initialise the end state with our provided previous kernel state
-        common::initialize_end_values_from_public_kernel_data(self.previous_kernel, &mut public_inputs);
+        common::initialize_end_values(self.previous_kernel, &mut public_inputs);
 
         // validate the inputs common to all invocation circumstances
         common::validate_inputs(self.public_call);

yarn-project/noir-protocol-circuits/src/crates/public-kernel-lib/src/public_kernel_setup.nr

@@ -43,7 +43,7 @@ impl PublicKernelSetupCircuitPrivateInputs {
         let mut public_inputs: PublicKernelCircuitPublicInputsBuilder = unsafe::zeroed();
 
         // initialise the end state with our provided previous kernel state
-        common::initialize_end_values_from_public_kernel_data(self.previous_kernel, &mut public_inputs);
+        common::initialize_end_values(self.previous_kernel, &mut public_inputs);
 
         // validate the inputs common to all invocation circumstances
         common::validate_inputs(self.public_call);

yarn-project/noir-protocol-circuits/src/index.ts

@@ -112,7 +112,7 @@ const getSolver = (): Promise<WasmBlackBoxFunctionSolver> => {
 
 /**
  * Executes the inner private kernel.
- * @param privateKernelInitCircuitPrivateInputs - The private inputs to the inner private kernel.
+ * @param privateKernelInnerCircuitPrivateInputs - The private inputs to the inner private kernel.
  * @returns The public inputs.
  */
 export async function executeInner(
@@ -129,7 +129,7 @@ export async function executeInner(
 
 /**
  * Executes the tail private kernel.
- * @param privateKernelInputsTail - The private inputs to the tail private kernel.
+ * @param privateKernelInnerCircuitPrivateInputs - The private inputs to the tail private kernel.
  * @returns The public inputs.
  */
 export async function executeTail(
@@ -145,8 +145,8 @@ export async function executeTail(
 }
 
 /**
- * Executes the public kernel.
- * @param privateKernelInputsInit - The public kernel private inputs.
+ * Executes the public kernel in the setup phase.
+ * @param publicKernelPrivateInputs - The public kernel setup circuit private inputs.
  * @returns The public inputs.
  */
 export async function executePublicKernelSetup(
@@ -162,8 +162,8 @@ export async function executePublicKernelSetup(
 }
 
 /**
- * Executes the inner public kernel.
- * @param privateKernelInputsInit - The public kernel private inputs.
+ * Executes the public kernel in the app logic phase.
+ * @param publicKernelPrivateInputs - The public kernel app logic circuit private inputs.
  * @returns The public inputs.
  */
 export async function executePublicKernelAppLogic(
@@ -173,7 +173,7 @@ export async function executePublicKernelAppLogic(
     input: mapPublicKernelCircuitPrivateInputsToNoir(publicKernelPrivateInputs),
   };
 
-  const returnType = await executePublicKernelPublicPreviousWithACVM(params);
+  const returnType = await executePublicKernelAppLogicWithACVM(params);
 
   return mapPublicKernelCircuitPublicInputsFromNoir(returnType);
 }
@@ -333,7 +333,7 @@ async function executePublicKernelSetupWithACVM(input: PublicSetupInputType): Pr
 /**
  * Executes the ordering private kernel with the given inputs using the acvm.
  */
-async function executePublicKernelPublicPreviousWithACVM(
+async function executePublicKernelAppLogicWithACVM(
   input: PublicPublicPreviousInputType,
 ): Promise<PublicPublicPreviousReturnType> {
   const initialWitnessMap = abiEncode(PublicKernelPublicPreviousSimulatedJson.abi as Abi, input as any);