Trait fil_actors_shared::v14::runtime::Runtime

pub trait Runtime: Primitives + RuntimePolicy {
    type Blockstore: Blockstore;

    // Required methods
    fn network_version(&self) -> NetworkVersion;
    fn message(&self) -> &dyn MessageInfo;
    fn curr_epoch(&self) -> ChainEpoch;
    fn chain_id(&self) -> ChainID;
    fn validate_immediate_caller_accept_any(&self) -> Result<(), ActorError>;
    fn validate_immediate_caller_is<'a, I>(
        &self,
        addresses: I,
    ) -> Result<(), ActorError>
       where I: IntoIterator<Item = &'a Address>;
    fn validate_immediate_caller_namespace<I>(
        &self,
        namespace_manager_addresses: I,
    ) -> Result<(), ActorError>
       where I: IntoIterator<Item = u64>;
    fn validate_immediate_caller_type<'a, I>(
        &self,
        types: I,
    ) -> Result<(), ActorError>
       where I: IntoIterator<Item = &'a Type>;
    fn current_balance(&self) -> TokenAmount;
    fn actor_balance(&self, id: ActorID) -> Option<TokenAmount>;
    fn resolve_address(&self, address: &Address) -> Option<ActorID>;
    fn lookup_delegated_address(&self, id: ActorID) -> Option<Address>;
    fn get_actor_code_cid(&self, id: &ActorID) -> Option<Cid>;
    fn get_randomness_from_tickets(
        &self,
        personalization: DomainSeparationTag,
        rand_epoch: ChainEpoch,
        entropy: &[u8],
    ) -> Result<[u8; 32], ActorError>;
    fn get_randomness_from_beacon(
        &self,
        personalization: DomainSeparationTag,
        rand_epoch: ChainEpoch,
        entropy: &[u8],
    ) -> Result<[u8; 32], ActorError>;
    fn get_state_root(&self) -> Result<Cid, ActorError>;
    fn set_state_root(&self, root: &Cid) -> Result<(), ActorError>;
    fn transaction<S, RT, F>(&self, f: F) -> Result<RT, ActorError>
       where S: Serialize + DeserializeOwned,
             F: FnOnce(&mut S, &Self) -> Result<RT, ActorError>;
    fn store(&self) -> &Self::Blockstore;
    fn send(
        &self,
        to: &Address,
        method: MethodNum,
        params: Option<IpldBlock>,
        value: TokenAmount,
        gas_limit: Option<u64>,
        flags: SendFlags,
    ) -> Result<Response, SendError>;
    fn new_actor_address(&self) -> Result<Address, ActorError>;
    fn create_actor(
        &self,
        code_id: Cid,
        actor_id: ActorID,
        predictable_address: Option<Address>,
    ) -> Result<(), ActorError>;
    fn delete_actor(&self) -> Result<(), ActorError>;
    fn resolve_builtin_actor_type(&self, code_id: &Cid) -> Option<Type>;
    fn get_code_cid_for_type(&self, typ: Type) -> Cid;
    fn total_fil_circ_supply(&self) -> TokenAmount;
    fn charge_gas(&self, name: &'static str, compute: i64);
    fn base_fee(&self) -> TokenAmount;
    fn gas_available(&self) -> u64;
    fn tipset_timestamp(&self) -> u64;
    fn tipset_cid(&self, epoch: i64) -> Result<Cid, ActorError>;
    fn emit_event(&self, event: &ActorEvent) -> Result<(), ActorError>;
    fn read_only(&self) -> bool;

    // Provided methods
    fn create<T: Serialize>(&self, obj: &T) -> Result<(), ActorError> { ... }
    fn state<T: DeserializeOwned>(&self) -> Result<T, ActorError> { ... }
    fn send_simple(
        &self,
        to: &Address,
        method: MethodNum,
        params: Option<IpldBlock>,
        value: TokenAmount,
    ) -> Result<Response, SendError> { ... }
}

Runtime is the VM’s internal runtime object. this is everything that is accessible to actors, beyond parameters.

Required Associated Types

type Blockstore: Blockstore

Required Methods

fn network_version(&self) -> NetworkVersion

The network protocol version number at the current epoch.

fn message(&self) -> &dyn MessageInfo

Information related to the current message being executed.

fn curr_epoch(&self) -> ChainEpoch

The current chain epoch number, corresponding to the epoch in which the message is executed. The genesis block has epoch zero.

fn chain_id(&self) -> ChainID

The ID for this chain. Filecoin chain IDs are usually in the Ethereum namespace, see: https://github.com/ethereum-lists/chains.

fn validate_immediate_caller_accept_any(&self) -> Result<(), ActorError>

Validates the caller against some predicate. Exported actor methods must invoke at least one caller validation before returning.

fn validate_immediate_caller_is<'a, I>( &self, addresses: I, ) -> Result<(), ActorError>

where I: IntoIterator<Item = &'a Address>,

fn validate_immediate_caller_namespace<I>( &self, namespace_manager_addresses: I, ) -> Result<(), ActorError>

where I: IntoIterator<Item = u64>,

Validates that the caller has a delegated address that is a member of one of the provided namespaces. Addresses must be of Protocol ID.

fn validate_immediate_caller_type<'a, I>( &self, types: I, ) -> Result<(), ActorError>

where I: IntoIterator<Item = &'a Type>,

fn current_balance(&self) -> TokenAmount

The balance of the receiver.

