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
350    /// The set of object refs written by this transaction, including deleted and wrapped objects.
351    /// Unlike object_changes(), returns no information about the starting state of the object.
352    fn written(&self) -> Vec<ObjectRef>;
353
354    fn accumulator_events(&self) -> Vec<AccumulatorEvent>;
355
356    // TODO: We should consider having this function to return Option.
357    // When the gas object is not available (i.e. system transaction), we currently return
358    // dummy object ref and owner. This is not ideal.
359    fn gas_object(&self) -> (ObjectRef, Owner);
360
361    fn events_digest(&self) -> Option<&TransactionEventsDigest>;
362    fn dependencies(&self) -> &[TransactionDigest];
363
364    fn transaction_digest(&self) -> &TransactionDigest;
365
366    fn gas_cost_summary(&self) -> &GasCostSummary;
367
368    fn stream_ended_mutably_accessed_consensus_objects(&self) -> Vec<ObjectID> {
369        self.input_consensus_objects()
370            .into_iter()
371            .filter_map(|kind| match kind {
372                InputConsensusObject::MutateConsensusStreamEnded(id, _) => Some(id),
373                InputConsensusObject::Mutate(..)
374                | InputConsensusObject::ReadOnly(..)
375                | InputConsensusObject::ReadConsensusStreamEnded(..)
376                | InputConsensusObject::Cancelled(..) => None,
377            })
378            .collect()
379    }
380
381    /// Returns all root consensus objects (i.e. not child object) that are read-only in the transaction.
382    fn unchanged_consensus_objects(&self) -> Vec<(ObjectID, UnchangedConsensusKind)>;
383
384    /// Returns all accumulator updates in the transaction.
385    fn accumulator_updates(&self) -> Vec<(ObjectID, AccumulatorWriteV1)>;
386
387    // All of these should be #[cfg(test)], but they are used by tests in other crates, and
388    // dependencies don't get built with cfg(test) set as far as I can tell.
389    fn status_mut_for_testing(&mut self) -> &mut ExecutionStatus;
390    fn gas_cost_summary_mut_for_testing(&mut self) -> &mut GasCostSummary;
391    fn transaction_digest_mut_for_testing(&mut self) -> &mut TransactionDigest;
392    fn dependencies_mut_for_testing(&mut self) -> &mut Vec<TransactionDigest>;
393    fn unsafe_add_input_consensus_object_for_testing(&mut self, kind: InputConsensusObject);
394
395    // Adding an old version of a live object.
396    fn unsafe_add_deleted_live_object_for_testing(&mut self, obj_ref: ObjectRef);
397
398    // Adding a tombstone for a deleted object.
399    fn unsafe_add_object_tombstone_for_testing(&mut self, obj_ref: ObjectRef);
400}
401
402#[derive(Clone, Debug)]
403pub struct ObjectChange {
404    pub id: ObjectID,
405    pub input_version: Option<SequenceNumber>,
406    pub input_digest: Option<ObjectDigest>,
407    pub output_version: Option<SequenceNumber>,
408    pub output_digest: Option<ObjectDigest>,
409    pub id_operation: IDOperation,
410}
411
412#[derive(Eq, PartialEq, Copy, Clone, Debug, Serialize, Deserialize)]
413pub enum IDOperation {
414    None,
415    Created,
416    Deleted,
417}
418
419#[derive(Eq, PartialEq, Clone, Debug, Serialize, Deserialize, Default)]
420pub struct TransactionEvents {
421    pub data: Vec<Event>,
422}
423
424impl TransactionEvents {
425    pub fn digest(&self) -> TransactionEventsDigest {
426        TransactionEventsDigest::new(default_hash(self))
427    }
428}
429
430#[derive(Debug)]
431pub struct TransactionEffectsDebugSummary {
432    /// Size of bcs serialized byets of the effects.
433    pub bcs_size: usize,
434    pub status: ExecutionStatus,
435    pub gas_used: GasCostSummary,
436    pub transaction_digest: TransactionDigest,
437    pub created_object_count: usize,
438    pub mutated_object_count: usize,
439    pub unwrapped_object_count: usize,
440    pub deleted_object_count: usize,
441    pub wrapped_object_count: usize,
442    pub dependency_count: usize,
443    // TODO: Add deleted_and_unwrapped_object_count and event digest.
444}
445
446pub type TransactionEffectsEnvelope<S> = Envelope<TransactionEffects, S>;
447pub type UnsignedTransactionEffects = TransactionEffectsEnvelope<EmptySignInfo>;
448pub type SignedTransactionEffects = TransactionEffectsEnvelope<AuthoritySignInfo>;
449pub type CertifiedTransactionEffects = TransactionEffectsEnvelope<AuthorityStrongQuorumSignInfo>;
450
451pub type TrustedSignedTransactionEffects = TrustedEnvelope<TransactionEffects, AuthoritySignInfo>;
452pub type VerifiedTransactionEffectsEnvelope<S> = VerifiedEnvelope<TransactionEffects, S>;
453pub type VerifiedSignedTransactionEffects = VerifiedTransactionEffectsEnvelope<AuthoritySignInfo>;
454pub type VerifiedCertifiedTransactionEffects =
455    VerifiedTransactionEffectsEnvelope<AuthorityStrongQuorumSignInfo>;
456
457impl CertifiedTransactionEffects {
458    pub fn verify_authority_signatures(&self, committee: &Committee) -> SuiResult {
459        self.auth_sig().verify_secure(
460            self.data(),
461            Intent::sui_app(IntentScope::TransactionEffects),
462            committee,
463        )
464    }
465
466    pub fn verify(self, committee: &Committee) -> SuiResult<VerifiedCertifiedTransactionEffects> {
467        self.verify_authority_signatures(committee)?;
468        Ok(VerifiedCertifiedTransactionEffects::new_from_verified(self))
469    }
470}
471
472#[cfg(test)]
473#[path = "../unit_tests/effects_tests.rs"]
474mod effects_tests;
sui_types/effects/mod.rs

sui_types/effects/
mod.rs
