Trait Externalities

pub trait Externalities {
    type UnrecoverableError;
    type FallibleError;
    type AllocError: Display;

    // Required methods
    fn alloc<Context>(
        &mut self,
        ctx: &mut Context,
        mem: &mut impl Memory<Context>,
        pages_num: u32,
    ) -> Result<WasmPage, Self::AllocError>;
    fn free(&mut self, page: WasmPage) -> Result<(), Self::AllocError>;
    fn free_range(
        &mut self,
        start: WasmPage,
        end: WasmPage,
    ) -> Result<(), Self::AllocError>;
    fn env_vars(
        &self,
        version: u32,
    ) -> Result<EnvVars, Self::UnrecoverableError>;
    fn block_height(&self) -> Result<u32, Self::UnrecoverableError>;
    fn block_timestamp(&self) -> Result<u64, Self::UnrecoverableError>;
    fn send_init(&mut self) -> Result<u32, Self::FallibleError>;
    fn send_push(
        &mut self,
        handle: u32,
        buffer: &[u8],
    ) -> Result<(), Self::FallibleError>;
    fn send_commit(
        &mut self,
        handle: u32,
        msg: HandlePacket,
        delay: u32,
    ) -> Result<MessageId, Self::FallibleError>;
    fn send_push_input(
        &mut self,
        handle: u32,
        offset: u32,
        len: u32,
    ) -> Result<(), Self::FallibleError>;
    fn reservation_send_commit(
        &mut self,
        id: ReservationId,
        handle: u32,
        msg: HandlePacket,
        delay: u32,
    ) -> Result<MessageId, Self::FallibleError>;
    fn reply_push(&mut self, buffer: &[u8]) -> Result<(), Self::FallibleError>;
    fn reply_commit(
        &mut self,
        msg: ReplyPacket,
    ) -> Result<MessageId, Self::FallibleError>;
    fn reservation_reply_commit(
        &mut self,
        id: ReservationId,
        msg: ReplyPacket,
    ) -> Result<MessageId, Self::FallibleError>;
    fn reply_to(&self) -> Result<MessageId, Self::FallibleError>;
    fn signal_from(&self) -> Result<MessageId, Self::FallibleError>;
    fn reply_push_input(
        &mut self,
        offset: u32,
        len: u32,
    ) -> Result<(), Self::FallibleError>;
    fn source(&self) -> Result<ProgramId, Self::UnrecoverableError>;
    fn reply_code(&self) -> Result<ReplyCode, Self::FallibleError>;
    fn signal_code(&self) -> Result<SignalCode, Self::FallibleError>;
    fn message_id(&self) -> Result<MessageId, Self::UnrecoverableError>;
    fn program_id(&self) -> Result<ProgramId, Self::UnrecoverableError>;
    fn debug(&self, data: &str) -> Result<(), Self::UnrecoverableError>;
    fn lock_payload(
        &mut self,
        at: u32,
        len: u32,
    ) -> Result<PayloadSliceLock, Self::FallibleError>;
    fn unlock_payload(
        &mut self,
        payload_holder: &mut PayloadSliceLock,
    ) -> UnlockPayloadBound;
    fn size(&self) -> Result<usize, Self::UnrecoverableError>;
    fn random(&self) -> Result<(&[u8], u32), Self::UnrecoverableError>;
    fn reserve_gas(
        &mut self,
        amount: u64,
        duration: u32,
    ) -> Result<ReservationId, Self::FallibleError>;
    fn unreserve_gas(
        &mut self,
        id: ReservationId,
    ) -> Result<u64, Self::FallibleError>;
    fn system_reserve_gas(
        &mut self,
        amount: u64,
    ) -> Result<(), Self::FallibleError>;
    fn gas_available(&self) -> Result<u64, Self::UnrecoverableError>;
    fn value(&self) -> Result<u128, Self::UnrecoverableError>;
    fn value_available(&self) -> Result<u128, Self::UnrecoverableError>;
    fn wait(&mut self) -> Result<(), Self::UnrecoverableError>;
    fn wait_for(
        &mut self,
        duration: u32,
    ) -> Result<(), Self::UnrecoverableError>;
    fn wait_up_to(
        &mut self,
        duration: u32,
    ) -> Result<bool, Self::UnrecoverableError>;
    fn wake(
        &mut self,
        waker_id: MessageId,
        delay: u32,
    ) -> Result<(), Self::FallibleError>;
    fn create_program(
        &mut self,
        packet: InitPacket,
        delay: u32,
    ) -> Result<(MessageId, ProgramId), Self::FallibleError>;
    fn reply_deposit(
        &mut self,
        message_id: MessageId,
        amount: u64,
    ) -> Result<(), Self::FallibleError>;
    fn forbidden_funcs(&self) -> &BTreeSet<SyscallName>;

