ethportal_api/
beacon.rs

1use alloy::primitives::B256;
2use discv5::enr::NodeId;
3use jsonrpsee::{core::RpcResult, proc_macros::rpc};
4use serde_json::Value;
5
6use crate::{
7    consensus::header::BeaconBlockHeader,
8    light_client::store::LightClientStore,
9    types::{
10        consensus::light_client::{
11            finality_update::LightClientFinalityUpdate,
12            optimistic_update::LightClientOptimisticUpdate,
13        },
14        content_key::beacon::BeaconContentKey,
15        enr::Enr,
16        ping_extensions::extension_types::PingExtensionType,
17        portal::{
18            AcceptInfo, DataRadius, FindContentInfo, FindNodesInfo, GetContentInfo,
19            PaginateLocalContentInfo, PongInfo, PutContentInfo, TraceContentInfo,
20        },
21        portal_wire::OfferTrace,
22    },
23    RawContentValue, RoutingTableInfo,
24};
25
26/// Portal Beacon JSON-RPC endpoints
27#[rpc(client, server, namespace = "portal")]
28pub trait BeaconNetworkApi {
29    /// Returns meta information about overlay routing table.
30    #[method(name = "beaconRoutingTableInfo")]
31    async fn routing_table_info(&self) -> RpcResult<RoutingTableInfo>;
32
33    /// Returns the node data radios
34    #[method(name = "beaconRadius")]
35    async fn radius(&self) -> RpcResult<DataRadius>;
36
37    /// Write an Ethereum Node Record to the overlay routing table.
38    #[method(name = "beaconAddEnr")]
39    async fn add_enr(&self, enr: Enr) -> RpcResult<bool>;
40
41    /// Fetch the latest ENR associated with the given node ID.
42    #[method(name = "beaconGetEnr")]
43    async fn get_enr(&self, node_id: NodeId) -> RpcResult<Enr>;
44
45    /// Delete Node ID from the overlay routing table.
46    #[method(name = "beaconDeleteEnr")]
47    async fn delete_enr(&self, node_id: NodeId) -> RpcResult<bool>;
48
49    /// Returns the local store of the light client.
50    #[method(name = "beaconLightClientStore")]
51    async fn light_client_store(&self) -> RpcResult<LightClientStore>;
52
53    /// Fetch the ENR representation associated with the given Node ID.
54    #[method(name = "beaconLookupEnr")]
55    async fn lookup_enr(&self, node_id: NodeId) -> RpcResult<Enr>;
56
57    /// Send a PING message to the designated node and wait for a PONG response
58    #[method(name = "beaconPing")]
59    async fn ping(
60        &self,
61        enr: Enr,
62        payload_type: Option<PingExtensionType>,
63        payload: Option<Value>,
64    ) -> RpcResult<PongInfo>;
65
66    /// Get the finalized state root of the finalized beacon header.
67    #[method(name = "beaconFinalizedStateRoot")]
68    async fn finalized_state_root(&self) -> RpcResult<B256>;
69
70    /// Get the finalized beacon header
71    #[method(name = "beaconFinalizedHeader")]
72    async fn finalized_header(&self) -> RpcResult<BeaconBlockHeader>;
73
74    /// Get the latest finality update
75    #[method(name = "beaconFinalityUpdate")]
76    async fn finality_update(&self) -> RpcResult<LightClientFinalityUpdate>;
77
78    /// Get the latest optimistic update
79    #[method(name = "beaconOptimisticUpdate")]
80    async fn optimistic_update(&self) -> RpcResult<LightClientOptimisticUpdate>;
81
82    /// Send a FINDNODES request for nodes that fall within the given set of distances, to the
83    /// designated peer and wait for a response
84    #[method(name = "beaconFindNodes")]
85    async fn find_nodes(&self, enr: Enr, distances: Vec<u16>) -> RpcResult<FindNodesInfo>;
86
87    /// Lookup a target node within in the network
88    #[method(name = "beaconRecursiveFindNodes")]
89    async fn recursive_find_nodes(&self, node_id: NodeId) -> RpcResult<Vec<Enr>>;
90
91    /// Get the optimistic root of the optimistic header.
92    #[method(name = "beaconOptimisticStateRoot")]
93    async fn optimistic_state_root(&self) -> RpcResult<B256>;
94
95    /// Send FINDCONTENT message to get the content with a content key.
96    #[method(name = "beaconFindContent")]
97    async fn find_content(
98        &self,
99        enr: Enr,
100        content_key: BeaconContentKey,
101    ) -> RpcResult<FindContentInfo>;
102
103    /// First checks local storage if content is not found lookup a target content key in the
104    /// network
105    #[method(name = "beaconGetContent")]
106    async fn get_content(&self, content_key: BeaconContentKey) -> RpcResult<GetContentInfo>;
107
108    /// First checks local storage if content is not found lookup a target content key in the
109    /// network. Return tracing info.
110    #[method(name = "beaconTraceGetContent")]
111    async fn trace_get_content(&self, content_key: BeaconContentKey)
112        -> RpcResult<TraceContentInfo>;
113
114    /// Pagination of local content keys
115    #[method(name = "beaconPaginateLocalContentKeys")]
116    async fn paginate_local_content_keys(
117        &self,
118        offset: u64,
119        limit: u64,
120    ) -> RpcResult<PaginateLocalContentInfo<BeaconContentKey>>;
121
122    /// Send the provided content value to interested peers. Clients may choose to send to some or
123    /// all peers. Return the number of peers that the content was gossiped to.
124    #[method(name = "beaconPutContent")]
125    async fn put_content(
126        &self,
127        content_key: BeaconContentKey,
128        content_value: RawContentValue,
129    ) -> RpcResult<PutContentInfo>;
130
131    /// Send an OFFER request with given ContentItems, to the designated peer and wait for a
132    /// response. Does not store the content locally.
133    /// Returns the content keys bitlist upon successful content transmission or empty bitlist
134    /// receive.
135    #[method(name = "beaconOffer")]
136    async fn offer(
137        &self,
138        enr: Enr,
139        content_items: Vec<(BeaconContentKey, RawContentValue)>,
140    ) -> RpcResult<AcceptInfo>;
141
142    /// Send an OFFER request with given ContentItems, to the designated peer.
143    /// Does not store the content locally.
144    /// Returns trace info for the offer.
145    #[method(name = "beaconTraceOffer")]
146    async fn trace_offer(
147        &self,
148        enr: Enr,
149        content_key: BeaconContentKey,
150        content_value: RawContentValue,
151    ) -> RpcResult<OfferTrace>;
152
153    /// Store content key with a content data to the local database.
154    #[method(name = "beaconStore")]
155    async fn store(
156        &self,
157        content_key: BeaconContentKey,
158        content_value: RawContentValue,
159    ) -> RpcResult<bool>;
160
161    /// Get a content from the local database
162    #[method(name = "beaconLocalContent")]
163    async fn local_content(&self, content_key: BeaconContentKey) -> RpcResult<RawContentValue>;
164}
ethportal_api/beacon.rs

ethportal_api/
beacon.rs
