Parachain Integration

Parachains that want to leverage the Hyperbridge protocol for secure cross-chain interoperability can do so by integrating the ismp-parachain pallet. This pallet empowers parachains to interoperate with whitelisted sibling parachains through the ISMP framework.

Runtime Integration

To establish a connection with Hyperbridge and utilize its message-passing capabilities, a parachain must complete three essential steps. First, it must integrate the pallet-ismp module into its runtime environment, providing the core functionalities for ISMP message handling. Next, the parachain must include the ismp-parachain pallet, which provides a parachain consensus client for verifying proofs of finalized parachain headers. Finally, the parachain must whitelist the Hyperbridge parachain on the ismp-parachain pallet.

Parachain Consensus Client

The ParachainConsensusClient adds support for parachain consensus proofs to pallet-ismp. These consensus proofs once verified, finalize new parachain state commitments. This module will only verify proofs for parachains whose IDs have been previously whitelisted in the ismp-parachain pallet.

To include the pallet in the runtime, implement the pallet config for the Runtime and add the pallet to the construct_runtime macro.

impl ismp_parachain::Config for Runtime {
    type RuntimeEvent = RuntimeEvent;
    // pallet-ismp implements the IsmpHost
    type IsmpHost = Ismp;
}
 
parameter_types! {
    // The hyperbridge parachain on Polkadot
    pub const Coprocessor: Option<StateMachine> = Some(StateMachine::Polkadot(3367));
}
 
impl pallet_ismp::Config for Runtime {
    // ...
    type Coprocessor = Coprocessor;
    type ConsensusClients = (
        // Add the parachain consensus clients to the supported consensus clients when configuring pallet-ismp
        ismp_parachain::ParachainConsensusClient<Runtime, IsmpParachain>,
    );
    // ...
}
 
construct_runtime! {
    // ...
    Ismp: pallet_ismp,
    IsmpParachain: ismp_parachain
}

Whitelisting Parachains

To use the parachain consensus client to communicate with sibling parachains, Hyperbridge included. You will need to first whitelist these parachains using the ismp_parachain::Call::<T>::add_parachain extrinsic. Once added consenus relayers like the ismp parachain inherent will begin including finality proofs of these parachains in your runtime. Opening the doors of secure cross-chain communication.

Calls

update_parachain_consensus

This is an inherent call that is used by the collator to include the consensus proofs for newly finalized parachain headers.

add_parachain

This call allows a priviledged origin to add a new parachain to the list of supported parachains. whenever a new parachain is added, the inherent provider will add state proofs of the parachain's latest header in subsequent consensus messages.

remove_parachain

This priviledged call removes a parachain from the list of supported parachains, thereby preventing any future state updates from such parachain.

Hooks

on_initialize

In the OnInitialize hook, the consensus state for the parachain consensus client will be initialized if it does not exist.

on_finalize

This hook is used to read the current relay chain state in order to get the state root of the finalized relay chain block, so it can be used to verify subsequent parachain consensus update messages.

Implementation

ismp-parachain