Trait concordium_std::HasHost
source · pub trait HasHost<State>: Sized {
type StateApiType: HasStateApi;
type ReturnValueType: HasCallResponse + Debug;
Show 15 methods
// Required methods
fn invoke_transfer(
&self,
receiver: &AccountAddress,
amount: Amount
) -> TransferResult;
fn invoke_contract_raw(
&mut self,
to: &ContractAddress,
parameter: Parameter<'_>,
method: EntrypointName<'_>,
amount: Amount
) -> CallContractResult<Self::ReturnValueType>;
fn upgrade(&mut self, module: ModuleReference) -> UpgradeResult;
fn invoke_contract_raw_read_only(
&self,
to: &ContractAddress,
parameter: Parameter<'_>,
method: EntrypointName<'_>,
amount: Amount
) -> ReadOnlyCallContractResult<Self::ReturnValueType>;
fn exchange_rates(&self) -> ExchangeRates;
fn account_balance(
&self,
address: AccountAddress
) -> QueryAccountBalanceResult;
fn contract_balance(
&self,
address: ContractAddress
) -> QueryContractBalanceResult;
fn state(&self) -> &State;
fn state_mut(&mut self) -> &mut State;
fn commit_state(&mut self);
fn state_builder(&mut self) -> &mut StateBuilder<Self::StateApiType>;
fn state_and_builder(
&mut self
) -> (&mut State, &mut StateBuilder<Self::StateApiType>);
fn self_balance(&self) -> Amount;
// Provided methods
fn invoke_contract<P: Serial>(
&mut self,
to: &ContractAddress,
parameter: &P,
method: EntrypointName<'_>,
amount: Amount
) -> CallContractResult<Self::ReturnValueType> { ... }
fn invoke_contract_read_only<P: Serial>(
&self,
to: &ContractAddress,
parameter: &P,
method: EntrypointName<'_>,
amount: Amount
) -> ReadOnlyCallContractResult<Self::ReturnValueType> { ... }
}
Expand description
A type that can serve as the host, meaning that it supports interactions with the chain, such as querying balance of the contract, accessing its state, and invoking operations on other contracts and accounts.
The trait is parameterized by the State
type. This is the type of the
contract state that the particular contract operates on.
Required Associated Types§
sourcetype StateApiType: HasStateApi
type StateApiType: HasStateApi
The type of low-level state that is associated with the host. This provides access to low-level state operations.
sourcetype ReturnValueType: HasCallResponse + Debug
type ReturnValueType: HasCallResponse + Debug
The type of return values this host provides. This is the raw return value. The intention is that it will be deserialized by the consumer, via the Read implementation.
The Debug requirement exists so that consumers of this trait may use methods like ExpectReport::expect_report.
Required Methods§
sourcefn invoke_transfer(
&self,
receiver: &AccountAddress,
amount: Amount
) -> TransferResult
fn invoke_transfer( &self, receiver: &AccountAddress, amount: Amount ) -> TransferResult
Perform a transfer to the given account if the contract has sufficient balance.
sourcefn invoke_contract_raw(
&mut self,
to: &ContractAddress,
parameter: Parameter<'_>,
method: EntrypointName<'_>,
amount: Amount
) -> CallContractResult<Self::ReturnValueType>
fn invoke_contract_raw( &mut self, to: &ContractAddress, parameter: Parameter<'_>, method: EntrypointName<'_>, amount: Amount ) -> CallContractResult<Self::ReturnValueType>
Invoke a given method of a contract with the amount and parameter provided. If invocation succeeds then the return value is a pair of a boolean which indicates whether the state of the contract has changed or not, and a possible return value. The return value is present if and only if a V1 contract was invoked.
sourcefn upgrade(&mut self, module: ModuleReference) -> UpgradeResult
fn upgrade(&mut self, module: ModuleReference) -> UpgradeResult
Upgrade the module for this instance to a given module. The new module must contain a smart contract with a matching name. Invocations of this instance after the point of a successful upgrade, will use the new smart contract module. The remaining code after a successful upgrade in the same invokation is executed as normal.
This will fail if:
- The supplied module is not deployed.
- The supplied module does not contain a smart contract with a name matching this instance.
- The supplied module is a version 0 smart contract module.
sourcefn invoke_contract_raw_read_only(
&self,
to: &ContractAddress,
parameter: Parameter<'_>,
method: EntrypointName<'_>,
amount: Amount
) -> ReadOnlyCallContractResult<Self::ReturnValueType>
fn invoke_contract_raw_read_only( &self, to: &ContractAddress, parameter: Parameter<'_>, method: EntrypointName<'_>, amount: Amount ) -> ReadOnlyCallContractResult<Self::ReturnValueType>
Invoke a given method of a contract with the amount and parameter
provided. If invocation succeeds and the state of the contract
instance is not modified then the return value is the return value
of the contract that was invoked. The return value is present (i.e.,
not None
) if and only if a V1 contract was invoked. If the
invocation succeeds but the state of the contract is modified then
this method will panic.
Warning: If the state of the contract was modified prior, i.e., if a mutable reference obtained via
state_mut
was used to modify the state then the state must be manually stored via thecommit_state
function, otherwise it will not be seen by the callee.
sourcefn exchange_rates(&self) -> ExchangeRates
fn exchange_rates(&self) -> ExchangeRates
Get the current exchange rates used by the chain. That is a Euro per Energy rate and micro CCD per Euro rate.
sourcefn account_balance(&self, address: AccountAddress) -> QueryAccountBalanceResult
fn account_balance(&self, address: AccountAddress) -> QueryAccountBalanceResult
Get the current public balance of an account. Here public means
unencrypted or unshielded. See
AccountBalance
for more.
This query will fail if the provided address does not exist on chain.
Any amount received by transfers during the transaction until the point of querying are reflected in this balance.
let balance_before = host.account_balance(account)?;
host.invoke_transfer(&account, amount)?;
let balance_after = host.account_balance(account)?; // balance_before + amount
Note: Querying the account invoking this transaction, will return the current account balance subtracted the amount of CCD reserved for paying the entire energy limit and the amount sent as part of update transaction.
sourcefn contract_balance(
&self,
address: ContractAddress
) -> QueryContractBalanceResult
fn contract_balance( &self, address: ContractAddress ) -> QueryContractBalanceResult
Get the current balance of a contract instance.
Any amount sent and received by transfers and invocations until the point of querying are reflected in this balance. This query will fail if the provided address does not exist on chain.
let balance_before = host.contract_balance(contract_address)?;
host.invoke_contract(&contract_address, ..., amount)?;
let balance_after = host.contract_balance(contract_address)?; // balance_before + amount
Note: Querying the contract itself returns the balance of the contract including the amount transferred as part of the invocation.
sourcefn state_mut(&mut self) -> &mut State
fn state_mut(&mut self) -> &mut State
Get a mutable reference to the contract state.
sourcefn commit_state(&mut self)
fn commit_state(&mut self)
Make sure the contract state is fully written out, so that any changes that were done in-memory up to the point in contract execution are reflected in the actual contract state maintained by the node.
sourcefn state_builder(&mut self) -> &mut StateBuilder<Self::StateApiType>
fn state_builder(&mut self) -> &mut StateBuilder<Self::StateApiType>
Get the state_builder for the contract state.
sourcefn state_and_builder(
&mut self
) -> (&mut State, &mut StateBuilder<Self::StateApiType>)
fn state_and_builder( &mut self ) -> (&mut State, &mut StateBuilder<Self::StateApiType>)
Get a mutable reference to both the state and the builder.
This is required due to limitations of the Rust type system, since
otherwise it is not possible to get the reference to the state and
the state builder at the same time. Once some incarnation of “view
types” is stable this will likely be possible to remove, and the
types of state_builder
and state_mut
can be refined.
sourcefn self_balance(&self) -> Amount
fn self_balance(&self) -> Amount
Get the contract’s own current balance. Upon entry to the entrypoint the balance that is returned is the sum of balance of the contract at the time of the invocation and the amount that is being transferred to the contract.
Provided Methods§
sourcefn invoke_contract<P: Serial>(
&mut self,
to: &ContractAddress,
parameter: &P,
method: EntrypointName<'_>,
amount: Amount
) -> CallContractResult<Self::ReturnValueType>
fn invoke_contract<P: Serial>( &mut self, to: &ContractAddress, parameter: &P, method: EntrypointName<'_>, amount: Amount ) -> CallContractResult<Self::ReturnValueType>
Like invoke_contract_raw
, except that the
parameter is automatically serialized. If the parameter already
implements AsRef<[u8]>
or can be equivalently cheaply
converted to a byte array, then
invoke_contract_raw
should be
used, since it avoids intermediate allocations.
sourcefn invoke_contract_read_only<P: Serial>(
&self,
to: &ContractAddress,
parameter: &P,
method: EntrypointName<'_>,
amount: Amount
) -> ReadOnlyCallContractResult<Self::ReturnValueType>
fn invoke_contract_read_only<P: Serial>( &self, to: &ContractAddress, parameter: &P, method: EntrypointName<'_>, amount: Amount ) -> ReadOnlyCallContractResult<Self::ReturnValueType>
Like invoke_contract_raw_read_only
, except that the parameter is
automatically serialized. If the parameter already implements
AsRef<[u8]>
or can be equivalently cheaply converted to a
byte array, then invoke_contract_raw
should be used, since it avoids intermediate allocations.
Warning: If the state of the contract was modified prior, i.e., if a mutable reference obtained via
state_mut
was used to modify the state then the state must be manually stored via thecommit_state
function, otherwise it will not be seen by the callee.