fn actor_balance(&self, id: ActorID) -> Option<TokenAmount>

The balance of an actor.

fn resolve_address(&self, address: &Address) -> Option<ActorID>

Resolves an address of any protocol to an ID address (via the Init actor’s table). This allows resolution of externally-provided SECP, BLS, or actor addresses to the canonical form. If the argument is an ID address it is returned directly.

fn lookup_delegated_address(&self, id: ActorID) -> Option<Address>

Looks up the “delegated” address of an actor by ID, if any. Returns None if either the target actor doesn’t exist, or doesn’t have an f4 address.

fn get_actor_code_cid(&self, id: &ActorID) -> Option<Cid>

Look up the code ID at an actor address.

fn get_randomness_from_tickets( &self, personalization: DomainSeparationTag, rand_epoch: ChainEpoch, entropy: &[u8], ) -> Result<[u8; 32], ActorError>

Randomness returns a (pseudo)random byte array drawing from the latest ticket chain from a given epoch and incorporating requisite entropy. This randomness is fork dependant but also biasable because of this.

fn get_randomness_from_beacon( &self, personalization: DomainSeparationTag, rand_epoch: ChainEpoch, entropy: &[u8], ) -> Result<[u8; 32], ActorError>

Randomness returns a (pseudo)random byte array drawing from the latest beacon from a given epoch and incorporating requisite entropy. This randomness is not tied to any fork of the chain, and is unbiasable.

fn get_state_root(&self) -> Result<Cid, ActorError>

Gets the state-root.

fn set_state_root(&self, root: &Cid) -> Result<(), ActorError>

Sets the state-root.

fn transaction<S, RT, F>(&self, f: F) -> Result<RT, ActorError>

where S: Serialize + DeserializeOwned, F: FnOnce(&mut S, &Self) -> Result<RT, ActorError>,

Loads a mutable copy of the state of the receiver, passes it to f, and after f completes puts the state object back to the store and sets it as the receiver’s state root.

During the call to f, execution is protected from side-effects, (including message send).

Returns the result of f.

fn store(&self) -> &Self::Blockstore

Returns reference to blockstore

fn send( &self, to: &Address, method: MethodNum, params: Option<IpldBlock>, value: TokenAmount, gas_limit: Option<u64>, flags: SendFlags, ) -> Result<Response, SendError>

Sends a message to another actor, returning the exit code and return value envelope. If the invoked method does not return successfully, its state changes (and that of any messages it sent in turn) will be rolled back.

fn new_actor_address(&self) -> Result<Address, ActorError>

Computes an address for a new actor. The returned address is intended to uniquely refer to the actor even in the event of a chain re-org (whereas an ID-address might refer to a different actor after messages are re-ordered). Always an ActorExec address.

fn create_actor( &self, code_id: Cid, actor_id: ActorID, predictable_address: Option<Address>, ) -> Result<(), ActorError>

Creates an actor with code codeID, an empty state, id actor_id, and an optional predictable address. May only be called by Init actor.

fn delete_actor(&self) -> Result<(), ActorError>

Deletes the executing actor from the state tree. Fails if there is any unspent balance in the actor.

May only be called by the actor itself.

fn resolve_builtin_actor_type(&self, code_id: &Cid) -> Option<Type>

Returns whether the specified CodeCID belongs to a built-in actor.

fn get_code_cid_for_type(&self, typ: Type) -> Cid

Returns the CodeCID for a built-in actor type. The kernel will abort if the supplied type is invalid.

fn total_fil_circ_supply(&self) -> TokenAmount

Returns the total token supply in circulation at the beginning of the current epoch. The circulating supply is the sum of:

• rewards emitted by the reward actor,
• funds vested from lock-ups in the genesis state,

less the sum of:

• funds burnt,
• pledge collateral locked in storage miner actors (recorded in the storage power actor)
• deal collateral locked by the storage market actor

fn charge_gas(&self, name: &'static str, compute: i64)

ChargeGas charges specified amount of gas for execution. name provides information about gas charging point

fn base_fee(&self) -> TokenAmount

Returns the gas base fee (cost per unit) for the current epoch.

fn gas_available(&self) -> u64

The gas still available for computation

fn tipset_timestamp(&self) -> u64

The timestamp of the tipset at the current epoch (see curr_epoch), as UNIX seconds.

fn tipset_cid(&self, epoch: i64) -> Result<Cid, ActorError>

The CID of the tipset at the specified epoch. The epoch must satisfy: (curr_epoch - FINALITY) < epoch <= curr_epoch

fn emit_event(&self, event: &ActorEvent) -> Result<(), ActorError>

Emits an event denoting that something externally noteworthy has ocurred.

fn read_only(&self) -> bool

Returns true if the call is read_only. All state updates, including actor creation and balance transfers, are rejected in read_only calls.

Provided Methods

fn create<T: Serialize>(&self, obj: &T) -> Result<(), ActorError>

Initializes the state object. This is only valid when the state has not yet been initialized. NOTE: we should also limit this to being invoked during the constructor method

fn state<T: DeserializeOwned>(&self) -> Result<T, ActorError>

Loads a readonly copy of the state of the receiver into the argument.

fn send_simple( &self, to: &Address, method: MethodNum, params: Option<IpldBlock>, value: TokenAmount, ) -> Result<Response, SendError>

Simplified version of Runtime::send that does not specify a gas limit, nor any send flags.

Object Safety

This trait is not object safe.

Implementors