refactor!: historical block -> anchor block (#17066)

Fixes #16026

Author: nventuro

docs/docs/developers/guides/smart_contracts/how_to_define_storage.md

@@ -415,7 +415,7 @@ While `DelayedPublicMutable` state variables are much less leaky than the assert
 
 ### Choosing Delays
 
-The `include_by_timestamp` transaction property will be set to a value close to the current timestamp plus the duration of the delay in seconds. The exact value depends on the historical block over which the private proof is constructed. For example, if current timestamp is `X` and a `DelayedPublicMutable` state variable has a delay of 3000 seconds, then transactions that read this value privately will set `include_by_timestamp` to a value close to 'X + 3000' (clients building proofs on older state will select a lower `include_by_timestamp`).
+The `include_by_timestamp` transaction property will be set to a value close to the current timestamp plus the duration of the delay in seconds. The exact value depends on the anchor block over which the private proof is constructed. For example, if current timestamp is `X` and a `DelayedPublicMutable` state variable has a delay of 3000 seconds, then transactions that read this value privately will set `include_by_timestamp` to a value close to 'X + 3000' (clients building proofs on older state will select a lower `include_by_timestamp`).
 
 These delays can be changed during the contract lifetime as the application's needs evolve.
 

docs/docs/migration_notes.md

@@ -49,6 +49,16 @@ As we prepare for a bigger `Wallet` interface refactor and the upcoming `WalletS
 
 ## [Aztec.nr]
 
+### Historical block renamed as anchor block
+
+A historical block term has been used as a term that denotes the block against which a private part of a tx has been executed.
+This name is ambiguous and for this reason we've introduce "anchor block".
+This naming change resulted in quite a few changes and if you've access private context's or utility context's block header you will need to update your code:
+
+```diff
+- let header = context.get_block_header();
++ let header = context.get_anchor_block_header();
+```diff
 
 ### PrivateMutable: replace / initialize_or_replace behaviour change
 

docs/docs/protocol-specs/gas-and-fees/kernel-tracking.md

@@ -41,7 +41,7 @@ class PrivateCircuitPublicInputs {
   +bool is_fee_payer
   +u32 min_revertible_side_effect_counter
   +Field public_teardown_function_hash
-  +Header historical_header
+  +Header anchor_block_header
 }
 PrivateCircuitPublicInputs --> TxContext
 PrivateCircuitPublicInputs --> Header
@@ -69,7 +69,7 @@ class PrivateAccumulatedData {
 }
 
 class CombinedConstantData {
-    +Header historical_header
+    +Header anchor_block_header
     +TxContext tx_context
     +GlobalVariables global_variables
 }
@@ -163,7 +163,7 @@ It must:
 
 - check that the `TxContext` provided as in the `TxRequest` input matches the `TxContext` in the `PrivateCallData`
 - copy the `TxContext` from the `TxRequest` to the `PrivateKernelCircuitPublicInputs.constants.tx_context`
-- copy the `Header` from the `PrivateCircuitPublicInputs` to the `PrivateKernelCircuitPublicInputs.constants.historical_header`
+- copy the `Header` from the `PrivateCircuitPublicInputs` to the `PrivateKernelCircuitPublicInputs.constants.anchor_block_header`
 - set the min_revertible_side_effect_counter if it is present in the `PrivateCallData`
 - set the `fee_payer` if the `is_fee_payer` flag is set in the `PrivateCircuitPublicInputs`
 - set the `public_teardown_function_hash` if it is present in the `PrivateCircuitPublicInputs`
@@ -304,7 +304,7 @@ PublicKernelCircuitPublicInputs --> PublicAccumulatedData
 PublicKernelCircuitPublicInputs --> CombinedConstantData
 
 class CombinedConstantData {
-    +Header historical_header
+    +Header anchor_block_header
     +TxContext tx_context
     +GlobalVariables global_variables
 }
@@ -387,7 +387,7 @@ class CombinedAccumulatedData {
 CombinedAccumulatedData --> Gas
 
 class PublicContextInputs {
-    +Header historical_header
+    +Header anchor_block_header
     +GlobalVariables public_global_variables
     +Gas gas_left
     +Field transaction_fee

docs/docs/protocol-specs/rollup-circuits/base-rollup.md

@@ -157,11 +157,11 @@ class TxContext {
 TxContext *-- GasSettings : gas_settings
 
 class CombinedConstantData {
-    historical_header: Header
+    anchor_block_header: Header
     tx_context: TxContext
     global_variables: GlobalVariables
 }
-CombinedConstantData *-- Header : historical_header
+CombinedConstantData *-- Header : anchor_block_header
 CombinedConstantData *-- TxContext : tx_context
 CombinedConstantData *-- GlobalVariables : global_variables
 
@@ -204,7 +204,7 @@ class StateDiffHints {
 }
 
 class BaseRollupInputs {
-  historical_header_membership_witnesses: HeaderMembershipWitness
+  anchor_block_header_membership_witnesses: HeaderMembershipWitness
   kernel_data: KernelData
   partial: PartialStateReference
   state_diff_hints: StateDiffHints
@@ -237,7 +237,7 @@ Fee structs and contract deployment structs will need to be revised, in line wit
 ```python
 def BaseRollupCircuit(
   state_diff_hints: StateDiffHints,
-  historical_header_membership_witnesses: HeaderMembershipWitness,
+  anchor_block_header_membership_witnesses: HeaderMembershipWitness,
   kernel_data: KernelData,
   partial: PartialStateReference,
   constants: ConstantRollupData,
@@ -248,7 +248,7 @@ def BaseRollupCircuit(
     kernel_data,
     constants,
     public_data_tree_root,
-    historical_header_membership_witnesses,
+    anchor_block_header_membership_witnesses,
   )
 
   note_hash_subtree = MerkleTree(kernel_data.public_inputs.end.note_hashes)
@@ -304,7 +304,7 @@ def kernel_checks(
   kernel: KernelData,
   constants: ConstantRollupData,
   public_data_tree_root: Fr,
-  historical_header_membership_witness: HeaderMembershipWitness
+  anchor_block_header_membership_witness: HeaderMembershipWitness
 ) -> (Fr[2], Fr[], Fr):
   assert public_data_tree_root == kernel.public_inputs.end.start_public_data_root
   assert kernel.proof.verify(kernel.public_inputs)
@@ -317,9 +317,9 @@ def kernel_checks(
   assert len(kernel.public_inputs.end.public_call_stack) == 0
 
   assert merkle_inclusion(
-    kernel.constants.historical_header.hash(),
-    kernel.constants.historical_header.global_variables.block_number,
-    historical_header_membership_witness,
+    kernel.constants.anchor_block_header.hash(),
+    kernel.constants.anchor_block_header.global_variables.block_number,
+    anchor_block_header_membership_witness,
     constants.last_archive
   )
 

docs/docs/protocol-specs/rollup-circuits/index.md

@@ -281,11 +281,11 @@ class TxContext {
 TxContext *-- GasSettings : gas_settings
 
 class CombinedConstantData {
-    historical_header: Header
+    anchor_block_header: Header
     tx_context: TxContext
     global_variables: GlobalVariables
 }
-CombinedConstantData *-- Header : historical_header
+CombinedConstantData *-- Header : anchor_block_header
 CombinedConstantData *-- TxContext : tx_context
 CombinedConstantData *-- GlobalVariables : global_variables
 
@@ -327,7 +327,7 @@ class StateDiffHints {
 }
 
 class BaseRollupInputs {
-  historical_header_membership_witnesses: HeaderMembershipWitness
+  anchor_block_header_membership_witnesses: HeaderMembershipWitness
   kernel_data: KernelData
   partial: PartialStateReference
   state_diff_hints: StateDiffHints

docs/docs/protocol-specs/transactions/validity.md

@@ -13,7 +13,7 @@ Mike review: If we have written definitions for the various kinds of "`data`" de
 - **Proof is valid**: The `proof` for the given public `data` should be valid according to a protocol-wide verification key for the final private kernel circuit.
 - **No duplicate nullifiers**: No `nullifier` in the transaction `data` should be already present in the nullifier tree.
 - **No pending private function calls**: The `data` private call stack should be empty.
-- **Valid historic data**: The tree roots in the block header of `data` must match the tree roots of a historical block in the chain.
+- **Valid anchor data**: The tree roots in the block header of `data` must match the tree roots of an anchor block in the chain.
 - **Maximum block number not exceeded**: The transaction must be included in a block with height no greater than the value specified in `maxBlockNum` within the transaction's `data`.
 - **Preimages must match commitments in `data`**: The expanded fields in the transaction object should match the commitments (hashes) to them in the public `data`.
   - The `encryptedLogs` should match the `encryptedLogsHash` and `encryptedLogPreimagesLength` in the transaction `data`.

noir-projects/aztec-nr/aztec/src/context/inputs/private_context_inputs.nr

@@ -10,7 +10,7 @@ use protocol_types::{
 #[derive(Eq)]
 pub struct PrivateContextInputs {
     pub call_context: CallContext,
-    pub historical_header: BlockHeader,
+    pub anchor_block_header: BlockHeader,
     pub tx_context: TxContext,
     pub start_side_effect_counter: u32,
 }
@@ -20,7 +20,7 @@ impl Empty for PrivateContextInputs {
     fn empty() -> Self {
         PrivateContextInputs {
             call_context: CallContext::empty(),
-            historical_header: BlockHeader::empty(),
+            anchor_block_header: BlockHeader::empty(),
             tx_context: TxContext::empty(),
             start_side_effect_counter: 0 as u32,
         }

noir-projects/aztec-nr/aztec/src/context/private_context.nr

@@ -193,7 +193,7 @@ pub struct PrivateContext {
     // docs:end:private-context
 
     // Header of a block whose state is used during private execution (not the block the transaction is included in).
-    pub historical_header: BlockHeader,
+    pub anchor_block_header: BlockHeader,
 
     pub private_logs: BoundedVec<PrivateLogData, MAX_PRIVATE_LOGS_PER_CALL>,
     pub contract_class_logs_hashes: BoundedVec<Counted<LogHash>, MAX_CONTRACT_CLASS_LOGS_PER_CALL>,
@@ -206,8 +206,8 @@ pub struct PrivateContext {
 
 impl PrivateContext {
     pub fn new(inputs: PrivateContextInputs, args_hash: Field) -> PrivateContext {
-        let max_allowed_include_by_timestamp =
-            inputs.historical_header.global_variables.timestamp + MAX_INCLUDE_BY_TIMESTAMP_DURATION;
+        let max_allowed_include_by_timestamp = inputs.anchor_block_header.global_variables.timestamp
+            + MAX_INCLUDE_BY_TIMESTAMP_DURATION;
         PrivateContext {
             inputs,
             side_effect_counter: inputs.start_side_effect_counter + 1,
@@ -221,7 +221,7 @@ impl PrivateContext {
             key_validation_requests_and_generators: BoundedVec::new(),
             note_hashes: BoundedVec::new(),
             nullifiers: BoundedVec::new(),
-            historical_header: inputs.historical_header,
+            anchor_block_header: inputs.anchor_block_header,
             private_call_requests: BoundedVec::new(),
             public_call_requests: BoundedVec::new(),
             public_teardown_call_request: PublicCallRequest::empty(),
@@ -489,7 +489,7 @@ impl PrivateContext {
     /// private function is reading from.
     ///
     /// A private function CANNOT read from the "current" block header,
-    /// but must read from some historical block header, because as soon as
+    /// but must read from some older block header, because as soon as
     /// private function execution begins (asynchronously, on a user's device),
     /// the public state of the chain (the "current state") will have progressed
     /// forward.
@@ -505,8 +505,8 @@ impl PrivateContext {
     ///   from the mempool. Therefore, the chosen block header _must_ be one
     ///   from within the last 24 hours.
     ///
-    pub fn get_block_header(self) -> BlockHeader {
-        self.historical_header
+    pub fn get_anchor_block_header(self) -> BlockHeader {
+        self.anchor_block_header
     }
 
     /// Returns the header of any historical block at or before the anchor
@@ -600,7 +600,7 @@ impl PrivateContext {
             contract_class_logs_hashes: ClaimedLengthArray::from_bounded_vec(
                 self.contract_class_logs_hashes,
             ),
-            historical_header: self.historical_header,
+            anchor_block_header: self.anchor_block_header,
             tx_context: self.inputs.tx_context,
         }
     }
@@ -993,7 +993,7 @@ impl PrivateContext {
     ) {
         // docs:end:context_consume_l1_to_l2_message
         let nullifier = process_l1_to_l2_message(
-            self.historical_header.state.l1_to_l2_message_tree.root,
+            self.anchor_block_header.state.l1_to_l2_message_tree.root,
             self.this_address(),
             sender,
             self.chain_id(),
@@ -1698,7 +1698,7 @@ impl Empty for PrivateContext {
             public_call_requests: BoundedVec::new(),
             public_teardown_call_request: PublicCallRequest::empty(),
             l2_to_l1_msgs: BoundedVec::new(),
-            historical_header: BlockHeader::empty(),
+            anchor_block_header: BlockHeader::empty(),
             private_logs: BoundedVec::new(),
             contract_class_logs_hashes: BoundedVec::new(),
             last_key_validation_requests: [Option::none(); NUM_KEY_TYPES],

noir-projects/aztec-nr/aztec/src/history/note_inclusion/test.nr

@@ -7,10 +7,10 @@ unconstrained fn succeeds_on_blocks_after_note_creation() {
     let (env, retrieved_note) = test::create_note();
 
     env.private_context_opts(
-        PrivateContextOptions::new().at_historical_block_number(test::NOTE_CREATED_AT),
+        PrivateContextOptions::new().at_anchor_block_number(test::NOTE_CREATED_AT),
         |context| {
             // docs:start:prove_note_inclusion
-            let header = context.historical_header;
+            let header = context.anchor_block_header;
             header.prove_note_inclusion(retrieved_note, test::NOTE_STORAGE_SLOT);
             // docs:end:prove_note_inclusion
         },
@@ -22,9 +22,9 @@ unconstrained fn fails_on_blocks_before_note_creation() {
     let (env, retrieved_note) = test::create_note();
 
     env.private_context_opts(
-        PrivateContextOptions::new().at_historical_block_number(test::NOTE_CREATED_AT - 1),
+        PrivateContextOptions::new().at_anchor_block_number(test::NOTE_CREATED_AT - 1),
         |context| {
-            let header = context.historical_header;
+            let header = context.anchor_block_header;
             header.prove_note_inclusion(retrieved_note, test::NOTE_STORAGE_SLOT);
         },
     );

noir-projects/aztec-nr/aztec/src/history/note_validity/test.nr

@@ -8,9 +8,9 @@ unconstrained fn fails_on_blocks_before_note_creation() {
     let (env, retrieved_note) = test::create_note_and_nullify_it();
 
     env.private_context_opts(
-        PrivateContextOptions::new().at_historical_block_number(test::NOTE_CREATED_AT - 1),
+        PrivateContextOptions::new().at_anchor_block_number(test::NOTE_CREATED_AT - 1),
         |context| {
-            let header = context.historical_header;
+            let header = context.anchor_block_header;
             header.prove_note_validity(retrieved_note, test::NOTE_STORAGE_SLOT, context);
         },
     );
@@ -21,10 +21,10 @@ unconstrained fn succeeds_on_blocks_after_creation_and_before_nullification() {
     let (env, retrieved_note) = test::create_note_and_nullify_it();
 
     env.private_context_opts(
-        PrivateContextOptions::new().at_historical_block_number(test::NOTE_CREATED_AT),
+        PrivateContextOptions::new().at_anchor_block_number(test::NOTE_CREATED_AT),
         |context| {
             // docs:start:prove_note_validity
-            let header = context.historical_header;
+            let header = context.anchor_block_header;
             header.prove_note_validity(retrieved_note, test::NOTE_STORAGE_SLOT, context);
             // docs:end:prove_note_validity
         },
@@ -36,9 +36,9 @@ unconstrained fn fails_on_blocks_after_note_nullification() {
     let (env, retrieved_note) = test::create_note_and_nullify_it();
 
     env.private_context_opts(
-        PrivateContextOptions::new().at_historical_block_number(test::NOTE_NULLIFIED_AT),
+        PrivateContextOptions::new().at_anchor_block_number(test::NOTE_NULLIFIED_AT),
         |context| {
-            let header = context.historical_header;
+            let header = context.anchor_block_header;
             header.prove_note_validity(retrieved_note, test::NOTE_STORAGE_SLOT, context);
         },
     );