signet-node-types 0.19.0

Trait abstractions for the signet node's host chain interface.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

use crate::HostNotification;
use core::future::Future;
use signet_extract::Extractable;

/// Abstraction over a host chain notification source.
///
/// Drives the signet node's main loop: yielding chain events, controlling
/// backfill, and sending feedback. All block data comes from notifications;
/// the backend handles hash resolution internally.
///
/// # Implementors
///
/// - `signet-host-reth`: wraps reth's `ExExContext`
///
/// # Implementing
///
/// Implementations must uphold the following contract:
///
/// 1. **`set_head`** — called exactly once at startup before the first
///    [`next_notification`]. Subsequent calls are silently ignored. The
///    backend must resolve the block number to a hash (falling back to
///    genesis if the number is not yet available) and begin delivering
///    notifications from that point.
/// 2. **`next_notification`** — must yield notifications in host-chain order.
///    Returning `None` signals a clean shutdown.
/// 3. **`set_backfill_thresholds`** — may be called at any time. Passing
///    `None` should restore the backend's default batch size.
/// 4. **`send_finished_height`** — may be called after processing each
///    notification batch. The backend resolves the block number to a hash
///    internally. Sending a height that has already been acknowledged is a
///    no-op.
///
/// [`next_notification`]: HostNotifier::next_notification
pub trait HostNotifier: Send + Sync {
    /// A chain segment — contiguous blocks with receipts.
    type Chain: Extractable;

    /// The error type for fallible operations.
    type Error: core::error::Error + Send + Sync + 'static;

    /// Yield the next notification. `None` signals host shutdown.
    fn next_notification(
        &mut self,
    ) -> impl Future<Output = Option<Result<HostNotification<Self::Chain>, Self::Error>>> + Send;

    /// Set the head position, requesting backfill from this block number.
    /// The backend resolves the block number to a block hash internally.
    ///
    /// This must be called exactly once before the first
    /// [`next_notification`]. Subsequent calls are silently ignored.
    ///
    /// [`next_notification`]: HostNotifier::next_notification
    fn set_head(&mut self, block_number: u64);

    /// Configure backfill batch size limits. `None` means use the backend's
    /// default.
    fn set_backfill_thresholds(&mut self, max_blocks: Option<u64>);

    /// Signal that processing is complete up to this host block number.
    /// The backend resolves the block number to a block hash internally.
    fn send_finished_height(&self, block_number: u64) -> Result<(), Self::Error>;
}