Struct Simulacrum

pub struct Simulacrum<R = OsRng, Store: SimulatorStore = InMemoryStore> { /* private fields */ }

A Simulacrum of Sui.

This type represents a simulated instantiation of a Sui blockchain that needs to be driven manually, that is time doesn’t advance and checkpoints are not formed unless explicitly requested.

See module level documentation for more details.

Implementations

impl Simulacrum

pub fn new() -> Self

Create a new, random Simulacrum instance using an OsRng as the source of randomness.

impl<R> Simulacrum<R>

where R: RngCore + CryptoRng,

pub fn new_with_rng(rng: R) -> Self

Create a new Simulacrum instance using the provided rng.

This allows you to create a fully deterministic initial chainstate when a seeded rng is used.

use simulacrum::Simulacrum;
use rand::{SeedableRng, rngs::StdRng};

let mut rng = StdRng::seed_from_u64(1);
let simulacrum = Simulacrum::new_with_rng(rng);

pub fn new_with_protocol_version( rng: R, protocol_version: ProtocolVersion, ) -> Self

Create a new Simulacrum instance with a specific protocol version.

pub fn new_with_protocol_version_and_accounts( rng: R, chain_start_timestamp_ms: u64, protocol_version: ProtocolVersion, account_configs: Vec<AccountConfig>, ) -> Self

impl<R, S: SimulatorStore> Simulacrum<R, S>

pub fn new_with_network_config_store( config: &NetworkConfig, rng: R, store: S, ) -> Self

pub fn execute_transaction( &mut self, transaction: Transaction, ) -> Result<(TransactionEffects, Option<ExecutionError>)>

Attempts to execute the provided Transaction.

The provided Transaction undergoes the same types of checks that a Validator does prior to signing and executing in the production system. Some of these checks are as follows:

• User signature is valid
• Sender owns all OwnedObject inputs
• etc

If the above checks are successful then the transaction is immediately executed, enqueued to be included in the next checkpoint (the next time create_checkpoint is called) and the corresponding TransactionEffects are returned.

pub fn create_checkpoint(&mut self) -> VerifiedCheckpoint

Creates the next Checkpoint using the Transactions enqueued since the last checkpoint was created.

pub fn advance_clock(&mut self, duration: Duration) -> TransactionEffects

Advances the clock by duration.

This creates and executes a ConsensusCommitPrologue transaction which advances the chain Clock by the provided duration.

pub fn advance_epoch(&mut self, config: AdvanceEpochConfig)

Advances the epoch.

This creates and executes an EndOfEpoch transaction which advances the chain into the next epoch. Since it is required to be the final transaction in an epoch, the final checkpoint in the epoch is also created.

The config parameter controls which special end-of-epoch transactions are created as part of this epoch change.

NOTE: This function does not currently support updating the protocol version

pub fn store(&self) -> &dyn SimulatorStore

pub fn keystore(&self) -> &KeyStore

pub fn epoch_start_state(&self) -> &EpochStartSystemState

pub fn rng(&mut self) -> &mut R

Return a handle to the internally held RNG.

Returns a handle to the RNG used to create this Simulacrum for use as a source of randomness. Using a seeded RNG to build a Simulacrum and then utilizing the stored RNG as a source of randomness can lead to a fully deterministic chain evolution.

pub fn reference_gas_price(&self) -> u64

Return the reference gas price for the current epoch

pub fn funded_account( &mut self, amount: u64, ) -> Result<(SuiAddress, AccountKeyPair, ObjectRef)>

Create a new account and credit it with amount gas units from a faucet account. Returns the account, its keypair, and a reference to the gas object it was funded with.

use simulacrum::Simulacrum;
use sui_types::base_types::SuiAddress;
use sui_types::gas_coin::MIST_PER_SUI;

let mut simulacrum = Simulacrum::new();
let (account, kp, gas) = simulacrum.funded_account(MIST_PER_SUI).unwrap();

// `account` is a fresh SuiAddress that owns a Coin<SUI> object with single SUI in it,
// referred to by `gas`.
// ...

pub fn request_gas( &mut self, address: SuiAddress, amount: u64, ) -> Result<TransactionEffects>

Request that amount Mist be sent to address from a faucet account.

use simulacrum::Simulacrum;
use sui_types::base_types::SuiAddress;
use sui_types::gas_coin::MIST_PER_SUI;

let mut simulacrum = Simulacrum::new();
let address = SuiAddress::generate(simulacrum.rng());
simulacrum.request_gas(address, MIST_PER_SUI).unwrap();

// `account` now has a Coin<SUI> object with single SUI in it.
// ...

pub fn set_data_ingestion_path(&mut self, data_ingestion_path: PathBuf)

pub fn override_next_checkpoint_number( &mut self, number: CheckpointSequenceNumber, )

impl Simulacrum

pub fn transfer_txn(&mut self, recipient: SuiAddress) -> (Transaction, u64)

