Crate pallet_ismp

Expand description

§Pallet ISMP

The interoperable state machine protocol implementation for substrate-based chains. This pallet provides the ability to

Track the finalized state of a remote state machine (blockchain) through the use of consensus proofs which attest to a finalized “state commitment”.
Execute incoming ISMP-compliant messages from a connected chain, through the use of state proofs which are verified through a known, previously finalized state commitment.
Dispatch ISMP requests and responses to a connected chain.

§Overview

The ISMP Pallet provides calls which allow for:

Creating consensus clients with their respective unbonding, challenge periods and any initial state machine commitments.
Updating consensus clients metadata
Executing ISMP-compliant Messages
Funding in-flight messages (Request or Response)

To use it in your runtime, you need to implement the ismp pallet_ismp::Config. The supported dispatchable functions are documented in the pallet_ismp::Call enum.

§Terminology

ISMP: Interoperable State Machine Protocol, is a framework for secure, cross-chain interoperability. Providing both messaging and state reading capabilities.
State Commitment: This refers to a cryptographic commitment of an entire blockchain state, otherwise known as state root.
State Machine: This refers to the blockchain itself, we identify blockchains as state machines.
Consensus State: This is the minimum data required by consensus client to verify consensus proofs which attest to a newly finalized state.
Consensus Client: This is an algorithm that verifies consensus proofs of a particular consensus mechanism.
Unbonding Period: Refers to how long it takes for validators to unstake their funds from the connected chain.
Challenge Period: A configurable value for how long to wait for state commitments to be challenged, before they can be used to verify incoming requests/responses.

§Dispatchable Functions

handle - Handles incoming ISMP messages.
handle_unsigned Unsigned variant for handling incoming messages, enabled by feature = ["unsigned"]
create_consensus_client - Handles creation of various properties for a particular consensus client. Can only be called by the AdminOrigin.
update_consensus_state - Updates consensus client properties in storage. Can only be called by the AdminOrigin.
fund_message - In cases where the initially provided relayer fees have now become insufficient, due to a transaction fee spike on the destination chain. Allows a user to add more funds to the request to be used for delivery and execution. Should never be called on a completed request.

Please refer to the Call enum and its associated variants for documentation on each function.

§Runtime Configuration

The following example shows how to configure pallet-ismp in your runtime

use frame_support::parameter_types;
use frame_system::EnsureRoot;
use ismp::Error;
use ismp::host::StateMachine;
use ismp::module::IsmpModule;
use ismp::router::{IsmpRouter, Post, Response, Timeout};

parameter_types! {
    // The hyperbridge parachain on Polkadot
    pub const Coprocessor: Option<StateMachine> = Some(StateMachine::Polkadot(3367));
    // The host state machine of this pallet
    pub const HostStateMachine: StateMachine = StateMachine::Polkadot(1000); // your paraId here
}

impl pallet_ismp::Config for Runtime {
    // configure the runtime event
    type RuntimeEvent = RuntimeEvent;
    // Permissioned origin who can create or update consensus clients
    type AdminOrigin = EnsureRoot<AccountId>;
    // The state machine identifier for this state machine
    type HostStateMachine = HostStateMachine;
    // The pallet_timestamp pallet
    type TimestampProvider = Timestamp;
    // The currency implementation that is offered to relayers
    type Currency = Balances;
    // The balance type for the currency implementation
    type Balance = Balance;
    // Router implementation for routing requests/responses to their respective modules
    type Router = Router;
    // Optional coprocessor for incoming requests/responses
    type Coprocessor = Coprocessor;
    // Supported consensus clients
    type ConsensusClients = (
        // as an example, the parachain consensus client
        ismp_parachain::ParachainConsensusClient<Runtime, IsmpParachain>,
    );
    // Offchain database implementation. Outgoing requests and responses are
    // inserted in this database, while their commitments are stored onchain.
    type OffchainDB = ();
    // The fee handler implementation
    type FeeHandler = WeightFeeHandler<()>;
}

#[derive(Default)]
struct Router;
impl IsmpRouter for Router {
    fn module_for_id(&self, id: Vec<u8>) -> Result<Box<dyn IsmpModule>, Error> {
        let module = match id.as_slice() {
            YOUR_MODULE_ID => Box::new(YourModule::default()),
            _ => Err(Error::ModuleNotFound(id))?
        };
        Ok(module)
    }
}

/// Some custom module capable of processing some incoming/request or response.
/// This could also be a pallet itself.
#[derive(Default)]
struct YourModule;

pub const YOUR_MODULE_ID: &'static [u8] = &[12, 24, 36, 48];

impl IsmpModule for YourModule {
    /// Called by the ISMP hanlder, to notify module of a new POST request
    /// the module may choose to respond immediately, or in a later block
    fn on_accept(&self, request: Post) -> Result<(), Error> {
        // do something useful with the request
        Ok(())
    }

    /// Called by the ISMP hanlder, to notify module of a response to a previously
    /// sent out request
    fn on_response(&self, response: Response) -> Result<(), Error> {
        // do something useful with the response
        Ok(())
    }

    /// Called by the ISMP hanlder, to notify module of requests that were previously
    /// sent but have now timed-out
	fn on_timeout(&self, request: Timeout) -> Result<(), Error> {
        // revert any state changes that were made prior to dispatching the request
        Ok(())
    }
}

§License

Re-exports§

pub use pallet::*;

Modules§

child_trie: Child trie storage layout for pallet-ismp
dispatcher: Implementation for the low-level ISMP Dispatcher
errors: Pallet error definitions and conversions
events: Pallet event conversions to the core ISMP event
fee_handler
host: IsmpHost implementation for pallet-ismp
offchain: Offchain DB interfaces and utilities
pallet: The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
weights: Utilities for providing the static weights for module callbacks

Enums§

LegacyDrainState: State of one of the multi-block legacy storage drains. Active(None) is the initial state and means the next call should pass None as the clear() cursor. Active(Some(cursor)) carries the cursor returned by the previous call so the next one resumes from where it stopped. Done is set when clear() returns None, meaning the prefix has been fully cleared; subsequent on_idle calls become a single cheap read for that target.