feat: annotate fact origin block state (#24289)

Augments facts exposed from PXE to Aztec.nr with origin block state
(pending | proven | finalized), capped to the anchor block to avoid
"future leaking"

Closes F-715

Author: mverzilli

noir-projects/aztec-nr/aztec/src/facts/mod.nr

@@ -1,4 +1,4 @@
-//! Storage of immutable facts grouped into collections.
+//! Per-contract storage of immutable facts grouped into collections.
 //!
 //! A fact is a contract-defined, typed, immutable datum. Facts are grouped into collections identified by a
 //! `(collection type, collection id)` tuple.
@@ -11,13 +11,24 @@ use crate::oracle::fact_store::{
 };
 use crate::protocol::{address::AztecAddress, traits::{Deserialize, Serialize}};
 
+mod origin_state;
+pub use origin_state::OriginBlockState;
+
 /// The block a retractable fact originates from.
 #[derive(Deserialize, Eq, Serialize)]
 pub struct OriginBlock {
     pub block_number: u32,
     pub block_hash: Field,
 }
 
+/// A retractable fact's origin block.
+#[derive(Deserialize, Eq, Serialize)]
+pub struct RetractableFactOrigin {
+    pub block_number: u32,
+    pub block_hash: Field,
+    pub block_state: OriginBlockState,
+}
+
 /// A single immutable fact in a collection.
 #[derive(Deserialize, Serialize)]
 pub struct Fact {
@@ -27,7 +38,7 @@ pub struct Fact {
     /// The block the fact is associated to, if any. A fact with an origin block is said to be a 'retractable' fact,
     /// and will be automatically deleted if its origin block gets pruned in a reorg. Typically used by facts
     /// associated with a transaction (e.g. 'processed entry X using data from tx Y in block Z').
-    pub origin_block: Option<OriginBlock>,
+    pub origin_block: Option<RetractableFactOrigin>,
 }
 
 /// A fact collection as returned by the store.
@@ -219,8 +230,9 @@ mod test {
     }
 
     #[test]
-    unconstrained fn records_a_retractable_fact() {
+    unconstrained fn records_a_retractable_fact_finalized_at_latest_block() {
         let (env, scope) = setup();
+        let origin_block_number = env.last_block_number();
         env.private_context(|context| {
             let contract_address = context.this_address();
             record_retractable_fact(
@@ -230,7 +242,7 @@ mod test {
                 COLLECTION_ID,
                 FACT_TYPE_ID,
                 make_payload(PAYLOAD),
-                OriginBlock { block_number: 5, block_hash: 0xabc },
+                OriginBlock { block_number: origin_block_number, block_hash: 0xabc },
             );
 
             let collection = get_fact_collection(contract_address, scope, TYPE_ID, COLLECTION_ID).unwrap();
@@ -240,9 +252,37 @@ mod test {
             assert_eq(fact.fact_type_id, FACT_TYPE_ID);
             assert_payload(fact.payload);
 
-            let origin_block = fact.origin_block.unwrap();
-            assert_eq(origin_block.block_number, 5);
-            assert_eq(origin_block.block_hash, 0xabc);
+            let origin = fact.origin_block.unwrap();
+            assert_eq(origin.block_number, origin_block_number);
+            assert_eq(origin.block_hash, 0xabc);
+            // TXE finalizes every mined block, so an origin at the latest block is Finalized.
+            assert(origin.block_state.is_finalized());
+        });
+    }
+
+    #[test]
+    unconstrained fn retractable_fact_above_proven_tip_is_pending() {
+        let (env, scope) = setup();
+        let future_block_number = env.last_block_number() + 100;
+        env.private_context(|context| {
+            let contract_address = context.this_address();
+            record_retractable_fact(
+                contract_address,
+                scope,
+                TYPE_ID,
+                COLLECTION_ID,
+                FACT_TYPE_ID,
+                make_payload(PAYLOAD),
+                OriginBlock { block_number: future_block_number, block_hash: 0xabc },
+            );
+
+            let origin = get_fact_collection(contract_address, scope, TYPE_ID, COLLECTION_ID)
+                .unwrap()
+                .facts
+                .get(0)
+                .origin_block
+                .unwrap();
+            assert(origin.block_state.is_pending());
         });
     }
 

noir-projects/aztec-nr/aztec/src/facts/origin_state.nr

@@ -0,0 +1,102 @@
+use crate::protocol::{traits::{Deserialize, Serialize}, utils::reader::Reader};
+
+/// Chain state of a retractable fact's origin block, mirroring the L2 chain tips.
+#[derive(Serialize)]
+pub struct OriginBlockState {
+    // Noir has no enums, so this wraps a `u8` discriminant. The discriminant values must stay in sync with the
+    // TypeScript `OriginBlockState` enum in `yarn-project/pxe/src/storage/fact_store/origin_state.ts`, which PXE
+    // serializes into the `Fact` oracle response that `from_u8` below deserializes.
+    inner: u8,
+}
+
+impl OriginBlockState {
+    pub fn pending() -> Self {
+        Self { inner: 1 }
+    }
+
+    pub fn proven() -> Self {
+        Self { inner: 2 }
+    }
+
+    pub fn finalized() -> Self {
+        Self { inner: 3 }
+    }
+
+    /// Whether the origin block is still above the proven tip.
+    pub fn is_pending(self) -> bool {
+        self == Self::pending()
+    }
+
+    /// Whether the origin block is proven but not yet finalized.
+    pub fn is_proven(self) -> bool {
+        self == Self::proven()
+    }
+
+    /// Whether the origin block is finalized, and thus facts related to it can no longer be retracted.
+    pub fn is_finalized(self) -> bool {
+        self == Self::finalized()
+    }
+
+    fn from_u8(inner: u8) -> Self {
+        let state = Self { inner };
+        assert(state.is_valid(), "unrecognized origin state");
+        state
+    }
+
+    fn is_valid(self) -> bool {
+        self.is_pending() | self.is_proven() | self.is_finalized()
+    }
+}
+
+impl Eq for OriginBlockState {
+    fn eq(self, other: Self) -> bool {
+        self.inner == other.inner
+    }
+}
+
+impl Deserialize for OriginBlockState {
+    let N: u32 = <u8 as Deserialize>::N;
+
+    fn deserialize(fields: [Field; Self::N]) -> Self {
+        Self::from_u8(<u8 as Deserialize>::deserialize(fields))
+    }
+
+    fn stream_deserialize<let K: u32>(reader: &mut Reader<K>) -> Self {
+        Self::from_u8(reader.read() as u8)
+    }
+}
+
+mod test {
+    use crate::protocol::traits::{Deserialize, Serialize};
+    use super::OriginBlockState;
+
+    #[test]
+    fn query_functions_identify_each_state() {
+        assert(OriginBlockState::pending().is_pending());
+        assert(!OriginBlockState::pending().is_proven());
+        assert(!OriginBlockState::pending().is_finalized());
+
+        assert(OriginBlockState::proven().is_proven());
+        assert(!OriginBlockState::proven().is_pending());
+        assert(!OriginBlockState::proven().is_finalized());
+
+        assert(OriginBlockState::finalized().is_finalized());
+        assert(!OriginBlockState::finalized().is_pending());
+        assert(!OriginBlockState::finalized().is_proven());
+    }
+
+    #[test]
+    fn origin_state_roundtrips_through_serialization() {
+        let pending = OriginBlockState::pending();
+        let proven = OriginBlockState::proven();
+        let finalized = OriginBlockState::finalized();
+        assert(OriginBlockState::deserialize(pending.serialize()) == pending);
+        assert(OriginBlockState::deserialize(proven.serialize()) == proven);
+        assert(OriginBlockState::deserialize(finalized.serialize()) == finalized);
+    }
+
+    #[test(should_fail_with = "unrecognized origin state")]
+    fn deserializing_invalid_state_fails() {
+        let _ = OriginBlockState::deserialize([99]);
+    }
+}

noir-projects/contract-snapshots/tests/snapshots/expand/amm_contract/snapshots__expanded.snap

@@ -1145,7 +1145,7 @@ pub contract AMM {
             returns_hash.get_preimage()
         }
 
-        pub fn swap_tokens_for_exact_tokens(self, token_in: AztecAddress, token_out: AztecAddress, amount_out: u128, amount_in_max: u128, authwit_nonce: Field) {
+        pub fn swap_exact_tokens_for_tokens(self, token_in: AztecAddress, token_out: AztecAddress, amount_in: u128, amount_out_min: u128, authwit_nonce: Field) {
             let mut serialized_params: [Field; 5] = [0_Field; 5];
             let mut offset: u32 = 0_u32;
             let serialized_member: [Field; 1] = <AztecAddress as aztec::protocol::traits::Serialize>::serialize(token_in);
@@ -1160,13 +1160,13 @@ pub contract AMM {
                 serialized_params[i + offset] = serialized_member[i];
             };
             offset = offset + serialized_member_len;
-            let serialized_member: [Field; 1] = <u128 as aztec::protocol::traits::Serialize>::serialize(amount_out);
+            let serialized_member: [Field; 1] = <u128 as aztec::protocol::traits::Serialize>::serialize(amount_in);
             let serialized_member_len: u32 = <u128 as aztec::protocol::traits::Serialize>::N;
             for i in 0_u32..serialized_member_len {
                 serialized_params[i + offset] = serialized_member[i];
             };
             offset = offset + serialized_member_len;
-            let serialized_member: [Field; 1] = <u128 as aztec::protocol::traits::Serialize>::serialize(amount_in_max);
+            let serialized_member: [Field; 1] = <u128 as aztec::protocol::traits::Serialize>::serialize(amount_out_min);
             let serialized_member_len: u32 = <u128 as aztec::protocol::traits::Serialize>::N;
             for i in 0_u32..serialized_member_len {
                 serialized_params[i + offset] = serialized_member[i];
@@ -1178,14 +1178,14 @@ pub contract AMM {
                 serialized_params[i + offset] = serialized_member[i];
             };
             offset = offset + serialized_member_len;
-            let selector: aztec::protocol::abis::function_selector::FunctionSelector = <aztec::protocol::abis::function_selector::FunctionSelector as aztec::protocol::traits::FromField>::from_field(2620890703_Field);
+            let selector: aztec::protocol::abis::function_selector::FunctionSelector = <aztec::protocol::abis::function_selector::FunctionSelector as aztec::protocol::traits::FromField>::from_field(2960373586_Field);
             let args_hash: Field = aztec::hash::hash_args(serialized_params);
             aztec::oracle::execution_cache::store(serialized_params, args_hash);
             let returns_hash: aztec::context::ReturnsHash = self.context.call_private_function_with_args_hash(self.address, selector, args_hash, false);
             returns_hash.get_preimage()
         }
 
-        pub fn swap_exact_tokens_for_tokens(self, token_in: AztecAddress, token_out: AztecAddress, amount_in: u128, amount_out_min: u128, authwit_nonce: Field) {
+        pub fn swap_tokens_for_exact_tokens(self, token_in: AztecAddress, token_out: AztecAddress, amount_out: u128, amount_in_max: u128, authwit_nonce: Field) {
             let mut serialized_params: [Field; 5] = [0_Field; 5];
             let mut offset: u32 = 0_u32;
             let serialized_member: [Field; 1] = <AztecAddress as aztec::protocol::traits::Serialize>::serialize(token_in);
@@ -1200,13 +1200,13 @@ pub contract AMM {
                 serialized_params[i + offset] = serialized_member[i];
             };
             offset = offset + serialized_member_len;
-            let serialized_member: [Field; 1] = <u128 as aztec::protocol::traits::Serialize>::serialize(amount_in);
+            let serialized_member: [Field; 1] = <u128 as aztec::protocol::traits::Serialize>::serialize(amount_out);
             let serialized_member_len: u32 = <u128 as aztec::protocol::traits::Serialize>::N;
             for i in 0_u32..serialized_member_len {
                 serialized_params[i + offset] = serialized_member[i];
             };
             offset = offset + serialized_member_len;
-            let serialized_member: [Field; 1] = <u128 as aztec::protocol::traits::Serialize>::serialize(amount_out_min);
+            let serialized_member: [Field; 1] = <u128 as aztec::protocol::traits::Serialize>::serialize(amount_in_max);
             let serialized_member_len: u32 = <u128 as aztec::protocol::traits::Serialize>::N;
             for i in 0_u32..serialized_member_len {
                 serialized_params[i + offset] = serialized_member[i];
@@ -1218,7 +1218,7 @@ pub contract AMM {
                 serialized_params[i + offset] = serialized_member[i];
             };
             offset = offset + serialized_member_len;
-            let selector: aztec::protocol::abis::function_selector::FunctionSelector = <aztec::protocol::abis::function_selector::FunctionSelector as aztec::protocol::traits::FromField>::from_field(2960373586_Field);
+            let selector: aztec::protocol::abis::function_selector::FunctionSelector = <aztec::protocol::abis::function_selector::FunctionSelector as aztec::protocol::traits::FromField>::from_field(2620890703_Field);
             let args_hash: Field = aztec::hash::hash_args(serialized_params);
             aztec::oracle::execution_cache::store(serialized_params, args_hash);
             let returns_hash: aztec::context::ReturnsHash = self.context.call_private_function_with_args_hash(self.address, selector, args_hash, false);