Enum pallet_gear::pallet::Call

pub enum Call<T: Config>
where
    T::AccountId: Origin,
{
    upload_code {
        code: Vec<u8>,
    },
    upload_program {
        code: Vec<u8>,
        salt: Vec<u8>,
        init_payload: Vec<u8>,
        gas_limit: u64,
        value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance,
        keep_alive: bool,
    },
    create_program {
        code_id: CodeId,
        salt: Vec<u8>,
        init_payload: Vec<u8>,
        gas_limit: u64,
        value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance,
        keep_alive: bool,
    },
    send_message {
        destination: ProgramId,
        payload: Vec<u8>,
        gas_limit: u64,
        value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance,
        keep_alive: bool,
    },
    send_reply {
        reply_to_id: MessageId,
        payload: Vec<u8>,
        gas_limit: u64,
        value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance,
        keep_alive: bool,
    },
    claim_value {
        message_id: MessageId,
    },
    run {
        max_gas: Option<GasBalanceOf<T>>,
    },
    set_execute_inherent {
        value: bool,
    },
    claim_value_to_inheritor {
        program_id: ProgramId,
        depth: NonZero<u32>,
    },
    // some variants omitted
}

Contains a variant per dispatchable extrinsic that this pallet has.

Variants

upload_code

Saves program code in storage.

The extrinsic was created to provide deploy program from program functionality. Anyone who wants to define a “factory” logic in program should first store the code and metadata for the “child” program in storage. So the code for the child will be initialized by program initialization request only if it exists in storage.

More precisely, the code and its metadata are actually saved in the storage under the hash of the code. The code hash is computed as Blake256 hash. At the time of the call the code hash should not be in the storage. If it was stored previously, call will end up with an CodeAlreadyExists error. In this case user can be sure, that he can actually use the hash of his program’s code bytes to define “program factory” logic in his program.

Parameters

• code: wasm code of a program as a byte vector.

Emits the following events:

• SavedCode(H256) - when the code is saved in storage.

Fields

code: Vec<u8>

upload_program

Creates program initialization request (message), that is scheduled to be run in the same block.

There are no guarantees that initialization message will be run in the same block due to block gas limit restrictions. For example, when it will be the message’s turn, required gas limit for it could be more than remaining block gas limit. Therefore, the message processing will be postponed until the next block.

