feat: runtime error

[chungquantin]

How to assert non-custom error thrown by Pop API?

This example interacts with a PSP22 example contract that uses Pop API. The contract method returns PSP22Error which is provided by Pop API library.

Learn more in the PSP22 example contract.

• Import required methods and types:

use drink::{call, session::Session};
use pop_api::v0::fungibles::PSP22Error;

• Example of interacting with the transfer method of the Psp22 contract:

// Example of a method to interact with contract via pop-drink.
fn transfer(session: &mut Session<Pop>, to: AccountId, amount: Balance) -> Result<(), PSP22Error> {
 // Initialising a string value of an empty array.
 let empty_array = serde_json::to_string::<[u8; 0]>(&[]).unwrap();
 // Call to a contract method.
 call::<Pop, (), PSP22Error>(
  session,
  "Psp22::transfer",
  vec![to.to_string(), amount.to_string(), empty_array],
  None,
 )
}

A custom error is returned if the error doesn't conform to the PSP22Error standard.
The custom error is represented by a StatusCode, which encapsulates a u32 value indicating the success or failure of a runtime call via the Pop API.

Pop DRink! provides an error type and a macro to simplify testing both runtime module errors and API errors.

• drink::v0::Error: Runtime error type for testing API V0.
• assert_err: Asserts that a Result with an error type convertible to u32 matches the expected Error from pop-drink.

Test the contract call if a custom error is the runtime module error:

use drink::{assert_err, v0::Error, Assets, AssetsError::NoAccount};

assert_err!(
 transfer(&mut session, ALICE, AMOUNT),
 Error::Module(Assets(NoAccount))
);

Test the contract call if a custom error is the API error:

use drink::{assert_err, v0::{Error, Arithmetic, ArithmeticError::Overflow}};

assert_err!(
 transfer(&mut session, ALICE, AMOUNT),
 Error::Api(Arithmetic(Overflow))
);

Implementation

assert_runtime_error

A utility macro to assert that an error returned from a smart contract method matches the
`RuntimeError`.

# Generic parameters:

- `VersionedApiError` - Version of Pop API.
- `R` - Success type returned if Ok().
- `E` - Returned `Err()` value of a method result. Must be convertable to `u32`.
- `RuntimeError` - Runtime error type.

# Parameters:

- `result` - Result returned by a smart contract method.
- `expected_error` - `RuntimeError` to be asserted.

RuntimeError

Introducing a new error type RuntimeError

/// Runtime error for testing.
///
/// # Generic Parameters:
///
/// - `ModuleError` - Error type of the runtime modules. Reference: https://paritytech.github.io/polkadot-sdk/master/solochain_template_runtime/enum.Error.html.
/// - `ApiError` - Error type of the API, which depends on version.
/// - `MODULE_INDEX` - Index of the variant `Error::Module`. This is based on the index of
///   `ApiError::Module`
#[derive(Encode, Decode, Debug)]
pub enum Error<ModuleError, ApiError, const MODULE_INDEX: u8>
where
	ModuleError: Decode + Encode + Debug,
	ApiError: Decode + Encode + Debug + From<u32> + Into<u32>,
{
	/// Module errors of the runtime.
	Module(ModuleError),
	/// Every `ApiError`.
	Api(ApiError),
}

With two conversion methods

• Convert into u32: Used to compare the RuntimeError with the another error type implementing Into<u32> (See PSP22Error in pop-node)
• Convert from u32: Used to convert a compared value into RuntimeError and display back to the developers.

[Daanvdplas]

This definitely looks better! We still have to do a little bit of thinking regarding the versioning. Then it is time to finalise, write docs and finish :)

[Daanvdplas]

Oke I think we have the implementation now. Polishing it up, testing and last step; writing clear documentation.

[evilrobot-01]

Outstanding work! This is so much nicer than where we started, so kudos!

