Struct ChainClient 

pub struct ChainClient<Env: Environment> { /* private fields */ }

Client to operate a chain by interacting with validators and the given local storage implementation.

• The chain being operated is called the “local chain” or just the “chain”.
• As a rule, operations are considered successful (and communication may stop) when they succeeded in gathering a quorum of responses.

Implementations

impl<Env: Environment> ChainClient<Env>

pub fn pending_proposal(&self) -> Option<PendingProposal>

Gets the next pending block.

pub fn signer(&self) -> &impl Signer

Gets a reference to the client’s signer instance.

pub fn options_mut(&mut self) -> &mut ChainClientOptions

Gets a mutable reference to the per-ChainClient options.

pub fn options(&self) -> &ChainClientOptions

Gets a reference to the per-ChainClient options.

pub fn chain_id(&self) -> ChainId

Gets the ID of the associated chain.

pub fn timing_sender(&self) -> Option<UnboundedSender<(u64, TimingType)>>

Gets a clone of the timing sender for benchmarking.

pub fn admin_id(&self) -> ChainId

Gets the ID of the admin chain.

pub fn preferred_owner(&self) -> Option<AccountOwner>

Gets the currently preferred owner for signing the blocks.

pub fn set_preferred_owner(&mut self, preferred_owner: AccountOwner)

Sets the new, preferred owner for signing the blocks.

pub fn unset_preferred_owner(&mut self)

Unsets the preferred owner for signing the blocks.

pub async fn chain_state_view( &self, ) -> Result<OwnedRwLockReadGuard<ChainStateView<Env::StorageContext>>, LocalNodeError>

Obtains a ChainStateView for this client’s chain.

pub async fn event_stream_publishers( &self, ) -> Result<BTreeSet<ChainId>, LocalNodeError>

Returns chain IDs that this chain subscribes to.

pub fn subscribe(&self) -> Result<NotificationStream, LocalNodeError>

Subscribes to notifications from this client’s chain.

pub fn subscribe_to( &self, chain_id: ChainId, ) -> Result<NotificationStream, LocalNodeError>

Subscribes to notifications from the specified chain.

pub fn storage_client(&self) -> &Env::Storage

Returns the storage client used by this client’s local node.

pub async fn chain_info(&self) -> Result<Box<ChainInfo>, LocalNodeError>

Obtains the basic ChainInfo data for the local chain.

pub async fn get_chain_description( &self, ) -> Result<ChainDescription, ChainClientError>

Returns the chain’s description. Fetches it from the validators if necessary.

pub async fn local_committee(&self) -> Result<Committee, ChainClientError>

Obtains the committee for the current epoch of the local chain.

pub async fn admin_committee( &self, ) -> Result<(Epoch, Committee), LocalNodeError>

Obtains the committee for the latest epoch on the admin chain.

pub async fn identity(&self) -> Result<AccountOwner, ChainClientError>

Obtains the identity of the current owner of the chain.

Returns an error if we don’t have the private key for the identity.

pub async fn prepare_chain(&self) -> Result<Box<ChainInfo>, ChainClientError>

Prepares the chain for the next operation, i.e. makes sure we have synchronized it up to its current height and are not missing any received messages from the inbox.

pub async fn submit_fast_block_proposal( &self, committee: &Committee, operations: &[Operation], incoming_bundles: &[IncomingBundle], super_owner: AccountOwner, ) -> Result<(u64, u64, u64, u64), ChainClientError>

Submits a fast block proposal to the validators.

This must only be used with valid epoch and super owner.

pub async fn update_validators( &self, old_committee: Option<&Committee>, ) -> Result<(), ChainClientError>

Attempts to update all validators about the local chain.

pub async fn communicate_chain_updates( &self, committee: &Committee, ) -> Result<(), ChainClientError>

Broadcasts certified blocks to validators.

