mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-27 09:17:58 +00:00
Svyatoslav Nikolsky
feefc34567
23dda62 Rococo <> Wococo messages relay (#1030) bcde21d Update the wasm builder to substrate master (#1029) a8318ce Make target signer optional when sending message. (#1018) f8602e1 Fix insufficient balance when send message. (#1020) d95c0a7 greedy relayer don't need message dispatch to be prepaid if dispatch is supposed to be paid at the target chain (#1016) ad5876f Update types. (#1027) 116cbbc CI: fix starting the pipeline (#1022) 7e0fadd Add temporary `canary` job (#1019) 6787091 Update types to contain dispatch_fee_payment (#1017) 03f79ad Allow Root to assume SourceAccount. (#1011) 372d019 Return dispatch_fee_payment from message details RPC (#1014) 604eb1c Relay basic single-bit message dispatch results back to the source chain (#935) bf52fff Use plain source_queue view when selecting nonces for delivery (#1010) fc5cf7d pay dispatch fee at target chain (#911) 1e35477 Bump Substrate to `286d7ce` (#1006) 7ad07b3 Add --only-mandatory-headers mode (#1004) 5351dc9 Messages relayer operating mode (#995) 9bc29a7 Rococo <> Wococo relayer balance guard (#998) bc17341 rename messages_dispatch_weight -> message_details (#996) 95be244 Bump Rococo and Wococo spec versions (#999) c35567b Move ChainWithBalances::NativeBalance -> Chain::Balance (#990) 1bfece1 Fix some nits (#988) 334ea0f Increase pause before starting relays again (#989) 7fb8248 Fix clippy in test code (#993) d60ae50 fix clippy issues (#991) 75ca813 Make sure GRANDPA shares state with RPC. (#987) da2a38a Bump Substrate (#986) 5a9862f Update submit finality proof weight formula (#981) 69df513 Flag for rejecting all outbound messages (#982) 14d0506 Add script to setup bench machine. (#984) e74e8ab Move CI from GitHub Actions to GitLab (#814) c5ca5dd Custom justification verification (#979) 643f10d Always run on-demand headers relay in complex relay (#975) a35b0ef Add JSON type definitions for Rococo<>Wococo bridge (#977) 0eb83f2 Update cargo.deny (#980) e1d1f4c Bump Rococo/Wococo spec_version (#976) deac90d increase pause before starting relays (#974) 68d6d79 Revert to use InspectCmd, bump substrate `6bef4f4` (#966) 66e1508 Avoid hashing headers twice in verify_justification (#973) a31844f Bump `environmental` dependency (#972) 2a4c29a in auto-relays keep trying to connect to nodes until connection is established (#971) 0e767b3 removed stray file (#969) b9545dc Serve multiple lanes with single complex relay instance (#964) 73419f4 Correct type error (#968) bac256f Start finality relay spec-version guards for Rococo <> Wococo finality relays (#965) bfd7037 pass source and target chain ids to account_ownership_proof (#963) 8436073 Upstream changes from Polkadot repo (#961) e58d851 Increase account endowment amount (#960) git-subtree-dir: bridges git-subtree-split: 23dda6248236b27f20d76cbedc30e189cc6f736c
179 lines
11 KiB
Markdown
179 lines
11 KiB
Markdown
# Helpers for Messages Module Integration
|
|
|
|
The [`messages`](./src/messages.rs) module of this crate contains a bunch of helpers for integrating
|
|
messages module into your runtime. Basic prerequisites of these helpers are:
|
|
- we're going to bridge Substrate-based chain with another Substrate-based chain;
|
|
- both chains have [messages module](../../modules/messages/README.md), Substrate bridge
|
|
module and the [call dispatch module](../../modules/dispatch/README.md);
|
|
- all message lanes are identical and may be used to transfer the same messages;
|
|
- the messages sent over the bridge are dispatched using
|
|
[call dispatch module](../../modules/dispatch/README.md);
|
|
- the messages are `bp_message_dispatch::MessagePayload` structures, where `call` field is
|
|
encoded `Call` of the target chain. This means that the `Call` is opaque to the
|
|
[messages module](../../modules/messages/README.md) instance at the source chain.
|
|
It is pre-encoded by the message submitter;
|
|
- all proofs in the [messages module](../../modules/messages/README.md) transactions are
|
|
based on the storage proofs from the bridged chain: storage proof of the outbound message (value
|
|
from the `pallet_bridge_messages::Store::MessagePayload` map), storage proof of the outbound lane
|
|
state (value from the `pallet_bridge_messages::Store::OutboundLanes` map) and storage proof of the
|
|
inbound lane state (value from the `pallet_bridge_messages::Store::InboundLanes` map);
|
|
- storage proofs are built at the finalized headers of the corresponding chain. So all message lane
|
|
transactions with proofs are verifying storage proofs against finalized chain headers from
|
|
Substrate bridge module.
|
|
|
|
**IMPORTANT NOTE**: after reading this document, you may refer to our test runtimes
|
|
([rialto_messages.rs](../millau/runtime/src/rialto_messages.rs) and/or
|
|
[millau_messages.rs](../rialto/runtime/src/millau_messages.rs)) to see how to use these helpers.
|
|
|
|
## Contents
|
|
- [`MessageBridge` Trait](#messagebridge-trait)
|
|
- [`ChainWithMessages` Trait ](#ChainWithMessages-trait)
|
|
- [Helpers for the Source Chain](#helpers-for-the-source-chain)
|
|
- [Helpers for the Target Chain](#helpers-for-the-target-chain)
|
|
|
|
## `MessageBridge` Trait
|
|
|
|
The essence of your integration will be a struct that implements a `MessageBridge` trait. It has
|
|
single method (`MessageBridge::bridged_balance_to_this_balance`), used to convert from bridged chain
|
|
tokens into this chain tokens. The bridge also requires two associated types to be specified -
|
|
`ThisChain` and `BridgedChain`.
|
|
|
|
Worth to say that if you're going to use hardcoded constant (conversion rate) in the
|
|
`MessageBridge::bridged_balance_to_this_balance` method (or in any other method of
|
|
`ThisChainWithMessages` or `BridgedChainWithMessages` traits), then you should take a
|
|
look at the
|
|
[messages parameters functionality](../../modules/messages/README.md#Non-Essential-Functionality).
|
|
They allow pallet owner to update constants more frequently than runtime upgrade happens.
|
|
|
|
## `ChainWithMessages` Trait
|
|
|
|
The trait is quite simple and can easily be implemented - you just need to specify types used at the
|
|
corresponding chain. There is single exception, though (it may be changed in the future):
|
|
|
|
- `ChainWithMessages::MessagesInstance`: this is used to compute runtime storage keys. There
|
|
may be several instances of messages pallet, included in the Runtime. Every instance stores
|
|
messages and these messages stored under different keys. When we are verifying storage proofs from
|
|
the bridged chain, we should know which instance we're talking to. This is fine, but there's
|
|
significant inconvenience with that - this chain runtime must have the same messages pallet
|
|
instance. This does not necessarily mean that we should use the same instance on both chains -
|
|
this instance may be used to bridge with another chain/instance, or may not be used at all.
|
|
|
|
## `ThisChainWithMessages` Trait
|
|
|
|
This trait represents this chain from bridge point of view. Let's review every method of this trait:
|
|
|
|
- `ThisChainWithMessages::is_outbound_lane_enabled`: is used to check whether given lane accepts
|
|
outbound messages.
|
|
|
|
- `ThisChainWithMessages::maximal_pending_messages_at_outbound_lane`: you should return maximal
|
|
number of pending (undelivered) messages from this function. Returning small values would require
|
|
relayers to operate faster and could make message sending logic more complicated. On the other
|
|
hand, returning large values could lead to chain state growth.
|
|
|
|
- `ThisChainWithMessages::estimate_delivery_confirmation_transaction`: you'll need to return
|
|
estimated size and dispatch weight of the delivery confirmation transaction (that happens on
|
|
this chain) from this function.
|
|
|
|
- `ThisChainWithMessages::transaction_payment`: you'll need to return fee that the submitter
|
|
must pay for given transaction on this chain. Normally, you would use transaction payment pallet
|
|
for this. However, if your chain has non-zero fee multiplier set, this would mean that the
|
|
payment will be computed using current value of this multiplier. But since this transaction
|
|
will be submitted in the future, you may want to choose other value instead. Otherwise,
|
|
non-altruistic relayer may choose not to submit this transaction until number of transactions
|
|
will decrease.
|
|
|
|
## `BridgedChainWithMessages` Trait
|
|
|
|
This trait represents this chain from bridge point of view. Let's review every method of this trait:
|
|
|
|
- `BridgedChainWithMessages::maximal_extrinsic_size`: you will need to return the maximal
|
|
extrinsic size of the target chain from this function.
|
|
|
|
- `MessageBridge::message_weight_limits`: you'll need to return a range of
|
|
dispatch weights that the outbound message may take at the target chain. Please keep in mind that
|
|
our helpers assume that the message is an encoded call of the target chain. But we never decode
|
|
this call at the source chain. So you can't simply get dispatch weight from pre-dispatch
|
|
information. Instead there are two options to prepare this range: if you know which calls are to
|
|
be sent over your bridge, then you may just return weight ranges for these particular calls.
|
|
Otherwise, if you're going to accept all kinds of calls, you may just return range `[0; maximal
|
|
incoming message dispatch weight]`. If you choose the latter, then you shall remember that the
|
|
delivery transaction itself has some weight, so you can't accept messages with weight equal to
|
|
maximal weight of extrinsic at the target chain. In our test chains, we reject all messages that
|
|
have declared dispatch weight larger than 50% of the maximal bridged extrinsic weight.
|
|
|
|
- `MessageBridge::estimate_delivery_transaction`: you will need to return estimated dispatch weight and
|
|
size of the delivery transaction that delivers a given message to the target chain. The transaction
|
|
weight must or must not include the weight of pay-dispatch-fee operation, depending on the value
|
|
of `include_pay_dispatch_fee_cost` argument.
|
|
|
|
- `MessageBridge::transaction_payment`: you'll need to return fee that the submitter
|
|
must pay for given transaction on bridged chain. The best case is when you have the same conversion
|
|
formula on both chains - then you may just reuse the `ThisChainWithMessages::transaction_payment`
|
|
implementation. Otherwise, you'll need to hardcode this formula into your runtime.
|
|
|
|
## Helpers for the Source Chain
|
|
|
|
The helpers for the Source Chain reside in the `source` submodule of the
|
|
[`messages`](./src/messages.rs) module. The structs are: `FromThisChainMessagePayload`,
|
|
`FromBridgedChainMessagesDeliveryProof`, `FromThisChainMessageVerifier`. And the helper functions
|
|
are: `maximal_message_size`, `verify_chain_message`, `verify_messages_delivery_proof` and
|
|
`estimate_message_dispatch_and_delivery_fee`.
|
|
|
|
`FromThisChainMessagePayload` is a message that the sender sends through our bridge. It is the
|
|
`bp_message_dispatch::MessagePayload`, where `call` field is encoded target chain call. So
|
|
at this chain we don't see internals of this call - we just know its size.
|
|
|
|
`FromThisChainMessageVerifier` is an implementation of `bp_messages::LaneMessageVerifier`. It
|
|
has following checks in its `verify_message` method:
|
|
|
|
1. it'll verify that the used outbound lane is enabled in our runtime;
|
|
|
|
1. it'll reject messages if there are too many undelivered outbound messages at this lane. The
|
|
sender need to wait while relayers will do their work before sending the message again;
|
|
|
|
1. it'll reject a message if it has the wrong dispatch origin declared. Like if the submitter is not
|
|
the root of this chain, but it tries to dispatch the message at the target chain using
|
|
`bp_message_dispatch::CallOrigin::SourceRoot` origin. Or he has provided wrong signature
|
|
in the `bp_message_dispatch::CallOrigin::TargetAccount` origin;
|
|
|
|
1. it'll reject a message if the delivery and dispatch fee that the submitter wants to pay is lesser
|
|
than the fee that is computed using the `estimate_message_dispatch_and_delivery_fee` function.
|
|
|
|
`estimate_message_dispatch_and_delivery_fee` returns a minimal fee that the submitter needs to pay
|
|
for sending a given message. The fee includes: payment for the delivery transaction at the target
|
|
chain, payment for delivery confirmation transaction on this chain, payment for `Call` dispatch at
|
|
the target chain and relayer interest.
|
|
|
|
`FromBridgedChainMessagesDeliveryProof` holds the lane identifier and the storage proof of this
|
|
inbound lane state at the bridged chain. This also holds the hash of the target chain header, that
|
|
was used to generate this storage proof. The proof is verified by the
|
|
`verify_messages_delivery_proof`, which simply checks that the target chain header is finalized
|
|
(using Substrate bridge module) and then reads the inbound lane state from the proof.
|
|
|
|
`verify_chain_message` function checks that the message may be delivered to the bridged chain. There
|
|
are two main checks:
|
|
|
|
1. that the message size is less than or equal to the `2/3` of maximal extrinsic size at the target
|
|
chain. We leave `1/3` for signed extras and for the storage proof overhead;
|
|
|
|
1. that the message dispatch weight is less than or equal to the `1/2` of maximal normal extrinsic
|
|
weight at the target chain. We leave `1/2` for the delivery transaction overhead.
|
|
|
|
## Helpers for the Target Chain
|
|
|
|
The helpers for the target chain reside in the `target` submodule of the
|
|
[`messages`](./src/messages.rs) module. The structs are: `FromBridgedChainMessagePayload`,
|
|
`FromBridgedChainMessagesProof`, `FromBridgedChainMessagesProof`. And the helper functions are:
|
|
`maximal_incoming_message_dispatch_weight`, `maximal_incoming_message_size` and
|
|
`verify_messages_proof`.
|
|
|
|
`FromBridgedChainMessagePayload` corresponds to the `FromThisChainMessagePayload` at the bridged
|
|
chain. We expect that messages with this payload are stored in the `OutboundMessages` storage map of
|
|
the [messages module](../../modules/messages/README.md). This map is used to build
|
|
`FromBridgedChainMessagesProof`. The proof holds the lane id, range of message nonces included in
|
|
the proof, storage proof of `OutboundMessages` entries and the hash of bridged chain header that has
|
|
been used to build the proof. Additionally, there's storage proof may contain the proof of outbound
|
|
lane state. It may be required to prune `relayers` entries at this chain (see
|
|
[messages module documentation](../../modules/messages/README.md#What-about-other-Constants-in-the-Messages-Module-Configuration-Trait)
|
|
for details). This proof is verified by the `verify_messages_proof` function.
|