Struct Runtime

pub struct Runtime<'a, R> { /* private fields */ }

Represents the runtime properties of a WASM execution.

Implementations

impl<'a, R> Runtime<'a, R>

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

pub fn call_contract( &mut self, contract_hash: AddressableEntityHash, entry_point_name: &str, args: RuntimeArgs, ) -> Result<CLValue, ExecError>

Calls contract living under a key, with supplied args.

pub fn call_versioned_contract( &mut self, contract_package_hash: PackageHash, contract_version: Option<EntityVersion>, entry_point_name: String, args: RuntimeArgs, ) -> Result<CLValue, ExecError>

Calls version of the contract living at key, invoking method with supplied args. This function also checks the args conform with the types given in the contract header.

pub fn take_host_buffer(&mut self) -> Option<CLValue>

If host_buffer set, clears the host_buffer and returns value, else None

Trait Implementations

impl<R> AccountProvider for Runtime<'_, R>

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

fn set_main_purse(&mut self, purse: URef)

Set main purse.

fn get_main_purse(&self) -> Result<URef, Error>

Get currently executing account’s purse.

impl<R> Auction for Runtime<'_, R>

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

fn get_era_validators( &mut self, ) -> Result<BTreeMap<EraId, BTreeMap<PublicKey, U512>>, Error>

Returns active validators and auction winners for a number of future eras determined by the configured auction_delay.

fn read_seigniorage_recipients( &mut self, ) -> Result<BTreeMap<PublicKey, SeigniorageRecipientV2>, Error>

Returns validators in era_validators, mapped to their bids or founding stakes, delegation rates and lists of delegators together with their delegated quantities from delegators. This function is publicly accessible, but intended for system use by the Handle Payment contract, because this data is necessary for distributing seigniorage.

fn add_bid( &mut self, public_key: PublicKey, delegation_rate: u8, amount: U512, minimum_delegation_amount: u64, maximum_delegation_amount: u64, minimum_bid_amount: u64, max_delegators_per_validator: u32, reserved_slots: u32, ) -> Result<U512, ApiError>

This entry point adds or modifies an entry in the Key::Bid section of the global state and creates (or tops off) a bid purse. Post genesis, any new call on this entry point causes a non-founding validator in the system to exist.

fn withdraw_bid( &mut self, public_key: PublicKey, amount: U512, minimum_bid_amount: u64, ) -> Result<U512, Error>

Unbonds aka reduces stake by specified amount, adding an entry to the unbonding queue. For a genesis validator, this is subject to vesting if applicable to a given network.

fn delegate( &mut self, delegator_kind: DelegatorKind, validator_public_key: PublicKey, amount: U512, max_delegators_per_validator: u32, ) -> Result<U512, ApiError>

Adds a new delegator to delegators or increases its current stake. If the target validator is missing, the function call returns an error and does nothing.

fn undelegate( &mut self, delegator_kind: DelegatorKind, validator_public_key: PublicKey, amount: U512, ) -> Result<U512, Error>

Unbonds aka reduces stake by specified amount, adding an entry to the unbonding queue

fn redelegate( &mut self, delegator_kind: DelegatorKind, validator_public_key: PublicKey, amount: U512, new_validator: PublicKey, ) -> Result<U512, Error>

Unbonds aka reduces stake by specified amount, adding an entry to the unbonding queue, which when processed will attempt to re-delegate the stake to the specified new validator. If this is not possible at that future point in time, the unbonded stake will instead downgrade to a standard undelegate operation automatically (the unbonded stake is returned to the associated purse).

fn forced_undelegate(&mut self) -> Result<(), Error>

Unbond delegator bids which fall outside validator-configured delegation limits.

fn add_reservations( &mut self, reservations: Vec<Reservation>, ) -> Result<(), Error>

Adds new reservations for a given validator with specified delegator public keys and delegation rates. If during adding reservations configured number of reserved delegator slots is exceeded it returns an error.

fn cancel_reservations( &mut self, validator: PublicKey, delegators: Vec<DelegatorKind>, max_delegators_per_validator: u32, ) -> Result<(), Error>

