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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
use jam_types::{CoreIndex, Hash, ServiceId, Slot};
use jsonrpsee::{
core::{RpcResult, SubscriptionResult},
proc_macros::rpc,
};
/// An update from a state subscription. `header_hash` and `slot` are of the block whose posterior
/// state contains `value`.
#[derive(serde::Serialize, serde::Deserialize, Debug)]
pub struct StateUpdate<T> {
pub header_hash: Hash,
pub slot: u32,
pub value: T,
}
#[derive(serde::Serialize, serde::Deserialize, Clone, Debug)]
pub enum VersionedParameters {
/// Parameters of the chain, version 1.
V1(crate::Parameters),
}
#[rpc(client, server)]
pub trait Rpc {
/// Parameters of the chain, version 1.
#[method(name = "parameters")]
fn parameters(&self) -> RpcResult<VersionedParameters>;
/// Returns the header hash and slot of the head of the "best" chain.
#[method(name = "bestBlock")]
fn best_block(&self) -> RpcResult<([u8; 32], u32)>;
/// Subscribe to updates of the head of the "best" chain, as returned by `bestBlock`.
#[subscription(name = "subscribeBestBlock", item = ([u8; 32], u32))]
async fn subscribe_best_block(&self) -> SubscriptionResult;
/// Returns the header hash and slot of the latest finalized block.
#[method(name = "finalizedBlock")]
fn finalized_block(&self) -> RpcResult<([u8; 32], u32)>;
/// Subscribe to updates of the latest finalized block, as returned by `finalizedBlock`.
#[subscription(name = "subscribeFinalizedBlock", item = ([u8; 32], u32))]
async fn subscribe_finalized_block(&self) -> SubscriptionResult;
/// Returns the header hash and slot of the parent of the block with the given header hash, or
/// `None` if this is not known.
#[method(name = "parent")]
fn parent(&self, header_hash: Hash) -> RpcResult<Option<([u8; 32], u32)>>;
/// Returns the posterior state root of the block with the given header hash, or `None` if this
/// is not known.
#[method(name = "stateRoot")]
fn state_root(&self, header_hash: Hash) -> RpcResult<Option<[u8; 32]>>;
/// Returns the activity statistics stored in the posterior state of the block with the given
/// header hash.
///
/// The statistics are encoded as per the GP. `None` is returned if the block's posterior state
/// is not known.
#[method(name = "statistics")]
fn statistics(&self, header_hash: Hash) -> RpcResult<Vec<u8>>;
/// Subscribe to updates of the activity statistics stored in chain state.
///
/// If `finalized` is true, the subscription will track the latest finalized block. If
/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
/// in the latter case the reported statistics may never be included in the finalized chain.
///
/// The statistics are encoded as per the GP.
#[subscription(name = "subscribeStatistics", item = StateUpdate<Vec<u8>>)]
async fn subscribe_statistics(&self, finalized: bool) -> SubscriptionResult;
/// Returns the service info for the given service ID.
///
/// The data are encoded as per the GP. `None` is returned if there is no value associated with
/// the given service ID.
#[method(name = "serviceInfo")]
fn service_info(&self, header_hash: Hash, id: u32) -> RpcResult<Option<Vec<u8>>>;
/// Subscribe to updates of the service info for the given service ID.
///
/// If `finalized` is true, the subscription will track the latest finalized block. If
/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
/// in the latter case the reported service info may never be included in the finalized chain.
///
/// The data are encoded as per the GP.
#[subscription(name = "subscribeServiceInfo", item = StateUpdate<Vec<u8>>)]
async fn subscribe_service_info(&self, id: ServiceId, finalized: bool) -> SubscriptionResult;
/// Returns the value associated with the given service ID and key in the posterior state of
/// the block with the given header hash.
///
/// `None` is returned if there is no value associated with the given service ID and key.
#[method(name = "serviceValue")]
fn service_value(
&self,
header_hash: Hash,
id: ServiceId,
key: Vec<u8>,
) -> RpcResult<Option<Vec<u8>>>;
/// Subscribe to updates of the value associated with the given service ID and key.
///
/// If `finalized` is true, the subscription will track the latest finalized block. If
/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
/// in the latter case reported value changes may never be included in the finalized chain.
///
/// The `value` field of subscription messages will be `None` when there is no value associated
/// with the given service ID and key.
#[subscription(name = "subscribeServiceValue", item = StateUpdate<Option<Vec<u8>>>)]
async fn subscribe_service_value(
&self,
id: ServiceId,
key: Vec<u8>,
finalized: bool,
) -> SubscriptionResult;
/// Returns the preimage associated with the given service ID and hash in the posterior state of
/// the block with the given header hash.
///
/// `None` is returned if there is no preimage associated with the given service ID and
/// hash.
#[method(name = "servicePreimage")]
fn service_preimage(
&self,
header_hash: Hash,
id: ServiceId,
hash: Hash,
) -> RpcResult<Option<Vec<u8>>>;
/// Subscribe to updates of the preimage associated with the given service ID and hash.
///
/// If `finalized` is true, the subscription will track the latest finalized block. If
/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
/// in the latter case reported preimage changes may never be included in the finalized chain.
///
/// The `preimage` field of subscription messages will be `None` when there is no preimage
/// associated with the given service ID and hash.
#[subscription(name = "subscribeServicePreimage", item = StateUpdate<Option<Vec<u8>>>)]
async fn subscribe_service_preimage(
&self,
id: ServiceId,
hash: Hash,
finalized: bool,
) -> SubscriptionResult;
/// Returns the preimage request associated with the given service ID and hash/len in the
/// posterior state of the block with the given header hash.
///
/// `None` is returned if there is no preimage request associated with the given service ID,
/// hash and length.
#[method(name = "serviceRequest")]
fn service_request(
&self,
header_hash: Hash,
id: ServiceId,
hash: Hash,
len: u32,
) -> RpcResult<Option<Vec<Slot>>>;
/// Subscribe to updates of the preimage associated with the given service ID and hash.
///
/// If `finalized` is true, the subscription will track the latest finalized block. If
/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
/// in the latter case reported preimage changes may never be included in the finalized chain.
///
/// The `request` field of subscription messages will be `None` when there is no preimage
/// request associated with the given service ID, hash and length.
#[subscription(name = "subscribeServiceRequest", item = StateUpdate<Option<Vec<Slot>>>)]
async fn subscribe_service_request(
&self,
id: ServiceId,
hash: Hash,
len: u32,
finalized: bool,
) -> SubscriptionResult;
/// Returns the BEEFY root of the block with the given header hash, or `None` if this is not
/// known.
#[method(name = "beefyRoot")]
fn beefy_root(&self, header_hash: Hash) -> RpcResult<Option<[u8; 32]>>;
/// Submit a work-package to the guarantors currently assigned to the given core.
#[method(name = "submitWorkPackage")]
async fn submit_work_package(
&self,
core: CoreIndex,
package: Vec<u8>,
extrinsics: Vec<Vec<u8>>,
) -> RpcResult<()>;
/// Submit a preimage which is being requested by a given service.
#[method(name = "submitPreimage")]
async fn submit_preimage(
&self,
service: ServiceId,
preimage: Vec<u8>,
require_block: Hash,
) -> RpcResult<()>;
/// Returns a list of all services currently known to be on JAM. This is a best-effort list and
/// may not reflect the true state. Nodes could e.g. reasonably hide services which are not
/// recently active from this list.
#[method(name = "listServices")]
fn list_services(&self, header_hash: Hash) -> RpcResult<Vec<ServiceId>>;
}