Struct TrackingCopy

pub struct TrackingCopy<R> { /* private fields */ }

An interface for the global state that caches all operations (reads and writes) instead of applying them directly to the state. This way the state remains unmodified, while the user can interact with it as if it was being modified in real time.

Implementations

impl<R> TrackingCopy<R>

where R: StateReader<Key, StoredValue, Error = Error> + StateReader<Key, StoredValue>,

pub fn new( reader: R, max_query_depth: u64, enable_addressable_entity: bool, ) -> TrackingCopy<R>

Creates a new TrackingCopy using the reader as the interface to the state.

pub fn reader(&self) -> &R

Returns the reader used to access the state.

pub fn shared_reader(&self) -> Arc<R>

Returns a shared reference to the reader used to access the state.

pub fn fork(&self) -> TrackingCopy<&TrackingCopy<R>>

Creates a new TrackingCopy using the reader as the interface to the state. Returns a new TrackingCopy instance that is a snapshot of the current state, allowing further changes to be made.

This method creates a new TrackingCopy using the current instance (including its mutations) as the base state to read against. Mutations made to the new TrackingCopy will not impact the original instance.

Note: Currently, there is no join or merge function to bring changes from a fork back to the main TrackingCopy. Therefore, forking should be done repeatedly, which is suboptimal and will be improved in the future.

pub fn fork2(&self) -> Self

Returns a new TrackingCopy instance that is a snapshot of the current state, allowing further changes to be made.

This method creates a new TrackingCopy using the current instance (including its mutations) as the base state to read against. Mutations made to the new TrackingCopy will not impact the original instance.

Note: Currently, there is no join or merge function to bring changes from a fork back to the main TrackingCopy. This method is an alternative to the fork method and is provided for clarity and consistency in naming.

pub fn apply_changes( &mut self, effects: Effects, cache: TrackingCopyCache, messages: Messages, )

Applies the changes to the state.

This is a low-level function that should be used only by the execution engine. The purpose of this function is to apply the changes to the state from a forked tracking copy. Once caller decides that the changes are valid, they can be applied to the state and the processing can resume.

pub fn effects(&self) -> Effects

Returns a copy of the execution effects cached by this instance.

pub fn cache(&self) -> TrackingCopyCache

Returns copy of cache.

pub fn destructure(self) -> (Vec<(Key, StoredValue)>, BTreeSet<Key>, Effects)

Destructure cached entries.

pub fn enable_addressable_entity(&self) -> bool

Enable the addressable entity and migrate accounts/contracts to entities.

pub fn get( &mut self, key: &Key, ) -> Result<Option<StoredValue>, TrackingCopyError>

Get record by key.

pub fn get_keys( &self, key_tag: &KeyTag, ) -> Result<BTreeSet<Key>, TrackingCopyError>

Gets the set of keys in the state whose tag is key_tag.

pub fn get_keys_by_prefix( &self, key_prefix: &KeyPrefix, ) -> Result<BTreeSet<Key>, TrackingCopyError>

Get keys by prefix.

pub fn read( &mut self, key: &Key, ) -> Result<Option<StoredValue>, TrackingCopyError>

Reads the value stored under key.

pub fn read_first( &mut self, keys: &[&Key], ) -> Result<Option<StoredValue>, TrackingCopyError>

Reads the first value stored under the keys in keys.

pub fn write(&mut self, key: Key, value: StoredValue)

Writes value under key. Note that the written value is only cached.

pub fn emit_message( &mut self, message_topic_key: Key, message_topic_summary: StoredValue, message_key: Key, message_value: StoredValue, block_message_count_value: StoredValue, message: Message, )

Caches the emitted message and writes the message topic summary under the specified key.

This function does not check the types for the key and the value so the caller should correctly set the type. The message_topic_key should be of the Key::MessageTopic variant and the message_topic_summary should be of the StoredValue::Message variant.

pub fn prune(&mut self, key: Key)

Prunes a key.

pub fn add( &mut self, key: Key, value: StoredValue, ) -> Result<AddResult, TrackingCopyError>

Ok(None) represents missing key to which we want to “add” some value. Ok(Some(unit)) represents successful operation. Err(error) is reserved for unexpected errors when accessing global state.

pub fn messages(&self) -> Messages

Returns a copy of the messages cached by this instance.

