Skip to main content

tributary_framework/tendermint/
mod.rs

1//! The integration with Tendermint for consensus.
2//!
3//! `tributary-framework` makes use of `tendermint-consensus` for consensus, complimenting its
4//! largely black-box view of consensus with the structure of a blockchain. This module implements
5//! the necessary traits from `tendermint-consensus` for the two to work together, and defines the
6//! [`Slash`] type.
7
8use core::{marker::PhantomData, pin::Pin, time::Duration};
9use alloc::{boxed::Box, collections::BTreeMap};
10use std::time::SystemTime;
11
12use serai_db::{Get, Transaction as DbTxn, Db};
13
14use ::tendermint::{Network, CommitFor, SlashReasonFor, InvalidBlock};
15
16use crate::{
17  ReadWrite as _, ReadWriteAsBorsh,
18  transaction::Transaction,
19  block::{SyntacticError, SemanticError, EphemeralError, BlockError, Block},
20  Blockchain,
21};
22
23mod validator_set;
24pub(crate) use validator_set::ValidatorSet;
25
26mod signature_scheme;
27pub use signature_scheme::*;
28
29mod slash;
30pub use slash::Slash;
31
32mod block_proposal;
33use block_proposal::BlockProposal;
34
35impl<T: Transaction> ::tendermint::Block for ReadWriteAsBorsh<Block<T>> {
36  type Hash = [u8; 32];
37
38  fn proposal_hash(&self) -> Self::Hash {
39    use blake2::Digest as _;
40    let mut digest = blake2::Blake2b256::new();
41    self.0.write(crate::merkle::DigestWriter(&mut digest)).expect("`DigestWriter` is infallible");
42    digest.finalize().into()
43  }
44
45  fn semantic_hash(&self) -> Self::Hash {
46    self.0.hash()
47  }
48}
49
50/// The [`tendermint_consensus::Commit`] type for a Tributary.
51pub type Commit = ::tendermint::Commit<AggregateSignature>;
52
53/// An abstraction over the mempool.
54// TODO: This is currently solely a half-baked internal API
55pub(crate) trait Mempool<T> {
56  /// The container for transactions from the mempool.
57  type Transactions: IntoIterator<Item = T>;
58  /// The future for the transactions to include in the proposal for the next block.
59  type Future: Future<Output = Self::Transactions>;
60  /// Fetch transactions to include in the proposal for the next block.
61  ///
62  /// These transactions MUST be syntactically and semantically valid for the specified parent
63  /// block. The transactions MUST be sorted but MAY exceed the block's size limit in their
64  /// totality. Some transactions MAY be omitted from the resulting proposal.
65  fn transactions(&mut self, parent_block: [u8; 32]) -> Self::Future;
66  /// If a validator has been censured.
67  fn censured(&self, getter: &impl Get, validator: [u8; 32]) -> bool;
68  /// Censure a validator.
69  fn censure(&mut self, txn: &mut impl DbTxn, validator: [u8; 32]);
70}
71
72mod db {
73  use super::*;
74
75  serai_db::schema!(TributaryTendermint {
76    PendingSlash: (genesis: [u8; 32], validator: [u8; 32]) -> ReadWriteAsBorsh<super::Slash>,
77    Commit: (genesis: [u8; 32], block: [u8; 32]) -> super::Commit,
78  });
79}
80
81pub(super) fn db_commit(getter: &impl Get, genesis: [u8; 32], block: [u8; 32]) -> Option<Commit> {
82  db::Commit::get(getter, genesis, block)
83}
84
85pub(crate) struct Tendermint<D, T: Transaction, M, N> {
86  genesis: [u8; 32],
87
88  _network: PhantomData<N>,
89
90  db: D,
91  blockchain: Blockchain<T>,
92  next_block_notification: async_channel::Receiver<async_channel::Sender<()>>,
93
94  /// The mempool for slashes.
95  ///
96  /// This can also be considered a `BTreeSet<T>` where `<Slash as core::cmp::Ord>` is implemented
97  /// by deferring to `<Slash::validator() as core::cmp::Ord>`.
98  slashes: BTreeMap<[u8; 32], Slash>,
99  /// The mempool for transactions.
100  mempool: M,
101}
102
103impl<D: Db, T: Transaction, M, N> Tendermint<D, T, M, N> {
104  pub(crate) fn new(
105    db: D,
106    genesis: [u8; 32],
107    blockchain: Blockchain<T>,
108    next_block_notification: async_channel::Receiver<async_channel::Sender<()>>,
109    mempool: M,
110  ) -> Self {
111    let slashes = blockchain
112      .validator_set()
113      .as_ref()
114      .keys()
115      .copied()
116      .filter_map(|validator| {
117        db::PendingSlash::get(&db, genesis, validator).map(|slash| (validator, slash.0))
118      })
119      .collect::<BTreeMap<_, _>>();
120
121    Self {
122      genesis,
123
124      _network: PhantomData,
125
126      db,
127      blockchain,
128      next_block_notification,
129
130      slashes,
131      mempool,
132    }
133  }
134}
135
136impl<
137  D: Db,
138  T: Transaction,
139  M: Mempool<T>,
140  N: Network<[u8; 32], [u8; 64], AggregateSignature, ReadWriteAsBorsh<Block<T>>>,
141> Tendermint<D, T, M, N>
142{
143  /// An `Unpin` future for a proposal for the next block.
144  ///
145  /// If `minimum_time` is none, it's considered as not being representable, in which case no block
146  /// should be proposed to maintain the system's soundness. The resulting future will never yield
147  /// `Poll::Ready(block)`.
148  pub(crate) fn block_proposal(
149    &mut self,
150    parent: [u8; 32],
151    minimum_time: Option<u64>,
152    weak_entropy: u64,
153  ) -> Pin<Box<BlockProposal<N::Sleep, M::Future>>> {
154    Box::pin(match minimum_time {
155      Some(minimum_time) => BlockProposal::some::<T, N>(
156        self.genesis,
157        parent,
158        minimum_time,
159        self.slashes.clone(),
160        self.mempool.transactions(parent),
161        weak_entropy,
162      ),
163      // If we were unable to determine the minimum time for this proposal, don't yield anything
164      None => BlockProposal::none(),
165    })
166  }
167}
168
169// TODO: Remove with Rust 1.100
170trait FnOutput {
171  type Output;
172}
173impl<R> FnOutput for fn() -> R {
174  type Output = R;
175}
176type Never = <fn() -> ! as FnOutput>::Output;
177
178type RWaB<T> = ReadWriteAsBorsh<T>;
179impl<
180  D: Send + Db,
181  T: Send + Transaction,
182  M: Send + Mempool<T>,
183  N: Send + Network<[u8; 32], [u8; 64], AggregateSignature, RWaB<Block<T>>, Sleep: Send>,
184> ::tendermint::Blockchain for Tendermint<D, T, M, N>
185{
186  type Validator = [u8; 32];
187  type ValidatorSet = ValidatorSet;
188  type SignatureScheme = SignatureScheme;
189  type Genesis = [u8; 32];
190  type Block = ReadWriteAsBorsh<Block<T>>;
191
192  type BlockProposal = Pin<Box<BlockProposal<N::Sleep, M::Future>>>;
193
194  fn genesis(&self) -> &Self::Genesis {
195    &self.genesis
196  }
197
198  fn validator_set(&self) -> &Self::ValidatorSet {
199    self.blockchain.validator_set()
200  }
201
202  fn signature_scheme(&self) -> &Self::SignatureScheme {
203    self.blockchain.signature_scheme()
204  }
205
206  fn validate(
207    &mut self,
208    proposer: Self::Validator,
209    block: &Self::Block,
210  ) -> impl Send + Future<Output = Result<(), InvalidBlock>> {
211    if self.blockchain.slashed(&self.db, proposer) {
212      return core::future::ready(Err(InvalidBlock::Fatal));
213    }
214    if self.slashes.contains_key(&proposer) || self.mempool.censured(&self.db, proposer) {
215      return core::future::ready(Err(InvalidBlock::Temporal));
216    }
217
218    core::future::ready(match self.blockchain.verify::<N>(&self.db, &block.0) {
219      Ok(()) => Ok(()),
220      Err(BlockError::Ephemeral(_)) => Err(InvalidBlock::Temporal),
221      Err(BlockError::Syntactic(_) | BlockError::Semantic(_)) => {
222        // If block is invalid for syntactic or semantic reasons, censure
223        let mut txn = self.db.txn();
224        self.mempool.censure(&mut txn, proposer);
225        txn.commit();
226
227        Err(InvalidBlock::Fatal)
228      }
229    })
230  }
231
232  fn add_block(
233    &mut self,
234    ReadWriteAsBorsh(block): Self::Block,
235    commit: CommitFor<Self>,
236  ) -> impl Send + Future<Output = Self::BlockProposal> {
237    let hash = block.hash();
238
239    let next_block_number = u64::from(commit.block_number()).checked_add(1);
240
241    let minimum_next_block_time = N::target_block_time()
242      .and_then(|target_block_time| u64::try_from(target_block_time.as_millis()).ok())
243      .and_then(|target_block_time| target_block_time.checked_add(block.time()));
244
245    #[expect(clippy::async_yields_async)]
246    async move {
247      let Some(next_block_number) = next_block_number else {
248        core::future::pending::<Never>().await
249      };
250
251      /*
252        The Tendermint consensus process and the Tributary blockchain use independent transactions.
253        The Tributary may run, adding the block, before the process reboots and Tendermint (once
254        reinstantiated) tries to add the block again (as documented).
255
256        Accordingly, if this is adding the block we already added, immediately short-circuit to the
257        block proposal.
258      */
259      if Some(hash) == crate::blockchain::Reader::<T>::tip(&self.db, self.genesis) {
260        return self.block_proposal(hash, minimum_next_block_time, next_block_number);
261      }
262
263      match self.blockchain.verify::<N>(&self.db, &block) {
264        block_result @ (Ok(()) |
265        Err(
266          BlockError::Ephemeral(
267            EphemeralError::NotLocallyProvidedTransaction { .. } | EphemeralError::Future,
268          ) |
269          BlockError::Semantic(SemanticError::DistinctProvided { .. }),
270        )) => {
271          // If this occurred in the future, sleep until it's valid
272          if matches!(block_result, Err(BlockError::Ephemeral(EphemeralError::Future))) {
273            if let Some(minimum_next_block_time) = minimum_next_block_time &&
274              let Some(minimum_next_block_time) = SystemTime::UNIX_EPOCH
275                .checked_add(Duration::from_millis(minimum_next_block_time))
276            {
277              if let Ok(time_remaining) = minimum_next_block_time.duration_since(SystemTime::now())
278              {
279                // Sleep until the next block's minimum time
280                N::sleep(time_remaining).await;
281              }
282            } else {
283              // If the amount of time in the future isn't representable, stall
284              core::future::pending::<Never>().await;
285            }
286          }
287
288          // Actually add the block
289          {
290            let mut txn = self.db.txn();
291            for slash in block.slashes() {
292              if self.slashes.remove(slash.validator()).is_some() {
293                db::PendingSlash::del(&mut txn, self.genesis, *slash.validator());
294              }
295            }
296            self.blockchain.add(&mut txn, &block);
297            db::Commit::set(&mut txn, self.genesis, hash, &commit);
298            txn.commit();
299          }
300
301          while let Ok(next_block_notification) = self.next_block_notification.try_recv() {
302            let _ = next_block_notification.try_send(());
303          }
304
305          /*
306            Sleep until the next block's minimum time before yielding back to the Tendermint
307            consensus process.
308
309            This causes the Tendermint consensus process to only start working on the next block
310            _after_ the next block may be valid, preventing (or at least limiting) the initial
311            attempts from failing in the time between when this block is added and when the next
312            block can be added.
313
314            This block of code is _solely_ intended to limit the initial attempts to achieve
315            consensus on the next block from failing. The rate limiting of blocks, preventing a
316            malicious supermajority from performing a DoS by flooding blocks, is handled _before_
317            each block is added. The block proposal logic also performs its own handling of the
318            minimum time for the next block to ensure it only creates valid proposals.
319          */
320          if let Some(minimum_next_block_time) = minimum_next_block_time &&
321            let Some(minimum_next_block_time) =
322              SystemTime::UNIX_EPOCH.checked_add(Duration::from_millis(minimum_next_block_time)) &&
323            let Ok(time_remaining) = minimum_next_block_time.duration_since(SystemTime::now())
324          {
325            N::sleep(time_remaining).await;
326          }
327
328          self.block_proposal(hash, minimum_next_block_time, next_block_number)
329        }
330
331        Err(
332          BlockError::Syntactic(
333            SyntacticError::ExceededSizeLimit { .. } |
334            SyntacticError::IncorrectContents |
335            SyntacticError::AbsurdTime |
336            SyntacticError::IncorrectOrderOfContents |
337            SyntacticError::Transaction(_),
338          ) |
339          BlockError::Semantic(
340            SemanticError::TooSoon |
341            SemanticError::InvalidSlash { .. } |
342            SemanticError::SlashAlreadyIncluded { .. } |
343            SemanticError::UnsignedAlreadyIncluded { .. } |
344            SemanticError::InvalidSigner { .. } |
345            SemanticError::Gap { .. },
346          ) |
347          BlockError::Ephemeral(EphemeralError::UnexpectedParent),
348        ) => {
349          // Because an invalid block was added, stall the consensus process/block production
350          core::future::pending::<Never>().await
351        }
352      }
353    }
354  }
355
356  // TODO: This should be tracked such that the application may pass judgement
357  fn missed_proposal(&self, _proposer: Self::Validator) {}
358
359  fn slash(&mut self, validator: Self::Validator, slash_reason: SlashReasonFor<Self>) {
360    // Check this validator hasn't already been slashed on-chain
361    if self.blockchain.slashed(&self.db, validator) {
362      return;
363    }
364
365    let slash = Slash { validator, slash_reason };
366    let Ok(slash_size) = crate::serialized_len(&slash) else { return };
367
368    let existing_slash_size = self
369      .slashes
370      .get(slash.validator())
371      .and_then(|existing_slash| crate::serialized_len(existing_slash).ok());
372
373    let mut txn = self.db.txn();
374    if existing_slash_size.is_none() {
375      self.mempool.censure(&mut txn, *slash.validator());
376    }
377    // If this validator already has a slash pending, keep whichever is smaller
378    if existing_slash_size.is_none_or(|existing_slash_size| existing_slash_size > slash_size) {
379      db::PendingSlash::set(&mut txn, self.genesis, *slash.validator(), (&slash).into());
380      self.slashes.insert(*slash.validator(), slash);
381    }
382    txn.commit();
383  }
384}