hopr-api 1.7.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

//! 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, EventWaitResult, NodeOnchainIdentity, TicketEvent, transport::TransportOperations};
use crate::{
    OffchainPublicKey,
    chain::HoprChainApi,
    graph::{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 + 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.
#[auto_impl::auto_impl(&, Arc)]
pub trait HasGraphView {
    /// The concrete graph type, constrained to read-only operations.
    type Graph: NetworkGraphView<NodeId = OffchainPublicKey>
        + NetworkGraphTraverse<NodeId = OffchainPublicKey>
        + Send
        + Sync;

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

// ---------------------------------------------------------------------------
// 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;
}