Skip to main content

sui_rpc_api/
finality.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Finality levels, and what a validator serves at each.
5//!
6//! A request names the least settled data it accepts in the
7//! [`X_SUI_FINALITY_LEVEL`] header; a request without the header accepts only
8//! certified data. A level is a minimum, so data more settled than the request
9//! asks for always satisfies it.
10//!
11//! A validator's live state includes checkpoints whose transactions are still
12//! executing, and the validator keeps no rpc indexes and no replaced object
13//! versions. [`ValidatorRequestLayer`] therefore serves:
14//!
15//! - at either level: `GetServiceInfo` and `GetCheckpoint`, which read only
16//!   certified checkpoints;
17//! - at `executed` only: the subscription streams, which carry each checkpoint
18//!   once the validator has executed it, usually before it is certified, and
19//!   reads of live state, Display and `VerifySignature` included.
20//!
21//! It refuses every other `sui.rpc` method the server mounts with
22//! `UNIMPLEMENTED` / `NOT_SERVED_HERE` (`no_rpc_indexes`), and a request at a
23//! level its method is not served at with `UNIMPLEMENTED` / `NOT_SERVED_HERE`
24//! (`uncertified_live_state`). The server does not mount
25//! `TransactionExecutionService`. Responses of the methods served only at
26//! `executed` carry no `x-sui-checkpoint-height`: the validator's certified
27//! checkpoint height does not bound what they contain.
28
29use std::collections::HashSet;
30use std::pin::Pin;
31use std::sync::Arc;
32use std::task::Context;
33use std::task::Poll;
34
35use http::HeaderMap;
36use sui_rpc::headers::X_SUI_CHECKPOINT_HEIGHT;
37use sui_rpc::proto::sui::rpc::v2::transaction_execution_service_server::SERVICE_NAME as TRANSACTION_EXECUTION_SERVICE;
38use tonic::Code;
39use tower::Layer;
40use tower::Service;
41
42use crate::RpcError;
43use crate::reader::NotServedHereCause;
44use crate::reader::not_served_here;
45
46/// Request header naming the least settled data a request accepts: `executed`
47/// or `certified`.
48pub const X_SUI_FINALITY_LEVEL: &str = "x-sui-finality-level";
49
50/// How settled data must be for a request to accept it, from least to most
51/// settled.
52#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
53enum FinalityLevel {
54    /// Executed locally, before its checkpoint is certified. How much of the
55    /// checkpoint has executed depends on the method: a checkpoint stream
56    /// waits for all of it, a point read sees the node's live state.
57    Executed,
58    /// In a checkpoint certified by a quorum of validators, and executed.
59    Certified,
60}
61
62impl FinalityLevel {
63    fn header_value(self) -> &'static str {
64        match self {
65            Self::Executed => "executed",
66            Self::Certified => "certified",
67        }
68    }
69
70    /// The level `headers` asks for: certified when the header is absent.
71    fn from_headers(headers: &HeaderMap) -> Result<Self, RpcError> {
72        let Some(value) = headers.get(X_SUI_FINALITY_LEVEL) else {
73            return Ok(Self::Certified);
74        };
75        [Self::Executed, Self::Certified]
76            .into_iter()
77            .find(|level| value.as_bytes() == level.header_value().as_bytes())
78            .ok_or_else(|| {
79                RpcError::new(
80                    Code::InvalidArgument,
81                    format!(
82                        "{X_SUI_FINALITY_LEVEL}: unknown level {value:?}; expected executed or \
83                         certified"
84                    ),
85                )
86            })
87    }
88}
89
90/// Every `sui.rpc` method a validator serves, with the most settled level it
91/// serves the method at.
92const VALIDATOR_METHODS: &[(&str, FinalityLevel)] = &[
93    (
94        "/sui.rpc.v2.LedgerService/GetServiceInfo",
95        FinalityLevel::Certified,
96    ),
97    (
98        "/sui.rpc.v2.LedgerService/GetCheckpoint",
99        FinalityLevel::Certified,
100    ),
101    (
102        "/sui.rpc.v2.SignatureVerificationService/VerifySignature",
103        FinalityLevel::Executed,
104    ),
105    (
106        "/sui.rpc.v2.SubscriptionService/SubscribeCheckpoints",
107        FinalityLevel::Executed,
108    ),
109    (
110        "/sui.rpc.v2.SubscriptionService/SubscribeTransactions",
111        FinalityLevel::Executed,
112    ),
113    (
114        "/sui.rpc.v2.SubscriptionService/SubscribeEvents",
115        FinalityLevel::Executed,
116    ),
117    (
118        "/sui.rpc.v2.LedgerService/GetObject",
119        FinalityLevel::Executed,
120    ),
121    (
122        "/sui.rpc.v2.LedgerService/BatchGetObjects",
123        FinalityLevel::Executed,
124    ),
125    (
126        "/sui.rpc.v2.LedgerService/GetEpoch",
127        FinalityLevel::Executed,
128    ),
129    (
130        "/sui.rpc.v2.LedgerService/GetProtocolConfig",
131        FinalityLevel::Executed,
132    ),
133    (
134        "/sui.rpc.v2.MovePackageService/GetPackage",
135        FinalityLevel::Executed,
136    ),
137    (
138        "/sui.rpc.v2.MovePackageService/GetDatatype",
139        FinalityLevel::Executed,
140    ),
141    (
142        "/sui.rpc.v2.MovePackageService/GetFunction",
143        FinalityLevel::Executed,
144    ),
145    (
146        "/sui.rpc.v2.NameService/LookupName",
147        FinalityLevel::Executed,
148    ),
149    (
150        "/sui.rpc.v2.NameService/ReverseLookupName",
151        FinalityLevel::Executed,
152    ),
153];
154
155/// Whether `path` names a method of `service`.
156fn is_method_of(path: &str, service: &str) -> bool {
157    path.strip_prefix('/')
158        .and_then(|path| path.strip_prefix(service))
159        .is_some_and(|method| method.starts_with('/'))
160}
161
162/// How settled the data a validator serves for a request is, or its refusal.
163/// Requests outside `sui.rpc` (gRPC health and reflection, `/health`) have no
164/// level and are always served. Requests for methods that are not in
165/// `known_methods` or that the server does not mount have no level either, and
166/// the router refuses them.
167fn admit_on_validator(
168    path: &str,
169    headers: &HeaderMap,
170    known_methods: &HashSet<String>,
171) -> Result<Option<FinalityLevel>, RpcError> {
172    if !path.starts_with("/sui.rpc.") {
173        return Ok(None);
174    }
175    let requested = FinalityLevel::from_headers(headers)?;
176    let Some(&(_, most_settled)) = VALIDATOR_METHODS.iter().find(|(method, _)| *method == path)
177    else {
178        if !known_methods.contains(path) || is_method_of(path, TRANSACTION_EXECUTION_SERVICE) {
179            return Ok(None);
180        }
181        return Err(not_served_here(
182            NotServedHereCause::NoRpcIndexes,
183            format!("validators do not keep the rpc indexes {path} needs"),
184        ));
185    };
186    if requested > most_settled {
187        return Err(not_served_here(
188            NotServedHereCause::UncertifiedLiveState,
189            format!(
190                "validators serve {path} at finality level {served}, not {requested}: their live \
191                 state includes data the network has not certified yet; send \
192                 `{X_SUI_FINALITY_LEVEL}: {served}`",
193                served = most_settled.header_value(),
194                requested = requested.header_value(),
195            ),
196        ));
197    }
198    Ok(Some(most_settled))
199}
200
201/// Admits requests to a validator's rpc server: see the module docs.
202#[derive(Clone)]
203pub(crate) struct ValidatorRequestLayer {
204    /// Every gRPC method path in the server's descriptor sets.
205    known_methods: Arc<HashSet<String>>,
206}
207
208impl ValidatorRequestLayer {
209    pub(crate) fn new(known_methods: Arc<HashSet<String>>) -> Self {
210        Self { known_methods }
211    }
212}
213
214impl<S> Layer<S> for ValidatorRequestLayer {
215    type Service = ValidatorRequests<S>;
216
217    fn layer(&self, inner: S) -> Self::Service {
218        ValidatorRequests {
219            inner,
220            known_methods: self.known_methods.clone(),
221        }
222    }
223}
224
225/// See [`ValidatorRequestLayer`].
226#[derive(Clone)]
227pub(crate) struct ValidatorRequests<S> {
228    inner: S,
229    known_methods: Arc<HashSet<String>>,
230}
231
232impl<S, ReqBody, ResBody> Service<http::Request<ReqBody>> for ValidatorRequests<S>
233where
234    S: Service<http::Request<ReqBody>, Response = http::Response<ResBody>> + Clone + Send + 'static,
235    S::Future: Send + 'static,
236    ReqBody: Send + 'static,
237    ResBody: Default,
238{
239    type Response = http::Response<ResBody>;
240    type Error = S::Error;
241    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;
242
243    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
244        self.inner.poll_ready(cx)
245    }
246
247    fn call(&mut self, request: http::Request<ReqBody>) -> Self::Future {
248        let level = match admit_on_validator(
249            request.uri().path(),
250            request.headers(),
251            &self.known_methods,
252        ) {
253            Ok(level) => level,
254            Err(error) => {
255                return Box::pin(async move { Ok(tonic::Status::from(error).into_http()) });
256            }
257        };
258
259        // Only the service `poll_ready` readied may be called, so move that one into the future
260        // and leave a fresh clone behind to be readied for the next request. See
261        // https://docs.rs/tower/latest/tower/trait.Service.html#be-careful-when-cloning-inner-services
262        let not_ready_inner = self.inner.clone();
263        let mut ready_inner = std::mem::replace(&mut self.inner, not_ready_inner);
264        Box::pin(async move {
265            let mut response = ready_inner.call(request).await?;
266            if level.is_some_and(|level| level < FinalityLevel::Certified) {
267                response.headers_mut().remove(X_SUI_CHECKPOINT_HEIGHT);
268            }
269            Ok(response)
270        })
271    }
272}
273
274#[cfg(test)]
275mod tests {
276    use super::*;
277
278    fn headers(level: Option<&str>) -> HeaderMap {
279        let mut headers = HeaderMap::new();
280        if let Some(level) = level {
281            headers.insert(X_SUI_FINALITY_LEVEL, level.parse().unwrap());
282        }
283        headers
284    }
285
286    #[test]
287    fn header_names_the_least_settled_level_accepted() {
288        let parse = |level| FinalityLevel::from_headers(&headers(level));
289        assert_eq!(parse(None).unwrap(), FinalityLevel::Certified);
290        assert_eq!(parse(Some("executed")).unwrap(), FinalityLevel::Executed);
291        assert_eq!(parse(Some("certified")).unwrap(), FinalityLevel::Certified);
292        for invalid in ["", "Certified", "ordered"] {
293            assert_eq!(
294                parse(Some(invalid)).unwrap_err().code(),
295                tonic::Code::InvalidArgument
296            );
297        }
298    }
299
300    fn sui_rpc_v2_methods() -> HashSet<String> {
301        crate::grpc_method_paths_from_file_descriptor_sets(&[
302            sui_rpc::proto::sui::rpc::v2::FILE_DESCRIPTOR_SET,
303        ])
304        .unwrap()
305    }
306
307    #[test]
308    fn validator_methods_exist() {
309        let methods = sui_rpc_v2_methods();
310        for (method, _) in VALIDATOR_METHODS {
311            assert!(
312                methods.contains(*method),
313                "{method} is not a sui.rpc.v2 method"
314            );
315        }
316    }
317
318    #[test]
319    fn validator_serves_each_method_up_to_its_level() {
320        let known_methods = sui_rpc_v2_methods();
321        let admit = |path, level| admit_on_validator(path, &headers(level), &known_methods);
322        let assert_refused = |path, level, cause| {
323            crate::reader::assert_not_served_here(admit(path, level).unwrap_err(), cause)
324        };
325
326        // Certified data at either level, so its responses keep the checkpoint
327        // height.
328        let get_checkpoint = "/sui.rpc.v2.LedgerService/GetCheckpoint";
329        for level in [None, Some("certified"), Some("executed")] {
330            assert_eq!(
331                admit(get_checkpoint, level).unwrap(),
332                Some(FinalityLevel::Certified)
333            );
334        }
335
336        // Streams of checkpoints built before certification, and reads of live
337        // state.
338        for path in [
339            "/sui.rpc.v2.SubscriptionService/SubscribeCheckpoints",
340            "/sui.rpc.v2.LedgerService/GetObject",
341            "/sui.rpc.v2.SignatureVerificationService/VerifySignature",
342        ] {
343            for level in [None, Some("certified")] {
344                assert_refused(path, level, NotServedHereCause::UncertifiedLiveState);
345            }
346            assert_eq!(
347                admit(path, Some("executed")).unwrap(),
348                Some(FinalityLevel::Executed)
349            );
350        }
351
352        // Methods that need data a validator does not keep are refused at every
353        // level, saying which.
354        for path in [
355            "/sui.rpc.v2.LedgerService/GetTransaction",
356            "/sui.rpc.v2.LedgerService/ListTransactions",
357            "/sui.rpc.v2.StateService/ListOwnedObjects",
358        ] {
359            for level in [None, Some("executed")] {
360                assert_refused(path, level, NotServedHereCause::NoRpcIndexes);
361            }
362        }
363
364        // Methods of services the validator does not mount, and unknown
365        // methods, go on to the router, which refuses them.
366        for path in [
367            "/sui.rpc.v2.TransactionExecutionService/ExecuteTransaction",
368            "/sui.rpc.v2.LedgerService/NoSuchMethod",
369        ] {
370            assert_eq!(admit(path, Some("executed")).unwrap(), None);
371        }
372
373        // An unknown level is refused before the method is looked up.
374        assert_eq!(
375            admit("/sui.rpc.v2.LedgerService/GetTransaction", Some("final"))
376                .unwrap_err()
377                .code(),
378            tonic::Code::InvalidArgument
379        );
380
381        // Requests outside sui.rpc have no level and ignore the header.
382        assert_eq!(
383            admit("/grpc.health.v1.Health/Check", Some("final")).unwrap(),
384            None
385        );
386    }
387}