    // Provided methods
    fn send(
        &mut self,
        msg: HandlePacket,
        delay: u32,
    ) -> Result<MessageId, Self::FallibleError> { ... }
    fn reservation_send(
        &mut self,
        id: ReservationId,
        msg: HandlePacket,
        delay: u32,
    ) -> Result<MessageId, Self::FallibleError> { ... }
    fn reply(
        &mut self,
        msg: ReplyPacket,
    ) -> Result<MessageId, Self::FallibleError> { ... }
    fn reservation_reply(
        &mut self,
        id: ReservationId,
        msg: ReplyPacket,
    ) -> Result<MessageId, Self::FallibleError> { ... }
}

External api and data for managing memory and messages, use by an executing program to trigger state transition in runtime.

Required Associated Types

type UnrecoverableError

An error issued in infallible syscall.

type FallibleError

An error issued in fallible syscall.

type AllocError: Display

An error issued during allocation.

Required Methods

fn alloc<Context>( &mut self, ctx: &mut Context, mem: &mut impl Memory<Context>, pages_num: u32, ) -> Result<WasmPage, Self::AllocError>

Allocate number of pages.

The resulting page number should point to pages consecutive memory pages.

fn free(&mut self, page: WasmPage) -> Result<(), Self::AllocError>

Free specific page.

fn free_range( &mut self, start: WasmPage, end: WasmPage, ) -> Result<(), Self::AllocError>

Free specific memory range.

fn env_vars(&self, version: u32) -> Result<EnvVars, Self::UnrecoverableError>

Get environment variables currently set in the system and in the form corresponded to the requested version.

fn block_height(&self) -> Result<u32, Self::UnrecoverableError>

Get the current block height.

fn block_timestamp(&self) -> Result<u64, Self::UnrecoverableError>

Get the current block timestamp.

fn send_init(&mut self) -> Result<u32, Self::FallibleError>

Initialize a new incomplete message for another program and return its handle.

fn send_push( &mut self, handle: u32, buffer: &[u8], ) -> Result<(), Self::FallibleError>

Push an extra buffer into message payload by handle.

