Call Dispatch Module
The call dispatch module has a single internal (only callable by other runtime modules) entry point
for dispatching encoded calls (pallet_bridge_dispatch::Module::dispatch). Every dispatch
(successful or not) emits a corresponding module event. The module doesn't have any call-related
requirements - they may come from the bridged chain over some message lane, or they may be crafted
locally. But in this document we'll mostly talk about this module in the context of bridges.
Every message that is being dispatched has three main characteristics:
bridgeis the 4-bytes identifier of the bridge where this message comes from. This may be the identifier of the bridged chain (likeb"rlto"for messages coming fromRialto), or the identifier of the bridge itself (b"rimi"forRialto<->Millaubridge);idis the unique id of the message within the given bridge. For messages coming from the messages module, it may worth to use a tuple(LaneId, MessageNonce)to identify a message;messageis thepallet_bridge_dispatch::MessagePayloadstructure. Thecallfield is set to the (potentially) encodedCallof this chain.
The easiest way to understand what is happening when a Call is being dispatched, is to look at the
module events set:
MessageRejectedevent is emitted if a message has been rejected even before it has reached the module. Dispatch then is called just to reflect the fact that message has been received, but we have failed to pre-process it (e.g. because we have failed to decodeMessagePayloadstructure from the proof);MessageVersionSpecMismatchevent is emitted if current runtime specification version differs from the version that has been used to encode theCall. The message payload has thespec_version, that is filled by the message submitter. If this value differs from the current runtime version, dispatch mechanism rejects to dispatch the message. Without this check, we may decode the wrongCallfor example if method arguments were changed;MessageCallDecodeFailedevent is emitted if we have failed to decodeCallfrom the payload. This may happen if the submitter has provided incorrect value in thecallfield, or if source chain storage has been corrupted. TheCallis decoded afterspec_versioncheck, so we'll never try to decodeCallfrom other runtime version;MessageSignatureMismatchevent is emitted if submitter has chose to dispatch message using specified this chain account (pallet_bridge_dispatch::CallOrigin::TargetAccountorigin), but he has failed to prove that he owns the private key for this account;MessageCallRejectedevent is emitted if the module has been deployed with some call filter and this filter has rejected theCall. In your bridge you may choose to reject all messages except e.g. balance transfer calls;MessageWeightMismatchevent is emitted if the message submitter has specified invalidCalldispatch weight in theweightfield of the message payload. The value of this field is compared to the pre-dispatch weight of the decodedCall. If it is less than the actual pre-dispatch weight, the dispatch is rejected. Keep in mind, that even if post-dispatch weight will be less than specified, the submitter still have to declare (and pay for) the maximal possible weight (that is the pre-dispatch weight);MessageDispatchedevent is emitted if the message has passed all checks and we have actually dispatched it. The dispatch may still fail, though - that's why we are including the dispatch result in the event payload.
When we talk about module in context of bridges, these events are helping in following cases:
-
when the message submitter has access to the state of both chains and wants to monitor what has happened with his message. Then he could use the message id (that he gets from the messages module events) to filter events of call dispatch module at the target chain and actually see what has happened with his message;
-
when the message submitter only has access to the source chain state (for example, when sender is the runtime module at the source chain). In this case, your bridge may have additional mechanism to deliver dispatch proofs (which are storage proof of module events) back to the source chain, thus allowing the submitter to see what has happened with his messages.