Skip to main content

iota_types/
test_checkpoint_data_builder.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2025 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::collections::{BTreeMap, BTreeSet, HashMap};
6
7use iota_protocol_config::ProtocolConfig;
8use iota_sdk_move_types::iota_system::iota_system_state_inner::SystemEpochInfoEventV2;
9use iota_sdk_types::{
10    Address, CheckpointContents, CheckpointSummary, EndOfEpochData, EndOfEpochTransactionKind,
11    Event, Identifier, MoveStruct, ObjectId, ObjectReference, Owner, SenderSignedTransaction,
12    SharedObjectReference, StructTag, Transaction, TransactionDigest, TransactionEffects,
13    TransactionEvents, TransactionKind, TypeTag, Version,
14};
15use tap::Pipe;
16
17use crate::{
18    base_types::{ExecutionDigests, dbg_addr, random_object_ref},
19    committee::Committee,
20    effects::{TestEffectsBuilder, TransactionEffectsAPI, TransactionEffectsExtForTesting},
21    full_checkpoint_content::{CheckpointData, CheckpointTransaction},
22    messages_checkpoint::{
23        CertifiedCheckpointSummary, CheckpointContentsExt, CheckpointSummaryExt,
24    },
25    object::{GAS_VALUE_FOR_TESTING, MoveStructExt, Object},
26    programmable_transaction_builder::ProgrammableTransactionBuilder,
27    transaction::{CallArg, TransactionAPI, TransactionEnvelope},
28};
29
30/// A builder for creating test checkpoint data.
31/// Once initialized, the builder can be used to build multiple checkpoints.
32/// Call `start_transaction` to begin creating a new transaction.
33/// Call `finish_transaction` to complete the current transaction and add it to
34/// the current checkpoint. After all transactions are added, call
35/// `build_checkpoint` to get the final checkpoint data. This will also
36/// increment the stored checkpoint sequence number. Start the above process
37/// again to build the next checkpoint. NOTE: The generated checkpoint data is
38/// not guaranteed to be semantically valid or consistent. For instance, all
39/// object digests will be randomly set. It focuses on providing a way to
40/// generate various shaped test data for testing purposes.
41/// If you need to test the validity of the checkpoint data, you should use
42/// Simulacrum instead.
43pub struct TestCheckpointDataBuilder {
44    /// Map of all live objects in the state.
45    live_objects: HashMap<ObjectId, Object>,
46    /// Map of all wrapped objects in the state.
47    wrapped_objects: HashMap<ObjectId, Object>,
48    /// A map from sender addresses to gas objects they own.
49    /// These are created automatically when a transaction is started.
50    /// Users of this builder should not need to worry about them.
51    gas_map: HashMap<Address, ObjectId>,
52
53    /// The current checkpoint builder.
54    /// It is initialized when the builder is created, and is reset when
55    /// `build_checkpoint` is called.
56    checkpoint_builder: CheckpointBuilder,
57}
58
59struct CheckpointBuilder {
60    /// Checkpoint number for the current checkpoint we are building.
61    checkpoint: u64,
62    /// Epoch number for the current checkpoint we are building.
63    epoch: u64,
64    /// Counter for the total number of transactions added to the builder.
65    network_total_transactions: u64,
66    /// Transactions that have been added to the current checkpoint.
67    transactions: Vec<CheckpointTransaction>,
68    /// The current transaction being built.
69    next_transaction: Option<TransactionBuilder>,
70}
71
72struct TransactionBuilder {
73    sender_idx: u8,
74    gas: ObjectReference,
75    move_calls: Vec<(ObjectId, &'static str, &'static str)>,
76    created_objects: BTreeMap<ObjectId, Object>,
77    mutated_objects: BTreeMap<ObjectId, Object>,
78    unwrapped_objects: BTreeSet<ObjectId>,
79    wrapped_objects: BTreeSet<ObjectId>,
80    deleted_objects: BTreeSet<ObjectId>,
81    frozen_objects: BTreeSet<ObjectReference>,
82    shared_inputs: BTreeMap<ObjectId, Shared>,
83    events: Option<Vec<Event>>,
84}
85
86struct Shared {
87    mutable: bool,
88    object: Object,
89}
90
91impl TransactionBuilder {
92    pub fn new(sender_idx: u8, gas: ObjectReference) -> Self {
93        Self {
94            sender_idx,
95            gas,
96            move_calls: vec![],
97            created_objects: BTreeMap::new(),
98            mutated_objects: BTreeMap::new(),
99            unwrapped_objects: BTreeSet::new(),
100            wrapped_objects: BTreeSet::new(),
101            deleted_objects: BTreeSet::new(),
102            frozen_objects: BTreeSet::new(),
103            shared_inputs: BTreeMap::new(),
104            events: None,
105        }
106    }
107}
108
109impl TestCheckpointDataBuilder {
110    pub fn new(checkpoint: u64) -> Self {
111        Self {
112            live_objects: HashMap::new(),
113            wrapped_objects: HashMap::new(),
114            gas_map: HashMap::new(),
115            checkpoint_builder: CheckpointBuilder {
116                checkpoint,
117                epoch: 0,
118                network_total_transactions: 0,
119                transactions: vec![],
120                next_transaction: None,
121            },
122        }
123    }
124
125    /// Set the epoch for the checkpoint.
126    pub fn with_epoch(mut self, epoch: u64) -> Self {
127        self.checkpoint_builder.epoch = epoch;
128        self
129    }
130
131    /// Start creating a new transaction.
132    /// `sender_idx` is a convenient representation of the sender's address.
133    /// A proper Address will be derived from it.
134    /// It will also create a gas object for the sender if it doesn't already
135    /// exist in the live object map. You do not need to create the gas
136    /// object yourself.
137    pub fn start_transaction(mut self, sender_idx: u8) -> Self {
138        assert!(self.checkpoint_builder.next_transaction.is_none());
139        let sender = Self::derive_address(sender_idx);
140        let gas_id = self.gas_map.entry(sender).or_insert_with(|| {
141            let gas = Object::with_owner_for_testing(sender);
142            let id = gas.id();
143            self.live_objects.insert(id, gas);
144            id
145        });
146        let gas_ref = self.live_objects.get(gas_id).cloned().unwrap().object_ref();
147        self.checkpoint_builder.next_transaction =
148            Some(TransactionBuilder::new(sender_idx, gas_ref));
149        self
150    }
151
152    /// Create a new object in the transaction.
153    /// `object_idx` is a convenient representation of the object's ID.
154    /// The object will be created as a IOTA coin object, with default balance,
155    /// and the transaction sender as its owner.
156    pub fn create_owned_object(self, object_idx: u64) -> Self {
157        self.create_iota_object(object_idx, GAS_VALUE_FOR_TESTING)
158    }
159
160    /// Create a new shared object in the transaction.
161    /// `object_idx` is a convenient representation of the object's ID.
162    /// The object will be created as a IOTA coin object, with default balance,
163    /// and it is a shared object.
164    pub fn create_shared_object(self, object_idx: u64) -> Self {
165        self.create_coin_object_with_owner(
166            object_idx,
167            Owner::Shared(Version::MIN_VALID_INCL),
168            GAS_VALUE_FOR_TESTING,
169            TypeTag::from(StructTag::new_gas()),
170        )
171    }
172
173    /// Create a new IOTA coin object in the transaction.
174    /// `object_idx` is a convenient representation of the object's ID.
175    /// `balance` is the amount of IOTA to be created.
176    pub fn create_iota_object(self, object_idx: u64, balance: u64) -> Self {
177        let sender_idx = self
178            .checkpoint_builder
179            .next_transaction
180            .as_ref()
181            .unwrap()
182            .sender_idx;
183        self.create_coin_object(
184            object_idx,
185            sender_idx,
186            balance,
187            TypeTag::from(StructTag::new_gas()),
188        )
189    }
190
191    /// Create a new coin object in the transaction.
192    /// `object_idx` is a convenient representation of the object's ID.
193    /// `owner_idx` is a convenient representation of the object's owner's
194    /// address. `balance` is the amount of IOTA to be created.
195    /// `coin_type` is the type of the coin to be created.
196    pub fn create_coin_object(
197        self,
198        object_idx: u64,
199        owner_idx: u8,
200        balance: u64,
201        coin_type: TypeTag,
202    ) -> Self {
203        self.create_coin_object_with_owner(
204            object_idx,
205            Owner::Address(Self::derive_address(owner_idx)),
206            balance,
207            coin_type,
208        )
209    }
210
211    fn create_coin_object_with_owner(
212        mut self,
213        object_idx: u64,
214        owner: Owner,
215        balance: u64,
216        coin_type: TypeTag,
217    ) -> Self {
218        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
219        let object_id = Self::derive_object_id(object_idx);
220        assert!(
221            !self.live_objects.contains_key(&object_id),
222            "Object already exists: {object_id}. Please use a different object index.",
223        );
224        let move_struct = MoveStruct::new_coin(
225            coin_type,
226            // version doesn't matter since we will set it to the lamport version when we finalize
227            // the transaction
228            Version::MIN_VALID_INCL,
229            object_id,
230            balance,
231        );
232        let object = Object::new_move(move_struct, owner, TransactionDigest::ZERO);
233        tx_builder.created_objects.insert(object_id, object);
234        self
235    }
236
237    /// Mutate an existing owned object in the transaction.
238    /// `object_idx` is a convenient representation of the object's ID.
239    pub fn mutate_owned_object(mut self, object_idx: u64) -> Self {
240        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
241        let object_id = Self::derive_object_id(object_idx);
242        let object = self
243            .live_objects
244            .get(&object_id)
245            .cloned()
246            .expect("Mutating an object that doesn't exist");
247        tx_builder.mutated_objects.insert(object_id, object);
248        self
249    }
250
251    /// Mutate an existing shared object in the transaction.
252    pub fn mutate_shared_object(self, object_idx: u64) -> Self {
253        self.access_shared_object(object_idx, true)
254    }
255
256    /// Transfer an existing object to a new owner.
257    /// `object_idx` is a convenient representation of the object's ID.
258    /// `recipient_idx` is a convenient representation of the recipient's
259    /// address.
260    pub fn transfer_object(self, object_idx: u64, recipient_idx: u8) -> Self {
261        self.change_object_owner(
262            object_idx,
263            Owner::Address(Self::derive_address(recipient_idx)),
264        )
265    }
266
267    /// Change the owner of an existing object.
268    /// `object_idx` is a convenient representation of the object's ID.
269    /// `owner` is the new owner of the object.
270    pub fn change_object_owner(mut self, object_idx: u64, owner: Owner) -> Self {
271        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
272        let object_id = Self::derive_object_id(object_idx);
273        let mut object = self.live_objects.get(&object_id).unwrap().clone();
274        object.owner = owner;
275        tx_builder.mutated_objects.insert(object_id, object);
276        self
277    }
278
279    /// Transfer part of an existing coin object's balance to a new owner.
280    /// `object_idx` is a convenient representation of the object's ID.
281    /// `new_object_idx` is a convenient representation of the new object's ID.
282    /// `recipient_idx` is a convenient representation of the recipient's
283    /// address. `amount` is the amount of balance to be transferred.
284    pub fn transfer_coin_balance(
285        mut self,
286        object_idx: u64,
287        new_object_idx: u64,
288        recipient_idx: u8,
289        amount: u64,
290    ) -> Self {
291        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
292        let object_id = Self::derive_object_id(object_idx);
293        let mut object = self
294            .live_objects
295            .get(&object_id)
296            .cloned()
297            .expect("Mutating an object that does not exist");
298        let coin_type = object.opt_coin_type().cloned().unwrap();
299        // Withdraw balance from coin object.
300        let move_object = object.data.as_opt_mut_struct().unwrap();
301        let old_balance = move_object.get_coin_value_unchecked();
302        let new_balance = old_balance - amount;
303        move_object.set_coin_value_unchecked(new_balance);
304        tx_builder.mutated_objects.insert(object_id, object);
305
306        // Deposit balance into new coin object.
307        self.create_coin_object(new_object_idx, recipient_idx, amount, coin_type)
308    }
309
310    /// Wrap an existing object in the transaction.
311    /// `object_idx` is a convenient representation of the object's ID.
312    pub fn wrap_object(mut self, object_idx: u64) -> Self {
313        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
314        let object_id = Self::derive_object_id(object_idx);
315        assert!(self.live_objects.contains_key(&object_id));
316        tx_builder.wrapped_objects.insert(object_id);
317        self
318    }
319
320    /// Unwrap an existing object from the transaction.
321    /// `object_idx` is a convenient representation of the object's ID.
322    pub fn unwrap_object(mut self, object_idx: u64) -> Self {
323        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
324        let object_id = Self::derive_object_id(object_idx);
325        assert!(self.wrapped_objects.contains_key(&object_id));
326        tx_builder.unwrapped_objects.insert(object_id);
327        self
328    }
329
330    /// Delete an existing object from the transaction.
331    /// `object_idx` is a convenient representation of the object's ID.
332    pub fn delete_object(mut self, object_idx: u64) -> Self {
333        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
334        let object_id = Self::derive_object_id(object_idx);
335        assert!(self.live_objects.contains_key(&object_id));
336        tx_builder.deleted_objects.insert(object_id);
337        self
338    }
339
340    /// Add an immutable object as an input to the transaction.
341    ///
342    /// Fails if the object is not live or if its owner is not
343    /// [Owner::Immutable]).
344    pub fn read_frozen_object(mut self, object_id: u64) -> Self {
345        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
346        let object_id = Self::derive_object_id(object_id);
347
348        let obj = self
349            .live_objects
350            .get(&object_id)
351            .expect("Frozen object not found");
352
353        assert!(obj.owner().is_immutable());
354        tx_builder.frozen_objects.insert(obj.object_ref());
355        self
356    }
357
358    /// Add a read to a shared object to the transaction's effects.
359    pub fn read_shared_object(self, object_idx: u64) -> Self {
360        self.access_shared_object(object_idx, false)
361    }
362
363    /// Add events to the transaction.
364    /// `events` is a vector of events to be added to the transaction.
365    pub fn with_events(mut self, events: Vec<Event>) -> Self {
366        self.checkpoint_builder
367            .next_transaction
368            .as_mut()
369            .unwrap()
370            .events = Some(events);
371        self
372    }
373
374    /// Add a move call PTB command to the transaction.
375    /// `package` is the ID of the package to be called.
376    /// `module` is the name of the module to be called.
377    /// `function` is the name of the function to be called.
378    pub fn add_move_call(
379        mut self,
380        package: ObjectId,
381        module: &'static str,
382        function: &'static str,
383    ) -> Self {
384        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
385        tx_builder.move_calls.push((package, module, function));
386        self
387    }
388
389    /// Complete the current transaction and add it to the checkpoint.
390    /// This will also finalize all the object changes, and reflect them in the
391    /// live object map.
392    pub fn finish_transaction(mut self) -> Self {
393        let TransactionBuilder {
394            sender_idx,
395            gas,
396            move_calls,
397            created_objects,
398            mutated_objects,
399            unwrapped_objects,
400            wrapped_objects,
401            deleted_objects,
402            frozen_objects,
403            shared_inputs,
404            events,
405        } = self.checkpoint_builder.next_transaction.take().unwrap();
406
407        let sender = Self::derive_address(sender_idx);
408        let events = events.map(TransactionEvents);
409        let events_digest = events.as_ref().map(|events| events.digest());
410
411        let mut pt_builder = ProgrammableTransactionBuilder::new();
412        for (package, module, function) in move_calls {
413            pt_builder
414                .move_call(
415                    package,
416                    Identifier::from_static(module),
417                    Identifier::from_static(function),
418                    vec![],
419                    vec![],
420                )
421                .unwrap();
422        }
423
424        for &object_ref in &frozen_objects {
425            pt_builder
426                .obj(CallArg::ImmutableOrOwned(object_ref))
427                .expect("Failed to add frozen object input");
428        }
429
430        for (id, input) in &shared_inputs {
431            let &Owner::Shared(initial_shared_version) = input.object.owner() else {
432                panic!("Accessing a non-shared object as shared");
433            };
434
435            pt_builder
436                .obj(CallArg::Shared(SharedObjectReference::new(
437                    *id,
438                    initial_shared_version,
439                    input.mutable,
440                )))
441                .expect("Failed to add shared object input");
442        }
443
444        let pt = pt_builder.finish();
445        let tx = Transaction::new(TransactionKind::Programmable(pt), sender, gas, 1, 1);
446        let tx = TransactionEnvelope::new(SenderSignedTransaction::new(tx, vec![]));
447
448        let wrapped_objects: Vec<_> = wrapped_objects
449            .into_iter()
450            .map(|id| self.live_objects.remove(&id).unwrap())
451            .collect();
452        let deleted_objects: Vec<_> = deleted_objects
453            .into_iter()
454            .map(|id| self.live_objects.remove(&id).unwrap())
455            .collect();
456        let unwrapped_objects: Vec<_> = unwrapped_objects
457            .into_iter()
458            .map(|id| self.wrapped_objects.remove(&id).unwrap())
459            .collect();
460
461        let mut effects_builder = TestEffectsBuilder::new(tx.data())
462            .with_created_objects(created_objects.iter().map(|(id, o)| (*id, *o.owner())))
463            .with_mutated_objects(
464                mutated_objects
465                    .iter()
466                    .map(|(id, o)| (*id, o.version(), *o.owner())),
467            )
468            .with_wrapped_objects(wrapped_objects.iter().map(|o| (o.id(), o.version())))
469            .with_unwrapped_objects(unwrapped_objects.iter().map(|o| (o.id(), *o.owner())))
470            .with_deleted_objects(deleted_objects.iter().map(|o| (o.id(), o.version())))
471            .with_frozen_objects(
472                frozen_objects
473                    .into_iter()
474                    .map(|object_ref| object_ref.object_id),
475            )
476            .with_shared_input_versions(
477                shared_inputs
478                    .iter()
479                    .map(|(id, input)| (*id, input.object.version()))
480                    .collect(),
481            );
482
483        if let Some(events_digest) = &events_digest {
484            effects_builder = effects_builder.with_events_digest(*events_digest);
485        }
486
487        let effects = effects_builder.build();
488        let lamport_version = effects.lamport_version();
489        let input_objects: Vec<_> = mutated_objects
490            .keys()
491            .chain(
492                shared_inputs
493                    .iter()
494                    .filter(|(_, i)| i.mutable)
495                    .map(|(id, _)| id),
496            )
497            .map(|id| self.live_objects.get(id).unwrap().clone())
498            .chain(deleted_objects)
499            .chain(wrapped_objects.clone())
500            .chain(std::iter::once(
501                self.live_objects.get(&gas.object_id).unwrap().clone(),
502            ))
503            .collect();
504        let output_objects: Vec<_> = created_objects
505            .values()
506            .cloned()
507            .chain(mutated_objects.values().cloned())
508            .chain(
509                shared_inputs
510                    .values()
511                    .filter(|i| i.mutable)
512                    .map(|i| i.object.clone()),
513            )
514            .chain(unwrapped_objects)
515            .chain(std::iter::once(
516                self.live_objects.get(&gas.object_id).cloned().unwrap(),
517            ))
518            .map(|mut o| {
519                o.data
520                    .as_opt_mut_struct()
521                    .unwrap()
522                    .increment_version_to(lamport_version);
523                o
524            })
525            .collect();
526        self.live_objects
527            .extend(output_objects.iter().map(|o| (o.id(), o.clone())));
528        self.wrapped_objects
529            .extend(wrapped_objects.iter().map(|o| (o.id(), o.clone())));
530
531        self.checkpoint_builder
532            .transactions
533            .push(CheckpointTransaction {
534                transaction: tx,
535                effects,
536                events,
537                input_objects,
538                output_objects,
539            });
540        self
541    }
542
543    /// Creates a transaction that advances the epoch, adds it to the
544    /// checkpoint, and then builds the checkpoint. This increments the
545    /// stored checkpoint sequence number and epoch. If `safe_mode` is true,
546    /// the epoch end transaction will not include the `SystemEpochInfoEvent`.
547    pub fn advance_epoch(&mut self, safe_mode: bool) -> CheckpointData {
548        let (committee, _) = Committee::new_simple_test_committee();
549        let protocol_config = ProtocolConfig::get_for_max_version_UNSAFE();
550        let tx_kind = EndOfEpochTransactionKind::new_change_epoch(
551            self.checkpoint_builder.epoch + 1,
552            protocol_config.version.as_u64(),
553            Default::default(),
554            Default::default(),
555            Default::default(),
556            Default::default(),
557            Default::default(),
558            Default::default(),
559        );
560
561        // TODO: need the system state object wrapper and dynamic field object to
562        // "correctly" mock advancing epoch, at least to satisfy kv_epoch_starts
563        // pipeline.
564        let end_of_epoch_tx = Transaction::new(
565            TransactionKind::EndOfEpoch(vec![tx_kind]),
566            Address::ZERO,
567            random_object_ref(),
568            1,
569            1,
570        )
571        .pipe(|tx| SenderSignedTransaction::new(tx, vec![]))
572        .pipe(TransactionEnvelope::new);
573
574        let events = if !safe_mode {
575            let system_epoch_info_event = SystemEpochInfoEventV2 {
576                epoch: self.checkpoint_builder.epoch,
577                protocol_version: protocol_config.version.as_u64(),
578                total_stake: 0,
579                storage_charge: 0,
580                storage_rebate: 0,
581                storage_fund_balance: 0,
582                total_gas_fees: 0,
583                total_stake_rewards_distributed: 0,
584                burnt_tokens_amount: 0,
585                minted_tokens_amount: 0,
586                tips_amount: 0,
587            };
588            Some(vec![Event {
589                package_id: ObjectId::SYSTEM,
590                module: Identifier::from_static("iota_system_state_inner"),
591                sender: TestCheckpointDataBuilder::derive_address(0),
592                struct_tag: StructTag::new_system_epoch_info_event(),
593                contents: bcs::to_bytes(&system_epoch_info_event).unwrap(),
594            }])
595        } else {
596            None
597        };
598
599        let transaction_events = events.map(TransactionEvents);
600
601        let effects = TransactionEffects::new_empty_v1_for_testing(*end_of_epoch_tx.digest());
602
603        // Similar to calling self.finish_transaction()
604        self.checkpoint_builder
605            .transactions
606            .push(CheckpointTransaction {
607                transaction: end_of_epoch_tx,
608                effects,
609                events: transaction_events,
610                input_objects: vec![],
611                output_objects: vec![],
612            });
613
614        // Call build_checkpoint() to finalize the checkpoint and then populate the
615        // checkpoint with additional end of epoch data.
616        let mut checkpoint = self.build_checkpoint();
617        let end_of_epoch_data = EndOfEpochData {
618            next_epoch_committee: committee.committee_members(),
619            next_epoch_protocol_version: protocol_config.version.as_u64(),
620            epoch_commitments: vec![],
621            // Do not simulate supply changes in tests.
622            epoch_supply_change: 0,
623        };
624        checkpoint.checkpoint_summary.end_of_epoch_data = Some(end_of_epoch_data);
625        self.checkpoint_builder.epoch += 1;
626        checkpoint
627    }
628
629    /// Build the checkpoint data using all the transactions added to the
630    /// builder so far. This will also increment the stored checkpoint
631    /// sequence number.
632    pub fn build_checkpoint(&mut self) -> CheckpointData {
633        assert!(self.checkpoint_builder.next_transaction.is_none());
634        let transactions = std::mem::take(&mut self.checkpoint_builder.transactions);
635        let contents = CheckpointContents::new_with_digests_only_for_tests(
636            transactions
637                .iter()
638                .map(|tx| ExecutionDigests::new(*tx.transaction.digest(), tx.effects.digest())),
639        );
640
641        self.checkpoint_builder.network_total_transactions += transactions.len() as u64;
642
643        let checkpoint_summary = CheckpointSummary::new_with_protocol_config(
644            &ProtocolConfig::get_for_max_version_UNSAFE(),
645            self.checkpoint_builder.epoch,
646            self.checkpoint_builder.checkpoint,
647            self.checkpoint_builder.network_total_transactions,
648            &contents,
649            None,
650            Default::default(),
651            None,
652            0,
653            vec![],
654            vec![],
655            Default::default(),
656        );
657
658        let (committee, keys) = Committee::new_simple_test_committee();
659
660        let checkpoint_cert = CertifiedCheckpointSummary::new_from_keypairs_for_testing(
661            checkpoint_summary,
662            &keys,
663            &committee,
664        );
665
666        self.checkpoint_builder.checkpoint += 1;
667        CheckpointData {
668            checkpoint_summary: checkpoint_cert,
669            checkpoint_contents: contents,
670            transactions,
671        }
672    }
673
674    /// Derive an object ID from an index. This is used to conveniently
675    /// represent an object's ID. We ensure that the bytes of object IDs
676    /// have a stable order that is the same as object_idx.
677    pub fn derive_object_id(object_idx: u64) -> ObjectId {
678        // We achieve this by setting the first 8 bytes of the object ID to the
679        // object_idx.
680        let mut bytes = [0; ObjectId::LENGTH];
681        bytes[0..8].copy_from_slice(&object_idx.to_le_bytes());
682        ObjectId::from_bytes(bytes).unwrap()
683    }
684
685    /// Derive an address from an index.
686    pub fn derive_address(address_idx: u8) -> Address {
687        dbg_addr(address_idx)
688    }
689
690    /// Add a shared input to the transaction, being accessed from the currently
691    /// recorded live version.
692    fn access_shared_object(mut self, object_idx: u64, mutable: bool) -> Self {
693        let tx_builder = self.checkpoint_builder.next_transaction.as_mut().unwrap();
694        let object_id = Self::derive_object_id(object_idx);
695        let object = self
696            .live_objects
697            .get(&object_id)
698            .cloned()
699            .expect("Accessing a shared object that doesn't exist");
700        tx_builder
701            .shared_inputs
702            .insert(object_id, Shared { mutable, object });
703        self
704    }
705}
706
707#[cfg(test)]
708mod tests {
709    use std::str::FromStr;
710
711    use iota_sdk_types::Command;
712
713    use super::*;
714    use crate::{
715        ObjectId,
716        transaction::{TransactionAPI, TransactionKindExt},
717    };
718    #[test]
719    fn test_basic_checkpoint_builder() {
720        // Create a checkpoint with a single transaction that does nothing.
721        let checkpoint = TestCheckpointDataBuilder::new(1)
722            .with_epoch(5)
723            .start_transaction(0)
724            .finish_transaction()
725            .build_checkpoint();
726
727        assert_eq!(checkpoint.checkpoint_summary.sequence_number(), 1);
728        assert_eq!(checkpoint.checkpoint_summary.epoch, 5);
729        assert_eq!(checkpoint.transactions.len(), 1);
730        let tx = &checkpoint.transactions[0];
731        assert_eq!(
732            tx.transaction.sender_address(),
733            TestCheckpointDataBuilder::derive_address(0)
734        );
735        assert_eq!(tx.effects.mutated().len(), 1); // gas object
736        assert_eq!(tx.effects.deleted().len(), 0);
737        assert_eq!(tx.effects.created().len(), 0);
738        assert_eq!(tx.input_objects.len(), 1);
739        assert_eq!(tx.output_objects.len(), 1);
740    }
741
742    #[test]
743    fn test_multiple_transactions() {
744        let checkpoint = TestCheckpointDataBuilder::new(1)
745            .start_transaction(0)
746            .finish_transaction()
747            .start_transaction(1)
748            .finish_transaction()
749            .start_transaction(2)
750            .finish_transaction()
751            .build_checkpoint();
752
753        assert_eq!(checkpoint.transactions.len(), 3);
754
755        // Verify transactions have different senders (since we used 0, 1, 2 as sender
756        // indices above).
757        let senders: Vec<_> = checkpoint
758            .transactions
759            .iter()
760            .map(|tx| tx.transaction.transaction().sender())
761            .collect();
762        assert_eq!(
763            senders,
764            vec![
765                TestCheckpointDataBuilder::derive_address(0),
766                TestCheckpointDataBuilder::derive_address(1),
767                TestCheckpointDataBuilder::derive_address(2)
768            ]
769        );
770    }
771
772    #[test]
773    fn test_object_creation() {
774        let checkpoint = TestCheckpointDataBuilder::new(1)
775            .start_transaction(0)
776            .create_owned_object(0)
777            .finish_transaction()
778            .build_checkpoint();
779
780        let tx = &checkpoint.transactions[0];
781        let created_obj_id = TestCheckpointDataBuilder::derive_object_id(0);
782
783        // Verify the newly created object appears in output objects
784        assert!(
785            tx.output_objects
786                .iter()
787                .any(|obj| obj.id() == created_obj_id)
788        );
789
790        // Verify effects show object creation
791        assert!(
792            tx.effects
793                .created()
794                .iter()
795                .any(|created| created.reference().object_id == created_obj_id
796                    && created.owner().address_or_object().unwrap()
797                        == &TestCheckpointDataBuilder::derive_address(0))
798        );
799    }
800
801    #[test]
802    fn test_object_mutation() {
803        let checkpoint = TestCheckpointDataBuilder::new(1)
804            .start_transaction(0)
805            .create_owned_object(0)
806            .finish_transaction()
807            .start_transaction(0)
808            .mutate_owned_object(0)
809            .finish_transaction()
810            .build_checkpoint();
811
812        let tx = &checkpoint.transactions[1];
813        let obj_id = TestCheckpointDataBuilder::derive_object_id(0);
814
815        // Verify object appears in both input and output objects
816        assert!(tx.input_objects.iter().any(|obj| obj.id() == obj_id));
817        assert!(tx.output_objects.iter().any(|obj| obj.id() == obj_id));
818
819        // Verify effects show object mutation
820        assert!(
821            tx.effects
822                .mutated()
823                .iter()
824                .any(|changed| changed.reference().object_id == obj_id)
825        );
826    }
827
828    #[test]
829    fn test_object_deletion() {
830        let checkpoint = TestCheckpointDataBuilder::new(1)
831            .start_transaction(0)
832            .create_owned_object(0)
833            .finish_transaction()
834            .start_transaction(0)
835            .delete_object(0)
836            .finish_transaction()
837            .build_checkpoint();
838
839        let tx = &checkpoint.transactions[1];
840        let obj_id = TestCheckpointDataBuilder::derive_object_id(0);
841
842        // Verify object appears in input objects but not output
843        assert!(tx.input_objects.iter().any(|obj| obj.id() == obj_id));
844        assert!(!tx.output_objects.iter().any(|obj| obj.id() == obj_id));
845
846        // Verify effects show object deletion
847        assert!(
848            tx.effects
849                .deleted()
850                .iter()
851                .any(|object_ref| object_ref.object_id == obj_id)
852        );
853    }
854
855    #[test]
856    fn test_object_wrapping() {
857        let checkpoint = TestCheckpointDataBuilder::new(1)
858            .start_transaction(0)
859            .create_owned_object(0)
860            .finish_transaction()
861            .start_transaction(0)
862            .wrap_object(0)
863            .finish_transaction()
864            .start_transaction(0)
865            .unwrap_object(0)
866            .finish_transaction()
867            .build_checkpoint();
868
869        let tx = &checkpoint.transactions[1];
870        let obj_id = TestCheckpointDataBuilder::derive_object_id(0);
871
872        // Verify object appears in input objects but not output
873        assert!(tx.input_objects.iter().any(|obj| obj.id() == obj_id));
874        assert!(!tx.output_objects.iter().any(|obj| obj.id() == obj_id));
875
876        // Verify effects show object wrapping
877        assert!(
878            tx.effects
879                .wrapped()
880                .iter()
881                .any(|object_ref| object_ref.object_id == obj_id)
882        );
883
884        let tx = &checkpoint.transactions[2];
885
886        // Verify object appears in output objects but not input
887        assert!(!tx.input_objects.iter().any(|obj| obj.id() == obj_id));
888        assert!(tx.output_objects.iter().any(|obj| obj.id() == obj_id));
889
890        // Verify effects show object unwrapping
891        assert!(
892            tx.effects
893                .unwrapped()
894                .iter()
895                .any(|changed| changed.reference().object_id == obj_id)
896        );
897    }
898
899    #[test]
900    fn test_object_transfer() {
901        let checkpoint = TestCheckpointDataBuilder::new(1)
902            .start_transaction(0)
903            .create_owned_object(0)
904            .finish_transaction()
905            .start_transaction(1)
906            .transfer_object(0, 1)
907            .finish_transaction()
908            .build_checkpoint();
909
910        let tx = &checkpoint.transactions[1];
911        let obj_id = TestCheckpointDataBuilder::derive_object_id(0);
912
913        // Verify object appears in input and output objects
914        assert!(tx.input_objects.iter().any(|obj| obj.id() == obj_id));
915        assert!(tx.output_objects.iter().any(|obj| obj.id() == obj_id));
916
917        // Verify effects show object transfer
918        assert!(
919            tx.effects
920                .mutated()
921                .iter()
922                .any(|changed| changed.reference().object_id == obj_id
923                    && changed.owner().address_or_object().unwrap()
924                        == &TestCheckpointDataBuilder::derive_address(1))
925        );
926    }
927
928    #[test]
929    fn test_shared_object() {
930        let checkpoint = TestCheckpointDataBuilder::new(1)
931            .start_transaction(0)
932            .create_shared_object(0)
933            .finish_transaction()
934            .build_checkpoint();
935
936        let tx = &checkpoint.transactions[0];
937        let obj_id = TestCheckpointDataBuilder::derive_object_id(0);
938
939        // Verify object appears in output objects and is shared
940        assert!(
941            tx.output_objects
942                .iter()
943                .any(|obj| obj.id() == obj_id && obj.owner().is_shared())
944        );
945    }
946
947    #[test]
948    fn test_freeze_object() {
949        let checkpoint = TestCheckpointDataBuilder::new(1)
950            .start_transaction(0)
951            .create_owned_object(0)
952            .finish_transaction()
953            .start_transaction(0)
954            .change_object_owner(0, Owner::Immutable)
955            .finish_transaction()
956            .build_checkpoint();
957
958        let tx = &checkpoint.transactions[1];
959        let obj_id = TestCheckpointDataBuilder::derive_object_id(0);
960
961        // Verify object appears in output objects and is immutable
962        assert!(
963            tx.output_objects
964                .iter()
965                .any(|obj| obj.id() == obj_id && obj.owner().is_immutable())
966        );
967    }
968
969    #[test]
970    fn test_iota_balance_transfer() {
971        let checkpoint = TestCheckpointDataBuilder::new(1)
972            .start_transaction(0)
973            .create_iota_object(0, 100)
974            .finish_transaction()
975            .start_transaction(1)
976            .transfer_coin_balance(0, 1, 1, 10)
977            .finish_transaction()
978            .build_checkpoint();
979
980        let tx = &checkpoint.transactions[0];
981        let obj_id0 = TestCheckpointDataBuilder::derive_object_id(0);
982
983        // Verify the newly created object appears in output objects and is a gas coin
984        // with 100 NANOS.
985        assert!(tx.output_objects.iter().any(|obj| obj.id() == obj_id0
986            && obj.is_gas_coin()
987            && obj.data.as_opt_struct().unwrap().get_coin_value_unchecked() == 100));
988
989        let tx = &checkpoint.transactions[1];
990        let obj_id1 = TestCheckpointDataBuilder::derive_object_id(1);
991
992        // Verify the original IOTA coin now has 90 NANOS after the transfer.
993        assert!(tx.output_objects.iter().any(|obj| obj.id() == obj_id0
994            && obj.is_gas_coin()
995            && obj.data.as_opt_struct().unwrap().get_coin_value_unchecked() == 90));
996
997        // Verify the split out IOTA coin has 10 NANOS.
998        assert!(tx.output_objects.iter().any(|obj| obj.id() == obj_id1
999            && obj.is_gas_coin()
1000            && obj.data.as_opt_struct().unwrap().get_coin_value_unchecked() == 10));
1001    }
1002
1003    #[test]
1004    fn test_coin_balance_transfer() {
1005        let type_tag = TypeTag::from_str("0x100::a::b").unwrap();
1006        let checkpoint = TestCheckpointDataBuilder::new(1)
1007            .start_transaction(0)
1008            .create_coin_object(0, 0, 100, type_tag.clone())
1009            .finish_transaction()
1010            .start_transaction(1)
1011            .transfer_coin_balance(0, 1, 1, 10)
1012            .finish_transaction()
1013            .build_checkpoint();
1014
1015        let tx = &checkpoint.transactions[1];
1016        let obj_id0 = TestCheckpointDataBuilder::derive_object_id(0);
1017        let obj_id1 = TestCheckpointDataBuilder::derive_object_id(1);
1018
1019        // Verify the original coin now has 90 balance after the transfer.
1020        assert!(tx.output_objects.iter().any(|obj| obj.id() == obj_id0
1021            && obj.opt_coin_type() == Some(&type_tag)
1022            && obj.data.as_opt_struct().unwrap().get_coin_value_unchecked() == 90));
1023
1024        // Verify the split out coin has 10 balance, with the same type tag.
1025        assert!(tx.output_objects.iter().any(|obj| obj.id() == obj_id1
1026            && obj.opt_coin_type() == Some(&type_tag)
1027            && obj.data.as_opt_struct().unwrap().get_coin_value_unchecked() == 10));
1028    }
1029
1030    #[test]
1031    fn test_events() {
1032        let checkpoint = TestCheckpointDataBuilder::new(1)
1033            .start_transaction(0)
1034            .with_events(vec![Event {
1035                package_id: ObjectId::ZERO,
1036                module: Identifier::from_static("test"),
1037                sender: TestCheckpointDataBuilder::derive_address(0),
1038                struct_tag: StructTag::new_gas(),
1039                contents: vec![],
1040            }])
1041            .finish_transaction()
1042            .build_checkpoint();
1043        let tx = &checkpoint.transactions[0];
1044
1045        // Verify the transaction has an events digest
1046        assert!(tx.effects.events_digest().is_some());
1047
1048        // Verify the transaction has a single event
1049        assert_eq!(tx.events.as_ref().unwrap().len(), 1);
1050    }
1051
1052    #[test]
1053    fn test_move_call() {
1054        let checkpoint = TestCheckpointDataBuilder::new(1)
1055            .start_transaction(0)
1056            .add_move_call(ObjectId::ZERO, "test", "test")
1057            .finish_transaction()
1058            .build_checkpoint();
1059        let tx = &checkpoint.transactions[0];
1060
1061        // Verify the transaction has a move call matching the arguments provided.
1062        assert!(
1063            tx.transaction
1064                .transaction()
1065                .kind()
1066                .iter_commands()
1067                .any(|cmd| {
1068                    cmd == &Command::new_move_call(
1069                        ObjectId::ZERO,
1070                        Identifier::new_unchecked("test"),
1071                        Identifier::new_unchecked("test"),
1072                        vec![],
1073                        vec![],
1074                    )
1075                })
1076        )
1077    }
1078
1079    #[test]
1080    fn test_multiple_checkpoints() {
1081        let mut builder = TestCheckpointDataBuilder::new(1)
1082            .start_transaction(0)
1083            .create_owned_object(0)
1084            .finish_transaction();
1085        let checkpoint1 = builder.build_checkpoint();
1086        builder = builder
1087            .start_transaction(0)
1088            .mutate_owned_object(0)
1089            .finish_transaction();
1090        let checkpoint2 = builder.build_checkpoint();
1091        builder = builder
1092            .start_transaction(0)
1093            .delete_object(0)
1094            .finish_transaction();
1095        let checkpoint3 = builder.build_checkpoint();
1096
1097        // Verify the sequence numbers are consecutive.
1098        assert_eq!(checkpoint1.checkpoint_summary.sequence_number, 1);
1099        assert_eq!(checkpoint2.checkpoint_summary.sequence_number, 2);
1100        assert_eq!(checkpoint3.checkpoint_summary.sequence_number, 3);
1101    }
1102}