chore: cleanup + various doc improvements (#4282)

Fixes #4264

docs/docs/developers/contracts/syntax/context.mdx

@@ -75,7 +75,7 @@ The call context contains information about the current call being made:
 
 Another structure that is contained within the context is the Header object.
 In the private context this is a header of a block which used to generate proofs against.
-In the public context this TBD TODO(#4262)
+In the public context this header is set by sequencer (sequencer executes public calls) and it is set to 1 block before the block in which the transaction is included.
 
 #include_code header /yarn-project/noir-protocol-circuits/src/crates/types/src/header.nr rust
 

yarn-project/acir-simulator/src/client/client_execution_context.ts

@@ -64,7 +64,7 @@ export class ClientExecutionContext extends ViewDataOracle {
     private readonly argsHash: Fr,
     private readonly txContext: TxContext,
     private readonly callContext: CallContext,
-    /** Header of a block whose state is used during private execution. */
+    /** Header of a block whose state is used during private execution (not the block the transaction is included in). */
     protected readonly historicalHeader: Header,
     /** List of transient auth witnesses to be used during this simulation */
     protected readonly authWitnesses: AuthWitness[],
@@ -74,7 +74,7 @@ export class ClientExecutionContext extends ViewDataOracle {
     private readonly curve: Grumpkin,
     protected log = createDebugLogger('aztec:simulator:client_execution_context'),
   ) {
-    super(contractAddress, historicalHeader, authWitnesses, db, undefined, log);
+    super(contractAddress, authWitnesses, db, undefined, log);
   }
 
   // We still need this function until we can get user-defined ordering of structs for fn arguments

yarn-project/acir-simulator/src/client/simulator.ts

@@ -139,8 +139,7 @@ export class AcirSimulator {
       throw new Error(`Cannot run ${entryPointArtifact.functionType} function as constrained`);
     }
 
-    const header = await this.db.getHeader();
-    const context = new ViewDataOracle(contractAddress, header, [], this.db, aztecNode);
+    const context = new ViewDataOracle(contractAddress, [], this.db, aztecNode);
 
     try {
       return await executeUnconstrainedFunction(

yarn-project/acir-simulator/src/client/view_data_oracle.ts

@@ -24,8 +24,6 @@ import { pickNotes } from './pick_notes.js';
 export class ViewDataOracle extends TypedOracle {
   constructor(
     protected readonly contractAddress: AztecAddress,
-    /** Data required to reconstruct the block hash, it contains historical roots. */
-    protected readonly historicalHeader: Header,
     /** List of transient auth witnesses to be used during this simulation */
     protected readonly authWitnesses: AuthWitness[],
     protected readonly db: DBOracle,

yarn-project/aztec-nr/aztec/src/context.nr

@@ -86,6 +86,7 @@ struct PrivateContext {
     new_l2_to_l1_msgs : BoundedVec<Field, MAX_NEW_L2_TO_L1_MSGS_PER_CALL>,
     // docs:end:private-context
 
+    // Header of a block whose state is used during private execution (not the block the transaction is included in).
     historical_header: Header,
 
     // TODO(https://github.com/AztecProtocol/aztec-packages/issues/1165)
@@ -148,11 +149,14 @@ impl PrivateContext {
         self.inputs.call_context.function_selector
     }
 
-    // Returns the header of a block whose state is used during private execution
+    // Returns the header of a block whose state is used during private execution (not the block the transaction is
+    // included in).
     pub fn get_header(self) -> Header {
         self.historical_header
     }
 
+    // Returns the header of an arbitrary block whose block number is less than or equal to the block number
+    // of historical header.
     pub fn get_header_at(self, block_number: u32) -> Header {
         get_header_at(block_number, self)
     }
@@ -494,6 +498,8 @@ struct PublicContext {
     unencrypted_logs_hash: BoundedVec<Field, NUM_FIELDS_PER_SHA256>,
     unencrypted_logs_preimages_length: Field,
 
+    // Header of a block whose state is used during public execution. Set by sequencer to be a header of a block
+    // previous to the one in which the tx is included.
     historical_header: Header,
     prover_address: AztecAddress,
 }

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

@@ -9,17 +9,22 @@ import { TxContext } from '../tx_context.js';
 export class CombinedConstantData {
   constructor(
     /**
-     * Roots of the trees relevant for both kernel circuits.
+     * Header of a block whose state is used during execution (not the block the transaction is included in).
      */
-    public header: Header,
+    public historicalHeader: Header,
     /**
      * Context of the transaction.
+     *
+     * Note: `chainId` and `version` in txContext are not redundant to the values in
+     * self.historical_header.global_variables because they can be different in case of a protocol upgrade. In such
+     * a situation we could be using header from a block before the upgrade took place but be using the updated
+     * protocol to execute and prove the transaction.
      */
     public txContext: TxContext,
   ) {}
 
   toBuffer() {
-    return serializeToBuffer(this.header, this.txContext);
+    return serializeToBuffer(this.historicalHeader, this.txContext);
   }
 
   /**

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

@@ -94,7 +94,7 @@ export class PrivateCircuitPublicInputs {
      */
     public unencryptedLogPreimagesLength: Fr,
     /**
-     * L2 block header.
+     * Header of a block whose state is used during private execution (not the block the transaction is included in).
      */
     public historicalHeader: Header,
     /**
@@ -103,6 +103,10 @@ export class PrivateCircuitPublicInputs {
     public contractDeploymentData: ContractDeploymentData,
     /**
      * Chain Id of the instance.
+     *
+     * Note: The following 2 values are not redundant to the values in self.historical_header.global_variables because
+     * they can be different in case of a protocol upgrade. In such a situation we could be using header from a block
+     * before the upgrade took place but be using the updated protocol to execute and prove the transaction.
      */
     public chainId: Fr,
     /**

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

@@ -198,7 +198,8 @@ export class PublicCircuitPublicInputs {
      */
     public unencryptedLogPreimagesLength: Fr,
     /**
-     * L2 block header of the block preceding the block in which this tx is included.
+     * Header of a block whose state is used during public execution. Set by sequencer to be a header of a block
+     * previous to the one in which the tx is included.
      */
     public historicalHeader: Header,
     /**

yarn-project/end-to-end/src/integration_l1_publisher.test.ts

@@ -163,7 +163,7 @@ describe('L1Publisher integration', () => {
     const kernelOutput = KernelCircuitPublicInputs.empty();
     kernelOutput.constants.txContext.chainId = fr(chainId);
     kernelOutput.constants.txContext.version = fr(config.version);
-    kernelOutput.constants.header = prevHeader;
+    kernelOutput.constants.historicalHeader = prevHeader;
     kernelOutput.end.publicDataUpdateRequests = makeTuple(
       MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
       i => new PublicDataUpdateRequest(fr(i), fr(0), fr(i + 10)),

yarn-project/noir-protocol-circuits/src/__snapshots__/index.test.ts.snap

@@ -103,7 +103,7 @@ exports[`Noir compatibility tests (interop_testing.nr) TxRequest Hash matches No
 exports[`Private kernel Executes private kernel init circuit for a contract deployment 1`] = `
 KernelCircuitPublicInputs {
   "constants": CombinedConstantData {
-    "header": Header {
+    "historicalHeader": Header {
       "bodyHash": {
         "data": [
           0,
@@ -33274,7 +33274,7 @@ KernelCircuitPublicInputs {
 exports[`Private kernel Executes private kernel inner for a nested call 1`] = `
 KernelCircuitPublicInputs {
   "constants": CombinedConstantData {
-    "header": Header {
+    "historicalHeader": Header {
       "bodyHash": {
         "data": [
           210,
@@ -66445,7 +66445,7 @@ KernelCircuitPublicInputs {
 exports[`Private kernel Executes private kernel ordering after a deployment 1`] = `
 KernelCircuitPublicInputsFinal {
   "constants": CombinedConstantData {
-    "header": Header {
+    "historicalHeader": Header {
       "bodyHash": {
         "data": [
           0,

yarn-project/noir-protocol-circuits/src/crates/private-kernel-lib/src/private_kernel_init.nr

@@ -21,7 +21,7 @@ struct PrivateKernelInputsInit {
 impl PrivateKernelInputsInit {
     fn initialize_end_values(self, public_inputs: &mut KernelCircuitPublicInputsBuilder) {
         public_inputs.constants = CombinedConstantData {
-            header: self.private_call.call_stack_item.public_inputs.historical_header,
+            historical_header: self.private_call.call_stack_item.public_inputs.historical_header,
             tx_context: self.tx_request.tx_context,
         };
     }
@@ -91,7 +91,7 @@ impl PrivateKernelInputsInit {
         self.validate_this_private_call_against_tx_request();
 
         common::validate_read_requests(
-            public_inputs.constants.header.state.partial.note_hash_tree.root,
+            public_inputs.constants.historical_header.state.partial.note_hash_tree.root,
             self.private_call.call_stack_item.public_inputs.read_requests,
             self.private_call.read_request_membership_witnesses
         );

yarn-project/noir-protocol-circuits/src/crates/private-kernel-lib/src/private_kernel_inner.nr

@@ -23,7 +23,7 @@ impl PrivateKernelInputsInner {
 
     fn validate_contract_tree_root(self) {
         let purported_contract_tree_root = self.private_call.call_stack_item.public_inputs.historical_header.state.partial.contract_tree.root;
-        let previous_kernel_contract_tree_root = self.previous_kernel.public_inputs.constants.header.state.partial.contract_tree.root;
+        let previous_kernel_contract_tree_root = self.previous_kernel.public_inputs.constants.historical_header.state.partial.contract_tree.root;
 
         assert(purported_contract_tree_root == previous_kernel_contract_tree_root, "purported_contract_tree_root does not match previous_kernel_contract_tree_root");
     }
@@ -52,7 +52,7 @@ impl PrivateKernelInputsInner {
         self.pop_and_validate_this_private_call_hash(&mut public_inputs);
 
         common::validate_read_requests(
-            public_inputs.constants.header.state.partial.note_hash_tree.root,
+            public_inputs.constants.historical_header.state.partial.note_hash_tree.root,
             self.private_call.call_stack_item.public_inputs.read_requests,  // read requests from private call
             self.private_call.read_request_membership_witnesses);
 
@@ -170,9 +170,9 @@ mod tests {
     fn private_function_incorrect_contract_tree_root_fails() {
         let mut builder = PrivateKernelInnerInputsBuilder::new();
 
-        // Set historical_tree_root to a wrong value (the correct value + 1).
-        let contract_tree_root = builder.previous_kernel.header.state.partial.contract_tree.root;
-        builder.previous_kernel.header.state.partial.contract_tree.root = contract_tree_root + 1;
+        // Set historical contract tree root to a wrong value (the correct value + 1).
+        let contract_tree_root = builder.previous_kernel.historical_header.state.partial.contract_tree.root;
+        builder.previous_kernel.historical_header.state.partial.contract_tree.root = contract_tree_root + 1;
 
         builder.failed();
     }
@@ -610,8 +610,8 @@ mod tests {
         builder.private_call.append_read_requests(1);
 
         // Set the root to be a different root so the above read request is not under this root.
-        let old_root = builder.previous_kernel.header.state.partial.note_hash_tree.root;
-        builder.previous_kernel.header.state.partial.note_hash_tree.root = old_root + 1;
+        let old_root = builder.previous_kernel.historical_header.state.partial.note_hash_tree.root;
+        builder.previous_kernel.historical_header.state.partial.note_hash_tree.root = old_root + 1;
 
         builder.failed();
     }

yarn-project/noir-protocol-circuits/src/crates/rollup-lib/src/base/base_rollup_inputs.nr

@@ -338,7 +338,7 @@ impl BaseRollupInputs {
         let archive_root = self.constants.last_archive.root;
 
         // Rebuild the block hash
-        let header = self.kernel_data.public_inputs.constants.header;
+        let header = self.kernel_data.public_inputs.constants.historical_header;
         let previous_block_hash = header.block_hash();
 
         let previous_block_hash_witness = self.archive_root_membership_witness;
@@ -738,7 +738,7 @@ mod tests {
             let _nullifier = builder.end.new_nullifiers.pop();
             inputs.kernel_data = builder.is_public();
 
-            inputs.pre_existing_blocks[0] = inputs.kernel_data.header.block_hash();
+            inputs.pre_existing_blocks[0] = inputs.kernel_data.historical_header.block_hash();
 
             inputs
         }

yarn-project/noir-protocol-circuits/src/crates/types/src/abis/combined_constant_data.nr

@@ -2,6 +2,10 @@ use crate::transaction::context::TxContext;
 use crate::header::Header;
 
 struct CombinedConstantData {
-    header: Header,
+    historical_header: Header,
+    // Note: `chainId` and `version` in txContext are not redundant to the values in
+    // self.historical_header.global_variables because they can be different in case of a protocol upgrade. In such
+    // a situation we could be using header from a block before the upgrade took place but be using the updated
+    // protocol to execute and prove the transaction.
     tx_context: TxContext,
 }

yarn-project/noir-protocol-circuits/src/crates/types/src/abis/private_circuit_public_inputs.nr

@@ -51,11 +51,14 @@ struct PrivateCircuitPublicInputs {
     encrypted_log_preimages_length: Field,
     unencrypted_log_preimages_length: Field,
 
-    // Header of the block the transaction is executing against (not the block the transaction is included in).
+    // Header of a block whose state is used during private execution (not the block the transaction is included in).
     historical_header: Header,
 
     contract_deployment_data: ContractDeploymentData,
 
+    // Note: The following 2 values are not redundant to the values in self.historical_header.global_variables because
+    // they can be different in case of a protocol upgrade. In such a situation we could be using header from a block
+    // before the upgrade took place but be using the updated protocol to execute and prove the transaction.
     chain_id: Field,
     version: Field,
 }

yarn-project/noir-protocol-circuits/src/crates/types/src/abis/public_circuit_public_inputs.nr

@@ -46,6 +46,8 @@ struct PublicCircuitPublicInputs{
     // variable-length data.
     unencrypted_log_preimages_length: Field,
 
+    // Header of a block whose state is used during public execution. Set by sequencer to be a header of a block
+    // previous to the one in which the tx is included.
     historical_header: Header,
 
     prover_address: AztecAddress,

yarn-project/noir-protocol-circuits/src/crates/types/src/tests/previous_kernel_data_builder.nr

@@ -32,7 +32,7 @@ struct PreviousKernelDataBuilder {
     contract_address: AztecAddress,
     portal_contract_address: EthAddress,
     end: CombinedAccumulatedDataBuilder,
-    header: Header,
+    historical_header: Header,
     tx_context: TxContext,
     is_private: bool,
     proof: Proof,
@@ -57,7 +57,7 @@ impl PreviousKernelDataBuilder {
             contract_address: fixtures::contracts::parent_contract.address,
             portal_contract_address: fixtures::contracts::parent_contract.portal_contract_address,
             end,
-            header: fixtures::HEADER,
+            historical_header: fixtures::HEADER,
             tx_context,
             is_private: true,
             proof: Proof {},
@@ -197,7 +197,7 @@ impl PreviousKernelDataBuilder {
         let public_inputs = KernelCircuitPublicInputs {
             end: self.end.finish(),
             constants: CombinedConstantData {
-                header: self.header,
+                historical_header: self.historical_header,
                 tx_context: self.tx_context,
             },
             is_private: self.is_private,

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

@@ -994,7 +994,7 @@ export function mapCombinedAccumulatedDataToNoir(
  */
 export function mapCombinedConstantDataFromNoir(combinedConstantData: CombinedConstantDataNoir): CombinedConstantData {
   return new CombinedConstantData(
-    mapHeaderFromNoir(combinedConstantData.header),
+    mapHeaderFromNoir(combinedConstantData.historical_header),
     mapTxContextFromNoir(combinedConstantData.tx_context),
   );
 }
@@ -1006,7 +1006,7 @@ export function mapCombinedConstantDataFromNoir(combinedConstantData: CombinedCo
  */
 export function mapCombinedConstantDataToNoir(combinedConstantData: CombinedConstantData): CombinedConstantDataNoir {
   return {
-    header: mapHeaderToNoir(combinedConstantData.header),
+    historical_header: mapHeaderToNoir(combinedConstantData.historicalHeader),
     tx_context: mapTxContextToNoir(combinedConstantData.txContext),
   };
 }

yarn-project/sequencer-client/src/block_builder/solo_block_builder.test.ts

@@ -191,7 +191,7 @@ describe('sequencer/solo_block_builder', () => {
 
   const buildMockSimulatorInputs = async () => {
     const kernelOutput = makePrivateKernelPublicInputsFinal();
-    kernelOutput.constants.header = await buildInitialHeader(expectsDb);
+    kernelOutput.constants.historicalHeader = await buildInitialHeader(expectsDb);
 
     const tx = await makeProcessedTx(
       new Tx(
@@ -297,7 +297,7 @@ describe('sequencer/solo_block_builder', () => {
     const makeBloatedProcessedTx = async (seed = 0x1) => {
       const tx = mockTx(seed);
       const kernelOutput = KernelCircuitPublicInputs.empty();
-      kernelOutput.constants.header = await buildInitialHeader(builderDb);
+      kernelOutput.constants.historicalHeader = await buildInitialHeader(builderDb);
       kernelOutput.end.publicDataUpdateRequests = makeTuple(
         MAX_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
         i => new PublicDataUpdateRequest(fr(i), fr(0), fr(i + 10)),

yarn-project/sequencer-client/src/block_builder/solo_block_builder.ts

@@ -157,7 +157,7 @@ export class SoloBlockBuilder implements BlockBuilder {
 
   protected validateTxs(txs: ProcessedTx[]) {
     for (const tx of txs) {
-      const txHeader = tx.data.constants.header;
+      const txHeader = tx.data.constants.historicalHeader;
       if (txHeader.state.l1ToL2MessageTree.isEmpty()) {
         throw new Error(`Empty L1 to L2 messages tree in tx: ${toFriendlyJSON(tx)}`);
       }
@@ -492,7 +492,7 @@ export class SoloBlockBuilder implements BlockBuilder {
   }
 
   protected getHistoricalTreesMembershipWitnessFor(tx: ProcessedTx) {
-    const header = tx.data.constants.header;
+    const header = tx.data.constants.historicalHeader;
     // TODO(#3941)
     const blockHash = computeBlockHash(
       computeGlobalsHash(header.globalVariables),

yarn-project/sequencer-client/src/sequencer/processed_tx.ts

@@ -89,7 +89,7 @@ export async function makeProcessedTx(
  */
 export function makeEmptyProcessedTx(header: Header, chainId: Fr, version: Fr): Promise<ProcessedTx> {
   const emptyKernelOutput = PublicKernelPublicInputs.empty();
-  emptyKernelOutput.constants.header = header;
+  emptyKernelOutput.constants.historicalHeader = header;
   emptyKernelOutput.constants.txContext.chainId = chainId;
   emptyKernelOutput.constants.txContext.version = version;
   const emptyProof = makeEmptyProof();