feat: add entity batching (n-02) (#32)

* backport 1

* fix: fix contracts path

Author: glihm

crates/contracts/Scarb.lock

@@ -11,4 +11,3 @@ dependencies = [
 [[package]]
 name = "dojo_plugin"
 version = "2.8.4"
-source = "git+https://github.com/dojoengine/dojo?branch=feat%2Fdojo-1-rc0#3bf1276163fe9dbfe0f65775de8363e358510c77"

crates/contracts/Scarb.toml

@@ -7,7 +7,8 @@ version = "1.0.0-rc.0"
 
 [dependencies]
 starknet = "=2.8.4"
-dojo_plugin = { git = "https://github.com/dojoengine/dojo", branch = "feat/dojo-1-rc0" }
+dojo_plugin = { path = "../contracts" }
+#dojo_macros = { path = "../macros" }
 
 [dev-dependencies]
 cairo_test = "=2.8.4"

crates/contracts/src/event/event.cairo

@@ -4,18 +4,15 @@ use dojo::meta::introspect::Ty;
 #[derive(Drop, Serde, Debug, PartialEq)]
 pub struct EventDefinition {
     pub name: ByteArray,
-    pub version: u8,
     pub layout: Layout,
     pub schema: Ty
 }
 
 pub trait Event<T> {
     fn name() -> ByteArray;
-    fn version() -> u8;
     fn definition() -> EventDefinition;
     fn layout() -> Layout;
     fn schema() -> Ty;
-    fn historical() -> bool;
     fn keys(self: @T) -> Span<felt252>;
     fn values(self: @T) -> Span<felt252>;
     /// Returns the selector of the model computed for the given namespace hash.

crates/contracts/src/event/interface.cairo

@@ -6,7 +6,6 @@ use super::EventDefinition;
 #[starknet::interface]
 pub trait IEvent<T> {
     fn dojo_name(self: @T) -> ByteArray;
-    fn version(self: @T) -> u8;
     fn definition(self: @T) -> EventDefinition;
     fn layout(self: @T) -> Layout;
     fn schema(self: @T) -> Ty;

crates/contracts/src/lib.cairo

@@ -47,14 +47,8 @@ pub mod model {
 
     pub mod storage;
     pub use storage::{
-        ModelStorage, ModelMemberStorage, ModelStorageTest, ModelValueStorage, ModelValueStorageTest
+        ModelStorage, ModelStorageTest, ModelValueStorage, ModelValueStorageTest, ModelPtr,
     };
-
-    #[cfg(target: "test")]
-    pub use model::{ModelTest};
-
-    #[cfg(target: "test")]
-    pub use model_value::{ModelValueTest};
 }
 
 pub mod storage {

crates/contracts/src/model/model.cairo

@@ -119,25 +119,3 @@ pub impl ModelImpl<M, +ModelParser<M>, +ModelDefinition<M>, +Serde<M>> of Model<
         }
     }
 }
-
-/// The `ModelTest` trait.
-///
-/// It provides a standardized way to interact with models for testing purposes,
-/// bypassing the permission checks.
-#[cfg(target: "test")]
-pub trait ModelTest<S, M> {
-    fn set_model_test(ref self: S, model: @M);
-    fn delete_model_test(ref self: S, model: @M);
-}
-
-/// The `ModelTestImpl` implementation for testing purposes.
-#[cfg(target: "test")]
-pub impl ModelTestImpl<S, M, +dojo::model::ModelStorageTest<S, M>, +Model<M>> of ModelTest<S, M> {
-    fn set_model_test(ref self: S, model: @M) {
-        dojo::model::ModelStorageTest::<S, M>::write_model_test(ref self, model);
-    }
-
-    fn delete_model_test(ref self: S, model: @M) {
-        dojo::model::ModelStorageTest::<S, M>::erase_model_test(ref self, model);
-    }
-}

crates/contracts/src/model/model_value.cairo

@@ -34,7 +34,7 @@ pub impl ModelValueImpl<V, +Serde<V>, +ModelDefinition<V>, +ModelValueParser<V>>
     }
 
     fn from_values(entity_id: felt252, ref values: Span<felt252>) -> Option<V> {
-        let mut serialized: Array<felt252> = array![entity_id];
+        let mut serialized: Array<felt252> = array![];
         serialized.append_span(values);
         let mut span = serialized.span();
         Serde::<V>::deserialize(ref span)
@@ -60,27 +60,3 @@ pub impl ModelValueImpl<V, +Serde<V>, +ModelDefinition<V>, +ModelValueParser<V>>
         dojo::utils::selector_from_namespace_and_name(namespace_hash, @Self::name())
     }
 }
