Merge commit 'e5bed7ac380b6adb54b60a2a72a2a8f07f50d6c1' as 'bridges'

polkadot/bridges/relays/bin-ethereum/Cargo.toml

@@ -0,0 +1,48 @@
+[package]
+name = "ethereum-poa-relay"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+ansi_term = "0.12"
+async-std = "1.9.0"
+async-trait = "0.1.42"
+clap = { version = "2.33.3", features = ["yaml"] }
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+env_logger = "0.8.3"
+ethabi = { git = "https://github.com/paritytech/ethabi", branch = "td-eth-types-11" }
+ethabi-contract = { git = "https://github.com/paritytech/ethabi", branch = "td-eth-types-11" }
+ethabi-derive = { git = "https://github.com/paritytech/ethabi", branch = "td-eth-types-11" }
+futures = "0.3.12"
+hex = "0.4"
+hex-literal = "0.3"
+libsecp256k1 = { version = "0.3.4", default-features = false, features = ["hmac"] }
+log = "0.4.14"
+num-traits = "0.2"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0.64"
+time = "0.2"
+
+# Bridge dependencies
+
+bp-currency-exchange = { path = "../../primitives/currency-exchange" }
+bp-eth-poa = { path = "../../primitives/ethereum-poa" }
+exchange-relay = { path = "../exchange" }
+headers-relay = { path = "../headers" }
+messages-relay = { path = "../messages" }
+relay-ethereum-client = { path = "../client-ethereum" }
+relay-rialto-client = { path = "../client-rialto" }
+relay-substrate-client = { path = "../client-substrate" }
+relay-utils = { path = "../utils" }
+rialto-runtime = { path = "../../bin/rialto/runtime" }
+
+# Substrate Dependencies
+
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "master" }
+pallet-transaction-payment = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-keyring = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }
+substrate-prometheus-endpoint = { git = "https://github.com/paritytech/substrate", branch = "master" }

polkadot/bridges/relays/bin-ethereum/README.md

@@ -0,0 +1,7 @@
+# PoA <> Substrate Bridge
+
+**DISCLAIMER:** *we recommend not using the bridge in "production" (to bridge significant amounts) just yet.
+it's missing a code audit and should still be considered alpha. we can't rule out that there are bugs that might result in loss of the bridged amounts.
+we'll update this disclaimer once that changes*
+
+These docs are very incomplete yet. Describe high-level goals here in the (near) future.

polkadot/bridges/relays/bin-ethereum/res/substrate-bridge-abi.json

@@ -0,0 +1,167 @@
+[
+	{
+		"inputs": [
+			{
+				"internalType": "bytes",
+				"name": "rawInitialHeader",
+				"type": "bytes"
+			},
+			{
+				"internalType": "uint64",
+				"name": "initialValidatorsSetId",
+				"type": "uint64"
+			},
+			{
+				"internalType": "bytes",
+				"name": "initialValidatorsSet",
+				"type": "bytes"
+			}
+		],
+		"stateMutability": "nonpayable",
+		"type": "constructor"
+	},
+	{
+		"stateMutability": "nonpayable",
+		"type": "fallback"
+	},
+	{
+		"inputs": [],
+		"name": "bestKnownHeader",
+		"outputs": [
+			{
+				"internalType": "uint256",
+				"name": "",
+				"type": "uint256"
+			},
+			{
+				"internalType": "bytes32",
+				"name": "",
+				"type": "bytes32"
+			}
+		],
+		"stateMutability": "view",
+		"type": "function"
+	},
+	{
+		"inputs": [
+			{
+				"internalType": "uint256",
+				"name": "finalityTargetNumber",
+				"type": "uint256"
+			},
+			{
+				"internalType": "bytes32",
+				"name": "finalityTargetHash",
+				"type": "bytes32"
+			},
+			{
+				"internalType": "bytes",
+				"name": "rawFinalityProof",
+				"type": "bytes"
+			}
+		],
+		"name": "importFinalityProof",
+		"outputs": [],
+		"stateMutability": "nonpayable",
+		"type": "function"
+	},
+	{
+		"inputs": [
+			{
+				"internalType": "bytes",
+				"name": "rawHeader1",
+				"type": "bytes"
+			},
+			{
+				"internalType": "bytes",
+				"name": "rawHeader2",
+				"type": "bytes"
+			},
+			{
+				"internalType": "bytes",
+				"name": "rawHeader3",
+				"type": "bytes"
+			},
+			{
+				"internalType": "bytes",
+				"name": "rawHeader4",
+				"type": "bytes"
+			}
+		],
+		"name": "importHeaders",
+		"outputs": [],
+		"stateMutability": "nonpayable",
+		"type": "function"
+	},
+	{
+		"inputs": [],
+		"name": "incompleteHeaders",
+		"outputs": [
+			{
+				"internalType": "uint256[]",
+				"name": "",
+				"type": "uint256[]"
+			},
+			{
+				"internalType": "bytes32[]",
+				"name": "",
+				"type": "bytes32[]"
+			}
+		],
+		"stateMutability": "view",
+		"type": "function"
+	},
+	{
+		"inputs": [
+			{
+				"internalType": "bytes",
+				"name": "rawHeader1",
+				"type": "bytes"
+			},
+			{
+				"internalType": "bytes",
+				"name": "rawHeader2",
+				"type": "bytes"
+			},
+			{
+				"internalType": "bytes",
+				"name": "rawHeader3",
+				"type": "bytes"
+			},
+			{
+				"internalType": "bytes",
+				"name": "rawHeader4",
+				"type": "bytes"
+			}
+		],
+		"name": "isIncompleteHeaders",
+		"outputs": [
+			{
+				"internalType": "uint256",
+				"name": "",
+				"type": "uint256"
+			}
+		],
+		"stateMutability": "view",
+		"type": "function"
+	},
+	{
+		"inputs": [
+			{
+				"internalType": "bytes32",
+				"name": "headerHash",
+				"type": "bytes32"
+			}
+		],
+		"name": "isKnownHeader",
+		"outputs": [
+			{
+				"internalType": "bool",
+				"name": "",
+				"type": "bool"
+			}
+		],
+		"stateMutability": "view",
+		"type": "function"
+	}
+]

polkadot/bridges/relays/bin-ethereum/res/substrate-bridge-metadata.txt

@@ -0,0 +1,5 @@
+Last Change Date: 2020-07-30
+Solc version: 0.6.6+commit.6c089d02.Linux.g++
+Source hash (keccak256): 0xea5d6d744f69157adc2857166792aca139c0b5b186ba89c1011358fbcad90d7e
+Source gist: https://github.com/svyatonik/substrate-bridge-sol/blob/6456d3e016c95cd5e6d5e817c23e9e69e739aa78/substrate-bridge.sol
+Compiler flags used (command to produce the file): `docker run -i ethereum/solc:0.6.6 --optimize --bin - < substrate-bridge.sol`

polkadot/bridges/relays/bin-ethereum/src/cli.yml

@@ -0,0 +1,166 @@
+name: ethsub-bridge
+version: "0.1.0"
+author: Parity Technologies <admin@parity.io>
+about: Parity Ethereum (PoA) <-> Substrate bridge
+subcommands:
+    - eth-to-sub:
+        about: Synchronize headers from Ethereum node to Substrate node.
+        args:
+            - eth-host: &eth-host
+                long: eth-host
+                value_name: ETH_HOST
+                help: Connect to Ethereum node websocket server at given host.
+                takes_value: true
+            - eth-port: &eth-port
+                long: eth-port
+                value_name: ETH_PORT
+                help: Connect to Ethereum node websocket server at given port.
+                takes_value: true
+            - sub-host: &sub-host
+                long: sub-host
+                value_name: SUB_HOST
+                help: Connect to Substrate node websocket server at given host.
+                takes_value: true
+            - sub-port: &sub-port
+                long: sub-port
+                value_name: SUB_PORT
+                help: Connect to Substrate node websocket server at given port.
+                takes_value: true
+            - sub-tx-mode:
+                long: sub-tx-mode
+                value_name: MODE
+                help: Submit headers using signed (default) or unsigned transactions. Third mode - backup - submits signed transactions only when we believe that sync has stalled.
+                takes_value: true
+                possible_values:
+                    - signed
+                    - unsigned
+                    - backup
+            - sub-signer: &sub-signer
+                long: sub-signer
+                value_name: SUB_SIGNER
+                help: The SURI of secret key to use when transactions are submitted to the Substrate node.
+            - sub-signer-password: &sub-signer-password
+                long: sub-signer-password
+                value_name: SUB_SIGNER_PASSWORD
+                help: The password for the SURI of secret key to use when transactions are submitted to the Substrate node.
+            - sub-pallet-instance: &sub-pallet-instance
+                long: instance
+                short: i
+                value_name: PALLET_INSTANCE
+                help: The instance of the bridge pallet the relay should follow.
+                takes_value: true
+                case_insensitive: true
+                possible_values:
+                  - Rialto
+                  - Kovan
+                default_value: Rialto
+            - no-prometheus: &no-prometheus
+                long: no-prometheus
+                help: Do not expose a Prometheus metric endpoint.
+            - prometheus-host: &prometheus-host
+                long: prometheus-host
+                value_name: PROMETHEUS_HOST
+                help: Expose Prometheus endpoint at given interface.
+            - prometheus-port: &prometheus-port
+                long: prometheus-port
+                value_name: PROMETHEUS_PORT
+                help: Expose Prometheus endpoint at given port.
+    - sub-to-eth:
+        about: Synchronize headers from Substrate node to Ethereum node.
+        args:
+            - eth-host: *eth-host
+            - eth-port: *eth-port
+            - eth-contract:
+                long: eth-contract
+                value_name: ETH_CONTRACT
+                help: Address of deployed bridge contract.
+                takes_value: true
+            - eth-chain-id: &eth-chain-id
+                long: eth-chain-id
+                value_name: ETH_CHAIN_ID
+                help: Chain ID to use for signing.
+            - eth-signer: &eth-signer
+                long: eth-signer
+                value_name: ETH_SIGNER
+                help: Hex-encoded secret to use when transactions are submitted to the Ethereum node.
+            - sub-host: *sub-host
+            - sub-port: *sub-port
+            - no-prometheus: *no-prometheus
+            - prometheus-host: *prometheus-host
+            - prometheus-port: *prometheus-port
+    - eth-deploy-contract:
+        about: Deploy Bridge contract on Ethereum node.
+        args:
+            - eth-host: *eth-host
+            - eth-port: *eth-port
+            - eth-signer: *eth-signer
+            - eth-chain-id: *eth-chain-id
+            - eth-contract-code:
+                long: eth-contract-code
+                value_name: ETH_CONTRACT_CODE
+                help: Bytecode of bridge contract.
+                takes_value: true
+            - sub-host: *sub-host
+            - sub-port: *sub-port
+            - sub-authorities-set-id:
+                long: sub-authorities-set-id
+                value_name: SUB_AUTHORITIES_SET_ID
+                help: ID of initial GRANDPA authorities set.
+                takes_value: true
+            - sub-authorities-set:
+                long: sub-authorities-set
+                value_name: SUB_AUTHORITIES_SET
+                help: Encoded initial GRANDPA authorities set.
+                takes_value: true
+            - sub-initial-header:
+                long: sub-initial-header
+                value_name: SUB_INITIAL_HEADER
+                help: Encoded initial Substrate header.
+                takes_value: true
+    - eth-submit-exchange-tx:
+        about: Submit lock funds transaction to Ethereum node.
+        args:
+            - eth-host: *eth-host
+            - eth-port: *eth-port
+            - eth-nonce:
+                long: eth-nonce
+                value_name: ETH_NONCE
+                help: Nonce that have to be used when building transaction. If not specified, read from PoA node.
+                takes_value: true
+            - eth-signer: *eth-signer
+            - eth-chain-id: *eth-chain-id
+            - eth-amount:
+                long: eth-amount
+                value_name: ETH_AMOUNT
+                help: Amount of ETH to lock (in wei).
+                takes_value: true
+            - sub-recipient:
+                long: sub-recipient
+                value_name: SUB_RECIPIENT
+                help: Hex-encoded Public key of funds recipient in Substrate chain.
+                takes_value: true
+    - eth-exchange-sub:
+        about: Submit proof of PoA lock funds transaction to Substrate node.
+        args:
+            - eth-host: *eth-host
+            - eth-port: *eth-port
+            - eth-start-with-block:
+                long: eth-start-with-block
+                value_name: ETH_START_WITH_BLOCK
+                help: Auto-relay transactions starting with given block number. If not specified, starts with best finalized Ethereum block (known to Substrate node) transactions.
+                takes_value: true
+                conflicts_with:
+                    - eth-tx-hash
+            - eth-tx-hash:
+                long: eth-tx-hash
+                value_name: ETH_TX_HASH
+                help: Hash of the lock funds transaction.
+                takes_value: true
+            - sub-host: *sub-host
+            - sub-port: *sub-port
+            - sub-signer: *sub-signer
+            - sub-signer-password: *sub-signer-password
+            - sub-pallet-instance: *sub-pallet-instance
+            - no-prometheus: *no-prometheus
+            - prometheus-host: *prometheus-host
+            - prometheus-port: *prometheus-port

polkadot/bridges/relays/bin-ethereum/src/ethereum_client.rs

@@ -0,0 +1,653 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::rpc_errors::RpcError;
+use crate::substrate_sync_loop::QueuedRialtoHeader;
+
+use async_trait::async_trait;
+use bp_eth_poa::signatures::secret_to_address;
+use codec::{Decode, Encode};
+use ethabi::FunctionOutputDecoder;
+use headers_relay::sync_types::SubmittedHeaders;
+use relay_ethereum_client::{
+	sign_and_submit_transaction,
+	types::{Address, CallRequest, HeaderId as EthereumHeaderId, Receipt, H256, U256},
+	Client as EthereumClient, Error as EthereumNodeError, SigningParams as EthereumSigningParams,
+};
+use relay_rialto_client::HeaderId as RialtoHeaderId;
+use relay_utils::{HeaderId, MaybeConnectionError};
+use sp_runtime::EncodedJustification;
+use std::collections::HashSet;
+
+// to encode/decode contract calls
+ethabi_contract::use_contract!(bridge_contract, "res/substrate-bridge-abi.json");
+
+type RpcResult<T> = std::result::Result<T, RpcError>;
+
+/// A trait which contains methods that work by using multiple low-level RPCs, or more complicated
+/// interactions involving, for example, an Ethereum contract.
+#[async_trait]
+pub trait EthereumHighLevelRpc {
+	/// Returns best Substrate block that PoA chain knows of.
+	async fn best_substrate_block(&self, contract_address: Address) -> RpcResult<RialtoHeaderId>;
+
+	/// Returns true if Substrate header is known to Ethereum node.
+	async fn substrate_header_known(
+		&self,
+		contract_address: Address,
+		id: RialtoHeaderId,
+	) -> RpcResult<(RialtoHeaderId, bool)>;
+
+	/// Submits Substrate headers to Ethereum contract.
+	async fn submit_substrate_headers(
+		&self,
+		params: EthereumSigningParams,
+		contract_address: Address,
+		headers: Vec<QueuedRialtoHeader>,
+	) -> SubmittedHeaders<RialtoHeaderId, RpcError>;
+
+	/// Returns ids of incomplete Substrate headers.
+	async fn incomplete_substrate_headers(&self, contract_address: Address) -> RpcResult<HashSet<RialtoHeaderId>>;
+
+	/// Complete Substrate header.
+	async fn complete_substrate_header(
+		&self,
+		params: EthereumSigningParams,
+		contract_address: Address,
+		id: RialtoHeaderId,
+		justification: EncodedJustification,
+	) -> RpcResult<RialtoHeaderId>;
+
+	/// Submit ethereum transaction.
+	async fn submit_ethereum_transaction(
+		&self,
+		params: &EthereumSigningParams,
+		contract_address: Option<Address>,
+		nonce: Option<U256>,
+		double_gas: bool,
+		encoded_call: Vec<u8>,
+	) -> RpcResult<()>;
+
+	/// Retrieve transactions receipts for given block.
+	async fn transaction_receipts(
+		&self,
+		id: EthereumHeaderId,
+		transactions: Vec<H256>,
+	) -> RpcResult<(EthereumHeaderId, Vec<Receipt>)>;
+}
+
+#[async_trait]
+impl EthereumHighLevelRpc for EthereumClient {
+	async fn best_substrate_block(&self, contract_address: Address) -> RpcResult<RialtoHeaderId> {
+		let (encoded_call, call_decoder) = bridge_contract::functions::best_known_header::call();
+		let call_request = CallRequest {
+			to: Some(contract_address),
+			data: Some(encoded_call.into()),
+			..Default::default()
+		};
+
+		let call_result = self.eth_call(call_request).await?;
+		let (number, raw_hash) = call_decoder.decode(&call_result.0)?;
+		let hash = rialto_runtime::Hash::decode(&mut &raw_hash[..])?;
+
+		if number != number.low_u32().into() {
+			return Err(RpcError::Ethereum(EthereumNodeError::InvalidSubstrateBlockNumber));
+		}
+
+		Ok(HeaderId(number.low_u32(), hash))
+	}
+
+	async fn substrate_header_known(
+		&self,
+		contract_address: Address,
+		id: RialtoHeaderId,
+	) -> RpcResult<(RialtoHeaderId, bool)> {
+		let (encoded_call, call_decoder) = bridge_contract::functions::is_known_header::call(id.1);
+		let call_request = CallRequest {
+			to: Some(contract_address),
+			data: Some(encoded_call.into()),
+			..Default::default()
+		};
+
+		let call_result = self.eth_call(call_request).await?;
+		let is_known_block = call_decoder.decode(&call_result.0)?;
+
+		Ok((id, is_known_block))
+	}
+
+	async fn submit_substrate_headers(
+		&self,
+		params: EthereumSigningParams,
+		contract_address: Address,
+		headers: Vec<QueuedRialtoHeader>,
+	) -> SubmittedHeaders<RialtoHeaderId, RpcError> {
+		// read nonce of signer
+		let address: Address = secret_to_address(&params.signer);
+		let nonce = match self.account_nonce(address).await {
+			Ok(nonce) => nonce,
+			Err(error) => {
+				return SubmittedHeaders {
+					submitted: Vec::new(),
+					incomplete: Vec::new(),
+					rejected: headers.iter().rev().map(|header| header.id()).collect(),
+					fatal_error: Some(error.into()),
+				}
+			}
+		};
+
+		// submit headers. Note that we're cloning self here. It is ok, because
+		// cloning `jsonrpsee::Client` only clones reference to background threads
+		submit_substrate_headers(
+			EthereumHeadersSubmitter {
+				client: self.clone(),
+				params,
+				contract_address,
+				nonce,
+			},
+			headers,
+		)
+		.await
+	}
+
+	async fn incomplete_substrate_headers(&self, contract_address: Address) -> RpcResult<HashSet<RialtoHeaderId>> {
+		let (encoded_call, call_decoder) = bridge_contract::functions::incomplete_headers::call();
+		let call_request = CallRequest {
+			to: Some(contract_address),
+			data: Some(encoded_call.into()),
+			..Default::default()
+		};
+
+		let call_result = self.eth_call(call_request).await?;
+
+		// Q: Is is correct to call these "incomplete_ids"?
+		let (incomplete_headers_numbers, incomplete_headers_hashes) = call_decoder.decode(&call_result.0)?;
+		let incomplete_ids = incomplete_headers_numbers
+			.into_iter()
+			.zip(incomplete_headers_hashes)
+			.filter_map(|(number, hash)| {
+				if number != number.low_u32().into() {
+					return None;
+				}
+
+				Some(HeaderId(number.low_u32(), hash))
+			})
+			.collect();
+
+		Ok(incomplete_ids)
+	}
+
+	async fn complete_substrate_header(
+		&self,
+		params: EthereumSigningParams,
+		contract_address: Address,
+		id: RialtoHeaderId,
+		justification: EncodedJustification,
+	) -> RpcResult<RialtoHeaderId> {
+		let _ = self
+			.submit_ethereum_transaction(
+				&params,
+				Some(contract_address),
+				None,
+				false,
+				bridge_contract::functions::import_finality_proof::encode_input(id.0, id.1, justification),
+			)
+			.await?;
+
+		Ok(id)
+	}
+
+	async fn submit_ethereum_transaction(
+		&self,
+		params: &EthereumSigningParams,
+		contract_address: Option<Address>,
+		nonce: Option<U256>,
+		double_gas: bool,
+		encoded_call: Vec<u8>,
+	) -> RpcResult<()> {
+		sign_and_submit_transaction(self, params, contract_address, nonce, double_gas, encoded_call)
+			.await
+			.map_err(Into::into)
+	}
+
+	async fn transaction_receipts(
+		&self,
+		id: EthereumHeaderId,
+		transactions: Vec<H256>,
+	) -> RpcResult<(EthereumHeaderId, Vec<Receipt>)> {
+		let mut transaction_receipts = Vec::with_capacity(transactions.len());
+		for transaction in transactions {
+			let transaction_receipt = self.transaction_receipt(transaction).await?;
+			transaction_receipts.push(transaction_receipt);
+		}
+		Ok((id, transaction_receipts))
+	}
+}
+
+/// Max number of headers which can be sent to Solidity contract.
+pub const HEADERS_BATCH: usize = 4;
+
+/// Substrate headers to send to the Ethereum light client.
+///
+/// The Solidity contract can only accept a fixed number of headers in one go.
+/// This struct is meant to encapsulate this limitation.
+#[derive(Debug)]
+#[cfg_attr(test, derive(Clone))]
+pub struct HeadersBatch {
+	pub header1: QueuedRialtoHeader,
+	pub header2: Option<QueuedRialtoHeader>,
+	pub header3: Option<QueuedRialtoHeader>,
+	pub header4: Option<QueuedRialtoHeader>,
+}
+
+impl HeadersBatch {
+	/// Create new headers from given header & ids collections.
+	///
+	/// This method will pop `HEADERS_BATCH` items from both collections
+	/// and construct `Headers` object and a vector of `RialtoHeaderId`s.
+	pub fn pop_from(
+		headers: &mut Vec<QueuedRialtoHeader>,
+		ids: &mut Vec<RialtoHeaderId>,
+	) -> Result<(Self, Vec<RialtoHeaderId>), ()> {
+		if headers.len() != ids.len() {
+			log::error!(target: "bridge", "Collection size mismatch ({} vs {})", headers.len(), ids.len());
+			return Err(());
+		}
+
+		let header1 = headers.pop().ok_or(())?;
+		let header2 = headers.pop();
+		let header3 = headers.pop();
+		let header4 = headers.pop();
+
+		let mut submitting_ids = Vec::with_capacity(HEADERS_BATCH);
+		for _ in 0..HEADERS_BATCH {
+			submitting_ids.extend(ids.pop().iter());
+		}
+
+		Ok((
+			Self {
+				header1,
+				header2,
+				header3,
+				header4,
+			},
+			submitting_ids,
+		))
+	}
+
+	/// Returns unified array of headers.
+	///
+	/// The first element is always `Some`.
+	fn headers(&self) -> [Option<&QueuedRialtoHeader>; HEADERS_BATCH] {
+		[
+			Some(&self.header1),
+			self.header2.as_ref(),
+			self.header3.as_ref(),
+			self.header4.as_ref(),
+		]
+	}
+
+	/// Encodes all headers. If header is not present an empty vector will be returned.
+	pub fn encode(&self) -> [Vec<u8>; HEADERS_BATCH] {
+		let encode = |h: &QueuedRialtoHeader| h.header().encode();
+		let headers = self.headers();
+		[
+			headers[0].map(encode).unwrap_or_default(),
+			headers[1].map(encode).unwrap_or_default(),
+			headers[2].map(encode).unwrap_or_default(),
+			headers[3].map(encode).unwrap_or_default(),
+		]
+	}
+	/// Returns number of contained headers.
+	pub fn len(&self) -> usize {
+		let is_set = |h: &Option<&QueuedRialtoHeader>| if h.is_some() { 1 } else { 0 };
+		self.headers().iter().map(is_set).sum()
+	}
+
+	/// Remove headers starting from `idx` (0-based) from this collection.
+	///
+	/// The collection will be left with `[0, idx)` headers.
+	/// Returns `Err` when `idx == 0`, since `Headers` must contain at least one header,
+	/// or when `idx > HEADERS_BATCH`.
+	pub fn split_off(&mut self, idx: usize) -> Result<(), ()> {
+		if idx == 0 || idx > HEADERS_BATCH {
+			return Err(());
+		}
+		let mut vals: [_; HEADERS_BATCH] = [&mut None, &mut self.header2, &mut self.header3, &mut self.header4];
+		for val in vals.iter_mut().skip(idx) {
+			**val = None;
+		}
+		Ok(())
+	}
+}
+
+/// Substrate headers submitter API.
+#[async_trait]
+trait HeadersSubmitter {
+	/// Returns Ok(0) if all given not-yet-imported headers are complete.
+	/// Returns Ok(index != 0) where index is 1-based index of first header that is incomplete.
+	///
+	/// Returns Err(()) if contract has rejected headers. This means that the contract is
+	/// unable to import first header (e.g. it may already be imported).
+	async fn is_headers_incomplete(&self, headers: &HeadersBatch) -> RpcResult<usize>;
+
+	/// Submit given headers to Ethereum node.
+	async fn submit_headers(&mut self, headers: HeadersBatch) -> RpcResult<()>;
+}
+
+/// Implementation of Substrate headers submitter that sends headers to running Ethereum node.
+struct EthereumHeadersSubmitter {
+	client: EthereumClient,
+	params: EthereumSigningParams,
+	contract_address: Address,
+	nonce: U256,
+}
+
+#[async_trait]
+impl HeadersSubmitter for EthereumHeadersSubmitter {
+	async fn is_headers_incomplete(&self, headers: &HeadersBatch) -> RpcResult<usize> {
+		let [h1, h2, h3, h4] = headers.encode();
+		let (encoded_call, call_decoder) = bridge_contract::functions::is_incomplete_headers::call(h1, h2, h3, h4);
+		let call_request = CallRequest {
+			to: Some(self.contract_address),
+			data: Some(encoded_call.into()),
+			..Default::default()
+		};
+
+		let call_result = self.client.eth_call(call_request).await?;
+		let incomplete_index: U256 = call_decoder.decode(&call_result.0)?;
+		if incomplete_index > HEADERS_BATCH.into() {
+			return Err(RpcError::Ethereum(EthereumNodeError::InvalidIncompleteIndex));
+		}
+
+		Ok(incomplete_index.low_u32() as _)
+	}
+
+	async fn submit_headers(&mut self, headers: HeadersBatch) -> RpcResult<()> {
+		let [h1, h2, h3, h4] = headers.encode();
+		let result = self
+			.client
+			.submit_ethereum_transaction(
+				&self.params,
+				Some(self.contract_address),
+				Some(self.nonce),
+				false,
+				bridge_contract::functions::import_headers::encode_input(h1, h2, h3, h4),
+			)
+			.await;
+
+		if result.is_ok() {
+			self.nonce += U256::one();
+		}
+
+		result
+	}
+}
+
+/// Submit multiple Substrate headers.
+async fn submit_substrate_headers(
+	mut header_submitter: impl HeadersSubmitter,
+	mut headers: Vec<QueuedRialtoHeader>,
+) -> SubmittedHeaders<RialtoHeaderId, RpcError> {
+	let mut submitted_headers = SubmittedHeaders::default();
+
+	let mut ids = headers.iter().map(|header| header.id()).rev().collect::<Vec<_>>();
+	headers.reverse();
+
+	while !headers.is_empty() {
+		let (headers, submitting_ids) =
+			HeadersBatch::pop_from(&mut headers, &mut ids).expect("Headers and ids are not empty; qed");
+
+		submitted_headers.fatal_error =
+			submit_substrate_headers_batch(&mut header_submitter, &mut submitted_headers, submitting_ids, headers)
+				.await;
+
+		if submitted_headers.fatal_error.is_some() {
+			ids.reverse();
+			submitted_headers.rejected.extend(ids);
+			break;
+		}
+	}
+
+	submitted_headers
+}
+
+/// Submit 4 Substrate headers in single PoA transaction.
+async fn submit_substrate_headers_batch(
+	header_submitter: &mut impl HeadersSubmitter,
+	submitted_headers: &mut SubmittedHeaders<RialtoHeaderId, RpcError>,
+	mut ids: Vec<RialtoHeaderId>,
+	mut headers: HeadersBatch,
+) -> Option<RpcError> {
+	debug_assert_eq!(ids.len(), headers.len(),);
+
+	// if parent of first header is either incomplete, or rejected, we assume that contract
+	// will reject this header as well
+	let parent_id = headers.header1.parent_id();
+	if submitted_headers.rejected.contains(&parent_id) || submitted_headers.incomplete.contains(&parent_id) {
+		submitted_headers.rejected.extend(ids);
+		return None;
+	}
+
+	// check if headers are incomplete
+	let incomplete_header_index = match header_submitter.is_headers_incomplete(&headers).await {
+		// All headers valid
+		Ok(0) => None,
+		Ok(incomplete_header_index) => Some(incomplete_header_index),
+		Err(error) => {
+			// contract has rejected all headers => we do not want to submit it
+			submitted_headers.rejected.extend(ids);
+			if error.is_connection_error() {
+				return Some(error);
+			} else {
+				return None;
+			}
+		}
+	};
+
+	// Modify `ids` and `headers` to only contain values that are going to be accepted.
+	let rejected = if let Some(idx) = incomplete_header_index {
+		let len = std::cmp::min(idx, ids.len());
+		headers
+			.split_off(len)
+			.expect("len > 0, the case where all headers are valid is converted to None; qed");
+		ids.split_off(len)
+	} else {
+		Vec::new()
+	};
+	let submitted = ids;
+	let submit_result = header_submitter.submit_headers(headers).await;
+	match submit_result {
+		Ok(_) => {
+			if incomplete_header_index.is_some() {
+				submitted_headers.incomplete.extend(submitted.iter().last().cloned());
+			}
+			submitted_headers.submitted.extend(submitted);
+			submitted_headers.rejected.extend(rejected);
+			None
+		}
+		Err(error) => {
+			submitted_headers.rejected.extend(submitted);
+			submitted_headers.rejected.extend(rejected);
+			Some(error)
+		}
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+	use sp_runtime::traits::Header;
+
+	struct TestHeadersSubmitter {
+		incomplete: Vec<RialtoHeaderId>,
+		failed: Vec<RialtoHeaderId>,
+	}
+
+	#[async_trait]
+	impl HeadersSubmitter for TestHeadersSubmitter {
+		async fn is_headers_incomplete(&self, headers: &HeadersBatch) -> RpcResult<usize> {
+			if self.incomplete.iter().any(|i| i.0 == headers.header1.id().0) {
+				Ok(1)
+			} else {
+				Ok(0)
+			}
+		}
+
+		async fn submit_headers(&mut self, headers: HeadersBatch) -> RpcResult<()> {
+			if self.failed.iter().any(|i| i.0 == headers.header1.id().0) {
+				Err(RpcError::Ethereum(EthereumNodeError::InvalidSubstrateBlockNumber))
+			} else {
+				Ok(())
+			}
+		}
+	}
+
+	fn header(number: rialto_runtime::BlockNumber) -> QueuedRialtoHeader {
+		QueuedRialtoHeader::new(
+			rialto_runtime::Header::new(
+				number,
+				Default::default(),
+				Default::default(),
+				if number == 0 {
+					Default::default()
+				} else {
+					header(number - 1).id().1
+				},
+				Default::default(),
+			)
+			.into(),
+		)
+	}
+
+	#[test]
+	fn descendants_of_incomplete_headers_are_not_submitted() {
+		let submitted_headers = async_std::task::block_on(submit_substrate_headers(
+			TestHeadersSubmitter {
+				incomplete: vec![header(5).id()],
+				failed: vec![],
+			},
+			vec![header(5), header(6)],
+		));
+		assert_eq!(submitted_headers.submitted, vec![header(5).id()]);
+		assert_eq!(submitted_headers.incomplete, vec![header(5).id()]);
+		assert_eq!(submitted_headers.rejected, vec![header(6).id()]);
+		assert!(submitted_headers.fatal_error.is_none());
+	}
+
+	#[test]
+	fn headers_after_fatal_error_are_not_submitted() {
+		let submitted_headers = async_std::task::block_on(submit_substrate_headers(
+			TestHeadersSubmitter {
+				incomplete: vec![],
+				failed: vec![header(9).id()],
+			},
+			vec![
+				header(5),
+				header(6),
+				header(7),
+				header(8),
+				header(9),
+				header(10),
+				header(11),
+			],
+		));
+		assert_eq!(
+			submitted_headers.submitted,
+			vec![header(5).id(), header(6).id(), header(7).id(), header(8).id()]
+		);
+		assert_eq!(submitted_headers.incomplete, vec![]);
+		assert_eq!(
+			submitted_headers.rejected,
+			vec![header(9).id(), header(10).id(), header(11).id(),]
+		);
+		assert!(submitted_headers.fatal_error.is_some());
+	}
+
+	fn headers_batch() -> HeadersBatch {
+		let mut init_headers = vec![header(1), header(2), header(3), header(4), header(5)];
+		init_headers.reverse();
+		let mut init_ids = init_headers.iter().map(|h| h.id()).collect();
+		let (headers, ids) = HeadersBatch::pop_from(&mut init_headers, &mut init_ids).unwrap();
+		assert_eq!(init_headers, vec![header(5)]);
+		assert_eq!(init_ids, vec![header(5).id()]);
+		assert_eq!(
+			ids,
+			vec![header(1).id(), header(2).id(), header(3).id(), header(4).id()]
+		);
+		headers
+	}
+
+	#[test]
+	fn headers_batch_len() {
+		let headers = headers_batch();
+		assert_eq!(headers.len(), 4);
+	}
+
+	#[test]
+	fn headers_batch_encode() {
+		let headers = headers_batch();
+		assert_eq!(
+			headers.encode(),
+			[
+				header(1).header().encode(),
+				header(2).header().encode(),
+				header(3).header().encode(),
+				header(4).header().encode(),
+			]
+		);
+	}
+
+	#[test]
+	fn headers_batch_split_off() {
+		// given
+		let mut headers = headers_batch();
+
+		// when
+		assert!(headers.split_off(0).is_err());
+		assert_eq!(headers.header1, header(1));
+		assert!(headers.header2.is_some());
+		assert!(headers.header3.is_some());
+		assert!(headers.header4.is_some());
+
+		// when
+		let mut h = headers.clone();
+		h.split_off(1).unwrap();
+		assert!(h.header2.is_none());
+		assert!(h.header3.is_none());
+		assert!(h.header4.is_none());
+
+		// when
+		let mut h = headers.clone();
+		h.split_off(2).unwrap();
+		assert!(h.header2.is_some());
+		assert!(h.header3.is_none());
+		assert!(h.header4.is_none());
+
+		// when
+		let mut h = headers.clone();
+		h.split_off(3).unwrap();
+		assert!(h.header2.is_some());
+		assert!(h.header3.is_some());
+		assert!(h.header4.is_none());
+
+		// when
+		let mut h = headers;
+		h.split_off(4).unwrap();
+		assert!(h.header2.is_some());
+		assert!(h.header3.is_some());
+		assert!(h.header4.is_some());
+	}
+}

polkadot/bridges/relays/bin-ethereum/src/ethereum_deploy_contract.rs

@@ -0,0 +1,154 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::ethereum_client::{bridge_contract, EthereumHighLevelRpc};
+use crate::rpc_errors::RpcError;
+
+use codec::{Decode, Encode};
+use num_traits::Zero;
+use relay_ethereum_client::{
+	Client as EthereumClient, ConnectionParams as EthereumConnectionParams, SigningParams as EthereumSigningParams,
+};
+use relay_rialto_client::{HeaderId as RialtoHeaderId, Rialto};
+use relay_substrate_client::{
+	Client as SubstrateClient, ConnectionParams as SubstrateConnectionParams, OpaqueGrandpaAuthoritiesSet,
+};
+use relay_utils::HeaderId;
+
+/// Ethereum synchronization parameters.
+#[derive(Debug)]
+pub struct EthereumDeployContractParams {
+	/// Ethereum connection params.
+	pub eth_params: EthereumConnectionParams,
+	/// Ethereum signing params.
+	pub eth_sign: EthereumSigningParams,
+	/// Ethereum contract bytecode.
+	pub eth_contract_code: Vec<u8>,
+	/// Substrate connection params.
+	pub sub_params: SubstrateConnectionParams,
+	/// Initial authorities set id.
+	pub sub_initial_authorities_set_id: Option<u64>,
+	/// Initial authorities set.
+	pub sub_initial_authorities_set: Option<Vec<u8>>,
+	/// Initial header.
+	pub sub_initial_header: Option<Vec<u8>>,
+}
+
+/// Deploy Bridge contract on Ethereum chain.
+pub async fn run(params: EthereumDeployContractParams) {
+	let EthereumDeployContractParams {
+		eth_params,
+		eth_sign,
+		sub_params,
+		sub_initial_authorities_set_id,
+		sub_initial_authorities_set,
+		sub_initial_header,
+		eth_contract_code,
+	} = params;
+
+	let result = async move {
+		let eth_client = EthereumClient::new(eth_params).await.map_err(RpcError::Ethereum)?;
+		let sub_client = SubstrateClient::<Rialto>::new(sub_params).await.map_err(RpcError::Substrate)?;
+
+		let (initial_header_id, initial_header) = prepare_initial_header(&sub_client, sub_initial_header).await?;
+		let initial_set_id = sub_initial_authorities_set_id.unwrap_or(0);
+		let initial_set = prepare_initial_authorities_set(
+			&sub_client,
+			initial_header_id.1,
+			sub_initial_authorities_set,
+		).await?;
+
+		log::info!(
+			target: "bridge",
+			"Deploying Ethereum contract.\r\n\tInitial header: {:?}\r\n\tInitial header id: {:?}\r\n\tInitial header encoded: {}\r\n\tInitial authorities set ID: {}\r\n\tInitial authorities set: {}",
+			initial_header,
+			initial_header_id,
+			hex::encode(&initial_header),
+			initial_set_id,
+			hex::encode(&initial_set),
+		);
+
+		deploy_bridge_contract(
+			&eth_client,
+			&eth_sign,
+			eth_contract_code,
+			initial_header,
+			initial_set_id,
+			initial_set,
+		).await
+	}.await;
+
+	if let Err(error) = result {
+		log::error!(target: "bridge", "{}", error);
+	}
+}
+
+/// Prepare initial header.
+async fn prepare_initial_header(
+	sub_client: &SubstrateClient<Rialto>,
+	sub_initial_header: Option<Vec<u8>>,
+) -> Result<(RialtoHeaderId, Vec<u8>), String> {
+	match sub_initial_header {
+		Some(raw_initial_header) => match rialto_runtime::Header::decode(&mut &raw_initial_header[..]) {
+			Ok(initial_header) => Ok((
+				HeaderId(initial_header.number, initial_header.hash()),
+				raw_initial_header,
+			)),
+			Err(error) => Err(format!("Error decoding initial header: {}", error)),
+		},
+		None => {
+			let initial_header = sub_client.header_by_number(Zero::zero()).await;
+			initial_header
+				.map(|header| (HeaderId(Zero::zero(), header.hash()), header.encode()))
+				.map_err(|error| format!("Error reading Substrate genesis header: {:?}", error))
+		}
+	}
+}
+
+/// Prepare initial GRANDPA authorities set.
+async fn prepare_initial_authorities_set(
+	sub_client: &SubstrateClient<Rialto>,
+	sub_initial_header_hash: rialto_runtime::Hash,
+	sub_initial_authorities_set: Option<Vec<u8>>,
+) -> Result<OpaqueGrandpaAuthoritiesSet, String> {
+	let initial_authorities_set = match sub_initial_authorities_set {
+		Some(initial_authorities_set) => Ok(initial_authorities_set),
+		None => sub_client.grandpa_authorities_set(sub_initial_header_hash).await,
+	};
+
+	initial_authorities_set.map_err(|error| format!("Error reading GRANDPA authorities set: {:?}", error))
+}
+
+/// Deploy bridge contract to Ethereum chain.
+async fn deploy_bridge_contract(
+	eth_client: &EthereumClient,
+	params: &EthereumSigningParams,
+	contract_code: Vec<u8>,
+	initial_header: Vec<u8>,
+	initial_set_id: u64,
+	initial_authorities: Vec<u8>,
+) -> Result<(), String> {
+	eth_client
+		.submit_ethereum_transaction(
+			params,
+			None,
+			None,
+			false,
+			bridge_contract::constructor(contract_code, initial_header, initial_set_id, initial_authorities),
+		)
+		.await
+		.map_err(|error| format!("Error deploying contract: {:?}", error))
+}

polkadot/bridges/relays/bin-ethereum/src/ethereum_exchange.rs

@@ -0,0 +1,403 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Relaying proofs of PoA -> Substrate exchange transactions.
+
+use crate::instances::BridgeInstance;
+use crate::rialto_client::{SubmitEthereumExchangeTransactionProof, SubstrateHighLevelRpc};
+use crate::rpc_errors::RpcError;
+use crate::substrate_types::into_substrate_ethereum_receipt;
+
+use async_trait::async_trait;
+use bp_currency_exchange::MaybeLockFundsTransaction;
+use exchange_relay::exchange::{
+	relay_single_transaction_proof, SourceBlock, SourceClient, SourceTransaction, TargetClient,
+	TransactionProofPipeline,
+};
+use exchange_relay::exchange_loop::{run as run_loop, InMemoryStorage};
+use relay_ethereum_client::{
+	types::{
+		HeaderId as EthereumHeaderId, HeaderWithTransactions as EthereumHeaderWithTransactions,
+		Transaction as EthereumTransaction, TransactionHash as EthereumTransactionHash, H256, HEADER_ID_PROOF,
+	},
+	Client as EthereumClient, ConnectionParams as EthereumConnectionParams,
+};
+use relay_rialto_client::{Rialto, SigningParams as RialtoSigningParams};
+use relay_substrate_client::{
+	Chain as SubstrateChain, Client as SubstrateClient, ConnectionParams as SubstrateConnectionParams,
+};
+use relay_utils::{metrics::MetricsParams, relay_loop::Client as RelayClient, HeaderId};
+use rialto_runtime::exchange::EthereumTransactionInclusionProof;
+use std::{sync::Arc, time::Duration};
+
+/// Interval at which we ask Ethereum node for updates.
+const ETHEREUM_TICK_INTERVAL: Duration = Duration::from_secs(10);
+
+/// Exchange relay mode.
+#[derive(Debug)]
+pub enum ExchangeRelayMode {
+	/// Relay single transaction and quit.
+	Single(EthereumTransactionHash),
+	/// Auto-relay transactions starting with given block.
+	Auto(Option<u64>),
+}
+
+/// PoA exchange transaction relay params.
+pub struct EthereumExchangeParams {
+	/// Ethereum connection params.
+	pub eth_params: EthereumConnectionParams,
+	/// Substrate connection params.
+	pub sub_params: SubstrateConnectionParams,
+	/// Substrate signing params.
+	pub sub_sign: RialtoSigningParams,
+	/// Relay working mode.
+	pub mode: ExchangeRelayMode,
+	/// Metrics parameters.
+	pub metrics_params: MetricsParams,
+	/// Instance of the bridge pallet being synchronized.
+	pub instance: Arc<dyn BridgeInstance>,
+}
+
+impl std::fmt::Debug for EthereumExchangeParams {
+	fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+		f.debug_struct("EthereumExchangeParams")
+			.field("eth_params", &self.eth_params)
+			.field("sub_params", &self.sub_params)
+			.field("sub_sign", &sp_core::Pair::public(&self.sub_sign))
+			.field("mode", &self.mode)
+			.field("metrics_params", &self.metrics_params)
+			.field("instance", &self.instance)
+			.finish()
+	}
+}
+
+/// Ethereum to Substrate exchange pipeline.
+struct EthereumToSubstrateExchange;
+
+impl TransactionProofPipeline for EthereumToSubstrateExchange {
+	const SOURCE_NAME: &'static str = "Ethereum";
+	const TARGET_NAME: &'static str = "Substrate";
+
+	type Block = EthereumSourceBlock;
+	type TransactionProof = EthereumTransactionInclusionProof;
+}
+
+/// Ethereum source block.
+struct EthereumSourceBlock(EthereumHeaderWithTransactions);
+
+impl SourceBlock for EthereumSourceBlock {
+	type Hash = H256;
+	type Number = u64;
+	type Transaction = EthereumSourceTransaction;
+
+	fn id(&self) -> EthereumHeaderId {
+		HeaderId(
+			self.0.number.expect(HEADER_ID_PROOF).as_u64(),
+			self.0.hash.expect(HEADER_ID_PROOF),
+		)
+	}
+
+	fn transactions(&self) -> Vec<Self::Transaction> {
+		self.0
+			.transactions
+			.iter()
+			.cloned()
+			.map(EthereumSourceTransaction)
+			.collect()
+	}
+}
+
+/// Ethereum source transaction.
+struct EthereumSourceTransaction(EthereumTransaction);
+
+impl SourceTransaction for EthereumSourceTransaction {
+	type Hash = EthereumTransactionHash;
+
+	fn hash(&self) -> Self::Hash {
+		self.0.hash
+	}
+}
+
+/// Ethereum node as transactions proof source.
+#[derive(Clone)]
+struct EthereumTransactionsSource {
+	client: EthereumClient,
+}
+
+#[async_trait]
+impl RelayClient for EthereumTransactionsSource {
+	type Error = RpcError;
+
+	async fn reconnect(&mut self) -> Result<(), RpcError> {
+		self.client.reconnect().await.map_err(Into::into)
+	}
+}
+
+#[async_trait]
+impl SourceClient<EthereumToSubstrateExchange> for EthereumTransactionsSource {
+	async fn tick(&self) {
+		async_std::task::sleep(ETHEREUM_TICK_INTERVAL).await;
+	}
+
+	async fn block_by_hash(&self, hash: H256) -> Result<EthereumSourceBlock, RpcError> {
+		self.client
+			.header_by_hash_with_transactions(hash)
+			.await
+			.map(EthereumSourceBlock)
+			.map_err(Into::into)
+	}
+
+	async fn block_by_number(&self, number: u64) -> Result<EthereumSourceBlock, RpcError> {
+		self.client
+			.header_by_number_with_transactions(number)
+			.await
+			.map(EthereumSourceBlock)
+			.map_err(Into::into)
+	}
+
+	async fn transaction_block(
+		&self,
+		hash: &EthereumTransactionHash,
+	) -> Result<Option<(EthereumHeaderId, usize)>, RpcError> {
+		let eth_tx = match self.client.transaction_by_hash(*hash).await? {
+			Some(eth_tx) => eth_tx,
+			None => return Ok(None),
+		};
+
+		// we need transaction to be mined => check if it is included in the block
+		let (eth_header_id, eth_tx_index) = match (eth_tx.block_number, eth_tx.block_hash, eth_tx.transaction_index) {
+			(Some(block_number), Some(block_hash), Some(transaction_index)) => (
+				HeaderId(block_number.as_u64(), block_hash),
+				transaction_index.as_u64() as _,
+			),
+			_ => return Ok(None),
+		};
+
+		Ok(Some((eth_header_id, eth_tx_index)))
+	}
+
+	async fn transaction_proof(
+		&self,
+		block: &EthereumSourceBlock,
+		tx_index: usize,
+	) -> Result<EthereumTransactionInclusionProof, RpcError> {
+		const TRANSACTION_HAS_RAW_FIELD_PROOF: &str = "RPC level checks that transactions from Ethereum\
+			node are having `raw` field; qed";
+		const BLOCK_HAS_HASH_FIELD_PROOF: &str = "RPC level checks that block has `hash` field; qed";
+
+		let mut transaction_proof = Vec::with_capacity(block.0.transactions.len());
+		for tx in &block.0.transactions {
+			let raw_tx_receipt = self
+				.client
+				.transaction_receipt(tx.hash)
+				.await
+				.map(|receipt| into_substrate_ethereum_receipt(&receipt))
+				.map(|receipt| receipt.rlp())?;
+			let raw_tx = tx.raw.clone().expect(TRANSACTION_HAS_RAW_FIELD_PROOF).0;
+			transaction_proof.push((raw_tx, raw_tx_receipt));
+		}
+
+		Ok(EthereumTransactionInclusionProof {
+			block: block.0.hash.expect(BLOCK_HAS_HASH_FIELD_PROOF),
+			index: tx_index as _,
+			proof: transaction_proof,
+		})
+	}
+}
+
+/// Substrate node as transactions proof target.
+#[derive(Clone)]
+struct SubstrateTransactionsTarget {
+	client: SubstrateClient<Rialto>,
+	sign_params: RialtoSigningParams,
+	bridge_instance: Arc<dyn BridgeInstance>,
+}
+
+#[async_trait]
+impl RelayClient for SubstrateTransactionsTarget {
+	type Error = RpcError;
+
+	async fn reconnect(&mut self) -> Result<(), RpcError> {
+		Ok(self.client.reconnect().await?)
+	}
+}
+
+#[async_trait]
+impl TargetClient<EthereumToSubstrateExchange> for SubstrateTransactionsTarget {
+	async fn tick(&self) {
+		async_std::task::sleep(Rialto::AVERAGE_BLOCK_INTERVAL).await;
+	}
+
+	async fn is_header_known(&self, id: &EthereumHeaderId) -> Result<bool, RpcError> {
+		self.client.ethereum_header_known(*id).await
+	}
+
+	async fn is_header_finalized(&self, id: &EthereumHeaderId) -> Result<bool, RpcError> {
+		// we check if header is finalized by simple comparison of the header number and
+		// number of best finalized PoA header known to Substrate node.
+		//
+		// this may lead to failure in tx proof import if PoA reorganization has happened
+		// after we have checked that our tx has been included into given block
+		//
+		// the fix is easy, but since this code is mostly developed for demonstration purposes,
+		// I'm leaving this KISS-based design here
+		let best_finalized_ethereum_block = self.client.best_ethereum_finalized_block().await?;
+		Ok(id.0 <= best_finalized_ethereum_block.0)
+	}
+
+	async fn best_finalized_header_id(&self) -> Result<EthereumHeaderId, RpcError> {
+		// we can't continue to relay exchange proofs if Substrate node is out of sync, because
+		// it may have already received (some of) proofs that we're going to relay
+		self.client.ensure_synced().await?;
+
+		self.client.best_ethereum_finalized_block().await
+	}
+
+	async fn filter_transaction_proof(&self, proof: &EthereumTransactionInclusionProof) -> Result<bool, RpcError> {
+		// let's try to parse transaction locally
+		let (raw_tx, raw_tx_receipt) = &proof.proof[proof.index as usize];
+		let parse_result = rialto_runtime::exchange::EthTransaction::parse(raw_tx);
+		if parse_result.is_err() {
+			return Ok(false);
+		}
+
+		// now let's check if transaction is successful
+		match bp_eth_poa::Receipt::is_successful_raw_receipt(raw_tx_receipt) {
+			Ok(true) => (),
+			_ => return Ok(false),
+		}
+
+		// seems that transaction is relayable - let's check if runtime is able to import it
+		// (we can't if e.g. header is pruned or there's some issue with tx data)
+		self.client.verify_exchange_transaction_proof(proof.clone()).await
+	}
+
+	async fn submit_transaction_proof(&self, proof: EthereumTransactionInclusionProof) -> Result<(), RpcError> {
+		let (sign_params, bridge_instance) = (self.sign_params.clone(), self.bridge_instance.clone());
+		self.client
+			.submit_exchange_transaction_proof(sign_params, bridge_instance, proof)
+			.await
+	}
+}
+
+/// Relay exchange transaction proof(s) to Substrate node.
+pub async fn run(params: EthereumExchangeParams) {
+	match params.mode {
+		ExchangeRelayMode::Single(eth_tx_hash) => {
+			let result = run_single_transaction_relay(params, eth_tx_hash).await;
+			match result {
+				Ok(_) => log::info!(
+					target: "bridge",
+					"Ethereum transaction {} proof has been successfully submitted to Substrate node",
+					eth_tx_hash,
+				),
+				Err(err) => log::error!(
+					target: "bridge",
+					"Error submitting Ethereum transaction {} proof to Substrate node: {}",
+					eth_tx_hash,
+					err,
+				),
+			}
+		}
+		ExchangeRelayMode::Auto(eth_start_with_block_number) => {
+			let result = run_auto_transactions_relay_loop(params, eth_start_with_block_number).await;
+			if let Err(err) = result {
+				log::error!(
+					target: "bridge",
+					"Error auto-relaying Ethereum transactions proofs to Substrate node: {}",
+					err,
+				);
+			}
+		}
+	}
+}
+
+/// Run single transaction proof relay and stop.
+async fn run_single_transaction_relay(params: EthereumExchangeParams, eth_tx_hash: H256) -> Result<(), String> {
+	let EthereumExchangeParams {
+		eth_params,
+		sub_params,
+		sub_sign,
+		instance,
+		..
+	} = params;
+
+	let eth_client = EthereumClient::new(eth_params).await.map_err(RpcError::Ethereum)?;
+	let sub_client = SubstrateClient::<Rialto>::new(sub_params)
+		.await
+		.map_err(RpcError::Substrate)?;
+
+	let source = EthereumTransactionsSource { client: eth_client };
+	let target = SubstrateTransactionsTarget {
+		client: sub_client,
+		sign_params: sub_sign,
+		bridge_instance: instance,
+	};
+
+	relay_single_transaction_proof(&source, &target, eth_tx_hash).await
+}
+
+async fn run_auto_transactions_relay_loop(
+	params: EthereumExchangeParams,
+	eth_start_with_block_number: Option<u64>,
+) -> Result<(), String> {
+	let EthereumExchangeParams {
+		eth_params,
+		sub_params,
+		sub_sign,
+		metrics_params,
+		instance,
+		..
+	} = params;
+
+	let eth_client = EthereumClient::new(eth_params)
+		.await
+		.map_err(|err| format!("Error starting Ethereum client: {:?}", err))?;
+	let sub_client = SubstrateClient::<Rialto>::new(sub_params)
+		.await
+		.map_err(|err| format!("Error starting Substrate client: {:?}", err))?;
+
+	let eth_start_with_block_number = match eth_start_with_block_number {
+		Some(eth_start_with_block_number) => eth_start_with_block_number,
+		None => {
+			sub_client
+				.best_ethereum_finalized_block()
+				.await
+				.map_err(|err| {
+					format!(
+						"Error retrieving best finalized Ethereum block from Substrate node: {:?}",
+						err
+					)
+				})?
+				.0
+		}
+	};
+
+	run_loop(
+		InMemoryStorage::new(eth_start_with_block_number),
+		EthereumTransactionsSource { client: eth_client },
+		SubstrateTransactionsTarget {
+			client: sub_client,
+			sign_params: sub_sign,
+			bridge_instance: instance,
+		},
+		metrics_params,
+		futures::future::pending(),
+	)
+	.await?;
+
+	Ok(())
+}

polkadot/bridges/relays/bin-ethereum/src/ethereum_exchange_submit.rs

@@ -0,0 +1,114 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Submitting Ethereum -> Substrate exchange transactions.
+
+use bp_eth_poa::{
+	signatures::{secret_to_address, SignTransaction},
+	UnsignedTransaction,
+};
+use relay_ethereum_client::{
+	types::{CallRequest, U256},
+	Client as EthereumClient, ConnectionParams as EthereumConnectionParams, SigningParams as EthereumSigningParams,
+};
+use rialto_runtime::exchange::LOCK_FUNDS_ADDRESS;
+
+/// Ethereum exchange transaction params.
+#[derive(Debug)]
+pub struct EthereumExchangeSubmitParams {
+	/// Ethereum connection params.
+	pub eth_params: EthereumConnectionParams,
+	/// Ethereum signing params.
+	pub eth_sign: EthereumSigningParams,
+	/// Ethereum signer nonce.
+	pub eth_nonce: Option<U256>,
+	/// Amount of Ethereum tokens to lock.
+	pub eth_amount: U256,
+	/// Funds recipient on Substrate side.
+	pub sub_recipient: [u8; 32],
+}
+
+/// Submit single Ethereum -> Substrate exchange transaction.
+pub async fn run(params: EthereumExchangeSubmitParams) {
+	let EthereumExchangeSubmitParams {
+		eth_params,
+		eth_sign,
+		eth_nonce,
+		eth_amount,
+		sub_recipient,
+	} = params;
+
+	let result: Result<_, String> = async move {
+		let eth_client = EthereumClient::new(eth_params)
+			.await
+			.map_err(|err| format!("error connecting to Ethereum node: {:?}", err))?;
+
+		let eth_signer_address = secret_to_address(&eth_sign.signer);
+		let sub_recipient_encoded = sub_recipient;
+		let nonce = match eth_nonce {
+			Some(eth_nonce) => eth_nonce,
+			None => eth_client
+				.account_nonce(eth_signer_address)
+				.await
+				.map_err(|err| format!("error fetching acount nonce: {:?}", err))?,
+		};
+		let gas = eth_client
+			.estimate_gas(CallRequest {
+				from: Some(eth_signer_address),
+				to: Some(LOCK_FUNDS_ADDRESS.into()),
+				value: Some(eth_amount),
+				data: Some(sub_recipient_encoded.to_vec().into()),
+				..Default::default()
+			})
+			.await
+			.map_err(|err| format!("error estimating gas requirements: {:?}", err))?;
+		let eth_tx_unsigned = UnsignedTransaction {
+			nonce,
+			gas_price: eth_sign.gas_price,
+			gas,
+			to: Some(LOCK_FUNDS_ADDRESS.into()),
+			value: eth_amount,
+			payload: sub_recipient_encoded.to_vec(),
+		};
+		let eth_tx_signed = eth_tx_unsigned
+			.clone()
+			.sign_by(&eth_sign.signer, Some(eth_sign.chain_id));
+		eth_client
+			.submit_transaction(eth_tx_signed)
+			.await
+			.map_err(|err| format!("error submitting transaction: {:?}", err))?;
+
+		Ok(eth_tx_unsigned)
+	}
+	.await;
+
+	match result {
+		Ok(eth_tx_unsigned) => {
+			log::info!(
+				target: "bridge",
+				"Exchange transaction has been submitted to Ethereum node: {:?}",
+				eth_tx_unsigned,
+			);
+		}
+		Err(err) => {
+			log::error!(
+				target: "bridge",
+				"Error submitting exchange transaction to Ethereum node: {}",
+				err,
+			);
+		}
+	}
+}

polkadot/bridges/relays/bin-ethereum/src/ethereum_sync_loop.rs

@@ -0,0 +1,298 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Ethereum PoA -> Rialto-Substrate synchronization.
+
+use crate::ethereum_client::EthereumHighLevelRpc;
+use crate::instances::BridgeInstance;
+use crate::rialto_client::{SubmitEthereumHeaders, SubstrateHighLevelRpc};
+use crate::rpc_errors::RpcError;
+use crate::substrate_types::{into_substrate_ethereum_header, into_substrate_ethereum_receipts};
+
+use async_trait::async_trait;
+use codec::Encode;
+use headers_relay::{
+	sync::{HeadersSyncParams, TargetTransactionMode},
+	sync_loop::{SourceClient, TargetClient},
+	sync_types::{HeadersSyncPipeline, QueuedHeader, SourceHeader, SubmittedHeaders},
+};
+use relay_ethereum_client::{
+	types::{HeaderHash, HeaderId as EthereumHeaderId, Receipt, SyncHeader as Header},
+	Client as EthereumClient, ConnectionParams as EthereumConnectionParams,
+};
+use relay_rialto_client::{Rialto, SigningParams as RialtoSigningParams};
+use relay_substrate_client::{
+	Chain as SubstrateChain, Client as SubstrateClient, ConnectionParams as SubstrateConnectionParams,
+};
+use relay_utils::{metrics::MetricsParams, relay_loop::Client as RelayClient};
+
+use std::fmt::Debug;
+use std::{collections::HashSet, sync::Arc, time::Duration};
+
+pub mod consts {
+	use super::*;
+
+	/// Interval at which we check new Ethereum headers when we are synced/almost synced.
+	pub const ETHEREUM_TICK_INTERVAL: Duration = Duration::from_secs(10);
+	/// Max number of headers in single submit transaction.
+	pub const MAX_HEADERS_IN_SINGLE_SUBMIT: usize = 32;
+	/// Max total size of headers in single submit transaction. This only affects signed
+	/// submissions, when several headers are submitted at once. 4096 is the maximal **expected**
+	/// size of the Ethereum header + transactions receipts (if they're required).
+	pub const MAX_HEADERS_SIZE_IN_SINGLE_SUBMIT: usize = MAX_HEADERS_IN_SINGLE_SUBMIT * 4096;
+	/// Max Ethereum headers we want to have in all 'before-submitted' states.
+	pub const MAX_FUTURE_HEADERS_TO_DOWNLOAD: usize = 128;
+	/// Max Ethereum headers count we want to have in 'submitted' state.
+	pub const MAX_SUBMITTED_HEADERS: usize = 128;
+	/// Max depth of in-memory headers in all states. Past this depth they will be forgotten (pruned).
+	pub const PRUNE_DEPTH: u32 = 4096;
+}
+
+/// Ethereum synchronization parameters.
+pub struct EthereumSyncParams {
+	/// Ethereum connection params.
+	pub eth_params: EthereumConnectionParams,
+	/// Substrate connection params.
+	pub sub_params: SubstrateConnectionParams,
+	/// Substrate signing params.
+	pub sub_sign: RialtoSigningParams,
+	/// Synchronization parameters.
+	pub sync_params: HeadersSyncParams,
+	/// Metrics parameters.
+	pub metrics_params: MetricsParams,
+	/// Instance of the bridge pallet being synchronized.
+	pub instance: Arc<dyn BridgeInstance>,
+}
+
+impl Debug for EthereumSyncParams {
+	fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+		f.debug_struct("EthereumSyncParams")
+			.field("eth_params", &self.eth_params)
+			.field("sub_params", &self.sub_params)
+			.field("sub_sign", &sp_core::Pair::public(&self.sub_sign))
+			.field("sync_params", &self.sync_params)
+			.field("metrics_params", &self.metrics_params)
+			.field("instance", &self.instance)
+			.finish()
+	}
+}
+
+/// Ethereum synchronization pipeline.
+#[derive(Clone, Copy, Debug)]
+#[cfg_attr(test, derive(PartialEq))]
+pub struct EthereumHeadersSyncPipeline;
+
+impl HeadersSyncPipeline for EthereumHeadersSyncPipeline {
+	const SOURCE_NAME: &'static str = "Ethereum";
+	const TARGET_NAME: &'static str = "Substrate";
+
+	type Hash = HeaderHash;
+	type Number = u64;
+	type Header = Header;
+	type Extra = Vec<Receipt>;
+	type Completion = ();
+
+	fn estimate_size(source: &QueuedHeader<Self>) -> usize {
+		into_substrate_ethereum_header(source.header()).encode().len()
+			+ into_substrate_ethereum_receipts(source.extra())
+				.map(|extra| extra.encode().len())
+				.unwrap_or(0)
+	}
+}
+
+/// Queued ethereum header ID.
+pub type QueuedEthereumHeader = QueuedHeader<EthereumHeadersSyncPipeline>;
+
+/// Ethereum client as headers source.
+#[derive(Clone)]
+struct EthereumHeadersSource {
+	/// Ethereum node client.
+	client: EthereumClient,
+}
+
+impl EthereumHeadersSource {
+	fn new(client: EthereumClient) -> Self {
+		Self { client }
+	}
+}
+
+#[async_trait]
+impl RelayClient for EthereumHeadersSource {
+	type Error = RpcError;
+
+	async fn reconnect(&mut self) -> Result<(), RpcError> {
+		self.client.reconnect().await.map_err(Into::into)
+	}
+}
+
+#[async_trait]
+impl SourceClient<EthereumHeadersSyncPipeline> for EthereumHeadersSource {
+	async fn best_block_number(&self) -> Result<u64, RpcError> {
+		// we **CAN** continue to relay headers if Ethereum node is out of sync, because
+		// Substrate node may be missing headers that are already available at the Ethereum
+
+		self.client.best_block_number().await.map_err(Into::into)
+	}
+
+	async fn header_by_hash(&self, hash: HeaderHash) -> Result<Header, RpcError> {
+		self.client
+			.header_by_hash(hash)
+			.await
+			.map(Into::into)
+			.map_err(Into::into)
+	}
+
+	async fn header_by_number(&self, number: u64) -> Result<Header, RpcError> {
+		self.client
+			.header_by_number(number)
+			.await
+			.map(Into::into)
+			.map_err(Into::into)
+	}
+
+	async fn header_completion(&self, id: EthereumHeaderId) -> Result<(EthereumHeaderId, Option<()>), RpcError> {
+		Ok((id, None))
+	}
+
+	async fn header_extra(
+		&self,
+		id: EthereumHeaderId,
+		header: QueuedEthereumHeader,
+	) -> Result<(EthereumHeaderId, Vec<Receipt>), RpcError> {
+		self.client
+			.transaction_receipts(id, header.header().transactions.clone())
+			.await
+	}
+}
+
+#[derive(Clone)]
+struct SubstrateHeadersTarget {
+	/// Substrate node client.
+	client: SubstrateClient<Rialto>,
+	/// Whether we want to submit signed (true), or unsigned (false) transactions.
+	sign_transactions: bool,
+	/// Substrate signing params.
+	sign_params: RialtoSigningParams,
+	/// Bridge instance used in Ethereum to Substrate sync.
+	bridge_instance: Arc<dyn BridgeInstance>,
+}
+
+impl SubstrateHeadersTarget {
+	fn new(
+		client: SubstrateClient<Rialto>,
+		sign_transactions: bool,
+		sign_params: RialtoSigningParams,
+		bridge_instance: Arc<dyn BridgeInstance>,
+	) -> Self {
+		Self {
+			client,
+			sign_transactions,
+			sign_params,
+			bridge_instance,
+		}
+	}
+}
+
+#[async_trait]
+impl RelayClient for SubstrateHeadersTarget {
+	type Error = RpcError;
+
+	async fn reconnect(&mut self) -> Result<(), RpcError> {
+		Ok(self.client.reconnect().await?)
+	}
+}
+
+#[async_trait]
+impl TargetClient<EthereumHeadersSyncPipeline> for SubstrateHeadersTarget {
+	async fn best_header_id(&self) -> Result<EthereumHeaderId, RpcError> {
+		// we can't continue to relay headers if Substrate node is out of sync, because
+		// it may have already received (some of) headers that we're going to relay
+		self.client.ensure_synced().await?;
+
+		self.client.best_ethereum_block().await
+	}
+
+	async fn is_known_header(&self, id: EthereumHeaderId) -> Result<(EthereumHeaderId, bool), RpcError> {
+		Ok((id, self.client.ethereum_header_known(id).await?))
+	}
+
+	async fn submit_headers(&self, headers: Vec<QueuedEthereumHeader>) -> SubmittedHeaders<EthereumHeaderId, RpcError> {
+		let (sign_params, bridge_instance, sign_transactions) = (
+			self.sign_params.clone(),
+			self.bridge_instance.clone(),
+			self.sign_transactions,
+		);
+		self.client
+			.submit_ethereum_headers(sign_params, bridge_instance, headers, sign_transactions)
+			.await
+	}
+
+	async fn incomplete_headers_ids(&self) -> Result<HashSet<EthereumHeaderId>, RpcError> {
+		Ok(HashSet::new())
+	}
+
+	#[allow(clippy::unit_arg)]
+	async fn complete_header(&self, id: EthereumHeaderId, _completion: ()) -> Result<EthereumHeaderId, RpcError> {
+		Ok(id)
+	}
+
+	async fn requires_extra(&self, header: QueuedEthereumHeader) -> Result<(EthereumHeaderId, bool), RpcError> {
+		// we can minimize number of receipts_check calls by checking header
+		// logs bloom here, but it may give us false positives (when authorities
+		// source is contract, we never need any logs)
+		let id = header.header().id();
+		let sub_eth_header = into_substrate_ethereum_header(header.header());
+		Ok((id, self.client.ethereum_receipts_required(sub_eth_header).await?))
+	}
+}
+
+/// Run Ethereum headers synchronization.
+pub async fn run(params: EthereumSyncParams) -> Result<(), RpcError> {
+	let EthereumSyncParams {
+		eth_params,
+		sub_params,
+		sub_sign,
+		sync_params,
+		metrics_params,
+		instance,
+	} = params;
+
+	let eth_client = EthereumClient::new(eth_params).await?;
+	let sub_client = SubstrateClient::<Rialto>::new(sub_params).await?;
+
+	let sign_sub_transactions = match sync_params.target_tx_mode {
+		TargetTransactionMode::Signed | TargetTransactionMode::Backup => true,
+		TargetTransactionMode::Unsigned => false,
+	};
+
+	let source = EthereumHeadersSource::new(eth_client);
+	let target = SubstrateHeadersTarget::new(sub_client, sign_sub_transactions, sub_sign, instance);
+
+	headers_relay::sync_loop::run(
+		source,
+		consts::ETHEREUM_TICK_INTERVAL,
+		target,
+		Rialto::AVERAGE_BLOCK_INTERVAL,
+		(),
+		sync_params,
+		metrics_params,
+		futures::future::pending(),
+	)
+	.await
+	.map_err(RpcError::SyncLoop)?;
+
+	Ok(())
+}

polkadot/bridges/relays/bin-ethereum/src/instances.rs

@@ -0,0 +1,115 @@
+// Copyright 2020-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! The PoA Bridge Pallet provides a way to include multiple instances of itself in a runtime. When
+//! synchronizing a Substrate chain which can include multiple instances of the bridge pallet we
+//! must somehow decide which of the instances to sync.
+//!
+//! Note that each instance of the bridge pallet is coupled with an instance of the currency exchange
+//! pallet. We must also have a way to create `Call`s for the correct currency exchange instance.
+//!
+//! This module helps by preparing the correct `Call`s for each of the different pallet instances.
+
+use crate::ethereum_sync_loop::QueuedEthereumHeader;
+use crate::substrate_types::{into_substrate_ethereum_header, into_substrate_ethereum_receipts};
+
+use rialto_runtime::exchange::EthereumTransactionInclusionProof as Proof;
+use rialto_runtime::Call;
+
+/// Interface for `Calls` which are needed to correctly sync the bridge.
+///
+/// Each instance of the bridge and currency exchange pallets in the bridge runtime requires similar
+/// but slightly different `Call` in order to be synchronized.
+pub trait BridgeInstance: Send + Sync + std::fmt::Debug {
+	/// Used to build a `Call` for importing signed headers to a Substrate runtime.
+	fn build_signed_header_call(&self, headers: Vec<QueuedEthereumHeader>) -> Call;
+	/// Used to build a `Call` for importing an unsigned header to a Substrate runtime.
+	fn build_unsigned_header_call(&self, header: QueuedEthereumHeader) -> Call;
+	/// Used to build a `Call` for importing peer transactions to a Substrate runtime.
+	fn build_currency_exchange_call(&self, proof: Proof) -> Call;
+}
+
+/// Corresponds to the Rialto instance used in the bridge runtime.
+#[derive(Default, Clone, Debug)]
+pub struct RialtoPoA;
+
+impl BridgeInstance for RialtoPoA {
+	fn build_signed_header_call(&self, headers: Vec<QueuedEthereumHeader>) -> Call {
+		let pallet_call = rialto_runtime::BridgeEthPoACall::import_signed_headers(
+			headers
+				.into_iter()
+				.map(|header| {
+					(
+						into_substrate_ethereum_header(&header.header()),
+						into_substrate_ethereum_receipts(header.extra()),
+					)
+				})
+				.collect(),
+		);
+
+		rialto_runtime::Call::BridgeRialtoPoA(pallet_call)
+	}
+
+	fn build_unsigned_header_call(&self, header: QueuedEthereumHeader) -> Call {
+		let pallet_call = rialto_runtime::BridgeEthPoACall::import_unsigned_header(
+			into_substrate_ethereum_header(&header.header()),
+			into_substrate_ethereum_receipts(header.extra()),
+		);
+
+		rialto_runtime::Call::BridgeRialtoPoA(pallet_call)
+	}
+
+	fn build_currency_exchange_call(&self, proof: Proof) -> Call {
+		let pallet_call = rialto_runtime::BridgeCurrencyExchangeCall::import_peer_transaction(proof);
+		rialto_runtime::Call::BridgeRialtoCurrencyExchange(pallet_call)
+	}
+}
+
+/// Corresponds to the Kovan instance used in the bridge runtime.
+#[derive(Default, Clone, Debug)]
+pub struct Kovan;
+
+impl BridgeInstance for Kovan {
+	fn build_signed_header_call(&self, headers: Vec<QueuedEthereumHeader>) -> Call {
+		let pallet_call = rialto_runtime::BridgeEthPoACall::import_signed_headers(
+			headers
+				.into_iter()
+				.map(|header| {
+					(
+						into_substrate_ethereum_header(header.header()),
+						into_substrate_ethereum_receipts(header.extra()),
+					)
+				})
+				.collect(),
+		);
+
+		rialto_runtime::Call::BridgeKovan(pallet_call)
+	}
+
+	fn build_unsigned_header_call(&self, header: QueuedEthereumHeader) -> Call {
+		let pallet_call = rialto_runtime::BridgeEthPoACall::import_unsigned_header(
+			into_substrate_ethereum_header(header.header()),
+			into_substrate_ethereum_receipts(header.extra()),
+		);
+
+		rialto_runtime::Call::BridgeKovan(pallet_call)
+	}
+
+	fn build_currency_exchange_call(&self, proof: Proof) -> Call {
+		let pallet_call = rialto_runtime::BridgeCurrencyExchangeCall::import_peer_transaction(proof);
+		rialto_runtime::Call::BridgeKovanCurrencyExchange(pallet_call)
+	}
+}

polkadot/bridges/relays/bin-ethereum/src/main.rs

@@ -0,0 +1,413 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+#![recursion_limit = "1024"]
+
+mod ethereum_client;
+mod ethereum_deploy_contract;
+mod ethereum_exchange;
+mod ethereum_exchange_submit;
+mod ethereum_sync_loop;
+mod instances;
+mod rialto_client;
+mod rpc_errors;
+mod substrate_sync_loop;
+mod substrate_types;
+
+use ethereum_deploy_contract::EthereumDeployContractParams;
+use ethereum_exchange::EthereumExchangeParams;
+use ethereum_exchange_submit::EthereumExchangeSubmitParams;
+use ethereum_sync_loop::EthereumSyncParams;
+use headers_relay::sync::TargetTransactionMode;
+use hex_literal::hex;
+use instances::{BridgeInstance, Kovan, RialtoPoA};
+use relay_utils::{
+	initialize::initialize_relay,
+	metrics::{MetricsAddress, MetricsParams},
+};
+use secp256k1::SecretKey;
+use sp_core::crypto::Pair;
+use substrate_sync_loop::SubstrateSyncParams;
+
+use headers_relay::sync::HeadersSyncParams;
+use relay_ethereum_client::{ConnectionParams as EthereumConnectionParams, SigningParams as EthereumSigningParams};
+use relay_rialto_client::SigningParams as RialtoSigningParams;
+use relay_substrate_client::ConnectionParams as SubstrateConnectionParams;
+use std::sync::Arc;
+
+fn main() {
+	initialize_relay();
+
+	let yaml = clap::load_yaml!("cli.yml");
+	let matches = clap::App::from_yaml(yaml).get_matches();
+	async_std::task::block_on(run_command(&matches));
+}
+
+async fn run_command(matches: &clap::ArgMatches<'_>) {
+	match matches.subcommand() {
+		("eth-to-sub", Some(eth_to_sub_matches)) => {
+			log::info!(target: "bridge", "Starting ETH ➡ SUB relay.");
+			if ethereum_sync_loop::run(match ethereum_sync_params(&eth_to_sub_matches) {
+				Ok(ethereum_sync_params) => ethereum_sync_params,
+				Err(err) => {
+					log::error!(target: "bridge", "Error parsing parameters: {}", err);
+					return;
+				}
+			})
+			.await
+			.is_err()
+			{
+				log::error!(target: "bridge", "Unable to get Substrate genesis block for Ethereum sync.");
+			};
+		}
+		("sub-to-eth", Some(sub_to_eth_matches)) => {
+			log::info!(target: "bridge", "Starting SUB ➡ ETH relay.");
+			if substrate_sync_loop::run(match substrate_sync_params(&sub_to_eth_matches) {
+				Ok(substrate_sync_params) => substrate_sync_params,
+				Err(err) => {
+					log::error!(target: "bridge", "Error parsing parameters: {}", err);
+					return;
+				}
+			})
+			.await
+			.is_err()
+			{
+				log::error!(target: "bridge", "Unable to get Substrate genesis block for Substrate sync.");
+			};
+		}
+		("eth-deploy-contract", Some(eth_deploy_matches)) => {
+			log::info!(target: "bridge", "Deploying ETH contracts.");
+			ethereum_deploy_contract::run(match ethereum_deploy_contract_params(&eth_deploy_matches) {
+				Ok(ethereum_deploy_params) => ethereum_deploy_params,
+				Err(err) => {
+					log::error!(target: "bridge", "Error during contract deployment: {}", err);
+					return;
+				}
+			})
+			.await;
+		}
+		("eth-submit-exchange-tx", Some(eth_exchange_submit_matches)) => {
+			log::info!(target: "bridge", "Submitting ETH ➡ SUB exchange transaction.");
+			ethereum_exchange_submit::run(match ethereum_exchange_submit_params(&eth_exchange_submit_matches) {
+				Ok(eth_exchange_submit_params) => eth_exchange_submit_params,
+				Err(err) => {
+					log::error!(target: "bridge", "Error submitting Eethereum exchange transaction: {}", err);
+					return;
+				}
+			})
+			.await;
+		}
+		("eth-exchange-sub", Some(eth_exchange_matches)) => {
+			log::info!(target: "bridge", "Starting ETH ➡ SUB exchange transactions relay.");
+			ethereum_exchange::run(match ethereum_exchange_params(&eth_exchange_matches) {
+				Ok(eth_exchange_params) => eth_exchange_params,
+				Err(err) => {
+					log::error!(target: "bridge", "Error relaying Ethereum transactions proofs: {}", err);
+					return;
+				}
+			})
+			.await;
+		}
+		("", _) => {
+			log::error!(target: "bridge", "No subcommand specified");
+		}
+		_ => unreachable!("all possible subcommands are checked above; qed"),
+	}
+}
+
+fn ethereum_connection_params(matches: &clap::ArgMatches) -> Result<EthereumConnectionParams, String> {
+	let mut params = EthereumConnectionParams::default();
+	if let Some(eth_host) = matches.value_of("eth-host") {
+		params.host = eth_host.into();
+	}
+	if let Some(eth_port) = matches.value_of("eth-port") {
+		params.port = eth_port
+			.parse()
+			.map_err(|e| format!("Failed to parse eth-port: {}", e))?;
+	}
+	Ok(params)
+}
+
+fn ethereum_signing_params(matches: &clap::ArgMatches) -> Result<EthereumSigningParams, String> {
+	let mut params = EthereumSigningParams::default();
+	if let Some(eth_signer) = matches.value_of("eth-signer") {
+		params.signer =
+			SecretKey::parse_slice(&hex::decode(eth_signer).map_err(|e| format!("Failed to parse eth-signer: {}", e))?)
+				.map_err(|e| format!("Invalid eth-signer: {}", e))?;
+	}
+	if let Some(eth_chain_id) = matches.value_of("eth-chain-id") {
+		params.chain_id = eth_chain_id
+			.parse::<u64>()
+			.map_err(|e| format!("Failed to parse eth-chain-id: {}", e))?;
+	}
+	Ok(params)
+}
+
+fn substrate_connection_params(matches: &clap::ArgMatches) -> Result<SubstrateConnectionParams, String> {
+	let mut params = SubstrateConnectionParams::default();
+	if let Some(sub_host) = matches.value_of("sub-host") {
+		params.host = sub_host.into();
+	}
+	if let Some(sub_port) = matches.value_of("sub-port") {
+		params.port = sub_port
+			.parse()
+			.map_err(|e| format!("Failed to parse sub-port: {}", e))?;
+	}
+	Ok(params)
+}
+
+fn rialto_signing_params(matches: &clap::ArgMatches) -> Result<RialtoSigningParams, String> {
+	let mut params = sp_keyring::AccountKeyring::Alice.pair();
+
+	if let Some(sub_signer) = matches.value_of("sub-signer") {
+		let sub_signer_password = matches.value_of("sub-signer-password");
+		params = sp_core::sr25519::Pair::from_string(sub_signer, sub_signer_password)
+			.map_err(|e| format!("Failed to parse sub-signer: {:?}", e))?;
+	}
+	Ok(params)
+}
+
+fn ethereum_sync_params(matches: &clap::ArgMatches) -> Result<EthereumSyncParams, String> {
+	use crate::ethereum_sync_loop::consts::*;
+
+	let mut sync_params = HeadersSyncParams {
+		max_future_headers_to_download: MAX_FUTURE_HEADERS_TO_DOWNLOAD,
+		max_headers_in_submitted_status: MAX_SUBMITTED_HEADERS,
+		max_headers_in_single_submit: MAX_HEADERS_IN_SINGLE_SUBMIT,
+		max_headers_size_in_single_submit: MAX_HEADERS_SIZE_IN_SINGLE_SUBMIT,
+		prune_depth: PRUNE_DEPTH,
+		target_tx_mode: TargetTransactionMode::Signed,
+	};
+
+	match matches.value_of("sub-tx-mode") {
+		Some("signed") => sync_params.target_tx_mode = TargetTransactionMode::Signed,
+		Some("unsigned") => {
+			sync_params.target_tx_mode = TargetTransactionMode::Unsigned;
+
+			// tx pool won't accept too much unsigned transactions
+			sync_params.max_headers_in_submitted_status = 10;
+		}
+		Some("backup") => sync_params.target_tx_mode = TargetTransactionMode::Backup,
+		Some(mode) => return Err(format!("Invalid sub-tx-mode: {}", mode)),
+		None => sync_params.target_tx_mode = TargetTransactionMode::Signed,
+	}
+
+	let params = EthereumSyncParams {
+		eth_params: ethereum_connection_params(matches)?,
+		sub_params: substrate_connection_params(matches)?,
+		sub_sign: rialto_signing_params(matches)?,
+		metrics_params: metrics_params(matches)?,
+		instance: instance_params(matches)?,
+		sync_params,
+	};
+
+	log::debug!(target: "bridge", "Ethereum sync params: {:?}", params);
+
+	Ok(params)
+}
+
+fn substrate_sync_params(matches: &clap::ArgMatches) -> Result<SubstrateSyncParams, String> {
+	use crate::substrate_sync_loop::consts::*;
+
+	let eth_contract_address: relay_ethereum_client::types::Address =
+		if let Some(eth_contract) = matches.value_of("eth-contract") {
+			eth_contract.parse().map_err(|e| format!("{}", e))?
+		} else {
+			"731a10897d267e19b34503ad902d0a29173ba4b1"
+				.parse()
+				.expect("address is hardcoded, thus valid; qed")
+		};
+
+	let params = SubstrateSyncParams {
+		sub_params: substrate_connection_params(matches)?,
+		eth_params: ethereum_connection_params(matches)?,
+		eth_sign: ethereum_signing_params(matches)?,
+		metrics_params: metrics_params(matches)?,
+		sync_params: HeadersSyncParams {
+			max_future_headers_to_download: MAX_FUTURE_HEADERS_TO_DOWNLOAD,
+			max_headers_in_submitted_status: MAX_SUBMITTED_HEADERS,
+			max_headers_in_single_submit: MAX_SUBMITTED_HEADERS,
+			max_headers_size_in_single_submit: std::usize::MAX,
+			prune_depth: PRUNE_DEPTH,
+			target_tx_mode: TargetTransactionMode::Signed,
+		},
+		eth_contract_address,
+	};
+
+	log::debug!(target: "bridge", "Substrate sync params: {:?}", params);
+
+	Ok(params)
+}
+
+fn ethereum_deploy_contract_params(matches: &clap::ArgMatches) -> Result<EthereumDeployContractParams, String> {
+	let eth_contract_code = parse_hex_argument(matches, "eth-contract-code")?.unwrap_or_else(|| {
+		hex::decode(include_str!("../res/substrate-bridge-bytecode.hex")).expect("code is hardcoded, thus valid; qed")
+	});
+	let sub_initial_authorities_set_id = matches
+		.value_of("sub-authorities-set-id")
+		.map(|set| {
+			set.parse()
+				.map_err(|e| format!("Failed to parse sub-authorities-set-id: {}", e))
+		})
+		.transpose()?;
+	let sub_initial_authorities_set = parse_hex_argument(matches, "sub-authorities-set")?;
+	let sub_initial_header = parse_hex_argument(matches, "sub-initial-header")?;
+
+	let params = EthereumDeployContractParams {
+		eth_params: ethereum_connection_params(matches)?,
+		eth_sign: ethereum_signing_params(matches)?,
+		sub_params: substrate_connection_params(matches)?,
+		sub_initial_authorities_set_id,
+		sub_initial_authorities_set,
+		sub_initial_header,
+		eth_contract_code,
+	};
+
+	log::debug!(target: "bridge", "Deploy params: {:?}", params);
+
+	Ok(params)
+}
+
+fn ethereum_exchange_submit_params(matches: &clap::ArgMatches) -> Result<EthereumExchangeSubmitParams, String> {
+	let eth_nonce = matches
+		.value_of("eth-nonce")
+		.map(|eth_nonce| {
+			relay_ethereum_client::types::U256::from_dec_str(&eth_nonce)
+				.map_err(|e| format!("Failed to parse eth-nonce: {}", e))
+		})
+		.transpose()?;
+
+	let eth_amount = matches
+		.value_of("eth-amount")
+		.map(|eth_amount| {
+			eth_amount
+				.parse()
+				.map_err(|e| format!("Failed to parse eth-amount: {}", e))
+		})
+		.transpose()?
+		.unwrap_or_else(|| {
+			// This is in Wei, represents 1 ETH
+			1_000_000_000_000_000_000_u64.into()
+		});
+
+	// This is the well-known Substrate account of Ferdie
+	let default_recepient = hex!("1cbd2d43530a44705ad088af313e18f80b53ef16b36177cd4b77b846f2a5f07c");
+
+	let sub_recipient = if let Some(sub_recipient) = matches.value_of("sub-recipient") {
+		hex::decode(&sub_recipient)
+			.map_err(|err| err.to_string())
+			.and_then(|vsub_recipient| {
+				let expected_len = default_recepient.len();
+				if expected_len != vsub_recipient.len() {
+					Err(format!("invalid length. Expected {} bytes", expected_len))
+				} else {
+					let mut sub_recipient = default_recepient;
+					sub_recipient.copy_from_slice(&vsub_recipient[..expected_len]);
+					Ok(sub_recipient)
+				}
+			})
+			.map_err(|e| format!("Failed to parse sub-recipient: {}", e))?
+	} else {
+		default_recepient
+	};
+
+	let params = EthereumExchangeSubmitParams {
+		eth_params: ethereum_connection_params(matches)?,
+		eth_sign: ethereum_signing_params(matches)?,
+		eth_nonce,
+		eth_amount,
+		sub_recipient,
+	};
+
+	log::debug!(target: "bridge", "Submit Ethereum exchange tx params: {:?}", params);
+
+	Ok(params)
+}
+
+fn ethereum_exchange_params(matches: &clap::ArgMatches) -> Result<EthereumExchangeParams, String> {
+	let mode = match matches.value_of("eth-tx-hash") {
+		Some(eth_tx_hash) => ethereum_exchange::ExchangeRelayMode::Single(
+			eth_tx_hash
+				.parse()
+				.map_err(|e| format!("Failed to parse eth-tx-hash: {}", e))?,
+		),
+		None => ethereum_exchange::ExchangeRelayMode::Auto(
+			matches
+				.value_of("eth-start-with-block")
+				.map(|eth_start_with_block| {
+					eth_start_with_block
+						.parse()
+						.map_err(|e| format!("Failed to parse eth-start-with-block: {}", e))
+				})
+				.transpose()?,
+		),
+	};
+
+	let params = EthereumExchangeParams {
+		eth_params: ethereum_connection_params(matches)?,
+		sub_params: substrate_connection_params(matches)?,
+		sub_sign: rialto_signing_params(matches)?,
+		metrics_params: metrics_params(matches)?,
+		instance: instance_params(matches)?,
+		mode,
+	};
+
+	log::debug!(target: "bridge", "Ethereum exchange params: {:?}", params);
+
+	Ok(params)
+}
+
+fn metrics_params(matches: &clap::ArgMatches) -> Result<MetricsParams, String> {
+	if matches.is_present("no-prometheus") {
+		return Ok(None.into());
+	}
+
+	let mut metrics_params = MetricsAddress::default();
+
+	if let Some(prometheus_host) = matches.value_of("prometheus-host") {
+		metrics_params.host = prometheus_host.into();
+	}
+	if let Some(prometheus_port) = matches.value_of("prometheus-port") {
+		metrics_params.port = prometheus_port
+			.parse()
+			.map_err(|e| format!("Failed to parse prometheus-port: {}", e))?;
+	}
+
+	Ok(Some(metrics_params).into())
+}
+
+fn instance_params(matches: &clap::ArgMatches) -> Result<Arc<dyn BridgeInstance>, String> {
+	let instance = if let Some(instance) = matches.value_of("sub-pallet-instance") {
+		match instance.to_lowercase().as_str() {
+			"rialto" => Arc::new(RialtoPoA) as Arc<dyn BridgeInstance>,
+			"kovan" => Arc::new(Kovan),
+			_ => return Err("Unsupported bridge pallet instance".to_string()),
+		}
+	} else {
+		unreachable!("CLI config enforces a default instance, can never be None")
+	};
+
+	Ok(instance)
+}
+
+fn parse_hex_argument(matches: &clap::ArgMatches, arg: &str) -> Result<Option<Vec<u8>>, String> {
+	match matches.value_of(arg) {
+		Some(value) => Ok(Some(
+			hex::decode(value).map_err(|e| format!("Failed to parse {}: {}", arg, e))?,
+		)),
+		None => Ok(None),
+	}
+}

polkadot/bridges/relays/bin-ethereum/src/rialto_client.rs

@@ -0,0 +1,279 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::ethereum_sync_loop::QueuedEthereumHeader;
+use crate::instances::BridgeInstance;
+use crate::rpc_errors::RpcError;
+
+use async_trait::async_trait;
+use bp_eth_poa::AuraHeader as SubstrateEthereumHeader;
+use codec::{Decode, Encode};
+use headers_relay::sync_types::SubmittedHeaders;
+use relay_ethereum_client::types::HeaderId as EthereumHeaderId;
+use relay_rialto_client::{Rialto, SigningParams as RialtoSigningParams};
+use relay_substrate_client::{Client as SubstrateClient, TransactionSignScheme};
+use relay_utils::HeaderId;
+use sp_core::{crypto::Pair, Bytes};
+use std::{collections::VecDeque, sync::Arc};
+
+const ETH_API_IMPORT_REQUIRES_RECEIPTS: &str = "RialtoPoAHeaderApi_is_import_requires_receipts";
+const ETH_API_IS_KNOWN_BLOCK: &str = "RialtoPoAHeaderApi_is_known_block";
+const ETH_API_BEST_BLOCK: &str = "RialtoPoAHeaderApi_best_block";
+const ETH_API_BEST_FINALIZED_BLOCK: &str = "RialtoPoAHeaderApi_finalized_block";
+const EXCH_API_FILTER_TRANSACTION_PROOF: &str = "RialtoCurrencyExchangeApi_filter_transaction_proof";
+
+type RpcResult<T> = std::result::Result<T, RpcError>;
+
+/// A trait which contains methods that work by using multiple low-level RPCs, or more complicated
+/// interactions involving, for example, an Ethereum bridge module.
+#[async_trait]
+pub trait SubstrateHighLevelRpc {
+	/// Returns best Ethereum block that Substrate runtime knows of.
+	async fn best_ethereum_block(&self) -> RpcResult<EthereumHeaderId>;
+	/// Returns best finalized Ethereum block that Substrate runtime knows of.
+	async fn best_ethereum_finalized_block(&self) -> RpcResult<EthereumHeaderId>;
+	/// Returns whether or not transactions receipts are required for Ethereum header submission.
+	async fn ethereum_receipts_required(&self, header: SubstrateEthereumHeader) -> RpcResult<bool>;
+	/// Returns whether or not the given Ethereum header is known to the Substrate runtime.
+	async fn ethereum_header_known(&self, header_id: EthereumHeaderId) -> RpcResult<bool>;
+}
+
+#[async_trait]
+impl SubstrateHighLevelRpc for SubstrateClient<Rialto> {
+	async fn best_ethereum_block(&self) -> RpcResult<EthereumHeaderId> {
+		let call = ETH_API_BEST_BLOCK.to_string();
+		let data = Bytes(Vec::new());
+
+		let encoded_response = self.state_call(call, data, None).await?;
+		let decoded_response: (u64, bp_eth_poa::H256) = Decode::decode(&mut &encoded_response.0[..])?;
+
+		let best_header_id = HeaderId(decoded_response.0, decoded_response.1);
+		Ok(best_header_id)
+	}
+
+	async fn best_ethereum_finalized_block(&self) -> RpcResult<EthereumHeaderId> {
+		let call = ETH_API_BEST_FINALIZED_BLOCK.to_string();
+		let data = Bytes(Vec::new());
+
+		let encoded_response = self.state_call(call, data, None).await?;
+		let decoded_response: (u64, bp_eth_poa::H256) = Decode::decode(&mut &encoded_response.0[..])?;
+
+		let best_header_id = HeaderId(decoded_response.0, decoded_response.1);
+		Ok(best_header_id)
+	}
+
+	async fn ethereum_receipts_required(&self, header: SubstrateEthereumHeader) -> RpcResult<bool> {
+		let call = ETH_API_IMPORT_REQUIRES_RECEIPTS.to_string();
+		let data = Bytes(header.encode());
+
+		let encoded_response = self.state_call(call, data, None).await?;
+		let receipts_required: bool = Decode::decode(&mut &encoded_response.0[..])?;
+
+		Ok(receipts_required)
+	}
+
+	// The Substrate module could prune old headers. So this function could return false even
+	// if header is synced. And we'll mark corresponding Ethereum header as Orphan.
+	//
+	// But when we read the best header from Substrate next time, we will know that
+	// there's a better header. This Orphan will either be marked as synced, or
+	// eventually pruned.
+	async fn ethereum_header_known(&self, header_id: EthereumHeaderId) -> RpcResult<bool> {
+		let call = ETH_API_IS_KNOWN_BLOCK.to_string();
+		let data = Bytes(header_id.1.encode());
+
+		let encoded_response = self.state_call(call, data, None).await?;
+		let is_known_block: bool = Decode::decode(&mut &encoded_response.0[..])?;
+
+		Ok(is_known_block)
+	}
+}
+
+/// A trait for RPC calls which are used to submit Ethereum headers to a Substrate
+/// runtime. These are typically calls which use a combination of other low-level RPC
+/// calls.
+#[async_trait]
+pub trait SubmitEthereumHeaders {
+	/// Submits Ethereum header to Substrate runtime.
+	async fn submit_ethereum_headers(
+		&self,
+		params: RialtoSigningParams,
+		instance: Arc<dyn BridgeInstance>,
+		headers: Vec<QueuedEthereumHeader>,
+		sign_transactions: bool,
+	) -> SubmittedHeaders<EthereumHeaderId, RpcError>;
+
+	/// Submits signed Ethereum header to Substrate runtime.
+	async fn submit_signed_ethereum_headers(
+		&self,
+		params: RialtoSigningParams,
+		instance: Arc<dyn BridgeInstance>,
+		headers: Vec<QueuedEthereumHeader>,
+	) -> SubmittedHeaders<EthereumHeaderId, RpcError>;
+
+	/// Submits unsigned Ethereum header to Substrate runtime.
+	async fn submit_unsigned_ethereum_headers(
+		&self,
+		instance: Arc<dyn BridgeInstance>,
+		headers: Vec<QueuedEthereumHeader>,
+	) -> SubmittedHeaders<EthereumHeaderId, RpcError>;
+}
+
+#[async_trait]
+impl SubmitEthereumHeaders for SubstrateClient<Rialto> {
+	async fn submit_ethereum_headers(
+		&self,
+		params: RialtoSigningParams,
+		instance: Arc<dyn BridgeInstance>,
+		headers: Vec<QueuedEthereumHeader>,
+		sign_transactions: bool,
+	) -> SubmittedHeaders<EthereumHeaderId, RpcError> {
+		if sign_transactions {
+			self.submit_signed_ethereum_headers(params, instance, headers).await
+		} else {
+			self.submit_unsigned_ethereum_headers(instance, headers).await
+		}
+	}
+
+	async fn submit_signed_ethereum_headers(
+		&self,
+		params: RialtoSigningParams,
+		instance: Arc<dyn BridgeInstance>,
+		headers: Vec<QueuedEthereumHeader>,
+	) -> SubmittedHeaders<EthereumHeaderId, RpcError> {
+		let ids = headers.iter().map(|header| header.id()).collect();
+		let submission_result = async {
+			self.submit_signed_extrinsic((*params.public().as_array_ref()).into(), |transaction_nonce| {
+				Bytes(
+					Rialto::sign_transaction(
+						*self.genesis_hash(),
+						&params,
+						transaction_nonce,
+						instance.build_signed_header_call(headers),
+					)
+					.encode(),
+				)
+			})
+			.await?;
+			Ok(())
+		}
+		.await;
+
+		match submission_result {
+			Ok(_) => SubmittedHeaders {
+				submitted: ids,
+				incomplete: Vec::new(),
+				rejected: Vec::new(),
+				fatal_error: None,
+			},
+			Err(error) => SubmittedHeaders {
+				submitted: Vec::new(),
+				incomplete: Vec::new(),
+				rejected: ids,
+				fatal_error: Some(error),
+			},
+		}
+	}
+
+	async fn submit_unsigned_ethereum_headers(
+		&self,
+		instance: Arc<dyn BridgeInstance>,
+		headers: Vec<QueuedEthereumHeader>,
+	) -> SubmittedHeaders<EthereumHeaderId, RpcError> {
+		let mut ids = headers.iter().map(|header| header.id()).collect::<VecDeque<_>>();
+		let mut submitted_headers = SubmittedHeaders::default();
+
+		for header in headers {
+			let id = ids.pop_front().expect("both collections have same size; qed");
+
+			let call = instance.build_unsigned_header_call(header);
+			let transaction = create_unsigned_submit_transaction(call);
+
+			match self.submit_unsigned_extrinsic(Bytes(transaction.encode())).await {
+				Ok(_) => submitted_headers.submitted.push(id),
+				Err(error) => {
+					submitted_headers.rejected.push(id);
+					submitted_headers.rejected.extend(ids);
+					submitted_headers.fatal_error = Some(error.into());
+					break;
+				}
+			}
+		}
+
+		submitted_headers
+	}
+}
+
+/// A trait for RPC calls which are used to submit proof of Ethereum exchange transaction to a
+/// Substrate runtime. These are typically calls which use a combination of other low-level RPC
+/// calls.
+#[async_trait]
+pub trait SubmitEthereumExchangeTransactionProof {
+	/// Pre-verify Ethereum exchange transaction proof.
+	async fn verify_exchange_transaction_proof(
+		&self,
+		proof: rialto_runtime::exchange::EthereumTransactionInclusionProof,
+	) -> RpcResult<bool>;
+	/// Submits Ethereum exchange transaction proof to Substrate runtime.
+	async fn submit_exchange_transaction_proof(
+		&self,
+		params: RialtoSigningParams,
+		instance: Arc<dyn BridgeInstance>,
+		proof: rialto_runtime::exchange::EthereumTransactionInclusionProof,
+	) -> RpcResult<()>;
+}
+
+#[async_trait]
+impl SubmitEthereumExchangeTransactionProof for SubstrateClient<Rialto> {
+	async fn verify_exchange_transaction_proof(
+		&self,
+		proof: rialto_runtime::exchange::EthereumTransactionInclusionProof,
+	) -> RpcResult<bool> {
+		let call = EXCH_API_FILTER_TRANSACTION_PROOF.to_string();
+		let data = Bytes(proof.encode());
+
+		let encoded_response = self.state_call(call, data, None).await?;
+		let is_allowed: bool = Decode::decode(&mut &encoded_response.0[..])?;
+
+		Ok(is_allowed)
+	}
+
+	async fn submit_exchange_transaction_proof(
+		&self,
+		params: RialtoSigningParams,
+		instance: Arc<dyn BridgeInstance>,
+		proof: rialto_runtime::exchange::EthereumTransactionInclusionProof,
+	) -> RpcResult<()> {
+		self.submit_signed_extrinsic((*params.public().as_array_ref()).into(), |transaction_nonce| {
+			Bytes(
+				Rialto::sign_transaction(
+					*self.genesis_hash(),
+					&params,
+					transaction_nonce,
+					instance.build_currency_exchange_call(proof),
+				)
+				.encode(),
+			)
+		})
+		.await?;
+		Ok(())
+	}
+}
+
+/// Create unsigned Substrate transaction for submitting Ethereum header.
+fn create_unsigned_submit_transaction(call: rialto_runtime::Call) -> rialto_runtime::UncheckedExtrinsic {
+	rialto_runtime::UncheckedExtrinsic::new_unsigned(call)
+}

polkadot/bridges/relays/bin-ethereum/src/rpc_errors.rs

@@ -0,0 +1,85 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use relay_ethereum_client::Error as EthereumNodeError;
+use relay_substrate_client::Error as SubstrateNodeError;
+use relay_utils::MaybeConnectionError;
+
+/// Contains common errors that can occur when
+/// interacting with a Substrate or Ethereum node
+/// through RPC.
+#[derive(Debug)]
+pub enum RpcError {
+	/// The arguments to the RPC method failed to serialize.
+	Serialization(serde_json::Error),
+	/// An error occured when interacting with an Ethereum node.
+	Ethereum(EthereumNodeError),
+	/// An error occured when interacting with a Substrate node.
+	Substrate(SubstrateNodeError),
+	/// Error running relay loop.
+	SyncLoop(String),
+}
+
+impl From<RpcError> for String {
+	fn from(err: RpcError) -> Self {
+		match err {
+			RpcError::Serialization(e) => e.to_string(),
+			RpcError::Ethereum(e) => e.to_string(),
+			RpcError::Substrate(e) => e.to_string(),
+			RpcError::SyncLoop(e) => e,
+		}
+	}
+}
+
+impl From<serde_json::Error> for RpcError {
+	fn from(err: serde_json::Error) -> Self {
+		Self::Serialization(err)
+	}
+}
+
+impl From<EthereumNodeError> for RpcError {
+	fn from(err: EthereumNodeError) -> Self {
+		Self::Ethereum(err)
+	}
+}
+
+impl From<SubstrateNodeError> for RpcError {
+	fn from(err: SubstrateNodeError) -> Self {
+		Self::Substrate(err)
+	}
+}
+
+impl From<ethabi::Error> for RpcError {
+	fn from(err: ethabi::Error) -> Self {
+		Self::Ethereum(EthereumNodeError::ResponseParseFailed(format!("{}", err)))
+	}
+}
+
+impl MaybeConnectionError for RpcError {
+	fn is_connection_error(&self) -> bool {
+		match self {
+			RpcError::Ethereum(ref error) => error.is_connection_error(),
+			RpcError::Substrate(ref error) => error.is_connection_error(),
+			_ => false,
+		}
+	}
+}
+
+impl From<codec::Error> for RpcError {
+	fn from(err: codec::Error) -> Self {
+		Self::Substrate(SubstrateNodeError::ResponseParseFailed(err))
+	}
+}

polkadot/bridges/relays/bin-ethereum/src/substrate_sync_loop.rs

@@ -0,0 +1,200 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Rialto-Substrate -> Ethereum PoA synchronization.
+
+use crate::ethereum_client::EthereumHighLevelRpc;
+use crate::rpc_errors::RpcError;
+
+use async_trait::async_trait;
+use codec::Encode;
+use headers_relay::{
+	sync::HeadersSyncParams,
+	sync_loop::TargetClient,
+	sync_types::{HeadersSyncPipeline, QueuedHeader, SourceHeader, SubmittedHeaders},
+};
+use relay_ethereum_client::{
+	types::Address, Client as EthereumClient, ConnectionParams as EthereumConnectionParams,
+	SigningParams as EthereumSigningParams,
+};
+use relay_rialto_client::{HeaderId as RialtoHeaderId, Rialto, SyncHeader as RialtoSyncHeader};
+use relay_substrate_client::{
+	headers_source::HeadersSource, Chain as SubstrateChain, Client as SubstrateClient,
+	ConnectionParams as SubstrateConnectionParams,
+};
+use relay_utils::{metrics::MetricsParams, relay_loop::Client as RelayClient};
+use sp_runtime::EncodedJustification;
+
+use std::fmt::Debug;
+use std::{collections::HashSet, time::Duration};
+
+pub mod consts {
+	use super::*;
+
+	/// Interval at which we check new Ethereum blocks.
+	pub const ETHEREUM_TICK_INTERVAL: Duration = Duration::from_secs(5);
+	/// Max Ethereum headers we want to have in all 'before-submitted' states.
+	pub const MAX_FUTURE_HEADERS_TO_DOWNLOAD: usize = 8;
+	/// Max Ethereum headers count we want to have in 'submitted' state.
+	pub const MAX_SUBMITTED_HEADERS: usize = 4;
+	/// Max depth of in-memory headers in all states. Past this depth they will be forgotten (pruned).
+	pub const PRUNE_DEPTH: u32 = 256;
+}
+
+/// Substrate synchronization parameters.
+#[derive(Debug)]
+pub struct SubstrateSyncParams {
+	/// Substrate connection params.
+	pub sub_params: SubstrateConnectionParams,
+	/// Ethereum connection params.
+	pub eth_params: EthereumConnectionParams,
+	/// Ethereum signing params.
+	pub eth_sign: EthereumSigningParams,
+	/// Ethereum bridge contract address.
+	pub eth_contract_address: Address,
+	/// Synchronization parameters.
+	pub sync_params: HeadersSyncParams,
+	/// Metrics parameters.
+	pub metrics_params: MetricsParams,
+}
+
+/// Substrate synchronization pipeline.
+#[derive(Clone, Copy, Debug)]
+#[cfg_attr(test, derive(PartialEq))]
+pub struct SubstrateHeadersSyncPipeline;
+
+impl HeadersSyncPipeline for SubstrateHeadersSyncPipeline {
+	const SOURCE_NAME: &'static str = "Substrate";
+	const TARGET_NAME: &'static str = "Ethereum";
+
+	type Hash = rialto_runtime::Hash;
+	type Number = rialto_runtime::BlockNumber;
+	type Header = RialtoSyncHeader;
+	type Extra = ();
+	type Completion = EncodedJustification;
+
+	fn estimate_size(source: &QueuedHeader<Self>) -> usize {
+		source.header().encode().len()
+	}
+}
+
+/// Queued substrate header ID.
+pub type QueuedRialtoHeader = QueuedHeader<SubstrateHeadersSyncPipeline>;
+
+/// Rialto node as headers source.
+type SubstrateHeadersSource = HeadersSource<Rialto, SubstrateHeadersSyncPipeline>;
+
+/// Ethereum client as Substrate headers target.
+#[derive(Clone)]
+struct EthereumHeadersTarget {
+	/// Ethereum node client.
+	client: EthereumClient,
+	/// Bridge contract address.
+	contract: Address,
+	/// Ethereum signing params.
+	sign_params: EthereumSigningParams,
+}
+
+impl EthereumHeadersTarget {
+	fn new(client: EthereumClient, contract: Address, sign_params: EthereumSigningParams) -> Self {
+		Self {
+			client,
+			contract,
+			sign_params,
+		}
+	}
+}
+
+#[async_trait]
+impl RelayClient for EthereumHeadersTarget {
+	type Error = RpcError;
+
+	async fn reconnect(&mut self) -> Result<(), RpcError> {
+		self.client.reconnect().await.map_err(Into::into)
+	}
+}
+
+#[async_trait]
+impl TargetClient<SubstrateHeadersSyncPipeline> for EthereumHeadersTarget {
+	async fn best_header_id(&self) -> Result<RialtoHeaderId, RpcError> {
+		// we can't continue to relay headers if Ethereum node is out of sync, because
+		// it may have already received (some of) headers that we're going to relay
+		self.client.ensure_synced().await?;
+
+		self.client.best_substrate_block(self.contract).await
+	}
+
+	async fn is_known_header(&self, id: RialtoHeaderId) -> Result<(RialtoHeaderId, bool), RpcError> {
+		self.client.substrate_header_known(self.contract, id).await
+	}
+
+	async fn submit_headers(&self, headers: Vec<QueuedRialtoHeader>) -> SubmittedHeaders<RialtoHeaderId, RpcError> {
+		self.client
+			.submit_substrate_headers(self.sign_params.clone(), self.contract, headers)
+			.await
+	}
+
+	async fn incomplete_headers_ids(&self) -> Result<HashSet<RialtoHeaderId>, RpcError> {
+		self.client.incomplete_substrate_headers(self.contract).await
+	}
+
+	async fn complete_header(
+		&self,
+		id: RialtoHeaderId,
+		completion: EncodedJustification,
+	) -> Result<RialtoHeaderId, RpcError> {
+		self.client
+			.complete_substrate_header(self.sign_params.clone(), self.contract, id, completion)
+			.await
+	}
+
+	async fn requires_extra(&self, header: QueuedRialtoHeader) -> Result<(RialtoHeaderId, bool), RpcError> {
+		Ok((header.header().id(), false))
+	}
+}
+
+/// Run Substrate headers synchronization.
+pub async fn run(params: SubstrateSyncParams) -> Result<(), RpcError> {
+	let SubstrateSyncParams {
+		sub_params,
+		eth_params,
+		eth_sign,
+		eth_contract_address,
+		sync_params,
+		metrics_params,
+	} = params;
+
+	let eth_client = EthereumClient::new(eth_params).await?;
+	let sub_client = SubstrateClient::<Rialto>::new(sub_params).await?;
+
+	let target = EthereumHeadersTarget::new(eth_client, eth_contract_address, eth_sign);
+	let source = SubstrateHeadersSource::new(sub_client);
+
+	headers_relay::sync_loop::run(
+		source,
+		Rialto::AVERAGE_BLOCK_INTERVAL,
+		target,
+		consts::ETHEREUM_TICK_INTERVAL,
+		(),
+		sync_params,
+		metrics_params,
+		futures::future::pending(),
+	)
+	.await
+	.map_err(RpcError::SyncLoop)?;
+
+	Ok(())
+}

polkadot/bridges/relays/bin-ethereum/src/substrate_types.rs

@@ -0,0 +1,76 @@
+// Copyright 2020-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Converting between Ethereum headers and bridge module types.
+
+use bp_eth_poa::{
+	AuraHeader as SubstrateEthereumHeader, LogEntry as SubstrateEthereumLogEntry, Receipt as SubstrateEthereumReceipt,
+	TransactionOutcome as SubstrateEthereumTransactionOutcome,
+};
+use relay_ethereum_client::types::{
+	Header as EthereumHeader, Receipt as EthereumReceipt, HEADER_ID_PROOF as ETHEREUM_HEADER_ID_PROOF,
+};
+
+/// Convert Ethereum header into Ethereum header for Substrate.
+pub fn into_substrate_ethereum_header(header: &EthereumHeader) -> SubstrateEthereumHeader {
+	SubstrateEthereumHeader {
+		parent_hash: header.parent_hash,
+		timestamp: header.timestamp.as_u64(),
+		number: header.number.expect(ETHEREUM_HEADER_ID_PROOF).as_u64(),
+		author: header.author,
+		transactions_root: header.transactions_root,
+		uncles_hash: header.uncles_hash,
+		extra_data: header.extra_data.0.clone(),
+		state_root: header.state_root,
+		receipts_root: header.receipts_root,
+		log_bloom: header.logs_bloom.unwrap_or_default().data().into(),
+		gas_used: header.gas_used,
+		gas_limit: header.gas_limit,
+		difficulty: header.difficulty,
+		seal: header.seal_fields.iter().map(|s| s.0.clone()).collect(),
+	}
+}
+
+/// Convert Ethereum transactions receipts into Ethereum transactions receipts for Substrate.
+pub fn into_substrate_ethereum_receipts(
+	receipts: &Option<Vec<EthereumReceipt>>,
+) -> Option<Vec<SubstrateEthereumReceipt>> {
+	receipts
+		.as_ref()
+		.map(|receipts| receipts.iter().map(into_substrate_ethereum_receipt).collect())
+}
+
+/// Convert Ethereum transactions receipt into Ethereum transactions receipt for Substrate.
+pub fn into_substrate_ethereum_receipt(receipt: &EthereumReceipt) -> SubstrateEthereumReceipt {
+	SubstrateEthereumReceipt {
+		gas_used: receipt.cumulative_gas_used,
+		log_bloom: receipt.logs_bloom.data().into(),
+		logs: receipt
+			.logs
+			.iter()
+			.map(|log_entry| SubstrateEthereumLogEntry {
+				address: log_entry.address,
+				topics: log_entry.topics.clone(),
+				data: log_entry.data.0.clone(),
+			})
+			.collect(),
+		outcome: match (receipt.status, receipt.root) {
+			(Some(status), None) => SubstrateEthereumTransactionOutcome::StatusCode(status.as_u64() as u8),
+			(None, Some(root)) => SubstrateEthereumTransactionOutcome::StateRoot(root),
+			_ => SubstrateEthereumTransactionOutcome::Unknown,
+		},
+	}
+}

polkadot/bridges/relays/bin-substrate/Cargo.toml

@@ -0,0 +1,61 @@
+[package]
+name = "substrate-relay"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+anyhow = "1.0"
+async-std = "1.9.0"
+async-trait = "0.1.42"
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+futures = "0.3.12"
+hex = "0.4"
+log = "0.4.14"
+num-format = "0.4"
+num-traits = "0.2"
+paste = "1.0"
+structopt = "0.3"
+
+# Bridge dependencies
+
+bp-header-chain = { path = "../../primitives/header-chain" }
+bp-kusama = { path = "../../primitives/chain-kusama" }
+bp-messages = { path = "../../primitives/messages" }
+bp-millau = { path = "../../primitives/chain-millau" }
+bp-polkadot = { path = "../../primitives/chain-polkadot" }
+bp-rialto = { path = "../../primitives/chain-rialto" }
+bp-rococo = { path = "../../primitives/chain-rococo" }
+bp-runtime = { path = "../../primitives/runtime" }
+bp-westend = { path = "../../primitives/chain-westend" }
+bridge-runtime-common = { path = "../../bin/runtime-common" }
+finality-grandpa = { version = "0.14.0" }
+finality-relay = { path = "../finality" }
+headers-relay = { path = "../headers" }
+messages-relay = { path = "../messages" }
+millau-runtime = { path = "../../bin/millau/runtime" }
+pallet-bridge-dispatch = { path = "../../modules/dispatch" }
+pallet-bridge-messages = { path = "../../modules/messages" }
+relay-kusama-client = { path = "../client-kusama" }
+relay-millau-client = { path = "../client-millau" }
+relay-polkadot-client = { path = "../client-polkadot" }
+relay-rialto-client = { path = "../client-rialto" }
+relay-rococo-client = { path = "../client-rococo" }
+relay-substrate-client = { path = "../client-substrate" }
+relay-utils = { path = "../utils" }
+relay-westend-client = { path = "../client-westend" }
+rialto-runtime = { path = "../../bin/rialto/runtime" }
+
+# Substrate Dependencies
+
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-finality-grandpa = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-trie = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-version = { git = "https://github.com/paritytech/substrate", branch = "master" }
+
+[dev-dependencies]
+sp-keyring = { git = "https://github.com/paritytech/substrate", branch = "master" }
+hex-literal = "0.3"

polkadot/bridges/relays/bin-substrate/src/chains/millau.rs

@@ -0,0 +1,101 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Millau chain specification for CLI.
+
+use crate::cli::{
+	bridge,
+	encode_call::{self, Call, CliEncodeCall},
+	encode_message, send_message, CliChain,
+};
+use codec::Decode;
+use frame_support::weights::{GetDispatchInfo, Weight};
+use pallet_bridge_dispatch::{CallOrigin, MessagePayload};
+use relay_millau_client::Millau;
+use sp_version::RuntimeVersion;
+
+impl CliEncodeCall for Millau {
+	fn max_extrinsic_size() -> u32 {
+		bp_millau::max_extrinsic_size()
+	}
+
+	fn encode_call(call: &Call) -> anyhow::Result<Self::Call> {
+		Ok(match call {
+			Call::Raw { data } => Decode::decode(&mut &*data.0)?,
+			Call::Remark { remark_payload, .. } => millau_runtime::Call::System(millau_runtime::SystemCall::remark(
+				remark_payload.as_ref().map(|x| x.0.clone()).unwrap_or_default(),
+			)),
+			Call::Transfer { recipient, amount } => millau_runtime::Call::Balances(
+				millau_runtime::BalancesCall::transfer(recipient.raw_id(), amount.cast()),
+			),
+			Call::BridgeSendMessage {
+				lane,
+				payload,
+				fee,
+				bridge_instance_index,
+			} => match *bridge_instance_index {
+				bridge::MILLAU_TO_RIALTO_INDEX => {
+					let payload = Decode::decode(&mut &*payload.0)?;
+					millau_runtime::Call::BridgeRialtoMessages(millau_runtime::MessagesCall::send_message(
+						lane.0,
+						payload,
+						fee.cast(),
+					))
+				}
+				_ => anyhow::bail!(
+					"Unsupported target bridge pallet with instance index: {}",
+					bridge_instance_index
+				),
+			},
+		})
+	}
+}
+
+impl CliChain for Millau {
+	const RUNTIME_VERSION: RuntimeVersion = millau_runtime::VERSION;
+
+	type KeyPair = sp_core::sr25519::Pair;
+	type MessagePayload = MessagePayload<bp_millau::AccountId, bp_rialto::AccountSigner, bp_rialto::Signature, Vec<u8>>;
+
+	fn ss58_format() -> u16 {
+		millau_runtime::SS58Prefix::get() as u16
+	}
+
+	fn max_extrinsic_weight() -> Weight {
+		bp_millau::max_extrinsic_weight()
+	}
+
+	// TODO [#854|#843] support multiple bridges?
+	fn encode_message(message: encode_message::MessagePayload) -> Result<Self::MessagePayload, String> {
+		match message {
+			encode_message::MessagePayload::Raw { data } => MessagePayload::decode(&mut &*data.0)
+				.map_err(|e| format!("Failed to decode Millau's MessagePayload: {:?}", e)),
+			encode_message::MessagePayload::Call { mut call, mut sender } => {
+				type Source = Millau;
+				type Target = relay_rialto_client::Rialto;
+
+				sender.enforce_chain::<Source>();
+				let spec_version = Target::RUNTIME_VERSION.spec_version;
+				let origin = CallOrigin::SourceAccount(sender.raw_id());
+				encode_call::preprocess_call::<Source, Target>(&mut call, bridge::MILLAU_TO_RIALTO_INDEX);
+				let call = Target::encode_call(&call).map_err(|e| e.to_string())?;
+				let weight = call.get_dispatch_info().weight;
+
+				Ok(send_message::message_payload(spec_version, weight, origin, &call))
+			}
+		}
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/millau_headers_to_rialto.rs

@@ -0,0 +1,53 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Millau-to-Rialto headers sync entrypoint.
+
+use crate::finality_pipeline::{SubstrateFinalitySyncPipeline, SubstrateFinalityToSubstrate};
+
+use bp_header_chain::justification::GrandpaJustification;
+use codec::Encode;
+use relay_millau_client::{Millau, SyncHeader as MillauSyncHeader};
+use relay_rialto_client::{Rialto, SigningParams as RialtoSigningParams};
+use relay_substrate_client::{Chain, TransactionSignScheme};
+use sp_core::{Bytes, Pair};
+
+/// Millau-to-Rialto finality sync pipeline.
+pub(crate) type MillauFinalityToRialto = SubstrateFinalityToSubstrate<Millau, Rialto, RialtoSigningParams>;
+
+impl SubstrateFinalitySyncPipeline for MillauFinalityToRialto {
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str = bp_millau::BEST_FINALIZED_MILLAU_HEADER_METHOD;
+
+	type TargetChain = Rialto;
+
+	fn transactions_author(&self) -> bp_rialto::AccountId {
+		(*self.target_sign.public().as_array_ref()).into()
+	}
+
+	fn make_submit_finality_proof_transaction(
+		&self,
+		transaction_nonce: <Rialto as Chain>::Index,
+		header: MillauSyncHeader,
+		proof: GrandpaJustification<bp_millau::Header>,
+	) -> Bytes {
+		let call = rialto_runtime::BridgeGrandpaMillauCall::submit_finality_proof(header.into_inner(), proof).into();
+
+		let genesis_hash = *self.target_client.genesis_hash();
+		let transaction = Rialto::sign_transaction(genesis_hash, &self.target_sign, transaction_nonce, call);
+
+		Bytes(transaction.encode())
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/millau_messages_to_rialto.rs

@@ -0,0 +1,245 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Millau-to-Rialto messages sync entrypoint.
+
+use crate::messages_lane::{
+	select_delivery_transaction_limits, MessagesRelayParams, SubstrateMessageLane, SubstrateMessageLaneToSubstrate,
+};
+use crate::messages_source::SubstrateMessagesSource;
+use crate::messages_target::SubstrateMessagesTarget;
+
+use bp_messages::MessageNonce;
+use bp_runtime::{MILLAU_BRIDGE_INSTANCE, RIALTO_BRIDGE_INSTANCE};
+use bridge_runtime_common::messages::target::FromBridgedChainMessagesProof;
+use codec::Encode;
+use frame_support::dispatch::GetDispatchInfo;
+use messages_relay::message_lane::MessageLane;
+use relay_millau_client::{HeaderId as MillauHeaderId, Millau, SigningParams as MillauSigningParams};
+use relay_rialto_client::{HeaderId as RialtoHeaderId, Rialto, SigningParams as RialtoSigningParams};
+use relay_substrate_client::{
+	metrics::{FloatStorageValueMetric, StorageProofOverheadMetric},
+	Chain, TransactionSignScheme,
+};
+use sp_core::{Bytes, Pair};
+use std::{ops::RangeInclusive, time::Duration};
+
+/// Millau-to-Rialto message lane.
+pub type MillauMessagesToRialto =
+	SubstrateMessageLaneToSubstrate<Millau, MillauSigningParams, Rialto, RialtoSigningParams>;
+
+impl SubstrateMessageLane for MillauMessagesToRialto {
+	const OUTBOUND_LANE_MESSAGES_DISPATCH_WEIGHT_METHOD: &'static str =
+		bp_rialto::TO_RIALTO_MESSAGES_DISPATCH_WEIGHT_METHOD;
+	const OUTBOUND_LANE_LATEST_GENERATED_NONCE_METHOD: &'static str =
+		bp_rialto::TO_RIALTO_LATEST_GENERATED_NONCE_METHOD;
+	const OUTBOUND_LANE_LATEST_RECEIVED_NONCE_METHOD: &'static str = bp_rialto::TO_RIALTO_LATEST_RECEIVED_NONCE_METHOD;
+
+	const INBOUND_LANE_LATEST_RECEIVED_NONCE_METHOD: &'static str = bp_millau::FROM_MILLAU_LATEST_RECEIVED_NONCE_METHOD;
+	const INBOUND_LANE_LATEST_CONFIRMED_NONCE_METHOD: &'static str =
+		bp_millau::FROM_MILLAU_LATEST_CONFIRMED_NONCE_METHOD;
+	const INBOUND_LANE_UNREWARDED_RELAYERS_STATE: &'static str = bp_millau::FROM_MILLAU_UNREWARDED_RELAYERS_STATE;
+
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str = bp_millau::BEST_FINALIZED_MILLAU_HEADER_METHOD;
+	const BEST_FINALIZED_TARGET_HEADER_ID_AT_SOURCE: &'static str = bp_rialto::BEST_FINALIZED_RIALTO_HEADER_METHOD;
+
+	type SourceChain = Millau;
+	type TargetChain = Rialto;
+
+	fn source_transactions_author(&self) -> bp_rialto::AccountId {
+		(*self.source_sign.public().as_array_ref()).into()
+	}
+
+	fn make_messages_receiving_proof_transaction(
+		&self,
+		transaction_nonce: <Millau as Chain>::Index,
+		_generated_at_block: RialtoHeaderId,
+		proof: <Self as MessageLane>::MessagesReceivingProof,
+	) -> Bytes {
+		let (relayers_state, proof) = proof;
+		let call: millau_runtime::Call =
+			millau_runtime::MessagesCall::receive_messages_delivery_proof(proof, relayers_state).into();
+		let call_weight = call.get_dispatch_info().weight;
+		let genesis_hash = *self.source_client.genesis_hash();
+		let transaction = Millau::sign_transaction(genesis_hash, &self.source_sign, transaction_nonce, call);
+		log::trace!(
+			target: "bridge",
+			"Prepared Rialto -> Millau confirmation transaction. Weight: {}/{}, size: {}/{}",
+			call_weight,
+			bp_millau::max_extrinsic_weight(),
+			transaction.encode().len(),
+			bp_millau::max_extrinsic_size(),
+		);
+		Bytes(transaction.encode())
+	}
+
+	fn target_transactions_author(&self) -> bp_rialto::AccountId {
+		(*self.target_sign.public().as_array_ref()).into()
+	}
+
+	fn make_messages_delivery_transaction(
+		&self,
+		transaction_nonce: <Rialto as Chain>::Index,
+		_generated_at_header: MillauHeaderId,
+		_nonces: RangeInclusive<MessageNonce>,
+		proof: <Self as MessageLane>::MessagesProof,
+	) -> Bytes {
+		let (dispatch_weight, proof) = proof;
+		let FromBridgedChainMessagesProof {
+			ref nonces_start,
+			ref nonces_end,
+			..
+		} = proof;
+		let messages_count = nonces_end - nonces_start + 1;
+		let call: rialto_runtime::Call = rialto_runtime::MessagesCall::receive_messages_proof(
+			self.relayer_id_at_source.clone(),
+			proof,
+			messages_count as _,
+			dispatch_weight,
+		)
+		.into();
+		let call_weight = call.get_dispatch_info().weight;
+		let genesis_hash = *self.target_client.genesis_hash();
+		let transaction = Rialto::sign_transaction(genesis_hash, &self.target_sign, transaction_nonce, call);
+		log::trace!(
+			target: "bridge",
+			"Prepared Millau -> Rialto delivery transaction. Weight: {}/{}, size: {}/{}",
+			call_weight,
+			bp_rialto::max_extrinsic_weight(),
+			transaction.encode().len(),
+			bp_rialto::max_extrinsic_size(),
+		);
+		Bytes(transaction.encode())
+	}
+}
+
+/// Millau node as messages source.
+type MillauSourceClient = SubstrateMessagesSource<
+	Millau,
+	MillauMessagesToRialto,
+	millau_runtime::Runtime,
+	millau_runtime::WithRialtoMessagesInstance,
+>;
+
+/// Rialto node as messages target.
+type RialtoTargetClient = SubstrateMessagesTarget<
+	Rialto,
+	MillauMessagesToRialto,
+	rialto_runtime::Runtime,
+	rialto_runtime::WithMillauMessagesInstance,
+>;
+
+/// Run Millau-to-Rialto messages sync.
+pub async fn run(
+	params: MessagesRelayParams<Millau, MillauSigningParams, Rialto, RialtoSigningParams>,
+) -> Result<(), String> {
+	let stall_timeout = Duration::from_secs(5 * 60);
+	let relayer_id_at_millau = (*params.source_sign.public().as_array_ref()).into();
+
+	let lane_id = params.lane_id;
+	let source_client = params.source_client;
+	let lane = MillauMessagesToRialto {
+		source_client: source_client.clone(),
+		source_sign: params.source_sign,
+		target_client: params.target_client.clone(),
+		target_sign: params.target_sign,
+		relayer_id_at_source: relayer_id_at_millau,
+	};
+
+	// 2/3 is reserved for proofs and tx overhead
+	let max_messages_size_in_single_batch = bp_rialto::max_extrinsic_size() as usize / 3;
+	// TODO: use Millau weights after https://github.com/paritytech/parity-bridges-common/issues/390
+	let (max_messages_in_single_batch, max_messages_weight_in_single_batch) =
+		select_delivery_transaction_limits::<pallet_bridge_messages::weights::RialtoWeight<millau_runtime::Runtime>>(
+			bp_rialto::max_extrinsic_weight(),
+			bp_rialto::MAX_UNREWARDED_RELAYER_ENTRIES_AT_INBOUND_LANE,
+		);
+
+	log::info!(
+		target: "bridge",
+		"Starting Millau -> Rialto messages relay.\n\t\
+			Millau relayer account id: {:?}\n\t\
+			Max messages in single transaction: {}\n\t\
+			Max messages size in single transaction: {}\n\t\
+			Max messages weight in single transaction: {}",
+		lane.relayer_id_at_source,
+		max_messages_in_single_batch,
+		max_messages_size_in_single_batch,
+		max_messages_weight_in_single_batch,
+	);
+
+	messages_relay::message_lane_loop::run(
+		messages_relay::message_lane_loop::Params {
+			lane: lane_id,
+			source_tick: Millau::AVERAGE_BLOCK_INTERVAL,
+			target_tick: Rialto::AVERAGE_BLOCK_INTERVAL,
+			reconnect_delay: relay_utils::relay_loop::RECONNECT_DELAY,
+			stall_timeout,
+			delivery_params: messages_relay::message_lane_loop::MessageDeliveryParams {
+				max_unrewarded_relayer_entries_at_target: bp_rialto::MAX_UNREWARDED_RELAYER_ENTRIES_AT_INBOUND_LANE,
+				max_unconfirmed_nonces_at_target: bp_rialto::MAX_UNCONFIRMED_MESSAGES_AT_INBOUND_LANE,
+				max_messages_in_single_batch,
+				max_messages_weight_in_single_batch,
+				max_messages_size_in_single_batch,
+			},
+		},
+		MillauSourceClient::new(
+			source_client.clone(),
+			lane.clone(),
+			lane_id,
+			RIALTO_BRIDGE_INSTANCE,
+			params.target_to_source_headers_relay,
+		),
+		RialtoTargetClient::new(
+			params.target_client,
+			lane,
+			lane_id,
+			MILLAU_BRIDGE_INSTANCE,
+			params.source_to_target_headers_relay,
+		),
+		relay_utils::relay_metrics(
+			Some(messages_relay::message_lane_loop::metrics_prefix::<
+				MillauMessagesToRialto,
+			>(&lane_id)),
+			params.metrics_params,
+		)
+		.standalone_metric(|registry, prefix| {
+			StorageProofOverheadMetric::new(
+				registry,
+				prefix,
+				source_client.clone(),
+				"millau_storage_proof_overhead".into(),
+				"Millau storage proof overhead".into(),
+			)
+		})?
+		.standalone_metric(|registry, prefix| {
+			FloatStorageValueMetric::<_, sp_runtime::FixedU128>::new(
+				registry,
+				prefix,
+				source_client,
+				sp_core::storage::StorageKey(
+					millau_runtime::rialto_messages::RialtoToMillauConversionRate::key().to_vec(),
+				),
+				Some(millau_runtime::rialto_messages::INITIAL_RIALTO_TO_MILLAU_CONVERSION_RATE),
+				"millau_rialto_to_millau_conversion_rate".into(),
+				"Rialto to Millau tokens conversion rate (used by Rialto)".into(),
+			)
+		})?
+		.into_params(),
+		futures::future::pending(),
+	)
+	.await
+}

polkadot/bridges/relays/bin-substrate/src/chains/mod.rs

@@ -0,0 +1,335 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Chain-specific relayer configuration.
+
+pub mod millau_headers_to_rialto;
+pub mod millau_messages_to_rialto;
+pub mod rialto_headers_to_millau;
+pub mod rialto_messages_to_millau;
+pub mod rococo_headers_to_westend;
+pub mod westend_headers_to_millau;
+pub mod westend_headers_to_rococo;
+
+mod millau;
+mod rialto;
+mod rococo;
+mod westend;
+
+use relay_utils::metrics::{FloatJsonValueMetric, MetricsParams};
+
+pub(crate) fn add_polkadot_kusama_price_metrics<T: finality_relay::FinalitySyncPipeline>(
+	params: MetricsParams,
+) -> anyhow::Result<MetricsParams> {
+	Ok(
+		relay_utils::relay_metrics(Some(finality_relay::metrics_prefix::<T>()), params)
+			// Polkadot/Kusama prices are added as metrics here, because atm we don't have Polkadot <-> Kusama
+			// relays, but we want to test metrics/dashboards in advance
+			.standalone_metric(|registry, prefix| {
+				FloatJsonValueMetric::new(
+					registry,
+					prefix,
+					"https://api.coingecko.com/api/v3/simple/price?ids=Polkadot&vs_currencies=btc".into(),
+					"$.polkadot.btc".into(),
+					"polkadot_to_base_conversion_rate".into(),
+					"Rate used to convert from DOT to some BASE tokens".into(),
+				)
+			})
+			.map_err(|e| anyhow::format_err!("{}", e))?
+			.standalone_metric(|registry, prefix| {
+				FloatJsonValueMetric::new(
+					registry,
+					prefix,
+					"https://api.coingecko.com/api/v3/simple/price?ids=Kusama&vs_currencies=btc".into(),
+					"$.kusama.btc".into(),
+					"kusama_to_base_conversion_rate".into(),
+					"Rate used to convert from KSM to some BASE tokens".into(),
+				)
+			})
+			.map_err(|e| anyhow::format_err!("{}", e))?
+			.into_params(),
+	)
+}
+
+#[cfg(test)]
+mod tests {
+	use crate::cli::{encode_call, send_message};
+	use bp_messages::source_chain::TargetHeaderChain;
+	use codec::Encode;
+	use frame_support::dispatch::GetDispatchInfo;
+	use relay_millau_client::Millau;
+	use relay_rialto_client::Rialto;
+	use relay_substrate_client::TransactionSignScheme;
+	use sp_core::Pair;
+	use sp_runtime::traits::{IdentifyAccount, Verify};
+
+	#[test]
+	fn millau_signature_is_valid_on_rialto() {
+		let millau_sign = relay_millau_client::SigningParams::from_string("//Dave", None).unwrap();
+
+		let call = rialto_runtime::Call::System(rialto_runtime::SystemCall::remark(vec![]));
+
+		let millau_public: bp_millau::AccountSigner = millau_sign.public().into();
+		let millau_account_id: bp_millau::AccountId = millau_public.into_account();
+
+		let digest = millau_runtime::rialto_account_ownership_digest(
+			&call,
+			millau_account_id,
+			rialto_runtime::VERSION.spec_version,
+		);
+
+		let rialto_signer = relay_rialto_client::SigningParams::from_string("//Dave", None).unwrap();
+		let signature = rialto_signer.sign(&digest);
+
+		assert!(signature.verify(&digest[..], &rialto_signer.public()));
+	}
+
+	#[test]
+	fn rialto_signature_is_valid_on_millau() {
+		let rialto_sign = relay_rialto_client::SigningParams::from_string("//Dave", None).unwrap();
+
+		let call = millau_runtime::Call::System(millau_runtime::SystemCall::remark(vec![]));
+
+		let rialto_public: bp_rialto::AccountSigner = rialto_sign.public().into();
+		let rialto_account_id: bp_rialto::AccountId = rialto_public.into_account();
+
+		let digest = rialto_runtime::millau_account_ownership_digest(
+			&call,
+			rialto_account_id,
+			millau_runtime::VERSION.spec_version,
+		);
+
+		let millau_signer = relay_millau_client::SigningParams::from_string("//Dave", None).unwrap();
+		let signature = millau_signer.sign(&digest);
+
+		assert!(signature.verify(&digest[..], &millau_signer.public()));
+	}
+
+	#[test]
+	fn maximal_rialto_to_millau_message_arguments_size_is_computed_correctly() {
+		use rialto_runtime::millau_messages::Millau;
+
+		let maximal_remark_size = encode_call::compute_maximal_message_arguments_size(
+			bp_rialto::max_extrinsic_size(),
+			bp_millau::max_extrinsic_size(),
+		);
+
+		let call: millau_runtime::Call = millau_runtime::SystemCall::remark(vec![42; maximal_remark_size as _]).into();
+		let payload = send_message::message_payload(
+			Default::default(),
+			call.get_dispatch_info().weight,
+			pallet_bridge_dispatch::CallOrigin::SourceRoot,
+			&call,
+		);
+		assert_eq!(Millau::verify_message(&payload), Ok(()));
+
+		let call: millau_runtime::Call =
+			millau_runtime::SystemCall::remark(vec![42; (maximal_remark_size + 1) as _]).into();
+		let payload = send_message::message_payload(
+			Default::default(),
+			call.get_dispatch_info().weight,
+			pallet_bridge_dispatch::CallOrigin::SourceRoot,
+			&call,
+		);
+		assert!(Millau::verify_message(&payload).is_err());
+	}
+
+	#[test]
+	fn maximal_size_remark_to_rialto_is_generated_correctly() {
+		assert!(
+			bridge_runtime_common::messages::target::maximal_incoming_message_size(
+				bp_rialto::max_extrinsic_size()
+			) > bp_millau::max_extrinsic_size(),
+			"We can't actually send maximal messages to Rialto from Millau, because Millau extrinsics can't be that large",
+		)
+	}
+
+	#[test]
+	fn maximal_rialto_to_millau_message_dispatch_weight_is_computed_correctly() {
+		use rialto_runtime::millau_messages::Millau;
+
+		let maximal_dispatch_weight =
+			send_message::compute_maximal_message_dispatch_weight(bp_millau::max_extrinsic_weight());
+		let call: millau_runtime::Call = rialto_runtime::SystemCall::remark(vec![]).into();
+
+		let payload = send_message::message_payload(
+			Default::default(),
+			maximal_dispatch_weight,
+			pallet_bridge_dispatch::CallOrigin::SourceRoot,
+			&call,
+		);
+		assert_eq!(Millau::verify_message(&payload), Ok(()));
+
+		let payload = send_message::message_payload(
+			Default::default(),
+			maximal_dispatch_weight + 1,
+			pallet_bridge_dispatch::CallOrigin::SourceRoot,
+			&call,
+		);
+		assert!(Millau::verify_message(&payload).is_err());
+	}
+
+	#[test]
+	fn maximal_weight_fill_block_to_rialto_is_generated_correctly() {
+		use millau_runtime::rialto_messages::Rialto;
+
+		let maximal_dispatch_weight =
+			send_message::compute_maximal_message_dispatch_weight(bp_rialto::max_extrinsic_weight());
+		let call: rialto_runtime::Call = millau_runtime::SystemCall::remark(vec![]).into();
+
+		let payload = send_message::message_payload(
+			Default::default(),
+			maximal_dispatch_weight,
+			pallet_bridge_dispatch::CallOrigin::SourceRoot,
+			&call,
+		);
+		assert_eq!(Rialto::verify_message(&payload), Ok(()));
+
+		let payload = send_message::message_payload(
+			Default::default(),
+			maximal_dispatch_weight + 1,
+			pallet_bridge_dispatch::CallOrigin::SourceRoot,
+			&call,
+		);
+		assert!(Rialto::verify_message(&payload).is_err());
+	}
+
+	#[test]
+	fn rialto_tx_extra_bytes_constant_is_correct() {
+		let rialto_call = rialto_runtime::Call::System(rialto_runtime::SystemCall::remark(vec![]));
+		let rialto_tx = Rialto::sign_transaction(
+			Default::default(),
+			&sp_keyring::AccountKeyring::Alice.pair(),
+			0,
+			rialto_call.clone(),
+		);
+		let extra_bytes_in_transaction = rialto_tx.encode().len() - rialto_call.encode().len();
+		assert!(
+			bp_rialto::TX_EXTRA_BYTES as usize >= extra_bytes_in_transaction,
+			"Hardcoded number of extra bytes in Rialto transaction {} is lower than actual value: {}",
+			bp_rialto::TX_EXTRA_BYTES,
+			extra_bytes_in_transaction,
+		);
+	}
+
+	#[test]
+	fn millau_tx_extra_bytes_constant_is_correct() {
+		let millau_call = millau_runtime::Call::System(millau_runtime::SystemCall::remark(vec![]));
+		let millau_tx = Millau::sign_transaction(
+			Default::default(),
+			&sp_keyring::AccountKeyring::Alice.pair(),
+			0,
+			millau_call.clone(),
+		);
+		let extra_bytes_in_transaction = millau_tx.encode().len() - millau_call.encode().len();
+		assert!(
+			bp_millau::TX_EXTRA_BYTES as usize >= extra_bytes_in_transaction,
+			"Hardcoded number of extra bytes in Millau transaction {} is lower than actual value: {}",
+			bp_millau::TX_EXTRA_BYTES,
+			extra_bytes_in_transaction,
+		);
+	}
+}
+
+#[cfg(test)]
+mod rococo_tests {
+	use bp_header_chain::justification::GrandpaJustification;
+	use codec::Encode;
+
+	#[test]
+	fn scale_compatibility_of_bridges_call() {
+		// given
+		let header = sp_runtime::generic::Header {
+			parent_hash: Default::default(),
+			number: Default::default(),
+			state_root: Default::default(),
+			extrinsics_root: Default::default(),
+			digest: sp_runtime::generic::Digest { logs: vec![] },
+		};
+
+		let justification = GrandpaJustification {
+			round: 0,
+			commit: finality_grandpa::Commit {
+				target_hash: Default::default(),
+				target_number: Default::default(),
+				precommits: vec![],
+			},
+			votes_ancestries: vec![],
+		};
+
+		let actual = bp_rococo::BridgeGrandpaWestendCall::submit_finality_proof(header.clone(), justification.clone());
+		let expected = millau_runtime::BridgeGrandpaRialtoCall::<millau_runtime::Runtime>::submit_finality_proof(
+			header,
+			justification,
+		);
+
+		// when
+		let actual_encoded = actual.encode();
+		let expected_encoded = expected.encode();
+
+		// then
+		assert_eq!(
+			actual_encoded, expected_encoded,
+			"\n\nEncoding difference.\nGot {:#?} \nExpected: {:#?}",
+			actual, expected
+		);
+	}
+}
+
+#[cfg(test)]
+mod westend_tests {
+	use bp_header_chain::justification::GrandpaJustification;
+	use codec::Encode;
+
+	#[test]
+	fn scale_compatibility_of_bridges_call() {
+		// given
+		let header = sp_runtime::generic::Header {
+			parent_hash: Default::default(),
+			number: Default::default(),
+			state_root: Default::default(),
+			extrinsics_root: Default::default(),
+			digest: sp_runtime::generic::Digest { logs: vec![] },
+		};
+
+		let justification = GrandpaJustification {
+			round: 0,
+			commit: finality_grandpa::Commit {
+				target_hash: Default::default(),
+				target_number: Default::default(),
+				precommits: vec![],
+			},
+			votes_ancestries: vec![],
+		};
+
+		let actual = bp_westend::BridgeGrandpaRococoCall::submit_finality_proof(header.clone(), justification.clone());
+		let expected = millau_runtime::BridgeGrandpaRialtoCall::<millau_runtime::Runtime>::submit_finality_proof(
+			header,
+			justification,
+		);
+
+		// when
+		let actual_encoded = actual.encode();
+		let expected_encoded = expected.encode();
+
+		// then
+		assert_eq!(
+			actual_encoded, expected_encoded,
+			"\n\nEncoding difference.\nGot {:#?} \nExpected: {:#?}",
+			actual, expected
+		);
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/rialto.rs

@@ -0,0 +1,98 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Rialto chain specification for CLI.
+
+use crate::cli::{
+	bridge,
+	encode_call::{self, Call, CliEncodeCall},
+	encode_message, send_message, CliChain,
+};
+use codec::Decode;
+use frame_support::weights::{GetDispatchInfo, Weight};
+use pallet_bridge_dispatch::{CallOrigin, MessagePayload};
+use relay_rialto_client::Rialto;
+use sp_version::RuntimeVersion;
+
+impl CliEncodeCall for Rialto {
+	fn max_extrinsic_size() -> u32 {
+		bp_rialto::max_extrinsic_size()
+	}
+
+	fn encode_call(call: &Call) -> anyhow::Result<Self::Call> {
+		Ok(match call {
+			Call::Raw { data } => Decode::decode(&mut &*data.0)?,
+			Call::Remark { remark_payload, .. } => rialto_runtime::Call::System(rialto_runtime::SystemCall::remark(
+				remark_payload.as_ref().map(|x| x.0.clone()).unwrap_or_default(),
+			)),
+			Call::Transfer { recipient, amount } => {
+				rialto_runtime::Call::Balances(rialto_runtime::BalancesCall::transfer(recipient.raw_id(), amount.0))
+			}
+			Call::BridgeSendMessage {
+				lane,
+				payload,
+				fee,
+				bridge_instance_index,
+			} => match *bridge_instance_index {
+				bridge::RIALTO_TO_MILLAU_INDEX => {
+					let payload = Decode::decode(&mut &*payload.0)?;
+					rialto_runtime::Call::BridgeMillauMessages(rialto_runtime::MessagesCall::send_message(
+						lane.0, payload, fee.0,
+					))
+				}
+				_ => anyhow::bail!(
+					"Unsupported target bridge pallet with instance index: {}",
+					bridge_instance_index
+				),
+			},
+		})
+	}
+}
+
+impl CliChain for Rialto {
+	const RUNTIME_VERSION: RuntimeVersion = rialto_runtime::VERSION;
+
+	type KeyPair = sp_core::sr25519::Pair;
+	type MessagePayload = MessagePayload<bp_rialto::AccountId, bp_millau::AccountSigner, bp_millau::Signature, Vec<u8>>;
+
+	fn ss58_format() -> u16 {
+		rialto_runtime::SS58Prefix::get() as u16
+	}
+
+	fn max_extrinsic_weight() -> Weight {
+		bp_rialto::max_extrinsic_weight()
+	}
+
+	fn encode_message(message: encode_message::MessagePayload) -> Result<Self::MessagePayload, String> {
+		match message {
+			encode_message::MessagePayload::Raw { data } => MessagePayload::decode(&mut &*data.0)
+				.map_err(|e| format!("Failed to decode Rialto's MessagePayload: {:?}", e)),
+			encode_message::MessagePayload::Call { mut call, mut sender } => {
+				type Source = Rialto;
+				type Target = relay_millau_client::Millau;
+
+				sender.enforce_chain::<Source>();
+				let spec_version = Target::RUNTIME_VERSION.spec_version;
+				let origin = CallOrigin::SourceAccount(sender.raw_id());
+				encode_call::preprocess_call::<Source, Target>(&mut call, bridge::RIALTO_TO_MILLAU_INDEX);
+				let call = Target::encode_call(&call).map_err(|e| e.to_string())?;
+				let weight = call.get_dispatch_info().weight;
+
+				Ok(send_message::message_payload(spec_version, weight, origin, &call))
+			}
+		}
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/rialto_headers_to_millau.rs

@@ -0,0 +1,57 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Rialto-to-Millau headers sync entrypoint.
+
+use crate::finality_pipeline::{SubstrateFinalitySyncPipeline, SubstrateFinalityToSubstrate};
+
+use bp_header_chain::justification::GrandpaJustification;
+use codec::Encode;
+use relay_millau_client::{Millau, SigningParams as MillauSigningParams};
+use relay_rialto_client::{Rialto, SyncHeader as RialtoSyncHeader};
+use relay_substrate_client::{Chain, TransactionSignScheme};
+use sp_core::{Bytes, Pair};
+
+/// Rialto-to-Millau finality sync pipeline.
+pub(crate) type RialtoFinalityToMillau = SubstrateFinalityToSubstrate<Rialto, Millau, MillauSigningParams>;
+
+impl SubstrateFinalitySyncPipeline for RialtoFinalityToMillau {
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str = bp_rialto::BEST_FINALIZED_RIALTO_HEADER_METHOD;
+
+	type TargetChain = Millau;
+
+	fn transactions_author(&self) -> bp_millau::AccountId {
+		(*self.target_sign.public().as_array_ref()).into()
+	}
+
+	fn make_submit_finality_proof_transaction(
+		&self,
+		transaction_nonce: <Millau as Chain>::Index,
+		header: RialtoSyncHeader,
+		proof: GrandpaJustification<bp_rialto::Header>,
+	) -> Bytes {
+		let call = millau_runtime::BridgeGrandpaRialtoCall::<
+			millau_runtime::Runtime,
+			millau_runtime::RialtoGrandpaInstance,
+		>::submit_finality_proof(header.into_inner(), proof)
+		.into();
+
+		let genesis_hash = *self.target_client.genesis_hash();
+		let transaction = Millau::sign_transaction(genesis_hash, &self.target_sign, transaction_nonce, call);
+
+		Bytes(transaction.encode())
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/rialto_messages_to_millau.rs

@@ -0,0 +1,244 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Rialto-to-Millau messages sync entrypoint.
+
+use crate::messages_lane::{
+	select_delivery_transaction_limits, MessagesRelayParams, SubstrateMessageLane, SubstrateMessageLaneToSubstrate,
+};
+use crate::messages_source::SubstrateMessagesSource;
+use crate::messages_target::SubstrateMessagesTarget;
+
+use bp_messages::MessageNonce;
+use bp_runtime::{MILLAU_BRIDGE_INSTANCE, RIALTO_BRIDGE_INSTANCE};
+use bridge_runtime_common::messages::target::FromBridgedChainMessagesProof;
+use codec::Encode;
+use frame_support::dispatch::GetDispatchInfo;
+use messages_relay::message_lane::MessageLane;
+use relay_millau_client::{HeaderId as MillauHeaderId, Millau, SigningParams as MillauSigningParams};
+use relay_rialto_client::{HeaderId as RialtoHeaderId, Rialto, SigningParams as RialtoSigningParams};
+use relay_substrate_client::{
+	metrics::{FloatStorageValueMetric, StorageProofOverheadMetric},
+	Chain, TransactionSignScheme,
+};
+use sp_core::{Bytes, Pair};
+use std::{ops::RangeInclusive, time::Duration};
+
+/// Rialto-to-Millau message lane.
+pub type RialtoMessagesToMillau =
+	SubstrateMessageLaneToSubstrate<Rialto, RialtoSigningParams, Millau, MillauSigningParams>;
+
+impl SubstrateMessageLane for RialtoMessagesToMillau {
+	const OUTBOUND_LANE_MESSAGES_DISPATCH_WEIGHT_METHOD: &'static str =
+		bp_millau::TO_MILLAU_MESSAGES_DISPATCH_WEIGHT_METHOD;
+	const OUTBOUND_LANE_LATEST_GENERATED_NONCE_METHOD: &'static str =
+		bp_millau::TO_MILLAU_LATEST_GENERATED_NONCE_METHOD;
+	const OUTBOUND_LANE_LATEST_RECEIVED_NONCE_METHOD: &'static str = bp_millau::TO_MILLAU_LATEST_RECEIVED_NONCE_METHOD;
+
+	const INBOUND_LANE_LATEST_RECEIVED_NONCE_METHOD: &'static str = bp_rialto::FROM_RIALTO_LATEST_RECEIVED_NONCE_METHOD;
+	const INBOUND_LANE_LATEST_CONFIRMED_NONCE_METHOD: &'static str =
+		bp_rialto::FROM_RIALTO_LATEST_CONFIRMED_NONCE_METHOD;
+	const INBOUND_LANE_UNREWARDED_RELAYERS_STATE: &'static str = bp_rialto::FROM_RIALTO_UNREWARDED_RELAYERS_STATE;
+
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str = bp_rialto::BEST_FINALIZED_RIALTO_HEADER_METHOD;
+	const BEST_FINALIZED_TARGET_HEADER_ID_AT_SOURCE: &'static str = bp_millau::BEST_FINALIZED_MILLAU_HEADER_METHOD;
+
+	type SourceChain = Rialto;
+	type TargetChain = Millau;
+
+	fn source_transactions_author(&self) -> bp_rialto::AccountId {
+		(*self.source_sign.public().as_array_ref()).into()
+	}
+
+	fn make_messages_receiving_proof_transaction(
+		&self,
+		transaction_nonce: <Rialto as Chain>::Index,
+		_generated_at_block: MillauHeaderId,
+		proof: <Self as MessageLane>::MessagesReceivingProof,
+	) -> Bytes {
+		let (relayers_state, proof) = proof;
+		let call: rialto_runtime::Call =
+			rialto_runtime::MessagesCall::receive_messages_delivery_proof(proof, relayers_state).into();
+		let call_weight = call.get_dispatch_info().weight;
+		let genesis_hash = *self.source_client.genesis_hash();
+		let transaction = Rialto::sign_transaction(genesis_hash, &self.source_sign, transaction_nonce, call);
+		log::trace!(
+			target: "bridge",
+			"Prepared Millau -> Rialto confirmation transaction. Weight: {}/{}, size: {}/{}",
+			call_weight,
+			bp_rialto::max_extrinsic_weight(),
+			transaction.encode().len(),
+			bp_rialto::max_extrinsic_size(),
+		);
+		Bytes(transaction.encode())
+	}
+
+	fn target_transactions_author(&self) -> bp_rialto::AccountId {
+		(*self.target_sign.public().as_array_ref()).into()
+	}
+
+	fn make_messages_delivery_transaction(
+		&self,
+		transaction_nonce: <Millau as Chain>::Index,
+		_generated_at_header: RialtoHeaderId,
+		_nonces: RangeInclusive<MessageNonce>,
+		proof: <Self as MessageLane>::MessagesProof,
+	) -> Bytes {
+		let (dispatch_weight, proof) = proof;
+		let FromBridgedChainMessagesProof {
+			ref nonces_start,
+			ref nonces_end,
+			..
+		} = proof;
+		let messages_count = nonces_end - nonces_start + 1;
+		let call: millau_runtime::Call = millau_runtime::MessagesCall::receive_messages_proof(
+			self.relayer_id_at_source.clone(),
+			proof,
+			messages_count as _,
+			dispatch_weight,
+		)
+		.into();
+		let call_weight = call.get_dispatch_info().weight;
+		let genesis_hash = *self.target_client.genesis_hash();
+		let transaction = Millau::sign_transaction(genesis_hash, &self.target_sign, transaction_nonce, call);
+		log::trace!(
+			target: "bridge",
+			"Prepared Rialto -> Millau delivery transaction. Weight: {}/{}, size: {}/{}",
+			call_weight,
+			bp_millau::max_extrinsic_weight(),
+			transaction.encode().len(),
+			bp_millau::max_extrinsic_size(),
+		);
+		Bytes(transaction.encode())
+	}
+}
+
+/// Rialto node as messages source.
+type RialtoSourceClient = SubstrateMessagesSource<
+	Rialto,
+	RialtoMessagesToMillau,
+	rialto_runtime::Runtime,
+	rialto_runtime::WithMillauMessagesInstance,
+>;
+
+/// Millau node as messages target.
+type MillauTargetClient = SubstrateMessagesTarget<
+	Millau,
+	RialtoMessagesToMillau,
+	millau_runtime::Runtime,
+	millau_runtime::WithRialtoMessagesInstance,
+>;
+
+/// Run Rialto-to-Millau messages sync.
+pub async fn run(
+	params: MessagesRelayParams<Rialto, RialtoSigningParams, Millau, MillauSigningParams>,
+) -> Result<(), String> {
+	let stall_timeout = Duration::from_secs(5 * 60);
+	let relayer_id_at_rialto = (*params.source_sign.public().as_array_ref()).into();
+
+	let lane_id = params.lane_id;
+	let source_client = params.source_client;
+	let lane = RialtoMessagesToMillau {
+		source_client: source_client.clone(),
+		source_sign: params.source_sign,
+		target_client: params.target_client.clone(),
+		target_sign: params.target_sign,
+		relayer_id_at_source: relayer_id_at_rialto,
+	};
+
+	// 2/3 is reserved for proofs and tx overhead
+	let max_messages_size_in_single_batch = bp_millau::max_extrinsic_size() as usize / 3;
+	let (max_messages_in_single_batch, max_messages_weight_in_single_batch) =
+		select_delivery_transaction_limits::<pallet_bridge_messages::weights::RialtoWeight<rialto_runtime::Runtime>>(
+			bp_millau::max_extrinsic_weight(),
+			bp_millau::MAX_UNREWARDED_RELAYER_ENTRIES_AT_INBOUND_LANE,
+		);
+
+	log::info!(
+		target: "bridge",
+		"Starting Rialto -> Millau messages relay.\n\t\
+			Rialto relayer account id: {:?}\n\t\
+			Max messages in single transaction: {}\n\t\
+			Max messages size in single transaction: {}\n\t\
+			Max messages weight in single transaction: {}",
+		lane.relayer_id_at_source,
+		max_messages_in_single_batch,
+		max_messages_size_in_single_batch,
+		max_messages_weight_in_single_batch,
+	);
+
+	messages_relay::message_lane_loop::run(
+		messages_relay::message_lane_loop::Params {
+			lane: lane_id,
+			source_tick: Rialto::AVERAGE_BLOCK_INTERVAL,
+			target_tick: Millau::AVERAGE_BLOCK_INTERVAL,
+			reconnect_delay: relay_utils::relay_loop::RECONNECT_DELAY,
+			stall_timeout,
+			delivery_params: messages_relay::message_lane_loop::MessageDeliveryParams {
+				max_unrewarded_relayer_entries_at_target: bp_millau::MAX_UNREWARDED_RELAYER_ENTRIES_AT_INBOUND_LANE,
+				max_unconfirmed_nonces_at_target: bp_millau::MAX_UNCONFIRMED_MESSAGES_AT_INBOUND_LANE,
+				max_messages_in_single_batch,
+				max_messages_weight_in_single_batch,
+				max_messages_size_in_single_batch,
+			},
+		},
+		RialtoSourceClient::new(
+			source_client.clone(),
+			lane.clone(),
+			lane_id,
+			MILLAU_BRIDGE_INSTANCE,
+			params.target_to_source_headers_relay,
+		),
+		MillauTargetClient::new(
+			params.target_client,
+			lane,
+			lane_id,
+			RIALTO_BRIDGE_INSTANCE,
+			params.source_to_target_headers_relay,
+		),
+		relay_utils::relay_metrics(
+			Some(messages_relay::message_lane_loop::metrics_prefix::<
+				RialtoMessagesToMillau,
+			>(&lane_id)),
+			params.metrics_params,
+		)
+		.standalone_metric(|registry, prefix| {
+			StorageProofOverheadMetric::new(
+				registry,
+				prefix,
+				source_client.clone(),
+				"rialto_storage_proof_overhead".into(),
+				"Rialto storage proof overhead".into(),
+			)
+		})?
+		.standalone_metric(|registry, prefix| {
+			FloatStorageValueMetric::<_, sp_runtime::FixedU128>::new(
+				registry,
+				prefix,
+				source_client,
+				sp_core::storage::StorageKey(
+					rialto_runtime::millau_messages::MillauToRialtoConversionRate::key().to_vec(),
+				),
+				Some(rialto_runtime::millau_messages::INITIAL_MILLAU_TO_RIALTO_CONVERSION_RATE),
+				"rialto_millau_to_rialto_conversion_rate".into(),
+				"Millau to Rialto tokens conversion rate (used by Millau)".into(),
+			)
+		})?
+		.into_params(),
+		futures::future::pending(),
+	)
+	.await
+}

polkadot/bridges/relays/bin-substrate/src/chains/rococo.rs

@@ -0,0 +1,39 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::{encode_message, CliChain};
+use frame_support::weights::Weight;
+use relay_rococo_client::Rococo;
+use sp_version::RuntimeVersion;
+
+impl CliChain for Rococo {
+	const RUNTIME_VERSION: RuntimeVersion = bp_rococo::VERSION;
+
+	type KeyPair = sp_core::sr25519::Pair;
+	type MessagePayload = ();
+
+	fn ss58_format() -> u16 {
+		42
+	}
+
+	fn max_extrinsic_weight() -> Weight {
+		0
+	}
+
+	fn encode_message(_message: encode_message::MessagePayload) -> Result<Self::MessagePayload, String> {
+		Err("Sending messages from Rococo is not yet supported.".into())
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/rococo_headers_to_westend.rs

@@ -0,0 +1,60 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Rococo-to-Westend headers sync entrypoint.
+
+use crate::finality_pipeline::{SubstrateFinalitySyncPipeline, SubstrateFinalityToSubstrate};
+
+use bp_header_chain::justification::GrandpaJustification;
+use codec::Encode;
+use relay_rococo_client::{Rococo, SyncHeader as RococoSyncHeader};
+use relay_substrate_client::{Chain, TransactionSignScheme};
+use relay_utils::metrics::MetricsParams;
+use relay_westend_client::{SigningParams as WestendSigningParams, Westend};
+use sp_core::{Bytes, Pair};
+
+/// Rococo-to-Westend finality sync pipeline.
+pub(crate) type RococoFinalityToWestend = SubstrateFinalityToSubstrate<Rococo, Westend, WestendSigningParams>;
+
+impl SubstrateFinalitySyncPipeline for RococoFinalityToWestend {
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str = bp_rococo::BEST_FINALIZED_ROCOCO_HEADER_METHOD;
+
+	type TargetChain = Westend;
+
+	fn customize_metrics(params: MetricsParams) -> anyhow::Result<MetricsParams> {
+		crate::chains::add_polkadot_kusama_price_metrics::<Self>(params)
+	}
+
+	fn transactions_author(&self) -> bp_westend::AccountId {
+		(*self.target_sign.public().as_array_ref()).into()
+	}
+
+	fn make_submit_finality_proof_transaction(
+		&self,
+		transaction_nonce: <Westend as Chain>::Index,
+		header: RococoSyncHeader,
+		proof: GrandpaJustification<bp_rococo::Header>,
+	) -> Bytes {
+		let call = bp_westend::Call::BridgeGrandpaRococo(bp_westend::BridgeGrandpaRococoCall::submit_finality_proof(
+			header.into_inner(),
+			proof,
+		));
+		let genesis_hash = *self.target_client.genesis_hash();
+		let transaction = Westend::sign_transaction(genesis_hash, &self.target_sign, transaction_nonce, call);
+
+		Bytes(transaction.encode())
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/westend.rs

@@ -0,0 +1,41 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Westend chain specification for CLI.
+
+use crate::cli::{encode_message, CliChain};
+use frame_support::weights::Weight;
+use relay_westend_client::Westend;
+use sp_version::RuntimeVersion;
+
+impl CliChain for Westend {
+	const RUNTIME_VERSION: RuntimeVersion = bp_westend::VERSION;
+
+	type KeyPair = sp_core::sr25519::Pair;
+	type MessagePayload = ();
+
+	fn ss58_format() -> u16 {
+		42
+	}
+
+	fn max_extrinsic_weight() -> Weight {
+		0
+	}
+
+	fn encode_message(_message: encode_message::MessagePayload) -> Result<Self::MessagePayload, String> {
+		Err("Sending messages from Westend is not yet supported.".into())
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/westend_headers_to_millau.rs

@@ -0,0 +1,62 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Westend-to-Millau headers sync entrypoint.
+
+use crate::finality_pipeline::{SubstrateFinalitySyncPipeline, SubstrateFinalityToSubstrate};
+
+use bp_header_chain::justification::GrandpaJustification;
+use codec::Encode;
+use relay_millau_client::{Millau, SigningParams as MillauSigningParams};
+use relay_substrate_client::{Chain, TransactionSignScheme};
+use relay_utils::metrics::MetricsParams;
+use relay_westend_client::{SyncHeader as WestendSyncHeader, Westend};
+use sp_core::{Bytes, Pair};
+
+/// Westend-to-Millau finality sync pipeline.
+pub(crate) type WestendFinalityToMillau = SubstrateFinalityToSubstrate<Westend, Millau, MillauSigningParams>;
+
+impl SubstrateFinalitySyncPipeline for WestendFinalityToMillau {
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str = bp_westend::BEST_FINALIZED_WESTEND_HEADER_METHOD;
+
+	type TargetChain = Millau;
+
+	fn customize_metrics(params: MetricsParams) -> anyhow::Result<MetricsParams> {
+		crate::chains::add_polkadot_kusama_price_metrics::<Self>(params)
+	}
+
+	fn transactions_author(&self) -> bp_millau::AccountId {
+		(*self.target_sign.public().as_array_ref()).into()
+	}
+
+	fn make_submit_finality_proof_transaction(
+		&self,
+		transaction_nonce: <Millau as Chain>::Index,
+		header: WestendSyncHeader,
+		proof: GrandpaJustification<bp_westend::Header>,
+	) -> Bytes {
+		let call = millau_runtime::BridgeGrandpaWestendCall::<
+			millau_runtime::Runtime,
+			millau_runtime::WestendGrandpaInstance,
+		>::submit_finality_proof(header.into_inner(), proof)
+		.into();
+
+		let genesis_hash = *self.target_client.genesis_hash();
+		let transaction = Millau::sign_transaction(genesis_hash, &self.target_sign, transaction_nonce, call);
+
+		Bytes(transaction.encode())
+	}
+}

polkadot/bridges/relays/bin-substrate/src/chains/westend_headers_to_rococo.rs

@@ -0,0 +1,60 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Westend-to-Rococo headers sync entrypoint.
+
+use crate::finality_pipeline::{SubstrateFinalitySyncPipeline, SubstrateFinalityToSubstrate};
+
+use bp_header_chain::justification::GrandpaJustification;
+use codec::Encode;
+use relay_rococo_client::{Rococo, SigningParams as RococoSigningParams};
+use relay_substrate_client::{Chain, TransactionSignScheme};
+use relay_utils::metrics::MetricsParams;
+use relay_westend_client::{SyncHeader as WestendSyncHeader, Westend};
+use sp_core::{Bytes, Pair};
+
+/// Westend-to-Rococo finality sync pipeline.
+pub(crate) type WestendFinalityToRococo = SubstrateFinalityToSubstrate<Westend, Rococo, RococoSigningParams>;
+
+impl SubstrateFinalitySyncPipeline for WestendFinalityToRococo {
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str = bp_westend::BEST_FINALIZED_WESTEND_HEADER_METHOD;
+
+	type TargetChain = Rococo;
+
+	fn customize_metrics(params: MetricsParams) -> anyhow::Result<MetricsParams> {
+		crate::chains::add_polkadot_kusama_price_metrics::<Self>(params)
+	}
+
+	fn transactions_author(&self) -> bp_rococo::AccountId {
+		(*self.target_sign.public().as_array_ref()).into()
+	}
+
+	fn make_submit_finality_proof_transaction(
+		&self,
+		transaction_nonce: <Rococo as Chain>::Index,
+		header: WestendSyncHeader,
+		proof: GrandpaJustification<bp_westend::Header>,
+	) -> Bytes {
+		let call = bp_rococo::Call::BridgeGrandpaWestend(bp_rococo::BridgeGrandpaWestendCall::submit_finality_proof(
+			header.into_inner(),
+			proof,
+		));
+		let genesis_hash = *self.target_client.genesis_hash();
+		let transaction = Rococo::sign_transaction(genesis_hash, &self.target_sign, transaction_nonce, call);
+
+		Bytes(transaction.encode())
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/bridge.rs

@@ -0,0 +1,96 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use structopt::clap::arg_enum;
+
+arg_enum! {
+	#[derive(Debug, PartialEq, Eq)]
+	/// Supported full bridges (headers + messages).
+	pub enum FullBridge {
+		MillauToRialto,
+		RialtoToMillau,
+	}
+}
+
+impl FullBridge {
+	/// Return instance index of the bridge pallet in source runtime.
+	pub fn bridge_instance_index(&self) -> u8 {
+		match self {
+			Self::MillauToRialto => MILLAU_TO_RIALTO_INDEX,
+			Self::RialtoToMillau => RIALTO_TO_MILLAU_INDEX,
+		}
+	}
+}
+
+pub const RIALTO_TO_MILLAU_INDEX: u8 = 0;
+pub const MILLAU_TO_RIALTO_INDEX: u8 = 0;
+
+/// The macro allows executing bridge-specific code without going fully generic.
+///
+/// It matches on the [`FullBridge`] enum, sets bridge-specific types or imports and injects
+/// the `$generic` code at every variant.
+#[macro_export]
+macro_rules! select_full_bridge {
+	($bridge: expr, $generic: tt) => {
+		match $bridge {
+			FullBridge::MillauToRialto => {
+				type Source = relay_millau_client::Millau;
+				#[allow(dead_code)]
+				type Target = relay_rialto_client::Rialto;
+
+				// Derive-account
+				#[allow(unused_imports)]
+				use bp_millau::derive_account_from_rialto_id as derive_account;
+
+				// Relay-messages
+				#[allow(unused_imports)]
+				use crate::chains::millau_messages_to_rialto::run as relay_messages;
+
+				// Send-message / Estimate-fee
+				#[allow(unused_imports)]
+				use bp_rialto::TO_RIALTO_ESTIMATE_MESSAGE_FEE_METHOD as ESTIMATE_MESSAGE_FEE_METHOD;
+				// Send-message
+				#[allow(unused_imports)]
+				use millau_runtime::rialto_account_ownership_digest as account_ownership_digest;
+
+				$generic
+			}
+			FullBridge::RialtoToMillau => {
+				type Source = relay_rialto_client::Rialto;
+				#[allow(dead_code)]
+				type Target = relay_millau_client::Millau;
+
+				// Derive-account
+				#[allow(unused_imports)]
+				use bp_rialto::derive_account_from_millau_id as derive_account;
+
+				// Relay-messages
+				#[allow(unused_imports)]
+				use crate::chains::rialto_messages_to_millau::run as relay_messages;
+
+				// Send-message / Estimate-fee
+				#[allow(unused_imports)]
+				use bp_millau::TO_MILLAU_ESTIMATE_MESSAGE_FEE_METHOD as ESTIMATE_MESSAGE_FEE_METHOD;
+
+				// Send-message
+				#[allow(unused_imports)]
+				use rialto_runtime::millau_account_ownership_digest as account_ownership_digest;
+
+				$generic
+			}
+		}
+	};
+}

polkadot/bridges/relays/bin-substrate/src/cli/derive_account.rs

@@ -0,0 +1,102 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::{bridge::FullBridge, AccountId};
+use crate::select_full_bridge;
+use relay_substrate_client::Chain;
+use structopt::StructOpt;
+
+/// Given a source chain `AccountId`, derive the corresponding `AccountId` for the target chain.
+///
+/// The (derived) target chain `AccountId` is going to be used as dispatch origin of the call
+/// that has been sent over the bridge.
+/// This account can also be used to receive target-chain funds (or other form of ownership),
+/// since messages sent over the bridge will be able to spend these.
+#[derive(StructOpt)]
+pub struct DeriveAccount {
+	/// A bridge instance to initalize.
+	#[structopt(possible_values = &FullBridge::variants(), case_insensitive = true)]
+	bridge: FullBridge,
+	/// Source-chain address to derive Target-chain address from.
+	account: AccountId,
+}
+
+impl DeriveAccount {
+	/// Parse CLI arguments and derive account.
+	///
+	/// Returns both the Source account in correct SS58 format and the derived account.
+	fn derive_account(&self) -> (AccountId, AccountId) {
+		select_full_bridge!(self.bridge, {
+			let mut account = self.account.clone();
+			account.enforce_chain::<Source>();
+			let acc = bp_runtime::SourceAccount::Account(account.raw_id());
+			let id = derive_account(acc);
+			let derived_account = AccountId::from_raw::<Target>(id);
+			(account, derived_account)
+		})
+	}
+
+	/// Run the command.
+	pub async fn run(self) -> anyhow::Result<()> {
+		select_full_bridge!(self.bridge, {
+			let (account, derived_account) = self.derive_account();
+			println!("Source address:\n{} ({})", account, Source::NAME);
+			println!(
+				"->Corresponding (derived) address:\n{} ({})",
+				derived_account,
+				Target::NAME,
+			);
+
+			Ok(())
+		})
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+
+	fn derive_account_cli(bridge: &str, account: &str) -> (AccountId, AccountId) {
+		DeriveAccount::from_iter(vec!["derive-account", bridge, account]).derive_account()
+	}
+
+	#[test]
+	fn should_derive_accounts_correctly() {
+		// given
+		let rialto = "5sauUXUfPjmwxSgmb3tZ5d6yx24eZX4wWJ2JtVUBaQqFbvEU";
+		let millau = "752paRyW1EGfq9YLTSSqcSJ5hqnBDidBmaftGhBo8fy6ypW9";
+
+		// when
+		let (rialto_parsed, rialto_derived) = derive_account_cli("RialtoToMillau", rialto);
+		let (millau_parsed, millau_derived) = derive_account_cli("MillauToRialto", millau);
+		let (millau2_parsed, millau2_derived) = derive_account_cli("MillauToRialto", rialto);
+
+		// then
+		assert_eq!(format!("{}", rialto_parsed), rialto);
+		assert_eq!(format!("{}", millau_parsed), millau);
+		assert_eq!(format!("{}", millau2_parsed), millau);
+
+		assert_eq!(
+			format!("{}", rialto_derived),
+			"73gLnUwrAdH4vMjbXCiNEpgyz1PLk9JxCaY4cKzvfSZT73KE"
+		);
+		assert_eq!(
+			format!("{}", millau_derived),
+			"5rpTJqGv1BPAYy2sXzkPpc3Wx1ZpQtgfuBsrDpNV4HsXAmbi"
+		);
+		assert_eq!(millau_derived, millau2_derived);
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/encode_call.rs

@@ -0,0 +1,275 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::bridge::FullBridge;
+use crate::cli::{AccountId, Balance, CliChain, ExplicitOrMaximal, HexBytes, HexLaneId};
+use crate::select_full_bridge;
+use frame_support::dispatch::GetDispatchInfo;
+use relay_substrate_client::Chain;
+use structopt::StructOpt;
+
+/// Encode source chain runtime call.
+#[derive(StructOpt, Debug)]
+pub struct EncodeCall {
+	/// A bridge instance to encode call for.
+	#[structopt(possible_values = &FullBridge::variants(), case_insensitive = true)]
+	bridge: FullBridge,
+	#[structopt(flatten)]
+	call: Call,
+}
+
+/// All possible messages that may be delivered to generic Substrate chain.
+///
+/// Note this enum may be used in the context of both Source (as part of `encode-call`)
+/// and Target chain (as part of `encode-message/send-message`).
+#[derive(StructOpt, Debug, PartialEq, Eq)]
+pub enum Call {
+	/// Raw bytes for the message
+	Raw {
+		/// Raw, SCALE-encoded message
+		data: HexBytes,
+	},
+	/// Make an on-chain remark (comment).
+	Remark {
+		/// Explicit remark payload.
+		#[structopt(long, conflicts_with("remark-size"))]
+		remark_payload: Option<HexBytes>,
+		/// Remark size. If not passed, small UTF8-encoded string is generated by relay as remark.
+		#[structopt(long, conflicts_with("remark-payload"))]
+		remark_size: Option<ExplicitOrMaximal<usize>>,
+	},
+	/// Transfer the specified `amount` of native tokens to a particular `recipient`.
+	Transfer {
+		/// Address of an account to receive the transfer.
+		#[structopt(long)]
+		recipient: AccountId,
+		/// Amount of target tokens to send in target chain base currency units.
+		#[structopt(long)]
+		amount: Balance,
+	},
+	/// A call to the specific Bridge Messages pallet to queue message to be sent over a bridge.
+	BridgeSendMessage {
+		/// An index of the bridge instance which represents the expected target chain.
+		#[structopt(skip = 255)]
+		bridge_instance_index: u8,
+		/// Hex-encoded lane id that should be served by the relay. Defaults to `00000000`.
+		#[structopt(long, default_value = "00000000")]
+		lane: HexLaneId,
+		/// Raw SCALE-encoded Message Payload to submit to the messages pallet.
+		///
+		/// This can be obtained by encoding call for the target chain.
+		#[structopt(long)]
+		payload: HexBytes,
+		/// Declared delivery and dispatch fee in base source-chain currency units.
+		#[structopt(long)]
+		fee: Balance,
+	},
+}
+
+pub trait CliEncodeCall: Chain {
+	/// Maximal size (in bytes) of any extrinsic (from the runtime).
+	fn max_extrinsic_size() -> u32;
+
+	/// Encode a CLI call.
+	fn encode_call(call: &Call) -> anyhow::Result<Self::Call>;
+}
+
+impl EncodeCall {
+	fn encode(&mut self) -> anyhow::Result<HexBytes> {
+		select_full_bridge!(self.bridge, {
+			preprocess_call::<Source, Target>(&mut self.call, self.bridge.bridge_instance_index());
+			let call = Source::encode_call(&self.call)?;
+
+			let encoded = HexBytes::encode(&call);
+
+			log::info!(target: "bridge", "Generated {} call: {:#?}", Source::NAME, call);
+			log::info!(target: "bridge", "Weight of {} call: {}", Source::NAME, call.get_dispatch_info().weight);
+			log::info!(target: "bridge", "Encoded {} call: {:?}", Source::NAME, encoded);
+
+			Ok(encoded)
+		})
+	}
+
+	/// Run the command.
+	pub async fn run(mut self) -> anyhow::Result<()> {
+		println!("{:?}", self.encode()?);
+		Ok(())
+	}
+}
+
+/// Prepare the call to be passed to [`CliEncodeCall::encode_call`].
+///
+/// This function will fill in all optional and missing pieces and will make sure that
+/// values are converted to bridge-specific ones.
+///
+/// Most importantly, the method will fill-in [`bridge_instance_index`] parameter for
+/// target-chain specific calls.
+pub(crate) fn preprocess_call<Source: CliEncodeCall + CliChain, Target: CliEncodeCall>(
+	call: &mut Call,
+	bridge_instance: u8,
+) {
+	match *call {
+		Call::Raw { .. } => {}
+		Call::Remark {
+			ref remark_size,
+			ref mut remark_payload,
+		} => {
+			if remark_payload.is_none() {
+				*remark_payload = Some(HexBytes(generate_remark_payload(
+					&remark_size,
+					compute_maximal_message_arguments_size(Source::max_extrinsic_size(), Target::max_extrinsic_size()),
+				)));
+			}
+		}
+		Call::Transfer { ref mut recipient, .. } => {
+			recipient.enforce_chain::<Source>();
+		}
+		Call::BridgeSendMessage {
+			ref mut bridge_instance_index,
+			..
+		} => {
+			*bridge_instance_index = bridge_instance;
+		}
+	};
+}
+
+fn generate_remark_payload(remark_size: &Option<ExplicitOrMaximal<usize>>, maximal_allowed_size: u32) -> Vec<u8> {
+	match remark_size {
+		Some(ExplicitOrMaximal::Explicit(remark_size)) => vec![0; *remark_size],
+		Some(ExplicitOrMaximal::Maximal) => vec![0; maximal_allowed_size as _],
+		None => format!(
+			"Unix time: {}",
+			std::time::SystemTime::now()
+				.duration_since(std::time::SystemTime::UNIX_EPOCH)
+				.unwrap_or_default()
+				.as_secs(),
+		)
+		.as_bytes()
+		.to_vec(),
+	}
+}
+
+pub(crate) fn compute_maximal_message_arguments_size(
+	maximal_source_extrinsic_size: u32,
+	maximal_target_extrinsic_size: u32,
+) -> u32 {
+	// assume that both signed extensions and other arguments fit 1KB
+	let service_tx_bytes_on_source_chain = 1024;
+	let maximal_source_extrinsic_size = maximal_source_extrinsic_size - service_tx_bytes_on_source_chain;
+	let maximal_call_size =
+		bridge_runtime_common::messages::target::maximal_incoming_message_size(maximal_target_extrinsic_size);
+	let maximal_call_size = if maximal_call_size > maximal_source_extrinsic_size {
+		maximal_source_extrinsic_size
+	} else {
+		maximal_call_size
+	};
+
+	// bytes in Call encoding that are used to encode everything except arguments
+	let service_bytes = 1 + 1 + 4;
+	maximal_call_size - service_bytes
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+
+	#[test]
+	fn should_encode_transfer_call() {
+		// given
+		let mut encode_call = EncodeCall::from_iter(vec![
+			"encode-call",
+			"RialtoToMillau",
+			"transfer",
+			"--amount",
+			"12345",
+			"--recipient",
+			"5sauUXUfPjmwxSgmb3tZ5d6yx24eZX4wWJ2JtVUBaQqFbvEU",
+		]);
+
+		// when
+		let hex = encode_call.encode().unwrap();
+
+		// then
+		assert_eq!(
+			format!("{:?}", hex),
+			"0x0c00d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27de5c0"
+		);
+	}
+
+	#[test]
+	fn should_encode_remark_with_default_payload() {
+		// given
+		let mut encode_call = EncodeCall::from_iter(vec!["encode-call", "RialtoToMillau", "remark"]);
+
+		// when
+		let hex = encode_call.encode().unwrap();
+
+		// then
+		assert!(format!("{:?}", hex).starts_with("0x070154556e69782074696d653a"));
+	}
+
+	#[test]
+	fn should_encode_remark_with_explicit_payload() {
+		// given
+		let mut encode_call = EncodeCall::from_iter(vec![
+			"encode-call",
+			"RialtoToMillau",
+			"remark",
+			"--remark-payload",
+			"1234",
+		]);
+
+		// when
+		let hex = encode_call.encode().unwrap();
+
+		// then
+		assert_eq!(format!("{:?}", hex), "0x0701081234");
+	}
+
+	#[test]
+	fn should_encode_remark_with_size() {
+		// given
+		let mut encode_call =
+			EncodeCall::from_iter(vec!["encode-call", "RialtoToMillau", "remark", "--remark-size", "12"]);
+
+		// when
+		let hex = encode_call.encode().unwrap();
+
+		// then
+		assert_eq!(format!("{:?}", hex), "0x070130000000000000000000000000");
+	}
+
+	#[test]
+	fn should_disallow_both_payload_and_size() {
+		// when
+		let err = EncodeCall::from_iter_safe(vec![
+			"encode-call",
+			"RialtoToMillau",
+			"remark",
+			"--remark-payload",
+			"1234",
+			"--remark-size",
+			"12",
+		])
+		.unwrap_err();
+
+		// then
+		assert_eq!(err.kind, structopt::clap::ErrorKind::ArgumentConflict);
+
+		let info = err.info.unwrap();
+		assert!(info.contains(&"remark-payload".to_string()) | info.contains(&"remark-size".to_string()))
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/encode_message.rs

@@ -0,0 +1,106 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::{bridge::FullBridge, AccountId, CliChain, HexBytes};
+use crate::select_full_bridge;
+use structopt::StructOpt;
+
+/// Generic message payload.
+#[derive(StructOpt, Debug, PartialEq, Eq)]
+pub enum MessagePayload {
+	/// Raw, SCALE-encoded `MessagePayload`.
+	Raw {
+		/// Hex-encoded SCALE data.
+		data: HexBytes,
+	},
+	/// Construct message to send over the bridge.
+	Call {
+		/// Message details.
+		#[structopt(flatten)]
+		call: crate::cli::encode_call::Call,
+		/// SS58 encoded Source account that will send the payload.
+		#[structopt(long)]
+		sender: AccountId,
+	},
+}
+
+/// A `MessagePayload` to encode.
+#[derive(StructOpt)]
+pub struct EncodeMessage {
+	/// A bridge instance to initalize.
+	#[structopt(possible_values = &FullBridge::variants(), case_insensitive = true)]
+	bridge: FullBridge,
+	#[structopt(flatten)]
+	payload: MessagePayload,
+}
+
+impl EncodeMessage {
+	/// Run the command.
+	pub fn encode(self) -> anyhow::Result<HexBytes> {
+		select_full_bridge!(self.bridge, {
+			let payload = Source::encode_message(self.payload).map_err(|e| anyhow::format_err!("{}", e))?;
+			Ok(HexBytes::encode(&payload))
+		})
+	}
+
+	/// Run the command.
+	pub async fn run(self) -> anyhow::Result<()> {
+		let payload = self.encode()?;
+		println!("{:?}", payload);
+		Ok(())
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+	use sp_core::crypto::Ss58Codec;
+
+	#[test]
+	fn should_encode_raw_message() {
+		// given
+		let msg = "01000000e88514000000000002d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d3c040130000000000000000000000000";
+		let encode_message = EncodeMessage::from_iter(vec!["encode-message", "MillauToRialto", "raw", msg]);
+
+		// when
+		let hex = encode_message.encode().unwrap();
+
+		// then
+		assert_eq!(format!("{:?}", hex), format!("0x{}", msg));
+	}
+
+	#[test]
+	fn should_encode_remark_with_size() {
+		// given
+		let sender = sp_keyring::AccountKeyring::Alice.to_account_id().to_ss58check();
+		let encode_message = EncodeMessage::from_iter(vec![
+			"encode-message",
+			"RialtoToMillau",
+			"call",
+			"--sender",
+			&sender,
+			"remark",
+			"--remark-size",
+			"12",
+		]);
+
+		// when
+		let hex = encode_message.encode().unwrap();
+
+		// then
+		assert_eq!(format!("{:?}", hex), "0x01000000e88514000000000002d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d3c040130000000000000000000000000");
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/estimate_fee.rs

@@ -0,0 +1,128 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::bridge::FullBridge;
+use crate::cli::{Balance, CliChain, HexBytes, HexLaneId, SourceConnectionParams};
+use crate::select_full_bridge;
+use codec::{Decode, Encode};
+use relay_substrate_client::{Chain, ChainWithBalances};
+use structopt::StructOpt;
+
+/// Estimate Delivery & Dispatch Fee command.
+#[derive(StructOpt, Debug, PartialEq, Eq)]
+pub struct EstimateFee {
+	/// A bridge instance to encode call for.
+	#[structopt(possible_values = &FullBridge::variants(), case_insensitive = true)]
+	bridge: FullBridge,
+	#[structopt(flatten)]
+	source: SourceConnectionParams,
+	/// Hex-encoded id of lane that will be delivering the message.
+	#[structopt(long, default_value = "00000000")]
+	lane: HexLaneId,
+	/// Payload to send over the bridge.
+	#[structopt(flatten)]
+	payload: crate::cli::encode_message::MessagePayload,
+}
+
+impl EstimateFee {
+	/// Run the command.
+	pub async fn run(self) -> anyhow::Result<()> {
+		let Self {
+			source,
+			bridge,
+			lane,
+			payload,
+		} = self;
+
+		select_full_bridge!(bridge, {
+			let source_client = source.to_client::<Source>().await?;
+			let lane = lane.into();
+			let payload = Source::encode_message(payload).map_err(|e| anyhow::format_err!("{:?}", e))?;
+
+			let fee: <Source as ChainWithBalances>::NativeBalance =
+				estimate_message_delivery_and_dispatch_fee(&source_client, ESTIMATE_MESSAGE_FEE_METHOD, lane, payload)
+					.await?;
+
+			log::info!(target: "bridge", "Fee: {:?}", Balance(fee as _));
+			println!("{}", fee);
+			Ok(())
+		})
+	}
+}
+
+pub(crate) async fn estimate_message_delivery_and_dispatch_fee<Fee: Decode, C: Chain, P: Encode>(
+	client: &relay_substrate_client::Client<C>,
+	estimate_fee_method: &str,
+	lane: bp_messages::LaneId,
+	payload: P,
+) -> anyhow::Result<Fee> {
+	let encoded_response = client
+		.state_call(estimate_fee_method.into(), (lane, payload).encode().into(), None)
+		.await?;
+	let decoded_response: Option<Fee> =
+		Decode::decode(&mut &encoded_response.0[..]).map_err(relay_substrate_client::Error::ResponseParseFailed)?;
+	let fee = decoded_response
+		.ok_or_else(|| anyhow::format_err!("Unable to decode fee from: {:?}", HexBytes(encoded_response.to_vec())))?;
+	Ok(fee)
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+	use crate::cli::encode_call;
+	use sp_core::crypto::Ss58Codec;
+
+	#[test]
+	fn should_parse_cli_options() {
+		// given
+		let alice = sp_keyring::AccountKeyring::Alice.to_account_id().to_ss58check();
+
+		// when
+		let res = EstimateFee::from_iter(vec![
+			"estimate_fee",
+			"RialtoToMillau",
+			"--source-port",
+			"1234",
+			"call",
+			"--sender",
+			&alice,
+			"remark",
+			"--remark-payload",
+			"1234",
+		]);
+
+		// then
+		assert_eq!(
+			res,
+			EstimateFee {
+				bridge: FullBridge::RialtoToMillau,
+				lane: HexLaneId([0, 0, 0, 0]),
+				source: SourceConnectionParams {
+					source_host: "127.0.0.1".into(),
+					source_port: 1234,
+					source_secure: false,
+				},
+				payload: crate::cli::encode_message::MessagePayload::Call {
+					sender: alice.parse().unwrap(),
+					call: encode_call::Call::Remark {
+						remark_payload: Some(HexBytes(vec![0x12, 0x34])),
+						remark_size: None,
+					}
+				}
+			}
+		);
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/init_bridge.rs

@@ -0,0 +1,162 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::{SourceConnectionParams, TargetConnectionParams, TargetSigningParams};
+use bp_header_chain::InitializationData;
+use bp_runtime::Chain as ChainBase;
+use codec::Encode;
+use relay_substrate_client::{Chain, TransactionSignScheme};
+use sp_core::{Bytes, Pair};
+use structopt::{clap::arg_enum, StructOpt};
+
+/// Initialize bridge pallet.
+#[derive(StructOpt)]
+pub struct InitBridge {
+	/// A bridge instance to initalize.
+	#[structopt(possible_values = &InitBridgeName::variants(), case_insensitive = true)]
+	bridge: InitBridgeName,
+	#[structopt(flatten)]
+	source: SourceConnectionParams,
+	#[structopt(flatten)]
+	target: TargetConnectionParams,
+	#[structopt(flatten)]
+	target_sign: TargetSigningParams,
+}
+
+// TODO [#851] Use kebab-case.
+arg_enum! {
+	#[derive(Debug)]
+	/// Bridge to initialize.
+	pub enum InitBridgeName {
+		MillauToRialto,
+		RialtoToMillau,
+		WestendToMillau,
+		WestendToRococo,
+		RococoToWestend,
+	}
+}
+
+macro_rules! select_bridge {
+	($bridge: expr, $generic: tt) => {
+		match $bridge {
+			InitBridgeName::MillauToRialto => {
+				type Source = relay_millau_client::Millau;
+				type Target = relay_rialto_client::Rialto;
+
+				fn encode_init_bridge(
+					init_data: InitializationData<<Source as ChainBase>::Header>,
+				) -> <Target as Chain>::Call {
+					rialto_runtime::SudoCall::sudo(Box::new(
+						rialto_runtime::BridgeGrandpaMillauCall::initialize(init_data).into(),
+					))
+					.into()
+				}
+
+				$generic
+			}
+			InitBridgeName::RialtoToMillau => {
+				type Source = relay_rialto_client::Rialto;
+				type Target = relay_millau_client::Millau;
+
+				fn encode_init_bridge(
+					init_data: InitializationData<<Source as ChainBase>::Header>,
+				) -> <Target as Chain>::Call {
+					let initialize_call = millau_runtime::BridgeGrandpaRialtoCall::<
+						millau_runtime::Runtime,
+						millau_runtime::RialtoGrandpaInstance,
+					>::initialize(init_data);
+					millau_runtime::SudoCall::sudo(Box::new(initialize_call.into())).into()
+				}
+
+				$generic
+			}
+			InitBridgeName::WestendToMillau => {
+				type Source = relay_westend_client::Westend;
+				type Target = relay_millau_client::Millau;
+
+				fn encode_init_bridge(
+					init_data: InitializationData<<Source as ChainBase>::Header>,
+				) -> <Target as Chain>::Call {
+					// at Westend -> Millau initialization we're not using sudo, because otherwise our deployments
+					// may fail, because we need to initialize both Rialto -> Millau and Westend -> Millau bridge.
+					// => since there's single possible sudo account, one of transaction may fail with duplicate nonce error
+					millau_runtime::BridgeGrandpaWestendCall::<
+						millau_runtime::Runtime,
+						millau_runtime::WestendGrandpaInstance,
+					>::initialize(init_data)
+					.into()
+				}
+
+				$generic
+			}
+			InitBridgeName::WestendToRococo => {
+				type Source = relay_westend_client::Westend;
+				type Target = relay_rococo_client::Rococo;
+
+				fn encode_init_bridge(
+					init_data: InitializationData<<Source as ChainBase>::Header>,
+				) -> <Target as Chain>::Call {
+					bp_rococo::Call::BridgeGrandpaWestend(bp_rococo::BridgeGrandpaWestendCall::initialize(init_data))
+				}
+
+				$generic
+			}
+			InitBridgeName::RococoToWestend => {
+				type Source = relay_rococo_client::Rococo;
+				type Target = relay_westend_client::Westend;
+
+				fn encode_init_bridge(
+					init_data: InitializationData<<Source as ChainBase>::Header>,
+				) -> <Target as Chain>::Call {
+					bp_westend::Call::BridgeGrandpaRococo(bp_westend::BridgeGrandpaRococoCall::initialize(init_data))
+				}
+
+				$generic
+			}
+		}
+	};
+}
+
+impl InitBridge {
+	/// Run the command.
+	pub async fn run(self) -> anyhow::Result<()> {
+		select_bridge!(self.bridge, {
+			let source_client = self.source.to_client::<Source>().await?;
+			let target_client = self.target.to_client::<Target>().await?;
+			let target_sign = self.target_sign.to_keypair::<Target>()?;
+
+			crate::headers_initialize::initialize(
+				source_client,
+				target_client.clone(),
+				target_sign.public().into(),
+				move |transaction_nonce, initialization_data| {
+					Bytes(
+						Target::sign_transaction(
+							*target_client.genesis_hash(),
+							&target_sign,
+							transaction_nonce,
+							encode_init_bridge(initialization_data),
+						)
+						.encode(),
+					)
+				},
+			)
+			.await;
+
+			Ok(())
+		})
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/mod.rs

@@ -0,0 +1,444 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Deal with CLI args of substrate-to-substrate relay.
+
+use std::convert::TryInto;
+
+use bp_messages::LaneId;
+use codec::{Decode, Encode};
+use frame_support::weights::Weight;
+use sp_runtime::app_crypto::Ss58Codec;
+use structopt::{clap::arg_enum, StructOpt};
+
+pub(crate) mod bridge;
+pub(crate) mod encode_call;
+pub(crate) mod encode_message;
+pub(crate) mod estimate_fee;
+pub(crate) mod send_message;
+
+mod derive_account;
+mod init_bridge;
+mod relay_headers;
+mod relay_headers_and_messages;
+mod relay_messages;
+
+/// Parse relay CLI args.
+pub fn parse_args() -> Command {
+	Command::from_args()
+}
+
+/// Substrate-to-Substrate bridge utilities.
+#[derive(StructOpt)]
+#[structopt(about = "Substrate-to-Substrate relay")]
+pub enum Command {
+	/// Start headers relay between two chains.
+	///
+	/// The on-chain bridge component should have been already initialized with
+	/// `init-bridge` sub-command.
+	RelayHeaders(relay_headers::RelayHeaders),
+	/// Start messages relay between two chains.
+	///
+	/// Ties up to `Messages` pallets on both chains and starts relaying messages.
+	/// Requires the header relay to be already running.
+	RelayMessages(relay_messages::RelayMessages),
+	/// Start headers and messages relay between two Substrate chains.
+	///
+	/// This high-level relay internally starts four low-level relays: two `RelayHeaders`
+	/// and two `RelayMessages` relays. Headers are only relayed when they are required by
+	/// the message relays - i.e. when there are messages or confirmations that needs to be
+	/// relayed between chains.
+	RelayHeadersAndMessages(relay_headers_and_messages::RelayHeadersAndMessages),
+	/// Initialize on-chain bridge pallet with current header data.
+	///
+	/// Sends initialization transaction to bootstrap the bridge with current finalized block data.
+	InitBridge(init_bridge::InitBridge),
+	/// Send custom message over the bridge.
+	///
+	/// Allows interacting with the bridge by sending messages over `Messages` component.
+	/// The message is being sent to the source chain, delivered to the target chain and dispatched
+	/// there.
+	SendMessage(send_message::SendMessage),
+	/// Generate SCALE-encoded `Call` for choosen network.
+	///
+	/// The call can be used either as message payload or can be wrapped into a transaction
+	/// and executed on the chain directly.
+	EncodeCall(encode_call::EncodeCall),
+	/// Generate SCALE-encoded `MessagePayload` object that can be sent over selected bridge.
+	///
+	/// The `MessagePayload` can be then fed to `Messages::send_message` function and sent over
+	/// the bridge.
+	EncodeMessage(encode_message::EncodeMessage),
+	/// Estimate Delivery and Dispatch Fee required for message submission to messages pallet.
+	EstimateFee(estimate_fee::EstimateFee),
+	/// Given a source chain `AccountId`, derive the corresponding `AccountId` for the target chain.
+	DeriveAccount(derive_account::DeriveAccount),
+}
+
+impl Command {
+	/// Run the command.
+	pub async fn run(self) -> anyhow::Result<()> {
+		match self {
+			Self::RelayHeaders(arg) => arg.run().await?,
+			Self::RelayMessages(arg) => arg.run().await?,
+			Self::RelayHeadersAndMessages(arg) => arg.run().await?,
+			Self::InitBridge(arg) => arg.run().await?,
+			Self::SendMessage(arg) => arg.run().await?,
+			Self::EncodeCall(arg) => arg.run().await?,
+			Self::EncodeMessage(arg) => arg.run().await?,
+			Self::EstimateFee(arg) => arg.run().await?,
+			Self::DeriveAccount(arg) => arg.run().await?,
+		}
+		Ok(())
+	}
+}
+
+arg_enum! {
+	#[derive(Debug)]
+	/// The origin to use when dispatching the message on the target chain.
+	///
+	/// - `Target` uses account existing on the target chain (requires target private key).
+	/// - `Origin` uses account derived from the source-chain account.
+	pub enum Origins {
+		Target,
+		Source,
+	}
+}
+
+/// Generic balance type.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Balance(pub u128);
+
+impl std::fmt::Display for Balance {
+	fn fmt(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
+		use num_format::{Locale, ToFormattedString};
+		write!(fmt, "{}", self.0.to_formatted_string(&Locale::en))
+	}
+}
+
+impl std::str::FromStr for Balance {
+	type Err = <u128 as std::str::FromStr>::Err;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		Ok(Self(s.parse()?))
+	}
+}
+
+impl Balance {
+	/// Cast balance to `u64` type, panicking if it's too large.
+	pub fn cast(&self) -> u64 {
+		self.0.try_into().expect("Balance is too high for this chain.")
+	}
+}
+
+/// Generic account id with custom parser.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountId {
+	account: sp_runtime::AccountId32,
+	ss58_format: sp_core::crypto::Ss58AddressFormat,
+}
+
+impl std::fmt::Display for AccountId {
+	fn fmt(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
+		write!(fmt, "{}", self.account.to_ss58check_with_version(self.ss58_format))
+	}
+}
+
+impl std::str::FromStr for AccountId {
+	type Err = String;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		let (account, ss58_format) = sp_runtime::AccountId32::from_ss58check_with_version(s)
+			.map_err(|err| format!("Unable to decode SS58 address: {:?}", err))?;
+		Ok(Self { account, ss58_format })
+	}
+}
+
+const SS58_FORMAT_PROOF: &str = "u16 -> Ss58Format is infallible; qed";
+
+impl AccountId {
+	/// Create new SS58-formatted address from raw account id.
+	pub fn from_raw<T: CliChain>(account: sp_runtime::AccountId32) -> Self {
+		Self {
+			account,
+			ss58_format: T::ss58_format().try_into().expect(SS58_FORMAT_PROOF),
+		}
+	}
+
+	/// Enforces formatting account to be for given [`CliChain`] type.
+	///
+	/// This will change the `ss58format` of the account to match the requested one.
+	/// Note that a warning will be produced in case the current format does not match
+	/// the requested one, but the conversion always succeeds.
+	pub fn enforce_chain<T: CliChain>(&mut self) {
+		let original = self.clone();
+		self.ss58_format = T::ss58_format().try_into().expect(SS58_FORMAT_PROOF);
+		log::debug!("{} SS58 format: {} (RAW: {})", self, self.ss58_format, self.account);
+		if original.ss58_format != self.ss58_format {
+			log::warn!(
+				target: "bridge",
+				"Address {} does not seem to match {}'s SS58 format (got: {}, expected: {}).\nConverted to: {}",
+				original,
+				T::NAME,
+				original.ss58_format,
+				self.ss58_format,
+				self,
+			)
+		}
+	}
+
+	/// Returns the raw (no SS58-prefixed) account id.
+	pub fn raw_id(&self) -> sp_runtime::AccountId32 {
+		self.account.clone()
+	}
+}
+
+/// Bridge-supported network definition.
+///
+/// Used to abstract away CLI commands.
+pub trait CliChain: relay_substrate_client::Chain {
+	/// Chain's current version of the runtime.
+	const RUNTIME_VERSION: sp_version::RuntimeVersion;
+
+	/// Crypto keypair type used to send messages.
+	///
+	/// In case of chains supporting multiple cryptos, pick one used by the CLI.
+	type KeyPair: sp_core::crypto::Pair;
+
+	/// Bridge Message Payload type.
+	///
+	/// TODO [#854] This should be removed in favour of target-specifc types.
+	type MessagePayload;
+
+	/// Numeric value of SS58 format.
+	fn ss58_format() -> u16;
+
+	/// Construct message payload to be sent over the bridge.
+	fn encode_message(message: crate::cli::encode_message::MessagePayload) -> Result<Self::MessagePayload, String>;
+
+	/// Maximal extrinsic weight (from the runtime).
+	fn max_extrinsic_weight() -> Weight;
+}
+
+/// Lane id.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HexLaneId(pub LaneId);
+
+impl From<HexLaneId> for LaneId {
+	fn from(lane_id: HexLaneId) -> LaneId {
+		lane_id.0
+	}
+}
+
+impl std::str::FromStr for HexLaneId {
+	type Err = hex::FromHexError;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		let mut lane_id = LaneId::default();
+		hex::decode_to_slice(s, &mut lane_id)?;
+		Ok(HexLaneId(lane_id))
+	}
+}
+
+/// Nicer formatting for raw bytes vectors.
+#[derive(Default, Encode, Decode, PartialEq, Eq)]
+pub struct HexBytes(pub Vec<u8>);
+
+impl std::str::FromStr for HexBytes {
+	type Err = hex::FromHexError;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		Ok(Self(hex::decode(s)?))
+	}
+}
+
+impl std::fmt::Debug for HexBytes {
+	fn fmt(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
+		write!(fmt, "0x{}", self)
+	}
+}
+
+impl std::fmt::Display for HexBytes {
+	fn fmt(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
+		write!(fmt, "{}", hex::encode(&self.0))
+	}
+}
+
+impl HexBytes {
+	/// Encode given object and wrap into nicely formatted bytes.
+	pub fn encode<T: Encode>(t: &T) -> Self {
+		Self(t.encode())
+	}
+}
+
+/// Prometheus metrics params.
+#[derive(StructOpt)]
+pub struct PrometheusParams {
+	/// Do not expose a Prometheus metric endpoint.
+	#[structopt(long)]
+	pub no_prometheus: bool,
+	/// Expose Prometheus endpoint at given interface.
+	#[structopt(long, default_value = "127.0.0.1")]
+	pub prometheus_host: String,
+	/// Expose Prometheus endpoint at given port.
+	#[structopt(long, default_value = "9616")]
+	pub prometheus_port: u16,
+}
+
+impl From<PrometheusParams> for relay_utils::metrics::MetricsParams {
+	fn from(cli_params: PrometheusParams) -> relay_utils::metrics::MetricsParams {
+		if !cli_params.no_prometheus {
+			Some(relay_utils::metrics::MetricsAddress {
+				host: cli_params.prometheus_host,
+				port: cli_params.prometheus_port,
+			})
+			.into()
+		} else {
+			None.into()
+		}
+	}
+}
+
+/// Either explicit or maximal allowed value.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ExplicitOrMaximal<V> {
+	/// User has explicitly specified argument value.
+	Explicit(V),
+	/// Maximal allowed value for this argument.
+	Maximal,
+}
+
+impl<V: std::str::FromStr> std::str::FromStr for ExplicitOrMaximal<V>
+where
+	V::Err: std::fmt::Debug,
+{
+	type Err = String;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		if s.to_lowercase() == "max" {
+			return Ok(ExplicitOrMaximal::Maximal);
+		}
+
+		V::from_str(s)
+			.map(ExplicitOrMaximal::Explicit)
+			.map_err(|e| format!("Failed to parse '{:?}'. Expected 'max' or explicit value", e))
+	}
+}
+
+/// Create chain-specific set of configuration objects: connection parameters,
+/// signing parameters and bridge initialisation parameters.
+#[macro_export]
+macro_rules! declare_chain_options {
+	($chain:ident, $chain_prefix:ident) => {
+		paste::item! {
+			#[doc = $chain " connection params."]
+			#[derive(StructOpt, Debug, PartialEq, Eq)]
+			pub struct [<$chain ConnectionParams>] {
+				#[doc = "Connect to " $chain " node at given host."]
+				#[structopt(long, default_value = "127.0.0.1")]
+				pub [<$chain_prefix _host>]: String,
+				#[doc = "Connect to " $chain " node websocket server at given port."]
+				#[structopt(long)]
+				pub [<$chain_prefix _port>]: u16,
+				#[doc = "Use secure websocket connection."]
+				#[structopt(long)]
+				pub [<$chain_prefix _secure>]: bool,
+			}
+
+			#[doc = $chain " signing params."]
+			#[derive(StructOpt, Debug, PartialEq, Eq)]
+			pub struct [<$chain SigningParams>] {
+				#[doc = "The SURI of secret key to use when transactions are submitted to the " $chain " node."]
+				#[structopt(long)]
+				pub [<$chain_prefix _signer>]: String,
+				#[doc = "The password for the SURI of secret key to use when transactions are submitted to the " $chain " node."]
+				#[structopt(long)]
+				pub [<$chain_prefix _signer_password>]: Option<String>,
+			}
+
+			impl [<$chain SigningParams>] {
+				/// Parse signing params into chain-specific KeyPair.
+				pub fn to_keypair<Chain: CliChain>(&self) -> anyhow::Result<Chain::KeyPair> {
+					use sp_core::crypto::Pair;
+
+					Chain::KeyPair::from_string(
+						&self.[<$chain_prefix _signer>],
+						self.[<$chain_prefix _signer_password>].as_deref()
+					).map_err(|e| anyhow::format_err!("{:?}", e))
+				}
+			}
+
+			impl [<$chain ConnectionParams>] {
+				/// Convert connection params into Substrate client.
+				pub async fn to_client<Chain: CliChain>(
+					&self,
+				) -> anyhow::Result<relay_substrate_client::Client<Chain>> {
+					Ok(relay_substrate_client::Client::new(relay_substrate_client::ConnectionParams {
+						host: self.[<$chain_prefix _host>].clone(),
+						port: self.[<$chain_prefix _port>],
+						secure: self.[<$chain_prefix _secure>],
+					})
+					.await?
+					)
+				}
+			}
+		}
+	};
+}
+
+declare_chain_options!(Source, source);
+declare_chain_options!(Target, target);
+
+#[cfg(test)]
+mod tests {
+	use std::str::FromStr;
+
+	use super::*;
+
+	#[test]
+	fn should_format_addresses_with_ss58_format() {
+		// given
+		let rialto1 = "5sauUXUfPjmwxSgmb3tZ5d6yx24eZX4wWJ2JtVUBaQqFbvEU";
+		let rialto2 = "5rERgaT1Z8nM3et2epA5i1VtEBfp5wkhwHtVE8HK7BRbjAH2";
+		let millau1 = "752paRyW1EGfq9YLTSSqcSJ5hqnBDidBmaftGhBo8fy6ypW9";
+		let millau2 = "74GNQjmkcfstRftSQPJgMREchqHM56EvAUXRc266cZ1NYVW5";
+
+		let expected = vec![rialto1, rialto2, millau1, millau2];
+
+		// when
+		let parsed = expected
+			.iter()
+			.map(|s| AccountId::from_str(s).unwrap())
+			.collect::<Vec<_>>();
+
+		let actual = parsed.iter().map(|a| format!("{}", a)).collect::<Vec<_>>();
+
+		assert_eq!(actual, expected)
+	}
+
+	#[test]
+	fn hex_bytes_display_matches_from_str_for_clap() {
+		// given
+		let hex = HexBytes(vec![1, 2, 3, 4]);
+		let display = format!("{}", hex);
+
+		// when
+		let hex2: HexBytes = display.parse().unwrap();
+
+		// then
+		assert_eq!(hex.0, hex2.0);
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/relay_headers.rs

@@ -0,0 +1,110 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::{PrometheusParams, SourceConnectionParams, TargetConnectionParams, TargetSigningParams};
+use crate::finality_pipeline::SubstrateFinalitySyncPipeline;
+use structopt::{clap::arg_enum, StructOpt};
+
+/// Start headers relayer process.
+#[derive(StructOpt)]
+pub struct RelayHeaders {
+	/// A bridge instance to relay headers for.
+	#[structopt(possible_values = &RelayHeadersBridge::variants(), case_insensitive = true)]
+	bridge: RelayHeadersBridge,
+	#[structopt(flatten)]
+	source: SourceConnectionParams,
+	#[structopt(flatten)]
+	target: TargetConnectionParams,
+	#[structopt(flatten)]
+	target_sign: TargetSigningParams,
+	#[structopt(flatten)]
+	prometheus_params: PrometheusParams,
+}
+
+// TODO [#851] Use kebab-case.
+arg_enum! {
+	#[derive(Debug)]
+	/// Headers relay bridge.
+	pub enum RelayHeadersBridge {
+		MillauToRialto,
+		RialtoToMillau,
+		WestendToMillau,
+		WestendToRococo,
+		RococoToWestend,
+	}
+}
+
+macro_rules! select_bridge {
+	($bridge: expr, $generic: tt) => {
+		match $bridge {
+			RelayHeadersBridge::MillauToRialto => {
+				type Source = relay_millau_client::Millau;
+				type Target = relay_rialto_client::Rialto;
+				type Finality = crate::chains::millau_headers_to_rialto::MillauFinalityToRialto;
+
+				$generic
+			}
+			RelayHeadersBridge::RialtoToMillau => {
+				type Source = relay_rialto_client::Rialto;
+				type Target = relay_millau_client::Millau;
+				type Finality = crate::chains::rialto_headers_to_millau::RialtoFinalityToMillau;
+
+				$generic
+			}
+			RelayHeadersBridge::WestendToMillau => {
+				type Source = relay_westend_client::Westend;
+				type Target = relay_millau_client::Millau;
+				type Finality = crate::chains::westend_headers_to_millau::WestendFinalityToMillau;
+
+				$generic
+			}
+			RelayHeadersBridge::WestendToRococo => {
+				type Source = relay_westend_client::Westend;
+				type Target = relay_rococo_client::Rococo;
+				type Finality = crate::chains::westend_headers_to_rococo::WestendFinalityToRococo;
+
+				$generic
+			}
+			RelayHeadersBridge::RococoToWestend => {
+				type Source = relay_rococo_client::Rococo;
+				type Target = relay_westend_client::Westend;
+				type Finality = crate::chains::rococo_headers_to_westend::RococoFinalityToWestend;
+
+				$generic
+			}
+		}
+	};
+}
+
+impl RelayHeaders {
+	/// Run the command.
+	pub async fn run(self) -> anyhow::Result<()> {
+		select_bridge!(self.bridge, {
+			let source_client = self.source.to_client::<Source>().await?;
+			let target_client = self.target.to_client::<Target>().await?;
+			let target_sign = self.target_sign.to_keypair::<Target>()?;
+			let metrics_params = Finality::customize_metrics(self.prometheus_params.into())?;
+
+			crate::finality_pipeline::run(
+				Finality::new(target_client.clone(), target_sign),
+				source_client,
+				target_client,
+				metrics_params,
+			)
+			.await
+		})
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/relay_headers_and_messages.rs

@@ -0,0 +1,183 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Complex headers+messages relays support.
+//!
+//! To add new complex relay between `ChainA` and `ChainB`, you must:
+//!
+//! 1) ensure that there's a `declare_chain_options!(...)` for both chains;
+//! 2) add `declare_bridge_options!(...)` for the bridge;
+//! 3) add bridge support to the `select_bridge! { ... }` macro.
+
+use crate::cli::{CliChain, HexLaneId, PrometheusParams};
+use crate::declare_chain_options;
+use crate::messages_lane::MessagesRelayParams;
+use crate::on_demand_headers::OnDemandHeadersRelay;
+
+use futures::{FutureExt, TryFutureExt};
+use relay_utils::metrics::MetricsParams;
+use structopt::StructOpt;
+
+/// Start headers+messages relayer process.
+#[derive(StructOpt)]
+pub enum RelayHeadersAndMessages {
+	MillauRialto(MillauRialtoHeadersAndMessages),
+}
+
+/// Parameters that have the same names across all bridges.
+#[derive(StructOpt)]
+pub struct HeadersAndMessagesSharedParams {
+	/// Hex-encoded lane id that should be served by the relay. Defaults to `00000000`.
+	#[structopt(long, default_value = "00000000")]
+	lane: HexLaneId,
+	#[structopt(flatten)]
+	prometheus_params: PrometheusParams,
+}
+
+// The reason behind this macro is that 'normal' relays are using source and target chains terminology,
+// which is unusable for both-way relays (if you're relaying headers from Rialto to Millau and from
+// Millau to Rialto, then which chain is source?).
+macro_rules! declare_bridge_options {
+	($chain1:ident, $chain2:ident) => {
+		paste::item! {
+			#[doc = $chain1 " and " $chain2 " headers+messages relay params."]
+			#[derive(StructOpt)]
+			pub struct [<$chain1 $chain2 HeadersAndMessages>] {
+				#[structopt(flatten)]
+				shared: HeadersAndMessagesSharedParams,
+				#[structopt(flatten)]
+				left: [<$chain1 ConnectionParams>],
+				#[structopt(flatten)]
+				left_sign: [<$chain1 SigningParams>],
+				#[structopt(flatten)]
+				right: [<$chain2 ConnectionParams>],
+				#[structopt(flatten)]
+				right_sign: [<$chain2 SigningParams>],
+			}
+
+			#[allow(unreachable_patterns)]
+			impl From<RelayHeadersAndMessages> for [<$chain1 $chain2 HeadersAndMessages>] {
+				fn from(relay_params: RelayHeadersAndMessages) -> [<$chain1 $chain2 HeadersAndMessages>] {
+					match relay_params {
+						RelayHeadersAndMessages::[<$chain1 $chain2>](params) => params,
+						_ => unreachable!(),
+					}
+				}
+			}
+		}
+	};
+}
+
+macro_rules! select_bridge {
+	($bridge: expr, $generic: tt) => {
+		match $bridge {
+			RelayHeadersAndMessages::MillauRialto(_) => {
+				type Params = MillauRialtoHeadersAndMessages;
+
+				type Left = relay_millau_client::Millau;
+				type Right = relay_rialto_client::Rialto;
+
+				type LeftToRightFinality = crate::chains::millau_headers_to_rialto::MillauFinalityToRialto;
+				type RightToLeftFinality = crate::chains::rialto_headers_to_millau::RialtoFinalityToMillau;
+
+				type LeftToRightMessages = crate::chains::millau_messages_to_rialto::MillauMessagesToRialto;
+				type RightToLeftMessages = crate::chains::rialto_messages_to_millau::RialtoMessagesToMillau;
+
+				use crate::chains::millau_messages_to_rialto::run as left_to_right_messages;
+				use crate::chains::rialto_messages_to_millau::run as right_to_left_messages;
+
+				$generic
+			}
+		}
+	};
+}
+
+// All supported chains.
+declare_chain_options!(Millau, millau);
+declare_chain_options!(Rialto, rialto);
+// All supported bridges.
+declare_bridge_options!(Millau, Rialto);
+
+impl RelayHeadersAndMessages {
+	/// Run the command.
+	pub async fn run(self) -> anyhow::Result<()> {
+		select_bridge!(self, {
+			let params: Params = self.into();
+
+			let left_client = params.left.to_client::<Left>().await?;
+			let left_sign = params.left_sign.to_keypair::<Left>()?;
+			let right_client = params.right.to_client::<Right>().await?;
+			let right_sign = params.right_sign.to_keypair::<Right>()?;
+
+			let lane = params.shared.lane.into();
+
+			let metrics_params: MetricsParams = params.shared.prometheus_params.into();
+			let metrics_params = relay_utils::relay_metrics(None, metrics_params).into_params();
+
+			let left_to_right_on_demand_headers = OnDemandHeadersRelay::new(
+				left_client.clone(),
+				right_client.clone(),
+				LeftToRightFinality::new(right_client.clone(), right_sign.clone()),
+			);
+			let right_to_left_on_demand_headers = OnDemandHeadersRelay::new(
+				right_client.clone(),
+				left_client.clone(),
+				RightToLeftFinality::new(left_client.clone(), left_sign.clone()),
+			);
+
+			let left_to_right_messages = left_to_right_messages(MessagesRelayParams {
+				source_client: left_client.clone(),
+				source_sign: left_sign.clone(),
+				target_client: right_client.clone(),
+				target_sign: right_sign.clone(),
+				source_to_target_headers_relay: Some(left_to_right_on_demand_headers.clone()),
+				target_to_source_headers_relay: Some(right_to_left_on_demand_headers.clone()),
+				lane_id: lane,
+				metrics_params: metrics_params
+					.clone()
+					.disable()
+					.metrics_prefix(messages_relay::message_lane_loop::metrics_prefix::<LeftToRightMessages>(&lane)),
+			})
+			.map_err(|e| anyhow::format_err!("{}", e))
+			.boxed();
+			let right_to_left_messages = right_to_left_messages(MessagesRelayParams {
+				source_client: right_client,
+				source_sign: right_sign,
+				target_client: left_client.clone(),
+				target_sign: left_sign.clone(),
+				source_to_target_headers_relay: Some(right_to_left_on_demand_headers),
+				target_to_source_headers_relay: Some(left_to_right_on_demand_headers),
+				lane_id: lane,
+				metrics_params: metrics_params
+					.clone()
+					.disable()
+					.metrics_prefix(messages_relay::message_lane_loop::metrics_prefix::<RightToLeftMessages>(&lane)),
+			})
+			.map_err(|e| anyhow::format_err!("{}", e))
+			.boxed();
+
+			relay_utils::relay_metrics(None, metrics_params)
+				.expose()
+				.await
+				.map_err(|e| anyhow::format_err!("{}", e))?;
+
+			futures::future::select(left_to_right_messages, right_to_left_messages)
+				.await
+				.factor_first()
+				.0
+		})
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/relay_messages.rs

@@ -0,0 +1,71 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::bridge::FullBridge;
+use crate::cli::{
+	HexLaneId, PrometheusParams, SourceConnectionParams, SourceSigningParams, TargetConnectionParams,
+	TargetSigningParams,
+};
+use crate::messages_lane::MessagesRelayParams;
+use crate::select_full_bridge;
+
+use structopt::StructOpt;
+
+/// Start messages relayer process.
+#[derive(StructOpt)]
+pub struct RelayMessages {
+	/// A bridge instance to relay messages for.
+	#[structopt(possible_values = &FullBridge::variants(), case_insensitive = true)]
+	bridge: FullBridge,
+	/// Hex-encoded lane id that should be served by the relay. Defaults to `00000000`.
+	#[structopt(long, default_value = "00000000")]
+	lane: HexLaneId,
+	#[structopt(flatten)]
+	source: SourceConnectionParams,
+	#[structopt(flatten)]
+	source_sign: SourceSigningParams,
+	#[structopt(flatten)]
+	target: TargetConnectionParams,
+	#[structopt(flatten)]
+	target_sign: TargetSigningParams,
+	#[structopt(flatten)]
+	prometheus_params: PrometheusParams,
+}
+
+impl RelayMessages {
+	/// Run the command.
+	pub async fn run(self) -> anyhow::Result<()> {
+		select_full_bridge!(self.bridge, {
+			let source_client = self.source.to_client::<Source>().await?;
+			let source_sign = self.source_sign.to_keypair::<Source>()?;
+			let target_client = self.target.to_client::<Target>().await?;
+			let target_sign = self.target_sign.to_keypair::<Target>()?;
+
+			relay_messages(MessagesRelayParams {
+				source_client,
+				source_sign,
+				target_client,
+				target_sign,
+				source_to_target_headers_relay: None,
+				target_to_source_headers_relay: None,
+				lane_id: self.lane.into(),
+				metrics_params: self.prometheus_params.into(),
+			})
+			.await
+			.map_err(|e| anyhow::format_err!("{}", e))
+		})
+	}
+}

polkadot/bridges/relays/bin-substrate/src/cli/send_message.rs

@@ -0,0 +1,317 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::cli::bridge::FullBridge;
+use crate::cli::encode_call::{self, CliEncodeCall};
+use crate::cli::estimate_fee::estimate_message_delivery_and_dispatch_fee;
+use crate::cli::{
+	Balance, CliChain, ExplicitOrMaximal, HexBytes, HexLaneId, Origins, SourceConnectionParams, SourceSigningParams,
+	TargetSigningParams,
+};
+use codec::Encode;
+use frame_support::{dispatch::GetDispatchInfo, weights::Weight};
+use pallet_bridge_dispatch::{CallOrigin, MessagePayload};
+use relay_substrate_client::{Chain, TransactionSignScheme};
+use sp_core::{Bytes, Pair};
+use sp_runtime::{traits::IdentifyAccount, AccountId32, MultiSignature, MultiSigner};
+use std::fmt::Debug;
+use structopt::StructOpt;
+
+/// Send bridge message.
+#[derive(StructOpt)]
+pub struct SendMessage {
+	/// A bridge instance to encode call for.
+	#[structopt(possible_values = &FullBridge::variants(), case_insensitive = true)]
+	bridge: FullBridge,
+	#[structopt(flatten)]
+	source: SourceConnectionParams,
+	#[structopt(flatten)]
+	source_sign: SourceSigningParams,
+	// TODO [#885] Move TargetSign to origins
+	#[structopt(flatten)]
+	target_sign: TargetSigningParams,
+	/// Hex-encoded lane id. Defaults to `00000000`.
+	#[structopt(long, default_value = "00000000")]
+	lane: HexLaneId,
+	/// Dispatch weight of the message. If not passed, determined automatically.
+	#[structopt(long)]
+	dispatch_weight: Option<ExplicitOrMaximal<Weight>>,
+	/// Delivery and dispatch fee in source chain base currency units. If not passed, determined automatically.
+	#[structopt(long)]
+	fee: Option<Balance>,
+	/// Message type.
+	#[structopt(subcommand)]
+	message: crate::cli::encode_call::Call,
+	/// The origin to use when dispatching the message on the target chain. Defaults to
+	/// `SourceAccount`.
+	#[structopt(long, possible_values = &Origins::variants(), default_value = "Source")]
+	origin: Origins,
+}
+
+impl SendMessage {
+	pub fn encode_payload(
+		&mut self,
+	) -> anyhow::Result<MessagePayload<AccountId32, MultiSigner, MultiSignature, Vec<u8>>> {
+		crate::select_full_bridge!(self.bridge, {
+			let SendMessage {
+				source_sign,
+				target_sign,
+				ref mut message,
+				dispatch_weight,
+				origin,
+				bridge,
+				..
+			} = self;
+
+			let source_sign = source_sign.to_keypair::<Source>()?;
+			let target_sign = target_sign.to_keypair::<Target>()?;
+
+			encode_call::preprocess_call::<Source, Target>(message, bridge.bridge_instance_index());
+			let target_call = Target::encode_call(&message)?;
+
+			let payload = {
+				let target_call_weight = prepare_call_dispatch_weight(
+					dispatch_weight,
+					ExplicitOrMaximal::Explicit(target_call.get_dispatch_info().weight),
+					compute_maximal_message_dispatch_weight(Target::max_extrinsic_weight()),
+				);
+				let source_sender_public: MultiSigner = source_sign.public().into();
+				let source_account_id = source_sender_public.into_account();
+
+				message_payload(
+					Target::RUNTIME_VERSION.spec_version,
+					target_call_weight,
+					match origin {
+						Origins::Source => CallOrigin::SourceAccount(source_account_id),
+						Origins::Target => {
+							let digest = account_ownership_digest(
+								&target_call,
+								source_account_id.clone(),
+								Target::RUNTIME_VERSION.spec_version,
+							);
+							let target_origin_public = target_sign.public();
+							let digest_signature = target_sign.sign(&digest);
+							CallOrigin::TargetAccount(
+								source_account_id,
+								target_origin_public.into(),
+								digest_signature.into(),
+							)
+						}
+					},
+					&target_call,
+				)
+			};
+			Ok(payload)
+		})
+	}
+
+	/// Run the command.
+	pub async fn run(mut self) -> anyhow::Result<()> {
+		crate::select_full_bridge!(self.bridge, {
+			let payload = self.encode_payload()?;
+
+			let source_client = self.source.to_client::<Source>().await?;
+			let source_sign = self.source_sign.to_keypair::<Source>()?;
+
+			let lane = self.lane.clone().into();
+			let fee = match self.fee {
+				Some(fee) => fee,
+				None => Balance(
+					estimate_message_delivery_and_dispatch_fee::<
+						<Source as relay_substrate_client::ChainWithBalances>::NativeBalance,
+						_,
+						_,
+					>(&source_client, ESTIMATE_MESSAGE_FEE_METHOD, lane, payload.clone())
+					.await? as _,
+				),
+			};
+			let dispatch_weight = payload.weight;
+			let send_message_call = Source::encode_call(&encode_call::Call::BridgeSendMessage {
+				bridge_instance_index: self.bridge.bridge_instance_index(),
+				lane: self.lane,
+				payload: HexBytes::encode(&payload),
+				fee,
+			})?;
+
+			source_client
+				.submit_signed_extrinsic(source_sign.public().into(), |transaction_nonce| {
+					let signed_source_call = Source::sign_transaction(
+						*source_client.genesis_hash(),
+						&source_sign,
+						transaction_nonce,
+						send_message_call,
+					)
+					.encode();
+
+					log::info!(
+						target: "bridge",
+						"Sending message to {}. Size: {}. Dispatch weight: {}. Fee: {}",
+						Target::NAME,
+						signed_source_call.len(),
+						dispatch_weight,
+						fee,
+					);
+					log::info!(
+						target: "bridge",
+						"Signed {} Call: {:?}",
+						Source::NAME,
+						HexBytes::encode(&signed_source_call)
+					);
+
+					Bytes(signed_source_call)
+				})
+				.await?;
+		});
+
+		Ok(())
+	}
+}
+
+fn prepare_call_dispatch_weight(
+	user_specified_dispatch_weight: &Option<ExplicitOrMaximal<Weight>>,
+	weight_from_pre_dispatch_call: ExplicitOrMaximal<Weight>,
+	maximal_allowed_weight: Weight,
+) -> Weight {
+	match user_specified_dispatch_weight
+		.clone()
+		.unwrap_or(weight_from_pre_dispatch_call)
+	{
+		ExplicitOrMaximal::Explicit(weight) => weight,
+		ExplicitOrMaximal::Maximal => maximal_allowed_weight,
+	}
+}
+
+pub(crate) fn message_payload<SAccountId, TPublic, TSignature>(
+	spec_version: u32,
+	weight: Weight,
+	origin: CallOrigin<SAccountId, TPublic, TSignature>,
+	call: &impl Encode,
+) -> MessagePayload<SAccountId, TPublic, TSignature, Vec<u8>>
+where
+	SAccountId: Encode + Debug,
+	TPublic: Encode + Debug,
+	TSignature: Encode + Debug,
+{
+	// Display nicely formatted call.
+	let payload = MessagePayload {
+		spec_version,
+		weight,
+		origin,
+		call: HexBytes::encode(call),
+	};
+
+	log::info!(target: "bridge", "Created Message Payload: {:#?}", payload);
+	log::info!(target: "bridge", "Encoded Message Payload: {:?}", HexBytes::encode(&payload));
+
+	// re-pack to return `Vec<u8>`
+	let MessagePayload {
+		spec_version,
+		weight,
+		origin,
+		call,
+	} = payload;
+	MessagePayload {
+		spec_version,
+		weight,
+		origin,
+		call: call.0,
+	}
+}
+
+pub(crate) fn compute_maximal_message_dispatch_weight(maximal_extrinsic_weight: Weight) -> Weight {
+	bridge_runtime_common::messages::target::maximal_incoming_message_dispatch_weight(maximal_extrinsic_weight)
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+	use hex_literal::hex;
+
+	#[test]
+	fn send_remark_rialto_to_millau() {
+		// given
+		let mut send_message = SendMessage::from_iter(vec![
+			"send-message",
+			"RialtoToMillau",
+			"--source-port",
+			"1234",
+			"--source-signer",
+			"//Alice",
+			"--target-signer",
+			"//Bob",
+			"remark",
+			"--remark-payload",
+			"1234",
+		]);
+
+		// when
+		let payload = send_message.encode_payload().unwrap();
+
+		// then
+		assert_eq!(
+			payload,
+			MessagePayload {
+				spec_version: relay_millau_client::Millau::RUNTIME_VERSION.spec_version,
+				weight: 1345000,
+				origin: CallOrigin::SourceAccount(sp_keyring::AccountKeyring::Alice.to_account_id()),
+				call: hex!("0401081234").to_vec(),
+			}
+		);
+	}
+
+	#[test]
+	fn send_remark_millau_to_rialto() {
+		// given
+		let mut send_message = SendMessage::from_iter(vec![
+			"send-message",
+			"MillauToRialto",
+			"--source-port",
+			"1234",
+			"--source-signer",
+			"//Alice",
+			"--origin",
+			"Target",
+			"--target-signer",
+			"//Bob",
+			"remark",
+			"--remark-payload",
+			"1234",
+		]);
+
+		// when
+		let payload = send_message.encode_payload().unwrap();
+
+		// then
+		// Since signatures are randomized we extract it from here and only check the rest.
+		let signature = match payload.origin {
+			CallOrigin::TargetAccount(_, _, ref sig) => sig.clone(),
+			_ => panic!("Unexpected `CallOrigin`: {:?}", payload),
+		};
+		assert_eq!(
+			payload,
+			MessagePayload {
+				spec_version: relay_millau_client::Millau::RUNTIME_VERSION.spec_version,
+				weight: 1345000,
+				origin: CallOrigin::TargetAccount(
+					sp_keyring::AccountKeyring::Alice.to_account_id(),
+					sp_keyring::AccountKeyring::Bob.into(),
+					signature,
+				),
+				call: hex!("0701081234").to_vec(),
+			}
+		);
+	}
+}

polkadot/bridges/relays/bin-substrate/src/finality_pipeline.rs

@@ -0,0 +1,149 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Substrate-to-Substrate headers sync entrypoint.
+
+use crate::finality_target::SubstrateFinalityTarget;
+
+use bp_header_chain::justification::GrandpaJustification;
+use finality_relay::{FinalitySyncParams, FinalitySyncPipeline};
+use relay_substrate_client::{finality_source::FinalitySource, BlockNumberOf, Chain, Client, HashOf, SyncHeader};
+use relay_utils::{metrics::MetricsParams, BlockNumberBase};
+use sp_core::Bytes;
+use std::{fmt::Debug, marker::PhantomData, time::Duration};
+
+/// Default synchronization loop timeout.
+const STALL_TIMEOUT: Duration = Duration::from_secs(120);
+/// Default limit of recent finality proofs.
+///
+/// Finality delay of 4096 blocks is unlikely to happen in practice in
+/// Substrate+GRANDPA based chains (good to know).
+const RECENT_FINALITY_PROOFS_LIMIT: usize = 4096;
+
+/// Headers sync pipeline for Substrate <-> Substrate relays.
+pub trait SubstrateFinalitySyncPipeline: FinalitySyncPipeline {
+	/// Name of the runtime method that returns id of best finalized source header at target chain.
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str;
+
+	/// Chain with GRANDPA bridge pallet.
+	type TargetChain: Chain;
+
+	/// Customize metrics exposed by headers sync loop.
+	fn customize_metrics(params: MetricsParams) -> anyhow::Result<MetricsParams> {
+		Ok(params)
+	}
+
+	/// Returns id of account that we're using to sign transactions at target chain.
+	fn transactions_author(&self) -> <Self::TargetChain as Chain>::AccountId;
+
+	/// Make submit header transaction.
+	fn make_submit_finality_proof_transaction(
+		&self,
+		transaction_nonce: <Self::TargetChain as Chain>::Index,
+		header: Self::Header,
+		proof: Self::FinalityProof,
+	) -> Bytes;
+}
+
+/// Substrate-to-Substrate finality proof pipeline.
+#[derive(Clone)]
+pub struct SubstrateFinalityToSubstrate<SourceChain, TargetChain: Chain, TargetSign> {
+	/// Client for the target chain.
+	pub(crate) target_client: Client<TargetChain>,
+	/// Data required to sign target chain transactions.
+	pub(crate) target_sign: TargetSign,
+	/// Unused generic arguments dump.
+	_marker: PhantomData<SourceChain>,
+}
+
+impl<SourceChain, TargetChain: Chain, TargetSign> Debug
+	for SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>
+{
+	fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+		f.debug_struct("SubstrateFinalityToSubstrate")
+			.field("target_client", &self.target_client)
+			.finish()
+	}
+}
+
+impl<SourceChain, TargetChain: Chain, TargetSign> SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign> {
+	/// Create new Substrate-to-Substrate headers pipeline.
+	pub fn new(target_client: Client<TargetChain>, target_sign: TargetSign) -> Self {
+		SubstrateFinalityToSubstrate {
+			target_client,
+			target_sign,
+			_marker: Default::default(),
+		}
+	}
+}
+
+impl<SourceChain, TargetChain, TargetSign> FinalitySyncPipeline
+	for SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>
+where
+	SourceChain: Clone + Chain + Debug,
+	BlockNumberOf<SourceChain>: BlockNumberBase,
+	TargetChain: Clone + Chain + Debug,
+	TargetSign: Clone + Send + Sync,
+{
+	const SOURCE_NAME: &'static str = SourceChain::NAME;
+	const TARGET_NAME: &'static str = TargetChain::NAME;
+
+	type Hash = HashOf<SourceChain>;
+	type Number = BlockNumberOf<SourceChain>;
+	type Header = SyncHeader<SourceChain::Header>;
+	type FinalityProof = GrandpaJustification<SourceChain::Header>;
+}
+
+/// Run Substrate-to-Substrate finality sync.
+pub async fn run<SourceChain, TargetChain, P>(
+	pipeline: P,
+	source_client: Client<SourceChain>,
+	target_client: Client<TargetChain>,
+	metrics_params: MetricsParams,
+) -> anyhow::Result<()>
+where
+	P: SubstrateFinalitySyncPipeline<
+		Hash = HashOf<SourceChain>,
+		Number = BlockNumberOf<SourceChain>,
+		Header = SyncHeader<SourceChain::Header>,
+		FinalityProof = GrandpaJustification<SourceChain::Header>,
+		TargetChain = TargetChain,
+	>,
+	SourceChain: Clone + Chain,
+	BlockNumberOf<SourceChain>: BlockNumberBase,
+	TargetChain: Clone + Chain,
+{
+	log::info!(
+		target: "bridge",
+		"Starting {} -> {} finality proof relay",
+		SourceChain::NAME,
+		TargetChain::NAME,
+	);
+
+	finality_relay::run(
+		FinalitySource::new(source_client),
+		SubstrateFinalityTarget::new(target_client, pipeline),
+		FinalitySyncParams {
+			tick: std::cmp::max(SourceChain::AVERAGE_BLOCK_INTERVAL, TargetChain::AVERAGE_BLOCK_INTERVAL),
+			recent_finality_proofs_limit: RECENT_FINALITY_PROOFS_LIMIT,
+			stall_timeout: STALL_TIMEOUT,
+		},
+		metrics_params,
+		futures::future::pending(),
+	)
+	.await
+	.map_err(|e| anyhow::format_err!("{}", e))
+}

polkadot/bridges/relays/bin-substrate/src/finality_target.rs

@@ -0,0 +1,91 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Substrate client as Substrate finality proof target. The chain we connect to should have
+//! runtime that implements `<BridgedChainName>FinalityApi` to allow bridging with
+//! <BridgedName> chain.
+
+use crate::finality_pipeline::SubstrateFinalitySyncPipeline;
+
+use async_trait::async_trait;
+use codec::Decode;
+use finality_relay::TargetClient;
+use relay_substrate_client::{Chain, Client, Error as SubstrateError};
+use relay_utils::relay_loop::Client as RelayClient;
+
+/// Substrate client as Substrate finality target.
+pub struct SubstrateFinalityTarget<C: Chain, P> {
+	client: Client<C>,
+	pipeline: P,
+}
+
+impl<C: Chain, P> SubstrateFinalityTarget<C, P> {
+	/// Create new Substrate headers target.
+	pub fn new(client: Client<C>, pipeline: P) -> Self {
+		SubstrateFinalityTarget { client, pipeline }
+	}
+}
+
+impl<C: Chain, P: SubstrateFinalitySyncPipeline> Clone for SubstrateFinalityTarget<C, P> {
+	fn clone(&self) -> Self {
+		SubstrateFinalityTarget {
+			client: self.client.clone(),
+			pipeline: self.pipeline.clone(),
+		}
+	}
+}
+
+#[async_trait]
+impl<C: Chain, P: SubstrateFinalitySyncPipeline> RelayClient for SubstrateFinalityTarget<C, P> {
+	type Error = SubstrateError;
+
+	async fn reconnect(&mut self) -> Result<(), SubstrateError> {
+		self.client.reconnect().await
+	}
+}
+
+#[async_trait]
+impl<C, P> TargetClient<P> for SubstrateFinalityTarget<C, P>
+where
+	C: Chain,
+	P::Number: Decode,
+	P::Hash: Decode,
+	P: SubstrateFinalitySyncPipeline<TargetChain = C>,
+{
+	async fn best_finalized_source_block_number(&self) -> Result<P::Number, SubstrateError> {
+		// we can't continue to relay finality if target node is out of sync, because
+		// it may have already received (some of) headers that we're going to relay
+		self.client.ensure_synced().await?;
+
+		Ok(crate::messages_source::read_client_state::<C, P::Hash, P::Number>(
+			&self.client,
+			P::BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET,
+		)
+		.await?
+		.best_finalized_peer_at_best_self
+		.0)
+	}
+
+	async fn submit_finality_proof(&self, header: P::Header, proof: P::FinalityProof) -> Result<(), SubstrateError> {
+		self.client
+			.submit_signed_extrinsic(self.pipeline.transactions_author(), move |transaction_nonce| {
+				self.pipeline
+					.make_submit_finality_proof_transaction(transaction_nonce, header, proof)
+			})
+			.await
+			.map(drop)
+	}
+}

polkadot/bridges/relays/bin-substrate/src/headers_initialize.rs

@@ -0,0 +1,256 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Initialize Substrate -> Substrate headers bridge.
+//!
+//! Initialization is a transaction that calls `initialize()` function of the
+//! `pallet-bridge-grandpa` pallet. This transaction brings initial header
+//! and authorities set from source to target chain. The headers sync starts
+//! with this header.
+
+use bp_header_chain::InitializationData;
+use bp_header_chain::{
+	find_grandpa_authorities_scheduled_change,
+	justification::{verify_justification, GrandpaJustification},
+};
+use codec::Decode;
+use finality_grandpa::voter_set::VoterSet;
+use num_traits::{One, Zero};
+use relay_substrate_client::{Chain, Client};
+use sp_core::Bytes;
+use sp_finality_grandpa::AuthorityList as GrandpaAuthoritiesSet;
+use sp_runtime::traits::Header as HeaderT;
+
+/// Submit headers-bridge initialization transaction.
+pub async fn initialize<SourceChain: Chain, TargetChain: Chain>(
+	source_client: Client<SourceChain>,
+	target_client: Client<TargetChain>,
+	target_transactions_signer: TargetChain::AccountId,
+	prepare_initialize_transaction: impl FnOnce(TargetChain::Index, InitializationData<SourceChain::Header>) -> Bytes,
+) {
+	let result = do_initialize(
+		source_client,
+		target_client,
+		target_transactions_signer,
+		prepare_initialize_transaction,
+	)
+	.await;
+
+	match result {
+		Ok(tx_hash) => log::info!(
+			target: "bridge",
+			"Successfully submitted {}-headers bridge initialization transaction to {}: {:?}",
+			SourceChain::NAME,
+			TargetChain::NAME,
+			tx_hash,
+		),
+		Err(err) => log::error!(
+			target: "bridge",
+			"Failed to submit {}-headers bridge initialization transaction to {}: {:?}",
+			SourceChain::NAME,
+			TargetChain::NAME,
+			err,
+		),
+	}
+}
+
+/// Craft and submit initialization transaction, returning any error that may occur.
+async fn do_initialize<SourceChain: Chain, TargetChain: Chain>(
+	source_client: Client<SourceChain>,
+	target_client: Client<TargetChain>,
+	target_transactions_signer: TargetChain::AccountId,
+	prepare_initialize_transaction: impl FnOnce(TargetChain::Index, InitializationData<SourceChain::Header>) -> Bytes,
+) -> Result<TargetChain::Hash, String> {
+	let initialization_data = prepare_initialization_data(source_client).await?;
+	log::info!(
+		target: "bridge",
+		"Prepared initialization data for {}-headers bridge at {}: {:?}",
+		SourceChain::NAME,
+		TargetChain::NAME,
+		initialization_data,
+	);
+
+	let initialization_tx_hash = target_client
+		.submit_signed_extrinsic(target_transactions_signer, move |transaction_nonce| {
+			prepare_initialize_transaction(transaction_nonce, initialization_data)
+		})
+		.await
+		.map_err(|err| format!("Failed to submit {} transaction: {:?}", TargetChain::NAME, err))?;
+	Ok(initialization_tx_hash)
+}
+
+/// Prepare initialization data for the GRANDPA verifier pallet.
+async fn prepare_initialization_data<SourceChain: Chain>(
+	source_client: Client<SourceChain>,
+) -> Result<InitializationData<SourceChain::Header>, String> {
+	// In ideal world we just need to get best finalized header and then to read GRANDPA authorities
+	// set (`pallet_grandpa::CurrentSetId` + `GrandpaApi::grandpa_authorities()`) at this header.
+	//
+	// But now there are problems with this approach - `CurrentSetId` may return invalid value. So here
+	// we're waiting for the next justification, read the authorities set and then try to figure out
+	// the set id with bruteforce.
+	let mut justifications = source_client
+		.subscribe_justifications()
+		.await
+		.map_err(|err| format!("Failed to subscribe to {} justifications: {:?}", SourceChain::NAME, err))?;
+
+	// Read next justification - the header that it finalizes will be used as initial header.
+	let justification = justifications.next().await.ok_or_else(|| {
+		format!(
+			"Failed to read {} justification from the stream: stream has ended unexpectedly",
+			SourceChain::NAME,
+		)
+	})?;
+
+	// Read initial header.
+	let justification: GrandpaJustification<SourceChain::Header> = Decode::decode(&mut &justification.0[..])
+		.map_err(|err| format!("Failed to decode {} justification: {:?}", SourceChain::NAME, err))?;
+
+	let (initial_header_hash, initial_header_number) =
+		(justification.commit.target_hash, justification.commit.target_number);
+
+	let initial_header = source_header(&source_client, initial_header_hash).await?;
+	log::trace!(target: "bridge", "Selected {} initial header: {}/{}",
+		SourceChain::NAME,
+		initial_header_number,
+		initial_header_hash,
+	);
+
+	// Read GRANDPA authorities set at initial header.
+	let initial_authorities_set = source_authorities_set(&source_client, initial_header_hash).await?;
+	log::trace!(target: "bridge", "Selected {} initial authorities set: {:?}",
+		SourceChain::NAME,
+		initial_authorities_set,
+	);
+
+	// If initial header changes the GRANDPA authorities set, then we need previous authorities
+	// to verify justification.
+	let mut authorities_for_verification = initial_authorities_set.clone();
+	let scheduled_change = find_grandpa_authorities_scheduled_change(&initial_header);
+	assert!(
+		scheduled_change.as_ref().map(|c| c.delay.is_zero()).unwrap_or(true),
+		"GRANDPA authorities change at {} scheduled to happen in {:?} blocks. We expect\
+		regular hange to have zero delay",
+		initial_header_hash,
+		scheduled_change.as_ref().map(|c| c.delay),
+	);
+	let schedules_change = scheduled_change.is_some();
+	if schedules_change {
+		authorities_for_verification = source_authorities_set(&source_client, *initial_header.parent_hash()).await?;
+		log::trace!(
+			target: "bridge",
+			"Selected {} header is scheduling GRANDPA authorities set changes. Using previous set: {:?}",
+			SourceChain::NAME,
+			authorities_for_verification,
+		);
+	}
+
+	// Now let's try to guess authorities set id by verifying justification.
+	let mut initial_authorities_set_id = 0;
+	let mut min_possible_block_number = SourceChain::BlockNumber::zero();
+	let authorities_for_verification = VoterSet::new(authorities_for_verification.clone()).ok_or_else(|| {
+		format!(
+			"Read invalid {} authorities set: {:?}",
+			SourceChain::NAME,
+			authorities_for_verification,
+		)
+	})?;
+	loop {
+		log::trace!(
+			target: "bridge", "Trying {} GRANDPA authorities set id: {}",
+			SourceChain::NAME,
+			initial_authorities_set_id,
+		);
+
+		let is_valid_set_id = verify_justification::<SourceChain::Header>(
+			(initial_header_hash, initial_header_number),
+			initial_authorities_set_id,
+			&authorities_for_verification,
+			&justification,
+		)
+		.is_ok();
+
+		if is_valid_set_id {
+			break;
+		}
+
+		initial_authorities_set_id += 1;
+		min_possible_block_number += One::one();
+		if min_possible_block_number > initial_header_number {
+			// there can't be more authorities set changes than headers => if we have reached `initial_block_number`
+			// and still have not found correct value of `initial_authorities_set_id`, then something
+			// else is broken => fail
+			return Err(format!(
+				"Failed to guess initial {} GRANDPA authorities set id: checked all\
+			possible ids in range [0; {}]",
+				SourceChain::NAME,
+				initial_header_number
+			));
+		}
+	}
+
+	Ok(InitializationData {
+		header: initial_header,
+		authority_list: initial_authorities_set,
+		set_id: if schedules_change {
+			initial_authorities_set_id + 1
+		} else {
+			initial_authorities_set_id
+		},
+		is_halted: false,
+	})
+}
+
+/// Read header by hash from the source client.
+async fn source_header<SourceChain: Chain>(
+	source_client: &Client<SourceChain>,
+	header_hash: SourceChain::Hash,
+) -> Result<SourceChain::Header, String> {
+	source_client.header_by_hash(header_hash).await.map_err(|err| {
+		format!(
+			"Failed to retrive {} header with hash {}: {:?}",
+			SourceChain::NAME,
+			header_hash,
+			err,
+		)
+	})
+}
+
+/// Read GRANDPA authorities set at given header.
+async fn source_authorities_set<SourceChain: Chain>(
+	source_client: &Client<SourceChain>,
+	header_hash: SourceChain::Hash,
+) -> Result<GrandpaAuthoritiesSet, String> {
+	let raw_authorities_set = source_client
+		.grandpa_authorities_set(header_hash)
+		.await
+		.map_err(|err| {
+			format!(
+				"Failed to retrive {} GRANDPA authorities set at header {}: {:?}",
+				SourceChain::NAME,
+				header_hash,
+				err,
+			)
+		})?;
+	GrandpaAuthoritiesSet::decode(&mut &raw_authorities_set[..]).map_err(|err| {
+		format!(
+			"Failed to decode {} GRANDPA authorities set at header {}: {:?}",
+			SourceChain::NAME,
+			header_hash,
+			err,
+		)
+	})
+}

polkadot/bridges/relays/bin-substrate/src/main.rs

@@ -0,0 +1,41 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Substrate-to-substrate relay entrypoint.
+
+#![warn(missing_docs)]
+
+use relay_utils::initialize::initialize_logger;
+
+mod chains;
+mod cli;
+mod finality_pipeline;
+mod finality_target;
+mod headers_initialize;
+mod messages_lane;
+mod messages_source;
+mod messages_target;
+mod on_demand_headers;
+
+fn main() {
+	initialize_logger(false);
+	let command = cli::parse_args();
+	let run = command.run();
+	let result = async_std::task::block_on(run);
+	if let Err(error) = result {
+		log::error!(target: "bridge", "Failed to start relay: {}", error);
+	}
+}

polkadot/bridges/relays/bin-substrate/src/messages_lane.rs

@@ -0,0 +1,209 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::messages_source::SubstrateMessagesProof;
+use crate::messages_target::SubstrateMessagesReceivingProof;
+use crate::on_demand_headers::OnDemandHeadersRelay;
+
+use bp_messages::{LaneId, MessageNonce};
+use frame_support::weights::Weight;
+use messages_relay::message_lane::{MessageLane, SourceHeaderIdOf, TargetHeaderIdOf};
+use relay_substrate_client::{BlockNumberOf, Chain, Client, HashOf};
+use relay_utils::{metrics::MetricsParams, BlockNumberBase};
+use sp_core::Bytes;
+use std::ops::RangeInclusive;
+
+/// Substrate <-> Substrate messages relay parameters.
+pub struct MessagesRelayParams<SC: Chain, SS, TC: Chain, TS> {
+	/// Messages source client.
+	pub source_client: Client<SC>,
+	/// Sign parameters for messages source chain.
+	pub source_sign: SS,
+	/// Messages target client.
+	pub target_client: Client<TC>,
+	/// Sign parameters for messages target chain.
+	pub target_sign: TS,
+	/// Optional on-demand source to target headers relay.
+	pub source_to_target_headers_relay: Option<OnDemandHeadersRelay<SC>>,
+	/// Optional on-demand target to source headers relay.
+	pub target_to_source_headers_relay: Option<OnDemandHeadersRelay<TC>>,
+	/// Identifier of lane that needs to be served.
+	pub lane_id: LaneId,
+	/// Metrics parameters.
+	pub metrics_params: MetricsParams,
+}
+
+/// Message sync pipeline for Substrate <-> Substrate relays.
+pub trait SubstrateMessageLane: MessageLane {
+	/// Name of the runtime method that returns dispatch weight of outbound messages at the source chain.
+	const OUTBOUND_LANE_MESSAGES_DISPATCH_WEIGHT_METHOD: &'static str;
+	/// Name of the runtime method that returns latest generated nonce at the source chain.
+	const OUTBOUND_LANE_LATEST_GENERATED_NONCE_METHOD: &'static str;
+	/// Name of the runtime method that returns latest received (confirmed) nonce at the the source chain.
+	const OUTBOUND_LANE_LATEST_RECEIVED_NONCE_METHOD: &'static str;
+
+	/// Name of the runtime method that returns latest received nonce at the target chain.
+	const INBOUND_LANE_LATEST_RECEIVED_NONCE_METHOD: &'static str;
+	/// Name of the runtime method that returns latest confirmed (reward-paid) nonce at the target chain.
+	const INBOUND_LANE_LATEST_CONFIRMED_NONCE_METHOD: &'static str;
+	/// Numebr of the runtime method that returns state of "unrewarded relayers" set at the target chain.
+	const INBOUND_LANE_UNREWARDED_RELAYERS_STATE: &'static str;
+
+	/// Name of the runtime method that returns id of best finalized source header at target chain.
+	const BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET: &'static str;
+	/// Name of the runtime method that returns id of best finalized target header at source chain.
+	const BEST_FINALIZED_TARGET_HEADER_ID_AT_SOURCE: &'static str;
+
+	/// Source chain.
+	type SourceChain: Chain;
+	/// Target chain.
+	type TargetChain: Chain;
+
+	/// Returns id of account that we're using to sign transactions at target chain (messages proof).
+	fn target_transactions_author(&self) -> <Self::TargetChain as Chain>::AccountId;
+
+	/// Make messages delivery transaction.
+	fn make_messages_delivery_transaction(
+		&self,
+		transaction_nonce: <Self::TargetChain as Chain>::Index,
+		generated_at_header: SourceHeaderIdOf<Self>,
+		nonces: RangeInclusive<MessageNonce>,
+		proof: Self::MessagesProof,
+	) -> Bytes;
+
+	/// Returns id of account that we're using to sign transactions at source chain (delivery proof).
+	fn source_transactions_author(&self) -> <Self::SourceChain as Chain>::AccountId;
+
+	/// Make messages receiving proof transaction.
+	fn make_messages_receiving_proof_transaction(
+		&self,
+		transaction_nonce: <Self::SourceChain as Chain>::Index,
+		generated_at_header: TargetHeaderIdOf<Self>,
+		proof: Self::MessagesReceivingProof,
+	) -> Bytes;
+}
+
+/// Substrate-to-Substrate message lane.
+#[derive(Debug)]
+pub struct SubstrateMessageLaneToSubstrate<Source: Chain, SourceSignParams, Target: Chain, TargetSignParams> {
+	/// Client for the source Substrate chain.
+	pub(crate) source_client: Client<Source>,
+	/// Parameters required to sign transactions for source chain.
+	pub(crate) source_sign: SourceSignParams,
+	/// Client for the target Substrate chain.
+	pub(crate) target_client: Client<Target>,
+	/// Parameters required to sign transactions for target chain.
+	pub(crate) target_sign: TargetSignParams,
+	/// Account id of relayer at the source chain.
+	pub(crate) relayer_id_at_source: Source::AccountId,
+}
+
+impl<Source: Chain, SourceSignParams: Clone, Target: Chain, TargetSignParams: Clone> Clone
+	for SubstrateMessageLaneToSubstrate<Source, SourceSignParams, Target, TargetSignParams>
+{
+	fn clone(&self) -> Self {
+		Self {
+			source_client: self.source_client.clone(),
+			source_sign: self.source_sign.clone(),
+			target_client: self.target_client.clone(),
+			target_sign: self.target_sign.clone(),
+			relayer_id_at_source: self.relayer_id_at_source.clone(),
+		}
+	}
+}
+
+impl<Source: Chain, SourceSignParams, Target: Chain, TargetSignParams> MessageLane
+	for SubstrateMessageLaneToSubstrate<Source, SourceSignParams, Target, TargetSignParams>
+where
+	SourceSignParams: Clone + Send + Sync + 'static,
+	TargetSignParams: Clone + Send + Sync + 'static,
+	BlockNumberOf<Source>: BlockNumberBase,
+	BlockNumberOf<Target>: BlockNumberBase,
+{
+	const SOURCE_NAME: &'static str = Source::NAME;
+	const TARGET_NAME: &'static str = Target::NAME;
+
+	type MessagesProof = SubstrateMessagesProof<Source>;
+	type MessagesReceivingProof = SubstrateMessagesReceivingProof<Target>;
+
+	type SourceHeaderNumber = BlockNumberOf<Source>;
+	type SourceHeaderHash = HashOf<Source>;
+
+	type TargetHeaderNumber = BlockNumberOf<Target>;
+	type TargetHeaderHash = HashOf<Target>;
+}
+
+/// Returns maximal number of messages and their maximal cumulative dispatch weight, based
+/// on given chain parameters.
+pub fn select_delivery_transaction_limits<W: pallet_bridge_messages::WeightInfoExt>(
+	max_extrinsic_weight: Weight,
+	max_unconfirmed_messages_at_inbound_lane: MessageNonce,
+) -> (MessageNonce, Weight) {
+	// We may try to guess accurate value, based on maximal number of messages and per-message
+	// weight overhead, but the relay loop isn't using this info in a super-accurate way anyway.
+	// So just a rough guess: let's say 1/3 of max tx weight is for tx itself and the rest is
+	// for messages dispatch.
+
+	// Another thing to keep in mind is that our runtimes (when this code was written) accept
+	// messages with dispatch weight <= max_extrinsic_weight/2. So we can't reserve less than
+	// that for dispatch.
+
+	let weight_for_delivery_tx = max_extrinsic_weight / 3;
+	let weight_for_messages_dispatch = max_extrinsic_weight - weight_for_delivery_tx;
+
+	let delivery_tx_base_weight =
+		W::receive_messages_proof_overhead() + W::receive_messages_proof_outbound_lane_state_overhead();
+	let delivery_tx_weight_rest = weight_for_delivery_tx - delivery_tx_base_weight;
+	let max_number_of_messages = std::cmp::min(
+		delivery_tx_weight_rest / W::receive_messages_proof_messages_overhead(1),
+		max_unconfirmed_messages_at_inbound_lane,
+	);
+
+	assert!(
+		max_number_of_messages > 0,
+		"Relay should fit at least one message in every delivery transaction",
+	);
+	assert!(
+		weight_for_messages_dispatch >= max_extrinsic_weight / 2,
+		"Relay shall be able to deliver messages with dispatch weight = max_extrinsic_weight / 2",
+	);
+
+	(max_number_of_messages, weight_for_messages_dispatch)
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+
+	type RialtoToMillauMessagesWeights = pallet_bridge_messages::weights::RialtoWeight<rialto_runtime::Runtime>;
+
+	#[test]
+	fn select_delivery_transaction_limits_works() {
+		let (max_count, max_weight) = select_delivery_transaction_limits::<RialtoToMillauMessagesWeights>(
+			bp_millau::max_extrinsic_weight(),
+			bp_millau::MAX_UNREWARDED_RELAYER_ENTRIES_AT_INBOUND_LANE,
+		);
+		assert_eq!(
+			(max_count, max_weight),
+			// We don't actually care about these values, so feel free to update them whenever test
+			// fails. The only thing to do before that is to ensure that new values looks sane: i.e. weight
+			// reserved for messages dispatch allows dispatch of non-trivial messages.
+			//
+			// Any significant change in this values should attract additional attention.
+			(1020, 216_583_333_334),
+		);
+	}
+}

polkadot/bridges/relays/bin-substrate/src/messages_source.rs

@@ -0,0 +1,411 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Substrate client as Substrate messages source. The chain we connect to should have
+//! runtime that implements `<BridgedChainName>HeaderApi` to allow bridging with
+//! <BridgedName> chain.
+
+use crate::messages_lane::SubstrateMessageLane;
+use crate::on_demand_headers::OnDemandHeadersRelay;
+
+use async_trait::async_trait;
+use bp_messages::{LaneId, MessageNonce};
+use bp_runtime::InstanceId;
+use bridge_runtime_common::messages::target::FromBridgedChainMessagesProof;
+use codec::{Decode, Encode};
+use frame_support::{traits::Instance, weights::Weight};
+use messages_relay::{
+	message_lane::{SourceHeaderIdOf, TargetHeaderIdOf},
+	message_lane_loop::{
+		ClientState, MessageProofParameters, MessageWeights, MessageWeightsMap, SourceClient, SourceClientState,
+	},
+};
+use pallet_bridge_messages::Config as MessagesConfig;
+use relay_substrate_client::{Chain, Client, Error as SubstrateError, HashOf, HeaderIdOf};
+use relay_utils::{relay_loop::Client as RelayClient, BlockNumberBase, HeaderId};
+use sp_core::Bytes;
+use sp_runtime::{traits::Header as HeaderT, DeserializeOwned};
+use std::{marker::PhantomData, ops::RangeInclusive};
+
+/// Intermediate message proof returned by the source Substrate node. Includes everything
+/// required to submit to the target node: cumulative dispatch weight of bundled messages and
+/// the proof itself.
+pub type SubstrateMessagesProof<C> = (Weight, FromBridgedChainMessagesProof<HashOf<C>>);
+
+/// Substrate client as Substrate messages source.
+pub struct SubstrateMessagesSource<C: Chain, P: SubstrateMessageLane, R, I> {
+	client: Client<C>,
+	lane: P,
+	lane_id: LaneId,
+	instance: InstanceId,
+	target_to_source_headers_relay: Option<OnDemandHeadersRelay<P::TargetChain>>,
+	_phantom: PhantomData<(R, I)>,
+}
+
+impl<C: Chain, P: SubstrateMessageLane, R, I> SubstrateMessagesSource<C, P, R, I> {
+	/// Create new Substrate headers source.
+	pub fn new(
+		client: Client<C>,
+		lane: P,
+		lane_id: LaneId,
+		instance: InstanceId,
+		target_to_source_headers_relay: Option<OnDemandHeadersRelay<P::TargetChain>>,
+	) -> Self {
+		SubstrateMessagesSource {
+			client,
+			lane,
+			lane_id,
+			instance,
+			target_to_source_headers_relay,
+			_phantom: Default::default(),
+		}
+	}
+}
+
+impl<C: Chain, P: SubstrateMessageLane, R, I> Clone for SubstrateMessagesSource<C, P, R, I> {
+	fn clone(&self) -> Self {
+		Self {
+			client: self.client.clone(),
+			lane: self.lane.clone(),
+			lane_id: self.lane_id,
+			instance: self.instance,
+			target_to_source_headers_relay: self.target_to_source_headers_relay.clone(),
+			_phantom: Default::default(),
+		}
+	}
+}
+
+#[async_trait]
+impl<C, P, R, I> RelayClient for SubstrateMessagesSource<C, P, R, I>
+where
+	C: Chain,
+	P: SubstrateMessageLane,
+	R: Send + Sync,
+	I: Send + Sync + Instance,
+{
+	type Error = SubstrateError;
+
+	async fn reconnect(&mut self) -> Result<(), SubstrateError> {
+		self.client.reconnect().await
+	}
+}
+
+#[async_trait]
+impl<C, P, R, I> SourceClient<P> for SubstrateMessagesSource<C, P, R, I>
+where
+	C: Chain,
+	C::Header: DeserializeOwned,
+	C::Index: DeserializeOwned,
+	C::BlockNumber: BlockNumberBase,
+	P: SubstrateMessageLane<
+		MessagesProof = SubstrateMessagesProof<C>,
+		SourceHeaderNumber = <C::Header as HeaderT>::Number,
+		SourceHeaderHash = <C::Header as HeaderT>::Hash,
+		SourceChain = C,
+	>,
+	P::TargetChain: Chain<Hash = P::TargetHeaderHash, BlockNumber = P::TargetHeaderNumber>,
+	P::TargetHeaderNumber: Decode,
+	P::TargetHeaderHash: Decode,
+	R: Send + Sync + MessagesConfig<I>,
+	I: Send + Sync + Instance,
+{
+	async fn state(&self) -> Result<SourceClientState<P>, SubstrateError> {
+		// we can't continue to deliver confirmations if source node is out of sync, because
+		// it may have already received confirmations that we're going to deliver
+		self.client.ensure_synced().await?;
+
+		read_client_state::<_, P::TargetHeaderHash, P::TargetHeaderNumber>(
+			&self.client,
+			P::BEST_FINALIZED_TARGET_HEADER_ID_AT_SOURCE,
+		)
+		.await
+	}
+
+	async fn latest_generated_nonce(
+		&self,
+		id: SourceHeaderIdOf<P>,
+	) -> Result<(SourceHeaderIdOf<P>, MessageNonce), SubstrateError> {
+		let encoded_response = self
+			.client
+			.state_call(
+				P::OUTBOUND_LANE_LATEST_GENERATED_NONCE_METHOD.into(),
+				Bytes(self.lane_id.encode()),
+				Some(id.1),
+			)
+			.await?;
+		let latest_generated_nonce: MessageNonce =
+			Decode::decode(&mut &encoded_response.0[..]).map_err(SubstrateError::ResponseParseFailed)?;
+		Ok((id, latest_generated_nonce))
+	}
+
+	async fn latest_confirmed_received_nonce(
+		&self,
+		id: SourceHeaderIdOf<P>,
+	) -> Result<(SourceHeaderIdOf<P>, MessageNonce), SubstrateError> {
+		let encoded_response = self
+			.client
+			.state_call(
+				P::OUTBOUND_LANE_LATEST_RECEIVED_NONCE_METHOD.into(),
+				Bytes(self.lane_id.encode()),
+				Some(id.1),
+			)
+			.await?;
+		let latest_received_nonce: MessageNonce =
+			Decode::decode(&mut &encoded_response.0[..]).map_err(SubstrateError::ResponseParseFailed)?;
+		Ok((id, latest_received_nonce))
+	}
+
+	async fn generated_messages_weights(
+		&self,
+		id: SourceHeaderIdOf<P>,
+		nonces: RangeInclusive<MessageNonce>,
+	) -> Result<MessageWeightsMap, SubstrateError> {
+		let encoded_response = self
+			.client
+			.state_call(
+				P::OUTBOUND_LANE_MESSAGES_DISPATCH_WEIGHT_METHOD.into(),
+				Bytes((self.lane_id, nonces.start(), nonces.end()).encode()),
+				Some(id.1),
+			)
+			.await?;
+
+		make_message_weights_map::<C>(
+			Decode::decode(&mut &encoded_response.0[..]).map_err(SubstrateError::ResponseParseFailed)?,
+			nonces,
+		)
+	}
+
+	async fn prove_messages(
+		&self,
+		id: SourceHeaderIdOf<P>,
+		nonces: RangeInclusive<MessageNonce>,
+		proof_parameters: MessageProofParameters,
+	) -> Result<(SourceHeaderIdOf<P>, RangeInclusive<MessageNonce>, P::MessagesProof), SubstrateError> {
+		let mut storage_keys = Vec::with_capacity(nonces.end().saturating_sub(*nonces.start()) as usize + 1);
+		let mut message_nonce = *nonces.start();
+		while message_nonce <= *nonces.end() {
+			let message_key = pallet_bridge_messages::storage_keys::message_key::<R, I>(&self.lane_id, message_nonce);
+			storage_keys.push(message_key);
+			message_nonce += 1;
+		}
+		if proof_parameters.outbound_state_proof_required {
+			storage_keys.push(pallet_bridge_messages::storage_keys::outbound_lane_data_key::<I>(
+				&self.lane_id,
+			));
+		}
+
+		let proof = self
+			.client
+			.prove_storage(storage_keys, id.1)
+			.await?
+			.iter_nodes()
+			.collect();
+		let proof = FromBridgedChainMessagesProof {
+			bridged_header_hash: id.1,
+			storage_proof: proof,
+			lane: self.lane_id,
+			nonces_start: *nonces.start(),
+			nonces_end: *nonces.end(),
+		};
+		Ok((id, nonces, (proof_parameters.dispatch_weight, proof)))
+	}
+
+	async fn submit_messages_receiving_proof(
+		&self,
+		generated_at_block: TargetHeaderIdOf<P>,
+		proof: P::MessagesReceivingProof,
+	) -> Result<(), SubstrateError> {
+		self.client
+			.submit_signed_extrinsic(self.lane.source_transactions_author(), move |transaction_nonce| {
+				self.lane
+					.make_messages_receiving_proof_transaction(transaction_nonce, generated_at_block, proof)
+			})
+			.await?;
+		Ok(())
+	}
+
+	async fn require_target_header_on_source(&self, id: TargetHeaderIdOf<P>) {
+		if let Some(ref target_to_source_headers_relay) = self.target_to_source_headers_relay {
+			target_to_source_headers_relay.require_finalized_header(id);
+		}
+	}
+}
+
+pub async fn read_client_state<SelfChain, BridgedHeaderHash, BridgedHeaderNumber>(
+	self_client: &Client<SelfChain>,
+	best_finalized_header_id_method_name: &str,
+) -> Result<ClientState<HeaderIdOf<SelfChain>, HeaderId<BridgedHeaderHash, BridgedHeaderNumber>>, SubstrateError>
+where
+	SelfChain: Chain,
+	SelfChain::Header: DeserializeOwned,
+	SelfChain::Index: DeserializeOwned,
+	BridgedHeaderHash: Decode,
+	BridgedHeaderNumber: Decode,
+{
+	// let's read our state first: we need best finalized header hash on **this** chain
+	let self_best_finalized_header_hash = self_client.best_finalized_header_hash().await?;
+	let self_best_finalized_header = self_client.header_by_hash(self_best_finalized_header_hash).await?;
+	let self_best_finalized_id = HeaderId(*self_best_finalized_header.number(), self_best_finalized_header_hash);
+
+	// now let's read our best header on **this** chain
+	let self_best_header = self_client.best_header().await?;
+	let self_best_hash = self_best_header.hash();
+	let self_best_id = HeaderId(*self_best_header.number(), self_best_hash);
+
+	// now let's read id of best finalized peer header at our best finalized block
+	let encoded_best_finalized_peer_on_self = self_client
+		.state_call(
+			best_finalized_header_id_method_name.into(),
+			Bytes(Vec::new()),
+			Some(self_best_hash),
+		)
+		.await?;
+	let decoded_best_finalized_peer_on_self: (BridgedHeaderNumber, BridgedHeaderHash) =
+		Decode::decode(&mut &encoded_best_finalized_peer_on_self.0[..]).map_err(SubstrateError::ResponseParseFailed)?;
+	let peer_on_self_best_finalized_id = HeaderId(
+		decoded_best_finalized_peer_on_self.0,
+		decoded_best_finalized_peer_on_self.1,
+	);
+
+	Ok(ClientState {
+		best_self: self_best_id,
+		best_finalized_self: self_best_finalized_id,
+		best_finalized_peer_at_best_self: peer_on_self_best_finalized_id,
+	})
+}
+
+fn make_message_weights_map<C: Chain>(
+	weights: Vec<(MessageNonce, Weight, u32)>,
+	nonces: RangeInclusive<MessageNonce>,
+) -> Result<MessageWeightsMap, SubstrateError> {
+	let make_missing_nonce_error = |expected_nonce| {
+		Err(SubstrateError::Custom(format!(
+			"Missing nonce {} in messages_dispatch_weight call result. Expected all nonces from {:?}",
+			expected_nonce, nonces,
+		)))
+	};
+
+	let mut weights_map = MessageWeightsMap::new();
+
+	// this is actually prevented by external logic
+	if nonces.is_empty() {
+		return Ok(weights_map);
+	}
+
+	// check if last nonce is missing - loop below is not checking this
+	let last_nonce_is_missing = weights
+		.last()
+		.map(|(last_nonce, _, _)| last_nonce != nonces.end())
+		.unwrap_or(true);
+	if last_nonce_is_missing {
+		return make_missing_nonce_error(*nonces.end());
+	}
+
+	let mut expected_nonce = *nonces.start();
+	let mut is_at_head = true;
+
+	for (nonce, weight, size) in weights {
+		match (nonce == expected_nonce, is_at_head) {
+			(true, _) => (),
+			(false, true) => {
+				// this may happen if some messages were already pruned from the source node
+				//
+				// this is not critical error and will be auto-resolved by messages lane (and target node)
+				log::info!(
+					target: "bridge",
+					"Some messages are missing from the {} node: {:?}. Target node may be out of sync?",
+					C::NAME,
+					expected_nonce..nonce,
+				);
+			}
+			(false, false) => {
+				// some nonces are missing from the middle/tail of the range
+				//
+				// this is critical error, because we can't miss any nonces
+				return make_missing_nonce_error(expected_nonce);
+			}
+		}
+
+		weights_map.insert(
+			nonce,
+			MessageWeights {
+				weight,
+				size: size as _,
+			},
+		);
+		expected_nonce = nonce + 1;
+		is_at_head = false;
+	}
+
+	Ok(weights_map)
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+
+	#[test]
+	fn make_message_weights_map_succeeds_if_no_messages_are_missing() {
+		assert_eq!(
+			make_message_weights_map::<relay_rialto_client::Rialto>(vec![(1, 0, 0), (2, 0, 0), (3, 0, 0)], 1..=3,)
+				.unwrap(),
+			vec![
+				(1, MessageWeights { weight: 0, size: 0 }),
+				(2, MessageWeights { weight: 0, size: 0 }),
+				(3, MessageWeights { weight: 0, size: 0 }),
+			]
+			.into_iter()
+			.collect(),
+		);
+	}
+
+	#[test]
+	fn make_message_weights_map_succeeds_if_head_messages_are_missing() {
+		assert_eq!(
+			make_message_weights_map::<relay_rialto_client::Rialto>(vec![(2, 0, 0), (3, 0, 0)], 1..=3,).unwrap(),
+			vec![
+				(2, MessageWeights { weight: 0, size: 0 }),
+				(3, MessageWeights { weight: 0, size: 0 }),
+			]
+			.into_iter()
+			.collect(),
+		);
+	}
+
+	#[test]
+	fn make_message_weights_map_fails_if_mid_messages_are_missing() {
+		assert!(matches!(
+			make_message_weights_map::<relay_rialto_client::Rialto>(vec![(1, 0, 0), (3, 0, 0)], 1..=3,),
+			Err(SubstrateError::Custom(_))
+		));
+	}
+
+	#[test]
+	fn make_message_weights_map_fails_if_tail_messages_are_missing() {
+		assert!(matches!(
+			make_message_weights_map::<relay_rialto_client::Rialto>(vec![(1, 0, 0), (2, 0, 0)], 1..=3,),
+			Err(SubstrateError::Custom(_))
+		));
+	}
+
+	#[test]
+	fn make_message_weights_map_fails_if_all_messages_are_missing() {
+		assert!(matches!(
+			make_message_weights_map::<relay_rialto_client::Rialto>(vec![], 1..=3),
+			Err(SubstrateError::Custom(_))
+		));
+	}
+}

polkadot/bridges/relays/bin-substrate/src/messages_target.rs

@@ -0,0 +1,232 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Substrate client as Substrate messages target. The chain we connect to should have
+//! runtime that implements `<BridgedChainName>HeaderApi` to allow bridging with
+//! <BridgedName> chain.
+
+use crate::messages_lane::SubstrateMessageLane;
+use crate::messages_source::read_client_state;
+use crate::on_demand_headers::OnDemandHeadersRelay;
+
+use async_trait::async_trait;
+use bp_messages::{LaneId, MessageNonce, UnrewardedRelayersState};
+use bp_runtime::InstanceId;
+use bridge_runtime_common::messages::source::FromBridgedChainMessagesDeliveryProof;
+use codec::{Decode, Encode};
+use frame_support::traits::Instance;
+use messages_relay::{
+	message_lane::{SourceHeaderIdOf, TargetHeaderIdOf},
+	message_lane_loop::{TargetClient, TargetClientState},
+};
+use pallet_bridge_messages::Config as MessagesConfig;
+use relay_substrate_client::{Chain, Client, Error as SubstrateError, HashOf};
+use relay_utils::{relay_loop::Client as RelayClient, BlockNumberBase};
+use sp_core::Bytes;
+use sp_runtime::{traits::Header as HeaderT, DeserializeOwned};
+use std::{marker::PhantomData, ops::RangeInclusive};
+
+/// Message receiving proof returned by the target Substrate node.
+pub type SubstrateMessagesReceivingProof<C> = (
+	UnrewardedRelayersState,
+	FromBridgedChainMessagesDeliveryProof<HashOf<C>>,
+);
+
+/// Substrate client as Substrate messages target.
+pub struct SubstrateMessagesTarget<C: Chain, P: SubstrateMessageLane, R, I> {
+	client: Client<C>,
+	lane: P,
+	lane_id: LaneId,
+	instance: InstanceId,
+	source_to_target_headers_relay: Option<OnDemandHeadersRelay<P::SourceChain>>,
+	_phantom: PhantomData<(R, I)>,
+}
+
+impl<C: Chain, P: SubstrateMessageLane, R, I> SubstrateMessagesTarget<C, P, R, I> {
+	/// Create new Substrate headers target.
+	pub fn new(
+		client: Client<C>,
+		lane: P,
+		lane_id: LaneId,
+		instance: InstanceId,
+		source_to_target_headers_relay: Option<OnDemandHeadersRelay<P::SourceChain>>,
+	) -> Self {
+		SubstrateMessagesTarget {
+			client,
+			lane,
+			lane_id,
+			instance,
+			source_to_target_headers_relay,
+			_phantom: Default::default(),
+		}
+	}
+}
+
+impl<C: Chain, P: SubstrateMessageLane, R, I> Clone for SubstrateMessagesTarget<C, P, R, I> {
+	fn clone(&self) -> Self {
+		Self {
+			client: self.client.clone(),
+			lane: self.lane.clone(),
+			lane_id: self.lane_id,
+			instance: self.instance,
+			source_to_target_headers_relay: self.source_to_target_headers_relay.clone(),
+			_phantom: Default::default(),
+		}
+	}
+}
+
+#[async_trait]
+impl<C, P, R, I> RelayClient for SubstrateMessagesTarget<C, P, R, I>
+where
+	C: Chain,
+	P: SubstrateMessageLane,
+	R: Send + Sync,
+	I: Send + Sync + Instance,
+{
+	type Error = SubstrateError;
+
+	async fn reconnect(&mut self) -> Result<(), SubstrateError> {
+		self.client.reconnect().await
+	}
+}
+
+#[async_trait]
+impl<C, P, R, I> TargetClient<P> for SubstrateMessagesTarget<C, P, R, I>
+where
+	C: Chain,
+	C::Header: DeserializeOwned,
+	C::Index: DeserializeOwned,
+	<C::Header as HeaderT>::Number: BlockNumberBase,
+	P: SubstrateMessageLane<
+		TargetChain = C,
+		MessagesReceivingProof = SubstrateMessagesReceivingProof<C>,
+		TargetHeaderNumber = <C::Header as HeaderT>::Number,
+		TargetHeaderHash = <C::Header as HeaderT>::Hash,
+	>,
+	P::SourceChain: Chain<Hash = P::SourceHeaderHash, BlockNumber = P::SourceHeaderNumber>,
+	P::SourceHeaderNumber: Decode,
+	P::SourceHeaderHash: Decode,
+	R: Send + Sync + MessagesConfig<I>,
+	I: Send + Sync + Instance,
+{
+	async fn state(&self) -> Result<TargetClientState<P>, SubstrateError> {
+		// we can't continue to deliver messages if target node is out of sync, because
+		// it may have already received (some of) messages that we're going to deliver
+		self.client.ensure_synced().await?;
+
+		read_client_state::<_, P::SourceHeaderHash, P::SourceHeaderNumber>(
+			&self.client,
+			P::BEST_FINALIZED_SOURCE_HEADER_ID_AT_TARGET,
+		)
+		.await
+	}
+
+	async fn latest_received_nonce(
+		&self,
+		id: TargetHeaderIdOf<P>,
+	) -> Result<(TargetHeaderIdOf<P>, MessageNonce), SubstrateError> {
+		let encoded_response = self
+			.client
+			.state_call(
+				P::INBOUND_LANE_LATEST_RECEIVED_NONCE_METHOD.into(),
+				Bytes(self.lane_id.encode()),
+				Some(id.1),
+			)
+			.await?;
+		let latest_received_nonce: MessageNonce =
+			Decode::decode(&mut &encoded_response.0[..]).map_err(SubstrateError::ResponseParseFailed)?;
+		Ok((id, latest_received_nonce))
+	}
+
+	async fn latest_confirmed_received_nonce(
+		&self,
+		id: TargetHeaderIdOf<P>,
+	) -> Result<(TargetHeaderIdOf<P>, MessageNonce), SubstrateError> {
+		let encoded_response = self
+			.client
+			.state_call(
+				P::INBOUND_LANE_LATEST_CONFIRMED_NONCE_METHOD.into(),
+				Bytes(self.lane_id.encode()),
+				Some(id.1),
+			)
+			.await?;
+		let latest_received_nonce: MessageNonce =
+			Decode::decode(&mut &encoded_response.0[..]).map_err(SubstrateError::ResponseParseFailed)?;
+		Ok((id, latest_received_nonce))
+	}
+
+	async fn unrewarded_relayers_state(
+		&self,
+		id: TargetHeaderIdOf<P>,
+	) -> Result<(TargetHeaderIdOf<P>, UnrewardedRelayersState), SubstrateError> {
+		let encoded_response = self
+			.client
+			.state_call(
+				P::INBOUND_LANE_UNREWARDED_RELAYERS_STATE.into(),
+				Bytes(self.lane_id.encode()),
+				Some(id.1),
+			)
+			.await?;
+		let unrewarded_relayers_state: UnrewardedRelayersState =
+			Decode::decode(&mut &encoded_response.0[..]).map_err(SubstrateError::ResponseParseFailed)?;
+		Ok((id, unrewarded_relayers_state))
+	}
+
+	async fn prove_messages_receiving(
+		&self,
+		id: TargetHeaderIdOf<P>,
+	) -> Result<(TargetHeaderIdOf<P>, P::MessagesReceivingProof), SubstrateError> {
+		let (id, relayers_state) = self.unrewarded_relayers_state(id).await?;
+		let inbound_data_key = pallet_bridge_messages::storage_keys::inbound_lane_data_key::<R, I>(&self.lane_id);
+		let proof = self
+			.client
+			.prove_storage(vec![inbound_data_key], id.1)
+			.await?
+			.iter_nodes()
+			.collect();
+		let proof = FromBridgedChainMessagesDeliveryProof {
+			bridged_header_hash: id.1,
+			storage_proof: proof,
+			lane: self.lane_id,
+		};
+		Ok((id, (relayers_state, proof)))
+	}
+
+	async fn submit_messages_proof(
+		&self,
+		generated_at_header: SourceHeaderIdOf<P>,
+		nonces: RangeInclusive<MessageNonce>,
+		proof: P::MessagesProof,
+	) -> Result<RangeInclusive<MessageNonce>, SubstrateError> {
+		self.client
+			.submit_signed_extrinsic(self.lane.target_transactions_author(), |transaction_nonce| {
+				self.lane.make_messages_delivery_transaction(
+					transaction_nonce,
+					generated_at_header,
+					nonces.clone(),
+					proof,
+				)
+			})
+			.await?;
+		Ok(nonces)
+	}
+
+	async fn require_source_header_on_target(&self, id: SourceHeaderIdOf<P>) {
+		if let Some(ref source_to_target_headers_relay) = self.source_to_target_headers_relay {
+			source_to_target_headers_relay.require_finalized_header(id);
+		}
+	}
+}

polkadot/bridges/relays/bin-substrate/src/on_demand_headers.rs

@@ -0,0 +1,255 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! On-demand Substrate -> Substrate headers relay.
+
+use crate::finality_pipeline::{SubstrateFinalitySyncPipeline, SubstrateFinalityToSubstrate};
+use crate::finality_target::SubstrateFinalityTarget;
+
+use bp_header_chain::justification::GrandpaJustification;
+use finality_relay::TargetClient as FinalityTargetClient;
+use futures::{
+	channel::{mpsc, oneshot},
+	select, FutureExt, StreamExt,
+};
+use num_traits::Zero;
+use relay_substrate_client::{BlockNumberOf, Chain, Client, HashOf, HeaderIdOf, SyncHeader};
+use relay_utils::{metrics::MetricsParams, BlockNumberBase, HeaderId};
+use std::fmt::Debug;
+
+/// On-demand Substrate <-> Substrate headers relay.
+///
+/// This relay may be started by messages whenever some other relay (e.g. messages relay) needs more
+/// headers to be relayed to continue its regular work. When enough headers are relayed, on-demand
+/// relay may be deactivated.
+#[derive(Clone)]
+pub struct OnDemandHeadersRelay<SourceChain: Chain> {
+	/// Background task name.
+	background_task_name: String,
+	/// Required headers to background sender.
+	required_header_tx: mpsc::Sender<HeaderId<SourceChain::Hash, SourceChain::BlockNumber>>,
+}
+
+impl<SourceChain: Chain> OnDemandHeadersRelay<SourceChain> {
+	/// Create new on-demand headers relay.
+	pub fn new<TargetChain: Chain, TargetSign>(
+		source_client: Client<SourceChain>,
+		target_client: Client<TargetChain>,
+		pipeline: SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>,
+	) -> Self
+	where
+		SourceChain: Chain + Debug,
+		SourceChain::BlockNumber: BlockNumberBase,
+		TargetChain: Chain + Debug,
+		TargetChain::BlockNumber: BlockNumberBase,
+		TargetSign: Clone + Send + Sync + 'static,
+		SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>: SubstrateFinalitySyncPipeline<
+			Hash = HashOf<SourceChain>,
+			Number = BlockNumberOf<SourceChain>,
+			Header = SyncHeader<SourceChain::Header>,
+			FinalityProof = GrandpaJustification<SourceChain::Header>,
+			TargetChain = TargetChain,
+		>,
+		SubstrateFinalityTarget<TargetChain, SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>>:
+			FinalityTargetClient<SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>>,
+	{
+		let (required_header_tx, required_header_rx) = mpsc::channel(1);
+		async_std::task::spawn(async move {
+			background_task(source_client, target_client, pipeline, required_header_rx).await;
+		});
+
+		let background_task_name = format!(
+			"{}-background",
+			on_demand_headers_relay_name::<SourceChain, TargetChain>()
+		);
+		OnDemandHeadersRelay {
+			background_task_name,
+			required_header_tx,
+		}
+	}
+
+	/// Someone is asking us to relay given finalized header.
+	pub fn require_finalized_header(&self, header_id: HeaderIdOf<SourceChain>) {
+		if let Err(error) = self.required_header_tx.clone().try_send(header_id) {
+			log::error!(
+				target: "bridge",
+				"Failed to send require header id {:?} to {:?}: {:?}",
+				header_id,
+				self.background_task_name,
+				error,
+			);
+		}
+	}
+}
+
+/// Background task that is responsible for starting and stopping headers relay when required.
+async fn background_task<SourceChain, TargetChain, TargetSign>(
+	source_client: Client<SourceChain>,
+	target_client: Client<TargetChain>,
+	pipeline: SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>,
+	mut required_header_rx: mpsc::Receiver<HeaderIdOf<SourceChain>>,
+) where
+	SourceChain: Chain + Debug,
+	SourceChain::BlockNumber: BlockNumberBase,
+	TargetChain: Chain + Debug,
+	TargetChain::BlockNumber: BlockNumberBase,
+	TargetSign: Clone + Send + Sync + 'static,
+	SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>: SubstrateFinalitySyncPipeline<
+		Hash = HashOf<SourceChain>,
+		Number = BlockNumberOf<SourceChain>,
+		Header = SyncHeader<SourceChain::Header>,
+		FinalityProof = GrandpaJustification<SourceChain::Header>,
+		TargetChain = TargetChain,
+	>,
+	SubstrateFinalityTarget<TargetChain, SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>>:
+		FinalityTargetClient<SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>>,
+{
+	let relay_task_name = on_demand_headers_relay_name::<SourceChain, TargetChain>();
+	let finality_target = SubstrateFinalityTarget::new(target_client.clone(), pipeline.clone());
+
+	let mut active_headers_relay = None;
+	let mut required_header_number = Zero::zero();
+	let mut relay_exited_rx = futures::future::pending().left_future();
+
+	loop {
+		// wait for next target block or for new required header
+		select! {
+			_ = async_std::task::sleep(TargetChain::AVERAGE_BLOCK_INTERVAL).fuse() => {},
+			required_header_id = required_header_rx.next() => {
+				match required_header_id {
+					Some(required_header_id) => {
+						if required_header_id.0 > required_header_number {
+							required_header_number = required_header_id.0;
+						}
+					},
+					None => {
+						// that's the only way to exit background task - to drop `required_header_tx`
+						break
+					},
+				}
+			},
+			_ = relay_exited_rx => {
+				// there could be a situation when we're receiving exit signals after we
+				// have already stopped relay or when we have already started new relay.
+				// but it isn't critical, because even if we'll accidentally stop new relay
+				// we'll restart it almost immediately
+				stop_on_demand_headers_relay(active_headers_relay.take()).await;
+			},
+		}
+
+		// read best finalized source block from target
+		let available_header_number = match finality_target.best_finalized_source_block_number().await {
+			Ok(available_header_number) => available_header_number,
+			Err(error) => {
+				log::error!(
+					target: "bridge",
+					"Failed to read best finalized {} header from {} in {} relay: {:?}",
+					SourceChain::NAME,
+					TargetChain::NAME,
+					relay_task_name,
+					error,
+				);
+
+				// we don't know what's happening with target client, so better to stop on-demand relay than
+				// submit unneeded transactions
+				// => assume that required header is known to the target node
+				required_header_number
+			}
+		};
+
+		// start or stop headers relay if required
+		let activate = required_header_number > available_header_number;
+		match (activate, active_headers_relay.is_some()) {
+			(true, false) => {
+				let (relay_exited_tx, new_relay_exited_rx) = oneshot::channel();
+				active_headers_relay = start_on_demand_headers_relay(
+					relay_task_name.clone(),
+					relay_exited_tx,
+					source_client.clone(),
+					target_client.clone(),
+					pipeline.clone(),
+				);
+				if active_headers_relay.is_some() {
+					relay_exited_rx = new_relay_exited_rx.right_future();
+				}
+			}
+			(false, true) => {
+				stop_on_demand_headers_relay(active_headers_relay.take()).await;
+			}
+			_ => (),
+		}
+	}
+}
+
+/// On-demand headers relay task name.
+fn on_demand_headers_relay_name<SourceChain: Chain, TargetChain: Chain>() -> String {
+	format!("on-demand-{}-to-{}", SourceChain::NAME, TargetChain::NAME)
+}
+
+/// Start on-demand headers relay task.
+fn start_on_demand_headers_relay<SourceChain: Chain, TargetChain: Chain, TargetSign>(
+	task_name: String,
+	relay_exited_tx: oneshot::Sender<()>,
+	source_client: Client<SourceChain>,
+	target_client: Client<TargetChain>,
+	pipeline: SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>,
+) -> Option<async_std::task::JoinHandle<()>>
+where
+	SourceChain::BlockNumber: BlockNumberBase,
+	SubstrateFinalityToSubstrate<SourceChain, TargetChain, TargetSign>: SubstrateFinalitySyncPipeline<
+		Hash = HashOf<SourceChain>,
+		Number = BlockNumberOf<SourceChain>,
+		Header = SyncHeader<SourceChain::Header>,
+		FinalityProof = GrandpaJustification<SourceChain::Header>,
+		TargetChain = TargetChain,
+	>,
+	TargetSign: 'static,
+{
+	let headers_relay_future =
+		crate::finality_pipeline::run(pipeline, source_client, target_client, MetricsParams::disabled());
+	let closure_task_name = task_name.clone();
+	async_std::task::Builder::new()
+		.name(task_name.clone())
+		.spawn(async move {
+			log::info!(target: "bridge", "Starting {} headers relay", closure_task_name);
+			let result = headers_relay_future.await;
+			log::trace!(target: "bridge", "{} headers relay has exited. Result: {:?}", closure_task_name, result);
+			let _ = relay_exited_tx.send(());
+		})
+		.map_err(|error| {
+			log::error!(
+				target: "bridge",
+				"Failed to start {} relay: {:?}",
+				task_name,
+				error,
+			);
+		})
+		.ok()
+}
+
+/// Stop on-demand headers relay task.
+async fn stop_on_demand_headers_relay(task: Option<async_std::task::JoinHandle<()>>) {
+	if let Some(task) = task {
+		let task_name = task
+			.task()
+			.name()
+			.expect("on-demand tasks are always started with name; qed")
+			.to_string();
+		log::trace!(target: "bridge", "Cancelling {} headers relay", task_name);
+		task.cancel().await;
+		log::info!(target: "bridge", "Cancelled {} headers relay", task_name);
+	}
+}

polkadot/bridges/relays/client-ethereum/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "relay-ethereum-client"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+bp-eth-poa = { path = "../../primitives/ethereum-poa" }
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+headers-relay = { path = "../headers" }
+hex-literal = "0.3"
+jsonrpsee-proc-macros = "=0.2.0-alpha.5"
+jsonrpsee-ws-client = "=0.2.0-alpha.5"
+libsecp256k1 = { version = "0.3.4", default-features = false, features = ["hmac"] }
+log = "0.4.11"
+relay-utils = { path = "../utils" }
+web3 = { version = "0.15", git = "https://github.com/tomusdrw/rust-web3", branch ="td-ethabi", default-features = false }

polkadot/bridges/relays/client-ethereum/src/client.rs

@@ -0,0 +1,172 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::rpc::Ethereum;
+use crate::types::{
+	Address, Bytes, CallRequest, Header, HeaderWithTransactions, Receipt, SignedRawTx, SyncState, Transaction,
+	TransactionHash, H256, U256,
+};
+use crate::{ConnectionParams, Error, Result};
+
+use jsonrpsee_ws_client::{WsClient as RpcClient, WsClientBuilder as RpcClientBuilder};
+use std::sync::Arc;
+
+/// Number of headers missing from the Ethereum node for us to consider node not synced.
+const MAJOR_SYNC_BLOCKS: u64 = 5;
+
+/// The client used to interact with an Ethereum node through RPC.
+#[derive(Clone)]
+pub struct Client {
+	params: ConnectionParams,
+	client: Arc<RpcClient>,
+}
+
+impl Client {
+	/// Create a new Ethereum RPC Client.
+	pub async fn new(params: ConnectionParams) -> Result<Self> {
+		Ok(Self {
+			client: Self::build_client(&params).await?,
+			params,
+		})
+	}
+
+	/// Build client to use in connection.
+	async fn build_client(params: &ConnectionParams) -> Result<Arc<RpcClient>> {
+		let uri = format!("ws://{}:{}", params.host, params.port);
+		let client = RpcClientBuilder::default().build(&uri).await?;
+		Ok(Arc::new(client))
+	}
+
+	/// Reopen client connection.
+	pub async fn reconnect(&mut self) -> Result<()> {
+		self.client = Self::build_client(&self.params).await?;
+		Ok(())
+	}
+}
+
+impl Client {
+	/// Returns true if client is connected to at least one peer and is in synced state.
+	pub async fn ensure_synced(&self) -> Result<()> {
+		match Ethereum::syncing(&*self.client).await? {
+			SyncState::NotSyncing => Ok(()),
+			SyncState::Syncing(syncing) => {
+				let missing_headers = syncing.highest_block.saturating_sub(syncing.current_block);
+				if missing_headers > MAJOR_SYNC_BLOCKS.into() {
+					return Err(Error::ClientNotSynced(missing_headers));
+				}
+
+				Ok(())
+			}
+		}
+	}
+
+	/// Estimate gas usage for the given call.
+	pub async fn estimate_gas(&self, call_request: CallRequest) -> Result<U256> {
+		Ok(Ethereum::estimate_gas(&*self.client, call_request).await?)
+	}
+
+	/// Retrieve number of the best known block from the Ethereum node.
+	pub async fn best_block_number(&self) -> Result<u64> {
+		Ok(Ethereum::block_number(&*self.client).await?.as_u64())
+	}
+
+	/// Retrieve number of the best known block from the Ethereum node.
+	pub async fn header_by_number(&self, block_number: u64) -> Result<Header> {
+		let get_full_tx_objects = false;
+		let header = Ethereum::get_block_by_number(&*self.client, block_number, get_full_tx_objects).await?;
+		match header.number.is_some() && header.hash.is_some() && header.logs_bloom.is_some() {
+			true => Ok(header),
+			false => Err(Error::IncompleteHeader),
+		}
+	}
+
+	/// Retrieve block header by its hash from Ethereum node.
+	pub async fn header_by_hash(&self, hash: H256) -> Result<Header> {
+		let get_full_tx_objects = false;
+		let header = Ethereum::get_block_by_hash(&*self.client, hash, get_full_tx_objects).await?;
+		match header.number.is_some() && header.hash.is_some() && header.logs_bloom.is_some() {
+			true => Ok(header),
+			false => Err(Error::IncompleteHeader),
+		}
+	}
+
+	/// Retrieve block header and its transactions by its number from Ethereum node.
+	pub async fn header_by_number_with_transactions(&self, number: u64) -> Result<HeaderWithTransactions> {
+		let get_full_tx_objects = true;
+		let header =
+			Ethereum::get_block_by_number_with_transactions(&*self.client, number, get_full_tx_objects).await?;
+
+		let is_complete_header = header.number.is_some() && header.hash.is_some() && header.logs_bloom.is_some();
+		if !is_complete_header {
+			return Err(Error::IncompleteHeader);
+		}
+
+		let is_complete_transactions = header.transactions.iter().all(|tx| tx.raw.is_some());
+		if !is_complete_transactions {
+			return Err(Error::IncompleteTransaction);
+		}
+
+		Ok(header)
+	}
+
+	/// Retrieve block header and its transactions by its hash from Ethereum node.
+	pub async fn header_by_hash_with_transactions(&self, hash: H256) -> Result<HeaderWithTransactions> {
+		let get_full_tx_objects = true;
+		let header = Ethereum::get_block_by_hash_with_transactions(&*self.client, hash, get_full_tx_objects).await?;
+
+		let is_complete_header = header.number.is_some() && header.hash.is_some() && header.logs_bloom.is_some();
+		if !is_complete_header {
+			return Err(Error::IncompleteHeader);
+		}
+
+		let is_complete_transactions = header.transactions.iter().all(|tx| tx.raw.is_some());
+		if !is_complete_transactions {
+			return Err(Error::IncompleteTransaction);
+		}
+
+		Ok(header)
+	}
+
+	/// Retrieve transaction by its hash from Ethereum node.
+	pub async fn transaction_by_hash(&self, hash: H256) -> Result<Option<Transaction>> {
+		Ok(Ethereum::transaction_by_hash(&*self.client, hash).await?)
+	}
+
+	/// Retrieve transaction receipt by transaction hash.
+	pub async fn transaction_receipt(&self, transaction_hash: H256) -> Result<Receipt> {
+		Ok(Ethereum::get_transaction_receipt(&*self.client, transaction_hash).await?)
+	}
+
+	/// Get the nonce of the given account.
+	pub async fn account_nonce(&self, address: Address) -> Result<U256> {
+		Ok(Ethereum::get_transaction_count(&*self.client, address).await?)
+	}
+
+	/// Submit an Ethereum transaction.
+	///
+	/// The transaction must already be signed before sending it through this method.
+	pub async fn submit_transaction(&self, signed_raw_tx: SignedRawTx) -> Result<TransactionHash> {
+		let transaction = Bytes(signed_raw_tx);
+		let tx_hash = Ethereum::submit_transaction(&*self.client, transaction).await?;
+		log::trace!(target: "bridge", "Sent transaction to Ethereum node: {:?}", tx_hash);
+		Ok(tx_hash)
+	}
+
+	/// Call Ethereum smart contract.
+	pub async fn eth_call(&self, call_transaction: CallRequest) -> Result<Bytes> {
+		Ok(Ethereum::call(&*self.client, call_transaction).await?)
+	}
+}

polkadot/bridges/relays/client-ethereum/src/error.rs

@@ -0,0 +1,86 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Ethereum node RPC errors.
+
+use crate::types::U256;
+
+use jsonrpsee_ws_client::Error as RpcError;
+use relay_utils::MaybeConnectionError;
+
+/// Result type used by Ethereum client.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Errors that can occur only when interacting with
+/// an Ethereum node through RPC.
+#[derive(Debug)]
+pub enum Error {
+	/// An error that can occur when making an HTTP request to
+	/// an JSON-RPC client.
+	RpcError(RpcError),
+	/// Failed to parse response.
+	ResponseParseFailed(String),
+	/// We have received a header with missing fields.
+	IncompleteHeader,
+	/// We have received a transaction missing a `raw` field.
+	IncompleteTransaction,
+	/// An invalid Substrate block number was received from
+	/// an Ethereum node.
+	InvalidSubstrateBlockNumber,
+	/// An invalid index has been received from an Ethereum node.
+	InvalidIncompleteIndex,
+	/// The client we're connected to is not synced, so we can't rely on its state. Contains
+	/// number of unsynced headers.
+	ClientNotSynced(U256),
+}
+
+impl From<RpcError> for Error {
+	fn from(error: RpcError) -> Self {
+		Error::RpcError(error)
+	}
+}
+
+impl MaybeConnectionError for Error {
+	fn is_connection_error(&self) -> bool {
+		matches!(
+			*self,
+			Error::RpcError(RpcError::TransportError(_))
+				// right now if connection to the ws server is dropped (after it is already established),
+				// we're getting this error
+				| Error::RpcError(RpcError::Internal(_))
+				| Error::ClientNotSynced(_),
+		)
+	}
+}
+
+impl ToString for Error {
+	fn to_string(&self) -> String {
+		match self {
+			Self::RpcError(e) => e.to_string(),
+			Self::ResponseParseFailed(e) => e.to_string(),
+			Self::IncompleteHeader => {
+				"Incomplete Ethereum Header Received (missing some of required fields - hash, number, logs_bloom)"
+					.to_string()
+			}
+			Self::IncompleteTransaction => "Incomplete Ethereum Transaction (missing required field - raw)".to_string(),
+			Self::InvalidSubstrateBlockNumber => "Received an invalid Substrate block from Ethereum Node".to_string(),
+			Self::InvalidIncompleteIndex => "Received an invalid incomplete index from Ethereum Node".to_string(),
+			Self::ClientNotSynced(missing_headers) => {
+				format!("Ethereum client is not synced: syncing {} headers", missing_headers)
+			}
+		}
+	}
+}

polkadot/bridges/relays/client-ethereum/src/lib.rs

@@ -0,0 +1,48 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Tools to interact with (Open) Ethereum node using RPC methods.
+
+#![warn(missing_docs)]
+
+mod client;
+mod error;
+mod rpc;
+mod sign;
+
+pub use crate::client::Client;
+pub use crate::error::{Error, Result};
+pub use crate::sign::{sign_and_submit_transaction, SigningParams};
+
+pub mod types;
+
+/// Ethereum-over-websocket connection params.
+#[derive(Debug, Clone)]
+pub struct ConnectionParams {
+	/// Websocket server hostname.
+	pub host: String,
+	/// Websocket server TCP port.
+	pub port: u16,
+}
+
+impl Default for ConnectionParams {
+	fn default() -> Self {
+		ConnectionParams {
+			host: "localhost".into(),
+			port: 8546,
+		}
+	}
+}

polkadot/bridges/relays/client-ethereum/src/rpc.rs

@@ -0,0 +1,51 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Ethereum node RPC interface.
+
+use crate::types::{
+	Address, Bytes, CallRequest, Header, HeaderWithTransactions, Receipt, SyncState, Transaction, TransactionHash,
+	H256, U256, U64,
+};
+
+jsonrpsee_proc_macros::rpc_client_api! {
+	pub(crate) Ethereum {
+		#[rpc(method = "eth_syncing", positional_params)]
+		fn syncing() -> SyncState;
+		#[rpc(method = "eth_estimateGas", positional_params)]
+		fn estimate_gas(call_request: CallRequest) -> U256;
+		#[rpc(method = "eth_blockNumber", positional_params)]
+		fn block_number() -> U64;
+		#[rpc(method = "eth_getBlockByNumber", positional_params)]
+		fn get_block_by_number(block_number: U64, full_tx_objs: bool) -> Header;
+		#[rpc(method = "eth_getBlockByHash", positional_params)]
+		fn get_block_by_hash(hash: H256, full_tx_objs: bool) -> Header;
+		#[rpc(method = "eth_getBlockByNumber", positional_params)]
+		fn get_block_by_number_with_transactions(number: U64, full_tx_objs: bool) -> HeaderWithTransactions;
+		#[rpc(method = "eth_getBlockByHash", positional_params)]
+		fn get_block_by_hash_with_transactions(hash: H256, full_tx_objs: bool) -> HeaderWithTransactions;
+		#[rpc(method = "eth_getTransactionByHash", positional_params)]
+		fn transaction_by_hash(hash: H256) -> Option<Transaction>;
+		#[rpc(method = "eth_getTransactionReceipt", positional_params)]
+		fn get_transaction_receipt(transaction_hash: H256) -> Receipt;
+		#[rpc(method = "eth_getTransactionCount", positional_params)]
+		fn get_transaction_count(address: Address) -> U256;
+		#[rpc(method = "eth_submitTransaction", positional_params)]
+		fn submit_transaction(transaction: Bytes) -> TransactionHash;
+		#[rpc(method = "eth_call", positional_params)]
+		fn call(transaction_call: CallRequest) -> Bytes;
+	}
+}

polkadot/bridges/relays/client-ethereum/src/sign.rs

@@ -0,0 +1,85 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::types::{Address, CallRequest, U256};
+use crate::{Client, Result};
+use bp_eth_poa::signatures::{secret_to_address, SignTransaction};
+use hex_literal::hex;
+use secp256k1::SecretKey;
+
+/// Ethereum signing params.
+#[derive(Clone, Debug)]
+pub struct SigningParams {
+	/// Ethereum chain id.
+	pub chain_id: u64,
+	/// Ethereum transactions signer.
+	pub signer: SecretKey,
+	/// Gas price we agree to pay.
+	pub gas_price: U256,
+}
+
+impl Default for SigningParams {
+	fn default() -> Self {
+		SigningParams {
+			chain_id: 0x11, // Parity dev chain
+			// account that has a lot of ether when we run instant seal engine
+			// address: 0x00a329c0648769a73afac7f9381e08fb43dbea72
+			// secret: 0x4d5db4107d237df6a3d58ee5f70ae63d73d7658d4026f2eefd2f204c81682cb7
+			signer: SecretKey::parse(&hex!(
+				"4d5db4107d237df6a3d58ee5f70ae63d73d7658d4026f2eefd2f204c81682cb7"
+			))
+			.expect("secret is hardcoded, thus valid; qed"),
+			gas_price: 8_000_000_000u64.into(), // 8 Gwei
+		}
+	}
+}
+
+/// Sign and submit tranaction using given Ethereum client.
+pub async fn sign_and_submit_transaction(
+	client: &Client,
+	params: &SigningParams,
+	contract_address: Option<Address>,
+	nonce: Option<U256>,
+	double_gas: bool,
+	encoded_call: Vec<u8>,
+) -> Result<()> {
+	let nonce = if let Some(n) = nonce {
+		n
+	} else {
+		let address: Address = secret_to_address(&params.signer);
+		client.account_nonce(address).await?
+	};
+
+	let call_request = CallRequest {
+		to: contract_address,
+		data: Some(encoded_call.clone().into()),
+		..Default::default()
+	};
+	let gas = client.estimate_gas(call_request).await?;
+
+	let raw_transaction = bp_eth_poa::UnsignedTransaction {
+		nonce,
+		to: contract_address,
+		value: U256::zero(),
+		gas: if double_gas { gas.saturating_mul(2.into()) } else { gas },
+		gas_price: params.gas_price,
+		payload: encoded_call,
+	}
+	.sign_by(&params.signer, Some(params.chain_id));
+
+	let _ = client.submit_transaction(raw_transaction).await?;
+	Ok(())
+}

polkadot/bridges/relays/client-ethereum/src/types.rs

@@ -0,0 +1,80 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Common types that are used in relay <-> Ethereum node communications.
+
+use headers_relay::sync_types::SourceHeader;
+
+pub use web3::types::{Address, Bytes, CallRequest, SyncState, H256, U128, U256, U64};
+
+/// When header is just received from the Ethereum node, we check that it has
+/// both number and hash fields filled.
+pub const HEADER_ID_PROOF: &str = "checked on retrieval; qed";
+
+/// Ethereum transaction hash type.
+pub type HeaderHash = H256;
+
+/// Ethereum transaction hash type.
+pub type TransactionHash = H256;
+
+/// Ethereum transaction type.
+pub type Transaction = web3::types::Transaction;
+
+/// Ethereum header type.
+pub type Header = web3::types::Block<H256>;
+
+/// Ethereum header type used in headers sync.
+#[derive(Clone, Debug, PartialEq)]
+pub struct SyncHeader(Header);
+
+impl std::ops::Deref for SyncHeader {
+	type Target = Header;
+
+	fn deref(&self) -> &Self::Target {
+		&self.0
+	}
+}
+
+/// Ethereum header with transactions type.
+pub type HeaderWithTransactions = web3::types::Block<Transaction>;
+
+/// Ethereum transaction receipt type.
+pub type Receipt = web3::types::TransactionReceipt;
+
+/// Ethereum header ID.
+pub type HeaderId = relay_utils::HeaderId<H256, u64>;
+
+/// A raw Ethereum transaction that's been signed.
+pub type SignedRawTx = Vec<u8>;
+
+impl From<Header> for SyncHeader {
+	fn from(header: Header) -> Self {
+		Self(header)
+	}
+}
+
+impl SourceHeader<H256, u64> for SyncHeader {
+	fn id(&self) -> HeaderId {
+		relay_utils::HeaderId(
+			self.number.expect(HEADER_ID_PROOF).as_u64(),
+			self.hash.expect(HEADER_ID_PROOF),
+		)
+	}
+
+	fn parent_id(&self) -> HeaderId {
+		relay_utils::HeaderId(self.number.expect(HEADER_ID_PROOF).as_u64() - 1, self.parent_hash)
+	}
+}

polkadot/bridges/relays/client-kusama/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "relay-kusama-client"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+headers-relay = { path = "../headers" }
+relay-substrate-client = { path = "../client-substrate" }
+relay-utils = { path = "../utils" }
+
+# Bridge dependencies
+
+bp-kusama = { path = "../../primitives/chain-kusama" }
+
+# Substrate Dependencies
+
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "master" }
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "master" }
+pallet-transaction-payment = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-keyring = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }

polkadot/bridges/relays/client-kusama/src/lib.rs

@@ -0,0 +1,47 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Types used to connect to the Kusama chain.
+
+use relay_substrate_client::{Chain, ChainBase};
+use std::time::Duration;
+
+/// Kusama header id.
+pub type HeaderId = relay_utils::HeaderId<bp_kusama::Hash, bp_kusama::BlockNumber>;
+
+/// Kusama chain definition
+#[derive(Debug, Clone, Copy)]
+pub struct Kusama;
+
+impl ChainBase for Kusama {
+	type BlockNumber = bp_kusama::BlockNumber;
+	type Hash = bp_kusama::Hash;
+	type Hasher = bp_kusama::Hasher;
+	type Header = bp_kusama::Header;
+}
+
+impl Chain for Kusama {
+	const NAME: &'static str = "Kusama";
+	const AVERAGE_BLOCK_INTERVAL: Duration = Duration::from_secs(6);
+
+	type AccountId = bp_kusama::AccountId;
+	type Index = bp_kusama::Nonce;
+	type SignedBlock = bp_kusama::SignedBlock;
+	type Call = ();
+}
+
+/// Kusama header type used in headers sync.
+pub type SyncHeader = relay_substrate_client::SyncHeader<bp_kusama::Header>;

polkadot/bridges/relays/client-millau/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "relay-millau-client"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+headers-relay = { path = "../headers" }
+relay-substrate-client = { path = "../client-substrate" }
+relay-utils = { path = "../utils" }
+
+# Supported Chains
+
+millau-runtime = { path = "../../bin/millau/runtime" }
+
+# Substrate Dependencies
+
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "master" }
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "master" }
+pallet-transaction-payment = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-keyring = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }

polkadot/bridges/relays/client-millau/src/lib.rs

@@ -0,0 +1,104 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Types used to connect to the Millau-Substrate chain.
+
+use codec::Encode;
+use relay_substrate_client::{Chain, ChainBase, ChainWithBalances, TransactionSignScheme};
+use sp_core::{storage::StorageKey, Pair};
+use sp_runtime::{generic::SignedPayload, traits::IdentifyAccount};
+use std::time::Duration;
+
+/// Millau header id.
+pub type HeaderId = relay_utils::HeaderId<millau_runtime::Hash, millau_runtime::BlockNumber>;
+
+/// Millau chain definition.
+#[derive(Debug, Clone, Copy)]
+pub struct Millau;
+
+impl ChainBase for Millau {
+	type BlockNumber = millau_runtime::BlockNumber;
+	type Hash = millau_runtime::Hash;
+	type Hasher = millau_runtime::Hashing;
+	type Header = millau_runtime::Header;
+}
+
+impl Chain for Millau {
+	const NAME: &'static str = "Millau";
+	const AVERAGE_BLOCK_INTERVAL: Duration = Duration::from_secs(5);
+
+	type AccountId = millau_runtime::AccountId;
+	type Index = millau_runtime::Index;
+	type SignedBlock = millau_runtime::SignedBlock;
+	type Call = millau_runtime::Call;
+}
+
+impl ChainWithBalances for Millau {
+	type NativeBalance = millau_runtime::Balance;
+
+	fn account_info_storage_key(account_id: &Self::AccountId) -> StorageKey {
+		use frame_support::storage::generator::StorageMap;
+		StorageKey(frame_system::Account::<millau_runtime::Runtime>::storage_map_final_key(
+			account_id,
+		))
+	}
+}
+
+impl TransactionSignScheme for Millau {
+	type Chain = Millau;
+	type AccountKeyPair = sp_core::sr25519::Pair;
+	type SignedTransaction = millau_runtime::UncheckedExtrinsic;
+
+	fn sign_transaction(
+		genesis_hash: <Self::Chain as ChainBase>::Hash,
+		signer: &Self::AccountKeyPair,
+		signer_nonce: <Self::Chain as Chain>::Index,
+		call: <Self::Chain as Chain>::Call,
+	) -> Self::SignedTransaction {
+		let raw_payload = SignedPayload::from_raw(
+			call,
+			(
+				frame_system::CheckSpecVersion::<millau_runtime::Runtime>::new(),
+				frame_system::CheckTxVersion::<millau_runtime::Runtime>::new(),
+				frame_system::CheckGenesis::<millau_runtime::Runtime>::new(),
+				frame_system::CheckEra::<millau_runtime::Runtime>::from(sp_runtime::generic::Era::Immortal),
+				frame_system::CheckNonce::<millau_runtime::Runtime>::from(signer_nonce),
+				frame_system::CheckWeight::<millau_runtime::Runtime>::new(),
+				pallet_transaction_payment::ChargeTransactionPayment::<millau_runtime::Runtime>::from(0),
+			),
+			(
+				millau_runtime::VERSION.spec_version,
+				millau_runtime::VERSION.transaction_version,
+				genesis_hash,
+				genesis_hash,
+				(),
+				(),
+				(),
+			),
+		);
+		let signature = raw_payload.using_encoded(|payload| signer.sign(payload));
+		let signer: sp_runtime::MultiSigner = signer.public().into();
+		let (call, extra, _) = raw_payload.deconstruct();
+
+		millau_runtime::UncheckedExtrinsic::new_signed(call, signer.into_account(), signature.into(), extra)
+	}
+}
+
+/// Millau signing params.
+pub type SigningParams = sp_core::sr25519::Pair;
+
+/// Millau header type used in headers sync.
+pub type SyncHeader = relay_substrate_client::SyncHeader<millau_runtime::Header>;

polkadot/bridges/relays/client-polkadot/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "relay-polkadot-client"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+headers-relay = { path = "../headers" }
+relay-substrate-client = { path = "../client-substrate" }
+relay-utils = { path = "../utils" }
+
+# Bridge dependencies
+
+bp-polkadot = { path = "../../primitives/chain-polkadot" }
+
+# Substrate Dependencies
+
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "master" }
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "master" }
+pallet-transaction-payment = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-keyring = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }

polkadot/bridges/relays/client-polkadot/src/lib.rs

@@ -0,0 +1,47 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Types used to connect to the Polkadot chain.
+
+use relay_substrate_client::{Chain, ChainBase};
+use std::time::Duration;
+
+/// Polkadot header id.
+pub type HeaderId = relay_utils::HeaderId<bp_polkadot::Hash, bp_polkadot::BlockNumber>;
+
+/// Polkadot chain definition
+#[derive(Debug, Clone, Copy)]
+pub struct Polkadot;
+
+impl ChainBase for Polkadot {
+	type BlockNumber = bp_polkadot::BlockNumber;
+	type Hash = bp_polkadot::Hash;
+	type Hasher = bp_polkadot::Hasher;
+	type Header = bp_polkadot::Header;
+}
+
+impl Chain for Polkadot {
+	const NAME: &'static str = "Polkadot";
+	const AVERAGE_BLOCK_INTERVAL: Duration = Duration::from_secs(6);
+
+	type AccountId = bp_polkadot::AccountId;
+	type Index = bp_polkadot::Nonce;
+	type SignedBlock = bp_polkadot::SignedBlock;
+	type Call = ();
+}
+
+/// Polkadot header type used in headers sync.
+pub type SyncHeader = relay_substrate_client::SyncHeader<bp_polkadot::Header>;

polkadot/bridges/relays/client-rialto/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "relay-rialto-client"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+headers-relay = { path = "../headers" }
+relay-substrate-client = { path = "../client-substrate" }
+relay-utils = { path = "../utils" }
+
+# Bridge dependencies
+
+rialto-runtime = { path = "../../bin/rialto/runtime" }
+
+# Substrate Dependencies
+
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "master" }
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "master" }
+pallet-transaction-payment = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-keyring = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }

polkadot/bridges/relays/client-rialto/src/lib.rs

@@ -0,0 +1,104 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Types used to connect to the Rialto-Substrate chain.
+
+use codec::Encode;
+use relay_substrate_client::{Chain, ChainBase, ChainWithBalances, TransactionSignScheme};
+use sp_core::{storage::StorageKey, Pair};
+use sp_runtime::{generic::SignedPayload, traits::IdentifyAccount};
+use std::time::Duration;
+
+/// Rialto header id.
+pub type HeaderId = relay_utils::HeaderId<rialto_runtime::Hash, rialto_runtime::BlockNumber>;
+
+/// Rialto chain definition
+#[derive(Debug, Clone, Copy)]
+pub struct Rialto;
+
+impl ChainBase for Rialto {
+	type BlockNumber = rialto_runtime::BlockNumber;
+	type Hash = rialto_runtime::Hash;
+	type Hasher = rialto_runtime::Hashing;
+	type Header = rialto_runtime::Header;
+}
+
+impl Chain for Rialto {
+	const NAME: &'static str = "Rialto";
+	const AVERAGE_BLOCK_INTERVAL: Duration = Duration::from_secs(5);
+
+	type AccountId = rialto_runtime::AccountId;
+	type Index = rialto_runtime::Index;
+	type SignedBlock = rialto_runtime::SignedBlock;
+	type Call = rialto_runtime::Call;
+}
+
+impl ChainWithBalances for Rialto {
+	type NativeBalance = rialto_runtime::Balance;
+
+	fn account_info_storage_key(account_id: &Self::AccountId) -> StorageKey {
+		use frame_support::storage::generator::StorageMap;
+		StorageKey(frame_system::Account::<rialto_runtime::Runtime>::storage_map_final_key(
+			account_id,
+		))
+	}
+}
+
+impl TransactionSignScheme for Rialto {
+	type Chain = Rialto;
+	type AccountKeyPair = sp_core::sr25519::Pair;
+	type SignedTransaction = rialto_runtime::UncheckedExtrinsic;
+
+	fn sign_transaction(
+		genesis_hash: <Self::Chain as ChainBase>::Hash,
+		signer: &Self::AccountKeyPair,
+		signer_nonce: <Self::Chain as Chain>::Index,
+		call: <Self::Chain as Chain>::Call,
+	) -> Self::SignedTransaction {
+		let raw_payload = SignedPayload::from_raw(
+			call,
+			(
+				frame_system::CheckSpecVersion::<rialto_runtime::Runtime>::new(),
+				frame_system::CheckTxVersion::<rialto_runtime::Runtime>::new(),
+				frame_system::CheckGenesis::<rialto_runtime::Runtime>::new(),
+				frame_system::CheckEra::<rialto_runtime::Runtime>::from(sp_runtime::generic::Era::Immortal),
+				frame_system::CheckNonce::<rialto_runtime::Runtime>::from(signer_nonce),
+				frame_system::CheckWeight::<rialto_runtime::Runtime>::new(),
+				pallet_transaction_payment::ChargeTransactionPayment::<rialto_runtime::Runtime>::from(0),
+			),
+			(
+				rialto_runtime::VERSION.spec_version,
+				rialto_runtime::VERSION.transaction_version,
+				genesis_hash,
+				genesis_hash,
+				(),
+				(),
+				(),
+			),
+		);
+		let signature = raw_payload.using_encoded(|payload| signer.sign(payload));
+		let signer: sp_runtime::MultiSigner = signer.public().into();
+		let (call, extra, _) = raw_payload.deconstruct();
+
+		rialto_runtime::UncheckedExtrinsic::new_signed(call, signer.into_account(), signature.into(), extra)
+	}
+}
+
+/// Rialto signing params.
+pub type SigningParams = sp_core::sr25519::Pair;
+
+/// Rialto header type used in headers sync.
+pub type SyncHeader = relay_substrate_client::SyncHeader<rialto_runtime::Header>;

polkadot/bridges/relays/client-rococo/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "relay-rococo-client"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+headers-relay = { path = "../headers" }
+relay-substrate-client = { path = "../client-substrate" }
+relay-utils = { path = "../utils" }
+
+# Bridge dependencies
+bp-rococo = { path = "../../primitives/chain-rococo" }
+
+# Substrate Dependencies
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "master" }
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "master" }
+pallet-transaction-payment = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-keyring = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }

polkadot/bridges/relays/client-rococo/src/lib.rs

@@ -0,0 +1,97 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Types used to connect to the Rococo-Substrate chain.
+
+use codec::Encode;
+use relay_substrate_client::{Chain, ChainBase, ChainWithBalances, TransactionSignScheme};
+use sp_core::{storage::StorageKey, Pair};
+use sp_runtime::{generic::SignedPayload, traits::IdentifyAccount};
+use std::time::Duration;
+
+/// Rococo header id.
+pub type HeaderId = relay_utils::HeaderId<bp_rococo::Hash, bp_rococo::BlockNumber>;
+
+/// Rococo header type used in headers sync.
+pub type SyncHeader = relay_substrate_client::SyncHeader<bp_rococo::Header>;
+
+/// Rococo chain definition
+#[derive(Debug, Clone, Copy)]
+pub struct Rococo;
+
+impl ChainBase for Rococo {
+	type BlockNumber = bp_rococo::BlockNumber;
+	type Hash = bp_rococo::Hash;
+	type Hasher = bp_rococo::Hashing;
+	type Header = bp_rococo::Header;
+}
+
+impl Chain for Rococo {
+	const NAME: &'static str = "Rococo";
+	const AVERAGE_BLOCK_INTERVAL: Duration = Duration::from_secs(6);
+
+	type AccountId = bp_rococo::AccountId;
+	type Index = bp_rococo::Index;
+	type SignedBlock = bp_rococo::SignedBlock;
+	type Call = bp_rococo::Call;
+}
+
+impl ChainWithBalances for Rococo {
+	type NativeBalance = bp_rococo::Balance;
+
+	fn account_info_storage_key(account_id: &Self::AccountId) -> StorageKey {
+		StorageKey(bp_rococo::account_info_storage_key(account_id))
+	}
+}
+
+impl TransactionSignScheme for Rococo {
+	type Chain = Rococo;
+	type AccountKeyPair = sp_core::sr25519::Pair;
+	type SignedTransaction = bp_rococo::UncheckedExtrinsic;
+
+	fn sign_transaction(
+		genesis_hash: <Self::Chain as ChainBase>::Hash,
+		signer: &Self::AccountKeyPair,
+		signer_nonce: <Self::Chain as Chain>::Index,
+		call: <Self::Chain as Chain>::Call,
+	) -> Self::SignedTransaction {
+		let raw_payload = SignedPayload::new(
+			call,
+			bp_rococo::SignedExtensions::new(
+				bp_rococo::VERSION,
+				sp_runtime::generic::Era::Immortal,
+				genesis_hash,
+				signer_nonce,
+				0,
+			),
+		)
+		.expect("SignedExtension never fails.");
+
+		let signature = raw_payload.using_encoded(|payload| signer.sign(payload));
+		let signer: sp_runtime::MultiSigner = signer.public().into();
+		let (call, extra, _) = raw_payload.deconstruct();
+
+		bp_rococo::UncheckedExtrinsic::new_signed(
+			call,
+			sp_runtime::MultiAddress::Id(signer.into_account()),
+			signature.into(),
+			extra,
+		)
+	}
+}
+
+/// Rococo signing params.
+pub type SigningParams = sp_core::sr25519::Pair;

polkadot/bridges/relays/client-substrate/Cargo.toml

@@ -0,0 +1,42 @@
+[package]
+name = "relay-substrate-client"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+async-std = "1.6.5"
+async-trait = "0.1.40"
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+jsonrpsee-proc-macros = "=0.2.0-alpha.5"
+jsonrpsee-ws-client = "=0.2.0-alpha.5"
+log = "0.4.11"
+num-traits = "0.2"
+rand = "0.7"
+
+# Bridge dependencies
+
+bp-header-chain = { path = "../../primitives/header-chain" }
+bp-messages = { path = "../../primitives/messages" }
+bp-runtime = { path = "../../primitives/runtime" }
+finality-relay = { path = "../finality" }
+headers-relay = { path = "../headers" }
+relay-utils = { path = "../utils" }
+
+# Substrate Dependencies
+
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "master" }
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "master" }
+pallet-balances = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sc-rpc-api = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-finality-grandpa = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-storage = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-std = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-trie = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-version = { git = "https://github.com/paritytech/substrate", branch = "master" }
+
+#[dev-dependencies]
+futures = "0.3.7"

polkadot/bridges/relays/client-substrate/src/chain.rs

@@ -0,0 +1,105 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use bp_runtime::Chain as ChainBase;
+use frame_support::Parameter;
+use jsonrpsee_ws_client::{DeserializeOwned, Serialize};
+use num_traits::{CheckedSub, Zero};
+use sp_core::{storage::StorageKey, Pair};
+use sp_runtime::{
+	generic::SignedBlock,
+	traits::{
+		AtLeast32Bit, Block as BlockT, Dispatchable, MaybeDisplay, MaybeSerialize, MaybeSerializeDeserialize, Member,
+	},
+	EncodedJustification,
+};
+use std::{fmt::Debug, time::Duration};
+
+/// Substrate-based chain from minimal relay-client point of view.
+pub trait Chain: ChainBase + Clone {
+	/// Chain name.
+	const NAME: &'static str;
+	/// Average block interval.
+	///
+	/// How often blocks are produced on that chain. It's suggested to set this value
+	/// to match the block time of the chain.
+	const AVERAGE_BLOCK_INTERVAL: Duration;
+
+	/// The user account identifier type for the runtime.
+	type AccountId: Parameter + Member + MaybeSerializeDeserialize + Debug + MaybeDisplay + Ord + Default;
+	/// Index of a transaction used by the chain.
+	type Index: Parameter
+		+ Member
+		+ MaybeSerialize
+		+ Debug
+		+ Default
+		+ MaybeDisplay
+		+ DeserializeOwned
+		+ AtLeast32Bit
+		+ Copy;
+	/// Block type.
+	type SignedBlock: Member + Serialize + DeserializeOwned + BlockWithJustification<Self::Header>;
+	/// The aggregated `Call` type.
+	type Call: Dispatchable + Debug;
+}
+
+/// Substrate-based chain with `frame_system::Config::AccountData` set to
+/// the `pallet_balances::AccountData<NativeBalance>`.
+pub trait ChainWithBalances: Chain {
+	/// Balance of an account in native tokens.
+	type NativeBalance: Parameter + Member + DeserializeOwned + Clone + Copy + CheckedSub + PartialOrd + Zero;
+
+	/// Return runtime storage key for getting `frame_system::AccountInfo` of given account.
+	fn account_info_storage_key(account_id: &Self::AccountId) -> StorageKey;
+}
+
+/// Block with justification.
+pub trait BlockWithJustification<Header> {
+	/// Return block header.
+	fn header(&self) -> Header;
+	/// Return block justification, if known.
+	fn justification(&self) -> Option<&EncodedJustification>;
+}
+
+/// Substrate-based chain transactions signing scheme.
+pub trait TransactionSignScheme {
+	/// Chain that this scheme is to be used.
+	type Chain: Chain;
+	/// Type of key pairs used to sign transactions.
+	type AccountKeyPair: Pair;
+	/// Signed transaction.
+	type SignedTransaction;
+
+	/// Create transaction for given runtime call, signed by given account.
+	fn sign_transaction(
+		genesis_hash: <Self::Chain as ChainBase>::Hash,
+		signer: &Self::AccountKeyPair,
+		signer_nonce: <Self::Chain as Chain>::Index,
+		call: <Self::Chain as Chain>::Call,
+	) -> Self::SignedTransaction;
+}
+
+impl<Block: BlockT> BlockWithJustification<Block::Header> for SignedBlock<Block> {
+	fn header(&self) -> Block::Header {
+		self.block.header().clone()
+	}
+
+	fn justification(&self) -> Option<&EncodedJustification> {
+		self.justifications
+			.as_ref()
+			.and_then(|j| j.get(sp_finality_grandpa::GRANDPA_ENGINE_ID))
+	}
+}

polkadot/bridges/relays/client-substrate/src/client.rs

@@ -0,0 +1,275 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Substrate node client.
+
+use crate::chain::{Chain, ChainWithBalances};
+use crate::rpc::Substrate;
+use crate::{ConnectionParams, Error, Result};
+
+use async_std::sync::{Arc, Mutex};
+use codec::Decode;
+use frame_system::AccountInfo;
+use jsonrpsee_ws_client::{traits::SubscriptionClient, v2::params::JsonRpcParams, DeserializeOwned};
+use jsonrpsee_ws_client::{Subscription, WsClient as RpcClient, WsClientBuilder as RpcClientBuilder};
+use num_traits::Zero;
+use pallet_balances::AccountData;
+use sp_core::{storage::StorageKey, Bytes};
+use sp_trie::StorageProof;
+use sp_version::RuntimeVersion;
+
+const SUB_API_GRANDPA_AUTHORITIES: &str = "GrandpaApi_grandpa_authorities";
+const MAX_SUBSCRIPTION_CAPACITY: usize = 4096;
+
+/// Opaque justifications subscription type.
+pub type JustificationsSubscription = Subscription<Bytes>;
+
+/// Opaque GRANDPA authorities set.
+pub type OpaqueGrandpaAuthoritiesSet = Vec<u8>;
+
+/// Substrate client type.
+///
+/// Cloning `Client` is a cheap operation.
+pub struct Client<C: Chain> {
+	/// Client connection params.
+	params: ConnectionParams,
+	/// Substrate RPC client.
+	client: Arc<RpcClient>,
+	/// Genesis block hash.
+	genesis_hash: C::Hash,
+	/// If several tasks are submitting their transactions simultaneously using `submit_signed_extrinsic`
+	/// method, they may get the same transaction nonce. So one of transactions will be rejected
+	/// from the pool. This lock is here to prevent situations like that.
+	submit_signed_extrinsic_lock: Arc<Mutex<()>>,
+}
+
+impl<C: Chain> Clone for Client<C> {
+	fn clone(&self) -> Self {
+		Client {
+			params: self.params.clone(),
+			client: self.client.clone(),
+			genesis_hash: self.genesis_hash,
+			submit_signed_extrinsic_lock: self.submit_signed_extrinsic_lock.clone(),
+		}
+	}
+}
+
+impl<C: Chain> std::fmt::Debug for Client<C> {
+	fn fmt(&self, fmt: &mut std::fmt::Formatter) -> std::fmt::Result {
+		fmt.debug_struct("Client")
+			.field("genesis_hash", &self.genesis_hash)
+			.finish()
+	}
+}
+
+impl<C: Chain> Client<C> {
+	/// Returns client that is able to call RPCs on Substrate node over websocket connection.
+	pub async fn new(params: ConnectionParams) -> Result<Self> {
+		let client = Self::build_client(params.clone()).await?;
+
+		let number: C::BlockNumber = Zero::zero();
+		let genesis_hash = Substrate::<C>::chain_get_block_hash(&*client, number).await?;
+
+		Ok(Self {
+			params,
+			client,
+			genesis_hash,
+			submit_signed_extrinsic_lock: Arc::new(Mutex::new(())),
+		})
+	}
+
+	/// Reopen client connection.
+	pub async fn reconnect(&mut self) -> Result<()> {
+		self.client = Self::build_client(self.params.clone()).await?;
+		Ok(())
+	}
+
+	/// Build client to use in connection.
+	async fn build_client(params: ConnectionParams) -> Result<Arc<RpcClient>> {
+		let uri = format!(
+			"{}://{}:{}",
+			if params.secure { "wss" } else { "ws" },
+			params.host,
+			params.port,
+		);
+		let client = RpcClientBuilder::default()
+			.max_notifs_per_subscription(MAX_SUBSCRIPTION_CAPACITY)
+			.build(&uri)
+			.await?;
+
+		Ok(Arc::new(client))
+	}
+}
+
+impl<C: Chain> Client<C> {
+	/// Returns true if client is connected to at least one peer and is in synced state.
+	pub async fn ensure_synced(&self) -> Result<()> {
+		let health = Substrate::<C>::system_health(&*self.client).await?;
+		let is_synced = !health.is_syncing && (!health.should_have_peers || health.peers > 0);
+		if is_synced {
+			Ok(())
+		} else {
+			Err(Error::ClientNotSynced(health))
+		}
+	}
+
+	/// Return hash of the genesis block.
+	pub fn genesis_hash(&self) -> &C::Hash {
+		&self.genesis_hash
+	}
+
+	/// Return hash of the best finalized block.
+	pub async fn best_finalized_header_hash(&self) -> Result<C::Hash> {
+		Ok(Substrate::<C>::chain_get_finalized_head(&*self.client).await?)
+	}
+
+	/// Returns the best Substrate header.
+	pub async fn best_header(&self) -> Result<C::Header>
+	where
+		C::Header: DeserializeOwned,
+	{
+		Ok(Substrate::<C>::chain_get_header(&*self.client, None).await?)
+	}
+
+	/// Get a Substrate block from its hash.
+	pub async fn get_block(&self, block_hash: Option<C::Hash>) -> Result<C::SignedBlock> {
+		Ok(Substrate::<C>::chain_get_block(&*self.client, block_hash).await?)
+	}
+
+	/// Get a Substrate header by its hash.
+	pub async fn header_by_hash(&self, block_hash: C::Hash) -> Result<C::Header>
+	where
+		C::Header: DeserializeOwned,
+	{
+		Ok(Substrate::<C>::chain_get_header(&*self.client, block_hash).await?)
+	}
+
+	/// Get a Substrate block hash by its number.
+	pub async fn block_hash_by_number(&self, number: C::BlockNumber) -> Result<C::Hash> {
+		Ok(Substrate::<C>::chain_get_block_hash(&*self.client, number).await?)
+	}
+
+	/// Get a Substrate header by its number.
+	pub async fn header_by_number(&self, block_number: C::BlockNumber) -> Result<C::Header>
+	where
+		C::Header: DeserializeOwned,
+	{
+		let block_hash = Self::block_hash_by_number(self, block_number).await?;
+		Ok(Self::header_by_hash(self, block_hash).await?)
+	}
+
+	/// Return runtime version.
+	pub async fn runtime_version(&self) -> Result<RuntimeVersion> {
+		Ok(Substrate::<C>::state_runtime_version(&*self.client).await?)
+	}
+
+	/// Read value from runtime storage.
+	pub async fn storage_value<T: Decode>(&self, storage_key: StorageKey) -> Result<Option<T>> {
+		Substrate::<C>::state_get_storage(&*self.client, storage_key)
+			.await?
+			.map(|encoded_value| T::decode(&mut &encoded_value.0[..]).map_err(Error::ResponseParseFailed))
+			.transpose()
+	}
+
+	/// Return native tokens balance of the account.
+	pub async fn free_native_balance(&self, account: C::AccountId) -> Result<C::NativeBalance>
+	where
+		C: ChainWithBalances,
+	{
+		let storage_key = C::account_info_storage_key(&account);
+		let encoded_account_data = Substrate::<C>::state_get_storage(&*self.client, storage_key)
+			.await?
+			.ok_or(Error::AccountDoesNotExist)?;
+		let decoded_account_data =
+			AccountInfo::<C::Index, AccountData<C::NativeBalance>>::decode(&mut &encoded_account_data.0[..])
+				.map_err(Error::ResponseParseFailed)?;
+		Ok(decoded_account_data.data.free)
+	}
+
+	/// Get the nonce of the given Substrate account.
+	///
+	/// Note: It's the caller's responsibility to make sure `account` is a valid ss58 address.
+	pub async fn next_account_index(&self, account: C::AccountId) -> Result<C::Index> {
+		Ok(Substrate::<C>::system_account_next_index(&*self.client, account).await?)
+	}
+
+	/// Submit unsigned extrinsic for inclusion in a block.
+	///
+	/// Note: The given transaction needs to be SCALE encoded beforehand.
+	pub async fn submit_unsigned_extrinsic(&self, transaction: Bytes) -> Result<C::Hash> {
+		let tx_hash = Substrate::<C>::author_submit_extrinsic(&*self.client, transaction).await?;
+		log::trace!(target: "bridge", "Sent transaction to Substrate node: {:?}", tx_hash);
+		Ok(tx_hash)
+	}
+
+	/// Submit an extrinsic signed by given account.
+	///
+	/// All calls of this method are synchronized, so there can't be more than one active
+	/// `submit_signed_extrinsic()` call. This guarantees that no nonces collision may happen
+	/// if all client instances are clones of the same initial `Client`.
+	///
+	/// Note: The given transaction needs to be SCALE encoded beforehand.
+	pub async fn submit_signed_extrinsic(
+		&self,
+		extrinsic_signer: C::AccountId,
+		prepare_extrinsic: impl FnOnce(C::Index) -> Bytes,
+	) -> Result<C::Hash> {
+		let _guard = self.submit_signed_extrinsic_lock.lock().await;
+		let transaction_nonce = self.next_account_index(extrinsic_signer).await?;
+		let extrinsic = prepare_extrinsic(transaction_nonce);
+		let tx_hash = Substrate::<C>::author_submit_extrinsic(&*self.client, extrinsic).await?;
+		log::trace!(target: "bridge", "Sent transaction to {} node: {:?}", C::NAME, tx_hash);
+		Ok(tx_hash)
+	}
+
+	/// Get the GRANDPA authority set at given block.
+	pub async fn grandpa_authorities_set(&self, block: C::Hash) -> Result<OpaqueGrandpaAuthoritiesSet> {
+		let call = SUB_API_GRANDPA_AUTHORITIES.to_string();
+		let data = Bytes(Vec::new());
+
+		let encoded_response = Substrate::<C>::state_call(&*self.client, call, data, Some(block)).await?;
+		let authority_list = encoded_response.0;
+
+		Ok(authority_list)
+	}
+
+	/// Execute runtime call at given block.
+	pub async fn state_call(&self, method: String, data: Bytes, at_block: Option<C::Hash>) -> Result<Bytes> {
+		Substrate::<C>::state_call(&*self.client, method, data, at_block)
+			.await
+			.map_err(Into::into)
+	}
+
+	/// Returns storage proof of given storage keys.
+	pub async fn prove_storage(&self, keys: Vec<StorageKey>, at_block: C::Hash) -> Result<StorageProof> {
+		Substrate::<C>::state_prove_storage(&*self.client, keys, Some(at_block))
+			.await
+			.map(|proof| StorageProof::new(proof.proof.into_iter().map(|b| b.0).collect()))
+			.map_err(Into::into)
+	}
+
+	/// Return new justifications stream.
+	pub async fn subscribe_justifications(&self) -> Result<JustificationsSubscription> {
+		Ok(self
+			.client
+			.subscribe(
+				"grandpa_subscribeJustifications",
+				JsonRpcParams::NoParams,
+				"grandpa_unsubscribeJustifications",
+			)
+			.await?)
+	}
+}

polkadot/bridges/relays/client-substrate/src/error.rs

@@ -0,0 +1,105 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Substrate node RPC errors.
+
+use jsonrpsee_ws_client::Error as RpcError;
+use relay_utils::MaybeConnectionError;
+use sc_rpc_api::system::Health;
+
+/// Result type used by Substrate client.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Errors that can occur only when interacting with
+/// a Substrate node through RPC.
+#[derive(Debug)]
+pub enum Error {
+	/// An error that can occur when making a request to
+	/// an JSON-RPC server.
+	RpcError(RpcError),
+	/// The response from the server could not be SCALE decoded.
+	ResponseParseFailed(codec::Error),
+	/// The Substrate bridge pallet has not yet been initialized.
+	UninitializedBridgePallet,
+	/// Account does not exist on the chain.
+	AccountDoesNotExist,
+	/// Runtime storage is missing mandatory ":code:" entry.
+	MissingMandatoryCodeEntry,
+	/// The client we're connected to is not synced, so we can't rely on its state.
+	ClientNotSynced(Health),
+	/// An error has happened when we have tried to parse storage proof.
+	StorageProofError(bp_runtime::StorageProofError),
+	/// Custom logic error.
+	Custom(String),
+}
+
+impl std::error::Error for Error {
+	fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+		match self {
+			Self::RpcError(ref e) => Some(e),
+			Self::ResponseParseFailed(ref e) => Some(e),
+			Self::UninitializedBridgePallet => None,
+			Self::AccountDoesNotExist => None,
+			Self::MissingMandatoryCodeEntry => None,
+			Self::ClientNotSynced(_) => None,
+			Self::StorageProofError(_) => None,
+			Self::Custom(_) => None,
+		}
+	}
+}
+
+impl From<RpcError> for Error {
+	fn from(error: RpcError) -> Self {
+		Error::RpcError(error)
+	}
+}
+
+impl MaybeConnectionError for Error {
+	fn is_connection_error(&self) -> bool {
+		matches!(
+			*self,
+			Error::RpcError(RpcError::TransportError(_))
+				// right now if connection to the ws server is dropped (after it is already established),
+				// we're getting this error
+				| Error::RpcError(RpcError::Internal(_))
+				| Error::RpcError(RpcError::RestartNeeded(_))
+				| Error::ClientNotSynced(_),
+		)
+	}
+}
+
+impl std::fmt::Display for Error {
+	fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+		let s = match self {
+			Self::RpcError(e) => e.to_string(),
+			Self::ResponseParseFailed(e) => e.to_string(),
+			Self::UninitializedBridgePallet => "The Substrate bridge pallet has not been initialized yet.".into(),
+			Self::AccountDoesNotExist => "Account does not exist on the chain".into(),
+			Self::MissingMandatoryCodeEntry => "Mandatory :code: entry is missing from runtime storage".into(),
+			Self::StorageProofError(e) => format!("Error when parsing storage proof: {:?}", e),
+			Self::ClientNotSynced(health) => format!("Substrate client is not synced: {}", health),
+			Self::Custom(e) => e.clone(),
+		};
+
+		write!(f, "{}", s)
+	}
+}
+
+impl From<Error> for String {
+	fn from(error: Error) -> String {
+		error.to_string()
+	}
+}

polkadot/bridges/relays/client-substrate/src/finality_source.rs

@@ -0,0 +1,135 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Default generic implementation of finality source for basic Substrate client.
+
+use crate::chain::{BlockWithJustification, Chain};
+use crate::client::Client;
+use crate::error::Error;
+use crate::sync_header::SyncHeader;
+
+use async_trait::async_trait;
+use bp_header_chain::justification::GrandpaJustification;
+use codec::Decode;
+use finality_relay::{FinalitySyncPipeline, SourceClient, SourceHeader};
+use futures::stream::{unfold, Stream, StreamExt};
+use relay_utils::relay_loop::Client as RelayClient;
+use sp_runtime::traits::Header as HeaderT;
+use std::{marker::PhantomData, pin::Pin};
+
+/// Substrate node as finality source.
+pub struct FinalitySource<C: Chain, P> {
+	client: Client<C>,
+	_phantom: PhantomData<P>,
+}
+
+impl<C: Chain, P> FinalitySource<C, P> {
+	/// Create new headers source using given client.
+	pub fn new(client: Client<C>) -> Self {
+		FinalitySource {
+			client,
+			_phantom: Default::default(),
+		}
+	}
+}
+
+impl<C: Chain, P> Clone for FinalitySource<C, P> {
+	fn clone(&self) -> Self {
+		FinalitySource {
+			client: self.client.clone(),
+			_phantom: Default::default(),
+		}
+	}
+}
+
+#[async_trait]
+impl<C: Chain, P: FinalitySyncPipeline> RelayClient for FinalitySource<C, P> {
+	type Error = Error;
+
+	async fn reconnect(&mut self) -> Result<(), Error> {
+		self.client.reconnect().await
+	}
+}
+
+#[async_trait]
+impl<C, P> SourceClient<P> for FinalitySource<C, P>
+where
+	C: Chain,
+	C::BlockNumber: relay_utils::BlockNumberBase,
+	P: FinalitySyncPipeline<
+		Hash = C::Hash,
+		Number = C::BlockNumber,
+		Header = SyncHeader<C::Header>,
+		FinalityProof = GrandpaJustification<C::Header>,
+	>,
+	P::Header: SourceHeader<C::BlockNumber>,
+{
+	type FinalityProofsStream = Pin<Box<dyn Stream<Item = GrandpaJustification<C::Header>> + Send>>;
+
+	async fn best_finalized_block_number(&self) -> Result<P::Number, Error> {
+		// we **CAN** continue to relay finality proofs if source node is out of sync, because
+		// target node may be missing proofs that are already available at the source
+		let finalized_header_hash = self.client.best_finalized_header_hash().await?;
+		let finalized_header = self.client.header_by_hash(finalized_header_hash).await?;
+		Ok(*finalized_header.number())
+	}
+
+	async fn header_and_finality_proof(
+		&self,
+		number: P::Number,
+	) -> Result<(P::Header, Option<P::FinalityProof>), Error> {
+		let header_hash = self.client.block_hash_by_number(number).await?;
+		let signed_block = self.client.get_block(Some(header_hash)).await?;
+
+		let justification = signed_block
+			.justification()
+			.map(|raw_justification| GrandpaJustification::<C::Header>::decode(&mut raw_justification.as_slice()))
+			.transpose()
+			.map_err(Error::ResponseParseFailed)?;
+
+		Ok((signed_block.header().into(), justification))
+	}
+
+	async fn finality_proofs(&self) -> Result<Self::FinalityProofsStream, Error> {
+		Ok(unfold(
+			self.client.clone().subscribe_justifications().await?,
+			move |mut subscription| async move {
+				loop {
+					let next_justification = subscription.next().await?;
+					let decoded_justification =
+						GrandpaJustification::<C::Header>::decode(&mut &next_justification.0[..]);
+
+					let justification = match decoded_justification {
+						Ok(j) => j,
+						Err(err) => {
+							log::error!(
+								target: "bridge",
+								"Failed to decode justification target from the {} justifications stream: {:?}",
+								P::SOURCE_NAME,
+								err,
+							);
+
+							continue;
+						}
+					};
+
+					return Some((justification, subscription));
+				}
+			},
+		)
+		.boxed())
+	}
+}

polkadot/bridges/relays/client-substrate/src/guard.rs

@@ -0,0 +1,373 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Pallet provides a set of guard functions that are running in background threads
+//! and are aborting process if some condition fails.
+
+use crate::{Chain, ChainWithBalances, Client};
+
+use async_trait::async_trait;
+use num_traits::CheckedSub;
+use sp_version::RuntimeVersion;
+use std::{
+	collections::VecDeque,
+	time::{Duration, Instant},
+};
+
+/// Guards environment.
+#[async_trait]
+pub trait Environment<C: ChainWithBalances>: Send + Sync + 'static {
+	/// Return current runtime version.
+	async fn runtime_version(&mut self) -> Result<RuntimeVersion, String>;
+	/// Return free native balance of the account on the chain.
+	async fn free_native_balance(&mut self, account: C::AccountId) -> Result<C::NativeBalance, String>;
+
+	/// Return current time.
+	fn now(&self) -> Instant {
+		Instant::now()
+	}
+	/// Sleep given amount of time.
+	async fn sleep(&mut self, duration: Duration) {
+		async_std::task::sleep(duration).await
+	}
+	/// Abort current process. Called when guard condition check fails.
+	async fn abort(&mut self) {
+		std::process::abort();
+	}
+}
+
+/// Abort when runtime spec version is different from specified.
+pub fn abort_on_spec_version_change<C: ChainWithBalances>(mut env: impl Environment<C>, expected_spec_version: u32) {
+	async_std::task::spawn(async move {
+		loop {
+			let actual_spec_version = env.runtime_version().await;
+			match actual_spec_version {
+				Ok(version) if version.spec_version == expected_spec_version => (),
+				Ok(version) => {
+					log::error!(
+						target: "bridge-guard",
+						"{} runtime spec version has changed from {} to {}. Aborting relay",
+						C::NAME,
+						expected_spec_version,
+						version.spec_version,
+					);
+
+					env.abort().await;
+				}
+				Err(error) => log::warn!(
+					target: "bridge-guard",
+					"Failed to read {} runtime version: {:?}. Relay may need to be stopped manually",
+					C::NAME,
+					error,
+				),
+			}
+
+			env.sleep(conditions_check_delay::<C>()).await;
+		}
+	});
+}
+
+/// Abort if, during a 24 hours, free balance of given account is decreased at least by given value.
+/// Other components may increase (or decrease) balance of account and it WILL affect logic of the guard.
+pub fn abort_when_account_balance_decreased<C: ChainWithBalances>(
+	mut env: impl Environment<C>,
+	account_id: C::AccountId,
+	maximal_decrease: C::NativeBalance,
+) {
+	const DAY: Duration = Duration::from_secs(60 * 60 * 24);
+
+	async_std::task::spawn(async move {
+		let mut balances = VecDeque::new();
+
+		loop {
+			let current_time = env.now();
+
+			// remember balances that are beyound 24h border
+			let time_border = current_time - DAY;
+			while balances.front().map(|(time, _)| *time < time_border).unwrap_or(false) {
+				balances.pop_front();
+			}
+
+			// read balance of the account
+			let current_balance = env.free_native_balance(account_id.clone()).await;
+
+			// remember balance and check difference
+			match current_balance {
+				Ok(current_balance) => {
+					// remember balance
+					balances.push_back((current_time, current_balance));
+
+					// check if difference between current and oldest balance is too large
+					let (oldest_time, oldest_balance) =
+						balances.front().expect("pushed to queue couple of lines above; qed");
+					let balances_difference = oldest_balance.checked_sub(&current_balance);
+					if balances_difference > Some(maximal_decrease) {
+						log::error!(
+							target: "bridge-guard",
+							"Balance of {} account {:?} has decreased from {:?} to {:?} in {} minutes. Aborting relay",
+							C::NAME,
+							account_id,
+							oldest_balance,
+							current_balance,
+							current_time.duration_since(*oldest_time).as_secs() / 60,
+						);
+
+						env.abort().await;
+					}
+				}
+				Err(error) => {
+					log::warn!(
+						target: "bridge-guard",
+						"Failed to read {} account {:?} balance: {:?}. Relay may need to be stopped manually",
+						C::NAME,
+						account_id,
+						error,
+					);
+				}
+			};
+
+			env.sleep(conditions_check_delay::<C>()).await;
+		}
+	});
+}
+
+/// Delay between conditions check.
+fn conditions_check_delay<C: Chain>() -> Duration {
+	C::AVERAGE_BLOCK_INTERVAL * (10 + rand::random::<u32>() % 10)
+}
+
+#[async_trait]
+impl<C: ChainWithBalances> Environment<C> for Client<C> {
+	async fn runtime_version(&mut self) -> Result<RuntimeVersion, String> {
+		Client::<C>::runtime_version(self).await.map_err(|e| e.to_string())
+	}
+
+	async fn free_native_balance(&mut self, account: C::AccountId) -> Result<C::NativeBalance, String> {
+		Client::<C>::free_native_balance(self, account)
+			.await
+			.map_err(|e| e.to_string())
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+	use futures::{
+		channel::mpsc::{unbounded, UnboundedReceiver, UnboundedSender},
+		future::FutureExt,
+		stream::StreamExt,
+		SinkExt,
+	};
+
+	#[derive(Debug, Clone)]
+	struct TestChain;
+
+	impl bp_runtime::Chain for TestChain {
+		type BlockNumber = u32;
+		type Hash = sp_core::H256;
+		type Hasher = sp_runtime::traits::BlakeTwo256;
+		type Header = sp_runtime::generic::Header<u32, sp_runtime::traits::BlakeTwo256>;
+	}
+
+	impl Chain for TestChain {
+		const NAME: &'static str = "Test";
+		const AVERAGE_BLOCK_INTERVAL: Duration = Duration::from_millis(1);
+
+		type AccountId = u32;
+		type Index = u32;
+		type SignedBlock =
+			sp_runtime::generic::SignedBlock<sp_runtime::generic::Block<Self::Header, sp_runtime::OpaqueExtrinsic>>;
+		type Call = ();
+	}
+
+	impl ChainWithBalances for TestChain {
+		type NativeBalance = u32;
+
+		fn account_info_storage_key(_account_id: &u32) -> sp_core::storage::StorageKey {
+			unreachable!()
+		}
+	}
+
+	struct TestEnvironment {
+		runtime_version_rx: UnboundedReceiver<RuntimeVersion>,
+		free_native_balance_rx: UnboundedReceiver<u32>,
+		slept_tx: UnboundedSender<()>,
+		aborted_tx: UnboundedSender<()>,
+	}
+
+	#[async_trait]
+	impl Environment<TestChain> for TestEnvironment {
+		async fn runtime_version(&mut self) -> Result<RuntimeVersion, String> {
+			Ok(self.runtime_version_rx.next().await.unwrap_or_default())
+		}
+
+		async fn free_native_balance(&mut self, _account: u32) -> Result<u32, String> {
+			Ok(self.free_native_balance_rx.next().await.unwrap_or_default())
+		}
+
+		async fn sleep(&mut self, _duration: Duration) {
+			let _ = self.slept_tx.send(()).await;
+		}
+
+		async fn abort(&mut self) {
+			let _ = self.aborted_tx.send(()).await;
+			// simulate process abort :)
+			async_std::task::sleep(Duration::from_secs(60)).await;
+		}
+	}
+
+	#[test]
+	fn aborts_when_spec_version_is_changed() {
+		async_std::task::block_on(async {
+			let (
+				(mut runtime_version_tx, runtime_version_rx),
+				(_free_native_balance_tx, free_native_balance_rx),
+				(slept_tx, mut slept_rx),
+				(aborted_tx, mut aborted_rx),
+			) = (unbounded(), unbounded(), unbounded(), unbounded());
+			abort_on_spec_version_change(
+				TestEnvironment {
+					runtime_version_rx,
+					free_native_balance_rx,
+					slept_tx,
+					aborted_tx,
+				},
+				0,
+			);
+
+			// client responds with wrong version
+			runtime_version_tx
+				.send(RuntimeVersion {
+					spec_version: 42,
+					..Default::default()
+				})
+				.await
+				.unwrap();
+
+			// then the `abort` function is called
+			aborted_rx.next().await;
+			// and we do not reach the `sleep` function call
+			assert!(slept_rx.next().now_or_never().is_none());
+		});
+	}
+
+	#[test]
+	fn does_not_aborts_when_spec_version_is_unchanged() {
+		async_std::task::block_on(async {
+			let (
+				(mut runtime_version_tx, runtime_version_rx),
+				(_free_native_balance_tx, free_native_balance_rx),
+				(slept_tx, mut slept_rx),
+				(aborted_tx, mut aborted_rx),
+			) = (unbounded(), unbounded(), unbounded(), unbounded());
+			abort_on_spec_version_change(
+				TestEnvironment {
+					runtime_version_rx,
+					free_native_balance_rx,
+					slept_tx,
+					aborted_tx,
+				},
+				42,
+			);
+
+			// client responds with the same version
+			runtime_version_tx
+				.send(RuntimeVersion {
+					spec_version: 42,
+					..Default::default()
+				})
+				.await
+				.unwrap();
+
+			// then the `sleep` function is called
+			slept_rx.next().await;
+			// and the `abort` function is not called
+			assert!(aborted_rx.next().now_or_never().is_none());
+		});
+	}
+
+	#[test]
+	fn aborts_when_balance_is_too_low() {
+		async_std::task::block_on(async {
+			let (
+				(_runtime_version_tx, runtime_version_rx),
+				(mut free_native_balance_tx, free_native_balance_rx),
+				(slept_tx, mut slept_rx),
+				(aborted_tx, mut aborted_rx),
+			) = (unbounded(), unbounded(), unbounded(), unbounded());
+			abort_when_account_balance_decreased(
+				TestEnvironment {
+					runtime_version_rx,
+					free_native_balance_rx,
+					slept_tx,
+					aborted_tx,
+				},
+				0,
+				100,
+			);
+
+			// client responds with initial balance
+			free_native_balance_tx.send(1000).await.unwrap();
+
+			// then the guard sleeps
+			slept_rx.next().await;
+
+			// and then client responds with updated balance, which is too low
+			free_native_balance_tx.send(899).await.unwrap();
+
+			// then the `abort` function is called
+			aborted_rx.next().await;
+			// and we do not reach next `sleep` function call
+			assert!(slept_rx.next().now_or_never().is_none());
+		});
+	}
+
+	#[test]
+	fn does_not_aborts_when_balance_is_enough() {
+		async_std::task::block_on(async {
+			let (
+				(_runtime_version_tx, runtime_version_rx),
+				(mut free_native_balance_tx, free_native_balance_rx),
+				(slept_tx, mut slept_rx),
+				(aborted_tx, mut aborted_rx),
+			) = (unbounded(), unbounded(), unbounded(), unbounded());
+			abort_when_account_balance_decreased(
+				TestEnvironment {
+					runtime_version_rx,
+					free_native_balance_rx,
+					slept_tx,
+					aborted_tx,
+				},
+				0,
+				100,
+			);
+
+			// client responds with initial balance
+			free_native_balance_tx.send(1000).await.unwrap();
+
+			// then the guard sleeps
+			slept_rx.next().await;
+
+			// and then client responds with updated balance, which is enough
+			free_native_balance_tx.send(950).await.unwrap();
+
+			// then the `sleep` function is called
+			slept_rx.next().await;
+			// and `abort` is not called
+			assert!(aborted_rx.next().now_or_never().is_none());
+		});
+	}
+}

polkadot/bridges/relays/client-substrate/src/headers_source.rs

@@ -0,0 +1,108 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Default generic implementation of headers source for basic Substrate client.
+
+use crate::chain::{BlockWithJustification, Chain};
+use crate::client::Client;
+use crate::error::Error;
+
+use async_trait::async_trait;
+use headers_relay::{
+	sync_loop::SourceClient,
+	sync_types::{HeaderIdOf, HeadersSyncPipeline, QueuedHeader, SourceHeader},
+};
+use relay_utils::relay_loop::Client as RelayClient;
+use sp_runtime::{traits::Header as HeaderT, EncodedJustification};
+use std::marker::PhantomData;
+
+/// Substrate node as headers source.
+pub struct HeadersSource<C: Chain, P> {
+	client: Client<C>,
+	_phantom: PhantomData<P>,
+}
+
+impl<C: Chain, P> HeadersSource<C, P> {
+	/// Create new headers source using given client.
+	pub fn new(client: Client<C>) -> Self {
+		HeadersSource {
+			client,
+			_phantom: Default::default(),
+		}
+	}
+}
+
+impl<C: Chain, P> Clone for HeadersSource<C, P> {
+	fn clone(&self) -> Self {
+		HeadersSource {
+			client: self.client.clone(),
+			_phantom: Default::default(),
+		}
+	}
+}
+
+#[async_trait]
+impl<C: Chain, P: HeadersSyncPipeline> RelayClient for HeadersSource<C, P> {
+	type Error = Error;
+
+	async fn reconnect(&mut self) -> Result<(), Error> {
+		self.client.reconnect().await
+	}
+}
+
+#[async_trait]
+impl<C, P> SourceClient<P> for HeadersSource<C, P>
+where
+	C: Chain,
+	C::BlockNumber: relay_utils::BlockNumberBase,
+	C::Header: Into<P::Header>,
+	P: HeadersSyncPipeline<Extra = (), Completion = EncodedJustification, Hash = C::Hash, Number = C::BlockNumber>,
+	P::Header: SourceHeader<C::Hash, C::BlockNumber>,
+{
+	async fn best_block_number(&self) -> Result<P::Number, Error> {
+		// we **CAN** continue to relay headers if source node is out of sync, because
+		// target node may be missing headers that are already available at the source
+		Ok(*self.client.best_header().await?.number())
+	}
+
+	async fn header_by_hash(&self, hash: P::Hash) -> Result<P::Header, Error> {
+		self.client
+			.header_by_hash(hash)
+			.await
+			.map(Into::into)
+			.map_err(Into::into)
+	}
+
+	async fn header_by_number(&self, number: P::Number) -> Result<P::Header, Error> {
+		self.client
+			.header_by_number(number)
+			.await
+			.map(Into::into)
+			.map_err(Into::into)
+	}
+
+	async fn header_completion(&self, id: HeaderIdOf<P>) -> Result<(HeaderIdOf<P>, Option<P::Completion>), Error> {
+		let hash = id.1;
+		let signed_block = self.client.get_block(Some(hash)).await?;
+		let grandpa_justification = signed_block.justification().cloned();
+
+		Ok((id, grandpa_justification))
+	}
+
+	async fn header_extra(&self, id: HeaderIdOf<P>, _header: QueuedHeader<P>) -> Result<(HeaderIdOf<P>, ()), Error> {
+		Ok((id, ()))
+	}
+}

polkadot/bridges/relays/client-substrate/src/lib.rs

@@ -0,0 +1,60 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Tools to interact with (Open) Ethereum node using RPC methods.
+
+#![warn(missing_docs)]
+
+mod chain;
+mod client;
+mod error;
+mod rpc;
+mod sync_header;
+
+pub mod finality_source;
+pub mod guard;
+pub mod headers_source;
+pub mod metrics;
+
+pub use crate::chain::{BlockWithJustification, Chain, ChainWithBalances, TransactionSignScheme};
+pub use crate::client::{Client, JustificationsSubscription, OpaqueGrandpaAuthoritiesSet};
+pub use crate::error::{Error, Result};
+pub use crate::sync_header::SyncHeader;
+pub use bp_runtime::{BlockNumberOf, Chain as ChainBase, HashOf, HeaderOf};
+
+/// Header id used by the chain.
+pub type HeaderIdOf<C> = relay_utils::HeaderId<HashOf<C>, BlockNumberOf<C>>;
+
+/// Substrate-over-websocket connection params.
+#[derive(Debug, Clone)]
+pub struct ConnectionParams {
+	/// Websocket server hostname.
+	pub host: String,
+	/// Websocket server TCP port.
+	pub port: u16,
+	/// Use secure websocket connection.
+	pub secure: bool,
+}
+
+impl Default for ConnectionParams {
+	fn default() -> Self {
+		ConnectionParams {
+			host: "localhost".into(),
+			port: 9944,
+			secure: false,
+		}
+	}
+}

polkadot/bridges/relays/client-substrate/src/metrics/float_storage_value.rs

@@ -0,0 +1,82 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::chain::Chain;
+use crate::client::Client;
+
+use async_trait::async_trait;
+use codec::Decode;
+use relay_utils::metrics::{metric_name, register, Gauge, PrometheusError, Registry, StandaloneMetrics, F64};
+use sp_core::storage::StorageKey;
+use sp_runtime::{traits::UniqueSaturatedInto, FixedPointNumber};
+use std::time::Duration;
+
+/// Storage value update interval (in blocks).
+const UPDATE_INTERVAL_IN_BLOCKS: u32 = 5;
+
+/// Metric that represents fixed-point runtime storage value as float gauge.
+#[derive(Clone, Debug)]
+pub struct FloatStorageValueMetric<C: Chain, T: Clone> {
+	client: Client<C>,
+	storage_key: StorageKey,
+	maybe_default_value: Option<T>,
+	metric: Gauge<F64>,
+}
+
+impl<C: Chain, T: Decode + FixedPointNumber> FloatStorageValueMetric<C, T> {
+	/// Create new metric.
+	pub fn new(
+		registry: &Registry,
+		prefix: Option<&str>,
+		client: Client<C>,
+		storage_key: StorageKey,
+		maybe_default_value: Option<T>,
+		name: String,
+		help: String,
+	) -> Result<Self, PrometheusError> {
+		Ok(FloatStorageValueMetric {
+			client,
+			storage_key,
+			maybe_default_value,
+			metric: register(Gauge::new(metric_name(prefix, &name), help)?, registry)?,
+		})
+	}
+}
+
+#[async_trait]
+impl<C: Chain, T> StandaloneMetrics for FloatStorageValueMetric<C, T>
+where
+	T: 'static + Decode + Send + Sync + FixedPointNumber,
+{
+	fn update_interval(&self) -> Duration {
+		C::AVERAGE_BLOCK_INTERVAL * UPDATE_INTERVAL_IN_BLOCKS
+	}
+
+	async fn update(&self) {
+		relay_utils::metrics::set_gauge_value(
+			&self.metric,
+			self.client
+				.storage_value::<T>(self.storage_key.clone())
+				.await
+				.map(|maybe_storage_value| {
+					maybe_storage_value.or(self.maybe_default_value).map(|storage_value| {
+						storage_value.into_inner().unique_saturated_into() as f64
+							/ T::DIV.unique_saturated_into() as f64
+					})
+				}),
+		);
+	}
+}

polkadot/bridges/relays/client-substrate/src/metrics/mod.rs

@@ -0,0 +1,23 @@
+// Copyright 2019-2020 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Contains several Substrate-specific metrics that may be exposed by relay.
+
+pub use float_storage_value::FloatStorageValueMetric;
+pub use storage_proof_overhead::StorageProofOverheadMetric;
+
+mod float_storage_value;
+mod storage_proof_overhead;

polkadot/bridges/relays/client-substrate/src/metrics/storage_proof_overhead.rs

@@ -0,0 +1,104 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::chain::Chain;
+use crate::client::Client;
+use crate::error::Error;
+
+use async_trait::async_trait;
+use relay_utils::metrics::{metric_name, register, Gauge, PrometheusError, Registry, StandaloneMetrics, U64};
+use sp_core::storage::StorageKey;
+use sp_runtime::traits::Header as HeaderT;
+use sp_storage::well_known_keys::CODE;
+use std::time::Duration;
+
+/// Storage proof overhead update interval (in blocks).
+const UPDATE_INTERVAL_IN_BLOCKS: u32 = 100;
+
+/// Metric that represents extra size of storage proof as unsigned integer gauge.
+///
+/// There's one thing to keep in mind when using this metric: the overhead may be slightly
+/// different for other values, but this metric gives a good estimation.
+#[derive(Debug)]
+pub struct StorageProofOverheadMetric<C: Chain> {
+	client: Client<C>,
+	metric: Gauge<U64>,
+}
+
+impl<C: Chain> Clone for StorageProofOverheadMetric<C> {
+	fn clone(&self) -> Self {
+		StorageProofOverheadMetric {
+			client: self.client.clone(),
+			metric: self.metric.clone(),
+		}
+	}
+}
+
+impl<C: Chain> StorageProofOverheadMetric<C> {
+	/// Create new metric instance with given name and help.
+	pub fn new(
+		registry: &Registry,
+		prefix: Option<&str>,
+		client: Client<C>,
+		name: String,
+		help: String,
+	) -> Result<Self, PrometheusError> {
+		Ok(StorageProofOverheadMetric {
+			client,
+			metric: register(Gauge::new(metric_name(prefix, &name), help)?, registry)?,
+		})
+	}
+
+	/// Returns approximate storage proof size overhead.
+	async fn compute_storage_proof_overhead(&self) -> Result<usize, Error> {
+		let best_header_hash = self.client.best_finalized_header_hash().await?;
+		let best_header = self.client.header_by_hash(best_header_hash).await?;
+
+		let storage_proof = self
+			.client
+			.prove_storage(vec![StorageKey(CODE.to_vec())], best_header_hash)
+			.await?;
+		let storage_proof_size: usize = storage_proof.clone().iter_nodes().map(|n| n.len()).sum();
+
+		let storage_value_reader =
+			bp_runtime::StorageProofChecker::<C::Hasher>::new(*best_header.state_root(), storage_proof)
+				.map_err(Error::StorageProofError)?;
+		let maybe_encoded_storage_value = storage_value_reader
+			.read_value(CODE)
+			.map_err(Error::StorageProofError)?;
+		let encoded_storage_value_size = maybe_encoded_storage_value
+			.ok_or(Error::MissingMandatoryCodeEntry)?
+			.len();
+
+		Ok(storage_proof_size - encoded_storage_value_size)
+	}
+}
+
+#[async_trait]
+impl<C: Chain> StandaloneMetrics for StorageProofOverheadMetric<C> {
+	fn update_interval(&self) -> Duration {
+		C::AVERAGE_BLOCK_INTERVAL * UPDATE_INTERVAL_IN_BLOCKS
+	}
+
+	async fn update(&self) {
+		relay_utils::metrics::set_gauge_value(
+			&self.metric,
+			self.compute_storage_proof_overhead()
+				.await
+				.map(|overhead| Some(overhead as u64)),
+		);
+	}
+}

polkadot/bridges/relays/client-substrate/src/rpc.rs

@@ -0,0 +1,53 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! The most generic Substrate node RPC interface.
+
+use crate::chain::Chain;
+
+use sc_rpc_api::{state::ReadProof, system::Health};
+use sp_core::{
+	storage::{StorageData, StorageKey},
+	Bytes,
+};
+use sp_version::RuntimeVersion;
+
+jsonrpsee_proc_macros::rpc_client_api! {
+	pub(crate) Substrate<C: Chain> {
+		#[rpc(method = "system_health", positional_params)]
+		fn system_health() -> Health;
+		#[rpc(method = "chain_getHeader", positional_params)]
+		fn chain_get_header(block_hash: Option<C::Hash>) -> C::Header;
+		#[rpc(method = "chain_getFinalizedHead", positional_params)]
+		fn chain_get_finalized_head() -> C::Hash;
+		#[rpc(method = "chain_getBlock", positional_params)]
+		fn chain_get_block(block_hash: Option<C::Hash>) -> C::SignedBlock;
+		#[rpc(method = "chain_getBlockHash", positional_params)]
+		fn chain_get_block_hash(block_number: Option<C::BlockNumber>) -> C::Hash;
+		#[rpc(method = "system_accountNextIndex", positional_params)]
+		fn system_account_next_index(account_id: C::AccountId) -> C::Index;
+		#[rpc(method = "author_submitExtrinsic", positional_params)]
+		fn author_submit_extrinsic(extrinsic: Bytes) -> C::Hash;
+		#[rpc(method = "state_call", positional_params)]
+		fn state_call(method: String, data: Bytes, at_block: Option<C::Hash>) -> Bytes;
+		#[rpc(method = "state_getStorage", positional_params)]
+		fn state_get_storage(key: StorageKey) -> Option<StorageData>;
+		#[rpc(method = "state_getReadProof", positional_params)]
+		fn state_prove_storage(keys: Vec<StorageKey>, hash: Option<C::Hash>) -> ReadProof<C::Hash>;
+		#[rpc(method = "state_getRuntimeVersion", positional_params)]
+		fn state_runtime_version() -> RuntimeVersion;
+	}
+}

polkadot/bridges/relays/client-substrate/src/sync_header.rs

@@ -0,0 +1,73 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+use bp_header_chain::find_grandpa_authorities_scheduled_change;
+use finality_relay::SourceHeader as FinalitySourceHeader;
+use headers_relay::sync_types::SourceHeader;
+use num_traits::{CheckedSub, One};
+use relay_utils::HeaderId;
+use sp_runtime::traits::Header as HeaderT;
+
+/// Generic wrapper for `sp_runtime::traits::Header` based headers, that
+/// implements `headers_relay::sync_types::SourceHeader` and may be used in headers sync directly.
+#[derive(Clone, Debug, PartialEq)]
+pub struct SyncHeader<Header>(Header);
+
+impl<Header> SyncHeader<Header> {
+	/// Extracts wrapped header from self.
+	pub fn into_inner(self) -> Header {
+		self.0
+	}
+}
+
+impl<Header> std::ops::Deref for SyncHeader<Header> {
+	type Target = Header;
+
+	fn deref(&self) -> &Self::Target {
+		&self.0
+	}
+}
+
+impl<Header> From<Header> for SyncHeader<Header> {
+	fn from(header: Header) -> Self {
+		Self(header)
+	}
+}
+
+impl<Header: HeaderT> SourceHeader<Header::Hash, Header::Number> for SyncHeader<Header> {
+	fn id(&self) -> HeaderId<Header::Hash, Header::Number> {
+		relay_utils::HeaderId(*self.0.number(), self.hash())
+	}
+
+	fn parent_id(&self) -> HeaderId<Header::Hash, Header::Number> {
+		relay_utils::HeaderId(
+			self.number()
+				.checked_sub(&One::one())
+				.expect("should never be called for genesis header"),
+			*self.parent_hash(),
+		)
+	}
+}
+
+impl<Header: HeaderT> FinalitySourceHeader<Header::Number> for SyncHeader<Header> {
+	fn number(&self) -> Header::Number {
+		*self.0.number()
+	}
+
+	fn is_mandatory(&self) -> bool {
+		find_grandpa_authorities_scheduled_change(&self.0).is_some()
+	}
+}

polkadot/bridges/relays/client-westend/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "relay-westend-client"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "2.0.0" }
+headers-relay = { path = "../headers" }
+relay-substrate-client = { path = "../client-substrate" }
+relay-utils = { path = "../utils" }
+
+# Bridge dependencies
+
+bp-westend = { path = "../../primitives/chain-westend" }
+
+# Substrate Dependencies
+
+frame-system = { git = "https://github.com/paritytech/substrate", branch = "master" }
+frame-support = { git = "https://github.com/paritytech/substrate", branch = "master" }
+pallet-transaction-payment = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-core = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-keyring = { git = "https://github.com/paritytech/substrate", branch = "master" }
+sp-runtime = { git = "https://github.com/paritytech/substrate", branch = "master" }

polkadot/bridges/relays/client-westend/src/lib.rs

@@ -0,0 +1,97 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Types used to connect to the Westend chain.
+
+use codec::Encode;
+use relay_substrate_client::{Chain, ChainBase, ChainWithBalances, TransactionSignScheme};
+use sp_core::{storage::StorageKey, Pair};
+use sp_runtime::{generic::SignedPayload, traits::IdentifyAccount};
+use std::time::Duration;
+
+/// Westend header id.
+pub type HeaderId = relay_utils::HeaderId<bp_westend::Hash, bp_westend::BlockNumber>;
+
+/// Westend header type used in headers sync.
+pub type SyncHeader = relay_substrate_client::SyncHeader<bp_westend::Header>;
+
+/// Westend chain definition
+#[derive(Debug, Clone, Copy)]
+pub struct Westend;
+
+impl ChainBase for Westend {
+	type BlockNumber = bp_westend::BlockNumber;
+	type Hash = bp_westend::Hash;
+	type Hasher = bp_westend::Hasher;
+	type Header = bp_westend::Header;
+}
+
+impl Chain for Westend {
+	const NAME: &'static str = "Westend";
+	const AVERAGE_BLOCK_INTERVAL: Duration = Duration::from_secs(6);
+
+	type AccountId = bp_westend::AccountId;
+	type Index = bp_westend::Nonce;
+	type SignedBlock = bp_westend::SignedBlock;
+	type Call = bp_westend::Call;
+}
+
+impl ChainWithBalances for Westend {
+	type NativeBalance = bp_westend::Balance;
+
+	fn account_info_storage_key(account_id: &Self::AccountId) -> StorageKey {
+		StorageKey(bp_westend::account_info_storage_key(account_id))
+	}
+}
+
+impl TransactionSignScheme for Westend {
+	type Chain = Westend;
+	type AccountKeyPair = sp_core::sr25519::Pair;
+	type SignedTransaction = bp_westend::UncheckedExtrinsic;
+
+	fn sign_transaction(
+		genesis_hash: <Self::Chain as ChainBase>::Hash,
+		signer: &Self::AccountKeyPair,
+		signer_nonce: <Self::Chain as Chain>::Index,
+		call: <Self::Chain as Chain>::Call,
+	) -> Self::SignedTransaction {
+		let raw_payload = SignedPayload::new(
+			call,
+			bp_westend::SignedExtensions::new(
+				bp_westend::VERSION,
+				sp_runtime::generic::Era::Immortal,
+				genesis_hash,
+				signer_nonce,
+				0,
+			),
+		)
+		.expect("SignedExtension never fails.");
+
+		let signature = raw_payload.using_encoded(|payload| signer.sign(payload));
+		let signer: sp_runtime::MultiSigner = signer.public().into();
+		let (call, extra, _) = raw_payload.deconstruct();
+
+		bp_westend::UncheckedExtrinsic::new_signed(
+			call,
+			sp_runtime::MultiAddress::Id(signer.into_account()),
+			signature.into(),
+			extra,
+		)
+	}
+}
+
+/// Westend signing params.
+pub type SigningParams = sp_core::sr25519::Pair;

polkadot/bridges/relays/exchange/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "exchange-relay"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+async-std = "1.6.5"
+async-trait = "0.1.40"
+backoff = "0.2"
+futures = "0.3.5"
+log = "0.4.11"
+num-traits = "0.2"
+parking_lot = "0.11.0"
+relay-utils = { path = "../utils" }

polkadot/bridges/relays/exchange/src/exchange.rs

@@ -0,0 +1,916 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Relaying proofs of exchange transaction.
+
+use async_trait::async_trait;
+use relay_utils::{
+	relay_loop::Client as RelayClient, FailedClient, MaybeConnectionError, StringifiedMaybeConnectionError,
+};
+use std::{
+	fmt::{Debug, Display},
+	string::ToString,
+};
+
+/// Transaction proof pipeline.
+pub trait TransactionProofPipeline {
+	/// Name of the transaction proof source.
+	const SOURCE_NAME: &'static str;
+	/// Name of the transaction proof target.
+	const TARGET_NAME: &'static str;
+
+	/// Block type.
+	type Block: SourceBlock;
+	/// Transaction inclusion proof type.
+	type TransactionProof;
+}
+
+/// Block that is participating in exchange.
+pub trait SourceBlock {
+	/// Block hash type.
+	type Hash: Clone + Debug + Display;
+	/// Block number type.
+	type Number: Debug
+		+ Display
+		+ Clone
+		+ Copy
+		+ Into<u64>
+		+ std::cmp::Ord
+		+ std::ops::Add<Output = Self::Number>
+		+ num_traits::One;
+	/// Block transaction.
+	type Transaction: SourceTransaction;
+
+	/// Return hash of the block.
+	fn id(&self) -> relay_utils::HeaderId<Self::Hash, Self::Number>;
+	/// Return block transactions iterator.
+	fn transactions(&self) -> Vec<Self::Transaction>;
+}
+
+/// Transaction that is participating in exchange.
+pub trait SourceTransaction {
+	/// Transaction hash type.
+	type Hash: Debug + Display;
+
+	/// Return transaction hash.
+	fn hash(&self) -> Self::Hash;
+}
+
+/// Block hash for given pipeline.
+pub type BlockHashOf<P> = <<P as TransactionProofPipeline>::Block as SourceBlock>::Hash;
+
+/// Block number for given pipeline.
+pub type BlockNumberOf<P> = <<P as TransactionProofPipeline>::Block as SourceBlock>::Number;
+
+/// Transaction hash for given pipeline.
+pub type TransactionOf<P> = <<P as TransactionProofPipeline>::Block as SourceBlock>::Transaction;
+
+/// Transaction hash for given pipeline.
+pub type TransactionHashOf<P> = <TransactionOf<P> as SourceTransaction>::Hash;
+
+/// Header id.
+pub type HeaderId<P> = relay_utils::HeaderId<BlockHashOf<P>, BlockNumberOf<P>>;
+
+/// Source client API.
+#[async_trait]
+pub trait SourceClient<P: TransactionProofPipeline>: RelayClient {
+	/// Sleep until exchange-related data is (probably) updated.
+	async fn tick(&self);
+	/// Get block by hash.
+	async fn block_by_hash(&self, hash: BlockHashOf<P>) -> Result<P::Block, Self::Error>;
+	/// Get canonical block by number.
+	async fn block_by_number(&self, number: BlockNumberOf<P>) -> Result<P::Block, Self::Error>;
+	/// Return block + index where transaction has been **mined**. May return `Ok(None)` if transaction
+	/// is unknown to the source node.
+	async fn transaction_block(&self, hash: &TransactionHashOf<P>)
+		-> Result<Option<(HeaderId<P>, usize)>, Self::Error>;
+	/// Prepare transaction proof.
+	async fn transaction_proof(&self, block: &P::Block, tx_index: usize) -> Result<P::TransactionProof, Self::Error>;
+}
+
+/// Target client API.
+#[async_trait]
+pub trait TargetClient<P: TransactionProofPipeline>: RelayClient {
+	/// Sleep until exchange-related data is (probably) updated.
+	async fn tick(&self);
+	/// Returns `Ok(true)` if header is known to the target node.
+	async fn is_header_known(&self, id: &HeaderId<P>) -> Result<bool, Self::Error>;
+	/// Returns `Ok(true)` if header is finalized by the target node.
+	async fn is_header_finalized(&self, id: &HeaderId<P>) -> Result<bool, Self::Error>;
+	/// Returns best finalized header id.
+	async fn best_finalized_header_id(&self) -> Result<HeaderId<P>, Self::Error>;
+	/// Returns `Ok(true)` if transaction proof is need to be relayed.
+	async fn filter_transaction_proof(&self, proof: &P::TransactionProof) -> Result<bool, Self::Error>;
+	/// Submits transaction proof to the target node.
+	async fn submit_transaction_proof(&self, proof: P::TransactionProof) -> Result<(), Self::Error>;
+}
+
+/// Block transaction statistics.
+#[derive(Debug, Default)]
+#[cfg_attr(test, derive(PartialEq))]
+pub struct RelayedBlockTransactions {
+	/// Total number of transactions processed (either relayed or ignored) so far.
+	pub processed: usize,
+	/// Total number of transactions successfully relayed so far.
+	pub relayed: usize,
+	/// Total number of transactions that we have failed to relay so far.
+	pub failed: usize,
+}
+
+/// Relay all suitable transactions from single block.
+///
+/// If connection error occurs, returns Err with number of successfully processed transactions.
+/// If some other error occurs, it is ignored and other transactions are processed.
+///
+/// All transaction-level traces are written by this function. This function is not tracing
+/// any information about block.
+pub async fn relay_block_transactions<P: TransactionProofPipeline>(
+	source_client: &impl SourceClient<P>,
+	target_client: &impl TargetClient<P>,
+	source_block: &P::Block,
+	mut relayed_transactions: RelayedBlockTransactions,
+) -> Result<RelayedBlockTransactions, (FailedClient, RelayedBlockTransactions)> {
+	let transactions_to_process = source_block
+		.transactions()
+		.into_iter()
+		.enumerate()
+		.skip(relayed_transactions.processed);
+	for (source_tx_index, source_tx) in transactions_to_process {
+		let result = async {
+			let source_tx_id = format!("{}/{}", source_block.id().1, source_tx_index);
+			let source_tx_proof =
+				prepare_transaction_proof(source_client, &source_tx_id, source_block, source_tx_index)
+					.await
+					.map_err(|e| (FailedClient::Source, e))?;
+
+			let needs_to_be_relayed =
+				target_client
+					.filter_transaction_proof(&source_tx_proof)
+					.await
+					.map_err(|err| {
+						(
+							FailedClient::Target,
+							StringifiedMaybeConnectionError::new(
+								err.is_connection_error(),
+								format!("Transaction filtering has failed with {:?}", err),
+							),
+						)
+					})?;
+
+			if !needs_to_be_relayed {
+				return Ok(false);
+			}
+
+			relay_ready_transaction_proof(target_client, &source_tx_id, source_tx_proof)
+				.await
+				.map(|_| true)
+				.map_err(|e| (FailedClient::Target, e))
+		}
+		.await;
+
+		// We have two options here:
+		// 1) retry with the same transaction later;
+		// 2) report error and proceed with next transaction.
+		//
+		// Option#1 may seems better, but:
+		// 1) we do not track if transaction is mined (without an error) by the target node;
+		// 2) error could be irrecoverable (e.g. when block is already pruned by bridge module or tx
+		//    has invalid format) && we'll end up in infinite loop of retrying the same transaction proof.
+		//
+		// So we're going with option#2 here (the only exception are connection errors).
+		match result {
+			Ok(false) => {
+				relayed_transactions.processed += 1;
+			}
+			Ok(true) => {
+				log::info!(
+					target: "bridge",
+					"{} transaction {} proof has been successfully submitted to {} node",
+					P::SOURCE_NAME,
+					source_tx.hash(),
+					P::TARGET_NAME,
+				);
+
+				relayed_transactions.processed += 1;
+				relayed_transactions.relayed += 1;
+			}
+			Err((failed_client, err)) => {
+				log::error!(
+					target: "bridge",
+					"Error relaying {} transaction {} proof to {} node: {}. {}",
+					P::SOURCE_NAME,
+					source_tx.hash(),
+					P::TARGET_NAME,
+					err.to_string(),
+					if err.is_connection_error() {
+						"Going to retry after delay..."
+					} else {
+						"You may need to submit proof of this transaction manually"
+					},
+				);
+
+				if err.is_connection_error() {
+					return Err((failed_client, relayed_transactions));
+				}
+
+				relayed_transactions.processed += 1;
+				relayed_transactions.failed += 1;
+			}
+		}
+	}
+
+	Ok(relayed_transactions)
+}
+
+/// Relay single transaction proof.
+pub async fn relay_single_transaction_proof<P: TransactionProofPipeline>(
+	source_client: &impl SourceClient<P>,
+	target_client: &impl TargetClient<P>,
+	source_tx_hash: TransactionHashOf<P>,
+) -> Result<(), String> {
+	// wait for transaction and header on source node
+	let (source_header_id, source_tx_index) = wait_transaction_mined(source_client, &source_tx_hash).await?;
+	let source_block = source_client.block_by_hash(source_header_id.1.clone()).await;
+	let source_block = source_block.map_err(|err| {
+		format!(
+			"Error retrieving block {} from {} node: {:?}",
+			source_header_id.1,
+			P::SOURCE_NAME,
+			err,
+		)
+	})?;
+
+	// wait for transaction and header on target node
+	wait_header_imported(target_client, &source_header_id).await?;
+	wait_header_finalized(target_client, &source_header_id).await?;
+
+	// and finally - prepare and submit transaction proof to target node
+	let source_tx_id = format!("{}", source_tx_hash);
+	relay_ready_transaction_proof(
+		target_client,
+		&source_tx_id,
+		prepare_transaction_proof(source_client, &source_tx_id, &source_block, source_tx_index)
+			.await
+			.map_err(|err| err.to_string())?,
+	)
+	.await
+	.map_err(|err| err.to_string())
+}
+
+/// Prepare transaction proof.
+async fn prepare_transaction_proof<P: TransactionProofPipeline>(
+	source_client: &impl SourceClient<P>,
+	source_tx_id: &str,
+	source_block: &P::Block,
+	source_tx_index: usize,
+) -> Result<P::TransactionProof, StringifiedMaybeConnectionError> {
+	source_client
+		.transaction_proof(source_block, source_tx_index)
+		.await
+		.map_err(|err| {
+			StringifiedMaybeConnectionError::new(
+				err.is_connection_error(),
+				format!(
+					"Error building transaction {} proof on {} node: {:?}",
+					source_tx_id,
+					P::SOURCE_NAME,
+					err,
+				),
+			)
+		})
+}
+
+/// Relay prepared proof of transaction.
+async fn relay_ready_transaction_proof<P: TransactionProofPipeline>(
+	target_client: &impl TargetClient<P>,
+	source_tx_id: &str,
+	source_tx_proof: P::TransactionProof,
+) -> Result<(), StringifiedMaybeConnectionError> {
+	target_client
+		.submit_transaction_proof(source_tx_proof)
+		.await
+		.map_err(|err| {
+			StringifiedMaybeConnectionError::new(
+				err.is_connection_error(),
+				format!(
+					"Error submitting transaction {} proof to {} node: {:?}",
+					source_tx_id,
+					P::TARGET_NAME,
+					err,
+				),
+			)
+		})
+}
+
+/// Wait until transaction is mined by source node.
+async fn wait_transaction_mined<P: TransactionProofPipeline>(
+	source_client: &impl SourceClient<P>,
+	source_tx_hash: &TransactionHashOf<P>,
+) -> Result<(HeaderId<P>, usize), String> {
+	loop {
+		let source_header_and_tx = source_client.transaction_block(&source_tx_hash).await.map_err(|err| {
+			format!(
+				"Error retrieving transaction {} from {} node: {:?}",
+				source_tx_hash,
+				P::SOURCE_NAME,
+				err,
+			)
+		})?;
+		match source_header_and_tx {
+			Some((source_header_id, source_tx)) => {
+				log::info!(
+					target: "bridge",
+					"Transaction {} is retrieved from {} node. Continuing...",
+					source_tx_hash,
+					P::SOURCE_NAME,
+				);
+
+				return Ok((source_header_id, source_tx));
+			}
+			None => {
+				log::info!(
+					target: "bridge",
+					"Waiting for transaction {} to be mined by {} node...",
+					source_tx_hash,
+					P::SOURCE_NAME,
+				);
+
+				source_client.tick().await;
+			}
+		}
+	}
+}
+
+/// Wait until target node imports required header.
+async fn wait_header_imported<P: TransactionProofPipeline>(
+	target_client: &impl TargetClient<P>,
+	source_header_id: &HeaderId<P>,
+) -> Result<(), String> {
+	loop {
+		let is_header_known = target_client.is_header_known(&source_header_id).await.map_err(|err| {
+			format!(
+				"Failed to check existence of header {}/{} on {} node: {:?}",
+				source_header_id.0,
+				source_header_id.1,
+				P::TARGET_NAME,
+				err,
+			)
+		})?;
+		match is_header_known {
+			true => {
+				log::info!(
+					target: "bridge",
+					"Header {}/{} is known to {} node. Continuing.",
+					source_header_id.0,
+					source_header_id.1,
+					P::TARGET_NAME,
+				);
+
+				return Ok(());
+			}
+			false => {
+				log::info!(
+					target: "bridge",
+					"Waiting for header {}/{} to be imported by {} node...",
+					source_header_id.0,
+					source_header_id.1,
+					P::TARGET_NAME,
+				);
+
+				target_client.tick().await;
+			}
+		}
+	}
+}
+
+/// Wait until target node finalizes required header.
+async fn wait_header_finalized<P: TransactionProofPipeline>(
+	target_client: &impl TargetClient<P>,
+	source_header_id: &HeaderId<P>,
+) -> Result<(), String> {
+	loop {
+		let is_header_finalized = target_client
+			.is_header_finalized(&source_header_id)
+			.await
+			.map_err(|err| {
+				format!(
+					"Failed to check finality of header {}/{} on {} node: {:?}",
+					source_header_id.0,
+					source_header_id.1,
+					P::TARGET_NAME,
+					err,
+				)
+			})?;
+		match is_header_finalized {
+			true => {
+				log::info!(
+					target: "bridge",
+					"Header {}/{} is finalizd by {} node. Continuing.",
+					source_header_id.0,
+					source_header_id.1,
+					P::TARGET_NAME,
+				);
+
+				return Ok(());
+			}
+			false => {
+				log::info!(
+					target: "bridge",
+					"Waiting for header {}/{} to be finalized by {} node...",
+					source_header_id.0,
+					source_header_id.1,
+					P::TARGET_NAME,
+				);
+
+				target_client.tick().await;
+			}
+		}
+	}
+}
+
+#[cfg(test)]
+pub(crate) mod tests {
+	use super::*;
+
+	use parking_lot::Mutex;
+	use relay_utils::HeaderId;
+	use std::{
+		collections::{HashMap, HashSet},
+		sync::Arc,
+	};
+
+	pub fn test_block_id() -> TestHeaderId {
+		HeaderId(1, 1)
+	}
+
+	pub fn test_next_block_id() -> TestHeaderId {
+		HeaderId(2, 2)
+	}
+
+	pub fn test_transaction_hash(tx_index: u64) -> TestTransactionHash {
+		200 + tx_index
+	}
+
+	pub fn test_transaction(tx_index: u64) -> TestTransaction {
+		TestTransaction(test_transaction_hash(tx_index))
+	}
+
+	pub fn test_block() -> TestBlock {
+		TestBlock(test_block_id(), vec![test_transaction(0)])
+	}
+
+	pub fn test_next_block() -> TestBlock {
+		TestBlock(test_next_block_id(), vec![test_transaction(1)])
+	}
+
+	pub type TestBlockNumber = u64;
+	pub type TestBlockHash = u64;
+	pub type TestTransactionHash = u64;
+	pub type TestHeaderId = HeaderId<TestBlockHash, TestBlockNumber>;
+
+	#[derive(Debug, Clone, PartialEq)]
+	pub struct TestError(pub bool);
+
+	impl MaybeConnectionError for TestError {
+		fn is_connection_error(&self) -> bool {
+			self.0
+		}
+	}
+
+	pub struct TestTransactionProofPipeline;
+
+	impl TransactionProofPipeline for TestTransactionProofPipeline {
+		const SOURCE_NAME: &'static str = "TestSource";
+		const TARGET_NAME: &'static str = "TestTarget";
+
+		type Block = TestBlock;
+		type TransactionProof = TestTransactionProof;
+	}
+
+	#[derive(Debug, Clone)]
+	pub struct TestBlock(pub TestHeaderId, pub Vec<TestTransaction>);
+
+	impl SourceBlock for TestBlock {
+		type Hash = TestBlockHash;
+		type Number = TestBlockNumber;
+		type Transaction = TestTransaction;
+
+		fn id(&self) -> TestHeaderId {
+			self.0
+		}
+
+		fn transactions(&self) -> Vec<TestTransaction> {
+			self.1.clone()
+		}
+	}
+
+	#[derive(Debug, Clone)]
+	pub struct TestTransaction(pub TestTransactionHash);
+
+	impl SourceTransaction for TestTransaction {
+		type Hash = TestTransactionHash;
+
+		fn hash(&self) -> Self::Hash {
+			self.0
+		}
+	}
+
+	#[derive(Debug, Clone, PartialEq)]
+	pub struct TestTransactionProof(pub TestTransactionHash);
+
+	#[derive(Clone)]
+	pub struct TestTransactionsSource {
+		pub on_tick: Arc<dyn Fn(&mut TestTransactionsSourceData) + Send + Sync>,
+		pub data: Arc<Mutex<TestTransactionsSourceData>>,
+	}
+
+	pub struct TestTransactionsSourceData {
+		pub block: Result<TestBlock, TestError>,
+		pub transaction_block: Result<Option<(TestHeaderId, usize)>, TestError>,
+		pub proofs_to_fail: HashMap<TestTransactionHash, TestError>,
+	}
+
+	impl TestTransactionsSource {
+		pub fn new(on_tick: Box<dyn Fn(&mut TestTransactionsSourceData) + Send + Sync>) -> Self {
+			Self {
+				on_tick: Arc::new(on_tick),
+				data: Arc::new(Mutex::new(TestTransactionsSourceData {
+					block: Ok(test_block()),
+					transaction_block: Ok(Some((test_block_id(), 0))),
+					proofs_to_fail: HashMap::new(),
+				})),
+			}
+		}
+	}
+
+	#[async_trait]
+	impl RelayClient for TestTransactionsSource {
+		type Error = TestError;
+
+		async fn reconnect(&mut self) -> Result<(), TestError> {
+			Ok(())
+		}
+	}
+
+	#[async_trait]
+	impl SourceClient<TestTransactionProofPipeline> for TestTransactionsSource {
+		async fn tick(&self) {
+			(self.on_tick)(&mut *self.data.lock())
+		}
+
+		async fn block_by_hash(&self, _: TestBlockHash) -> Result<TestBlock, TestError> {
+			self.data.lock().block.clone()
+		}
+
+		async fn block_by_number(&self, _: TestBlockNumber) -> Result<TestBlock, TestError> {
+			self.data.lock().block.clone()
+		}
+
+		async fn transaction_block(&self, _: &TestTransactionHash) -> Result<Option<(TestHeaderId, usize)>, TestError> {
+			self.data.lock().transaction_block.clone()
+		}
+
+		async fn transaction_proof(&self, block: &TestBlock, index: usize) -> Result<TestTransactionProof, TestError> {
+			let tx_hash = block.1[index].hash();
+			let proof_error = self.data.lock().proofs_to_fail.get(&tx_hash).cloned();
+			if let Some(err) = proof_error {
+				return Err(err);
+			}
+
+			Ok(TestTransactionProof(tx_hash))
+		}
+	}
+
+	#[derive(Clone)]
+	pub struct TestTransactionsTarget {
+		pub on_tick: Arc<dyn Fn(&mut TestTransactionsTargetData) + Send + Sync>,
+		pub data: Arc<Mutex<TestTransactionsTargetData>>,
+	}
+
+	pub struct TestTransactionsTargetData {
+		pub is_header_known: Result<bool, TestError>,
+		pub is_header_finalized: Result<bool, TestError>,
+		pub best_finalized_header_id: Result<TestHeaderId, TestError>,
+		pub transactions_to_accept: HashSet<TestTransactionHash>,
+		pub submitted_proofs: Vec<TestTransactionProof>,
+	}
+
+	impl TestTransactionsTarget {
+		pub fn new(on_tick: Box<dyn Fn(&mut TestTransactionsTargetData) + Send + Sync>) -> Self {
+			Self {
+				on_tick: Arc::new(on_tick),
+				data: Arc::new(Mutex::new(TestTransactionsTargetData {
+					is_header_known: Ok(true),
+					is_header_finalized: Ok(true),
+					best_finalized_header_id: Ok(test_block_id()),
+					transactions_to_accept: vec![test_transaction_hash(0)].into_iter().collect(),
+					submitted_proofs: Vec::new(),
+				})),
+			}
+		}
+	}
+
+	#[async_trait]
+	impl RelayClient for TestTransactionsTarget {
+		type Error = TestError;
+
+		async fn reconnect(&mut self) -> Result<(), TestError> {
+			Ok(())
+		}
+	}
+
+	#[async_trait]
+	impl TargetClient<TestTransactionProofPipeline> for TestTransactionsTarget {
+		async fn tick(&self) {
+			(self.on_tick)(&mut *self.data.lock())
+		}
+
+		async fn is_header_known(&self, _: &TestHeaderId) -> Result<bool, TestError> {
+			self.data.lock().is_header_known.clone()
+		}
+
+		async fn is_header_finalized(&self, _: &TestHeaderId) -> Result<bool, TestError> {
+			self.data.lock().is_header_finalized.clone()
+		}
+
+		async fn best_finalized_header_id(&self) -> Result<TestHeaderId, TestError> {
+			self.data.lock().best_finalized_header_id.clone()
+		}
+
+		async fn filter_transaction_proof(&self, proof: &TestTransactionProof) -> Result<bool, TestError> {
+			Ok(self.data.lock().transactions_to_accept.contains(&proof.0))
+		}
+
+		async fn submit_transaction_proof(&self, proof: TestTransactionProof) -> Result<(), TestError> {
+			self.data.lock().submitted_proofs.push(proof);
+			Ok(())
+		}
+	}
+
+	fn ensure_relay_single_success(source: &TestTransactionsSource, target: &TestTransactionsTarget) {
+		assert_eq!(
+			async_std::task::block_on(relay_single_transaction_proof(source, target, test_transaction_hash(0),)),
+			Ok(()),
+		);
+		assert_eq!(
+			target.data.lock().submitted_proofs,
+			vec![TestTransactionProof(test_transaction_hash(0))],
+		);
+	}
+
+	fn ensure_relay_single_failure(source: TestTransactionsSource, target: TestTransactionsTarget) {
+		assert!(async_std::task::block_on(relay_single_transaction_proof(
+			&source,
+			&target,
+			test_transaction_hash(0),
+		))
+		.is_err(),);
+		assert!(target.data.lock().submitted_proofs.is_empty());
+	}
+
+	#[test]
+	fn ready_transaction_proof_relayed_immediately() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+		ensure_relay_single_success(&source, &target)
+	}
+
+	#[test]
+	fn relay_transaction_proof_waits_for_transaction_to_be_mined() {
+		let source = TestTransactionsSource::new(Box::new(|source_data| {
+			assert_eq!(source_data.transaction_block, Ok(None));
+			source_data.transaction_block = Ok(Some((test_block_id(), 0)));
+		}));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		// transaction is not yet mined, but will be available after first wait (tick)
+		source.data.lock().transaction_block = Ok(None);
+
+		ensure_relay_single_success(&source, &target)
+	}
+
+	#[test]
+	fn relay_transaction_fails_when_transaction_retrieval_fails() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		source.data.lock().transaction_block = Err(TestError(false));
+
+		ensure_relay_single_failure(source, target)
+	}
+
+	#[test]
+	fn relay_transaction_fails_when_proof_retrieval_fails() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		source
+			.data
+			.lock()
+			.proofs_to_fail
+			.insert(test_transaction_hash(0), TestError(false));
+
+		ensure_relay_single_failure(source, target)
+	}
+
+	#[test]
+	fn relay_transaction_proof_waits_for_header_to_be_imported() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|target_data| {
+			assert_eq!(target_data.is_header_known, Ok(false));
+			target_data.is_header_known = Ok(true);
+		}));
+
+		// header is not yet imported, but will be available after first wait (tick)
+		target.data.lock().is_header_known = Ok(false);
+
+		ensure_relay_single_success(&source, &target)
+	}
+
+	#[test]
+	fn relay_transaction_proof_fails_when_is_header_known_fails() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		target.data.lock().is_header_known = Err(TestError(false));
+
+		ensure_relay_single_failure(source, target)
+	}
+
+	#[test]
+	fn relay_transaction_proof_waits_for_header_to_be_finalized() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|target_data| {
+			assert_eq!(target_data.is_header_finalized, Ok(false));
+			target_data.is_header_finalized = Ok(true);
+		}));
+
+		// header is not yet finalized, but will be available after first wait (tick)
+		target.data.lock().is_header_finalized = Ok(false);
+
+		ensure_relay_single_success(&source, &target)
+	}
+
+	#[test]
+	fn relay_transaction_proof_fails_when_is_header_finalized_fails() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		target.data.lock().is_header_finalized = Err(TestError(false));
+
+		ensure_relay_single_failure(source, target)
+	}
+
+	#[test]
+	fn relay_transaction_proof_fails_when_target_node_rejects_proof() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		target
+			.data
+			.lock()
+			.transactions_to_accept
+			.remove(&test_transaction_hash(0));
+
+		ensure_relay_single_success(&source, &target)
+	}
+
+	fn test_relay_block_transactions(
+		source: &TestTransactionsSource,
+		target: &TestTransactionsTarget,
+		pre_relayed: RelayedBlockTransactions,
+	) -> Result<RelayedBlockTransactions, RelayedBlockTransactions> {
+		async_std::task::block_on(relay_block_transactions(
+			source,
+			target,
+			&TestBlock(
+				test_block_id(),
+				vec![test_transaction(0), test_transaction(1), test_transaction(2)],
+			),
+			pre_relayed,
+		))
+		.map_err(|(_, transactions)| transactions)
+	}
+
+	#[test]
+	fn relay_block_transactions_process_all_transactions() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		// let's only accept tx#1
+		target
+			.data
+			.lock()
+			.transactions_to_accept
+			.remove(&test_transaction_hash(0));
+		target
+			.data
+			.lock()
+			.transactions_to_accept
+			.insert(test_transaction_hash(1));
+
+		let relayed_transactions = test_relay_block_transactions(&source, &target, Default::default());
+		assert_eq!(
+			relayed_transactions,
+			Ok(RelayedBlockTransactions {
+				processed: 3,
+				relayed: 1,
+				failed: 0,
+			}),
+		);
+		assert_eq!(
+			target.data.lock().submitted_proofs,
+			vec![TestTransactionProof(test_transaction_hash(1))],
+		);
+	}
+
+	#[test]
+	fn relay_block_transactions_ignores_transaction_failure() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		// let's reject proof for tx#0
+		source
+			.data
+			.lock()
+			.proofs_to_fail
+			.insert(test_transaction_hash(0), TestError(false));
+
+		let relayed_transactions = test_relay_block_transactions(&source, &target, Default::default());
+		assert_eq!(
+			relayed_transactions,
+			Ok(RelayedBlockTransactions {
+				processed: 3,
+				relayed: 0,
+				failed: 1,
+			}),
+		);
+		assert_eq!(target.data.lock().submitted_proofs, vec![],);
+	}
+
+	#[test]
+	fn relay_block_transactions_fails_on_connection_error() {
+		let source = TestTransactionsSource::new(Box::new(|_| unreachable!("no ticks allowed")));
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no ticks allowed")));
+
+		// fail with connection error when preparing proof for tx#1
+		source
+			.data
+			.lock()
+			.proofs_to_fail
+			.insert(test_transaction_hash(1), TestError(true));
+
+		let relayed_transactions = test_relay_block_transactions(&source, &target, Default::default());
+		assert_eq!(
+			relayed_transactions,
+			Err(RelayedBlockTransactions {
+				processed: 1,
+				relayed: 1,
+				failed: 0,
+			}),
+		);
+		assert_eq!(
+			target.data.lock().submitted_proofs,
+			vec![TestTransactionProof(test_transaction_hash(0))],
+		);
+
+		// now do not fail on tx#2
+		source.data.lock().proofs_to_fail.clear();
+		// and also relay tx#3
+		target
+			.data
+			.lock()
+			.transactions_to_accept
+			.insert(test_transaction_hash(2));
+
+		let relayed_transactions = test_relay_block_transactions(&source, &target, relayed_transactions.unwrap_err());
+		assert_eq!(
+			relayed_transactions,
+			Ok(RelayedBlockTransactions {
+				processed: 3,
+				relayed: 2,
+				failed: 0,
+			}),
+		);
+		assert_eq!(
+			target.data.lock().submitted_proofs,
+			vec![
+				TestTransactionProof(test_transaction_hash(0)),
+				TestTransactionProof(test_transaction_hash(2))
+			],
+		);
+	}
+}

polkadot/bridges/relays/exchange/src/exchange_loop.rs

@@ -0,0 +1,315 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Relaying proofs of exchange transactions.
+
+use crate::exchange::{
+	relay_block_transactions, BlockNumberOf, RelayedBlockTransactions, SourceClient, TargetClient,
+	TransactionProofPipeline,
+};
+use crate::exchange_loop_metrics::ExchangeLoopMetrics;
+
+use backoff::backoff::Backoff;
+use futures::{future::FutureExt, select};
+use num_traits::One;
+use relay_utils::{
+	metrics::{GlobalMetrics, MetricsParams},
+	retry_backoff, FailedClient, MaybeConnectionError,
+};
+use std::future::Future;
+
+/// Transactions proofs relay state.
+#[derive(Debug)]
+pub struct TransactionProofsRelayState<BlockNumber> {
+	/// Number of last header we have processed so far.
+	pub best_processed_header_number: BlockNumber,
+}
+
+/// Transactions proofs relay storage.
+pub trait TransactionProofsRelayStorage: Clone {
+	/// Associated block number.
+	type BlockNumber;
+
+	/// Get relay state.
+	fn state(&self) -> TransactionProofsRelayState<Self::BlockNumber>;
+	/// Update relay state.
+	fn set_state(&mut self, state: &TransactionProofsRelayState<Self::BlockNumber>);
+}
+
+/// In-memory storage for auto-relay loop.
+#[derive(Debug, Clone)]
+pub struct InMemoryStorage<BlockNumber> {
+	best_processed_header_number: BlockNumber,
+}
+
+impl<BlockNumber> InMemoryStorage<BlockNumber> {
+	/// Created new in-memory storage with given best processed block number.
+	pub fn new(best_processed_header_number: BlockNumber) -> Self {
+		InMemoryStorage {
+			best_processed_header_number,
+		}
+	}
+}
+
+impl<BlockNumber: Clone + Copy> TransactionProofsRelayStorage for InMemoryStorage<BlockNumber> {
+	type BlockNumber = BlockNumber;
+
+	fn state(&self) -> TransactionProofsRelayState<BlockNumber> {
+		TransactionProofsRelayState {
+			best_processed_header_number: self.best_processed_header_number,
+		}
+	}
+
+	fn set_state(&mut self, state: &TransactionProofsRelayState<BlockNumber>) {
+		self.best_processed_header_number = state.best_processed_header_number;
+	}
+}
+
+/// Return prefix that will be used by default to expose Prometheus metrics of the exchange loop.
+pub fn metrics_prefix<P: TransactionProofPipeline>() -> String {
+	format!("{}_to_{}_Exchange", P::SOURCE_NAME, P::TARGET_NAME)
+}
+
+/// Run proofs synchronization.
+pub async fn run<P: TransactionProofPipeline>(
+	storage: impl TransactionProofsRelayStorage<BlockNumber = BlockNumberOf<P>>,
+	source_client: impl SourceClient<P>,
+	target_client: impl TargetClient<P>,
+	metrics_params: MetricsParams,
+	exit_signal: impl Future<Output = ()>,
+) -> Result<(), String> {
+	let exit_signal = exit_signal.shared();
+
+	relay_utils::relay_loop(source_client, target_client)
+		.with_metrics(Some(metrics_prefix::<P>()), metrics_params)
+		.loop_metric(|registry, prefix| ExchangeLoopMetrics::new(registry, prefix))?
+		.standalone_metric(|registry, prefix| GlobalMetrics::new(registry, prefix))?
+		.expose()
+		.await?
+		.run(|source_client, target_client, metrics| {
+			run_until_connection_lost(
+				storage.clone(),
+				source_client,
+				target_client,
+				metrics,
+				exit_signal.clone(),
+			)
+		})
+		.await
+}
+
+/// Run proofs synchronization.
+async fn run_until_connection_lost<P: TransactionProofPipeline>(
+	mut storage: impl TransactionProofsRelayStorage<BlockNumber = BlockNumberOf<P>>,
+	source_client: impl SourceClient<P>,
+	target_client: impl TargetClient<P>,
+	metrics_exch: Option<ExchangeLoopMetrics>,
+	exit_signal: impl Future<Output = ()>,
+) -> Result<(), FailedClient> {
+	let mut retry_backoff = retry_backoff();
+	let mut state = storage.state();
+	let mut current_finalized_block = None;
+
+	let exit_signal = exit_signal.fuse();
+
+	futures::pin_mut!(exit_signal);
+
+	loop {
+		let iteration_result = run_loop_iteration(
+			&mut storage,
+			&source_client,
+			&target_client,
+			&mut state,
+			&mut current_finalized_block,
+			metrics_exch.as_ref(),
+		)
+		.await;
+
+		if let Err((is_connection_error, failed_client)) = iteration_result {
+			if is_connection_error {
+				return Err(failed_client);
+			}
+
+			let retry_timeout = retry_backoff
+				.next_backoff()
+				.unwrap_or(relay_utils::relay_loop::RECONNECT_DELAY);
+			select! {
+				_ = async_std::task::sleep(retry_timeout).fuse() => {},
+				_ = exit_signal => return Ok(()),
+			}
+		} else {
+			retry_backoff.reset();
+
+			select! {
+				_ = source_client.tick().fuse() => {},
+				_ = exit_signal => return Ok(()),
+			}
+		}
+	}
+}
+
+/// Run exchange loop until we need to break.
+async fn run_loop_iteration<P: TransactionProofPipeline>(
+	storage: &mut impl TransactionProofsRelayStorage<BlockNumber = BlockNumberOf<P>>,
+	source_client: &impl SourceClient<P>,
+	target_client: &impl TargetClient<P>,
+	state: &mut TransactionProofsRelayState<BlockNumberOf<P>>,
+	current_finalized_block: &mut Option<(P::Block, RelayedBlockTransactions)>,
+	exchange_loop_metrics: Option<&ExchangeLoopMetrics>,
+) -> Result<(), (bool, FailedClient)> {
+	let best_finalized_header_id = match target_client.best_finalized_header_id().await {
+		Ok(best_finalized_header_id) => {
+			log::debug!(
+				target: "bridge",
+				"Got best finalized {} block from {} node: {:?}",
+				P::SOURCE_NAME,
+				P::TARGET_NAME,
+				best_finalized_header_id,
+			);
+
+			best_finalized_header_id
+		}
+		Err(err) => {
+			log::error!(
+				target: "bridge",
+				"Failed to retrieve best {} header id from {} node: {:?}. Going to retry...",
+				P::SOURCE_NAME,
+				P::TARGET_NAME,
+				err,
+			);
+
+			return Err((err.is_connection_error(), FailedClient::Target));
+		}
+	};
+
+	loop {
+		// if we already have some finalized block body, try to relay its transactions
+		if let Some((block, relayed_transactions)) = current_finalized_block.take() {
+			let result = relay_block_transactions(source_client, target_client, &block, relayed_transactions).await;
+
+			match result {
+				Ok(relayed_transactions) => {
+					log::info!(
+						target: "bridge",
+						"Relay has processed {} block #{}. Total/Relayed/Failed transactions: {}/{}/{}",
+						P::SOURCE_NAME,
+						state.best_processed_header_number,
+						relayed_transactions.processed,
+						relayed_transactions.relayed,
+						relayed_transactions.failed,
+					);
+
+					state.best_processed_header_number = state.best_processed_header_number + One::one();
+					storage.set_state(state);
+
+					if let Some(ref exchange_loop_metrics) = exchange_loop_metrics {
+						exchange_loop_metrics.update::<P>(
+							state.best_processed_header_number,
+							best_finalized_header_id.0,
+							relayed_transactions,
+						);
+					}
+
+					// we have just updated state => proceed to next block retrieval
+				}
+				Err((failed_client, relayed_transactions)) => {
+					*current_finalized_block = Some((block, relayed_transactions));
+					return Err((true, failed_client));
+				}
+			}
+		}
+
+		// we may need to retrieve finalized block body from source node
+		if best_finalized_header_id.0 > state.best_processed_header_number {
+			let next_block_number = state.best_processed_header_number + One::one();
+			let result = source_client.block_by_number(next_block_number).await;
+
+			match result {
+				Ok(block) => {
+					*current_finalized_block = Some((block, RelayedBlockTransactions::default()));
+
+					// we have received new finalized block => go back to relay its transactions
+					continue;
+				}
+				Err(err) => {
+					log::error!(
+						target: "bridge",
+						"Failed to retrieve canonical block #{} from {} node: {:?}. Going to retry...",
+						next_block_number,
+						P::SOURCE_NAME,
+						err,
+					);
+
+					return Err((err.is_connection_error(), FailedClient::Source));
+				}
+			}
+		}
+
+		// there are no any transactions we need to relay => wait for new data
+		return Ok(());
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+	use crate::exchange::tests::{
+		test_next_block, test_next_block_id, test_transaction_hash, TestTransactionProof, TestTransactionsSource,
+		TestTransactionsTarget,
+	};
+	use futures::{future::FutureExt, stream::StreamExt};
+
+	#[test]
+	fn exchange_loop_is_able_to_relay_proofs() {
+		let storage = InMemoryStorage {
+			best_processed_header_number: 0,
+		};
+		let target = TestTransactionsTarget::new(Box::new(|_| unreachable!("no target ticks allowed")));
+		let target_data = target.data.clone();
+		let (exit_sender, exit_receiver) = futures::channel::mpsc::unbounded();
+
+		let source = TestTransactionsSource::new(Box::new(move |data| {
+			let transaction1_relayed = target_data
+				.lock()
+				.submitted_proofs
+				.contains(&TestTransactionProof(test_transaction_hash(0)));
+			let transaction2_relayed = target_data
+				.lock()
+				.submitted_proofs
+				.contains(&TestTransactionProof(test_transaction_hash(1)));
+			match (transaction1_relayed, transaction2_relayed) {
+				(true, true) => exit_sender.unbounded_send(()).unwrap(),
+				(true, false) => {
+					data.block = Ok(test_next_block());
+					target_data.lock().best_finalized_header_id = Ok(test_next_block_id());
+					target_data
+						.lock()
+						.transactions_to_accept
+						.insert(test_transaction_hash(1));
+				}
+				_ => (),
+			}
+		}));
+
+		let _ = async_std::task::block_on(run(
+			storage,
+			source,
+			target,
+			MetricsParams::disabled(),
+			exit_receiver.into_future().map(|(_, _)| ()),
+		));
+	}
+}

polkadot/bridges/relays/exchange/src/exchange_loop_metrics.rs

@@ -0,0 +1,97 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Metrics for currency-exchange relay loop.
+
+use crate::exchange::{BlockNumberOf, RelayedBlockTransactions, TransactionProofPipeline};
+use relay_utils::metrics::{
+	metric_name, register, Counter, CounterVec, GaugeVec, Opts, PrometheusError, Registry, U64,
+};
+
+/// Exchange transactions relay metrics.
+#[derive(Clone)]
+pub struct ExchangeLoopMetrics {
+	/// Best finalized block numbers - "processed" and "known".
+	best_block_numbers: GaugeVec<U64>,
+	/// Number of processed blocks ("total").
+	processed_blocks: Counter<U64>,
+	/// Number of processed transactions ("total", "relayed" and "failed").
+	processed_transactions: CounterVec<U64>,
+}
+
+impl ExchangeLoopMetrics {
+	/// Create and register exchange loop metrics.
+	pub fn new(registry: &Registry, prefix: Option<&str>) -> Result<Self, PrometheusError> {
+		Ok(ExchangeLoopMetrics {
+			best_block_numbers: register(
+				GaugeVec::new(
+					Opts::new(
+						metric_name(prefix, "best_block_numbers"),
+						"Best finalized block numbers",
+					),
+					&["type"],
+				)?,
+				registry,
+			)?,
+			processed_blocks: register(
+				Counter::new(
+					metric_name(prefix, "processed_blocks"),
+					"Total number of processed blocks",
+				)?,
+				registry,
+			)?,
+			processed_transactions: register(
+				CounterVec::new(
+					Opts::new(
+						metric_name(prefix, "processed_transactions"),
+						"Total number of processed transactions",
+					),
+					&["type"],
+				)?,
+				registry,
+			)?,
+		})
+	}
+}
+
+impl ExchangeLoopMetrics {
+	/// Update metrics when single block is relayed.
+	pub fn update<P: TransactionProofPipeline>(
+		&self,
+		best_processed_block_number: BlockNumberOf<P>,
+		best_known_block_number: BlockNumberOf<P>,
+		relayed_transactions: RelayedBlockTransactions,
+	) {
+		self.best_block_numbers
+			.with_label_values(&["processed"])
+			.set(best_processed_block_number.into());
+		self.best_block_numbers
+			.with_label_values(&["known"])
+			.set(best_known_block_number.into());
+
+		self.processed_blocks.inc();
+
+		self.processed_transactions
+			.with_label_values(&["total"])
+			.inc_by(relayed_transactions.processed as _);
+		self.processed_transactions
+			.with_label_values(&["relayed"])
+			.inc_by(relayed_transactions.relayed as _);
+		self.processed_transactions
+			.with_label_values(&["failed"])
+			.inc_by(relayed_transactions.failed as _);
+	}
+}

polkadot/bridges/relays/exchange/src/lib.rs

@@ -0,0 +1,26 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Relaying [`currency-exchange`](../pallet_bridge_currency_exchange/index.html) application
+//! specific data. Currency exchange application allows exchanging tokens between bridged chains.
+//! This module provides entrypoints for crafting and submitting (single and multiple)
+//! proof-of-exchange-at-source-chain transaction(s) to target chain.
+
+#![warn(missing_docs)]
+
+pub mod exchange;
+pub mod exchange_loop;
+pub mod exchange_loop_metrics;

polkadot/bridges/relays/finality/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "finality-relay"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+description = "Finality proofs relay"
+
+[dependencies]
+async-std = "1.6.5"
+async-trait = "0.1.40"
+backoff = "0.2"
+bp-header-chain = { path = "../../primitives/header-chain" }
+futures = "0.3.5"
+headers-relay = { path = "../headers" }
+log = "0.4.11"
+num-traits = "0.2"
+relay-utils = { path = "../utils" }
+
+[dev-dependencies]
+parking_lot = "0.11.0"

polkadot/bridges/relays/finality/src/finality_loop.rs

@@ -0,0 +1,599 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! The loop basically reads all missing headers and their finality proofs from the source client.
+//! The proof for the best possible header is then submitted to the target node. The only exception
+//! is the mandatory headers, which we always submit to the target node. For such headers, we
+//! assume that the persistent proof either exists, or will eventually become available.
+
+use crate::{FinalityProof, FinalitySyncPipeline, SourceHeader};
+
+use async_trait::async_trait;
+use backoff::backoff::Backoff;
+use futures::{select, Future, FutureExt, Stream, StreamExt};
+use headers_relay::sync_loop_metrics::SyncLoopMetrics;
+use num_traits::{One, Saturating};
+use relay_utils::{
+	metrics::{GlobalMetrics, MetricsParams},
+	relay_loop::Client as RelayClient,
+	retry_backoff, FailedClient, MaybeConnectionError,
+};
+use std::{
+	pin::Pin,
+	time::{Duration, Instant},
+};
+
+/// Finality proof synchronization loop parameters.
+#[derive(Debug, Clone)]
+pub struct FinalitySyncParams {
+	/// Interval at which we check updates on both clients. Normally should be larger than
+	/// `min(source_block_time, target_block_time)`.
+	///
+	/// This parameter may be used to limit transactions rate. Increase the value && you'll get
+	/// infrequent updates => sparse headers => potential slow down of bridge applications, but pallet storage
+	/// won't be super large. Decrease the value to near `source_block_time` and you'll get
+	/// transaction for (almost) every block of the source chain => all source headers will be known
+	/// to the target chain => bridge applications will run faster, but pallet storage may explode
+	/// (but if pruning is there, then it's fine).
+	pub tick: Duration,
+	/// Number of finality proofs to keep in internal buffer between loop wakeups.
+	///
+	/// While in "major syncing" state, we still read finality proofs from the stream. They're stored
+	/// in the internal buffer between loop wakeups. When we're close to the tip of the chain, we may
+	/// meet finality delays if headers are not finalized frequently. So instead of waiting for next
+	/// finality proof to appear in the stream, we may use existing proof from that buffer.
+	pub recent_finality_proofs_limit: usize,
+	/// Timeout before we treat our transactions as lost and restart the whole sync process.
+	pub stall_timeout: Duration,
+}
+
+/// Source client used in finality synchronization loop.
+#[async_trait]
+pub trait SourceClient<P: FinalitySyncPipeline>: RelayClient {
+	/// Stream of new finality proofs. The stream is allowed to miss proofs for some
+	/// headers, even if those headers are mandatory.
+	type FinalityProofsStream: Stream<Item = P::FinalityProof>;
+
+	/// Get best finalized block number.
+	async fn best_finalized_block_number(&self) -> Result<P::Number, Self::Error>;
+
+	/// Get canonical header and its finality proof by number.
+	async fn header_and_finality_proof(
+		&self,
+		number: P::Number,
+	) -> Result<(P::Header, Option<P::FinalityProof>), Self::Error>;
+
+	/// Subscribe to new finality proofs.
+	async fn finality_proofs(&self) -> Result<Self::FinalityProofsStream, Self::Error>;
+}
+
+/// Target client used in finality synchronization loop.
+#[async_trait]
+pub trait TargetClient<P: FinalitySyncPipeline>: RelayClient {
+	/// Get best finalized source block number.
+	async fn best_finalized_source_block_number(&self) -> Result<P::Number, Self::Error>;
+
+	/// Submit header finality proof.
+	async fn submit_finality_proof(&self, header: P::Header, proof: P::FinalityProof) -> Result<(), Self::Error>;
+}
+
+/// Return prefix that will be used by default to expose Prometheus metrics of the finality proofs sync loop.
+pub fn metrics_prefix<P: FinalitySyncPipeline>() -> String {
+	format!("{}_to_{}_Sync", P::SOURCE_NAME, P::TARGET_NAME)
+}
+
+/// Run finality proofs synchronization loop.
+pub async fn run<P: FinalitySyncPipeline>(
+	source_client: impl SourceClient<P>,
+	target_client: impl TargetClient<P>,
+	sync_params: FinalitySyncParams,
+	metrics_params: MetricsParams,
+	exit_signal: impl Future<Output = ()>,
+) -> Result<(), String> {
+	let exit_signal = exit_signal.shared();
+	relay_utils::relay_loop(source_client, target_client)
+		.with_metrics(Some(metrics_prefix::<P>()), metrics_params)
+		.loop_metric(|registry, prefix| SyncLoopMetrics::new(registry, prefix))?
+		.standalone_metric(|registry, prefix| GlobalMetrics::new(registry, prefix))?
+		.expose()
+		.await?
+		.run(|source_client, target_client, metrics| {
+			run_until_connection_lost(
+				source_client,
+				target_client,
+				sync_params.clone(),
+				metrics,
+				exit_signal.clone(),
+			)
+		})
+		.await
+}
+
+/// Unjustified headers container. Ordered by header number.
+pub(crate) type UnjustifiedHeaders<H> = Vec<H>;
+/// Finality proofs container. Ordered by target header number.
+pub(crate) type FinalityProofs<P> = Vec<(
+	<P as FinalitySyncPipeline>::Number,
+	<P as FinalitySyncPipeline>::FinalityProof,
+)>;
+/// Reference to finality proofs container.
+pub(crate) type FinalityProofsRef<'a, P> = &'a [(
+	<P as FinalitySyncPipeline>::Number,
+	<P as FinalitySyncPipeline>::FinalityProof,
+)];
+
+/// Error that may happen inside finality synchronization loop.
+#[derive(Debug)]
+pub(crate) enum Error<P: FinalitySyncPipeline, SourceError, TargetError> {
+	/// Source client request has failed with given error.
+	Source(SourceError),
+	/// Target client request has failed with given error.
+	Target(TargetError),
+	/// Finality proof for mandatory header is missing from the source node.
+	MissingMandatoryFinalityProof(P::Number),
+	/// The synchronization has stalled.
+	Stalled,
+}
+
+impl<P, SourceError, TargetError> Error<P, SourceError, TargetError>
+where
+	P: FinalitySyncPipeline,
+	SourceError: MaybeConnectionError,
+	TargetError: MaybeConnectionError,
+{
+	fn fail_if_connection_error(&self) -> Result<(), FailedClient> {
+		match *self {
+			Error::Source(ref error) if error.is_connection_error() => Err(FailedClient::Source),
+			Error::Target(ref error) if error.is_connection_error() => Err(FailedClient::Target),
+			Error::Stalled => Err(FailedClient::Both),
+			_ => Ok(()),
+		}
+	}
+}
+
+/// Information about transaction that we have submitted.
+#[derive(Debug, Clone)]
+struct Transaction<Number> {
+	/// Time when we have submitted this transaction.
+	pub time: Instant,
+	/// The number of the header we have submitted.
+	pub submitted_header_number: Number,
+}
+
+/// Finality proofs stream that may be restarted.
+pub(crate) struct RestartableFinalityProofsStream<S> {
+	/// Flag that the stream needs to be restarted.
+	pub(crate) needs_restart: bool,
+	/// The stream itself.
+	stream: Pin<Box<S>>,
+}
+
+#[cfg(test)]
+impl<S> From<S> for RestartableFinalityProofsStream<S> {
+	fn from(stream: S) -> Self {
+		RestartableFinalityProofsStream {
+			needs_restart: false,
+			stream: Box::pin(stream),
+		}
+	}
+}
+
+/// Finality synchronization loop state.
+struct FinalityLoopState<'a, P: FinalitySyncPipeline, FinalityProofsStream> {
+	/// Synchronization loop progress.
+	progress: &'a mut (Instant, Option<P::Number>),
+	/// Finality proofs stream.
+	finality_proofs_stream: &'a mut RestartableFinalityProofsStream<FinalityProofsStream>,
+	/// Recent finality proofs that we have read from the stream.
+	recent_finality_proofs: &'a mut FinalityProofs<P>,
+	/// Last transaction that we have submitted to the target node.
+	last_transaction: Option<Transaction<P::Number>>,
+}
+
+async fn run_until_connection_lost<P: FinalitySyncPipeline>(
+	source_client: impl SourceClient<P>,
+	target_client: impl TargetClient<P>,
+	sync_params: FinalitySyncParams,
+	metrics_sync: Option<SyncLoopMetrics>,
+	exit_signal: impl Future<Output = ()>,
+) -> Result<(), FailedClient> {
+	let restart_finality_proofs_stream = || async {
+		source_client.finality_proofs().await.map_err(|error| {
+			log::error!(
+				target: "bridge",
+				"Failed to subscribe to {} justifications: {:?}. Going to reconnect",
+				P::SOURCE_NAME,
+				error,
+			);
+
+			FailedClient::Source
+		})
+	};
+
+	let exit_signal = exit_signal.fuse();
+	futures::pin_mut!(exit_signal);
+
+	let mut finality_proofs_stream = RestartableFinalityProofsStream {
+		needs_restart: false,
+		stream: Box::pin(restart_finality_proofs_stream().await?),
+	};
+	let mut recent_finality_proofs = Vec::new();
+
+	let mut progress = (Instant::now(), None);
+	let mut retry_backoff = retry_backoff();
+	let mut last_transaction = None;
+
+	loop {
+		// run loop iteration
+		let iteration_result = run_loop_iteration(
+			&source_client,
+			&target_client,
+			FinalityLoopState {
+				progress: &mut progress,
+				finality_proofs_stream: &mut finality_proofs_stream,
+				recent_finality_proofs: &mut recent_finality_proofs,
+				last_transaction: last_transaction.clone(),
+			},
+			&sync_params,
+			&metrics_sync,
+		)
+		.await;
+
+		// deal with errors
+		let next_tick = match iteration_result {
+			Ok(updated_last_transaction) => {
+				last_transaction = updated_last_transaction;
+				retry_backoff.reset();
+				sync_params.tick
+			}
+			Err(error) => {
+				log::error!(target: "bridge", "Finality sync loop iteration has failed with error: {:?}", error);
+				error.fail_if_connection_error()?;
+				retry_backoff
+					.next_backoff()
+					.unwrap_or(relay_utils::relay_loop::RECONNECT_DELAY)
+			}
+		};
+		if finality_proofs_stream.needs_restart {
+			log::warn!(target: "bridge", "{} finality proofs stream is being restarted", P::SOURCE_NAME);
+
+			finality_proofs_stream.needs_restart = false;
+			finality_proofs_stream.stream = Box::pin(restart_finality_proofs_stream().await?);
+		}
+
+		// wait till exit signal, or new source block
+		select! {
+			_ = async_std::task::sleep(next_tick).fuse() => {},
+			_ = exit_signal => return Ok(()),
+		}
+	}
+}
+
+async fn run_loop_iteration<P, SC, TC>(
+	source_client: &SC,
+	target_client: &TC,
+	state: FinalityLoopState<'_, P, SC::FinalityProofsStream>,
+	sync_params: &FinalitySyncParams,
+	metrics_sync: &Option<SyncLoopMetrics>,
+) -> Result<Option<Transaction<P::Number>>, Error<P, SC::Error, TC::Error>>
+where
+	P: FinalitySyncPipeline,
+	SC: SourceClient<P>,
+	TC: TargetClient<P>,
+{
+	// read best source headers ids from source and target nodes
+	let best_number_at_source = source_client
+		.best_finalized_block_number()
+		.await
+		.map_err(Error::Source)?;
+	let best_number_at_target = target_client
+		.best_finalized_source_block_number()
+		.await
+		.map_err(Error::Target)?;
+	if let Some(ref metrics_sync) = *metrics_sync {
+		metrics_sync.update_best_block_at_source(best_number_at_source);
+		metrics_sync.update_best_block_at_target(best_number_at_target);
+	}
+	*state.progress = print_sync_progress::<P>(*state.progress, best_number_at_source, best_number_at_target);
+
+	// if we have already submitted header, then we just need to wait for it
+	// if we're waiting too much, then we believe our transaction has been lost and restart sync
+	if let Some(last_transaction) = state.last_transaction {
+		if best_number_at_target >= last_transaction.submitted_header_number {
+			// transaction has been mined && we can continue
+		} else if last_transaction.time.elapsed() > sync_params.stall_timeout {
+			log::error!(
+				target: "bridge",
+				"Finality synchronization from {} to {} has stalled. Going to restart",
+				P::SOURCE_NAME,
+				P::TARGET_NAME,
+			);
+
+			return Err(Error::Stalled);
+		} else {
+			return Ok(Some(last_transaction));
+		}
+	}
+
+	// submit new header if we have something new
+	match select_header_to_submit(
+		source_client,
+		target_client,
+		state.finality_proofs_stream,
+		state.recent_finality_proofs,
+		best_number_at_source,
+		best_number_at_target,
+		sync_params,
+	)
+	.await?
+	{
+		Some((header, justification)) => {
+			let new_transaction = Transaction {
+				time: Instant::now(),
+				submitted_header_number: header.number(),
+			};
+
+			log::debug!(
+				target: "bridge",
+				"Going to submit finality proof of {} header #{:?} to {}",
+				P::SOURCE_NAME,
+				new_transaction.submitted_header_number,
+				P::TARGET_NAME,
+			);
+
+			target_client
+				.submit_finality_proof(header, justification)
+				.await
+				.map_err(Error::Target)?;
+			Ok(Some(new_transaction))
+		}
+		None => Ok(None),
+	}
+}
+
+async fn select_header_to_submit<P, SC, TC>(
+	source_client: &SC,
+	target_client: &TC,
+	finality_proofs_stream: &mut RestartableFinalityProofsStream<SC::FinalityProofsStream>,
+	recent_finality_proofs: &mut FinalityProofs<P>,
+	best_number_at_source: P::Number,
+	best_number_at_target: P::Number,
+	sync_params: &FinalitySyncParams,
+) -> Result<Option<(P::Header, P::FinalityProof)>, Error<P, SC::Error, TC::Error>>
+where
+	P: FinalitySyncPipeline,
+	SC: SourceClient<P>,
+	TC: TargetClient<P>,
+{
+	// to see that the loop is progressing
+	log::trace!(
+		target: "bridge",
+		"Considering range of headers ({:?}; {:?}]",
+		best_number_at_target,
+		best_number_at_source,
+	);
+
+	// read missing headers. if we see that the header schedules GRANDPA change, we need to
+	// submit this header
+	let selected_finality_proof = read_missing_headers::<P, SC, TC>(
+		source_client,
+		target_client,
+		best_number_at_source,
+		best_number_at_target,
+	)
+	.await?;
+	let (mut unjustified_headers, mut selected_finality_proof) = match selected_finality_proof {
+		SelectedFinalityProof::Mandatory(header, finality_proof) => return Ok(Some((header, finality_proof))),
+		SelectedFinalityProof::Regular(unjustified_headers, header, finality_proof) => {
+			(unjustified_headers, Some((header, finality_proof)))
+		}
+		SelectedFinalityProof::None(unjustified_headers) => (unjustified_headers, None),
+	};
+
+	// all headers that are missing from the target client are non-mandatory
+	// => even if we have already selected some header and its persistent finality proof,
+	// we may try to select better header by reading non-persistent proofs from the stream
+	read_finality_proofs_from_stream::<P, _>(finality_proofs_stream, recent_finality_proofs);
+	selected_finality_proof = select_better_recent_finality_proof::<P>(
+		recent_finality_proofs,
+		&mut unjustified_headers,
+		selected_finality_proof,
+	);
+
+	// remove obsolete 'recent' finality proofs + keep its size under certain limit
+	let oldest_finality_proof_to_keep = selected_finality_proof
+		.as_ref()
+		.map(|(header, _)| header.number())
+		.unwrap_or(best_number_at_target);
+	prune_recent_finality_proofs::<P>(
+		oldest_finality_proof_to_keep,
+		recent_finality_proofs,
+		sync_params.recent_finality_proofs_limit,
+	);
+
+	Ok(selected_finality_proof)
+}
+
+/// Finality proof that has been selected by the `read_missing_headers` function.
+pub(crate) enum SelectedFinalityProof<Header, FinalityProof> {
+	/// Mandatory header and its proof has been selected. We shall submit proof for this header.
+	Mandatory(Header, FinalityProof),
+	/// Regular header and its proof has been selected. We may submit this proof, or proof for
+	/// some better header.
+	Regular(UnjustifiedHeaders<Header>, Header, FinalityProof),
+	/// We haven't found any missing header with persistent proof at the target client.
+	None(UnjustifiedHeaders<Header>),
+}
+
+/// Read missing headers and their persistent finality proofs from the target client.
+///
+/// If we have found some header with known proof, it is returned.
+/// Otherwise, `SelectedFinalityProof::None` is returned.
+///
+/// Unless we have found mandatory header, all missing headers are collected and returned.
+pub(crate) async fn read_missing_headers<P: FinalitySyncPipeline, SC: SourceClient<P>, TC: TargetClient<P>>(
+	source_client: &SC,
+	_target_client: &TC,
+	best_number_at_source: P::Number,
+	best_number_at_target: P::Number,
+) -> Result<SelectedFinalityProof<P::Header, P::FinalityProof>, Error<P, SC::Error, TC::Error>> {
+	let mut unjustified_headers = Vec::new();
+	let mut selected_finality_proof = None;
+	let mut header_number = best_number_at_target + One::one();
+	while header_number <= best_number_at_source {
+		let (header, finality_proof) = source_client
+			.header_and_finality_proof(header_number)
+			.await
+			.map_err(Error::Source)?;
+		let is_mandatory = header.is_mandatory();
+
+		match (is_mandatory, finality_proof) {
+			(true, Some(finality_proof)) => {
+				log::trace!(target: "bridge", "Header {:?} is mandatory", header_number);
+				return Ok(SelectedFinalityProof::Mandatory(header, finality_proof));
+			}
+			(true, None) => return Err(Error::MissingMandatoryFinalityProof(header.number())),
+			(false, Some(finality_proof)) => {
+				log::trace!(target: "bridge", "Header {:?} has persistent finality proof", header_number);
+				unjustified_headers.clear();
+				selected_finality_proof = Some((header, finality_proof));
+			}
+			(false, None) => {
+				unjustified_headers.push(header);
+			}
+		}
+
+		header_number = header_number + One::one();
+	}
+
+	Ok(match selected_finality_proof {
+		Some((header, proof)) => SelectedFinalityProof::Regular(unjustified_headers, header, proof),
+		None => SelectedFinalityProof::None(unjustified_headers),
+	})
+}
+
+/// Read finality proofs from the stream.
+pub(crate) fn read_finality_proofs_from_stream<P: FinalitySyncPipeline, FPS: Stream<Item = P::FinalityProof>>(
+	finality_proofs_stream: &mut RestartableFinalityProofsStream<FPS>,
+	recent_finality_proofs: &mut FinalityProofs<P>,
+) {
+	loop {
+		let next_proof = finality_proofs_stream.stream.next();
+		let finality_proof = match next_proof.now_or_never() {
+			Some(Some(finality_proof)) => finality_proof,
+			Some(None) => {
+				finality_proofs_stream.needs_restart = true;
+				break;
+			}
+			None => break,
+		};
+
+		recent_finality_proofs.push((finality_proof.target_header_number(), finality_proof));
+	}
+}
+
+/// Try to select better header and its proof, given finality proofs that we
+/// have recently read from the stream.
+pub(crate) fn select_better_recent_finality_proof<P: FinalitySyncPipeline>(
+	recent_finality_proofs: FinalityProofsRef<P>,
+	unjustified_headers: &mut UnjustifiedHeaders<P::Header>,
+	selected_finality_proof: Option<(P::Header, P::FinalityProof)>,
+) -> Option<(P::Header, P::FinalityProof)> {
+	if unjustified_headers.is_empty() || recent_finality_proofs.is_empty() {
+		return selected_finality_proof;
+	}
+
+	const NOT_EMPTY_PROOF: &str = "we have checked that the vec is not empty; qed";
+
+	// we need proofs for headers in range unjustified_range_begin..=unjustified_range_end
+	let unjustified_range_begin = unjustified_headers.first().expect(NOT_EMPTY_PROOF).number();
+	let unjustified_range_end = unjustified_headers.last().expect(NOT_EMPTY_PROOF).number();
+
+	// we have proofs for headers in range buffered_range_begin..=buffered_range_end
+	let buffered_range_begin = recent_finality_proofs.first().expect(NOT_EMPTY_PROOF).0;
+	let buffered_range_end = recent_finality_proofs.last().expect(NOT_EMPTY_PROOF).0;
+
+	// we have two ranges => find intersection
+	let intersection_begin = std::cmp::max(unjustified_range_begin, buffered_range_begin);
+	let intersection_end = std::cmp::min(unjustified_range_end, buffered_range_end);
+	let intersection = intersection_begin..=intersection_end;
+
+	// find last proof from intersection
+	let selected_finality_proof_index = recent_finality_proofs
+		.binary_search_by_key(intersection.end(), |(number, _)| *number)
+		.unwrap_or_else(|index| index.saturating_sub(1));
+	let (selected_header_number, finality_proof) = &recent_finality_proofs[selected_finality_proof_index];
+	if !intersection.contains(selected_header_number) {
+		return selected_finality_proof;
+	}
+
+	// now remove all obsolete headers and extract selected header
+	let selected_header_position = unjustified_headers
+		.binary_search_by_key(selected_header_number, |header| header.number())
+		.expect("unjustified_headers contain all headers from intersection; qed");
+	let selected_header = unjustified_headers.swap_remove(selected_header_position);
+	Some((selected_header, finality_proof.clone()))
+}
+
+pub(crate) fn prune_recent_finality_proofs<P: FinalitySyncPipeline>(
+	justified_header_number: P::Number,
+	recent_finality_proofs: &mut FinalityProofs<P>,
+	recent_finality_proofs_limit: usize,
+) {
+	let position =
+		recent_finality_proofs.binary_search_by_key(&justified_header_number, |(header_number, _)| *header_number);
+
+	// remove all obsolete elements
+	*recent_finality_proofs = recent_finality_proofs.split_off(
+		position
+			.map(|position| position + 1)
+			.unwrap_or_else(|position| position),
+	);
+
+	// now - limit vec by size
+	let split_index = recent_finality_proofs
+		.len()
+		.saturating_sub(recent_finality_proofs_limit);
+	*recent_finality_proofs = recent_finality_proofs.split_off(split_index);
+}
+
+fn print_sync_progress<P: FinalitySyncPipeline>(
+	progress_context: (Instant, Option<P::Number>),
+	best_number_at_source: P::Number,
+	best_number_at_target: P::Number,
+) -> (Instant, Option<P::Number>) {
+	let (prev_time, prev_best_number_at_target) = progress_context;
+	let now = Instant::now();
+
+	let need_update = now - prev_time > Duration::from_secs(10)
+		|| prev_best_number_at_target
+			.map(|prev_best_number_at_target| {
+				best_number_at_target.saturating_sub(prev_best_number_at_target) > 10.into()
+			})
+			.unwrap_or(true);
+
+	if !need_update {
+		return (prev_time, prev_best_number_at_target);
+	}
+
+	log::info!(
+		target: "bridge",
+		"Synced {:?} of {:?} headers",
+		best_number_at_target,
+		best_number_at_source,
+	);
+	(now, Some(best_number_at_target))
+}

polkadot/bridges/relays/finality/src/finality_loop_tests.rs

@@ -0,0 +1,404 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Tests for finality synchronization loop.
+
+#![cfg(test)]
+
+use crate::finality_loop::{
+	prune_recent_finality_proofs, read_finality_proofs_from_stream, run, select_better_recent_finality_proof,
+	FinalityProofs, FinalitySyncParams, SourceClient, TargetClient,
+};
+use crate::{FinalityProof, FinalitySyncPipeline, SourceHeader};
+
+use async_trait::async_trait;
+use futures::{FutureExt, Stream, StreamExt};
+use parking_lot::Mutex;
+use relay_utils::{metrics::MetricsParams, relay_loop::Client as RelayClient, MaybeConnectionError};
+use std::{collections::HashMap, pin::Pin, sync::Arc, time::Duration};
+
+type IsMandatory = bool;
+type TestNumber = u64;
+
+#[derive(Debug, Clone)]
+enum TestError {
+	NonConnection,
+}
+
+impl MaybeConnectionError for TestError {
+	fn is_connection_error(&self) -> bool {
+		false
+	}
+}
+
+#[derive(Debug, Clone)]
+struct TestFinalitySyncPipeline;
+
+impl FinalitySyncPipeline for TestFinalitySyncPipeline {
+	const SOURCE_NAME: &'static str = "TestSource";
+	const TARGET_NAME: &'static str = "TestTarget";
+
+	type Hash = u64;
+	type Number = TestNumber;
+	type Header = TestSourceHeader;
+	type FinalityProof = TestFinalityProof;
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct TestSourceHeader(IsMandatory, TestNumber);
+
+impl SourceHeader<TestNumber> for TestSourceHeader {
+	fn number(&self) -> TestNumber {
+		self.1
+	}
+
+	fn is_mandatory(&self) -> bool {
+		self.0
+	}
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct TestFinalityProof(TestNumber);
+
+impl FinalityProof<TestNumber> for TestFinalityProof {
+	fn target_header_number(&self) -> TestNumber {
+		self.0
+	}
+}
+
+#[derive(Debug, Clone, Default)]
+struct ClientsData {
+	source_best_block_number: TestNumber,
+	source_headers: HashMap<TestNumber, (TestSourceHeader, Option<TestFinalityProof>)>,
+	source_proofs: Vec<TestFinalityProof>,
+
+	target_best_block_number: TestNumber,
+	target_headers: Vec<(TestSourceHeader, TestFinalityProof)>,
+}
+
+#[derive(Clone)]
+struct TestSourceClient {
+	on_method_call: Arc<dyn Fn(&mut ClientsData) + Send + Sync>,
+	data: Arc<Mutex<ClientsData>>,
+}
+
+#[async_trait]
+impl RelayClient for TestSourceClient {
+	type Error = TestError;
+
+	async fn reconnect(&mut self) -> Result<(), TestError> {
+		unreachable!()
+	}
+}
+
+#[async_trait]
+impl SourceClient<TestFinalitySyncPipeline> for TestSourceClient {
+	type FinalityProofsStream = Pin<Box<dyn Stream<Item = TestFinalityProof>>>;
+
+	async fn best_finalized_block_number(&self) -> Result<TestNumber, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(&mut *data);
+		Ok(data.source_best_block_number)
+	}
+
+	async fn header_and_finality_proof(
+		&self,
+		number: TestNumber,
+	) -> Result<(TestSourceHeader, Option<TestFinalityProof>), TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(&mut *data);
+		data.source_headers
+			.get(&number)
+			.cloned()
+			.ok_or(TestError::NonConnection)
+	}
+
+	async fn finality_proofs(&self) -> Result<Self::FinalityProofsStream, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(&mut *data);
+		Ok(futures::stream::iter(data.source_proofs.clone()).boxed())
+	}
+}
+
+#[derive(Clone)]
+struct TestTargetClient {
+	on_method_call: Arc<dyn Fn(&mut ClientsData) + Send + Sync>,
+	data: Arc<Mutex<ClientsData>>,
+}
+
+#[async_trait]
+impl RelayClient for TestTargetClient {
+	type Error = TestError;
+
+	async fn reconnect(&mut self) -> Result<(), TestError> {
+		unreachable!()
+	}
+}
+
+#[async_trait]
+impl TargetClient<TestFinalitySyncPipeline> for TestTargetClient {
+	async fn best_finalized_source_block_number(&self) -> Result<TestNumber, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(&mut *data);
+		Ok(data.target_best_block_number)
+	}
+
+	async fn submit_finality_proof(&self, header: TestSourceHeader, proof: TestFinalityProof) -> Result<(), TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(&mut *data);
+		data.target_best_block_number = header.number();
+		data.target_headers.push((header, proof));
+		Ok(())
+	}
+}
+
+fn run_sync_loop(state_function: impl Fn(&mut ClientsData) -> bool + Send + Sync + 'static) -> ClientsData {
+	let (exit_sender, exit_receiver) = futures::channel::mpsc::unbounded();
+	let internal_state_function: Arc<dyn Fn(&mut ClientsData) + Send + Sync> = Arc::new(move |data| {
+		if state_function(data) {
+			exit_sender.unbounded_send(()).unwrap();
+		}
+	});
+	let clients_data = Arc::new(Mutex::new(ClientsData {
+		source_best_block_number: 10,
+		source_headers: vec![
+			(6, (TestSourceHeader(false, 6), None)),
+			(7, (TestSourceHeader(false, 7), Some(TestFinalityProof(7)))),
+			(8, (TestSourceHeader(true, 8), Some(TestFinalityProof(8)))),
+			(9, (TestSourceHeader(false, 9), Some(TestFinalityProof(9)))),
+			(10, (TestSourceHeader(false, 10), None)),
+		]
+		.into_iter()
+		.collect(),
+		source_proofs: vec![TestFinalityProof(12), TestFinalityProof(14)],
+
+		target_best_block_number: 5,
+		target_headers: vec![],
+	}));
+	let source_client = TestSourceClient {
+		on_method_call: internal_state_function.clone(),
+		data: clients_data.clone(),
+	};
+	let target_client = TestTargetClient {
+		on_method_call: internal_state_function,
+		data: clients_data.clone(),
+	};
+	let sync_params = FinalitySyncParams {
+		tick: Duration::from_secs(0),
+		recent_finality_proofs_limit: 1024,
+		stall_timeout: Duration::from_secs(1),
+	};
+
+	let _ = async_std::task::block_on(run(
+		source_client,
+		target_client,
+		sync_params,
+		MetricsParams::disabled(),
+		exit_receiver.into_future().map(|(_, _)| ()),
+	));
+
+	let clients_data = clients_data.lock().clone();
+	clients_data
+}
+
+#[test]
+fn finality_sync_loop_works() {
+	let client_data = run_sync_loop(|data| {
+		// header#7 has persistent finality proof, but it isn't mandatory => it isn't submitted, because
+		// header#8 has persistent finality proof && it is mandatory => it is submitted
+		// header#9 has persistent finality proof, but it isn't mandatory => it is submitted, because
+		//   there are no more persistent finality proofs
+		//
+		// once this ^^^ is done, we generate more blocks && read proof for blocks 12 and 14 from the stream
+		if data.target_best_block_number == 9 {
+			data.source_best_block_number = 14;
+			data.source_headers.insert(11, (TestSourceHeader(false, 11), None));
+			data.source_headers
+				.insert(12, (TestSourceHeader(false, 12), Some(TestFinalityProof(12))));
+			data.source_headers.insert(13, (TestSourceHeader(false, 13), None));
+			data.source_headers
+				.insert(14, (TestSourceHeader(false, 14), Some(TestFinalityProof(14))));
+		}
+		// once this ^^^ is done, we generate more blocks && read persistent proof for block 16
+		if data.target_best_block_number == 14 {
+			data.source_best_block_number = 17;
+			data.source_headers.insert(15, (TestSourceHeader(false, 15), None));
+			data.source_headers
+				.insert(16, (TestSourceHeader(false, 16), Some(TestFinalityProof(16))));
+			data.source_headers.insert(17, (TestSourceHeader(false, 17), None));
+		}
+
+		data.target_best_block_number == 16
+	});
+
+	assert_eq!(
+		client_data.target_headers,
+		vec![
+			// before adding 11..14: finality proof for mandatory header#8
+			(TestSourceHeader(true, 8), TestFinalityProof(8)),
+			// before adding 11..14: persistent finality proof for non-mandatory header#9
+			(TestSourceHeader(false, 9), TestFinalityProof(9)),
+			// after adding 11..14: ephemeral finality proof for non-mandatory header#14
+			(TestSourceHeader(false, 14), TestFinalityProof(14)),
+			// after adding 15..17: persistent finality proof for non-mandatory header#16
+			(TestSourceHeader(false, 16), TestFinalityProof(16)),
+		],
+	);
+}
+
+#[test]
+fn select_better_recent_finality_proof_works() {
+	// if there are no unjustified headers, nothing is changed
+	assert_eq!(
+		select_better_recent_finality_proof::<TestFinalitySyncPipeline>(
+			&[(5, TestFinalityProof(5))],
+			&mut vec![],
+			Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+		),
+		Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+	);
+
+	// if there are no recent finality proofs, nothing is changed
+	assert_eq!(
+		select_better_recent_finality_proof::<TestFinalitySyncPipeline>(
+			&[],
+			&mut vec![TestSourceHeader(false, 5)],
+			Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+		),
+		Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+	);
+
+	// if there's no intersection between recent finality proofs and unjustified headers, nothing is changed
+	let mut unjustified_headers = vec![TestSourceHeader(false, 9), TestSourceHeader(false, 10)];
+	assert_eq!(
+		select_better_recent_finality_proof::<TestFinalitySyncPipeline>(
+			&[(1, TestFinalityProof(1)), (4, TestFinalityProof(4))],
+			&mut unjustified_headers,
+			Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+		),
+		Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+	);
+
+	// if there's intersection between recent finality proofs and unjustified headers, but there are no
+	// proofs in this intersection, nothing is changed
+	let mut unjustified_headers = vec![
+		TestSourceHeader(false, 8),
+		TestSourceHeader(false, 9),
+		TestSourceHeader(false, 10),
+	];
+	assert_eq!(
+		select_better_recent_finality_proof::<TestFinalitySyncPipeline>(
+			&[(7, TestFinalityProof(7)), (11, TestFinalityProof(11))],
+			&mut unjustified_headers,
+			Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+		),
+		Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+	);
+	assert_eq!(
+		unjustified_headers,
+		vec![
+			TestSourceHeader(false, 8),
+			TestSourceHeader(false, 9),
+			TestSourceHeader(false, 10)
+		]
+	);
+
+	// if there's intersection between recent finality proofs and unjustified headers and there's
+	// a proof in this intersection:
+	// - this better (last from intersection) proof is selected;
+	// - 'obsolete' unjustified headers are pruned.
+	let mut unjustified_headers = vec![
+		TestSourceHeader(false, 8),
+		TestSourceHeader(false, 9),
+		TestSourceHeader(false, 10),
+	];
+	assert_eq!(
+		select_better_recent_finality_proof::<TestFinalitySyncPipeline>(
+			&[(7, TestFinalityProof(7)), (9, TestFinalityProof(9))],
+			&mut unjustified_headers,
+			Some((TestSourceHeader(false, 2), TestFinalityProof(2))),
+		),
+		Some((TestSourceHeader(false, 9), TestFinalityProof(9))),
+	);
+}
+
+#[test]
+fn read_finality_proofs_from_stream_works() {
+	// when stream is currently empty, nothing is changed
+	let mut recent_finality_proofs = vec![(1, TestFinalityProof(1))];
+	let mut stream = futures::stream::pending().into();
+	read_finality_proofs_from_stream::<TestFinalitySyncPipeline, _>(&mut stream, &mut recent_finality_proofs);
+	assert_eq!(recent_finality_proofs, vec![(1, TestFinalityProof(1))]);
+	assert_eq!(stream.needs_restart, false);
+
+	// when stream has entry with target, it is added to the recent proofs container
+	let mut stream = futures::stream::iter(vec![TestFinalityProof(4)])
+		.chain(futures::stream::pending())
+		.into();
+	read_finality_proofs_from_stream::<TestFinalitySyncPipeline, _>(&mut stream, &mut recent_finality_proofs);
+	assert_eq!(
+		recent_finality_proofs,
+		vec![(1, TestFinalityProof(1)), (4, TestFinalityProof(4))]
+	);
+	assert_eq!(stream.needs_restart, false);
+
+	// when stream has ended, we'll need to restart it
+	let mut stream = futures::stream::empty().into();
+	read_finality_proofs_from_stream::<TestFinalitySyncPipeline, _>(&mut stream, &mut recent_finality_proofs);
+	assert_eq!(
+		recent_finality_proofs,
+		vec![(1, TestFinalityProof(1)), (4, TestFinalityProof(4))]
+	);
+	assert_eq!(stream.needs_restart, true);
+}
+
+#[test]
+fn prune_recent_finality_proofs_works() {
+	let original_recent_finality_proofs: FinalityProofs<TestFinalitySyncPipeline> = vec![
+		(10, TestFinalityProof(10)),
+		(13, TestFinalityProof(13)),
+		(15, TestFinalityProof(15)),
+		(17, TestFinalityProof(17)),
+		(19, TestFinalityProof(19)),
+	]
+	.into_iter()
+	.collect();
+
+	// when there's proof for justified header in the vec
+	let mut recent_finality_proofs = original_recent_finality_proofs.clone();
+	prune_recent_finality_proofs::<TestFinalitySyncPipeline>(10, &mut recent_finality_proofs, 1024);
+	assert_eq!(&original_recent_finality_proofs[1..], recent_finality_proofs,);
+
+	// when there are no proof for justified header in the vec
+	let mut recent_finality_proofs = original_recent_finality_proofs.clone();
+	prune_recent_finality_proofs::<TestFinalitySyncPipeline>(11, &mut recent_finality_proofs, 1024);
+	assert_eq!(&original_recent_finality_proofs[1..], recent_finality_proofs,);
+
+	// when there are too many entries after initial prune && they also need to be pruned
+	let mut recent_finality_proofs = original_recent_finality_proofs.clone();
+	prune_recent_finality_proofs::<TestFinalitySyncPipeline>(10, &mut recent_finality_proofs, 2);
+	assert_eq!(&original_recent_finality_proofs[3..], recent_finality_proofs,);
+
+	// when last entry is pruned
+	let mut recent_finality_proofs = original_recent_finality_proofs.clone();
+	prune_recent_finality_proofs::<TestFinalitySyncPipeline>(19, &mut recent_finality_proofs, 2);
+	assert_eq!(&original_recent_finality_proofs[5..], recent_finality_proofs,);
+
+	// when post-last entry is pruned
+	let mut recent_finality_proofs = original_recent_finality_proofs.clone();
+	prune_recent_finality_proofs::<TestFinalitySyncPipeline>(20, &mut recent_finality_proofs, 2);
+	assert_eq!(&original_recent_finality_proofs[5..], recent_finality_proofs,);
+}

polkadot/bridges/relays/finality/src/lib.rs

@@ -0,0 +1,53 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! This crate has single entrypoint to run synchronization loop that is built around finality
+//! proofs, as opposed to headers synchronization loop, which is built around headers. The headers
+//! are still submitted to the target node, but are treated as auxiliary data as we are not trying
+//! to submit all source headers to the target node.
+
+pub use crate::finality_loop::{metrics_prefix, run, FinalitySyncParams, SourceClient, TargetClient};
+
+use bp_header_chain::FinalityProof;
+use std::fmt::Debug;
+
+mod finality_loop;
+mod finality_loop_tests;
+
+/// Finality proofs synchronization pipeline.
+pub trait FinalitySyncPipeline: Clone + Debug + Send + Sync {
+	/// Name of the finality proofs source.
+	const SOURCE_NAME: &'static str;
+	/// Name of the finality proofs target.
+	const TARGET_NAME: &'static str;
+
+	/// Headers we're syncing are identified by this hash.
+	type Hash: Eq + Clone + Copy + Send + Sync + Debug;
+	/// Headers we're syncing are identified by this number.
+	type Number: relay_utils::BlockNumberBase;
+	/// Type of header that we're syncing.
+	type Header: SourceHeader<Self::Number>;
+	/// Finality proof type.
+	type FinalityProof: FinalityProof<Self::Number>;
+}
+
+/// Header that we're receiving from source node.
+pub trait SourceHeader<Number>: Clone + Debug + PartialEq + Send + Sync {
+	/// Returns number of header.
+	fn number(&self) -> Number;
+	/// Returns true if this header needs to be submitted to target node.
+	fn is_mandatory(&self) -> bool;
+}

polkadot/bridges/relays/headers/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "headers-relay"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+async-std = "1.6.5"
+async-trait = "0.1.40"
+backoff = "0.2"
+futures = "0.3.5"
+linked-hash-map = "0.5.3"
+log = "0.4.11"
+num-traits = "0.2"
+parking_lot = "0.11.0"
+relay-utils = { path = "../utils" }

polkadot/bridges/relays/headers/src/lib.rs

@@ -0,0 +1,33 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Relaying source chain headers to target chain. This module provides entrypoint
+//! that starts reading new headers from source chain and submit these headers as
+//! module/contract transactions to the target chain. Pallet/contract on the target
+//! chain is a light-client of the source chain. All other trustless bridge
+//! applications are built using this light-client, so running headers-relay is
+//! essential for running all other bridge applications.
+
+// required for futures::select!
+#![recursion_limit = "1024"]
+#![warn(missing_docs)]
+
+pub mod headers;
+pub mod sync;
+pub mod sync_loop;
+pub mod sync_loop_metrics;
+pub mod sync_loop_tests;
+pub mod sync_types;

polkadot/bridges/relays/headers/src/sync.rs

@@ -0,0 +1,523 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Headers synchronization context. This structure wraps headers queue and is
+//! able to choose: which headers to read from the source chain? Which headers
+//! to submit to the target chain? The context makes decisions basing on parameters
+//! passed using `HeadersSyncParams` structure.
+
+use crate::headers::QueuedHeaders;
+use crate::sync_types::{HeaderIdOf, HeaderStatus, HeadersSyncPipeline, QueuedHeader};
+use num_traits::{One, Saturating, Zero};
+
+/// Common sync params.
+#[derive(Debug, Clone)]
+pub struct HeadersSyncParams {
+	/// Maximal number of ethereum headers to pre-download.
+	pub max_future_headers_to_download: usize,
+	/// Maximal number of active (we believe) submit header transactions.
+	pub max_headers_in_submitted_status: usize,
+	/// Maximal number of headers in single submit request.
+	pub max_headers_in_single_submit: usize,
+	/// Maximal total headers size in single submit request.
+	pub max_headers_size_in_single_submit: usize,
+	/// We only may store and accept (from Ethereum node) headers that have
+	/// number >= than best_substrate_header.number - prune_depth.
+	pub prune_depth: u32,
+	/// Target transactions mode.
+	pub target_tx_mode: TargetTransactionMode,
+}
+
+/// Target transaction mode.
+#[derive(Debug, PartialEq, Clone)]
+pub enum TargetTransactionMode {
+	/// Submit new headers using signed transactions.
+	Signed,
+	/// Submit new headers using unsigned transactions.
+	Unsigned,
+	/// Submit new headers using signed transactions, but only when we
+	/// believe that sync has stalled.
+	Backup,
+}
+
+/// Headers synchronization context.
+#[derive(Debug)]
+pub struct HeadersSync<P: HeadersSyncPipeline> {
+	/// Synchronization parameters.
+	params: HeadersSyncParams,
+	/// Best header number known to source node.
+	source_best_number: Option<P::Number>,
+	/// Best header known to target node.
+	target_best_header: Option<HeaderIdOf<P>>,
+	/// Headers queue.
+	headers: QueuedHeaders<P>,
+	/// Pause headers submission.
+	pause_submit: bool,
+}
+
+impl<P: HeadersSyncPipeline> HeadersSync<P> {
+	/// Creates new headers synchronizer.
+	pub fn new(params: HeadersSyncParams) -> Self {
+		HeadersSync {
+			headers: QueuedHeaders::default(),
+			params,
+			source_best_number: None,
+			target_best_header: None,
+			pause_submit: false,
+		}
+	}
+
+	/// Return best header number known to source node.
+	pub fn source_best_number(&self) -> Option<P::Number> {
+		self.source_best_number
+	}
+
+	/// Best header known to target node.
+	pub fn target_best_header(&self) -> Option<HeaderIdOf<P>> {
+		self.target_best_header
+	}
+
+	/// Returns true if we have synced almost all known headers.
+	pub fn is_almost_synced(&self) -> bool {
+		match self.source_best_number {
+			Some(source_best_number) => self
+				.target_best_header
+				.map(|best| source_best_number.saturating_sub(best.0) < 4.into())
+				.unwrap_or(false),
+			None => true,
+		}
+	}
+
+	/// Returns synchronization status.
+	pub fn status(&self) -> (&Option<HeaderIdOf<P>>, &Option<P::Number>) {
+		(&self.target_best_header, &self.source_best_number)
+	}
+
+	/// Returns reference to the headers queue.
+	pub fn headers(&self) -> &QueuedHeaders<P> {
+		&self.headers
+	}
+
+	/// Returns mutable reference to the headers queue.
+	pub fn headers_mut(&mut self) -> &mut QueuedHeaders<P> {
+		&mut self.headers
+	}
+
+	/// Select header that needs to be downloaded from the source node.
+	pub fn select_new_header_to_download(&self) -> Option<P::Number> {
+		// if we haven't received best header from source node yet, there's nothing we can download
+		let source_best_number = self.source_best_number?;
+
+		// if we haven't received known best header from target node yet, there's nothing we can download
+		let target_best_header = self.target_best_header.as_ref()?;
+
+		// if there's too many headers in the queue, stop downloading
+		let in_memory_headers = self.headers.total_headers();
+		if in_memory_headers >= self.params.max_future_headers_to_download {
+			return None;
+		}
+
+		// if queue is empty and best header on target is > than best header on source,
+		// then we shoud reorg
+		let best_queued_number = self.headers.best_queued_number();
+		if best_queued_number.is_zero() && source_best_number < target_best_header.0 {
+			return Some(source_best_number);
+		}
+
+		// we assume that there were no reorgs if we have already downloaded best header
+		let best_downloaded_number = std::cmp::max(
+			std::cmp::max(best_queued_number, self.headers.best_synced_number()),
+			target_best_header.0,
+		);
+		if best_downloaded_number >= source_best_number {
+			return None;
+		}
+
+		// download new header
+		Some(best_downloaded_number + One::one())
+	}
+
+	/// Selech orphan header to downoload.
+	pub fn select_orphan_header_to_download(&self) -> Option<&QueuedHeader<P>> {
+		let orphan_header = self.headers.header(HeaderStatus::Orphan)?;
+
+		// we consider header orphan until we'll find it ancestor that is known to the target node
+		// => we may get orphan header while we ask target node whether it knows its parent
+		// => let's avoid fetching duplicate headers
+		let parent_id = orphan_header.parent_id();
+		if self.headers.status(&parent_id) != HeaderStatus::Unknown {
+			return None;
+		}
+
+		Some(orphan_header)
+	}
+
+	/// Select headers that need to be submitted to the target node.
+	pub fn select_headers_to_submit(&self, stalled: bool) -> Option<Vec<&QueuedHeader<P>>> {
+		// maybe we have paused new headers submit?
+		if self.pause_submit {
+			return None;
+		}
+
+		// if we operate in backup mode, we only submit headers when sync has stalled
+		if self.params.target_tx_mode == TargetTransactionMode::Backup && !stalled {
+			return None;
+		}
+
+		let headers_in_submit_status = self.headers.headers_in_status(HeaderStatus::Submitted);
+		let headers_to_submit_count = self
+			.params
+			.max_headers_in_submitted_status
+			.checked_sub(headers_in_submit_status)?;
+
+		let mut total_size = 0;
+		let mut total_headers = 0;
+		self.headers.headers(HeaderStatus::Ready, |header| {
+			if total_headers == headers_to_submit_count {
+				return false;
+			}
+			if total_headers == self.params.max_headers_in_single_submit {
+				return false;
+			}
+
+			let encoded_size = P::estimate_size(header);
+			if total_headers != 0 && total_size + encoded_size > self.params.max_headers_size_in_single_submit {
+				return false;
+			}
+
+			total_size += encoded_size;
+			total_headers += 1;
+
+			true
+		})
+	}
+
+	/// Receive new target header number from the source node.
+	pub fn source_best_header_number_response(&mut self, best_header_number: P::Number) {
+		log::debug!(
+			target: "bridge",
+			"Received best header number from {} node: {}",
+			P::SOURCE_NAME,
+			best_header_number,
+		);
+		self.source_best_number = Some(best_header_number);
+	}
+
+	/// Receive new best header from the target node.
+	/// Returns true if it is different from the previous block known to us.
+	pub fn target_best_header_response(&mut self, best_header: HeaderIdOf<P>) -> bool {
+		log::debug!(
+			target: "bridge",
+			"Received best known header from {}: {:?}",
+			P::TARGET_NAME,
+			best_header,
+		);
+
+		// early return if it is still the same
+		if self.target_best_header == Some(best_header) {
+			return false;
+		}
+
+		// remember that this header is now known to the Substrate runtime
+		self.headers.target_best_header_response(&best_header);
+
+		// prune ancient headers
+		self.headers
+			.prune(best_header.0.saturating_sub(self.params.prune_depth.into()));
+
+		// finally remember the best header itself
+		self.target_best_header = Some(best_header);
+
+		// we are ready to submit headers again
+		if self.pause_submit {
+			log::debug!(
+				target: "bridge",
+				"Ready to submit {} headers to {} node again!",
+				P::SOURCE_NAME,
+				P::TARGET_NAME,
+			);
+
+			self.pause_submit = false;
+		}
+
+		true
+	}
+
+	/// Pause headers submit until best header will be updated on target node.
+	pub fn pause_submit(&mut self) {
+		log::debug!(
+			target: "bridge",
+			"Stopping submitting {} headers to {} node. Waiting for {} submitted headers to be accepted",
+			P::SOURCE_NAME,
+			P::TARGET_NAME,
+			self.headers.headers_in_status(HeaderStatus::Submitted),
+		);
+
+		self.pause_submit = true;
+	}
+
+	/// Restart synchronization.
+	pub fn restart(&mut self) {
+		self.source_best_number = None;
+		self.target_best_header = None;
+		self.headers.clear();
+		self.pause_submit = false;
+	}
+}
+
+#[cfg(test)]
+pub mod tests {
+	use super::*;
+	use crate::headers::tests::{header, id};
+	use crate::sync_loop_tests::{TestHash, TestHeadersSyncPipeline, TestNumber};
+	use crate::sync_types::HeaderStatus;
+	use relay_utils::HeaderId;
+
+	fn side_hash(number: TestNumber) -> TestHash {
+		1000 + number
+	}
+
+	pub fn default_sync_params() -> HeadersSyncParams {
+		HeadersSyncParams {
+			max_future_headers_to_download: 128,
+			max_headers_in_submitted_status: 128,
+			max_headers_in_single_submit: 32,
+			max_headers_size_in_single_submit: 131_072,
+			prune_depth: 4096,
+			target_tx_mode: TargetTransactionMode::Signed,
+		}
+	}
+
+	#[test]
+	fn select_new_header_to_download_works() {
+		let mut eth_sync = HeadersSync::<TestHeadersSyncPipeline>::new(default_sync_params());
+
+		// both best && target headers are unknown
+		assert_eq!(eth_sync.select_new_header_to_download(), None);
+
+		// best header is known, target header is unknown
+		eth_sync.target_best_header = Some(HeaderId(0, Default::default()));
+		assert_eq!(eth_sync.select_new_header_to_download(), None);
+
+		// target header is known, best header is unknown
+		eth_sync.target_best_header = None;
+		eth_sync.source_best_number = Some(100);
+		assert_eq!(eth_sync.select_new_header_to_download(), None);
+
+		// when our best block has the same number as the target
+		eth_sync.target_best_header = Some(HeaderId(100, Default::default()));
+		assert_eq!(eth_sync.select_new_header_to_download(), None);
+
+		// when we actually need a new header
+		eth_sync.source_best_number = Some(101);
+		assert_eq!(eth_sync.select_new_header_to_download(), Some(101));
+
+		// when we have to reorganize to longer fork
+		eth_sync.source_best_number = Some(100);
+		eth_sync.target_best_header = Some(HeaderId(200, Default::default()));
+		assert_eq!(eth_sync.select_new_header_to_download(), Some(100));
+
+		// when there are too many headers scheduled for submitting
+		for i in 1..1000 {
+			eth_sync.headers.header_response(header(i).header().clone());
+		}
+		assert_eq!(eth_sync.select_new_header_to_download(), None);
+	}
+
+	#[test]
+	fn select_new_header_to_download_works_with_empty_queue() {
+		let mut eth_sync = HeadersSync::<TestHeadersSyncPipeline>::new(default_sync_params());
+		eth_sync.source_best_header_number_response(100);
+
+		// when queue is not empty => everything goes as usually
+		eth_sync.target_best_header_response(header(10).id());
+		eth_sync.headers_mut().header_response(header(11).header().clone());
+		eth_sync.headers_mut().maybe_extra_response(&header(11).id(), false);
+		assert_eq!(eth_sync.select_new_header_to_download(), Some(12));
+
+		// but then queue is drained
+		eth_sync.headers_mut().target_best_header_response(&header(11).id());
+
+		// even though it's empty, we know that header#11 is synced
+		assert_eq!(eth_sync.headers().best_queued_number(), 0);
+		assert_eq!(eth_sync.headers().best_synced_number(), 11);
+		assert_eq!(eth_sync.select_new_header_to_download(), Some(12));
+	}
+
+	#[test]
+	fn sync_without_reorgs_works() {
+		let mut eth_sync = HeadersSync::new(default_sync_params());
+		eth_sync.params.max_headers_in_submitted_status = 1;
+
+		// ethereum reports best header #102
+		eth_sync.source_best_header_number_response(102);
+
+		// substrate reports that it is at block #100
+		eth_sync.target_best_header_response(id(100));
+
+		// block #101 is downloaded first
+		assert_eq!(eth_sync.select_new_header_to_download(), Some(101));
+		eth_sync.headers.header_response(header(101).header().clone());
+
+		// now header #101 is ready to be submitted
+		assert_eq!(eth_sync.headers.header(HeaderStatus::MaybeExtra), Some(&header(101)));
+		eth_sync.headers.maybe_extra_response(&id(101), false);
+		assert_eq!(eth_sync.headers.header(HeaderStatus::Ready), Some(&header(101)));
+		assert_eq!(eth_sync.select_headers_to_submit(false), Some(vec![&header(101)]));
+
+		// and header #102 is ready to be downloaded
+		assert_eq!(eth_sync.select_new_header_to_download(), Some(102));
+		eth_sync.headers.header_response(header(102).header().clone());
+
+		// receive submission confirmation
+		eth_sync.headers.headers_submitted(vec![id(101)]);
+
+		// we have nothing to submit because previous header hasn't been confirmed yet
+		// (and we allow max 1 submit transaction in the wild)
+		assert_eq!(eth_sync.headers.header(HeaderStatus::MaybeExtra), Some(&header(102)));
+		eth_sync.headers.maybe_extra_response(&id(102), false);
+		assert_eq!(eth_sync.headers.header(HeaderStatus::Ready), Some(&header(102)));
+		assert_eq!(eth_sync.select_headers_to_submit(false), None);
+
+		// substrate reports that it has imported block #101
+		eth_sync.target_best_header_response(id(101));
+
+		// and we are ready to submit #102
+		assert_eq!(eth_sync.select_headers_to_submit(false), Some(vec![&header(102)]));
+		eth_sync.headers.headers_submitted(vec![id(102)]);
+
+		// substrate reports that it has imported block #102
+		eth_sync.target_best_header_response(id(102));
+
+		// and we have nothing to download
+		assert_eq!(eth_sync.select_new_header_to_download(), None);
+	}
+
+	#[test]
+	fn sync_with_orphan_headers_work() {
+		let mut eth_sync = HeadersSync::new(default_sync_params());
+
+		// ethereum reports best header #102
+		eth_sync.source_best_header_number_response(102);
+
+		// substrate reports that it is at block #100, but it isn't part of best chain
+		eth_sync.target_best_header_response(HeaderId(100, side_hash(100)));
+
+		// block #101 is downloaded first
+		assert_eq!(eth_sync.select_new_header_to_download(), Some(101));
+		eth_sync.headers.header_response(header(101).header().clone());
+
+		// we can't submit header #101, because its parent status is unknown
+		assert_eq!(eth_sync.select_headers_to_submit(false), None);
+
+		// instead we are trying to determine status of its parent (#100)
+		assert_eq!(eth_sync.headers.header(HeaderStatus::MaybeOrphan), Some(&header(101)));
+
+		// and the status is still unknown
+		eth_sync.headers.maybe_orphan_response(&id(100), false);
+
+		// so we consider #101 orphaned now && will download its parent - #100
+		assert_eq!(eth_sync.headers.header(HeaderStatus::Orphan), Some(&header(101)));
+		eth_sync.headers.header_response(header(100).header().clone());
+
+		// #101 is now Orphan and #100 is MaybeOrphan => we do not want to retrieve
+		// header #100 again
+		assert_eq!(eth_sync.headers.header(HeaderStatus::Orphan), Some(&header(101)));
+		assert_eq!(eth_sync.select_orphan_header_to_download(), None);
+
+		// we can't submit header #100, because its parent status is unknown
+		assert_eq!(eth_sync.select_headers_to_submit(false), None);
+
+		// instead we are trying to determine status of its parent (#99)
+		assert_eq!(eth_sync.headers.header(HeaderStatus::MaybeOrphan), Some(&header(100)));
+
+		// and the status is known, so we move previously orphaned #100 and #101 to ready queue
+		eth_sync.headers.maybe_orphan_response(&id(99), true);
+
+		// and we are ready to submit #100
+		assert_eq!(eth_sync.headers.header(HeaderStatus::MaybeExtra), Some(&header(100)));
+		eth_sync.headers.maybe_extra_response(&id(100), false);
+		assert_eq!(eth_sync.select_headers_to_submit(false), Some(vec![&header(100)]));
+		eth_sync.headers.headers_submitted(vec![id(100)]);
+
+		// and we are ready to submit #101
+		assert_eq!(eth_sync.headers.header(HeaderStatus::MaybeExtra), Some(&header(101)));
+		eth_sync.headers.maybe_extra_response(&id(101), false);
+		assert_eq!(eth_sync.select_headers_to_submit(false), Some(vec![&header(101)]));
+		eth_sync.headers.headers_submitted(vec![id(101)]);
+	}
+
+	#[test]
+	fn pruning_happens_on_target_best_header_response() {
+		let mut eth_sync = HeadersSync::<TestHeadersSyncPipeline>::new(default_sync_params());
+		eth_sync.params.prune_depth = 50;
+		eth_sync.target_best_header_response(id(100));
+		assert_eq!(eth_sync.headers.prune_border(), 50);
+	}
+
+	#[test]
+	fn only_submitting_headers_in_backup_mode_when_stalled() {
+		let mut eth_sync = HeadersSync::new(default_sync_params());
+		eth_sync.params.target_tx_mode = TargetTransactionMode::Backup;
+
+		// ethereum reports best header #102
+		eth_sync.source_best_header_number_response(102);
+
+		// substrate reports that it is at block #100
+		eth_sync.target_best_header_response(id(100));
+
+		// block #101 is downloaded first
+		eth_sync.headers.header_response(header(101).header().clone());
+		eth_sync.headers.maybe_extra_response(&id(101), false);
+
+		// ensure that headers are not submitted when sync is not stalled
+		assert_eq!(eth_sync.select_headers_to_submit(false), None);
+
+		// ensure that headers are not submitted when sync is stalled
+		assert_eq!(eth_sync.select_headers_to_submit(true), Some(vec![&header(101)]));
+	}
+
+	#[test]
+	fn does_not_select_new_headers_to_submit_when_submit_is_paused() {
+		let mut eth_sync = HeadersSync::new(default_sync_params());
+		eth_sync.params.max_headers_in_submitted_status = 1;
+
+		// ethereum reports best header #102 and substrate is at #100
+		eth_sync.source_best_header_number_response(102);
+		eth_sync.target_best_header_response(id(100));
+
+		// let's prepare #101 and #102 for submitting
+		eth_sync.headers.header_response(header(101).header().clone());
+		eth_sync.headers.maybe_extra_response(&id(101), false);
+		eth_sync.headers.header_response(header(102).header().clone());
+		eth_sync.headers.maybe_extra_response(&id(102), false);
+
+		// when submit is not paused, we're ready to submit #101
+		assert_eq!(eth_sync.select_headers_to_submit(false), Some(vec![&header(101)]));
+
+		// when submit is paused, we're not ready to submit anything
+		eth_sync.pause_submit();
+		assert_eq!(eth_sync.select_headers_to_submit(false), None);
+
+		// if best header on substrate node isn't updated, we still not submitting anything
+		eth_sync.target_best_header_response(id(100));
+		assert_eq!(eth_sync.select_headers_to_submit(false), None);
+
+		// but after it is actually updated, we are ready to submit
+		eth_sync.target_best_header_response(id(101));
+		assert_eq!(eth_sync.select_headers_to_submit(false), Some(vec![&header(102)]));
+	}
+}

polkadot/bridges/relays/headers/src/sync_loop.rs

@@ -0,0 +1,637 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Entrypoint for running headers synchronization loop.
+
+use crate::sync::{HeadersSync, HeadersSyncParams};
+use crate::sync_loop_metrics::SyncLoopMetrics;
+use crate::sync_types::{HeaderIdOf, HeaderStatus, HeadersSyncPipeline, QueuedHeader, SubmittedHeaders};
+
+use async_trait::async_trait;
+use futures::{future::FutureExt, stream::StreamExt};
+use num_traits::{Saturating, Zero};
+use relay_utils::{
+	format_ids, interval,
+	metrics::{GlobalMetrics, MetricsParams},
+	process_future_result,
+	relay_loop::Client as RelayClient,
+	retry_backoff, FailedClient, MaybeConnectionError, StringifiedMaybeConnectionError,
+};
+use std::{
+	collections::HashSet,
+	future::Future,
+	time::{Duration, Instant},
+};
+
+/// When we submit headers to target node, but see no updates of best
+/// source block known to target node during STALL_SYNC_TIMEOUT seconds,
+/// we consider that our headers are rejected because there has been reorg in target chain.
+/// This reorg could invalidate our knowledge about sync process (i.e. we have asked if
+/// HeaderA is known to target, but then reorg happened and the answer is different
+/// now) => we need to reset sync.
+/// The other option is to receive **EVERY** best target header and check if it is
+/// direct child of previous best header. But: (1) subscription doesn't guarantee that
+/// the subscriber will receive every best header (2) reorg won't always lead to sync
+/// stall and restart is a heavy operation (we forget all in-memory headers).
+const STALL_SYNC_TIMEOUT: Duration = Duration::from_secs(5 * 60);
+/// Delay after we have seen update of best source header at target node,
+/// for us to treat sync stalled. ONLY when relay operates in backup mode.
+const BACKUP_STALL_SYNC_TIMEOUT: Duration = Duration::from_secs(10 * 60);
+/// Interval between calling sync maintain procedure.
+const MAINTAIN_INTERVAL: Duration = Duration::from_secs(30);
+
+/// Source client trait.
+#[async_trait]
+pub trait SourceClient<P: HeadersSyncPipeline>: RelayClient {
+	/// Get best block number.
+	async fn best_block_number(&self) -> Result<P::Number, Self::Error>;
+
+	/// Get header by hash.
+	async fn header_by_hash(&self, hash: P::Hash) -> Result<P::Header, Self::Error>;
+
+	/// Get canonical header by number.
+	async fn header_by_number(&self, number: P::Number) -> Result<P::Header, Self::Error>;
+
+	/// Get completion data by header hash.
+	async fn header_completion(&self, id: HeaderIdOf<P>)
+		-> Result<(HeaderIdOf<P>, Option<P::Completion>), Self::Error>;
+
+	/// Get extra data by header hash.
+	async fn header_extra(
+		&self,
+		id: HeaderIdOf<P>,
+		header: QueuedHeader<P>,
+	) -> Result<(HeaderIdOf<P>, P::Extra), Self::Error>;
+}
+
+/// Target client trait.
+#[async_trait]
+pub trait TargetClient<P: HeadersSyncPipeline>: RelayClient {
+	/// Returns ID of best header known to the target node.
+	async fn best_header_id(&self) -> Result<HeaderIdOf<P>, Self::Error>;
+
+	/// Returns true if header is known to the target node.
+	async fn is_known_header(&self, id: HeaderIdOf<P>) -> Result<(HeaderIdOf<P>, bool), Self::Error>;
+
+	/// Submit headers.
+	async fn submit_headers(&self, headers: Vec<QueuedHeader<P>>) -> SubmittedHeaders<HeaderIdOf<P>, Self::Error>;
+
+	/// Returns ID of headers that require to be 'completed' before children can be submitted.
+	async fn incomplete_headers_ids(&self) -> Result<HashSet<HeaderIdOf<P>>, Self::Error>;
+
+	/// Submit completion data for header.
+	async fn complete_header(&self, id: HeaderIdOf<P>, completion: P::Completion)
+		-> Result<HeaderIdOf<P>, Self::Error>;
+
+	/// Returns true if header requires extra data to be submitted.
+	async fn requires_extra(&self, header: QueuedHeader<P>) -> Result<(HeaderIdOf<P>, bool), Self::Error>;
+}
+
+/// Synchronization maintain procedure.
+#[async_trait]
+pub trait SyncMaintain<P: HeadersSyncPipeline>: Clone + Send + Sync {
+	/// Run custom maintain procedures. This is guaranteed to be called when both source and target
+	/// clients are unoccupied.
+	async fn maintain(&self, _sync: &mut HeadersSync<P>) {}
+}
+
+impl<P: HeadersSyncPipeline> SyncMaintain<P> for () {}
+
+/// Return prefix that will be used by default to expose Prometheus metrics of the finality proofs sync loop.
+pub fn metrics_prefix<P: HeadersSyncPipeline>() -> String {
+	format!("{}_to_{}_Sync", P::SOURCE_NAME, P::TARGET_NAME)
+}
+
+/// Run headers synchronization.
+#[allow(clippy::too_many_arguments)]
+pub async fn run<P: HeadersSyncPipeline, TC: TargetClient<P>>(
+	source_client: impl SourceClient<P>,
+	source_tick: Duration,
+	target_client: TC,
+	target_tick: Duration,
+	sync_maintain: impl SyncMaintain<P>,
+	sync_params: HeadersSyncParams,
+	metrics_params: MetricsParams,
+	exit_signal: impl Future<Output = ()>,
+) -> Result<(), String> {
+	let exit_signal = exit_signal.shared();
+	relay_utils::relay_loop(source_client, target_client)
+		.with_metrics(Some(metrics_prefix::<P>()), metrics_params)
+		.loop_metric(|registry, prefix| SyncLoopMetrics::new(registry, prefix))?
+		.standalone_metric(|registry, prefix| GlobalMetrics::new(registry, prefix))?
+		.expose()
+		.await?
+		.run(|source_client, target_client, metrics| {
+			run_until_connection_lost(
+				source_client,
+				source_tick,
+				target_client,
+				target_tick,
+				sync_maintain.clone(),
+				sync_params.clone(),
+				metrics,
+				exit_signal.clone(),
+			)
+		})
+		.await
+}
+
+/// Run headers synchronization.
+#[allow(clippy::too_many_arguments)]
+async fn run_until_connection_lost<P: HeadersSyncPipeline, TC: TargetClient<P>>(
+	source_client: impl SourceClient<P>,
+	source_tick: Duration,
+	target_client: TC,
+	target_tick: Duration,
+	sync_maintain: impl SyncMaintain<P>,
+	sync_params: HeadersSyncParams,
+	metrics_sync: Option<SyncLoopMetrics>,
+	exit_signal: impl Future<Output = ()>,
+) -> Result<(), FailedClient> {
+	let mut progress_context = (Instant::now(), None, None);
+
+	let mut sync = HeadersSync::<P>::new(sync_params);
+	let mut stall_countdown = None;
+	let mut last_update_time = Instant::now();
+
+	let mut source_retry_backoff = retry_backoff();
+	let mut source_client_is_online = false;
+	let mut source_best_block_number_required = false;
+	let source_best_block_number_future = source_client.best_block_number().fuse();
+	let source_new_header_future = futures::future::Fuse::terminated();
+	let source_orphan_header_future = futures::future::Fuse::terminated();
+	let source_extra_future = futures::future::Fuse::terminated();
+	let source_completion_future = futures::future::Fuse::terminated();
+	let source_go_offline_future = futures::future::Fuse::terminated();
+	let source_tick_stream = interval(source_tick).fuse();
+
+	let mut target_retry_backoff = retry_backoff();
+	let mut target_client_is_online = false;
+	let mut target_best_block_required = false;
+	let mut target_incomplete_headers_required = true;
+	let target_best_block_future = target_client.best_header_id().fuse();
+	let target_incomplete_headers_future = futures::future::Fuse::terminated();
+	let target_extra_check_future = futures::future::Fuse::terminated();
+	let target_existence_status_future = futures::future::Fuse::terminated();
+	let target_submit_header_future = futures::future::Fuse::terminated();
+	let target_complete_header_future = futures::future::Fuse::terminated();
+	let target_go_offline_future = futures::future::Fuse::terminated();
+	let target_tick_stream = interval(target_tick).fuse();
+
+	let mut maintain_required = false;
+	let maintain_stream = interval(MAINTAIN_INTERVAL).fuse();
+
+	let exit_signal = exit_signal.fuse();
+
+	futures::pin_mut!(
+		source_best_block_number_future,
+		source_new_header_future,
+		source_orphan_header_future,
+		source_extra_future,
+		source_completion_future,
+		source_go_offline_future,
+		source_tick_stream,
+		target_best_block_future,
+		target_incomplete_headers_future,
+		target_extra_check_future,
+		target_existence_status_future,
+		target_submit_header_future,
+		target_complete_header_future,
+		target_go_offline_future,
+		target_tick_stream,
+		maintain_stream,
+		exit_signal
+	);
+
+	loop {
+		futures::select! {
+			source_best_block_number = source_best_block_number_future => {
+				source_best_block_number_required = false;
+
+				source_client_is_online = process_future_result(
+					source_best_block_number,
+					&mut source_retry_backoff,
+					|source_best_block_number| sync.source_best_header_number_response(source_best_block_number),
+					&mut source_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving best header number from {}", P::SOURCE_NAME),
+				).fail_if_connection_error(FailedClient::Source)?;
+			},
+			source_new_header = source_new_header_future => {
+				source_client_is_online = process_future_result(
+					source_new_header,
+					&mut source_retry_backoff,
+					|source_new_header| sync.headers_mut().header_response(source_new_header),
+					&mut source_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving header from {} node", P::SOURCE_NAME),
+				).fail_if_connection_error(FailedClient::Source)?;
+			},
+			source_orphan_header = source_orphan_header_future => {
+				source_client_is_online = process_future_result(
+					source_orphan_header,
+					&mut source_retry_backoff,
+					|source_orphan_header| sync.headers_mut().header_response(source_orphan_header),
+					&mut source_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving orphan header from {} node", P::SOURCE_NAME),
+				).fail_if_connection_error(FailedClient::Source)?;
+			},
+			source_extra = source_extra_future => {
+				source_client_is_online = process_future_result(
+					source_extra,
+					&mut source_retry_backoff,
+					|(header, extra)| sync.headers_mut().extra_response(&header, extra),
+					&mut source_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving extra data from {} node", P::SOURCE_NAME),
+				).fail_if_connection_error(FailedClient::Source)?;
+			},
+			source_completion = source_completion_future => {
+				source_client_is_online = process_future_result(
+					source_completion,
+					&mut source_retry_backoff,
+					|(header, completion)| sync.headers_mut().completion_response(&header, completion),
+					&mut source_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving completion data from {} node", P::SOURCE_NAME),
+				).fail_if_connection_error(FailedClient::Source)?;
+			},
+			_ = source_go_offline_future => {
+				source_client_is_online = true;
+			},
+			_ = source_tick_stream.next() => {
+				if sync.is_almost_synced() {
+					source_best_block_number_required = true;
+				}
+			},
+			target_best_block = target_best_block_future => {
+				target_best_block_required = false;
+
+				target_client_is_online = process_future_result(
+					target_best_block,
+					&mut target_retry_backoff,
+					|target_best_block| {
+						let head_updated = sync.target_best_header_response(target_best_block);
+						if head_updated {
+							last_update_time = Instant::now();
+						}
+						match head_updated {
+							// IF head is updated AND there are still our transactions:
+							// => restart stall countdown timer
+							true if sync.headers().headers_in_status(HeaderStatus::Submitted) != 0 =>
+								stall_countdown = Some(Instant::now()),
+							// IF head is updated AND there are no our transactions:
+							// => stop stall countdown timer
+							true => stall_countdown = None,
+							// IF head is not updated AND stall countdown is not yet completed
+							// => do nothing
+							false if stall_countdown
+								.map(|stall_countdown| stall_countdown.elapsed() < STALL_SYNC_TIMEOUT)
+								.unwrap_or(true)
+								=> (),
+							// IF head is not updated AND stall countdown has completed
+							// => restart sync
+							false => {
+								log::info!(
+									target: "bridge",
+									"Sync has stalled. Restarting {} headers synchronization.",
+									P::SOURCE_NAME,
+								);
+								stall_countdown = None;
+								sync.restart();
+							},
+						}
+					},
+					&mut target_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving best known {} header from {} node", P::SOURCE_NAME, P::TARGET_NAME),
+				).fail_if_connection_error(FailedClient::Target)?;
+			},
+			incomplete_headers_ids = target_incomplete_headers_future => {
+				target_incomplete_headers_required = false;
+
+				target_client_is_online = process_future_result(
+					incomplete_headers_ids,
+					&mut target_retry_backoff,
+					|incomplete_headers_ids| sync.headers_mut().incomplete_headers_response(incomplete_headers_ids),
+					&mut target_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving incomplete headers from {} node", P::TARGET_NAME),
+				).fail_if_connection_error(FailedClient::Target)?;
+			},
+			target_existence_status = target_existence_status_future => {
+				target_client_is_online = process_future_result(
+					target_existence_status,
+					&mut target_retry_backoff,
+					|(target_header, target_existence_status)| sync
+						.headers_mut()
+						.maybe_orphan_response(&target_header, target_existence_status),
+					&mut target_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving existence status from {} node", P::TARGET_NAME),
+				).fail_if_connection_error(FailedClient::Target)?;
+			},
+			submitted_headers = target_submit_header_future => {
+				// following line helps Rust understand the type of `submitted_headers` :/
+				let submitted_headers: SubmittedHeaders<HeaderIdOf<P>, TC::Error> = submitted_headers;
+				let submitted_headers_str = format!("{}", submitted_headers);
+				let all_headers_rejected = submitted_headers.submitted.is_empty()
+					&& submitted_headers.incomplete.is_empty();
+				let has_submitted_headers = sync.headers().headers_in_status(HeaderStatus::Submitted) != 0;
+
+				let maybe_fatal_error = match submitted_headers.fatal_error {
+					Some(fatal_error) => Err(StringifiedMaybeConnectionError::new(
+						fatal_error.is_connection_error(),
+						format!("{:?}", fatal_error),
+					)),
+					None if all_headers_rejected && !has_submitted_headers =>
+						Err(StringifiedMaybeConnectionError::new(false, "All headers were rejected".into())),
+					None => Ok(()),
+				};
+
+				let no_fatal_error = maybe_fatal_error.is_ok();
+				target_client_is_online = process_future_result(
+					maybe_fatal_error,
+					&mut target_retry_backoff,
+					|_| {},
+					&mut target_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error submitting headers to {} node", P::TARGET_NAME),
+				).fail_if_connection_error(FailedClient::Target)?;
+
+				log::debug!(target: "bridge", "Header submit result: {}", submitted_headers_str);
+
+				sync.headers_mut().headers_submitted(submitted_headers.submitted);
+				sync.headers_mut().add_incomplete_headers(false, submitted_headers.incomplete);
+
+				// when there's no fatal error, but node has rejected all our headers we may
+				// want to pause until our submitted headers will be accepted
+				if no_fatal_error && all_headers_rejected && has_submitted_headers {
+					sync.pause_submit();
+				}
+			},
+			target_complete_header_result = target_complete_header_future => {
+				target_client_is_online = process_future_result(
+					target_complete_header_result,
+					&mut target_retry_backoff,
+					|completed_header| sync.headers_mut().header_completed(&completed_header),
+					&mut target_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error completing headers at {}", P::TARGET_NAME),
+				).fail_if_connection_error(FailedClient::Target)?;
+			},
+			target_extra_check_result = target_extra_check_future => {
+				target_client_is_online = process_future_result(
+					target_extra_check_result,
+					&mut target_retry_backoff,
+					|(header, extra_check_result)| sync
+						.headers_mut()
+						.maybe_extra_response(&header, extra_check_result),
+					&mut target_go_offline_future,
+					async_std::task::sleep,
+					|| format!("Error retrieving receipts requirement from {} node", P::TARGET_NAME),
+				).fail_if_connection_error(FailedClient::Target)?;
+			},
+			_ = target_go_offline_future => {
+				target_client_is_online = true;
+			},
+			_ = target_tick_stream.next() => {
+				target_best_block_required = true;
+				target_incomplete_headers_required = true;
+			},
+
+			_ = maintain_stream.next() => {
+				maintain_required = true;
+			},
+			_ = exit_signal => {
+				return Ok(());
+			}
+		}
+
+		// update metrics
+		if let Some(ref metrics_sync) = metrics_sync {
+			metrics_sync.update(&sync);
+		}
+
+		// print progress
+		progress_context = print_sync_progress(progress_context, &sync);
+
+		// run maintain procedures
+		if maintain_required && source_client_is_online && target_client_is_online {
+			log::debug!(target: "bridge", "Maintaining headers sync loop");
+			maintain_required = false;
+			sync_maintain.maintain(&mut sync).await;
+		}
+
+		// If the target client is accepting requests we update the requests that
+		// we want it to run
+		if !maintain_required && target_client_is_online {
+			// NOTE: Is is important to reset this so that we only have one
+			// request being processed by the client at a time. This prevents
+			// race conditions like receiving two transactions with the same
+			// nonce from the client.
+			target_client_is_online = false;
+
+			// The following is how we prioritize requests:
+			//
+			// 1. Get best block
+			//     - Stops us from downloading or submitting new blocks
+			//     - Only called rarely
+			//
+			// 2. Get incomplete headers
+			//     - Stops us from submitting new blocks
+			//     - Only called rarely
+			//
+			// 3. Get complete headers
+			//     - Stops us from submitting new blocks
+			//
+			// 4. Check if we need extra data from source
+			//     - Stops us from downloading or submitting new blocks
+			//
+			// 5. Check existence of header
+			//     - Stops us from submitting new blocks
+			//
+			// 6. Submit header
+
+			if target_best_block_required {
+				log::debug!(target: "bridge", "Asking {} about best block", P::TARGET_NAME);
+				target_best_block_future.set(target_client.best_header_id().fuse());
+			} else if target_incomplete_headers_required {
+				log::debug!(target: "bridge", "Asking {} about incomplete headers", P::TARGET_NAME);
+				target_incomplete_headers_future.set(target_client.incomplete_headers_ids().fuse());
+			} else if let Some((id, completion)) = sync.headers_mut().header_to_complete() {
+				log::debug!(
+					target: "bridge",
+					"Going to complete header: {:?}",
+					id,
+				);
+
+				target_complete_header_future.set(target_client.complete_header(id, completion.clone()).fuse());
+			} else if let Some(header) = sync.headers().header(HeaderStatus::MaybeExtra) {
+				log::debug!(
+					target: "bridge",
+					"Checking if header submission requires extra: {:?}",
+					header.id(),
+				);
+
+				target_extra_check_future.set(target_client.requires_extra(header.clone()).fuse());
+			} else if let Some(header) = sync.headers().header(HeaderStatus::MaybeOrphan) {
+				// for MaybeOrphan we actually ask for parent' header existence
+				let parent_id = header.parent_id();
+
+				log::debug!(
+					target: "bridge",
+					"Asking {} node for existence of: {:?}",
+					P::TARGET_NAME,
+					parent_id,
+				);
+
+				target_existence_status_future.set(target_client.is_known_header(parent_id).fuse());
+			} else if let Some(headers) =
+				sync.select_headers_to_submit(last_update_time.elapsed() > BACKUP_STALL_SYNC_TIMEOUT)
+			{
+				log::debug!(
+					target: "bridge",
+					"Submitting {} header(s) to {} node: {:?}",
+					headers.len(),
+					P::TARGET_NAME,
+					format_ids(headers.iter().map(|header| header.id())),
+				);
+
+				let headers = headers.into_iter().cloned().collect();
+				target_submit_header_future.set(target_client.submit_headers(headers).fuse());
+
+				// remember that we have submitted some headers
+				if stall_countdown.is_none() {
+					stall_countdown = Some(Instant::now());
+				}
+			} else {
+				target_client_is_online = true;
+			}
+		}
+
+		// If the source client is accepting requests we update the requests that
+		// we want it to run
+		if !maintain_required && source_client_is_online {
+			// NOTE: Is is important to reset this so that we only have one
+			// request being processed by the client at a time. This prevents
+			// race conditions like receiving two transactions with the same
+			// nonce from the client.
+			source_client_is_online = false;
+
+			// The following is how we prioritize requests:
+			//
+			// 1. Get best block
+			//     - Stops us from downloading or submitting new blocks
+			//     - Only called rarely
+			//
+			// 2. Download completion data
+			//     - Stops us from submitting new blocks
+			//
+			// 3. Download extra data
+			//     - Stops us from submitting new blocks
+			//
+			// 4. Download missing headers
+			//     - Stops us from downloading or submitting new blocks
+			//
+			// 5. Downloading new headers
+
+			if source_best_block_number_required {
+				log::debug!(target: "bridge", "Asking {} node about best block number", P::SOURCE_NAME);
+				source_best_block_number_future.set(source_client.best_block_number().fuse());
+			} else if let Some(id) = sync.headers_mut().incomplete_header() {
+				log::debug!(
+					target: "bridge",
+					"Retrieving completion data for header: {:?}",
+					id,
+				);
+				source_completion_future.set(source_client.header_completion(id).fuse());
+			} else if let Some(header) = sync.headers().header(HeaderStatus::Extra) {
+				let id = header.id();
+				log::debug!(
+					target: "bridge",
+					"Retrieving extra data for header: {:?}",
+					id,
+				);
+				source_extra_future.set(source_client.header_extra(id, header.clone()).fuse());
+			} else if let Some(header) = sync.select_orphan_header_to_download() {
+				// for Orphan we actually ask for parent' header
+				let parent_id = header.parent_id();
+
+				// if we have end up with orphan header#0, then we are misconfigured
+				if parent_id.0.is_zero() {
+					log::error!(
+						target: "bridge",
+						"Misconfiguration. Genesis {} header is considered orphan by {} node",
+						P::SOURCE_NAME,
+						P::TARGET_NAME,
+					);
+					return Ok(());
+				}
+
+				log::debug!(
+					target: "bridge",
+					"Going to download orphan header from {} node: {:?}",
+					P::SOURCE_NAME,
+					parent_id,
+				);
+
+				source_orphan_header_future.set(source_client.header_by_hash(parent_id.1).fuse());
+			} else if let Some(id) = sync.select_new_header_to_download() {
+				log::debug!(
+					target: "bridge",
+					"Going to download new header from {} node: {:?}",
+					P::SOURCE_NAME,
+					id,
+				);
+
+				source_new_header_future.set(source_client.header_by_number(id).fuse());
+			} else {
+				source_client_is_online = true;
+			}
+		}
+	}
+}
+
+/// Print synchronization progress.
+fn print_sync_progress<P: HeadersSyncPipeline>(
+	progress_context: (Instant, Option<P::Number>, Option<P::Number>),
+	eth_sync: &HeadersSync<P>,
+) -> (Instant, Option<P::Number>, Option<P::Number>) {
+	let (prev_time, prev_best_header, prev_target_header) = progress_context;
+	let now_time = Instant::now();
+	let (now_best_header, now_target_header) = eth_sync.status();
+
+	let need_update = now_time - prev_time > Duration::from_secs(10)
+		|| match (prev_best_header, now_best_header) {
+			(Some(prev_best_header), Some(now_best_header)) => {
+				now_best_header.0.saturating_sub(prev_best_header) > 10.into()
+			}
+			_ => false,
+		};
+	if !need_update {
+		return (prev_time, prev_best_header, prev_target_header);
+	}
+
+	log::info!(
+		target: "bridge",
+		"Synced {:?} of {:?} headers",
+		now_best_header.map(|id| id.0),
+		now_target_header,
+	);
+	(now_time, (*now_best_header).map(|id| id.0), *now_target_header)
+}

polkadot/bridges/relays/headers/src/sync_loop_metrics.rs

@@ -0,0 +1,108 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Metrics for headers synchronization relay loop.
+
+use crate::sync::HeadersSync;
+use crate::sync_types::{HeaderStatus, HeadersSyncPipeline};
+
+use num_traits::Zero;
+use relay_utils::metrics::{metric_name, register, GaugeVec, Opts, PrometheusError, Registry, U64};
+
+/// Headers sync metrics.
+#[derive(Clone)]
+pub struct SyncLoopMetrics {
+	/// Best syncing headers at "source" and "target" nodes.
+	best_block_numbers: GaugeVec<U64>,
+	/// Number of headers in given states (see `HeaderStatus`).
+	blocks_in_state: GaugeVec<U64>,
+}
+
+impl SyncLoopMetrics {
+	/// Create and register headers loop metrics.
+	pub fn new(registry: &Registry, prefix: Option<&str>) -> Result<Self, PrometheusError> {
+		Ok(SyncLoopMetrics {
+			best_block_numbers: register(
+				GaugeVec::new(
+					Opts::new(
+						metric_name(prefix, "best_block_numbers"),
+						"Best block numbers on source and target nodes",
+					),
+					&["node"],
+				)?,
+				registry,
+			)?,
+			blocks_in_state: register(
+				GaugeVec::new(
+					Opts::new(
+						metric_name(prefix, "blocks_in_state"),
+						"Number of blocks in given state",
+					),
+					&["state"],
+				)?,
+				registry,
+			)?,
+		})
+	}
+}
+
+impl SyncLoopMetrics {
+	/// Update best block number at source.
+	pub fn update_best_block_at_source<Number: Into<u64>>(&self, source_best_number: Number) {
+		self.best_block_numbers
+			.with_label_values(&["source"])
+			.set(source_best_number.into());
+	}
+
+	/// Update best block number at target.
+	pub fn update_best_block_at_target<Number: Into<u64>>(&self, target_best_number: Number) {
+		self.best_block_numbers
+			.with_label_values(&["target"])
+			.set(target_best_number.into());
+	}
+
+	/// Update metrics.
+	pub fn update<P: HeadersSyncPipeline>(&self, sync: &HeadersSync<P>) {
+		let headers = sync.headers();
+		let source_best_number = sync.source_best_number().unwrap_or_else(Zero::zero);
+		let target_best_number = sync.target_best_header().map(|id| id.0).unwrap_or_else(Zero::zero);
+
+		self.update_best_block_at_source(source_best_number);
+		self.update_best_block_at_target(target_best_number);
+
+		self.blocks_in_state
+			.with_label_values(&["maybe_orphan"])
+			.set(headers.headers_in_status(HeaderStatus::MaybeOrphan) as _);
+		self.blocks_in_state
+			.with_label_values(&["orphan"])
+			.set(headers.headers_in_status(HeaderStatus::Orphan) as _);
+		self.blocks_in_state
+			.with_label_values(&["maybe_extra"])
+			.set(headers.headers_in_status(HeaderStatus::MaybeExtra) as _);
+		self.blocks_in_state
+			.with_label_values(&["extra"])
+			.set(headers.headers_in_status(HeaderStatus::Extra) as _);
+		self.blocks_in_state
+			.with_label_values(&["ready"])
+			.set(headers.headers_in_status(HeaderStatus::Ready) as _);
+		self.blocks_in_state
+			.with_label_values(&["incomplete"])
+			.set(headers.headers_in_status(HeaderStatus::Incomplete) as _);
+		self.blocks_in_state
+			.with_label_values(&["submitted"])
+			.set(headers.headers_in_status(HeaderStatus::Submitted) as _);
+	}
+}

polkadot/bridges/relays/headers/src/sync_loop_tests.rs

@@ -0,0 +1,594 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+#![cfg(test)]
+
+use crate::sync_loop::{run, SourceClient, TargetClient};
+use crate::sync_types::{HeadersSyncPipeline, QueuedHeader, SourceHeader, SubmittedHeaders};
+
+use async_trait::async_trait;
+use backoff::backoff::Backoff;
+use futures::{future::FutureExt, stream::StreamExt};
+use parking_lot::Mutex;
+use relay_utils::{
+	metrics::MetricsParams, process_future_result, relay_loop::Client as RelayClient, retry_backoff, HeaderId,
+	MaybeConnectionError,
+};
+use std::{
+	collections::{HashMap, HashSet},
+	sync::Arc,
+	time::Duration,
+};
+
+pub type TestNumber = u64;
+pub type TestHash = u64;
+pub type TestHeaderId = HeaderId<TestHash, TestNumber>;
+pub type TestExtra = u64;
+pub type TestCompletion = u64;
+pub type TestQueuedHeader = QueuedHeader<TestHeadersSyncPipeline>;
+
+#[derive(Default, Debug, Clone, PartialEq)]
+pub struct TestHeader {
+	pub hash: TestHash,
+	pub number: TestNumber,
+	pub parent_hash: TestHash,
+}
+
+impl SourceHeader<TestHash, TestNumber> for TestHeader {
+	fn id(&self) -> TestHeaderId {
+		HeaderId(self.number, self.hash)
+	}
+
+	fn parent_id(&self) -> TestHeaderId {
+		HeaderId(self.number - 1, self.parent_hash)
+	}
+}
+
+#[derive(Debug, Clone)]
+struct TestError(bool);
+
+impl MaybeConnectionError for TestError {
+	fn is_connection_error(&self) -> bool {
+		self.0
+	}
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TestHeadersSyncPipeline;
+
+impl HeadersSyncPipeline for TestHeadersSyncPipeline {
+	const SOURCE_NAME: &'static str = "Source";
+	const TARGET_NAME: &'static str = "Target";
+
+	type Hash = TestHash;
+	type Number = TestNumber;
+	type Header = TestHeader;
+	type Extra = TestExtra;
+	type Completion = TestCompletion;
+
+	fn estimate_size(_: &TestQueuedHeader) -> usize {
+		0
+	}
+}
+
+enum SourceMethod {
+	BestBlockNumber,
+	HeaderByHash(TestHash),
+	HeaderByNumber(TestNumber),
+	HeaderCompletion(TestHeaderId),
+	HeaderExtra(TestHeaderId, TestQueuedHeader),
+}
+
+#[derive(Clone)]
+struct Source {
+	data: Arc<Mutex<SourceData>>,
+	on_method_call: Arc<dyn Fn(SourceMethod, &mut SourceData) + Send + Sync>,
+}
+
+struct SourceData {
+	best_block_number: Result<TestNumber, TestError>,
+	header_by_hash: HashMap<TestHash, TestHeader>,
+	header_by_number: HashMap<TestNumber, TestHeader>,
+	provides_completion: bool,
+	provides_extra: bool,
+}
+
+impl Source {
+	pub fn new(
+		best_block_id: TestHeaderId,
+		headers: Vec<(bool, TestHeader)>,
+		on_method_call: impl Fn(SourceMethod, &mut SourceData) + Send + Sync + 'static,
+	) -> Self {
+		Source {
+			data: Arc::new(Mutex::new(SourceData {
+				best_block_number: Ok(best_block_id.0),
+				header_by_hash: headers
+					.iter()
+					.map(|(_, header)| (header.hash, header.clone()))
+					.collect(),
+				header_by_number: headers
+					.iter()
+					.filter_map(|(is_canonical, header)| {
+						if *is_canonical {
+							Some((header.hash, header.clone()))
+						} else {
+							None
+						}
+					})
+					.collect(),
+				provides_completion: true,
+				provides_extra: true,
+			})),
+			on_method_call: Arc::new(on_method_call),
+		}
+	}
+}
+
+#[async_trait]
+impl RelayClient for Source {
+	type Error = TestError;
+
+	async fn reconnect(&mut self) -> Result<(), TestError> {
+		unimplemented!()
+	}
+}
+
+#[async_trait]
+impl SourceClient<TestHeadersSyncPipeline> for Source {
+	async fn best_block_number(&self) -> Result<TestNumber, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(SourceMethod::BestBlockNumber, &mut *data);
+		data.best_block_number.clone()
+	}
+
+	async fn header_by_hash(&self, hash: TestHash) -> Result<TestHeader, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(SourceMethod::HeaderByHash(hash), &mut *data);
+		data.header_by_hash.get(&hash).cloned().ok_or(TestError(false))
+	}
+
+	async fn header_by_number(&self, number: TestNumber) -> Result<TestHeader, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(SourceMethod::HeaderByNumber(number), &mut *data);
+		data.header_by_number.get(&number).cloned().ok_or(TestError(false))
+	}
+
+	async fn header_completion(&self, id: TestHeaderId) -> Result<(TestHeaderId, Option<TestCompletion>), TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(SourceMethod::HeaderCompletion(id), &mut *data);
+		if data.provides_completion {
+			Ok((id, Some(test_completion(id))))
+		} else {
+			Ok((id, None))
+		}
+	}
+
+	async fn header_extra(
+		&self,
+		id: TestHeaderId,
+		header: TestQueuedHeader,
+	) -> Result<(TestHeaderId, TestExtra), TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(SourceMethod::HeaderExtra(id, header), &mut *data);
+		if data.provides_extra {
+			Ok((id, test_extra(id)))
+		} else {
+			Err(TestError(false))
+		}
+	}
+}
+
+enum TargetMethod {
+	BestHeaderId,
+	IsKnownHeader(TestHeaderId),
+	SubmitHeaders(Vec<TestQueuedHeader>),
+	IncompleteHeadersIds,
+	CompleteHeader(TestHeaderId, TestCompletion),
+	RequiresExtra(TestQueuedHeader),
+}
+
+#[derive(Clone)]
+struct Target {
+	data: Arc<Mutex<TargetData>>,
+	on_method_call: Arc<dyn Fn(TargetMethod, &mut TargetData) + Send + Sync>,
+}
+
+struct TargetData {
+	best_header_id: Result<TestHeaderId, TestError>,
+	is_known_header_by_hash: HashMap<TestHash, bool>,
+	submitted_headers: HashMap<TestHash, TestQueuedHeader>,
+	submit_headers_result: Option<SubmittedHeaders<TestHeaderId, TestError>>,
+	completed_headers: HashMap<TestHash, TestCompletion>,
+	requires_completion: bool,
+	requires_extra: bool,
+}
+
+impl Target {
+	pub fn new(
+		best_header_id: TestHeaderId,
+		headers: Vec<TestHeaderId>,
+		on_method_call: impl Fn(TargetMethod, &mut TargetData) + Send + Sync + 'static,
+	) -> Self {
+		Target {
+			data: Arc::new(Mutex::new(TargetData {
+				best_header_id: Ok(best_header_id),
+				is_known_header_by_hash: headers.iter().map(|header| (header.1, true)).collect(),
+				submitted_headers: HashMap::new(),
+				submit_headers_result: None,
+				completed_headers: HashMap::new(),
+				requires_completion: false,
+				requires_extra: false,
+			})),
+			on_method_call: Arc::new(on_method_call),
+		}
+	}
+}
+
+#[async_trait]
+impl RelayClient for Target {
+	type Error = TestError;
+
+	async fn reconnect(&mut self) -> Result<(), TestError> {
+		unimplemented!()
+	}
+}
+
+#[async_trait]
+impl TargetClient<TestHeadersSyncPipeline> for Target {
+	async fn best_header_id(&self) -> Result<TestHeaderId, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(TargetMethod::BestHeaderId, &mut *data);
+		data.best_header_id.clone()
+	}
+
+	async fn is_known_header(&self, id: TestHeaderId) -> Result<(TestHeaderId, bool), TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(TargetMethod::IsKnownHeader(id), &mut *data);
+		data.is_known_header_by_hash
+			.get(&id.1)
+			.cloned()
+			.map(|is_known_header| Ok((id, is_known_header)))
+			.unwrap_or(Ok((id, false)))
+	}
+
+	async fn submit_headers(&self, headers: Vec<TestQueuedHeader>) -> SubmittedHeaders<TestHeaderId, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(TargetMethod::SubmitHeaders(headers.clone()), &mut *data);
+		data.submitted_headers
+			.extend(headers.iter().map(|header| (header.id().1, header.clone())));
+		data.submit_headers_result.take().expect("test must accept headers")
+	}
+
+	async fn incomplete_headers_ids(&self) -> Result<HashSet<TestHeaderId>, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(TargetMethod::IncompleteHeadersIds, &mut *data);
+		if data.requires_completion {
+			Ok(data
+				.submitted_headers
+				.iter()
+				.filter(|(hash, _)| !data.completed_headers.contains_key(hash))
+				.map(|(_, header)| header.id())
+				.collect())
+		} else {
+			Ok(HashSet::new())
+		}
+	}
+
+	async fn complete_header(&self, id: TestHeaderId, completion: TestCompletion) -> Result<TestHeaderId, TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(TargetMethod::CompleteHeader(id, completion), &mut *data);
+		data.completed_headers.insert(id.1, completion);
+		Ok(id)
+	}
+
+	async fn requires_extra(&self, header: TestQueuedHeader) -> Result<(TestHeaderId, bool), TestError> {
+		let mut data = self.data.lock();
+		(self.on_method_call)(TargetMethod::RequiresExtra(header.clone()), &mut *data);
+		if data.requires_extra {
+			Ok((header.id(), true))
+		} else {
+			Ok((header.id(), false))
+		}
+	}
+}
+
+fn test_tick() -> Duration {
+	// in ideal world that should have been Duration::from_millis(0), because we do not want
+	// to sleep in tests at all, but that could lead to `select! {}` always waking on tick
+	// => not doing actual job
+	Duration::from_millis(10)
+}
+
+fn test_id(number: TestNumber) -> TestHeaderId {
+	HeaderId(number, number)
+}
+
+fn test_header(number: TestNumber) -> TestHeader {
+	let id = test_id(number);
+	TestHeader {
+		hash: id.1,
+		number: id.0,
+		parent_hash: if number == 0 {
+			TestHash::default()
+		} else {
+			test_id(number - 1).1
+		},
+	}
+}
+
+fn test_forked_id(number: TestNumber, forked_from: TestNumber) -> TestHeaderId {
+	const FORK_OFFSET: TestNumber = 1000;
+
+	if number == forked_from {
+		HeaderId(number, number)
+	} else {
+		HeaderId(number, FORK_OFFSET + number)
+	}
+}
+
+fn test_forked_header(number: TestNumber, forked_from: TestNumber) -> TestHeader {
+	let id = test_forked_id(number, forked_from);
+	TestHeader {
+		hash: id.1,
+		number: id.0,
+		parent_hash: if number == 0 {
+			TestHash::default()
+		} else {
+			test_forked_id(number - 1, forked_from).1
+		},
+	}
+}
+
+fn test_completion(id: TestHeaderId) -> TestCompletion {
+	id.0
+}
+
+fn test_extra(id: TestHeaderId) -> TestExtra {
+	id.0
+}
+
+fn source_reject_completion(method: &SourceMethod) {
+	if let SourceMethod::HeaderCompletion(_) = method {
+		unreachable!("HeaderCompletion request is not expected")
+	}
+}
+
+fn source_reject_extra(method: &SourceMethod) {
+	if let SourceMethod::HeaderExtra(_, _) = method {
+		unreachable!("HeaderExtra request is not expected")
+	}
+}
+
+fn target_accept_all_headers(method: &TargetMethod, data: &mut TargetData, requires_extra: bool) {
+	if let TargetMethod::SubmitHeaders(ref submitted) = method {
+		assert_eq!(submitted.iter().all(|header| header.extra().is_some()), requires_extra,);
+
+		data.submit_headers_result = Some(SubmittedHeaders {
+			submitted: submitted.iter().map(|header| header.id()).collect(),
+			..Default::default()
+		});
+	}
+}
+
+fn target_signal_exit_when_header_submitted(
+	method: &TargetMethod,
+	header_id: TestHeaderId,
+	exit_signal: &futures::channel::mpsc::UnboundedSender<()>,
+) {
+	if let TargetMethod::SubmitHeaders(ref submitted) = method {
+		if submitted.iter().any(|header| header.id() == header_id) {
+			exit_signal.unbounded_send(()).unwrap();
+		}
+	}
+}
+
+fn target_signal_exit_when_header_completed(
+	method: &TargetMethod,
+	header_id: TestHeaderId,
+	exit_signal: &futures::channel::mpsc::UnboundedSender<()>,
+) {
+	if let TargetMethod::CompleteHeader(completed_id, _) = method {
+		if *completed_id == header_id {
+			exit_signal.unbounded_send(()).unwrap();
+		}
+	}
+}
+
+fn run_backoff_test(result: Result<(), TestError>) -> (Duration, Duration) {
+	let mut backoff = retry_backoff();
+
+	// no randomness in tests (otherwise intervals may overlap => asserts are failing)
+	backoff.randomization_factor = 0f64;
+
+	// increase backoff's current interval
+	let interval1 = backoff.next_backoff().unwrap();
+	let interval2 = backoff.next_backoff().unwrap();
+	assert!(interval2 > interval1);
+
+	// successful future result leads to backoff's reset
+	let go_offline_future = futures::future::Fuse::terminated();
+	futures::pin_mut!(go_offline_future);
+
+	process_future_result(
+		result,
+		&mut backoff,
+		|_| {},
+		&mut go_offline_future,
+		async_std::task::sleep,
+		|| "Test error".into(),
+	);
+
+	(interval2, backoff.next_backoff().unwrap())
+}
+
+#[test]
+fn process_future_result_resets_backoff_on_success() {
+	let (interval2, interval_after_reset) = run_backoff_test(Ok(()));
+	assert!(interval2 > interval_after_reset);
+}
+
+#[test]
+fn process_future_result_resets_backoff_on_connection_error() {
+	let (interval2, interval_after_reset) = run_backoff_test(Err(TestError(true)));
+	assert!(interval2 > interval_after_reset);
+}
+
+#[test]
+fn process_future_result_does_not_reset_backoff_on_non_connection_error() {
+	let (interval2, interval_after_reset) = run_backoff_test(Err(TestError(false)));
+	assert!(interval2 < interval_after_reset);
+}
+
+struct SyncLoopTestParams {
+	best_source_header: TestHeader,
+	headers_on_source: Vec<(bool, TestHeader)>,
+	best_target_header: TestHeader,
+	headers_on_target: Vec<TestHeader>,
+	target_requires_extra: bool,
+	target_requires_completion: bool,
+	stop_at: TestHeaderId,
+}
+
+fn run_sync_loop_test(params: SyncLoopTestParams) {
+	let (exit_sender, exit_receiver) = futures::channel::mpsc::unbounded();
+	let target_requires_extra = params.target_requires_extra;
+	let target_requires_completion = params.target_requires_completion;
+	let stop_at = params.stop_at;
+	let source = Source::new(
+		params.best_source_header.id(),
+		params.headers_on_source,
+		move |method, _| {
+			if !target_requires_extra {
+				source_reject_extra(&method);
+			}
+			if !target_requires_completion {
+				source_reject_completion(&method);
+			}
+		},
+	);
+	let target = Target::new(
+		params.best_target_header.id(),
+		params.headers_on_target.into_iter().map(|header| header.id()).collect(),
+		move |method, data| {
+			target_accept_all_headers(&method, data, target_requires_extra);
+			if target_requires_completion {
+				target_signal_exit_when_header_completed(&method, stop_at, &exit_sender);
+			} else {
+				target_signal_exit_when_header_submitted(&method, stop_at, &exit_sender);
+			}
+		},
+	);
+	target.data.lock().requires_extra = target_requires_extra;
+	target.data.lock().requires_completion = target_requires_completion;
+
+	let _ = async_std::task::block_on(run(
+		source,
+		test_tick(),
+		target,
+		test_tick(),
+		(),
+		crate::sync::tests::default_sync_params(),
+		MetricsParams::disabled(),
+		exit_receiver.into_future().map(|(_, _)| ()),
+	));
+}
+
+#[test]
+fn sync_loop_is_able_to_synchronize_single_header() {
+	run_sync_loop_test(SyncLoopTestParams {
+		best_source_header: test_header(1),
+		headers_on_source: vec![(true, test_header(1))],
+		best_target_header: test_header(0),
+		headers_on_target: vec![test_header(0)],
+		target_requires_extra: false,
+		target_requires_completion: false,
+		stop_at: test_id(1),
+	});
+}
+
+#[test]
+fn sync_loop_is_able_to_synchronize_single_header_with_extra() {
+	run_sync_loop_test(SyncLoopTestParams {
+		best_source_header: test_header(1),
+		headers_on_source: vec![(true, test_header(1))],
+		best_target_header: test_header(0),
+		headers_on_target: vec![test_header(0)],
+		target_requires_extra: true,
+		target_requires_completion: false,
+		stop_at: test_id(1),
+	});
+}
+
+#[test]
+fn sync_loop_is_able_to_synchronize_single_header_with_completion() {
+	run_sync_loop_test(SyncLoopTestParams {
+		best_source_header: test_header(1),
+		headers_on_source: vec![(true, test_header(1))],
+		best_target_header: test_header(0),
+		headers_on_target: vec![test_header(0)],
+		target_requires_extra: false,
+		target_requires_completion: true,
+		stop_at: test_id(1),
+	});
+}
+
+#[test]
+fn sync_loop_is_able_to_reorganize_from_shorter_fork() {
+	run_sync_loop_test(SyncLoopTestParams {
+		best_source_header: test_header(3),
+		headers_on_source: vec![
+			(true, test_header(1)),
+			(true, test_header(2)),
+			(true, test_header(3)),
+			(false, test_forked_header(1, 0)),
+			(false, test_forked_header(2, 0)),
+		],
+		best_target_header: test_forked_header(2, 0),
+		headers_on_target: vec![test_header(0), test_forked_header(1, 0), test_forked_header(2, 0)],
+		target_requires_extra: false,
+		target_requires_completion: false,
+		stop_at: test_id(3),
+	});
+}
+
+#[test]
+fn sync_loop_is_able_to_reorganize_from_longer_fork() {
+	run_sync_loop_test(SyncLoopTestParams {
+		best_source_header: test_header(3),
+		headers_on_source: vec![
+			(true, test_header(1)),
+			(true, test_header(2)),
+			(true, test_header(3)),
+			(false, test_forked_header(1, 0)),
+			(false, test_forked_header(2, 0)),
+			(false, test_forked_header(3, 0)),
+			(false, test_forked_header(4, 0)),
+			(false, test_forked_header(5, 0)),
+		],
+		best_target_header: test_forked_header(5, 0),
+		headers_on_target: vec![
+			test_header(0),
+			test_forked_header(1, 0),
+			test_forked_header(2, 0),
+			test_forked_header(3, 0),
+			test_forked_header(4, 0),
+			test_forked_header(5, 0),
+		],
+		target_requires_extra: false,
+		target_requires_completion: false,
+		stop_at: test_id(3),
+	});
+}

polkadot/bridges/relays/headers/src/sync_types.rs

@@ -0,0 +1,189 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Types that are used by headers synchronization components.
+
+use relay_utils::{format_ids, HeaderId};
+use std::{ops::Deref, sync::Arc};
+
+/// Ethereum header synchronization status.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum HeaderStatus {
+	/// Header is unknown.
+	Unknown,
+	/// Header is in MaybeOrphan queue.
+	MaybeOrphan,
+	/// Header is in Orphan queue.
+	Orphan,
+	/// Header is in MaybeExtra queue.
+	MaybeExtra,
+	/// Header is in Extra queue.
+	Extra,
+	/// Header is in Ready queue.
+	Ready,
+	/// Header is in Incomplete queue.
+	Incomplete,
+	/// Header has been recently submitted to the target node.
+	Submitted,
+	/// Header is known to the target node.
+	Synced,
+}
+
+/// Headers synchronization pipeline.
+pub trait HeadersSyncPipeline: Clone + Send + Sync {
+	/// Name of the headers source.
+	const SOURCE_NAME: &'static str;
+	/// Name of the headers target.
+	const TARGET_NAME: &'static str;
+
+	/// Headers we're syncing are identified by this hash.
+	type Hash: Eq + Clone + Copy + Send + Sync + std::fmt::Debug + std::fmt::Display + std::hash::Hash;
+	/// Headers we're syncing are identified by this number.
+	type Number: relay_utils::BlockNumberBase;
+	/// Type of header that we're syncing.
+	type Header: SourceHeader<Self::Hash, Self::Number>;
+	/// Type of extra data for the header that we're receiving from the source node:
+	/// 1) extra data is required for some headers;
+	/// 2) target node may answer if it'll require extra data before header is submitted;
+	/// 3) extra data available since the header creation time;
+	/// 4) header and extra data are submitted in single transaction.
+	///
+	/// Example: Ethereum transactions receipts.
+	type Extra: Clone + Send + Sync + PartialEq + std::fmt::Debug;
+	/// Type of data required to 'complete' header that we're receiving from the source node:
+	/// 1) completion data is required for some headers;
+	/// 2) target node can't answer if it'll require completion data before header is accepted;
+	/// 3) completion data may be generated after header generation;
+	/// 4) header and completion data are submitted in separate transactions.
+	///
+	/// Example: Substrate GRANDPA justifications.
+	type Completion: Clone + Send + Sync + std::fmt::Debug;
+
+	/// Function used to estimate size of target-encoded header.
+	fn estimate_size(source: &QueuedHeader<Self>) -> usize;
+}
+
+/// A HeaderId for `HeaderSyncPipeline`.
+pub type HeaderIdOf<P> = HeaderId<<P as HeadersSyncPipeline>::Hash, <P as HeadersSyncPipeline>::Number>;
+
+/// Header that we're receiving from source node.
+pub trait SourceHeader<Hash, Number>: Clone + std::fmt::Debug + PartialEq + Send + Sync {
+	/// Returns ID of header.
+	fn id(&self) -> HeaderId<Hash, Number>;
+	/// Returns ID of parent header.
+	///
+	/// Panics if called for genesis header.
+	fn parent_id(&self) -> HeaderId<Hash, Number>;
+}
+
+/// Header how it's stored in the synchronization queue.
+#[derive(Clone, Debug, PartialEq)]
+pub struct QueuedHeader<P: HeadersSyncPipeline>(Arc<QueuedHeaderData<P>>);
+
+impl<P: HeadersSyncPipeline> QueuedHeader<P> {
+	/// Creates new queued header.
+	pub fn new(header: P::Header) -> Self {
+		QueuedHeader(Arc::new(QueuedHeaderData { header, extra: None }))
+	}
+
+	/// Set associated extra data.
+	pub fn set_extra(self, extra: P::Extra) -> Self {
+		QueuedHeader(Arc::new(QueuedHeaderData {
+			header: Arc::try_unwrap(self.0)
+				.map(|data| data.header)
+				.unwrap_or_else(|data| data.header.clone()),
+			extra: Some(extra),
+		}))
+	}
+}
+
+impl<P: HeadersSyncPipeline> Deref for QueuedHeader<P> {
+	type Target = QueuedHeaderData<P>;
+
+	fn deref(&self) -> &Self::Target {
+		&self.0
+	}
+}
+
+/// Header how it's stored in the synchronization queue.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct QueuedHeaderData<P: HeadersSyncPipeline> {
+	header: P::Header,
+	extra: Option<P::Extra>,
+}
+
+impl<P: HeadersSyncPipeline> QueuedHeader<P> {
+	/// Returns ID of header.
+	pub fn id(&self) -> HeaderId<P::Hash, P::Number> {
+		self.header.id()
+	}
+
+	/// Returns ID of parent header.
+	pub fn parent_id(&self) -> HeaderId<P::Hash, P::Number> {
+		self.header.parent_id()
+	}
+
+	/// Returns reference to header.
+	pub fn header(&self) -> &P::Header {
+		&self.header
+	}
+
+	/// Returns reference to associated extra data.
+	pub fn extra(&self) -> &Option<P::Extra> {
+		&self.extra
+	}
+}
+
+/// Headers submission result.
+#[derive(Debug)]
+#[cfg_attr(test, derive(PartialEq))]
+pub struct SubmittedHeaders<Id, Error> {
+	/// IDs of headers that have been submitted to target node.
+	pub submitted: Vec<Id>,
+	/// IDs of incomplete headers. These headers were submitted (so this id is also in `submitted` vec),
+	/// but all descendants are not.
+	pub incomplete: Vec<Id>,
+	/// IDs of ignored headers that we have decided not to submit (they're either rejected by
+	/// target node immediately, or they're descendants of incomplete headers).
+	pub rejected: Vec<Id>,
+	/// Fatal target node error, if it has occured during submission.
+	pub fatal_error: Option<Error>,
+}
+
+impl<Id, Error> Default for SubmittedHeaders<Id, Error> {
+	fn default() -> Self {
+		SubmittedHeaders {
+			submitted: Vec::new(),
+			incomplete: Vec::new(),
+			rejected: Vec::new(),
+			fatal_error: None,
+		}
+	}
+}
+
+impl<Id: std::fmt::Debug, Error> std::fmt::Display for SubmittedHeaders<Id, Error> {
+	fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+		let submitted = format_ids(self.submitted.iter());
+		let incomplete = format_ids(self.incomplete.iter());
+		let rejected = format_ids(self.rejected.iter());
+
+		write!(
+			f,
+			"Submitted: {}, Incomplete: {}, Rejected: {}",
+			submitted, incomplete, rejected
+		)
+	}
+}

polkadot/bridges/relays/messages/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "messages-relay"
+version = "0.1.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+license = "GPL-3.0-or-later WITH Classpath-exception-2.0"
+
+[dependencies]
+async-std = "1.6.5"
+async-trait = "0.1.40"
+futures = "0.3.5"
+hex = "0.4"
+log = "0.4.11"
+parking_lot = "0.11.0"
+
+# Bridge Dependencies
+
+bp-messages = { path = "../../primitives/messages" }
+relay-utils = { path = "../utils" }

polkadot/bridges/relays/messages/src/lib.rs

@@ -0,0 +1,36 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+// This file is part of Parity Bridges Common.
+
+// Parity Bridges Common is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Parity Bridges Common is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Relaying [`pallet-bridge-messages`](../pallet_bridge_messages/index.html) application specific
+//! data. Message lane allows sending arbitrary messages between bridged chains. This
+//! module provides entrypoint that starts reading messages from given message lane
+//! of source chain and submits proof-of-message-at-source-chain transactions to the
+//! target chain. Additionaly, proofs-of-messages-delivery are sent back from the
+//! target chain to the source chain.
+
+// required for futures::select!
+#![recursion_limit = "1024"]
+#![warn(missing_docs)]
+
+mod metrics;
+
+pub mod message_lane;
+pub mod message_lane_loop;
+
+mod message_race_delivery;
+mod message_race_loop;
+mod message_race_receiving;
+mod message_race_strategy;