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<ActorId, 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<ActorId, Self::UnrecoverableError>;
    fn debug(&self, data: &str) -> Result<(), Self::UnrecoverableError>;
    fn payload_slice(
        &mut self,
        at: u32,
        len: u32,
    ) -> Result<PayloadSlice, Self::FallibleError>;
    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, ActorId), Self::FallibleError>;
    fn reply_deposit(
        &mut self,
        message_id: MessageId,
        amount: u64,
    ) -> Result<(), Self::FallibleError>;
    fn forbidden_funcs(&self) -> &BTreeSet<SyscallName>;
    fn msg_ctx(&self) -> &MessageContext;

    // 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<ActorId, 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<ActorId, 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 payload_slice( &mut self, at: u32, len: u32, ) -> Result<PayloadSlice, Self::FallibleError>

Get the currently handled message payload slice.

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, ActorId), 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.

fn msg_ctx(&self) -> &MessageContext

Return the current message context.

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".

Implementors