-
-
-/// Test implementation of the `ModelValueTest` trait to bypass permission checks.
-#[cfg(target: "test")]
-pub trait ModelValueTest<S, V> {
-    fn update_test(ref self: S, entity_id: felt252, value: @V);
-    fn delete_test(ref self: S, entity_id: felt252);
-}
-
-/// Implementation of the `ModelValueTest` trait for testing purposes, bypassing permission checks.
-#[cfg(target: "test")]
-pub impl ModelValueTestImpl<
-    S, V, +super::storage::ModelValueStorageTest<S, V>, +ModelValue<V>
-> of ModelValueTest<S, V> {
-    fn update_test(ref self: S, entity_id: felt252, value: @V) {
-        super::storage::ModelValueStorageTest::<
-            S, V
-        >::write_model_value_test(ref self, entity_id, value)
-    }
-
-    fn delete_test(ref self: S, entity_id: felt252) {
-        super::storage::ModelValueStorageTest::<S, V>::erase_model_value_test(ref self, entity_id)
-    }
-}

crates/contracts/src/model/storage.cairo

@@ -1,5 +1,17 @@
 use dojo::model::model_value::ModelValueKey;
 
+// TODO: define the right interface for member accesses.
+
+/// A pointer to a model, which can be expressed by an entity id.
+/// It's different from `ModelIndex` which is used for low level accesses.
+#[derive(Copy, Drop, Serde, Debug, PartialEq)]
+pub enum ModelPtr<M> {
+    // The id of the model.
+    Id: felt252,
+    // The keys of the model as span.
+    Keys: Span<felt252>,
+}
+
 /// A `ModelStorage` trait that abstracts where the storage is.
 ///
 /// Currently it's only world storage, but this will be useful when we have other