pub fn query( &self, base_key: Key, path: &[String], ) -> Result<TrackingCopyQueryResult, TrackingCopyError>

Calling query() avoids calling into self.cache, so this will not return any values written or mutated in this TrackingCopy via previous calls to write() or add(), since these updates are only held in self.cache.

The intent is that query() is only used to satisfy QueryRequests made to the server. Other EE internal use cases should call read() or get() in order to retrieve cached values.

Trait Implementations

impl<R: Clone> Clone for TrackingCopy<R>

fn clone(&self) -> TrackingCopy<R>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<R: StateReader<Key, StoredValue>> StateReader for &TrackingCopy<R>

The purpose of this implementation is to allow a “snapshot” mechanism for TrackingCopy. The state of a TrackingCopy (including the effects of any transforms it has accumulated) can be read using an immutable reference to that TrackingCopy via this trait implementation. See TrackingCopy::fork for more information.

type Error = <R as StateReader>::Error

An error which occurs when reading state

fn read(&self, key: &Key) -> Result<Option<StoredValue>, Self::Error>

Returns the state value from the corresponding key

fn read_with_proof( &self, key: &Key, ) -> Result<Option<TrieMerkleProof<Key, StoredValue>>, Self::Error>

Returns the merkle proof of the state value from the corresponding key

fn keys_with_prefix(&self, byte_prefix: &[u8]) -> Result<Vec<Key>, Self::Error>

Returns the keys in the trie matching prefix.

impl<R> TrackingCopyEntityExt<R> for TrackingCopy<R>

where R: StateReader<Key, StoredValue, Error = Error>,

type Error = Error

The type for the returned errors.

fn runtime_footprint_by_entity_addr( &self, entity_addr: EntityAddr, ) -> Result<RuntimeFootprint, Self::Error>

Gets a runtime information by entity_addr.

fn runtime_footprint_by_hash_addr( &mut self, hash_addr: HashAddr, ) -> Result<RuntimeFootprint, Self::Error>

Gets a runtime information by hash_addr.

fn runtime_footprint_by_account_hash( &mut self, protocol_version: ProtocolVersion, account_hash: AccountHash, ) -> Result<(EntityAddr, RuntimeFootprint), Self::Error>

Gets a runtime information by account hash.

fn authorized_runtime_footprint_by_account( &mut self, protocol_version: ProtocolVersion, account_hash: AccountHash, authorization_keys: &BTreeSet<AccountHash>, administrative_accounts: &BTreeSet<AccountHash>, ) -> Result<(RuntimeFootprint, EntityAddr), Self::Error>

Get runtime information for an account if authorized, else error.

fn authorized_runtime_footprint_with_access_rights( &mut self, protocol_version: ProtocolVersion, initiating_address: AccountHash, authorization_keys: &BTreeSet<AccountHash>, administrative_accounts: &BTreeSet<AccountHash>, ) -> Result<(EntityAddr, RuntimeFootprint, ContextAccessRights), TrackingCopyError>

Returns runtime information and access rights if authorized, else error.

fn system_entity_runtime_footprint( &mut self, protocol_version: ProtocolVersion, ) -> Result<(EntityAddr, RuntimeFootprint, ContextAccessRights), TrackingCopyError>

Returns runtime information for systemic functionality.

fn migrate_named_keys( &mut self, entity_addr: EntityAddr, named_keys: NamedKeys, ) -> Result<(), Self::Error>

Migrate the NamedKeys for a entity.

fn migrate_entry_points( &mut self, entity_addr: EntityAddr, entry_points: EntryPoints, ) -> Result<(), Self::Error>

Migrate entry points from and older structure to top level entries.

fn upsert_uref_to_named_keys( &mut self, entity_addr: EntityAddr, name: &str, named_keys: &NamedKeys, uref: URef, stored_value: StoredValue, ) -> Result<(), Self::Error>

Upsert uref value to global state and imputed entity’s named keys.

fn migrate_account( &mut self, account_hash: AccountHash, protocol_version: ProtocolVersion, ) -> Result<(), Self::Error>

Migrate Account to AddressableEntity.

fn create_new_addressable_entity_on_transfer( &mut self, account_hash: AccountHash, main_purse: URef, protocol_version: ProtocolVersion, ) -> Result<(), Self::Error>

Create an addressable entity to receive transfer.