Generate a random transfer transaction. TODO: This is here today to make it easier to write tests. But we should utilize all the existing code for generating transactions in sui-test-transaction-builder by defining a trait that both WalletContext and Simulacrum implement. Then we can remove this function.

Trait Implementations

impl<T, V: SimulatorStore> ObjectStore for Simulacrum<T, V>

fn get_object(&self, object_id: &ObjectID) -> Option<Object>

fn get_object_by_key( &self, object_id: &ObjectID, version: VersionNumber, ) -> Option<Object>

fn multi_get_objects(&self, object_ids: &[ObjectID]) -> Vec<Option<Object>>

fn multi_get_objects_by_key( &self, object_keys: &[ObjectKey], ) -> Vec<Option<Object>>

impl<T, V: SimulatorStore> ReadStore for Simulacrum<T, V>

fn get_committee(&self, _epoch: EpochId) -> Option<Arc<Committee>>

fn get_latest_checkpoint(&self) -> Result<VerifiedCheckpoint>

Get the latest available checkpoint. This is the latest executed checkpoint.

fn get_latest_epoch_id(&self) -> Result<EpochId>

Get the epoch of the latest checkpoint

fn get_highest_verified_checkpoint(&self) -> Result<VerifiedCheckpoint>

Get the highest verified checkpint. This is the highest checkpoint summary that has been verified, generally by state-sync. Only the checkpoint header is guaranteed to be present in the store.

fn get_highest_synced_checkpoint(&self) -> Result<VerifiedCheckpoint>

Get the highest synced checkpint. This is the highest checkpoint that has been synced from state-synce. The checkpoint header, contents, transactions, and effects of this checkpoint are guaranteed to be present in the store

fn get_lowest_available_checkpoint(&self) -> Result<CheckpointSequenceNumber>

Lowest available checkpoint for which transaction and checkpoint data can be requested.

fn get_checkpoint_by_digest( &self, digest: &CheckpointDigest, ) -> Option<VerifiedCheckpoint>

fn get_checkpoint_by_sequence_number( &self, sequence_number: CheckpointSequenceNumber, ) -> Option<VerifiedCheckpoint>

fn get_checkpoint_contents_by_digest( &self, digest: &CheckpointContentsDigest, ) -> Option<CheckpointContents>

fn get_checkpoint_contents_by_sequence_number( &self, _sequence_number: CheckpointSequenceNumber, ) -> Option<CheckpointContents>

fn get_transaction( &self, tx_digest: &TransactionDigest, ) -> Option<Arc<VerifiedTransaction>>

fn get_transaction_effects( &self, tx_digest: &TransactionDigest, ) -> Option<TransactionEffects>

fn get_events( &self, event_digest: &TransactionDigest, ) -> Option<TransactionEvents>

fn get_full_checkpoint_contents( &self, _sequence_number: Option<CheckpointSequenceNumber>, _digest: &CheckpointContentsDigest, ) -> Option<VersionedFullCheckpointContents>

Get a “full” checkpoint for purposes of state-sync “full” checkpoints include: header, contents, transactions, effects. sequence_number is optional since we can always query it using the digest. However if it is provided, we can avoid an extra db lookup.

fn get_unchanged_loaded_runtime_objects( &self, _digest: &TransactionDigest, ) -> Option<Vec<ObjectKey>>

fn get_transaction_checkpoint( &self, _digest: &TransactionDigest, ) -> Option<CheckpointSequenceNumber>

fn get_latest_checkpoint_sequence_number(&self) -> Result<u64, Error>

Get the latest available checkpoint sequence number. This is the sequence number of the latest executed checkpoint.

fn multi_get_transactions( &self, tx_digests: &[TransactionDigest], ) -> Vec<Option<Arc<VerifiedEnvelope<SenderSignedData, EmptySignInfo>>>>

fn multi_get_transaction_effects( &self, tx_digests: &[TransactionDigest], ) -> Vec<Option<TransactionEffects>>

fn multi_get_events( &self, event_digests: &[TransactionDigest], ) -> Vec<Option<TransactionEvents>>

fn get_checkpoint_data( &self, checkpoint: VerifiedEnvelope<CheckpointSummary, AuthorityQuorumSignInfo<true>>, checkpoint_contents: CheckpointContents, ) -> Result<Checkpoint, Error>

impl<T: Send + Sync, V: SimulatorStore + Send + Sync> RpcStateReader for Simulacrum<T, V>

fn get_lowest_available_checkpoint_objects( &self, ) -> Result<CheckpointSequenceNumber>

Lowest available checkpoint for which object data can be requested.

fn get_chain_identifier(&self) -> Result<ChainIdentifier>

fn indexes(&self) -> Option<&dyn RpcIndexes>

fn get_struct_layout(&self, _: &StructTag) -> Result<Option<MoveTypeLayout>>

fn get_type_layout( &self, type_tag: &TypeTag, ) -> Result<Option<MoveTypeLayout>, Error>