Struct ink_env::chain_extension::ChainExtensionMethod

pub struct ChainExtensionMethod<I, O, ErrorCode> { /* private fields */ }

A concrete instance of a chain extension method.

This is a utility type used to drive the execution of a chain extension method call. It has several specializations of its call method for different ways to manage error handling when calling a predefined chain extension method.

• I represents the input type of the chain extension method. All tuple types that may act as input parameters for the chain extension method are valid. Examples include (), i32, (u8, [u8; 5], i32), etc.
• O represents the return (or output) type of the chain extension method. Only Result<T, E> or NoResult<O> generic types are allowed for O. The Result<T, E> type says that the chain extension method returns a Result type whereas the NoResult<O> type says that the chain extension method returns a non-Result value of type O.
• ErrorCode represents how the chain extension method handles the chain extension’s error code. Only HandleErrorCode<E> and IgnoreErrorCode types are allowed that each say to either properly handle or ignore the chain extension’s error code respectively.

The type states for type parameter O and ErrorCode represent 4 different states:

1. The chain extension method makes use of the chain extension’s error code: HandleErrorCode(E)
   • A: The chain extension method returns a Result<T, E> type.
   • B: The chain extension method returns a type T that is not a Result type: NoResult<T>
2. The chain extension ignores the chain extension’s error code: IgnoreErrorCode
   • A: The chain extension method returns a Result<T, E> type.
   • B: The chain extension method returns a type T that is not a Result type: NoResult<T>

Implementations

impl ChainExtensionMethod<(), (), ()>

pub fn build(func_id: u32) -> Self

Creates a new chain extension method instance.

impl<O, ErrorCode> ChainExtensionMethod<(), O, ErrorCode>

pub fn input<I>(self) -> ChainExtensionMethod<I, O, ErrorCode> where
    I: Encode, 

Sets the input types of the chain extension method call to I.

Note

I represents the input type of the chain extension method. All tuple types that may act as input parameters for the chain extension method are valid. Examples include (), i32, (u8, [u8; 5], i32), etc.

impl<I, ErrorCode> ChainExtensionMethod<I, (), ErrorCode>

pub fn output_result<T, E>(
    self
) -> ChainExtensionMethod<I, Result<T, E>, ErrorCode> where
    Result<T, E>: Decode,
    E: From<Error>, 

Sets the output type of the chain extension method call to Result<T, E>.

Note

This indicates that the chain extension method return value might represent a failure.

pub fn output<O>(self) -> ChainExtensionMethod<I, NoResult<O>, ErrorCode> where
    O: Decode, 

Sets the output type of the chain extension method call to O.

Note

The set returned type O must not be of type Result<T, E>. When using the #[ink::chain_extension] procedural macro to define this chain extension method the above constraint is enforced at compile time.

impl<I, O> ChainExtensionMethod<I, O, ()>

pub fn ignore_error_code(self) -> ChainExtensionMethod<I, O, IgnoreErrorCode>

Makes the chain extension method call assume that the returned status code is always success.

Note

This will avoid handling of failure status codes returned by the chain extension method call. Use this only if you are sure that the chain extension method call will never return an error code that represents failure.

The output of the chain extension method call is always decoded and returned in this case.

pub fn handle_error_code<ErrorCode>(
    self
) -> ChainExtensionMethod<I, O, HandleErrorCode<ErrorCode>> where
    ErrorCode: FromStatusCode, 

Makes the chain extension method call handle the returned status code.

Note

This will handle the returned status code and only loads and decodes the value returned as the output of the chain extension method call in case of success.

impl<I, T, E, ErrorCode> ChainExtensionMethod<I, Result<T, E>, HandleErrorCode<ErrorCode>> where
    I: Encode,
    T: Decode,
    E: Decode + From<ErrorCode> + From<Error>,
    ErrorCode: FromStatusCode, 

pub fn call(self, input: &I) -> Result<T, E>

Calls the chain extension method for case 1.A described here.

Errors

• If the called chain extension method returns a non-successful error code.
• If the Result return value of the called chain extension represents an error.
• If the Result return value cannot be SCALE decoded properly.
• If custom constraints specified by the called chain extension method are violated.
  • These constraints are determined and defined by the author of the chain extension method.

Example

Declares a chain extension method with the unique ID of 5 that requires a bool and an i32 as input parameters and returns a Result<i32, MyError> upon completion. It will handle the shared error code from the chain extension. The call is finally invoked with arguments true and 42 for the bool and i32 input parameter respectively.

let result = ChainExtensionMethod::build(5)
    .input::<(bool, i32)>()
    .output_result::<i32, MyError>()
    .handle_error_code::<MyErrorCode>()
    .call(&(true, 42));

impl<I, T, E> ChainExtensionMethod<I, Result<T, E>, IgnoreErrorCode> where
    I: Encode,
    T: Decode,
    E: Decode + From<Error>, 

pub fn call(self, input: &I) -> Result<T, E>

Calls the chain extension method for case 2.A described here.

Errors

• If the Result return value of the called chain extension represents an error.
• If the Result return value cannot be SCALE decoded properly.
• If custom constraints specified by the called chain extension method are violated.
  • These constraints are determined and defined by the author of the chain extension method.

Example

Declares a chain extension method with the unique ID of 5 that requires a bool and an i32 as input parameters and returns a Result<i32, MyError> upon completion. It will ignore the shared error code from the chain extension and assumes that the call succeeds. The call is finally invoked with arguments true and 42 for the bool and i32 input parameter respectively.

let result = ChainExtensionMethod::build(5)
    .input::<(bool, i32)>()
    .output_result::<i32, MyError>()
    .ignore_error_code()
    .call(&(true, 42));

impl<I, O, ErrorCode> ChainExtensionMethod<I, NoResult<O>, HandleErrorCode<ErrorCode>> where
    I: Encode,
    O: Decode,
    ErrorCode: FromStatusCode, 

pub fn call(self, input: &I) -> Result<O, ErrorCode>

Calls the chain extension method for case 1.B described here.

Errors

• If the called chain extension method returns a non-successful error code.
• If custom constraints specified by the called chain extension method are violated.
  • These constraints are determined and defined by the author of the chain extension method.

Panics

• If the return value cannot be SCALE decoded properly.

Example

Declares a chain extension method with the unique ID of 5 that requires a bool and an i32 as input parameters and returns a Result<i32, MyErrorCode> upon completion. It will handle the shared error code from the chain extension. The call is finally invoked with arguments true and 42 for the bool and i32 input parameter respectively.

let result = ChainExtensionMethod::build(5)
    .input::<(bool, i32)>()
    .output::<i32>()
    .handle_error_code::<MyErrorCode>()
    .call(&(true, 42));

impl<I, O> ChainExtensionMethod<I, NoResult<O>, IgnoreErrorCode> where
    I: Encode,
    O: Decode, 

pub fn call(self, input: &I) -> O

Calls the chain extension method for case 2.B described here.

Panics

• If the return value cannot be SCALE decoded properly.

Example

Declares a chain extension method with the unique ID of 5 that requires a bool and an i32 as input parameters and returns a Result<i32, MyErrorCode> upon completion. It will ignore the shared error code from the chain extension and assumes that the call succeeds. The call is finally invoked with arguments true and 42 for the bool and i32 input parameter respectively.

let result = ChainExtensionMethod::build(5)
    .input::<(bool, i32)>()
    .output::<i32>()
    .ignore_error_code()
    .call(&(true, 42));

Trait Implementations

impl<I: Debug, O: Debug, ErrorCode: Debug> Debug for ChainExtensionMethod<I, O, ErrorCode>

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

Formats the value using the given formatter.