Skip to main content

sui_rpc_api/ledger_history/cursor/
mod.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use anyhow::Context as _;
5use bytes::Bytes;
6use prost::Message as _;
7use sui_inverted_index::ScanDirection;
8use sui_rpc::proto::sui::rpc::v2::LedgerPosition;
9
10mod proto;
11
12use proto::sui::rpc::cursor::v1 as grpc;
13
14/// Pagination cursor for ledger-history endpoints.
15#[derive(Clone, Debug, Eq, PartialEq)]
16pub struct CursorToken {
17    pub kind: CursorKind,
18    pub position: Position,
19}
20
21/// A boundary in public ledger order (`sui.rpc.v2.LedgerPosition`): just before the item keyed
22/// `(checkpoint, transaction_index, event_index)`. An index past the last transaction of a
23/// checkpoint (or past the last event of a transaction) names the start of the next one, so
24/// different points can name the same boundary; they still order correctly against every item
25/// key. Transaction cursors carry `event_index` 0.
26#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd)]
27pub struct LedgerPoint {
28    pub checkpoint: u64,
29    pub transaction_index: u64,
30    pub event_index: u32,
31}
32
33impl LedgerPoint {
34    /// The start of the ledger.
35    pub const GENESIS: Self = Self {
36        checkpoint: 0,
37        transaction_index: 0,
38        event_index: 0,
39    };
40
41    /// The boundary before `checkpoint`'s first item.
42    pub fn checkpoint_start(checkpoint: u64) -> Self {
43        Self {
44            checkpoint,
45            ..Self::GENESIS
46        }
47    }
48
49    /// The boundary before the transaction at `transaction_index` of `checkpoint`, or a
50    /// transaction's key.
51    pub fn transaction(checkpoint: u64, transaction_index: u64) -> Self {
52        Self {
53            checkpoint,
54            transaction_index,
55            event_index: 0,
56        }
57    }
58
59    /// The boundary before an event, or an event's key.
60    pub fn event(checkpoint: u64, transaction_index: u64, event_index: u32) -> Self {
61        Self {
62            checkpoint,
63            transaction_index,
64            event_index,
65        }
66    }
67
68    /// The wire form of this point for a watermark whose cursor is `position`: only the
69    /// coordinates of that lane's keys are set.
70    pub fn to_ledger_position(self, position: &Position) -> LedgerPosition {
71        let proto = LedgerPosition::default().with_checkpoint(self.checkpoint);
72        match position {
73            Position::Checkpoints { .. } => proto,
74            Position::Transactions { .. } => proto.with_transaction_index(self.transaction_index),
75            Position::Events { .. } => proto
76                .with_transaction_index(self.transaction_index)
77                .with_event_index(self.event_index),
78        }
79    }
80}
81
82/// Endpoint-specific cursor position. Transaction and event positions carry `public_position`,
83/// the boundary immediately before the item at their coordinate in public ledger coordinates,
84/// independent of the cursor's kind: an item cursor's item key, or the boundary a boundary cursor
85/// names. It only labels the cursor: scans are bounded by `tx_seq` and `event_index` alone.
86#[derive(Clone, Copy, Debug, Eq, PartialEq)]
87pub enum Position {
88    Checkpoints {
89        checkpoint: u64,
90    },
91    Transactions {
92        tx_seq: u64,
93        public_position: LedgerPoint,
94    },
95    Events {
96        tx_seq: u64,
97        event_index: u32,
98        public_position: LedgerPoint,
99    },
100}
101
102impl Position {
103    /// This coordinate in public ledger coordinates: a checkpoint position's checkpoint start, or
104    /// the public position a transaction or event position carries.
105    pub fn public_position(&self) -> LedgerPoint {
106        match *self {
107            Position::Checkpoints { checkpoint } => LedgerPoint::checkpoint_start(checkpoint),
108            Position::Transactions {
109                public_position, ..
110            }
111            | Position::Events {
112                public_position, ..
113            } => public_position,
114        }
115    }
116
117    /// The resume point of a frame carrying the item at this position, whose public position is
118    /// the item's key: ascending, the boundary right after the item (the key with its lane's
119    /// finest index incremented, never carried into the next transaction or checkpoint);
120    /// descending, the key.
121    pub fn item_resume(&self, direction: ScanDirection) -> LedgerPoint {
122        let key = self.public_position();
123        if !direction.is_ascending() {
124            return key;
125        }
126        // The finest index of a real item never reaches its numeric maximum; saturating keeps the
127        // impossible edge, which a client's cursor can still name, from wrapping.
128        match self {
129            Position::Checkpoints { .. } => {
130                LedgerPoint::checkpoint_start(key.checkpoint.saturating_add(1))
131            }
132            Position::Transactions { .. } => {
133                LedgerPoint::transaction(key.checkpoint, key.transaction_index.saturating_add(1))
134            }
135            Position::Events { .. } => LedgerPoint::event(
136                key.checkpoint,
137                key.transaction_index,
138                key.event_index.saturating_add(1),
139            ),
140        }
141    }
142}
143
144/// Whether a cursor position is a matched row that was returned to the client (`Item`) or a scan
145/// frontier the server reached (`Boundary`).
146#[derive(Clone, Copy, Debug, Eq, PartialEq)]
147pub enum CursorKind {
148    Item,
149    Boundary,
150}
151
152impl CursorToken {
153    pub fn item(position: Position) -> Self {
154        Self {
155            kind: CursorKind::Item,
156            position,
157        }
158    }
159
160    pub fn boundary(position: Position) -> Self {
161        Self {
162            kind: CursorKind::Boundary,
163            position,
164        }
165    }
166
167    pub fn encode(&self) -> Bytes {
168        grpc::CursorToken::from(self).encode_to_vec().into()
169    }
170
171    pub fn decode(bytes: &[u8]) -> anyhow::Result<Self> {
172        Self::try_from(grpc::CursorToken::decode(bytes)?)
173    }
174}
175
176impl CursorKind {
177    fn to_proto(self) -> grpc::CursorKind {
178        match self {
179            CursorKind::Item => grpc::CursorKind::Item,
180            CursorKind::Boundary => grpc::CursorKind::Boundary,
181        }
182    }
183
184    fn from_proto(value: grpc::CursorKind) -> Option<Self> {
185        match value {
186            grpc::CursorKind::Item => Some(CursorKind::Item),
187            grpc::CursorKind::Boundary => Some(CursorKind::Boundary),
188            grpc::CursorKind::Unspecified => None,
189        }
190    }
191}
192
193impl From<LedgerPoint> for grpc::PublicPosition {
194    fn from(point: LedgerPoint) -> Self {
195        Self {
196            checkpoint: point.checkpoint,
197            transaction_index: point.transaction_index,
198            event_index: point.event_index,
199        }
200    }
201}
202
203impl From<grpc::PublicPosition> for LedgerPoint {
204    fn from(position: grpc::PublicPosition) -> Self {
205        Self {
206            checkpoint: position.checkpoint,
207            transaction_index: position.transaction_index,
208            event_index: position.event_index,
209        }
210    }
211}
212
213impl From<&CursorToken> for grpc::CursorToken {
214    fn from(cursor: &CursorToken) -> Self {
215        let (position, public_position) = match cursor.position {
216            Position::Checkpoints { checkpoint } => (
217                grpc::cursor_token::Position::Checkpoints(grpc::CheckpointsPosition {
218                    checkpoint: Some(checkpoint),
219                }),
220                None,
221            ),
222            Position::Transactions {
223                tx_seq,
224                public_position,
225            } => (
226                grpc::cursor_token::Position::Transactions(grpc::TransactionsPosition {
227                    tx_seq: Some(tx_seq),
228                }),
229                // A transaction cursor's position lies between or at transactions.
230                Some(LedgerPoint::transaction(
231                    public_position.checkpoint,
232                    public_position.transaction_index,
233                )),
234            ),
235            Position::Events {
236                tx_seq,
237                event_index,
238                public_position,
239            } => (
240                grpc::cursor_token::Position::Events(grpc::EventsPosition {
241                    tx_seq: Some(tx_seq),
242                    event_index: Some(event_index),
243                }),
244                Some(public_position),
245            ),
246        };
247        Self {
248            kind: cursor.kind.to_proto() as i32,
249            public_position: public_position.map(Into::into),
250            position: Some(position),
251        }
252    }
253}
254
255/// A transaction or event cursor without `public_position` is invalid. A checkpoint cursor's
256/// `public_position` is ignored: its checkpoint is already its public position. A transaction
257/// cursor's position is a place between or at transactions, so its `public_position.event_index`
258/// is ignored and decodes as 0.
259impl TryFrom<grpc::CursorToken> for CursorToken {
260    type Error = anyhow::Error;
261
262    fn try_from(proto: grpc::CursorToken) -> anyhow::Result<Self> {
263        let kind = grpc::CursorKind::try_from(proto.kind)
264            .ok()
265            .and_then(CursorKind::from_proto)
266            .with_context(|| format!("unknown cursor kind: {}", proto.kind))?;
267        let public_position = || -> anyhow::Result<LedgerPoint> {
268            proto
269                .public_position
270                .map(Into::into)
271                .context("cursor missing public_position")
272        };
273        let position = match proto.position.context("cursor missing position")? {
274            grpc::cursor_token::Position::Checkpoints(position) => Position::Checkpoints {
275                checkpoint: position.checkpoint.context("cursor missing checkpoint")?,
276            },
277            grpc::cursor_token::Position::Transactions(position) => {
278                let tx_seq = position.tx_seq.context("cursor missing tx_seq")?;
279                let point = public_position()?;
280                Position::Transactions {
281                    tx_seq,
282                    public_position: LedgerPoint::transaction(
283                        point.checkpoint,
284                        point.transaction_index,
285                    ),
286                }
287            }
288            grpc::cursor_token::Position::Events(position) => Position::Events {
289                tx_seq: position.tx_seq.context("cursor missing tx_seq")?,
290                event_index: position.event_index.context("cursor missing event_index")?,
291                public_position: public_position()?,
292            },
293        };
294        Ok(Self { kind, position })
295    }
296}
297
298#[cfg(test)]
299mod tests {
300    use super::*;
301
302    const PUBLIC: LedgerPoint = LedgerPoint {
303        checkpoint: 11,
304        transaction_index: 2,
305        event_index: 13,
306    };
307
308    fn token_bytes(
309        public_position: Option<grpc::PublicPosition>,
310        position: grpc::cursor_token::Position,
311    ) -> Vec<u8> {
312        grpc::CursorToken {
313            kind: grpc::CursorKind::Item as i32,
314            public_position,
315            position: Some(position),
316        }
317        .encode_to_vec()
318    }
319
320    #[test]
321    fn roundtrips_all_position_variants() {
322        for token in [
323            CursorToken::item(Position::Checkpoints { checkpoint: 7 }),
324            CursorToken::boundary(Position::Transactions {
325                tx_seq: 10,
326                public_position: LedgerPoint::transaction(9, 4),
327            }),
328            CursorToken::item(Position::Events {
329                tx_seq: 12,
330                event_index: 13,
331                public_position: PUBLIC,
332            }),
333            // A position at genesis encodes as an empty message, still present.
334            CursorToken::boundary(Position::Events {
335                tx_seq: 0,
336                event_index: 0,
337                public_position: LedgerPoint::GENESIS,
338            }),
339        ] {
340            let bytes = token.encode();
341            let decoded = CursorToken::decode(&bytes).unwrap();
342            assert_eq!(decoded, token);
343            assert_eq!(decoded.encode(), bytes, "re-encoding keeps the bytes");
344        }
345    }
346
347    /// A cursor whose transaction or event position carries a checkpoint label in tag 1 decodes by
348    /// its scan position and public position, and re-encodes without the label.
349    #[test]
350    fn decodes_cursors_carrying_a_checkpoint_label() {
351        let cases: [(&[u8], CursorToken, &[u8]); 2] = [
352            (
353                // kind = ITEM; transactions { 1: 42, tx_seq: 7 };
354                // public_position { checkpoint: 42, transaction_index: 3 }.
355                &[
356                    0x28, 0x01, 0x3a, 0x04, 0x08, 0x2a, 0x10, 0x07, 0x4a, 0x04, 0x08, 0x2a, 0x10,
357                    0x03,
358                ],
359                CursorToken::item(Position::Transactions {
360                    tx_seq: 7,
361                    public_position: LedgerPoint::transaction(42, 3),
362                }),
363                &[
364                    0x28, 0x01, 0x3a, 0x02, 0x10, 0x07, 0x4a, 0x04, 0x08, 0x2a, 0x10, 0x03,
365                ],
366            ),
367            (
368                // kind = ITEM; events { 1: 42, tx_seq: 7, event_index: 1 };
369                // public_position { checkpoint: 42, transaction_index: 3, event_index: 1 }.
370                &[
371                    0x28, 0x01, 0x42, 0x06, 0x08, 0x2a, 0x10, 0x07, 0x18, 0x01, 0x4a, 0x06, 0x08,
372                    0x2a, 0x10, 0x03, 0x18, 0x01,
373                ],
374                CursorToken::item(Position::Events {
375                    tx_seq: 7,
376                    event_index: 1,
377                    public_position: LedgerPoint::event(42, 3, 1),
378                }),
379                &[
380                    0x28, 0x01, 0x42, 0x04, 0x10, 0x07, 0x18, 0x01, 0x4a, 0x06, 0x08, 0x2a, 0x10,
381                    0x03, 0x18, 0x01,
382                ],
383            ),
384        ];
385        for (labelled, expected, unlabelled) in cases {
386            let token = CursorToken::decode(labelled).unwrap();
387            assert_eq!(token, expected);
388            assert_eq!(token.encode().as_ref(), unlabelled);
389        }
390    }
391
392    /// A transaction cursor carrying a public `event_index` decodes and encodes without it,
393    /// whatever its kind. An event cursor keeps it.
394    #[test]
395    fn transaction_cursors_drop_a_public_event_index() {
396        for (kind, token) in [
397            (0x01, CursorToken::item as fn(Position) -> CursorToken),
398            (0x02, CursorToken::boundary),
399        ] {
400            // kind; transactions { tx_seq: 42 };
401            // public_position { checkpoint: 7, transaction_index: 3, event_index: 9 }.
402            let forged: &[u8] = &[
403                0x28, kind, 0x3a, 0x02, 0x10, 0x2a, 0x4a, 0x06, 0x08, 0x07, 0x10, 0x03, 0x18, 0x09,
404            ];
405            // The same cursor with public_position { checkpoint: 7, transaction_index: 3 }.
406            let projected: &[u8] = &[
407                0x28, kind, 0x3a, 0x02, 0x10, 0x2a, 0x4a, 0x04, 0x08, 0x07, 0x10, 0x03,
408            ];
409            let decoded = CursorToken::decode(forged).unwrap();
410            assert_eq!(
411                decoded,
412                token(Position::Transactions {
413                    tx_seq: 42,
414                    public_position: LedgerPoint::transaction(7, 3),
415                })
416            );
417            assert_eq!(decoded.encode().as_ref(), projected);
418            let minted = token(Position::Transactions {
419                tx_seq: 42,
420                public_position: LedgerPoint::event(7, 3, 9),
421            });
422            assert_eq!(minted.encode().as_ref(), projected);
423        }
424
425        let event = CursorToken::item(Position::Events {
426            tx_seq: 42,
427            event_index: 9,
428            public_position: LedgerPoint::event(7, 3, 9),
429        });
430        assert_eq!(CursorToken::decode(&event.encode()).unwrap(), event);
431    }
432
433    #[test]
434    fn rejects_transaction_and_event_cursors_without_a_public_position() {
435        let transactions = token_bytes(
436            None,
437            grpc::cursor_token::Position::Transactions(grpc::TransactionsPosition {
438                tx_seq: Some(10),
439            }),
440        );
441        assert!(CursorToken::decode(&transactions).is_err());
442
443        let events = token_bytes(
444            None,
445            grpc::cursor_token::Position::Events(grpc::EventsPosition {
446                tx_seq: Some(10),
447                event_index: Some(3),
448            }),
449        );
450        assert!(CursorToken::decode(&events).is_err());
451    }
452
453    /// A checkpoint cursor's checkpoint is its public position; one it carries is ignored.
454    #[test]
455    fn checkpoint_cursors_ignore_a_public_position() {
456        let bytes = token_bytes(
457            Some(PUBLIC.into()),
458            grpc::cursor_token::Position::Checkpoints(grpc::CheckpointsPosition {
459                checkpoint: Some(5),
460            }),
461        );
462        let token = CursorToken::decode(&bytes).unwrap();
463        assert_eq!(
464            token,
465            CursorToken::item(Position::Checkpoints { checkpoint: 5 })
466        );
467    }
468
469    /// Tokens in the schema that used tags 1-4 decode as a token with no kind or position.
470    #[test]
471    fn rejects_tokens_in_the_reserved_schema() {
472        // query_type = TRANSACTIONS, kind = ITEM, checkpoint = 42, position = 7.
473        let bytes = [0x08, 0x02, 0x10, 0x01, 0x18, 0x2a, 0x20, 0x07];
474        assert!(CursorToken::decode(&bytes).is_err());
475    }
476
477    #[test]
478    fn rejects_unspecified_kind() {
479        let bytes = grpc::CursorToken {
480            kind: grpc::CursorKind::Unspecified as i32,
481            public_position: Some(PUBLIC.into()),
482            position: Some(grpc::cursor_token::Position::Transactions(
483                grpc::TransactionsPosition { tx_seq: Some(2) },
484            )),
485        }
486        .encode_to_vec();
487
488        assert!(CursorToken::decode(&bytes).is_err());
489    }
490
491    #[test]
492    fn rejects_missing_position() {
493        let bytes = grpc::CursorToken {
494            kind: grpc::CursorKind::Item as i32,
495            public_position: Some(grpc::PublicPosition::default()),
496            position: None,
497        }
498        .encode_to_vec();
499
500        assert!(CursorToken::decode(&bytes).is_err());
501    }
502
503    #[test]
504    fn rejects_missing_inner_fields() {
505        let events = token_bytes(
506            Some(PUBLIC.into()),
507            grpc::cursor_token::Position::Events(grpc::EventsPosition {
508                tx_seq: Some(2),
509                event_index: None,
510            }),
511        );
512        assert!(CursorToken::decode(&events).is_err());
513
514        let checkpoints = token_bytes(
515            None,
516            grpc::cursor_token::Position::Checkpoints(grpc::CheckpointsPosition {
517                checkpoint: None,
518            }),
519        );
520        assert!(CursorToken::decode(&checkpoints).is_err());
521    }
522
523    #[test]
524    fn item_resume_is_above_the_key_ascending_and_the_key_descending() {
525        for (item, key, above) in [
526            (
527                Position::Checkpoints { checkpoint: 4 },
528                LedgerPoint::checkpoint_start(4),
529                LedgerPoint::checkpoint_start(5),
530            ),
531            (
532                Position::Transactions {
533                    tx_seq: 9,
534                    public_position: LedgerPoint::transaction(4, 2),
535                },
536                LedgerPoint::transaction(4, 2),
537                LedgerPoint::transaction(4, 3),
538            ),
539            (
540                Position::Events {
541                    tx_seq: 9,
542                    event_index: 1,
543                    public_position: LedgerPoint::event(4, 2, 1),
544                },
545                LedgerPoint::event(4, 2, 1),
546                LedgerPoint::event(4, 2, 2),
547            ),
548        ] {
549            assert_eq!(item.item_resume(ScanDirection::Ascending), above);
550            assert_eq!(item.item_resume(ScanDirection::Descending), key);
551        }
552    }
553
554    /// The lane comes from the cursor position; its own coordinates don't matter.
555    #[test]
556    fn to_ledger_position_sets_only_the_lane_coordinates() {
557        let point = LedgerPoint::event(4, 2, 1);
558        let checkpoint = point.to_ledger_position(&Position::Checkpoints { checkpoint: 0 });
559        assert_eq!(
560            (
561                checkpoint.checkpoint,
562                checkpoint.transaction_index,
563                checkpoint.event_index
564            ),
565            (Some(4), None, None)
566        );
567        let transaction = point.to_ledger_position(&Position::Transactions {
568            tx_seq: 0,
569            public_position: LedgerPoint::GENESIS,
570        });
571        assert_eq!(
572            (
573                transaction.checkpoint,
574                transaction.transaction_index,
575                transaction.event_index
576            ),
577            (Some(4), Some(2), None)
578        );
579        let event = point.to_ledger_position(&Position::Events {
580            tx_seq: 0,
581            event_index: 0,
582            public_position: LedgerPoint::GENESIS,
583        });
584        assert_eq!(
585            (event.checkpoint, event.transaction_index, event.event_index),
586            (Some(4), Some(2), Some(1))
587        );
588    }
589}