Struct pallet_contracts::chain_extension::Environment

pub struct Environment<'a, 'b, E: Ext, S: State> { /* fields omitted */ }

Grants the chain extension access to its parameters and execution environment.

It uses typestate programming to enforce the correct usage of the parameters passed to the chain extension.

Implementations

impl<'a, 'b, E: Ext, S: State> Environment<'a, 'b, E, S> where
    <E::T as SysConfig>::AccountId: UncheckedFrom<<E::T as SysConfig>::Hash> + AsRef<[u8]>, 

Functions that are available in every state of this type.

pub fn charge_weight(&mut self, amount: Weight) -> Result<ChargedAmount>

Charge the passed amount of weight from the overall limit.

It returns Ok when there the remaining weight budget is larger than the passed weight. It returns Err otherwise. In this case the chain extension should abort the execution and pass through the error.

The returned value can be used to with Self::adjust_weight. Other than that it has no purpose.

Note

Weight is synonymous with gas in substrate.

pub fn adjust_weight(&mut self, charged: ChargedAmount, actual_weight: Weight)

Adjust a previously charged amount down to its actual amount.

This is when a maximum a priori amount was charged and then should be partially refunded to match the actual amount.

pub fn ext(&mut self) -> &mut E

Grants access to the execution environment of the current contract call.

Consult the functions on the returned type before re-implementing those functions.

impl<'a, 'b, E: Ext> Environment<'a, 'b, E, Init>

Functions that are only available in the initial state of this type.

Those are the functions that determine how the arguments to the chain extensions should be consumed.

pub fn only_in(self) -> Environment<'a, 'b, E, OnlyIn>

Use all arguments as integer values.

pub fn prim_in_buf_out(self) -> Environment<'a, 'b, E, PrimInBufOut>

Use input arguments as integer and output arguments as pointer to a buffer.

pub fn buf_in_buf_out(self) -> Environment<'a, 'b, E, BufInBufOut>

Use input and output arguments as pointers to a buffer.

impl<'a, 'b, E: Ext, S: PrimIn> Environment<'a, 'b, E, S>

Functions to use the input arguments as integers.

pub fn val0(&self) -> u32

The input_ptr argument.

pub fn val1(&self) -> u32

The input_len argument.

impl<'a, 'b, E: Ext, S: PrimOut> Environment<'a, 'b, E, S>

Functions to use the output arguments as integers.

pub fn val2(&self) -> u32

The output_ptr argument.

pub fn val3(&self) -> u32

The output_len_ptr argument.

impl<'a, 'b, E: Ext, S: BufIn> Environment<'a, 'b, E, S> where
    <E::T as SysConfig>::AccountId: UncheckedFrom<<E::T as SysConfig>::Hash> + AsRef<[u8]>, 

Functions to use the input arguments as pointer to a buffer.

pub fn read(&self, max_len: u32) -> Result<Vec<u8>>

Reads min(max_len, in_len) from contract memory.

This does not charge any weight. The caller must make sure that the an appropriate amount of weight is charged before reading from contract memory. The reason for that is that usually the costs for reading data and processing said data cannot be separated in a benchmark. Therefore a chain extension would charge the overall costs either using max_len (worst case approximation) or using in_len().

pub fn read_into(&self, buffer: &mut &mut [u8]) -> Result<()>

Reads `min(buffer.len(), in_len) from contract memory.

This takes a mutable pointer to a buffer fills it with data and shrinks it to the size of the actual data. Apart from supporting pre-allocated buffers it is equivalent to to read().

pub fn read_as<T: Decode + MaxEncodedLen>(&mut self) -> Result<T>

Reads and decodes a type with a size fixed at compile time from contract memory.

This function is secure and recommended for all input types of fixed size as long as the cost of reading the memory is included in the overall already charged weight of the chain extension. This should usually be the case when fixed input types are used.

pub fn read_as_unbounded<T: Decode>(&mut self, len: u32) -> Result<T>

Reads and decodes a type with a dynamic size from contract memory.

Make sure to include len in your weight calculations.

pub fn in_len(&self) -> u32

The length of the input as passed in as input_len.

A chain extension would use this value to calculate the dynamic part of its weight. For example a chain extension that calculates the hash of some passed in bytes would use in_len to charge the costs of hashing that amount of bytes. This also subsumes the act of copying those bytes as a benchmarks measures both.

impl<'a, 'b, E: Ext, S: BufOut> Environment<'a, 'b, E, S> where
    <E::T as SysConfig>::AccountId: UncheckedFrom<<E::T as SysConfig>::Hash> + AsRef<[u8]>, 

Functions to use the output arguments as pointer to a buffer.

pub fn write(
    &mut self,
    buffer: &[u8],
    allow_skip: bool,
    weight_per_byte: Option<Weight>
) -> Result<()>

Write the supplied buffer to contract memory.

If the contract supplied buffer is smaller than the passed buffer an Err is returned. If allow_skip is set to true the contract is allowed to skip the copying of the buffer by supplying the guard value of u32::MAX as out_ptr. The weight_per_byte is only charged when the write actually happens and is not skipped or failed due to a too small output buffer.