Removes reservations for given delegator public keys. If a reservation for one of the keys does not exist it returns an error.

fn slash(&mut self, validator_public_keys: Vec<PublicKey>) -> Result<(), Error>

Slashes each validator.

fn run_auction( &mut self, era_end_timestamp_millis: u64, evicted_validators: Vec<PublicKey>, max_delegators_per_validator: u32, include_credits: bool, credit_cap: Ratio<U512>, minimum_bid_amount: u64, ) -> Result<(), ApiError>

Takes active_bids and delegators to construct a list of validators’ total bids (their own added to their delegators’) ordered by size from largest to smallest, then takes the top N (number of auction slots) bidders and replaces era_validators with these.

fn distribute( &mut self, rewards: BTreeMap<PublicKey, Vec<U512>>, ) -> Result<(), Error>

Mint and distribute seigniorage rewards to validators and their delegators, according to reward_factors returned by the consensus component.

fn read_era_id(&mut self) -> Result<EraId, Error>

Reads current era id.

fn activate_bid( &mut self, validator: PublicKey, minimum_bid: u64, ) -> Result<(), Error>

Activates a given validator’s bid. To be used when a validator has been marked as inactive by consensus (aka “evicted”).

fn change_bid_public_key( &mut self, public_key: PublicKey, new_public_key: PublicKey, ) -> Result<(), Error>

Updates a ValidatorBid and all related delegator bids to use a new public key.

fn write_validator_credit( &mut self, validator: PublicKey, era_id: EraId, amount: U512, ) -> Result<Option<BidAddr>, Error>

Writes a validator credit record.

impl<R> Externals for Runtime<'_, R>

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