I have made various suggestions to try and simplify it a little more for a cleaner final product. I suspect some may not be possible, but if so it will reduce the amount of code required. Type names used by the end user should be as concise as possible so its less to type, quicker to achieve more.

PS - please ensure that any types used are consistent across runtime error and macro (e.g. module error first, then api error). I think the PR description has them in a different order, but that may not exist in the code.

[evilrobot-01]

A reminder that these will need to be updated to the actual repos before this is merged.

[chungquantin]

#20

[Daanvdplas]

Man we are close! Amazing work! This will become incredibly important for the devex that pop claims to provide!

I'm not sure if anyone else made a comment that this crate should be generic in its explanation but because this is called pop-drink I guess we can opinionate a little bit and simplify. We want to provide an easy to understand test suite for developers building smart contracts on Pop Network using the pop api. Lets make it like that.

The term API is used for both pop api and apis in general. Lets make a clear distinction. The pop api is never clearly mentioned btw as well as the pop api error and the status code. The latter two might be a bit too low level but a link / reference is always good if they want to learn more.

Try to take the stand of a developer never having seen the psp22 example, pop api and pop drink crate. Viewing it by looking in the branch, not the PR (really taking the perspective of someone skimming through our repos), and see if there are some missing links and easy explanations that can bind all of it together nicely (not talking about extra work on pop api crate :) ).

[Daanvdplas]

One last iteration for the docs.

Lets take a step back and try to explain in easy language what the crate provides to developers and what it can be used for.

One idea; put the things in order in the file first in terms of what the developer will want to use first. This the macro as first. Explain what the macro does. Then one layer deeper, the error type, explain that. Really try to explain the thing itself and leaving out the details when you go one layer deeper.

[Daanvdplas]

Does this term API error make any sense to you? I find it very confusing to be honest. There is the Error type which makes a separation between module runtime errors and the other errors that can come from the runtime. Everywhere where the latter is mentioned we call it ApiError. If this refers to the pop api error it is incorrect as the module error is basically also from the pop api error.

[chungquantin]

Resolved by removing all the introduction of ApiError

ApiError -> RuntimeCallError

I changed it to RuntimeCallError and don't mention anything about errors returned by the API. I reordered the RuntimeCallError and ModuleError so developers will read the RuntimeCallError description first before visiting ModuleError. From my perspective, ModuleError is simply a subset of reasons why the runtime call fails, originating from the modules.

Hence, both errors types RuntimeCallError and ModuleError come from the runtime. Simply speaking, RuntimeCallError is a parent of ModuleError, but ModuleError helps to test the runtime module error in a better way.

[Daanvdplas]

This is again confusing, why is it only a numerical value of ApiError? It is a numerical value of Error.

[chungquantin]

Agree. Resolved!

[Daanvdplas]

Again confusing for the same reason.

[chungquantin]

Resolved.

[Daanvdplas]

These documentation section also need to be revisited.

For example the first line:

Asserts an error type to Error. This can be used for custom error types used by a contract which uses the status code returned by the pop runtime. The error type must be convertible to a u32.

I think it is much easier to use the status code as a way of explaining everything here then by calling it an Api error.

[chungquantin]

Thanks for the suggestion. Resolved and removed all the introduction of ApiError.

[Daanvdplas]

Here you are referring to the psp22 error as the API error but it is very unclear why and how. The reason it is (in the current terminology) an API error is because it is an error that is converted from a status code (an error from the runtime) and has a variant that holds this status code. Information is extracted from this status code to see what runtime error happened. drink provides a simplified runtime error type which you can use to discover which error occurred.

Try to take a step back and explain the pop drink features to someone that is new to polkadot / smart contracts.

[chungquantin]

Resolved! Simplify the example by removing the PSP22Error and just return StatusCode instead: 30405b4#:~:text=///%20//%20Required%20imports%20to,Api(Arithmetic(Overflow)))%3B

[Daanvdplas]

LGTM!!!