ProgramId is computed as Blake256 hash of concatenated bytes of code + salt. (todo #512 code_hash + salt) Such ProgramId must not exist in the Program Storage at the time of this call.

There is the same guarantee here as in upload_code. That is, future program’s code and metadata are stored before message was added to the queue and processed.

The origin must be Signed and the sender must have sufficient funds to pay for gas and value (in case the latter is being transferred).

Gear runtime guarantees that an active program always has an account to store value. If the underlying account management platform (e.g. Substrate’s System pallet) requires an existential deposit to keep an account alive, the related overhead is considered an extra cost related with a program instantiation and is charged to the program’s creator and is released back to the creator when the program is removed. In context of the above, the value parameter represents the so-called reducible balance a program should have at its disposal upon instantiation. It is not used to offset the existential deposit required for an account creation.

Parameters:

• code: wasm code of a program as a byte vector.
• salt: randomness term (a seed) to allow programs with identical code to be created independently.
• init_payload: encoded parameters of the wasm module init function.
• gas_limit: maximum amount of gas the program can spend before it is halted.
• value: balance to be transferred to the program once it’s been created.

Emits the following events:

• InitMessageEnqueued(MessageInfo) when init message is placed in the queue.

Note

Faulty (uninitialized) programs still have a valid addresses (program ids) that can deterministically be derived on the caller’s side upfront. It means that if messages are sent to such an address, they might still linger in the queue.

In order to mitigate the risk of users’ funds being sent to an address, where a valid program should have resided, while it’s not, such “failed-to-initialize” programs are not silently deleted from the program storage but rather marked as “ghost” programs. Ghost program can be removed by their original author via an explicit call. The funds stored by a ghost program will be release to the author once the program has been removed.

Fields

code: Vec<u8>

salt: Vec<u8>

init_payload: Vec<u8>

gas_limit: u64

value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance

keep_alive: bool

create_program

Creates program via code_id from storage.

Parameters:

• code_id: wasm code id in the code storage.
• salt: randomness term (a seed) to allow programs with identical code to be created independently.
• init_payload: encoded parameters of the wasm module init function.
• gas_limit: maximum amount of gas the program can spend before it is halted.
• value: balance to be transferred to the program once it’s been created.

Emits the following events:

• InitMessageEnqueued(MessageInfo) when init message is placed in the queue.

NOTE

For the details of this extrinsic, see upload_code.

Fields

code_id: CodeId

salt: Vec<u8>

init_payload: Vec<u8>

gas_limit: u64

value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance

keep_alive: bool

send_message

Sends a message to a program or to another account.

The origin must be Signed and the sender must have sufficient funds to pay for gas and value (in case the latter is being transferred).

To avoid an undefined behavior a check is made that the destination address is not a program in uninitialized state. If the opposite holds true, the message is not enqueued for processing.

Parameters:

• destination: the message destination.
• payload: in case of a program destination, parameters of the handle function.
• gas_limit: maximum amount of gas the program can spend before it is halted.
• value: balance to be transferred to the program once it’s been created.

Emits the following events:

• DispatchMessageEnqueued(MessageInfo) when dispatch message is placed in the queue.

Fields

destination: ProgramId

payload: Vec<u8>

gas_limit: u64

value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance

keep_alive: bool

send_reply

Send reply on message in Mailbox.

Removes message by given MessageId from callers Mailbox: rent funds become free, associated with the message value transfers from message sender to extrinsic caller.

Generates reply on removed message with given parameters and pushes it in MessageQueue.

NOTE: source of the message in mailbox guaranteed to be a program.

NOTE: only user who is destination of the message, can claim value or reply on the message from mailbox.

Fields

reply_to_id: MessageId

payload: Vec<u8>

gas_limit: u64

value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance

keep_alive: bool

claim_value

Claim value from message in Mailbox.

Removes message by given MessageId from callers Mailbox: rent funds become free, associated with the message value transfers from message sender to extrinsic caller.

NOTE: only user who is destination of the message, can claim value or reply on the message from mailbox.

Fields

message_id: MessageId

run

Process message queue

Fields

max_gas: Option<GasBalanceOf<T>>

set_execute_inherent

Sets ExecuteInherent flag.

Requires root origin (eventually, will only be set via referendum)

Fields

value: bool

claim_value_to_inheritor

Transfers value from chain of terminated or exited programs to its final inheritor.

depth parameter is how far to traverse to inheritor. A value of 10 is sufficient for most cases.

Example of chain

• Program #1 exits (e.g `gr_exit syscall) with argument pointing to user. Balance of program #1 has been sent to user.
• Program #2 exits with inheritor pointing to program #1. Balance of program #2 has been sent to exited program #1.
• Program #3 exits with inheritor pointing to program #2 Balance of program #1 has been sent to exited program #2.

So chain of inheritors looks like: Program #3 -> Program #2 -> Program #1 -> User.

We have programs #1 and #2 with stuck value on their balances. The balances should’ve been transferred to user (final inheritor) according to the chain. But protocol doesn’t traverse the chain automatically, so user have to call this extrinsic.

Fields

program_id: ProgramId

depth: NonZero<u32>

Implementations

impl<T: Config> Call<T>

where T::AccountId: Origin,

pub fn new_call_variant_upload_code(code: Vec<u8>) -> Self

Create a call with the variant upload_code.

pub fn new_call_variant_upload_program( code: Vec<u8>, salt: Vec<u8>, init_payload: Vec<u8>, gas_limit: u64, value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance, keep_alive: bool, ) -> Self

Create a call with the variant upload_program.

pub fn new_call_variant_create_program( code_id: CodeId, salt: Vec<u8>, init_payload: Vec<u8>, gas_limit: u64, value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance, keep_alive: bool, ) -> Self

Create a call with the variant create_program.

pub fn new_call_variant_send_message( destination: ProgramId, payload: Vec<u8>, gas_limit: u64, value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance, keep_alive: bool, ) -> Self

Create a call with the variant send_message.

pub fn new_call_variant_send_reply( reply_to_id: MessageId, payload: Vec<u8>, gas_limit: u64, value: <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance, keep_alive: bool, ) -> Self

Create a call with the variant send_reply.

pub fn new_call_variant_claim_value(message_id: MessageId) -> Self

Create a call with the variant claim_value.

pub fn new_call_variant_run(max_gas: Option<GasBalanceOf<T>>) -> Self

Create a call with the variant run.

pub fn new_call_variant_set_execute_inherent(value: bool) -> Self

Create a call with the variant set_execute_inherent.

pub fn new_call_variant_claim_value_to_inheritor( program_id: ProgramId, depth: NonZero<u32>, ) -> Self

Create a call with the variant claim_value_to_inheritor.

Trait Implementations

impl<T: Config> CheckIfFeeless for Call<T>

where T::AccountId: Origin,

type Origin = <T as Config>::RuntimeOrigin

The Origin type of the runtime.

fn is_feeless(&self, origin: &Self::Origin) -> bool

Checks if the dispatchable satisfies the feeless condition as defined by #[pallet::feeless_if]

impl<T: Config> Clone for Call<T>

where T::AccountId: Origin,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Config> Debug for Call<T>

where T::AccountId: Origin,

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

Formats the value using the given formatter.

impl<T: Config> Decode for Call<T>

where T::AccountId: Origin,

fn decode<__CodecInputEdqy: Input>( __codec_input_edqy: &mut __CodecInputEdqy, ) -> Result<Self, Error>

Attempt to deserialise the value from input.

fn decode_into<I>( input: &mut I, dst: &mut MaybeUninit<Self>, ) -> Result<DecodeFinished, Error>

where I: Input,

Attempt to deserialize the value from input into a pre-allocated piece of memory.

fn skip<I>(input: &mut I) -> Result<(), Error>

where I: Input,

Attempt to skip the encoded value from input.

fn encoded_fixed_size() -> Option<usize>

Returns the fixed encoded size of the type.

impl<T: Config> Encode for Call<T>

where T::AccountId: Origin,

fn size_hint(&self) -> usize

If possible give a hint of expected size of the encoding.

fn encode_to<__CodecOutputEdqy: Output + ?Sized>( &self, __codec_dest_edqy: &mut __CodecOutputEdqy, )

Convert self to a slice and append it to the destination.

fn encode(&self) -> Vec<u8>

Convert self to an owned vector.

fn using_encoded<R, F>(&self, f: F) -> R

where F: FnOnce(&[u8]) -> R,

Convert self to a slice and then invoke the given closure with it.

fn encoded_size(&self) -> usize

Calculates the encoded size.

impl<T: Config> GetCallIndex for Call<T>

where T::AccountId: Origin,

fn get_call_index(&self) -> u8

Return the index of this Call.

fn get_call_indices() -> &'static [u8]

Return all call indices in the same order as [GetCallName].

impl<T: Config> GetCallName for Call<T>

where T::AccountId: Origin,

fn get_call_name(&self) -> &'static str

Return the function name of the Call.

fn get_call_names() -> &'static [&'static str]

