sui_types/effects/
mod.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4pub use self::effects_v2::TransactionEffectsV2;
5use crate::accumulator_event::AccumulatorEvent;
6use crate::base_types::{ExecutionDigests, ObjectID, ObjectRef, SequenceNumber};
7use crate::committee::{Committee, EpochId};
8use crate::crypto::{
9    AuthoritySignInfo, AuthoritySignInfoTrait, AuthorityStrongQuorumSignInfo, EmptySignInfo,
10    default_hash,
11};
12use crate::digests::{
13    ObjectDigest, TransactionDigest, TransactionEffectsDigest, TransactionEventsDigest,
14};
15use crate::error::SuiResult;
16use crate::event::Event;
17use crate::execution::SharedInput;
18use crate::execution_status::{ExecutionStatus, MoveLocation};
19use crate::gas::GasCostSummary;
20use crate::message_envelope::{Envelope, Message, TrustedEnvelope, VerifiedEnvelope};
21use crate::object::Owner;
22use crate::storage::WriteKind;
23pub use effects_v1::TransactionEffectsV1;
24pub use effects_v2::UnchangedConsensusKind;
25use enum_dispatch::enum_dispatch;
26pub use object_change::{
27    AccumulatorAddress, AccumulatorOperation, AccumulatorValue, AccumulatorWriteV1,
28    EffectsObjectChange, ObjectIn, ObjectOut,
29};
30use serde::{Deserialize, Serialize};
31use shared_crypto::intent::{Intent, IntentScope};
32use std::collections::{BTreeMap, BTreeSet};
33pub use test_effects_builder::TestEffectsBuilder;
34
35mod effects_v1;
36mod effects_v2;
37mod object_change;
38mod test_effects_builder;
39
40// Since `std::mem::size_of` may not be stable across platforms, we use rough constants
41// We need these for estimating effects sizes
42// Approximate size of `ObjectRef` type in bytes
43pub const APPROX_SIZE_OF_OBJECT_REF: usize = 80;
44// Approximate size of `ExecutionStatus` type in bytes
45pub const APPROX_SIZE_OF_EXECUTION_STATUS: usize = 120;
46// Approximate size of `EpochId` type in bytes
47pub const APPROX_SIZE_OF_EPOCH_ID: usize = 10;
48// Approximate size of `GasCostSummary` type in bytes
49pub const APPROX_SIZE_OF_GAS_COST_SUMMARY: usize = 40;
50// Approximate size of `Option<TransactionEventsDigest>` type in bytes
51pub const APPROX_SIZE_OF_OPT_TX_EVENTS_DIGEST: usize = 40;
52// Approximate size of `TransactionDigest` type in bytes
53pub const APPROX_SIZE_OF_TX_DIGEST: usize = 40;
54// Approximate size of `Owner` type in bytes
55pub const APPROX_SIZE_OF_OWNER: usize = 48;
56
57/// The response from processing a transaction or a certified transaction
58#[enum_dispatch(TransactionEffectsAPI)]
59#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize)]
60#[allow(clippy::large_enum_variant)]
61pub enum TransactionEffects {
62    V1(TransactionEffectsV1),
63    V2(TransactionEffectsV2),
64}
65
66impl Message for TransactionEffects {
67    type DigestType = TransactionEffectsDigest;
68    const SCOPE: IntentScope = IntentScope::TransactionEffects;
69
70    fn digest(&self) -> Self::DigestType {
71        TransactionEffectsDigest::new(default_hash(self))
72    }
73}
74
75// TODO: Get rid of this and use TestEffectsBuilder instead.
76impl Default for TransactionEffects {
77    fn default() -> Self {
78        TransactionEffects::V2(Default::default())
79    }
80}
81
82pub enum ObjectRemoveKind {
83    Delete,
84    Wrap,
85}
86
87impl TransactionEffects {
88    /// Creates a TransactionEffects message from the results of execution, choosing the correct
89    /// format for the current protocol version.
90    pub fn new_from_execution_v1(
91        status: ExecutionStatus,
92        executed_epoch: EpochId,
93        gas_used: GasCostSummary,
94        modified_at_versions: Vec<(ObjectID, SequenceNumber)>,
95        shared_objects: Vec<ObjectRef>,
96        transaction_digest: TransactionDigest,
97        created: Vec<(ObjectRef, Owner)>,
98        mutated: Vec<(ObjectRef, Owner)>,
99        unwrapped: Vec<(ObjectRef, Owner)>,
100        deleted: Vec<ObjectRef>,
101        unwrapped_then_deleted: Vec<ObjectRef>,
102        wrapped: Vec<ObjectRef>,
103        gas_object: (ObjectRef, Owner),
104        events_digest: Option<TransactionEventsDigest>,
105        dependencies: Vec<TransactionDigest>,
106    ) -> Self {
107        Self::V1(TransactionEffectsV1::new(
108            status,
109            executed_epoch,
110            gas_used,
111            modified_at_versions,
112            shared_objects,
113            transaction_digest,
114            created,
115            mutated,
116            unwrapped,
117            deleted,
118            unwrapped_then_deleted,
119            wrapped,
120            gas_object,
121            events_digest,
122            dependencies,
123        ))
124    }
125
126    /// Creates a TransactionEffects message from the results of execution, choosing the correct
127    /// format for the current protocol version.
128    pub fn new_from_execution_v2(
129        status: ExecutionStatus,
130        executed_epoch: EpochId,
131        gas_used: GasCostSummary,
132        shared_objects: Vec<SharedInput>,
133        loaded_per_epoch_config_objects: BTreeSet<ObjectID>,
134        transaction_digest: TransactionDigest,
135        lamport_version: SequenceNumber,
136        changed_objects: BTreeMap<ObjectID, EffectsObjectChange>,
137        gas_object: Option<ObjectID>,
138        events_digest: Option<TransactionEventsDigest>,
139        dependencies: Vec<TransactionDigest>,
140    ) -> Self {
141        Self::V2(TransactionEffectsV2::new(
142            status,
143            executed_epoch,
144            gas_used,
145            shared_objects,
146            loaded_per_epoch_config_objects,
147            transaction_digest,
148            lamport_version,
149            changed_objects,
150            gas_object,
151            events_digest,
152            dependencies,
153        ))
154    }
155
156    pub fn execution_digests(&self) -> ExecutionDigests {
157        ExecutionDigests {
158            transaction: *self.transaction_digest(),
159            effects: self.digest(),
160        }
161    }
162
163    pub fn estimate_effects_size_upperbound_v1(
164        num_writes: usize,
165        num_mutables: usize,
166        num_deletes: usize,
167        num_deps: usize,
168    ) -> usize {
169        let fixed_sizes = APPROX_SIZE_OF_EXECUTION_STATUS
170            + APPROX_SIZE_OF_EPOCH_ID
171            + APPROX_SIZE_OF_GAS_COST_SUMMARY
172            + APPROX_SIZE_OF_OPT_TX_EVENTS_DIGEST;
173
174        // Each write or delete contributes at roughly this amount because:
175        // Each write can be a mutation which can show up in `mutated` and `modified_at_versions`
176        // `num_delete` is added for padding
177        let approx_change_entry_size = 1_000
178            + (APPROX_SIZE_OF_OWNER + APPROX_SIZE_OF_OBJECT_REF) * num_writes
179            + (APPROX_SIZE_OF_OBJECT_REF * num_mutables)
180            + (APPROX_SIZE_OF_OBJECT_REF * num_deletes);
181
182        let deps_size = 1_000 + APPROX_SIZE_OF_TX_DIGEST * num_deps;
183
184        fixed_sizes + approx_change_entry_size + deps_size
185    }
186
187    pub fn estimate_effects_size_upperbound_v2(
188        num_writes: usize,
189        num_modifies: usize,
190        num_deps: usize,
191    ) -> usize {
192        let fixed_sizes = APPROX_SIZE_OF_EXECUTION_STATUS
193            + APPROX_SIZE_OF_EPOCH_ID
194            + APPROX_SIZE_OF_GAS_COST_SUMMARY
195            + APPROX_SIZE_OF_OPT_TX_EVENTS_DIGEST;
196
197        // We store object ref and owner for both old objects and new objects.
198        let approx_change_entry_size = 1_000
199            + (APPROX_SIZE_OF_OWNER + APPROX_SIZE_OF_OBJECT_REF) * num_writes
200            + (APPROX_SIZE_OF_OWNER + APPROX_SIZE_OF_OBJECT_REF) * num_modifies;
201
202        let deps_size = 1_000 + APPROX_SIZE_OF_TX_DIGEST * num_deps;
203
204        fixed_sizes + approx_change_entry_size + deps_size
205    }
206
207    /// Return an iterator that iterates through all changed objects, including mutated,
208    /// created and unwrapped objects. In other words, all objects that still exist
209    /// in the object state after this transaction.
210    /// It doesn't include deleted/wrapped objects.
211    pub fn all_changed_objects(&self) -> Vec<(ObjectRef, Owner, WriteKind)> {
212        self.mutated()
213            .into_iter()
214            .map(|(r, o)| (r, o, WriteKind::Mutate))
215            .chain(
216                self.created()
217                    .into_iter()
218                    .map(|(r, o)| (r, o, WriteKind::Create)),
219            )
220            .chain(
221                self.unwrapped()
222                    .into_iter()
223                    .map(|(r, o)| (r, o, WriteKind::Unwrap)),
224            )
225            .collect()
226    }
227
228    /// Return all objects that existed in the state prior to the transaction
229    /// but no longer exist in the state after the transaction.
230    /// It includes deleted and wrapped objects, but does not include unwrapped_then_deleted objects.
231    pub fn all_removed_objects(&self) -> Vec<(ObjectRef, ObjectRemoveKind)> {
232        self.deleted()
233            .iter()
234            .map(|obj_ref| (*obj_ref, ObjectRemoveKind::Delete))
235            .chain(
236                self.wrapped()
237                    .iter()
238                    .map(|obj_ref| (*obj_ref, ObjectRemoveKind::Wrap)),
239            )
240            .collect()
241    }
242
243    /// Returns all objects that will become a tombstone after this transaction.
244    /// This includes deleted, unwrapped_then_deleted and wrapped objects.
245    pub fn all_tombstones(&self) -> Vec<(ObjectID, SequenceNumber)> {
246        self.deleted()
247            .into_iter()
248            .chain(self.unwrapped_then_deleted())
249            .chain(self.wrapped())
250            .map(|obj_ref| (obj_ref.0, obj_ref.1))
251            .collect()
252    }
253
254    /// Return an iterator of mutated objects, but excluding the gas object.
255    pub fn mutated_excluding_gas(&self) -> Vec<(ObjectRef, Owner)> {
256        self.mutated()
257            .into_iter()
258            .filter(|o| o != &self.gas_object())
259            .collect()
260    }
261
262    pub fn summary_for_debug(&self) -> TransactionEffectsDebugSummary {
263        TransactionEffectsDebugSummary {
264            bcs_size: bcs::serialized_size(self).unwrap(),
265            status: self.status().clone(),
266            gas_used: self.gas_cost_summary().clone(),
267            transaction_digest: *self.transaction_digest(),
268            created_object_count: self.created().len(),
269            mutated_object_count: self.mutated().len(),
270            unwrapped_object_count: self.unwrapped().len(),
271            deleted_object_count: self.deleted().len(),
272            wrapped_object_count: self.wrapped().len(),
273            dependency_count: self.dependencies().len(),
274        }
275    }
276}
277
278#[derive(Eq, PartialEq, Clone, Debug)]
279pub enum InputConsensusObject {
280    Mutate(ObjectRef),
281    ReadOnly(ObjectRef),
282    ReadConsensusStreamEnded(ObjectID, SequenceNumber),
283    MutateConsensusStreamEnded(ObjectID, SequenceNumber),
284    Cancelled(ObjectID, SequenceNumber),
285}
286
287impl InputConsensusObject {
288    pub fn id_and_version(&self) -> (ObjectID, SequenceNumber) {
289        match self {
290            InputConsensusObject::Mutate(oref) | InputConsensusObject::ReadOnly(oref) => {
291                (oref.0, oref.1)
292            }
293            InputConsensusObject::ReadConsensusStreamEnded(id, version)
294            | InputConsensusObject::MutateConsensusStreamEnded(id, version) => (*id, *version),
295            InputConsensusObject::Cancelled(id, version) => (*id, *version),
296        }
297    }
298
299    // NOTE: When `ObjectDigest::OBJECT_DIGEST_DELETED` is returned, the object's consensus stream
300    // has ended, but it may not be deleted.
301    #[deprecated]
302    pub fn object_ref(&self) -> ObjectRef {
303        match self {
304            InputConsensusObject::Mutate(oref) | InputConsensusObject::ReadOnly(oref) => *oref,
305            InputConsensusObject::ReadConsensusStreamEnded(id, version)
306            | InputConsensusObject::MutateConsensusStreamEnded(id, version) => {
307                (*id, *version, ObjectDigest::OBJECT_DIGEST_DELETED)
308            }
309            InputConsensusObject::Cancelled(id, version) => {
310                (*id, *version, ObjectDigest::OBJECT_DIGEST_CANCELLED)
311            }
312        }
313    }
314}
315
316#[enum_dispatch]
317pub trait TransactionEffectsAPI {
318    fn status(&self) -> &ExecutionStatus;
319    fn into_status(self) -> ExecutionStatus;
320    fn executed_epoch(&self) -> EpochId;
321    fn modified_at_versions(&self) -> Vec<(ObjectID, SequenceNumber)>;
322    fn move_abort(&self) -> Option<(MoveLocation, u64)>;
323
324    /// The version assigned to all output objects (apart from packages).
325    fn lamport_version(&self) -> SequenceNumber;
326
327    /// Metadata of objects prior to modification. This includes any object that exists in the
328    /// store prior to this transaction and is modified in this transaction.
329    /// It includes objects that are mutated, wrapped and deleted.
330    /// This API is only available on effects v2 and above.
331    fn old_object_metadata(&self) -> Vec<(ObjectRef, Owner)>;
332    /// Returns the list of sequenced consensus objects used in the input.
333    /// This is needed in effects because in transaction we only have object ID
334    /// for consensus objects. Their version and digest can only be figured out after sequencing.
335    /// Also provides the use kind to indicate whether the object was mutated or read-only.
336    /// It does not include per epoch config objects since they do not require sequencing.
337    fn input_consensus_objects(&self) -> Vec<InputConsensusObject>;
338    fn created(&self) -> Vec<(ObjectRef, Owner)>;
339    fn mutated(&self) -> Vec<(ObjectRef, Owner)>;
340    fn unwrapped(&self) -> Vec<(ObjectRef, Owner)>;
341    fn deleted(&self) -> Vec<ObjectRef>;
342    fn unwrapped_then_deleted(&self) -> Vec<ObjectRef>;
343    fn wrapped(&self) -> Vec<ObjectRef>;
344    fn transferred_from_consensus(&self) -> Vec<ObjectRef>;
345    fn transferred_to_consensus(&self) -> Vec<ObjectRef>;
346    fn consensus_owner_changed(&self) -> Vec<ObjectRef>;
347
348    fn object_changes(&self) -> Vec<ObjectChange>;
349    fn published_packages(&self) -> Vec<ObjectID>;
350
351    /// The set of object refs written by this transaction, including deleted and wrapped objects.
352    /// Unlike object_changes(), returns no information about the starting state of the object.
353    fn written(&self) -> Vec<ObjectRef>;
354
355    fn accumulator_events(&self) -> Vec<AccumulatorEvent>;
356
357    // TODO: We should consider having this function to return Option.
358    // When the gas object is not available (i.e. system transaction), we currently return
359    // dummy object ref and owner. This is not ideal.
360    fn gas_object(&self) -> (ObjectRef, Owner);
361
362    fn events_digest(&self) -> Option<&TransactionEventsDigest>;
363    fn dependencies(&self) -> &[TransactionDigest];
364
365    fn transaction_digest(&self) -> &TransactionDigest;
366
367    fn gas_cost_summary(&self) -> &GasCostSummary;
368
369    fn stream_ended_mutably_accessed_consensus_objects(&self) -> Vec<ObjectID> {
370        self.input_consensus_objects()
371            .into_iter()
372            .filter_map(|kind| match kind {
373                InputConsensusObject::MutateConsensusStreamEnded(id, _) => Some(id),
374                InputConsensusObject::Mutate(..)
375                | InputConsensusObject::ReadOnly(..)
376                | InputConsensusObject::ReadConsensusStreamEnded(..)
377                | InputConsensusObject::Cancelled(..) => None,
378            })
379            .collect()
380    }
381
382    /// Returns all root consensus objects (i.e. not child object) that are read-only in the transaction.
383    fn unchanged_consensus_objects(&self) -> Vec<(ObjectID, UnchangedConsensusKind)>;
384
385    /// Returns all accumulator updates in the transaction.
386    fn accumulator_updates(&self) -> Vec<(ObjectID, AccumulatorWriteV1)>;
387
388    // All of these should be #[cfg(test)], but they are used by tests in other crates, and
389    // dependencies don't get built with cfg(test) set as far as I can tell.
390    fn status_mut_for_testing(&mut self) -> &mut ExecutionStatus;
391    fn gas_cost_summary_mut_for_testing(&mut self) -> &mut GasCostSummary;
392    fn transaction_digest_mut_for_testing(&mut self) -> &mut TransactionDigest;
393    fn dependencies_mut_for_testing(&mut self) -> &mut Vec<TransactionDigest>;
394    fn unsafe_add_input_consensus_object_for_testing(&mut self, kind: InputConsensusObject);
395
396    // Adding an old version of a live object.
397    fn unsafe_add_deleted_live_object_for_testing(&mut self, obj_ref: ObjectRef);
398
399    // Adding a tombstone for a deleted object.
400    fn unsafe_add_object_tombstone_for_testing(&mut self, obj_ref: ObjectRef);
401}
402
403#[derive(Clone, Debug)]
404pub struct ObjectChange {
405    pub id: ObjectID,
406    pub input_version: Option<SequenceNumber>,
407    pub input_digest: Option<ObjectDigest>,
408    pub output_version: Option<SequenceNumber>,
409    pub output_digest: Option<ObjectDigest>,
410    pub id_operation: IDOperation,
411}
412
413#[derive(Eq, PartialEq, Copy, Clone, Debug, Serialize, Deserialize)]
414pub enum IDOperation {
415    None,
416    Created,
417    Deleted,
418}
419
420#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize, Default)]
421pub struct TransactionEvents {
422    pub data: Vec<Event>,
423}
424
425impl TransactionEvents {
426    pub fn digest(&self) -> TransactionEventsDigest {
427        TransactionEventsDigest::new(default_hash(self))
428    }
429}
430
431#[derive(Debug)]
432pub struct TransactionEffectsDebugSummary {
433    /// Size of bcs serialized byets of the effects.
434    pub bcs_size: usize,
435    pub status: ExecutionStatus,
436    pub gas_used: GasCostSummary,
437    pub transaction_digest: TransactionDigest,
438    pub created_object_count: usize,
439    pub mutated_object_count: usize,
440    pub unwrapped_object_count: usize,
441    pub deleted_object_count: usize,
442    pub wrapped_object_count: usize,
443    pub dependency_count: usize,
444    // TODO: Add deleted_and_unwrapped_object_count and event digest.
445}
446
447pub type TransactionEffectsEnvelope<S> = Envelope<TransactionEffects, S>;
448pub type UnsignedTransactionEffects = TransactionEffectsEnvelope<EmptySignInfo>;
449pub type SignedTransactionEffects = TransactionEffectsEnvelope<AuthoritySignInfo>;
450pub type CertifiedTransactionEffects = TransactionEffectsEnvelope<AuthorityStrongQuorumSignInfo>;
451
452pub type TrustedSignedTransactionEffects = TrustedEnvelope<TransactionEffects, AuthoritySignInfo>;
453pub type VerifiedTransactionEffectsEnvelope<S> = VerifiedEnvelope<TransactionEffects, S>;
454pub type VerifiedSignedTransactionEffects = VerifiedTransactionEffectsEnvelope<AuthoritySignInfo>;
455pub type VerifiedCertifiedTransactionEffects =
456    VerifiedTransactionEffectsEnvelope<AuthorityStrongQuorumSignInfo>;
457
458impl CertifiedTransactionEffects {
459    pub fn verify_authority_signatures(&self, committee: &Committee) -> SuiResult {
460        self.auth_sig().verify_secure(
461            self.data(),
462            Intent::sui_app(IntentScope::TransactionEffects),
463            committee,
464        )
465    }
466
467    pub fn verify(self, committee: &Committee) -> SuiResult<VerifiedCertifiedTransactionEffects> {
468        self.verify_authority_signatures(committee)?;
469        Ok(VerifiedCertifiedTransactionEffects::new_from_verified(self))
470    }
471}
472
473#[cfg(test)]
474#[path = "../unit_tests/effects_tests.rs"]
475mod effects_tests;
sui_types/effects/mod.rs

sui_types/effects/
mod.rs
