refactor!: ephemeral arrays (#22162)

Implements a new type of array especially designed to use in oracle
interfaces between Aztec.nr and PXE. The memory space of of these arrays
is isolated by contract call frame and lives in memory. This makes them
faster to work with, but it also removes the need for a lot of
boilerplate to instantiate them, use them as params, and ultimately
dispose of them.

Closes F-136

---------

Co-authored-by: Jan Beneš <janbenes1234@gmail.com>

Author: 2 people

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

@@ -0,0 +1,366 @@
+use crate::oracle::ephemeral;
+use crate::protocol::traits::{Deserialize, Serialize};
+
+/// A dynamically sized array that exists only during a single contract call frame.
+///
+/// Ephemeral arrays are backed by in-memory storage on the PXE side rather than a persistent database. Each contract
+/// call frame gets its own isolated slot space of ephemeral arrays. Child simulations cannot see the parent's
+/// ephemeral arrays, and vice versa.
+///
+/// Each logical array operation (push, pop, get, etc.) is a single oracle call, making ephemeral arrays significantly
+/// cheaper than capsule arrays.
+///
+/// ## Use Cases
+///
+/// Ephemeral arrays are designed for passing data between PXE (TypeScript) and contracts (Noir) during simulation,
+/// for example, note validation requests or event validation responses. This data type is appropriate for data that
+/// is not supposed to be persisted.
+///
+/// For data that needs to persist across simulations, contract calls, etc, use
+/// [`CapsuleArray`](crate::capsules::CapsuleArray) instead.
+pub struct EphemeralArray<T> {
+    pub slot: Field,
+}
+
+impl<T> EphemeralArray<T> {
+    /// Returns a handle to an ephemeral array at the given slot, which may already contain data (e.g. populated
+    /// by an oracle).
+    pub unconstrained fn at(slot: Field) -> Self {
+        Self { slot }
+    }
+
+    /// Returns the number of elements stored in the array.
+    pub unconstrained fn len(self) -> u32 {
+        ephemeral::len_oracle(self.slot)
+    }
+
+    /// Stores a value at the end of the array.
+    pub unconstrained fn push(self, value: T)
+    where
+        T: Serialize,
+    {
+        let serialized = value.serialize();
+        let _ = ephemeral::push_oracle(self.slot, serialized);
+    }
+
+    /// Removes and returns the last element. Panics if the array is empty.
+    pub unconstrained fn pop(self) -> T
+    where
+        T: Deserialize,
+    {
+        let serialized = ephemeral::pop_oracle(self.slot);
+        Deserialize::deserialize(serialized)
+    }
+
+    /// Retrieves the value stored at `index`. Panics if the index is out of bounds.
+    pub unconstrained fn get(self, index: u32) -> T
+    where
+        T: Deserialize,
+    {
+        let serialized = ephemeral::get_oracle(self.slot, index);
+        Deserialize::deserialize(serialized)
+    }
+
+    /// Overwrites the value stored at `index`. Panics if the index is out of bounds.
+    pub unconstrained fn set(self, index: u32, value: T)
+    where
+        T: Serialize,
+    {
+        let serialized = value.serialize();
+        ephemeral::set_oracle(self.slot, index, serialized);
+    }
+
+    /// Removes the element at `index`, shifting subsequent elements backward. Panics if out of bounds.
+    pub unconstrained fn remove(self, index: u32) {
+        ephemeral::remove_oracle(self.slot, index);
+    }
+
+    /// Removes all elements from the array and returns self for chaining (e.g. `EphemeralArray::at(slot).clear()`
+    /// to get a guaranteed-empty array at a given slot).
+    pub unconstrained fn clear(self) -> Self {
+        ephemeral::clear_oracle(self.slot);
+        self
+    }
+
+    /// Calls a function on each element of the array.
+    ///
+    /// The function `f` is called once with each array value and its corresponding index. Iteration proceeds
+    /// backwards so that it is safe to remove the current element (and only the current element) inside the
+    /// callback.
+    ///
+    /// It is **not** safe to push new elements from inside the callback.
+    pub unconstrained fn for_each<Env>(self, f: unconstrained fn[Env](u32, T) -> ())
+    where
+        T: Deserialize,
+    {
+        let mut i = self.len();
+        while i > 0 {
+            i -= 1;
+            f(i, self.get(i));
+        }
+    }
+}
+
+mod test {
+    use crate::test::helpers::test_environment::TestEnvironment;
+    use crate::test::mocks::MockStruct;
+    use super::EphemeralArray;
+
+    global SLOT: Field = 1230;
+    global OTHER_SLOT: Field = 5670;
+
+    #[test]
+    unconstrained fn empty_array() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array: EphemeralArray<Field> = EphemeralArray::at(SLOT);
+            assert_eq(array.len(), 0);
+        });
+    }
+
+    #[test(should_fail_with = "out of bounds")]
+    unconstrained fn empty_array_read() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+            let _: Field = array.get(0);
+        });
+    }
+
+    #[test(should_fail_with = "is empty")]
+    unconstrained fn empty_array_pop() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+            let _: Field = array.pop();
+        });
+    }
+
+    #[test]
+    unconstrained fn array_push() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+            array.push(5);
+
+            assert_eq(array.len(), 1);
+            assert_eq(array.get(0), 5);
+        });
+    }
+
+    #[test(should_fail_with = "out of bounds")]
+    unconstrained fn read_past_len() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+            array.push(5);
+
+            let _ = array.get(1);
+        });
+    }
+
+    #[test]
+    unconstrained fn array_pop() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+            array.push(5);
+            array.push(10);
+
+            let popped: Field = array.pop();
+            assert_eq(popped, 10);
+            assert_eq(array.len(), 1);
+            assert_eq(array.get(0), 5);
+        });
+    }
+
+    #[test]
+    unconstrained fn array_set() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+            array.push(5);
+            array.set(0, 99);
+            assert_eq(array.get(0), 99);
+        });
+    }
+
+    #[test]
+    unconstrained fn array_remove_last() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+            array.push(5);
+            array.remove(0);
+            assert_eq(array.len(), 0);
+        });
+    }
+
+    #[test]
+    unconstrained fn array_remove_some() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+
+            array.push(7);
+            array.push(8);
+            array.push(9);
+
+            assert_eq(array.len(), 3);
+
+            array.remove(1);
+
+            assert_eq(array.len(), 2);
+            assert_eq(array.get(0), 7);
+            assert_eq(array.get(1), 9);
+        });
+    }
+
+    #[test]
+    unconstrained fn array_remove_all() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+
+            array.push(7);
+            array.push(8);
+            array.push(9);
+
+            array.remove(1);
+            array.remove(1);
+            array.remove(0);
+
+            assert_eq(array.len(), 0);
+        });
+    }
+
+    #[test]
+    unconstrained fn for_each_called_with_all_elements() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+
+            array.push(4);
+            array.push(5);
+            array.push(6);
+
+            let called_with = &mut BoundedVec::<(u32, Field), 3>::new();
+            array.for_each(|index, value| { called_with.push((index, value)); });
+
+            assert_eq(called_with.len(), 3);
+            assert(called_with.any(|(index, value)| (index == 0) & (value == 4)));
+            assert(called_with.any(|(index, value)| (index == 1) & (value == 5)));
+            assert(called_with.any(|(index, value)| (index == 2) & (value == 6)));
+        });
+    }
+
+    #[test]
+    unconstrained fn for_each_remove_some() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+
+            array.push(4);
+            array.push(5);
+            array.push(6);
+
+            array.for_each(|index, _| {
+                if index == 1 {
+                    array.remove(index);
+                }
+            });
+
+            assert_eq(array.len(), 2);
+            assert_eq(array.get(0), 4);
+            assert_eq(array.get(1), 6);
+        });
+    }
+
+    #[test]
+    unconstrained fn for_each_remove_all() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array = EphemeralArray::at(SLOT);
+
+            array.push(4);
+            array.push(5);
+            array.push(6);
+
+            array.for_each(|index, _| { array.remove(index); });
+
+            assert_eq(array.len(), 0);
+        });
+    }
+
+    #[test]
+    unconstrained fn different_slots_are_isolated() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array_a = EphemeralArray::at(SLOT);
+            let array_b = EphemeralArray::at(OTHER_SLOT);
+
+            array_a.push(10);
+            array_a.push(20);
+            array_b.push(99);
+
+            assert_eq(array_a.len(), 2);
+            assert_eq(array_a.get(0), 10);
+            assert_eq(array_a.get(1), 20);
+
+            assert_eq(array_b.len(), 1);
+            assert_eq(array_b.get(0), 99);
+        });
+    }
+
+    #[test]
+    unconstrained fn works_with_multi_field_type() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array: EphemeralArray<MockStruct> = EphemeralArray::at(SLOT);
+
+            let a = MockStruct::new(5, 6);
+            let b = MockStruct::new(7, 8);
+            array.push(a);
+            array.push(b);
+
+            assert_eq(array.len(), 2);
+            assert_eq(array.get(0), a);
+            assert_eq(array.get(1), b);
+
+            let popped: MockStruct = array.pop();
+            assert_eq(popped, b);
+            assert_eq(array.len(), 1);
+        });
+    }
+
+    #[test]
+    unconstrained fn clear_returns_self() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array: EphemeralArray<Field> = EphemeralArray::at(SLOT).clear();
+            assert_eq(array.len(), 0);
+
+            array.push(42);
+            assert_eq(array.len(), 1);
+            assert_eq(array.get(0), 42);
+        });
+    }
+
+    #[test]
+    unconstrained fn clear_wipes_previous_data() {
+        let env = TestEnvironment::new();
+        env.utility_context(|_| {
+            let array: EphemeralArray<Field> = EphemeralArray::at(SLOT);
+            array.push(1);
+            array.push(2);
+            array.push(3);
+            assert_eq(array.len(), 3);
+
+            // Clear the same slot, previous data should be gone.
+            let fresh: EphemeralArray<Field> = EphemeralArray::at(SLOT).clear();
+            assert_eq(fresh.len(), 0);
+            fresh.push(4);
+            assert_eq(fresh.get(0), 4);
+        });
+    }
+}

noir-projects/aztec-nr/aztec/src/lib.nr

@@ -39,6 +39,7 @@ pub mod nullifier;
 pub mod oracle;
 pub mod state_vars;
 pub mod capsules;
+pub mod ephemeral;
 pub mod event;
 pub mod messages;
 pub use protocol_types as protocol;