Return all function names in the same order as [GetCallIndex].

impl<T: Config> GetDispatchInfo for Call<T>

where T::AccountId: Origin,

fn get_dispatch_info(&self) -> DispatchInfo

Return a DispatchInfo, containing relevant information of this dispatch.

impl<T: Config> PartialEq for Call<T>

where T::AccountId: Origin,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> TypeInfo for Call<T>

where T::AccountId: Origin, PhantomData<(T,)>: TypeInfo + 'static, <<T as Config>::Currency as Currency<<T as Config>::AccountId>>::Balance: TypeInfo + 'static, Option<GasBalanceOf<T>>: TypeInfo + 'static, T: Config + 'static,

type Identity = Call<T>

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.

impl<T: Config> UnfilteredDispatchable for Call<T>

where T::AccountId: Origin,

type RuntimeOrigin = <T as Config>::RuntimeOrigin

The origin type of the runtime, (i.e. frame_system::Config::RuntimeOrigin).

fn dispatch_bypass_filter( self, origin: Self::RuntimeOrigin, ) -> DispatchResultWithPostInfo

Dispatch this call but do not check the filter in origin.

impl<T: Config> EncodeLike for Call<T>

where T::AccountId: Origin,

impl<T: Config> Eq for Call<T>

where T::AccountId: Origin,