Struct ink_env::chain_extension::ChainExtensionMethod

pub struct ChainExtensionMethod<I, O, ErrorCode, const IS_RESULT: bool> { /* 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.
• 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.
• const IS_RESULT: bool indicates if the O (output type) is of Result<T, E> type.

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, i.e. IS_RESULT is set to true.
   • B: The chain extension method returns a type O that is not a Result type. The return type is still wrapped into Result<O, E>
2. The chain extension ignores the chain extension’s error code: IgnoreErrorCode
   • A: The chain extension method returns a Result<T, E> type, i.e. IS_RESULT is set to true.
   • B: The chain extension method returns a type O that is not a Result type. The method just returns O.

Implementations

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

pub fn build(id: u32) -> Self

Creates a new chain extension method instance.

impl<O, ErrorCode, const IS_RESULT: bool> ChainExtensionMethod<(), O, ErrorCode, IS_RESULT>

pub fn input<I>(self) -> ChainExtensionMethod<I, O, ErrorCode, IS_RESULT>

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, false>

pub fn output<O, const IS_RESULT: bool>( self, ) -> ChainExtensionMethod<I, O, ErrorCode, IS_RESULT>

where O: Decode,

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

If const IS_RESULT: bool is set to true, O is treated as Result<T, E>

Note

If O is incorrectly indicated as Return<T, E>, the type will not satisfy trait bounds later in method builder pipeline.

impl<I, O, const IS_RESULT: bool> ChainExtensionMethod<I, O, (), IS_RESULT>

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

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>, IS_RESULT>

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, O, ErrorCode> ChainExtensionMethod<I, O, HandleErrorCode<ErrorCode>, true>

where O: IsResultType, I: Encode, <O as IsResultType>::Ok: Decode, <O as IsResultType>::Err: Decode + From<ErrorCode> + From<Error>, ErrorCode: FromStatusCode,

pub fn call( self, input: &I, ) -> Result<<O as IsResultType>::Ok, <O as IsResultType>::Err>

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. Note how we set const constant argument to true to indicate that return type is Result<T, E>. 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>, true>()
    .handle_error_code::<MyErrorCode>()
    .call(&(true, 42));

impl<I, O> ChainExtensionMethod<I, O, IgnoreErrorCode, true>

where O: IsResultType, I: Encode, <O as IsResultType>::Ok: Decode, <O as IsResultType>::Err: Decode + From<Error>,

pub fn call( self, input: &I, ) -> Result<<O as IsResultType>::Ok, <O as IsResultType>::Err>

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. Note how we set const constant argument to true to indicate that return type is Result<T, E>. 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>, true>()
    .ignore_error_code()
    .call(&(true, 42));

impl<I, O, ErrorCode> ChainExtensionMethod<I, O, HandleErrorCode<ErrorCode>, false>

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, because handle_status flag is set. We still need to indicate that the original type is not Result<T, E>, so const IS_RESULT is set false. 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, false>()
    .handle_error_code::<MyErrorCode>()
    .call(&(true, 42));

impl<I, O> ChainExtensionMethod<I, O, IgnoreErrorCode, false>

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 i32 upon completion. Hence, const IS_RESULT is set false. 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, false>()
    .ignore_error_code()
    .call(&(true, 42));

Trait Implementations

impl<I: Debug, O: Debug, ErrorCode: Debug, const IS_RESULT: bool> Debug for ChainExtensionMethod<I, O, ErrorCode, IS_RESULT>

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

Formats the value using the given formatter.