Skip to main content

iota_types/effects/
test_effects_builder.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::collections::{BTreeMap, BTreeSet};
6
7use iota_sdk_types::{
8    ExecutionStatus, GasCostSummary, ObjectDigest, ObjectId, ObjectReference, Owner,
9    SenderSignedTransaction, TransactionEventsDigest, Version,
10    effects::{ChangedObject, IdOperation, ObjectIn, ObjectOut, TransactionEffects},
11};
12
13use crate::{
14    committee::EpochId,
15    effects::TransactionEffectsExt,
16    execution::SharedInput,
17    message_envelope::Message,
18    transaction::{InputObjectKind, TransactionAPI},
19};
20
21pub struct TestEffectsBuilder {
22    transaction: SenderSignedTransaction,
23    /// The epoch the effects record as the one that executed the transaction.
24    epoch: EpochId,
25    /// Override the execution status if provided.
26    status: Option<ExecutionStatus>,
27    /// Provide the assigned versions for all shared objects.
28    shared_input_versions: BTreeMap<ObjectId, Version>,
29    events_digest: Option<TransactionEventsDigest>,
30    created_objects: Vec<(ObjectId, Owner)>,
31    /// Objects that are mutated: (ID, old version, new owner).
32    mutated_objects: Vec<(ObjectId, Version, Owner)>,
33    /// Objects that are deleted: (ID, old version, old owner).
34    deleted_objects: Vec<(ObjectId, Version, Owner)>,
35    /// Objects that are wrapped: (ID, old version).
36    wrapped_objects: Vec<(ObjectId, Version)>,
37    /// Objects that are unwrapped: (ID, new owner).
38    unwrapped_objects: Vec<(ObjectId, Owner)>,
39    /// Immutable objects that are read.
40    frozen_objects: BTreeSet<ObjectId>,
41}
42
43impl TestEffectsBuilder {
44    pub fn new(transaction: &SenderSignedTransaction) -> Self {
45        Self {
46            transaction: transaction.clone(),
47            epoch: 0,
48            status: None,
49            shared_input_versions: BTreeMap::new(),
50            events_digest: None,
51            created_objects: vec![],
52            mutated_objects: vec![],
53            deleted_objects: vec![],
54            wrapped_objects: vec![],
55            unwrapped_objects: vec![],
56            frozen_objects: BTreeSet::new(),
57        }
58    }
59
60    /// Records `epoch` as the epoch that executed the transaction.
61    pub fn with_epoch(mut self, epoch: EpochId) -> Self {
62        self.epoch = epoch;
63        self
64    }
65
66    pub fn with_status(mut self, status: ExecutionStatus) -> Self {
67        self.status = Some(status);
68        self
69    }
70
71    pub fn with_shared_input_versions(mut self, versions: BTreeMap<ObjectId, Version>) -> Self {
72        assert!(self.shared_input_versions.is_empty());
73        self.shared_input_versions = versions;
74        self
75    }
76
77    pub fn with_events_digest(mut self, digest: TransactionEventsDigest) -> Self {
78        self.events_digest = Some(digest);
79        self
80    }
81
82    pub fn with_created_objects(
83        mut self,
84        objects: impl IntoIterator<Item = (ObjectId, Owner)>,
85    ) -> Self {
86        self.created_objects.extend(objects);
87        self
88    }
89
90    pub fn with_mutated_objects(
91        mut self,
92        // Object ID, old version, and new owner.
93        objects: impl IntoIterator<Item = (ObjectId, Version, Owner)>,
94    ) -> Self {
95        self.mutated_objects.extend(objects);
96        self
97    }
98
99    pub fn with_wrapped_objects(
100        mut self,
101        objects: impl IntoIterator<Item = (ObjectId, Version)>,
102    ) -> Self {
103        self.wrapped_objects.extend(objects);
104        self
105    }
106
107    pub fn with_unwrapped_objects(
108        mut self,
109        objects: impl IntoIterator<Item = (ObjectId, Owner)>,
110    ) -> Self {
111        self.unwrapped_objects.extend(objects);
112        self
113    }
114
115    /// Deleted objects owned by the sender: (ID, old version).
116    pub fn with_deleted_objects(
117        mut self,
118        objects: impl IntoIterator<Item = (ObjectId, Version)>,
119    ) -> Self {
120        let sender = self.transaction.transaction().sender();
121        self.deleted_objects.extend(
122            objects
123                .into_iter()
124                .map(|(id, version)| (id, version, Owner::Address(sender))),
125        );
126        self
127    }
128
129    /// Deleted objects with the owner they had: (ID, old version, old owner).
130    pub fn with_deleted_objects_owned_by(
131        mut self,
132        objects: impl IntoIterator<Item = (ObjectId, Version, Owner)>,
133    ) -> Self {
134        self.deleted_objects.extend(objects);
135        self
136    }
137
138    pub fn with_frozen_objects(mut self, objects: impl IntoIterator<Item = ObjectId>) -> Self {
139        self.frozen_objects.extend(objects);
140        self
141    }
142
143    pub fn build(self) -> TransactionEffects {
144        let lamport_version = self.get_lamport_version();
145        let status = self.status.unwrap_or(ExecutionStatus::Success);
146        // TODO: This does not yet support deleted shared objects.
147        let shared_objects = self
148            .shared_input_versions
149            .iter()
150            .map(|(id, version)| {
151                SharedInput::Existing(ObjectReference::new(*id, *version, ObjectDigest::MIN))
152            })
153            .collect();
154        let epoch = self.epoch;
155        let sender = self.transaction.transaction().sender();
156        // TODO: Include receiving objects in the object changes as well.
157        let changed_objects = self
158            .transaction
159            .transaction()
160            .input_objects()
161            .unwrap()
162            .iter()
163            .filter_map(|kind| match kind {
164                InputObjectKind::ImmOrOwnedMoveObject(object_ref)
165                    if self.frozen_objects.contains(&object_ref.object_id) =>
166                {
167                    None
168                }
169                InputObjectKind::ImmOrOwnedMoveObject(oref) => {
170                    Some((
171                        oref.object_id,
172                        ChangedObject {
173                            object_id: oref.object_id,
174                            input_state: ObjectIn::Data {
175                                version: oref.version,
176                                digest: oref.digest,
177                                owner: Owner::Address(sender),
178                            },
179                            output_state: ObjectOut::ObjectWrite {
180                                // Digest must change with a mutation.
181                                digest: ObjectDigest::MAX,
182                                owner: Owner::Address(sender),
183                            },
184                            id_operation: IdOperation::None,
185                        },
186                    ))
187                }
188                InputObjectKind::MovePackage(_) => None,
189                InputObjectKind::SharedMoveObject {
190                    id,
191                    initial_shared_version,
192                    mutable,
193                } => mutable.then_some((
194                    *id,
195                    ChangedObject {
196                        object_id: *id,
197                        input_state: ObjectIn::Data {
198                            version: *self
199                                .shared_input_versions
200                                .get(id)
201                                .unwrap_or(initial_shared_version),
202                            digest: ObjectDigest::MIN,
203                            owner: Owner::Shared(*initial_shared_version),
204                        },
205                        output_state: ObjectOut::ObjectWrite {
206                            // Digest must change with a mutation.
207                            digest: ObjectDigest::MAX,
208                            owner: Owner::Shared(*initial_shared_version),
209                        },
210                        id_operation: IdOperation::None,
211                    },
212                )),
213            })
214            .chain(self.created_objects.into_iter().map(|(id, owner)| {
215                (
216                    id,
217                    ChangedObject {
218                        object_id: id,
219                        input_state: ObjectIn::Missing,
220                        output_state: ObjectOut::ObjectWrite {
221                            digest: ObjectDigest::random(),
222                            owner,
223                        },
224                        id_operation: IdOperation::Created,
225                    },
226                )
227            }))
228            .chain(
229                self.mutated_objects
230                    .into_iter()
231                    .map(|(id, version, owner)| {
232                        (
233                            id,
234                            ChangedObject {
235                                object_id: id,
236                                input_state: ObjectIn::Data {
237                                    version,
238                                    digest: ObjectDigest::random(),
239                                    owner: Owner::Address(sender),
240                                },
241                                output_state: ObjectOut::ObjectWrite {
242                                    digest: ObjectDigest::random(),
243                                    owner,
244                                },
245                                id_operation: IdOperation::None,
246                            },
247                        )
248                    }),
249            )
250            .chain(
251                self.deleted_objects
252                    .into_iter()
253                    .map(|(id, version, owner)| {
254                        (
255                            id,
256                            ChangedObject {
257                                object_id: id,
258                                input_state: ObjectIn::Data {
259                                    version,
260                                    digest: ObjectDigest::random(),
261                                    owner,
262                                },
263                                output_state: ObjectOut::Missing,
264                                id_operation: IdOperation::Deleted,
265                            },
266                        )
267                    }),
268            )
269            .chain(self.wrapped_objects.into_iter().map(|(id, version)| {
270                (
271                    id,
272                    ChangedObject {
273                        object_id: id,
274                        input_state: ObjectIn::Data {
275                            version,
276                            digest: ObjectDigest::random(),
277                            owner: Owner::Address(sender),
278                        },
279                        output_state: ObjectOut::Missing,
280                        id_operation: IdOperation::None,
281                    },
282                )
283            }))
284            .chain(self.unwrapped_objects.into_iter().map(|(id, owner)| {
285                (
286                    id,
287                    ChangedObject {
288                        object_id: id,
289                        input_state: ObjectIn::Missing,
290                        output_state: ObjectOut::ObjectWrite {
291                            digest: ObjectDigest::random(),
292                            owner,
293                        },
294                        id_operation: IdOperation::None,
295                    },
296                )
297            }))
298            .collect();
299        // A system transaction carries only a placeholder gas payment that
300        // never appears in the changed objects.
301        let gas_object_id = (!self.transaction.transaction().is_system_tx())
302            .then(|| self.transaction.transaction().gas()[0].object_id);
303        let event_digest = self.events_digest;
304        let dependencies = vec![];
305
306        TransactionEffects::new_from_execution_v1(
307            status,
308            epoch,
309            GasCostSummary::default(),
310            shared_objects,
311            BTreeSet::new(),
312            self.transaction.digest(),
313            lamport_version,
314            changed_objects,
315            gas_object_id,
316            event_digest,
317            dependencies,
318        )
319    }
320
321    fn get_lamport_version(&self) -> Version {
322        Version::lamport_increment(
323            self.transaction
324                .transaction()
325                .input_objects()
326                .unwrap()
327                .iter()
328                .filter_map(|kind| kind.version())
329                .chain(
330                    self.transaction
331                        .transaction()
332                        .receiving_objects()
333                        .iter()
334                        .map(|oref| oref.version),
335                )
336                .chain(self.shared_input_versions.values().copied())
337                .chain(self.mutated_objects.iter().map(|(_, v, _)| *v))
338                .chain(self.deleted_objects.iter().map(|(_, v, _)| *v))
339                .chain(self.wrapped_objects.iter().map(|(_, v)| *v)),
340        )
341        .unwrap()
342    }
343}