fn create_addressable_entity_from_account( &mut self, account: Account, protocol_version: ProtocolVersion, ) -> Result<(), Self::Error>

Create an addressable entity instance using the field data of an account instance.

fn migrate_package( &mut self, legacy_package_key: Key, protocol_version: ProtocolVersion, ) -> Result<(), Self::Error>

Migrate ContractPackage to Package.

fn fees_purse( &mut self, protocol_version: ProtocolVersion, fees_purse_handling: FeesPurseHandling, ) -> Result<URef, TrackingCopyError>

Returns fee purse.

fn system_contract_named_key( &mut self, system_contract_name: &str, name: &str, ) -> Result<Option<Key>, Self::Error>

Returns named key from selected system contract.

impl<R> TrackingCopyExt<R> for TrackingCopy<R>

where R: StateReader<Key, StoredValue, Error = Error>,

type Error = Error

The type for the returned errors.

fn read_account_key( &mut self, account_hash: AccountHash, ) -> Result<Key, Self::Error>

Reads the entity key for a given account hash.

fn get_block_time(&self) -> Result<Option<BlockTime>, Self::Error>

Returns block time associated with checked out root hash.

fn get_balance_hold_config( &self, hold_kind: BalanceHoldAddrTag, ) -> Result<Option<(BlockTime, HoldBalanceHandling, u64)>, Self::Error>

Returns balance hold configuration settings for imputed kind of balance hold.

fn get_purse_balance_key(&self, purse_key: Key) -> Result<Key, Self::Error>

Gets the purse balance key for a given purse.

fn get_balance_hold_addresses( &self, purse_addr: URefAddr, ) -> Result<Vec<BalanceHoldAddr>, Self::Error>

Gets the balance hold keys for the imputed purse (if any).

fn get_total_balance(&self, key: Key) -> Result<Motes, Self::Error>

Returns total balance.

fn get_available_balance(&mut self, key: Key) -> Result<Motes, Self::Error>

Returns the available balance, considering any holds from holds_epoch to now.

fn get_purse_balance_key_with_proof( &self, purse_key: Key, ) -> Result<(Key, TrieMerkleProof<Key, StoredValue>), Self::Error>

Gets the purse balance key for a given purse and provides a Merkle proof.

fn get_total_balance_with_proof( &self, key: Key, ) -> Result<(U512, TrieMerkleProof<Key, StoredValue>), Self::Error>

Gets the balance at a given balance key and provides a Merkle proof.

fn clear_expired_balance_holds( &mut self, purse_addr: URefAddr, filter: Vec<(BalanceHoldAddrTag, HoldsEpoch)>, ) -> Result<(), Self::Error>

Clear expired balance holds.

fn get_balance_holds( &mut self, purse_addr: URefAddr, block_time: BlockTime, interval: u64, ) -> Result<BTreeMap<BlockTime, BalanceHolds>, Self::Error>

Gets the balance holds for a given balance, without Merkle proofs.

fn get_balance_holds_with_proof( &self, purse_addr: URefAddr, ) -> Result<BTreeMap<BlockTime, BalanceHoldsWithProof>, Self::Error>

Gets the balance holds for a given balance, with Merkle proofs.

fn get_message_topics( &self, hash_addr: EntityAddr, ) -> Result<MessageTopics, Self::Error>

Returns the collection of message topics (if any) for a given HashAddr.

fn get_named_keys( &self, entity_addr: EntityAddr, ) -> Result<NamedKeys, Self::Error>

Returns the collection of named keys for a given AddressableEntity.

fn get_v1_entry_points( &self, entity_addr: EntityAddr, ) -> Result<EntryPoints, Self::Error>

Returns the collection of entry points for a given AddresableEntity.

fn get_package(&mut self, hash_addr: HashAddr) -> Result<Package, Self::Error>

Gets a package by hash.

fn get_contract( &mut self, contract_hash: ContractHash, ) -> Result<Contract, Self::Error>

Get a Contract record.

fn get_system_entity_registry(&self) -> Result<SystemHashRegistry, Self::Error>

Gets the system entity registry.

fn get_checksum_registry( &mut self, ) -> Result<Option<ChecksumRegistry>, Self::Error>

Gets the system checksum registry.

fn get_byte_code( &mut self, byte_code_hash: ByteCodeHash, ) -> Result<ByteCode, Self::Error>

Gets byte code by hash.