hopr-api 1.8.0

Common high-level external and internal API traits used by hopr-lib to implement the HOPR protocol
Documentation 
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
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

//! Has* accessor traits providing minimal per-component access to the HOPR node.
//!
//! Each accessor trait exposes:
//! - A typed reference to the component's API
//! - A sync `status()` method reporting component health
//!
//! Composed traits (`IncentiveChannelOperations`, `IncentiveRedeemOperations`, etc.)
//! are blanket-implemented over combinations of these accessors.

use std::time::Duration;

use futures::Stream;
use hopr_types::chain::chain_events::ChainEvent;

use super::{
    ComponentStatus, ComponentStatusReporter, EventWaitResult, NodeOnchainIdentity, TicketEvent,
    transport::TransportOperations,
};
use crate::{
    OffchainPublicKey,
    chain::HoprChainApi,
    graph::{NetworkGraphConnectivity, NetworkGraphTraverse, NetworkGraphView},
    network::NetworkView,
    tickets::TicketManagement,
};

// ---------------------------------------------------------------------------
// HasChainApi
// ---------------------------------------------------------------------------

/// Provides access to the chain component of a HOPR node.
#[auto_impl::auto_impl(&, Arc)]
pub trait HasChainApi {
    /// The concrete chain API implementation.
    type ChainApi: HoprChainApi + ComponentStatusReporter + Clone + Send + Sync + 'static;

    /// Error type for node-level chain operations (distinct from on-chain errors).
    type ChainError: std::error::Error + Send + Sync + 'static;

    /// Returns the node's on-chain identity (node address, Safe address, module address).
    fn identity(&self) -> &NodeOnchainIdentity;

    /// Returns a reference to the underlying chain API.
    fn chain_api(&self) -> &Self::ChainApi;

    /// Reports the current health of the chain component.
    fn status(&self) -> ComponentStatus;

    /// Spawns an asynchronous waiter that subscribes to [`ChainEvent`]s
    /// and resolves when `predicate` matches or `timeout` elapses.
    fn wait_for_on_chain_event<F>(
        &self,
        predicate: F,
        context: String,
        timeout: Duration,
    ) -> EventWaitResult<<Self::ChainApi as HoprChainApi>::ChainError, Self::ChainError>
    where
        F: Fn(&ChainEvent) -> bool + Send + Sync + 'static;
}

// ---------------------------------------------------------------------------
// HasNetworkView
// ---------------------------------------------------------------------------

/// Provides read-only access to the network layer (peer connectivity, addresses).
#[auto_impl::auto_impl(&, Arc)]
pub trait HasNetworkView {
    /// The concrete [`NetworkView`] implementation.
    type NetworkView: NetworkView + Send + Sync;

    /// Returns a reference to the network view.
    fn network_view(&self) -> &Self::NetworkView;

    /// Reports the current health of the network component.
    fn status(&self) -> ComponentStatus;
}

// ---------------------------------------------------------------------------
// HasGraphView
// ---------------------------------------------------------------------------

/// Provides read-only access to the network graph and its health status.
#[auto_impl::auto_impl(&, Arc)]
pub trait HasGraphView {
    /// The concrete graph type, constrained to read-only operations.
    type Graph: NetworkGraphView<NodeId = OffchainPublicKey>
        + NetworkGraphConnectivity<NodeId = OffchainPublicKey>
        + NetworkGraphTraverse<NodeId = OffchainPublicKey>
        + Send
        + Sync;

    /// Returns a reference to the network graph.
    fn graph(&self) -> &Self::Graph;

    /// Reports the current health of the graph component.
    fn status(&self) -> ComponentStatus;
}

// ---------------------------------------------------------------------------
// HasTransportApi
// ---------------------------------------------------------------------------

/// Provides access to transport-level operations (ping, peer observations).
#[auto_impl::auto_impl(&, Arc)]
pub trait HasTransportApi {
    /// The concrete [`TransportOperations`] implementation.
    type Transport: TransportOperations;

    /// Returns a reference to the transport API.
    fn transport(&self) -> &Self::Transport;

    /// Reports the current health of the transport component.
    fn status(&self) -> ComponentStatus;
}

// ---------------------------------------------------------------------------
// HasTicketManagement
// ---------------------------------------------------------------------------

/// Provides access to the ticket management component.
///
/// Only available on relay nodes that process tickets.
#[auto_impl::auto_impl(&, Arc)]
pub trait HasTicketManagement {
    /// The concrete [`TicketManagement`] implementation.
    type TicketManager: TicketManagement + Clone + Send + Sync + 'static;

    /// Returns a reference to the ticket manager.
    fn ticket_management(&self) -> &Self::TicketManager;

    /// Returns a stream of [`TicketEvent`]s from the transport layer.
    fn subscribe_ticket_events(&self) -> impl Stream<Item = TicketEvent> + Send + 'static;

    /// Reports the current health of the ticket management component.
    fn status(&self) -> ComponentStatus;
}