pub async fn transfer( &self, owner: AccountOwner, amount: Amount, recipient: Account, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Sends money.

pub async fn read_data_blob( &self, hash: CryptoHash, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Verify if a data blob is readable from storage.

pub async fn claim( &self, owner: AccountOwner, target_id: ChainId, recipient: Account, amount: Amount, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Claims money in a remote chain.

pub async fn request_leader_timeout( &self, ) -> Result<TimeoutCertificate, ChainClientError>

Requests a leader timeout vote from all validators. If a quorum signs it, creates a certificate and sends it to all validators, to make them enter the next round.

pub async fn synchronize_chain_state( &self, chain_id: ChainId, ) -> Result<Box<ChainInfo>, ChainClientError>

Downloads and processes any certificates we are missing for the given chain.

pub async fn synchronize_chain_state_from_committee( &self, committee: Committee, ) -> Result<Box<ChainInfo>, ChainClientError>

Downloads and processes any certificates we are missing for this chain, from the given committee.

pub async fn execute_operations( &self, operations: Vec<Operation>, blobs: Vec<Blob>, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Executes a list of operations.

pub async fn execute_operation( &self, operation: impl Into<Operation>, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Executes an operation.

pub async fn query_application( &self, query: Query, ) -> Result<QueryOutcome, ChainClientError>

Queries an application.

pub async fn query_system_application( &self, query: SystemQuery, ) -> Result<QueryOutcome<SystemResponse>, ChainClientError>

Queries a system application.

pub async fn query_user_application<A: Abi>( &self, application_id: ApplicationId<A>, query: &A::Query, ) -> Result<QueryOutcome<A::QueryResponse>, ChainClientError>

Queries a user application.

pub async fn query_balance(&self) -> Result<Amount, ChainClientError>

Obtains the local balance of the chain account after staging the execution of incoming messages in a new block.

Does not attempt to synchronize with validators. The result will reflect up to max_pending_message_bundles incoming message bundles and the execution fees for a single block.

pub async fn query_owner_balance( &self, owner: AccountOwner, ) -> Result<Amount, ChainClientError>

Obtains the local balance of an account after staging the execution of incoming messages in a new block.

Does not attempt to synchronize with validators. The result will reflect up to max_pending_message_bundles incoming message bundles and the execution fees for a single block.

pub async fn local_balance(&self) -> Result<Amount, ChainClientError>

Reads the local balance of the chain account.

Does not process the inbox or attempt to synchronize with validators.

pub async fn local_owner_balance( &self, owner: AccountOwner, ) -> Result<Amount, ChainClientError>

Reads the local balance of a user account.

Does not process the inbox or attempt to synchronize with validators.

pub async fn transfer_to_account( &self, from: AccountOwner, amount: Amount, account: Account, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Sends tokens to a chain.

pub async fn fetch_chain_info(&self) -> Result<Box<ChainInfo>, ChainClientError>

pub async fn synchronize_from_validators( &self, ) -> Result<Box<ChainInfo>, ChainClientError>

Attempts to synchronize chains that have sent us messages and populate our local inbox.

To create a block that actually executes the messages in the inbox, process_inbox must be called separately.

pub async fn process_pending_block( &self, ) -> Result<ClientOutcome<Option<ConfirmedBlockCertificate>>, ChainClientError>

Processes the last pending block

pub async fn receive_certificate_and_update_validators( &self, certificate: ConfirmedBlockCertificate, ) -> Result<(), ChainClientError>

Processes a confirmed block for which this chain is a recipient and updates validators.

pub async fn rotate_key_pair( &self, public_key: AccountPublicKey, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Rotates the key of the chain.

Replaces current owners of the chain with the new key pair.

pub async fn transfer_ownership( &self, new_owner: AccountOwner, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Transfers ownership of the chain to a single super owner.

pub async fn share_ownership( &self, new_owner: AccountOwner, new_weight: u64, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Adds another owner to the chain, and turns existing super owners into regular owners.

pub async fn change_ownership( &self, ownership: ChainOwnership, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Changes the ownership of this chain. Fails if it would remove existing owners, unless remove_owners is true.

pub async fn change_application_permissions( &self, application_permissions: ApplicationPermissions, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Changes the application permissions configuration on this chain.

pub async fn open_chain( &self, ownership: ChainOwnership, application_permissions: ApplicationPermissions, balance: Amount, ) -> Result<ClientOutcome<(ChainDescription, ConfirmedBlockCertificate)>, ChainClientError>

Opens a new chain with a derived UID.

pub async fn close_chain( &self, ) -> Result<ClientOutcome<Option<ConfirmedBlockCertificate>>, ChainClientError>

Closes the chain (and loses everything in it!!). Returns None if the chain was already closed.

pub async fn publish_module( &self, contract: Bytecode, service: Bytecode, vm_runtime: VmRuntime, ) -> Result<ClientOutcome<(ModuleId, ConfirmedBlockCertificate)>, ChainClientError>

Publishes some module.

pub async fn publish_module_blobs( &self, blobs: Vec<Blob>, module_id: ModuleId, ) -> Result<ClientOutcome<(ModuleId, ConfirmedBlockCertificate)>, ChainClientError>

Publishes some module.

pub async fn publish_data_blobs( &self, bytes: Vec<Vec<u8>>, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Publishes some data blobs.

pub async fn publish_data_blob( &self, bytes: Vec<u8>, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Publishes some data blob.

pub async fn create_application<A: Abi, Parameters: Serialize, InstantiationArgument: Serialize>( &self, module_id: ModuleId<A, Parameters, InstantiationArgument>, parameters: &Parameters, instantiation_argument: &InstantiationArgument, required_application_ids: Vec<ApplicationId>, ) -> Result<ClientOutcome<(ApplicationId<A>, ConfirmedBlockCertificate)>, ChainClientError>

Creates an application by instantiating some bytecode.

pub async fn create_application_untyped( &self, module_id: ModuleId, parameters: Vec<u8>, instantiation_argument: Vec<u8>, required_application_ids: Vec<ApplicationId>, ) -> Result<ClientOutcome<(ApplicationId, ConfirmedBlockCertificate)>, ChainClientError>

Creates an application by instantiating some bytecode.

pub async fn stage_new_committee( &self, committee: Committee, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Creates a new committee and starts using it (admin chains only).

pub async fn process_inbox( &self, ) -> Result<(Vec<ConfirmedBlockCertificate>, Option<RoundTimeout>), ChainClientError>

Synchronizes the chain with the validators and creates blocks without any operations to process all incoming messages. This may require several blocks.

If not all certificates could be processed due to a timeout, the timestamp for when to retry is returned, too.

pub async fn process_inbox_without_prepare( &self, ) -> Result<(Vec<ConfirmedBlockCertificate>, Option<RoundTimeout>), ChainClientError>

Creates blocks without any operations to process all incoming messages. This may require several blocks.

If not all certificates could be processed due to a timeout, the timestamp for when to retry is returned, too.

pub async fn events_from_index( &self, stream_id: StreamId, start_index: u32, ) -> Result<Vec<IndexAndEvent>, ChainClientError>

Returns the indices and events from the storage

pub async fn revoke_epochs( &self, revoked_epoch: Epoch, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Deprecates all the configurations of voting rights up to the given one (admin chains only). Currently, each individual chain is still entitled to wait before accepting this command. However, it is expected that deprecated validators stop functioning shortly after such command is issued.

pub async fn transfer_to_account_unsafe_unconfirmed( &self, owner: AccountOwner, amount: Amount, recipient: Account, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Sends money to a chain. Do not check balance. (This may block the client) Do not confirm the transaction.

pub async fn read_confirmed_block( &self, hash: CryptoHash, ) -> Result<ConfirmedBlock, ChainClientError>

pub async fn retry_pending_outgoing_messages( &self, ) -> Result<(), ChainClientError>

Handles any cross-chain requests for any pending outgoing messages.

pub fn is_tracked(&self) -> bool

Returns whether this chain is tracked by the client, i.e. we are updating its inbox.

pub async fn listen( &self, ) -> Result<(impl Future<Output = ()>, AbortOnDrop, NotificationStream), ChainClientError>

Spawns a task that listens to notifications about the current chain from all validators, and synchronizes the local state accordingly.

pub async fn sync_validator( &self, remote_node: Env::ValidatorNode, ) -> Result<(), ChainClientError>

Attempts to update a validator with the local information.

Trait Implementations

impl<Env: Environment> Clone for ChainClient<Env>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Env: Environment> Debug for ChainClient<Env>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.