Struct linera_core::client::ChainClient

pub struct ChainClient<ValidatorNodeProvider, Storage>
where
    Storage: Storage,
{ /* 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<P: 'static, S: Storage> ChainClient<P, S>

pub fn state(&self) -> ChainGuard<'_, ChainClientState>

Gets a shared reference to the chain’s state.

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 block_hash(&self) -> Option<CryptoHash>

Gets the hash of the latest known block.

pub fn timestamp(&self) -> Timestamp

Gets the earliest possible timestamp for the next block.

pub fn next_block_height(&self) -> BlockHeight

Gets the next block height.

pub fn pending_proposal(&self) -> ChainGuardMapped<'_, Option<PendingProposal>>

Gets a guarded reference to the next pending block.

impl<P, S> ChainClient<P, S>

where P: ValidatorNodeProvider + Sync + 'static, S: Storage + Clone + Send + Sync + 'static,

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

Obtains a ChainStateView for this client’s chain.

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

Subscribes to notifications from this client’s chain.

pub fn storage_client(&self) -> S

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 chain_info_with_manager_values( &self, ) -> Result<Box<ChainInfo>, LocalNodeError>

Obtains the basic ChainInfo data for the local chain, with chain manager values.

pub async fn epoch_and_committees( &self, chain_id: ChainId, ) -> Result<(Option<Epoch>, BTreeMap<Epoch, Committee>), LocalNodeError>

Obtains the current epoch of the given chain as well as its set of trusted committees.

pub async fn epochs(&self) -> Result<Vec<Epoch>, LocalNodeError>

Obtains the epochs of the committees trusted by the local chain.

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

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

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

Obtains the identity of the current owner of the chain. Returns an error if we have the private key for more than one identity.

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

Obtains the key pair associated to the current identity.

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

Obtains the public key associated to the current 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 synchronize_until( &self, next_block_height: BlockHeight, ) -> Result<Box<ChainInfo>, ChainClientError>

pub async fn submit_block_proposal<T: ProcessableCertificate>( &self, committee: &Committee, proposal: Box<BlockProposal>, value: Hashed<T>, ) -> Result<GenericCertificate<T>, ChainClientError>

Submits a block proposal to the validators.

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, chain_id: ChainId, height: BlockHeight, delivery: CrossChainMessageDelivery, ) -> Result<(), ChainClientError>

Broadcasts certified blocks to validators.

pub async fn transfer( &self, owner: Option<Owner>, amount: Amount, recipient: Recipient, ) -> 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: Owner, target_id: ChainId, recipient: Recipient, amount: Amount, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Claims money in a remote chain.

pub async fn process_certificate<T: ProcessableCertificate>( &self, certificate: GenericCertificate<T>, ) -> Result<(), LocalNodeError>

Handles the certificate in the local node and the resulting notifications.

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 receive_certificate_for_blob( &self, blob_id: BlobId, ) -> Result<(), ChainClientError>

Downloads and processes a confirmed block certificate that uses the given blob. If this succeeds, the blob will be in our storage.

pub async fn receive_certificates_for_blobs( &self, blob_ids: Vec<BlobId>, ) -> Result<(), ChainClientError>

Downloads and processes confirmed block certificates that use the given blobs. If this succeeds, the blobs will be in our storage.

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: 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: UserApplicationId<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 request_application( &self, application_id: UserApplicationId, chain_id: Option<ChainId>, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Requests a RegisterApplications message from another chain so the application can be used on this one.

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

Sends tokens to a chain.

pub async fn burn( &self, owner: Option<Owner>, amount: Amount, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Burns tokens.

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 fn clear_pending_proposal(&self)

Clears the information on any operation that previously failed.

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 receive_certificate( &self, certificate: ConfirmedBlockCertificate, ) -> Result<(), ChainClientError>

Processes confirmed operation for which this chain is a recipient.

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

Rotates the key of the chain.

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

Transfers ownership of the chain to a single super owner.

pub async fn share_ownership( &self, new_owner: Owner, 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<(MessageId, 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_bytecode( &self, contract: Bytecode, service: Bytecode, vm_runtime: VmRuntime, ) -> Result<ClientOutcome<(BytecodeId, ConfirmedBlockCertificate)>, ChainClientError>

Publishes some bytecode.

pub async fn publish_bytecode_blobs( &self, contract_blob: Blob, service_blob: Blob, bytecode_id: BytecodeId, ) -> Result<ClientOutcome<(BytecodeId, ConfirmedBlockCertificate)>, ChainClientError>

Publishes some bytecode.

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, bytecode_id: BytecodeId<A, Parameters, InstantiationArgument>, parameters: &Parameters, instantiation_argument: &InstantiationArgument, required_application_ids: Vec<UserApplicationId>, ) -> Result<ClientOutcome<(UserApplicationId<A>, ConfirmedBlockCertificate)>, ChainClientError>

Creates an application by instantiating some bytecode.

pub async fn create_application_untyped( &self, bytecode_id: BytecodeId, parameters: Vec<u8>, instantiation_argument: Vec<u8>, required_application_ids: Vec<UserApplicationId>, ) -> Result<ClientOutcome<(UserApplicationId, 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 subscribe_to_new_committees( &self, ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError>

Starts listening to the admin chain for new committees. (This is only useful for other genesis chains or for testing.)

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

Stops listening to the admin chain for new committees. (This is only useful for testing.)

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

Deprecates all the configurations of voting rights but the last 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: Option<Owner>, amount: Amount, account: 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_hashed_confirmed_block( &self, hash: CryptoHash, ) -> Result<Hashed<ConfirmedBlock>, ViewError>

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

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

pub async fn read_hashed_confirmed_blocks_downward( &self, from: CryptoHash, limit: u32, ) -> Result<Vec<Hashed<ConfirmedBlock>>, ViewError>

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: P::Node, ) -> Result<(), ChainClientError>

Attempts to update a validator with the local information.

Trait Implementations

impl<P, S> Clone for ChainClient<P, S>

where S: Storage,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<ValidatorNodeProvider, Storage> Debug for ChainClient<ValidatorNodeProvider, Storage>

where Storage: Storage,

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

Formats the value using the given formatter.