Skip to main content

sui_rpc_api/ledger_history/
row_placement.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Placing scan frontiers in public ledger coordinates.
5//!
6//! Every list and subscription frame carries its resume point as a [`LedgerPoint`]
7//! (`Watermark.cursor_position`). Cursors name the same boundaries by `tx_seq`, which stays
8//! private, and carry the public position of their coordinate ([`Position::public_position`]),
9//! so a server places any cursor without a read. A scan frontier is placed by the index row
10//! (checkpoint and position in it) of one transaction the scan already reads: [`RowPlacement`]
11//! says which one, and how its row places the boundary. Checkpoint boundaries, the request's own
12//! fields, and items need no read.
13//!
14//! [`Position::public_position`]: crate::ledger_history::cursor::Position::public_position
15
16use sui_inverted_index::ScanDirection;
17
18use crate::ledger_history::cursor::LedgerPoint;
19use crate::ledger_history::query_options::IntraTxCoordinate;
20
21/// Which transaction's index row places a transaction- or event-lane boundary, and how. A scan
22/// boundary is placed by the transaction on its covered side: ascending, the last transaction
23/// before it (or the transaction it lies inside); descending, the transaction right after it. That
24/// transaction lies in the scanned, indexed part of the ledger whenever the scan reached the
25/// boundary, including a boundary at the indexed tip.
26#[derive(Clone, Copy, Debug, Eq, PartialEq)]
27pub struct RowPlacement {
28    /// The transaction whose row places the boundary.
29    pub tx_seq: u64,
30    /// Whether the boundary lies right after that transaction rather than before one of its
31    /// events.
32    after_transaction: bool,
33    event_index: u32,
34}
35
36impl RowPlacement {
37    /// The placement of the transaction-lane boundary right before `tx_seq`, or `None` for the
38    /// ascending boundary at genesis, which is [`LedgerPoint::GENESIS`]. It is the event-lane
39    /// boundary before the transaction's first event.
40    pub fn transaction_boundary(tx_seq: u64, direction: ScanDirection) -> Option<Self> {
41        Self::event_boundary(IntraTxCoordinate::start_of_tx(tx_seq), direction)
42    }
43
44    /// The placement of the event-lane boundary right before `position`, or `None` for the
45    /// ascending boundary at genesis, which is [`LedgerPoint::GENESIS`].
46    pub fn event_boundary(position: IntraTxCoordinate, direction: ScanDirection) -> Option<Self> {
47        if direction.is_ascending() && position.index == 0 {
48            position.tx_seq.checked_sub(1).map(|tx_seq| Self {
49                tx_seq,
50                after_transaction: true,
51                event_index: 0,
52            })
53        } else {
54            Some(Self {
55                tx_seq: position.tx_seq,
56                after_transaction: false,
57                event_index: position.index,
58            })
59        }
60    }
61
62    /// The boundary, given the checkpoint of [`Self::tx_seq`] and its index in that checkpoint.
63    /// A boundary right after a checkpoint's last transaction keeps that checkpoint, with a
64    /// transaction index past its end.
65    pub fn point(self, checkpoint: u64, transaction_index: u64) -> LedgerPoint {
66        if self.after_transaction {
67            LedgerPoint::transaction(checkpoint, transaction_index + 1)
68        } else {
69            LedgerPoint::event(checkpoint, transaction_index, self.event_index)
70        }
71    }
72}
73
74#[cfg(test)]
75mod tests {
76    use super::*;
77
78    #[test]
79    fn row_placement_reads_the_covered_side() {
80        // Ascending, a transaction boundary is placed after the transaction before it.
81        let placement = RowPlacement::transaction_boundary(10, ScanDirection::Ascending).unwrap();
82        assert_eq!(placement.tx_seq, 9);
83        assert_eq!(placement.point(3, 4), LedgerPoint::transaction(3, 5));
84        assert_eq!(
85            RowPlacement::transaction_boundary(0, ScanDirection::Ascending),
86            None
87        );
88
89        // Descending, before the transaction at the boundary.
90        let placement = RowPlacement::transaction_boundary(10, ScanDirection::Descending).unwrap();
91        assert_eq!(placement.tx_seq, 10);
92        assert_eq!(placement.point(3, 4), LedgerPoint::transaction(3, 4));
93
94        // An event boundary inside a transaction is placed by that transaction either way.
95        let inside = IntraTxCoordinate {
96            tx_seq: 10,
97            index: 2,
98        };
99        for direction in [ScanDirection::Ascending, ScanDirection::Descending] {
100            let placement = RowPlacement::event_boundary(inside, direction).unwrap();
101            assert_eq!(placement.tx_seq, 10);
102            assert_eq!(placement.point(3, 4), LedgerPoint::event(3, 4, 2));
103        }
104
105        // At a transaction's start, ascending reads the transaction before it.
106        let start = IntraTxCoordinate::start_of_tx(10);
107        let placement = RowPlacement::event_boundary(start, ScanDirection::Ascending).unwrap();
108        assert_eq!(placement.tx_seq, 9);
109        assert_eq!(placement.point(3, 4), LedgerPoint::event(3, 5, 0));
110        let placement = RowPlacement::event_boundary(start, ScanDirection::Descending).unwrap();
111        assert_eq!(placement.tx_seq, 10);
112        assert_eq!(placement.point(3, 4), LedgerPoint::event(3, 4, 0));
113        assert_eq!(
114            RowPlacement::event_boundary(
115                IntraTxCoordinate::start_of_tx(0),
116                ScanDirection::Ascending
117            ),
118            None
119        );
120    }
121}