Squashed 'bridges/' changes from b2099c5..23dda62 (#3369)

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

polkadot/bridges/modules/messages/README.md

@@ -101,7 +101,14 @@ the `MessageAccepted` event is emitted in the `send_message()` transaction. The
 message lane identifier and nonce that has been assigned to the message. When a message is delivered
 to the target chain, the `MessagesDelivered` event is emitted from the
 `receive_messages_delivery_proof()` transaction. The `MessagesDelivered` contains the message lane
-identifier and inclusive range of delivered message nonces.
+identifier, inclusive range of delivered message nonces and their single-bit dispatch results.
+
+Please note that the meaning of the 'dispatch result' is determined by the message dispatcher at
+the target chain. For example, in case of immediate call dispatcher it will be the `true` if call
+has been successfully dispatched and `false` if it has only been delivered. This simple mechanism
+built into the messages module allows building basic bridge applications, which only care whether
+their messages have been successfully dispatched or not. More sophisticated applications may use
+their own dispatch result delivery mechanism to deliver something larger than single bit.
 
 ### How to plug-in Messages Module to Send Messages to the Bridged Chain?
 
@@ -152,7 +159,7 @@ all required traits and will simply reject all transactions, related to outbound
 
 The `pallet_bridge_messages::Config` trait has 2 main associated types that are used to work with
 inbound messages. The `pallet_bridge_messages::Config::SourceHeaderChain` defines how we see the
-bridged chain as the source or our inbound messages. When relayer sends us a  delivery transaction,
+bridged chain as the source or our inbound messages. When relayer sends us a delivery transaction,
 this implementation must be able to parse and verify the proof of messages wrapped in this
 transaction. Normally, you would reuse the same (configurable) type on all chains that are sending
 messages to the same bridged chain.
@@ -194,7 +201,7 @@ message needs to be read. So there's another
 When choosing values for these parameters, you must also keep in mind that if proof in your scheme
 is based on finality of headers (and it is the most obvious option for Substrate-based chains with
 finality notion), then choosing too small values for these parameters may cause significant delays
-in message delivery. That's because there too many actors involved in this scheme: 1) authorities
+in message delivery. That's because there are too many actors involved in this scheme: 1) authorities
 that are finalizing headers of the target chain need to finalize header with non-empty map; 2) the
 headers relayer then needs to submit this header and its finality proof to the source chain; 3) the
 messages relayer must then send confirmation transaction (storage proof of this map) to the source
@@ -347,6 +354,23 @@ Both conditions are verified by `pallet_bridge_messages::ensure_weights_are_corr
 `pallet_bridge_messages::ensure_able_to_receive_messages` functions, which must be called from every
 runtime's tests.
 
+### Post-dispatch weight refunds of the `receive_messages_proof` call
+
+Weight formula of the `receive_messages_proof` call assumes that the dispatch fee of every message is
+paid at the target chain (where call is executed), that every message will be dispatched and that
+dispatch weight of the message will be exactly the weight that is returned from the
+`MessageDispatch::dispatch_weight` method call. This isn't true for all messages, so the call returns
+actual weight used to dispatch messages.
+
+This actual weight is the weight, returned by the weight formula, minus:
+- the weight of undispatched messages, if we have failed to dispatch because of different issues;
+- the unspent dispatch weight if the declared weight of some messages is less than their actual post-dispatch weight;
+- the pay-dispatch-fee weight for every message that had dispatch fee paid at the source chain.
+
+The last component is computed as a difference between two benchmarks results - the `receive_single_message_proof`
+benchmark (that assumes that the fee is paid during dispatch) and the `receive_single_prepaid_message_proof`
+(that assumes that the dispatch fee is already paid).
+
 ### Weight of `receive_messages_delivery_proof` call
 
 #### Related benchmarks