@@ -8,41 +20,29 @@ pub trait ModelStorage<S, M> {
     /// Sets a model of type `M`.
     fn write_model(ref self: S, model: @M);
 
+    /// Sets multiple models of type `M`.
+    fn write_models(ref self: S, models: Span<@M>);
+
     /// Retrieves a model of type `M` using the provided key of type `K`.
     fn read_model<K, +Drop<K>, +Serde<K>>(self: @S, key: K) -> M;
 
+    /// Retrieves multiple models of type `M` using the provided keys of type `K`.
+    /// Returnes an array to ensure the user can consume the models, even if the type is not
+    /// copiable.
+    fn read_models<K, +Drop<K>, +Serde<K>>(self: @S, keys: Span<K>) -> Array<M>;
+
     /// Deletes a model of type `M`.
     fn erase_model(ref self: S, model: @M);
 
-    /// Deletes a model of type `M` using the provided key of type `K`.
-    fn erase_model_from_key<K, +Drop<K>, +Serde<K>>(ref self: S, key: K);
+    /// Deletes multiple models of type `M`.
+    fn erase_models(ref self: S, models: Span<@M>);
 
     /// Deletes a model of type `M` using the provided entity id.
-    fn erase_model_from_id(ref self: S, entity_id: felt252);
-
-    /// Retrieves a member of type `T` from a model of type `M` using the provided member id and key
-    /// of type `K`.
-    fn read_member<T, K, +ModelMemberStorage<S, M, T>, +Drop<T>, +Drop<K>, +Serde<K>>(
-        self: @S, key: K, member_id: felt252
-    ) -> T;
-
-    /// Updates a member of type `T` within a model of type `M` using the provided member id, key of
-    /// type `K`, and new value of type `T`.
-    fn write_member<T, K, +ModelMemberStorage<S, M, T>, +Drop<T>, +Drop<K>, +Serde<K>>(
-        ref self: S, key: K, member_id: felt252, value: T
-    );
-
-    /// Returns the current namespace hash.
-    fn namespace_hash(self: @S) -> felt252;
-}
-
-/// A `ModelMemberStorage` trait that abstracts where the storage is.
-pub trait ModelMemberStorage<S, M, T> {
-    /// Retrieves a member of type `T` for the given entity id and member id.
-    fn read_member_from_id(self: @S, entity_id: felt252, member_id: felt252) -> T;
+    /// The ptr is mostly used for type inferrence.
+    fn erase_model_ptr(ref self: S, ptr: ModelPtr<M>);
 
-    /// Updates a member of type `T` for the given entity id and member id.
-    fn write_member_from_id(ref self: S, entity_id: felt252, member_id: felt252, value: T);
+    /// Deletes multiple models of type `M` using the provided entity ids.
+    fn erase_models_ptrs(ref self: S, ptrs: Span<ModelPtr<M>>);
 
     /// Returns the current namespace hash.
     fn namespace_hash(self: @S) -> felt252;
@@ -51,18 +51,32 @@ pub trait ModelMemberStorage<S, M, T> {
 /// A `ModelValueStorage` trait that abstracts where the storage is.
 pub trait ModelValueStorage<S, V> {
     /// Retrieves a model value of type `V` using the provided key of type `K`.
-    fn read_model_value<K, +Drop<K>, +Serde<K>, +ModelValueKey<V, K>>(self: @S, key: K) -> V;
+    fn read_value<K, +Drop<K>, +Serde<K>, +ModelValueKey<V, K>>(self: @S, key: K) -> V;
+
+    /// Retrieves multiple model values of type `V` using the provided keys of type `K`.
+    fn read_values<K, +Drop<K>, +Serde<K>, +ModelValueKey<V, K>>(
+        self: @S, keys: Span<K>
+    ) -> Array<V>;
 
     /// Retrieves a model value of type `V` using the provided entity id.
-    fn read_model_value_from_id(self: @S, entity_id: felt252) -> V;
+    fn read_value_from_id(self: @S, entity_id: felt252) -> V;
+
+    /// Retrieves multiple model values of type `V` using the provided entity ids.
+    fn read_values_from_ids(self: @S, entity_ids: Span<felt252>) -> Array<V>;
 
     /// Updates a model value of type `V`.
-    fn write_model_value<K, +Drop<K>, +Serde<K>, +ModelValueKey<V, K>>(
-        ref self: S, key: K, value: @V
+    fn write_value<K, +Drop<K>, +Serde<K>, +ModelValueKey<V, K>>(ref self: S, key: K, value: @V);
+
+    /// Updates multiple model values of type `V`.
+    fn write_values<K, +Drop<K>, +Serde<K>, +ModelValueKey<V, K>>(
+        ref self: S, keys: Span<K>, values: Span<@V>
     );
 
     /// Updates a model value of type `V`.
-    fn write_model_value_from_id(ref self: S, entity_id: felt252, value: @V);
+    fn write_value_from_id(ref self: S, entity_id: felt252, value: @V);
+
+    /// Updates multiple model values of type `V`.
+    fn write_values_from_ids(ref self: S, entity_ids: Span<felt252>, values: Span<@V>);
 }
 
 /// A `ModelStorage` trait that abstracts where the storage is.
@@ -72,15 +86,31 @@ pub trait ModelValueStorage<S, V> {
 pub trait ModelStorageTest<S, M> {
     /// Sets a model of type `M`.
     fn write_model_test(ref self: S, model: @M);
+    /// Sets multiple models of type `M`.
+    fn write_models_test(ref self: S, models: Span<@M>);
     /// Deletes a model of type `M`.
     fn erase_model_test(ref self: S, model: @M);
+    /// Deletes multiple models of type `M`.
+    fn erase_models_test(ref self: S, models: Span<@M>);
+    /// Deletes a model of type `M` using the provided entity id.
+    fn erase_model_ptr_test(ref self: S, ptr: ModelPtr<M>);
+    /// Deletes multiple models of type `M` using the provided entity ids.
+    fn erase_models_ptrs_test(ref self: S, ptrs: Span<ModelPtr<M>>);
 }
 
 /// A `ModelValueStorageTest` trait that abstracts where the storage is and bypass the permission
 /// checks.
 pub trait ModelValueStorageTest<S, V> {
     /// Updates a model value of type `V`.
-    fn write_model_value_test(ref self: S, entity_id: felt252, value: @V);
-    /// Deletes a model value of type `V`.
-    fn erase_model_value_test(ref self: S, entity_id: felt252);
+    fn write_value_test<K, +Drop<K>, +Serde<K>, +ModelValueKey<V, K>>(
+        ref self: S, key: K, value: @V
+    );
+    /// Updates multiple model values of type `V`.
+    fn write_values_test<K, +Drop<K>, +Serde<K>, +ModelValueKey<V, K>>(
+        ref self: S, keys: Span<K>, values: Span<@V>
+    );
+    /// Updates a model value of type `V`.
+    fn write_value_from_id_test(ref self: S, entity_id: felt252, value: @V);
+    /// Updates multiple model values of type `V`.
+    fn write_values_from_ids_test(ref self: S, entity_ids: Span<felt252>, values: Span<@V>);
 }

crates/contracts/src/world/errors.cairo

@@ -2,6 +2,10 @@ use starknet::ContractAddress;
 
 pub const DELETE_ENTITY_MEMBER: felt252 = 'Cannot delete entity member';
 
+pub fn lengths_mismatch(a: @ByteArray, b: @ByteArray, context: @ByteArray) -> ByteArray {
+    format!("Length mismatch: `{a}` and `{b}` in `{context}`")
+}
+
 pub fn not_writer(contract_tag: @ByteArray, on_type: @ByteArray, on_tag: @ByteArray) -> ByteArray {
     format!("Caller `{}` has no write access on {} `{}`", contract_tag, on_type, on_tag)
 }
@@ -63,7 +67,7 @@ pub fn invalid_resource_selector(selector: felt252) -> ByteArray {
 }
 
 pub fn resource_conflict(name: @ByteArray, expected_type: @ByteArray) -> ByteArray {
-    format!("Resource `{}` is registered but not as a {}", name, expected_type)
+    format!("Resource `{}` is registered but not as {}", name, expected_type)
 }
 
 pub fn no_model_write_access(tag: @ByteArray, caller: ContractAddress) -> ByteArray {

crates/contracts/src/world/iworld.cairo

@@ -126,13 +126,23 @@ pub trait IWorld<T> {
     /// * `event_selector` - The selector of the event.
     /// * `keys` - The keys of the event.
     /// * `values` - The data to be logged by the event.
-    /// * `historical` - Whether the event should be logged in historical mode.
     fn emit_event(
+        ref self: T, event_selector: felt252, keys: Span<felt252>, values: Span<felt252>,
+    );
+
+    /// Emits multiple events.
+    /// Permissions are only checked once, then the events are batched.
+    ///
+    /// # Arguments
+    ///
+    /// * `event_selector` - The selector of the event.
+    /// * `keys` - The keys of the event.
+    /// * `values` - The data to be logged by the event.
+    fn emit_events(
         ref self: T,
         event_selector: felt252,
-        keys: Span<felt252>,
-        values: Span<felt252>,
-        historical: bool
+        keys: Span<Span<felt252>>,
+        values: Span<Span<felt252>>,
     );
 
     /// Gets the values of a model entity/member.
@@ -151,6 +161,17 @@ pub trait IWorld<T> {
         self: @T, model_selector: felt252, index: ModelIndex, layout: Layout
     ) -> Span<felt252>;
 
+    /// Gets the model values for the given entities.
+    ///
+    /// # Arguments
+    ///
+    /// * `model_selector` - The selector of the model to be retrieved.
+    /// * `indices` - The indexes of the entities/members to read.
+    /// * `layout` - The memory layout of the model.
+    fn entities(
+        self: @T, model_selector: felt252, indexes: Span<ModelIndex>, layout: Layout
+    ) -> Span<Span<felt252>>;
+
     /// Sets the model value for the given entity/member.
     ///
     /// # Arguments
@@ -167,6 +188,23 @@ pub trait IWorld<T> {
         layout: Layout
     );
 
+    /// Sets the model values for the given entities.
+    /// The permissions are only checked once, then the writes are batched.
+    ///
+    /// # Arguments
+    ///
+    /// * `model_selector` - The selector of the model to be set.
+    /// * `indexes` - The indexes of the entities/members to write.
+    /// * `values` - The values to be set, serialized using the model layout format.
+    /// * `layout` - The memory layout of the model.
+    fn set_entities(
+        ref self: T,
+        model_selector: felt252,
+        indexes: Span<ModelIndex>,
+        values: Span<Span<felt252>>,
+        layout: Layout
+    );
+
     /// Deletes a model value for the given entity/member.
     /// Deleting is setting all the values to 0 in the given layout.
     ///
@@ -177,6 +215,18 @@ pub trait IWorld<T> {
     /// * `layout` - The memory layout of the model.
     fn delete_entity(ref self: T, model_selector: felt252, index: ModelIndex, layout: Layout);
 
+    /// Deletes the model values for the given entities.
+    /// The permissions are only checked once, then the deletes are batched.
+    ///
+    /// # Arguments
+    ///
+    /// * `model_selector` - The selector of the model to be deleted.
+    /// * `indexes` - The indexes of the entities/members to delete.
+    /// * `layout` - The memory layout of the model.
+    fn delete_entities(
+        ref self: T, model_selector: felt252, indexes: Span<ModelIndex>, layout: Layout
+    );
+
     /// Returns true if the provided account has owner permission for the resource, false otherwise.
     ///
     /// # Arguments
@@ -258,11 +308,7 @@ pub trait IWorldTest<T> {
     /// Emits a custom event that was previously registered in the world without checking for
     /// resource permissions.
     fn emit_event_test(
-        ref self: T,
-        event_selector: felt252,
-        keys: Span<felt252>,
-        values: Span<felt252>,
-        historical: bool
+        ref self: T, event_selector: felt252, keys: Span<felt252>, values: Span<felt252>,
     );
 
     /// Returns the address of a registered contract, panics otherwise.