fn invoke_index( &mut self, index: usize, args: RuntimeArgs<'_>, ) -> Result<Option<RuntimeValue>, Trap>

Perform invoke of a host function by specified index.

impl<R> HandlePayment for Runtime<'_, R>

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

fn get_payment_purse(&mut self) -> Result<URef, Error>

Get payment purse.

fn set_refund_purse(&mut self, purse: URef) -> Result<(), Error>

Set refund purse.

fn get_refund_purse(&mut self) -> Result<Option<URef>, Error>

Get refund purse.

fn clear_refund_purse(&mut self) -> Result<(), Error>

Clear refund purse.

fn calculate_overpayment_and_fee( &mut self, limit: U512, gas_price: u8, cost: U512, consumed: U512, source_purse: URef, refund_ratio: Ratio<U512>, ) -> Result<(U512, U512), Error>

Calculate overpayment and fees (if any) for payment finalization.

fn distribute_accumulated_fees( &mut self, source_uref: URef, amount: Option<U512>, ) -> Result<(), Error>

Distribute fees from an accumulation purse.

fn payment_burn( &mut self, source_uref: URef, amount: Option<U512>, ) -> Result<(), Error>

Burns the imputed amount from the imputed purse.

impl<R> Mint for Runtime<'_, R>

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

fn purse_exists(&mut self, uref: URef) -> Result<bool, Error>

Check if a purse exists.

fn mint(&mut self, initial_balance: U512) -> Result<URef, Error>

Mint new token with given initial_balance balance. Returns new purse on success, otherwise an error.

fn burn(&mut self, purse: URef, amount: U512) -> Result<(), Error>

Burns native tokens.

fn reduce_total_supply(&mut self, amount: U512) -> Result<(), Error>

Reduce total supply by amount. Returns unit on success, otherwise an error.

fn balance(&mut self, purse: URef) -> Result<Option<U512>, Error>

Read balance of given purse.

fn transfer( &mut self, maybe_to: Option<AccountHash>, source: URef, target: URef, amount: U512, id: Option<u64>, ) -> Result<(), Error>

Transfers amount of tokens from source purse to a target purse.

fn read_base_round_reward(&mut self) -> Result<U512, Error>

Retrieves the base round reward.

fn mint_into_existing_purse( &mut self, existing_purse: URef, amount: U512, ) -> Result<(), Error>

Mint amount new token into existing_purse. Returns unit on success, otherwise an error.

impl<R> MintProvider for Runtime<'_, R>

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

fn mint_transfer_direct( &mut self, to: Option<AccountHash>, source: URef, target: URef, amount: U512, id: Option<u64>, ) -> Result<Result<(), Error>, Error>

Allows optimized auction and mint interaction. Intended to be used only by system contracts to manage staked purses. NOTE: Never expose this through FFI.

fn unbond( &mut self, unbond_kind: &UnbondKind, unbond_era: &UnbondEra, ) -> Result<(), Error>

Returns successfully unbonded stake to origin account.

fn mint_into_existing_purse( &mut self, amount: U512, existing_purse: URef, ) -> Result<(), Error>

Mint amount new token into existing_purse. Returns unit on success, otherwise an error.

fn create_purse(&mut self) -> Result<URef, Error>

Creates new purse.

fn available_balance(&mut self, purse: URef) -> Result<Option<U512>, Error>

Gets purse balance.

fn read_base_round_reward(&mut self) -> Result<U512, Error>

Reads the base round reward.

fn mint(&mut self, amount: U512) -> Result<URef, Error>

Mints new token with given initial_balance balance. Returns new purse on success, otherwise an error.

fn reduce_total_supply(&mut self, amount: U512) -> Result<(), Error>

Reduce total supply by amount. Returns unit on success, otherwise an error.

impl<R> MintProvider for Runtime<'_, R>

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

fn transfer_purse_to_account( &mut self, source: URef, target: AccountHash, amount: U512, ) -> Result<TransferredTo, Error>

Transfer amount from source purse to a target account. Note: the source should always be a system purse of some kind, such as the payment purse or an accumulator purse. The target should be the recipient of a refund or a reward

fn transfer_purse_to_purse( &mut self, source: URef, target: URef, amount: U512, ) -> Result<(), Error>

Transfer amount from source purse to a target purse. Note: the source should always be a system purse of some kind, such as the payment purse or an accumulator purse. The target should be the recipient of a refund or a reward

fn available_balance(&mut self, purse: URef) -> Result<Option<U512>, Error>

Checks balance of a purse. Returns None if given purse does not exist.

fn reduce_total_supply(&mut self, amount: U512) -> Result<(), Error>

Reduce total supply by amount.

impl<R> RuntimeProvider for Runtime<'_, R>

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

fn get_caller(&self) -> AccountHash

This method should return the caller of the current context.

fn is_allowed_session_caller(&self, account_hash: &AccountHash) -> bool

Checks if account_hash matches the active session’s account.

fn is_valid_uref(&self, uref: URef) -> bool

Checks if uref is in access rights.

fn named_keys_get(&self, name: &str) -> Option<Key>

Gets named key under a name.

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

Gets keys in a given keyspace

fn get_keys_by_prefix(&mut self, prefix: &[u8]) -> Result<Vec<Key>, Error>

Gets keys by prefix.

fn delegator_count(&mut self, bid_addr: &BidAddr) -> Result<usize, Error>

Returns the current number of delegators for this validator.

fn reservation_count(&mut self, bid_addr: &BidAddr) -> Result<usize, Error>

Returns number of reservations for this validator.

fn used_reservation_count(&mut self, bid_addr: &BidAddr) -> Result<usize, Error>

Returns number of reservations for which a delegator bid exists.

fn vesting_schedule_period_millis(&self) -> u64

Returns vesting schedule period.

fn allow_auction_bids(&self) -> bool

Check if auction bids are allowed.

fn should_compute_rewards(&self) -> bool

Check if auction should compute rewards.

impl<R> RuntimeProvider for Runtime<'_, R>

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

fn get_key(&mut self, name: &str) -> Option<Key>

Get named key under a name.

fn put_key(&mut self, name: &str, key: Key) -> Result<(), Error>

Put key under a name.

fn remove_key(&mut self, name: &str) -> Result<(), Error>

Remove a named key by name.

fn get_phase(&self) -> Phase

Get current execution phase.

fn get_caller(&self) -> AccountHash

Get caller.

fn refund_handling(&self) -> RefundHandling

Get refund handling.

fn fee_handling(&self) -> FeeHandling

Returns fee handling value.

fn administrative_accounts(&self) -> BTreeSet<AccountHash>

Returns list of administrative accounts.

impl<R> RuntimeProvider for Runtime<'_, R>

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

fn is_valid_uref(&self, uref: &URef) -> bool

Validate URef against context access rights.

fn get_caller(&self) -> AccountHash

This method should return the caller of the current context.

fn get_immediate_caller(&self) -> Option<Caller>

This method should return the immediate caller of the current context.

fn is_called_from_standard_payment(&self) -> bool

Is the caller standard payment logic?

fn get_system_entity_registry( &self, ) -> Result<SystemHashRegistry, ProviderError>

Get system entity registry.

fn runtime_footprint_by_account_hash( &mut self, account_hash: AccountHash, ) -> Result<Option<RuntimeFootprint>, ProviderError>

Read addressable entity by account hash.

fn get_phase(&self) -> Phase

Gets execution phase

fn get_key(&self, name: &str) -> Option<Key>

This method should handle obtaining a given named Key under a name.

fn get_approved_spending_limit(&self) -> U512

Returns approved CSPR spending limit.

fn sub_approved_spending_limit(&mut self, transferred: U512)

Signal to host that amount of tokens has been transferred.

fn get_main_purse(&self) -> Option<URef>

Returns main purse of the sender account.

fn is_administrator(&self, account_hash: &AccountHash) -> bool

Returns true if the account hash belongs to an administrator account, otherwise false.

fn allow_unrestricted_transfers(&self) -> bool

Checks if users can perform unrestricted transfers. This option is valid only for private chains.

impl<R> StorageProvider for Runtime<'_, R>

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

fn read<T: FromBytes + CLTyped>( &mut self, uref: URef, ) -> Result<Option<T>, Error>

Reads data from URef.

fn write<T: ToBytes + CLTyped>( &mut self, uref: URef, value: T, ) -> Result<(), Error>

Writes data to `URef.

fn read_bid(&mut self, key: &Key) -> Result<Option<BidKind>, Error>

Reads casper_types::system::auction::Bid at account hash derived from given public key

fn write_bid(&mut self, key: Key, bid_kind: BidKind) -> Result<(), Error>

Writes given BidKind at given key.

fn read_unbond(&mut self, bid_addr: BidAddr) -> Result<Option<Unbond>, Error>

Reads Unbonds at bid address.

fn write_unbond( &mut self, bid_addr: BidAddr, unbond: Option<Unbond>, ) -> Result<(), Error>

Writes given Unbond if some, else prunes if none at bid address.

fn record_era_info(&mut self, era_info: EraInfo) -> Result<(), Error>

Records era info.

fn prune_bid(&mut self, bid_addr: BidAddr)

Prunes a given bid at BidAddr.

impl<R> StorageProvider for Runtime<'_, R>

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

fn write_balance(&mut self, purse_uref: URef, amount: U512) -> Result<(), Error>

Write new balance.

impl<R> StorageProvider for Runtime<'_, R>

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

fn new_uref<T: CLTyped + ToBytes>(&mut self, init: T) -> Result<URef, Error>

Create new URef.

fn read<T: CLTyped + FromBytes>( &mut self, uref: URef, ) -> Result<Option<T>, Error>

Read data from URef.

fn write_amount(&mut self, uref: URef, amount: U512) -> Result<(), Error>

Write a U512 amount under a URef.

fn add<T: CLTyped + ToBytes>( &mut self, uref: URef, value: T, ) -> Result<(), Error>

Add data to a URef.

fn total_balance(&mut self, purse: URef) -> Result<U512, Error>

Read total balance.

fn available_balance(&mut self, purse: URef) -> Result<Option<U512>, Error>

Read balance.

fn write_balance(&mut self, uref: URef, balance: U512) -> Result<(), Error>

Write balance.

fn add_balance(&mut self, uref: URef, value: U512) -> Result<(), Error>

Add amount to an existing balance.

impl<R> SystemProvider for Runtime<'_, R>

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

fn record_transfer( &mut self, maybe_to: Option<AccountHash>, source: URef, target: URef, amount: U512, id: Option<u64>, ) -> Result<(), Error>

Records a transfer.