fn send_commit( &mut self, handle: u32, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>

Complete message and send it to another program.

fn send_push_input( &mut self, handle: u32, offset: u32, len: u32, ) -> Result<(), Self::FallibleError>

Push the incoming message buffer into message payload by handle.

fn reservation_send_commit( &mut self, id: ReservationId, handle: u32, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>

Complete message and send it to another program using gas from reservation.

fn reply_push(&mut self, buffer: &[u8]) -> Result<(), Self::FallibleError>

Push an extra buffer into reply message.

fn reply_commit( &mut self, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>

Complete reply message and send it to source program.

fn reservation_reply_commit( &mut self, id: ReservationId, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>

Complete reply message and send it to source program from reservation.

fn reply_to(&self) -> Result<MessageId, Self::FallibleError>

Get the message id of the initial message.

fn signal_from(&self) -> Result<MessageId, Self::FallibleError>

Get the message id which signal issues from.

fn reply_push_input( &mut self, offset: u32, len: u32, ) -> Result<(), Self::FallibleError>

Push the incoming message buffer into reply message.

fn source(&self) -> Result<ProgramId, Self::UnrecoverableError>

Get the source of the message currently being handled.

fn reply_code(&self) -> Result<ReplyCode, Self::FallibleError>

Get the reply code if the message being processed.

fn signal_code(&self) -> Result<SignalCode, Self::FallibleError>

Get the signal code if the message being processed.

fn message_id(&self) -> Result<MessageId, Self::UnrecoverableError>

Get the id of the message currently being handled.

fn program_id(&self) -> Result<ProgramId, Self::UnrecoverableError>

Get the id of program itself

fn debug(&self, data: &str) -> Result<(), Self::UnrecoverableError>

Send debug message.

This should be no-op in release builds.

fn lock_payload( &mut self, at: u32, len: u32, ) -> Result<PayloadSliceLock, Self::FallibleError>

Takes ownership over payload of the executing message and returns it in the wrapper PayloadSliceLock, which acts like lock.

Due to details of implementation of the runtime which executes gear syscalls inside wasm execution environment, to prevent additional memory allocation on payload read op, we give ownership over payload to the caller. Giving ownership over payload actually means, that the payload value in the currently executed message will become empty. To prevent from the risk of payload being not “returned” back to the message a Externalities::unlock_payload is introduced. For more info, read docs to PayloadSliceLock, DropPayloadLockBound, UnlockPayloadBound, PayloadSliceAccess types and their methods.

fn unlock_payload( &mut self, payload_holder: &mut PayloadSliceLock, ) -> UnlockPayloadBound

Reclaims ownership from the payload lock over previously taken payload from the currently executing message..

It’s supposed, that the implementation of the method calls PayloadSliceLock::release.

fn size(&self) -> Result<usize, Self::UnrecoverableError>

Size of currently handled message payload.

fn random(&self) -> Result<(&[u8], u32), Self::UnrecoverableError>

Returns a random seed for the current block with message id as a subject, along with the time in the past since when it was determinable by chain observers.

fn reserve_gas( &mut self, amount: u64, duration: u32, ) -> Result<ReservationId, Self::FallibleError>

Reserve some gas for a few blocks.

fn unreserve_gas( &mut self, id: ReservationId, ) -> Result<u64, Self::FallibleError>

Unreserve gas using reservation ID.

fn system_reserve_gas(&mut self, amount: u64) -> Result<(), Self::FallibleError>

Do system reservation.

fn gas_available(&self) -> Result<u64, Self::UnrecoverableError>

Tell how much gas is left in running context.

fn value(&self) -> Result<u128, Self::UnrecoverableError>

Value associated with message.

fn value_available(&self) -> Result<u128, Self::UnrecoverableError>

Tell how much value is left in running context.

fn wait(&mut self) -> Result<(), Self::UnrecoverableError>

Interrupt the program and reschedule execution for maximum.

fn wait_for(&mut self, duration: u32) -> Result<(), Self::UnrecoverableError>

Interrupt the program and reschedule execution in duration.

fn wait_up_to( &mut self, duration: u32, ) -> Result<bool, Self::UnrecoverableError>

Interrupt the program and reschedule execution for maximum, but not more than duration.

fn wake( &mut self, waker_id: MessageId, delay: u32, ) -> Result<(), Self::FallibleError>

Wake the waiting message and move it to the processing queue.

fn create_program( &mut self, packet: InitPacket, delay: u32, ) -> Result<(MessageId, ProgramId), Self::FallibleError>

Send init message to create a new program.

fn reply_deposit( &mut self, message_id: MessageId, amount: u64, ) -> Result<(), Self::FallibleError>

Create deposit to handle reply on given message.

fn forbidden_funcs(&self) -> &BTreeSet<SyscallName>

Return the set of functions that are forbidden to be called.

Provided Methods

fn send( &mut self, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>

Send message to another program.

fn reservation_send( &mut self, id: ReservationId, msg: HandlePacket, delay: u32, ) -> Result<MessageId, Self::FallibleError>

Send message to another program using gas from reservation.

fn reply(&mut self, msg: ReplyPacket) -> Result<MessageId, Self::FallibleError>

Produce reply to the current message.

fn reservation_reply( &mut self, id: ReservationId, msg: ReplyPacket, ) -> Result<MessageId, Self::FallibleError>

Produce reply to the current message from reservation.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors