1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![doc = include_str!("../README.md")]
3#![deny(missing_docs)]
4#![no_std]
5
6use core::{
7 pin::Pin,
8 task::{Poll, Context},
9 num::NonZero,
10 time::Duration,
11};
12extern crate alloc;
13use alloc::boxed::Box;
14extern crate std;
15use std::collections::HashMap;
16
17use futures_core::stream::{Stream as _, FusedStream as _};
18
19use zeroize::Zeroizing;
20use ciphersuite::Ciphersuite;
21use dalek_ff_group::Ristretto;
22
23use serai_db::{Transaction as _, Db};
24
25use ::tendermint::{Signer as _, Network};
26
27mod read_write;
28pub use read_write::*;
29
30pub mod merkle;
32use merkle::*;
33
34pub mod transaction;
36use transaction::{Signed, TransactionKind};
37pub use transaction::Transaction;
38
39pub mod block;
41pub use block::Block;
42
43pub mod mempool;
44use mempool::{MempoolError, MempoolNetwork, Mempool, MempoolConsumer};
45
46mod blockchain;
47use blockchain::{Reader, Blockchain};
48
49mod tendermint;
50use tendermint::{SignatureScheme, Tendermint};
51pub use tendermint::{AggregateSignature, Commit, Slash};
52
53mod or;
54
55pub type Message<T> =
57 ::tendermint::Message<[u8; 32], [u8; 64], AggregateSignature, ReadWriteAsBorsh<Block<T>>>;
58
59struct AsyncAddToMempool<T> {
60 transaction: T,
61 bypass_rate_limit: bool,
62 response: async_channel::Sender<Result<(), MempoolError>>,
63}
64
65pin_project_lite::pin_project! {
66 struct MempoolFuture<D: Db, T: Transaction, MN: MempoolNetwork<T>> {
67 db: D,
68 #[pin]
69 mempool: Mempool<D, T, MN>,
70 #[pin]
71 mempool_recv: async_channel::Receiver<AsyncAddToMempool<T>>,
72 }
73}
74
75impl<D: Db, T: Transaction, MN: MempoolNetwork<T>> Future for MempoolFuture<D, T, MN> {
76 type Output = ();
77 fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
78 let mut projection = self.project();
79
80 let _: Poll<()> = projection.mempool.as_mut().poll(cx);
81 if (!projection.mempool_recv.is_terminated()) &&
82 let Poll::Ready(Some(AsyncAddToMempool { transaction, bypass_rate_limit, response })) =
83 projection.mempool_recv.poll_next(cx)
84 {
85 let mut txn = projection.db.txn();
86 let result = projection.mempool.add(&mut txn, transaction, bypass_rate_limit);
87 txn.commit();
88
89 let _ = response.try_send(result);
90 }
91
92 Poll::Pending
93 }
94}
95
96pin_project_lite::pin_project! {
97 pub struct Tributary<
104 D: Db,
105 T: Transaction,
106 MN: MempoolNetwork<T>,
107 Tendermint = (),
108 Loop = (),
109 > {
110 #[pin]
111 tendermint: Tendermint,
112 #[pin]
113 mempool: MempoolFuture<D, T, MN>,
114 #[pin]
115 inner_loop: Loop,
116 }
117}
118
119impl<
120 D: Db,
121 T: Transaction,
122 MN: MempoolNetwork<T>,
123 Tendermint: Future<Output = ()>,
124 Loop: Future<Output = ()>,
125> Future for Tributary<D, T, MN, Tendermint, Loop>
126{
127 type Output = ();
128 fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
129 let projection = self.project();
130
131 let _: Poll<()> = projection.tendermint.poll(cx);
132 let _: Poll<()> = projection.mempool.poll(cx);
133 let _: Poll<()> = projection.inner_loop.poll(cx);
134
135 Poll::Pending
136 }
137}
138
139impl<
140 D: 'static + Send + for<'db> Db<Transaction<'db>: Send>,
141 T: 'static + Send + Transaction,
142 MN: 'static + Send + MempoolNetwork<T>,
143 Tendermint: 'static + Send + Future<Output = ()>,
144 Loop: 'static + Send + Future<Output = ()>,
145> IntoIterator for Tributary<D, T, MN, Tendermint, Loop>
146{
147 type Item = Pin<Box<dyn Send + Future<Output = ()>>>;
148 type IntoIter = <[Self::Item; 3] as IntoIterator>::IntoIter;
149 fn into_iter(self) -> Self::IntoIter {
150 let Self { tendermint, mempool, inner_loop } = self;
151 let tendermint: Self::Item = Box::pin(tendermint);
152 let mempool = Box::pin(mempool);
153 let inner_loop = Box::pin(inner_loop);
154 [tendermint, mempool, inner_loop].into_iter()
155 }
156}
157
158#[derive(Debug)]
160pub enum TributaryError {
161 UnrepresentableBlockTime,
163 NotValidator,
165}
166
167pub enum SyncError {
169 InvalidBlock(block::SyntacticError),
171 InvalidCommit,
173}
174
175#[derive(Clone)]
177pub struct TributaryHandle<D: Db, T: Transaction> {
178 db: D,
179
180 genesis: [u8; 32],
181 block_time: Duration,
182 validator_set: crate::tendermint::ValidatorSet,
183 signature_scheme: SignatureScheme,
184
185 validator: [u8; 32],
186
187 blocks_behind: async_channel::Sender<async_channel::Sender<u64>>,
188
189 sync: async_channel::Sender<(Block<T>, crate::tendermint::Commit)>,
190 message: async_channel::Sender<Message<T>>,
191 mempool: async_channel::Sender<AsyncAddToMempool<T>>,
192 censure: async_channel::Sender<([u8; 32], async_channel::Sender<()>)>,
193
194 next_block_notification: async_channel::Sender<async_channel::Sender<()>>,
195}
196
197impl<
198 D: Send + Sync + for<'db> Db<Transaction<'db>: Send>,
199 T: Send + Sync + Transaction,
200 MN: MempoolNetwork<T>,
201> Tributary<D, T, MN>
202{
203 #[expect(clippy::too_many_arguments)]
229 pub async fn new<
230 N: Send
231 + Sync
232 + Network<[u8; 32], [u8; 64], AggregateSignature, ReadWriteAsBorsh<Block<T>>, Sleep: Send>,
233 >(
234 db: D,
235 genesis: [u8; 16],
236 genesis_time: Option<u64>,
237 validators: HashMap<[u8; 32], NonZero<u16>>,
238 tendermint_network: N,
239 mempool_network: MN,
240 key: Zeroizing<<Ristretto as Ciphersuite>::F>,
241 mempool_rate_limit: usize,
242 ) -> Result<
243 (
244 Tributary<D, T, MN, impl Send + Future<Output = ()>, impl Send + Future<Output = ()>>,
245 TributaryHandle<D, T>,
246 ),
247 TributaryError,
248 > {
249 let genesis = {
261 let mut genesis_32 = [0; 32];
262 genesis_32[16 ..].copy_from_slice(&genesis);
263 genesis_32
264 };
265
266 let genesis_time = genesis_time.unwrap_or(0);
267
268 let target_block_time =
269 N::target_block_time().ok_or(TributaryError::UnrepresentableBlockTime)?;
270
271 let (sync_send, sync_recv) =
273 async_channel::bounded::<(Block<T>, crate::tendermint::Commit)>(64);
274 let (message_send, message_recv) = async_channel::bounded::<
275 ::tendermint::MessageFor<Tendermint<D, T, MempoolConsumer<T>, N>>,
276 >(2 * validators.len());
277
278 let (mempool_send, mempool_recv) =
279 async_channel::bounded::<AsyncAddToMempool<T>>(mempool_rate_limit.max(8));
280
281 let (censure_send, censure_recv) =
282 async_channel::bounded::<([u8; 32], async_channel::Sender<()>)>(validators.len());
283
284 let (mempool, mempool_consumer) = Mempool::new(
285 db.clone(),
286 genesis,
287 validators.keys().copied(),
288 mempool_network,
289 censure_recv,
290 mempool_rate_limit,
291 );
292
293 let (blocks_behind_send, blocks_behind_recv) =
294 async_channel::bounded::<async_channel::Sender<u64>>(1);
295
296 let signature_scheme = SignatureScheme::new(genesis, validators.len());
297 let signer = signature_scheme.signer(key);
298 let validator = signer.validator();
299 if !validators.contains_key(&validator) {
300 Err(TributaryError::NotValidator)?;
301 }
302
303 let (validator_set, next_block_notification, (mut tendermint_handle, tendermint)) = {
304 let blockchain =
305 Blockchain::new(&db, genesis, genesis_time, validators, signature_scheme.clone());
306
307 let (tip, minimum_next_block_time) = {
308 let tip = blockchain.tip(&db);
309 let target_block_time = u64::try_from(target_block_time.as_millis())
310 .map_err(|_| TributaryError::UnrepresentableBlockTime)?;
311 let minimum_next_block_time = tip
312 .as_ref()
313 .map(|tip| tip.time().checked_add(target_block_time))
314 .unwrap_or(Some(genesis_time));
315 let tip = tip.map(|block| block.hash()).unwrap_or(genesis);
316 (tip, minimum_next_block_time)
317 };
318
319 let (next_block_notification_send, next_block_notification_recv) =
326 async_channel::unbounded::<async_channel::Sender<()>>();
327
328 let mut tendermint = Tendermint::<_, _, _, N>::new(
329 db.clone(),
330 genesis,
331 blockchain,
332 next_block_notification_recv,
333 mempool_consumer,
334 );
335 let validator_set = {
336 use ::tendermint::Blockchain as _;
337 tendermint.validator_set().clone()
338 };
339 let proposal = tendermint.block_proposal(tip, minimum_next_block_time, 0);
340
341 (
342 validator_set,
343 next_block_notification_send,
344 ::tendermint::Tendermint::process(
345 tendermint,
346 signer,
347 db.clone(),
348 tendermint_network,
349 proposal,
350 )
351 .await,
352 )
353 };
354
355 let inner_loop = async move {
356 loop {
357 if let Err(::tendermint::ProcessTerminated) = match (or::Or {
358 f1: or::Or { f1: sync_recv.recv(), f2: message_recv.recv() },
359 f2: blocks_behind_recv.recv(),
360 })
361 .await
362 {
363 or::Either::L(or::Either::L(Ok((block, commit)))) => {
364 tendermint_handle.sync(ReadWriteAsBorsh(block), commit).await
365 }
366 or::Either::L(or::Either::R(Ok(message))) => tendermint_handle.message(message).await,
367
368 or::Either::R(Ok(blocks_behind)) => {
369 let _ = blocks_behind.try_send({
371 let observed_block_number = u64::from(tendermint_handle.observed_block_number());
372 let block_number = u64::from(tendermint_handle.block_number());
373 observed_block_number.saturating_sub(block_number)
374 });
375 Ok(())
376 }
377
378 or::Either::L(or::Either::L(Err(_)) | or::Either::R(Err(_))) | or::Either::R(Err(_)) => {
380 Err(::tendermint::ProcessTerminated)
381 }
382 } {
383 core::future::pending::<()>().await;
385 }
386 }
387 };
388
389 Ok((
390 Tributary {
391 tendermint,
392 mempool: MempoolFuture { db: db.clone(), mempool, mempool_recv },
393 inner_loop,
394 },
395 TributaryHandle {
396 db,
397
398 genesis,
399 block_time: target_block_time,
400 validator_set,
401 signature_scheme,
402
403 validator,
404
405 blocks_behind: blocks_behind_send,
406
407 sync: sync_send,
408 message: message_send,
409 mempool: mempool_send,
410 censure: censure_send,
411
412 next_block_notification,
413 },
414 ))
415 }
416}
417
418impl<D: Db, T: Transaction> TributaryHandle<D, T> {
419 pub fn genesis(&self) -> [u8; 32] {
421 self.genesis
422 }
423
424 pub fn block_time(&self) -> Duration {
426 self.block_time
427 }
428
429 pub fn tip(&self) -> Option<[u8; 32]> {
433 Reader::<T>::tip(&self.db, self.genesis)
434 }
435
436 pub async fn blocks_behind(&self) -> u64 {
444 let (send, recv) = async_channel::bounded(1);
445 let _ = self.blocks_behind.send(send).await;
446 match recv.recv().await {
447 Ok(blocks_behind) => blocks_behind,
448 Err(_) => core::future::pending().await,
449 }
450 }
451
452 pub fn block(&self, hash: [u8; 32]) -> Option<Block<T>> {
456 Reader::<T>::block(&self.db, self.genesis, hash)
457 }
458 pub fn commit(&self, block: [u8; 32]) -> Option<crate::tendermint::Commit> {
462 crate::tendermint::db_commit(&self.db, self.genesis, block)
463 }
464 pub fn block_after(&self, parent: [u8; 32]) -> Option<[u8; 32]> {
470 Reader::<T>::block_after(&self.db, self.genesis, parent)
471 }
472
473 pub fn locally_provided_transactions(
475 &self,
476 scope: &'static str,
477 start: u64,
478 ) -> impl Iterator<Item = [u8; 32]> {
479 mempool::ProvidedReader::<T>::locally_provided(&self.db, self.genesis, scope, start)
480 }
481
482 pub async fn message(&self, message: Message<T>) {
487 let _ = self.message.send(message).await;
494 }
495
496 pub async fn sync(
513 &self,
514 block: Block<T>,
515 commit: crate::tendermint::Commit,
516 ) -> Result<(), SyncError> {
517 if !commit.verify(&self.validator_set, &self.signature_scheme, &self.genesis, block.hash()) {
518 Err(SyncError::InvalidCommit)?;
519 }
520 let () = block.verify_syntax(self.genesis).map_err(SyncError::InvalidBlock)?;
521
522 let _ = self.sync.send((block, commit)).await;
529
530 Ok(())
531 }
532
533 pub async fn transaction(&self, transaction: T) -> Result<(), MempoolError> {
543 let bypass_rate_limit =
544 if let TransactionKind::Signed { signed: Signed { signer, .. }, .. } = transaction.kind() {
545 signer == self.validator
546 } else {
547 true
548 };
549
550 let (response_send, response_recv) = async_channel::bounded(1);
551 let _ = self
552 .mempool
553 .send(AsyncAddToMempool { transaction, bypass_rate_limit, response: response_send })
554 .await;
555 match response_recv.recv().await {
556 Ok(result) => result,
557 Err(_) => core::future::pending().await,
565 }
566 }
567
568 pub async fn censure(&self, validator: [u8; 32]) {
574 let (censured_send, censured_recv) = async_channel::bounded::<()>(1);
575 let _ = self.censure.send((validator, censured_send)).await;
576 match censured_recv.recv().await {
577 Ok(()) => {}
578 Err(_) => core::future::pending().await,
586 }
587 }
588
589 pub fn next_block_notification(&self) -> impl Send + Future<Output = ()> {
591 let (next_block_notification_send, next_block_notification_recv) =
592 async_channel::bounded::<()>(1);
593 let _ = self.next_block_notification.try_send(next_block_notification_send);
594 async move {
595 match next_block_notification_recv.recv().await {
596 Ok(()) => {}
597 Err(_) => core::future::pending().await,
605 }
606 }
607 }
608}