equivocation_detector/
lib.rs

1// Copyright 2019-2023 Parity Technologies (UK) Ltd.
2// This file is part of Parity Bridges Common.
3
4// Parity Bridges Common is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// Parity Bridges Common is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with Parity Bridges Common.  If not, see <http://www.gnu.org/licenses/>.
16
17mod block_checker;
18mod equivocation_loop;
19mod mock;
20mod reporter;
21
22use async_trait::async_trait;
23use bp_header_chain::{FinalityProof, FindEquivocations};
24use finality_relay::{FinalityPipeline, SourceClientBase};
25use relay_utils::{relay_loop::Client as RelayClient, MaybeConnectionError, TransactionTracker};
26use std::{fmt::Debug, time::Duration};
27
28pub use equivocation_loop::run;
29
30#[cfg(not(test))]
31const RECONNECT_DELAY: Duration = relay_utils::relay_loop::RECONNECT_DELAY;
32#[cfg(test)]
33const RECONNECT_DELAY: Duration = mock::TEST_RECONNECT_DELAY;
34
35pub trait EquivocationDetectionPipeline: FinalityPipeline {
36	/// Block number of the target chain.
37	type TargetNumber: relay_utils::BlockNumberBase;
38	/// The context needed for validating finality proofs.
39	type FinalityVerificationContext: Debug + Send;
40	/// The type of the equivocation proof.
41	type EquivocationProof: Clone + Debug + Send + Sync;
42	/// The equivocations finder.
43	type EquivocationsFinder: FindEquivocations<
44		Self::FinalityProof,
45		Self::FinalityVerificationContext,
46		Self::EquivocationProof,
47	>;
48}
49
50type HeaderFinalityInfo<P> = bp_header_chain::HeaderFinalityInfo<
51	<P as FinalityPipeline>::FinalityProof,
52	<P as EquivocationDetectionPipeline>::FinalityVerificationContext,
53>;
54
55/// Source client used in equivocation detection loop.
56#[async_trait]
57pub trait SourceClient<P: EquivocationDetectionPipeline>: SourceClientBase<P> {
58	/// Transaction tracker to track submitted transactions.
59	type TransactionTracker: TransactionTracker;
60
61	/// Report equivocation.
62	async fn report_equivocation(
63		&self,
64		at: P::Hash,
65		equivocation: P::EquivocationProof,
66	) -> Result<Self::TransactionTracker, Self::Error>;
67}
68
69/// Target client used in equivocation detection loop.
70#[async_trait]
71pub trait TargetClient<P: EquivocationDetectionPipeline>: RelayClient {
72	/// Get the best finalized header number.
73	async fn best_finalized_header_number(&self) -> Result<P::TargetNumber, Self::Error>;
74
75	/// Get the hash of the best source header known by the target at the provided block number.
76	async fn best_synced_header_hash(
77		&self,
78		at: P::TargetNumber,
79	) -> Result<Option<P::Hash>, Self::Error>;
80
81	/// Get the data stored by the target at the specified block for validating source finality
82	/// proofs.
83	async fn finality_verification_context(
84		&self,
85		at: P::TargetNumber,
86	) -> Result<P::FinalityVerificationContext, Self::Error>;
87
88	/// Get the finality info associated to the source headers synced with the target chain at the
89	/// specified block.
90	async fn synced_headers_finality_info(
91		&self,
92		at: P::TargetNumber,
93	) -> Result<Vec<HeaderFinalityInfo<P>>, Self::Error>;
94}
95
96/// The context needed for finding equivocations inside finality proofs and reporting them.
97#[derive(Debug, PartialEq)]
98struct EquivocationReportingContext<P: EquivocationDetectionPipeline> {
99	pub synced_header_hash: P::Hash,
100	pub synced_verification_context: P::FinalityVerificationContext,
101}
102
103impl<P: EquivocationDetectionPipeline> EquivocationReportingContext<P> {
104	/// Try to get the `EquivocationReportingContext` used by the target chain
105	/// at the provided block.
106	pub async fn try_read_from_target<TC: TargetClient<P>>(
107		target_client: &TC,
108		at: P::TargetNumber,
109	) -> Result<Option<Self>, TC::Error> {
110		let maybe_best_synced_header_hash = target_client.best_synced_header_hash(at).await?;
111		Ok(match maybe_best_synced_header_hash {
112			Some(best_synced_header_hash) => Some(EquivocationReportingContext {
113				synced_header_hash: best_synced_header_hash,
114				synced_verification_context: target_client
115					.finality_verification_context(at)
116					.await?,
117			}),
118			None => None,
119		})
120	}
121
122	/// Update with the new context introduced by the `HeaderFinalityInfo<P>` if any.
123	pub fn update(&mut self, info: HeaderFinalityInfo<P>) {
124		if let Some(new_verification_context) = info.new_verification_context {
125			self.synced_header_hash = info.finality_proof.target_header_hash();
126			self.synced_verification_context = new_verification_context;
127		}
128	}
129}
130
131async fn handle_client_error<C: RelayClient>(client: &mut C, e: C::Error) {
132	if e.is_connection_error() {
133		client.reconnect_until_success(RECONNECT_DELAY).await;
134	} else {
135		async_std::task::sleep(RECONNECT_DELAY).await;
136	}
137}
equivocation_detector/lib.rs

equivocation_detector/
lib.rs
