Skip to main content

iota_graphql_rpc/types/
balance.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::str::FromStr;
6
7use async_graphql::{
8    connection::{Connection, CursorType, Edge},
9    *,
10};
11use diesel::{
12    OptionalExtension, QueryableByName,
13    sql_types::{BigInt as SqlBigInt, Nullable, Text},
14};
15use iota_indexer::types::OwnerType;
16use iota_sdk_types::TypeTag;
17use serde::{Deserialize, Serialize};
18
19use crate::{
20    consistency::Checkpointed,
21    data::{Db, DbConnection, QueryExecutor},
22    error::Error,
23    filter, query,
24    raw_query::RawQuery,
25    types::{
26        available_range::AvailableRange,
27        big_int::BigInt,
28        cursor::{self, Page, RawPaginated, ScanLimited, Target},
29        iota_address::IotaAddress,
30        move_type::MoveType,
31        uint53::UInt53,
32    },
33};
34
35/// The total balance for a particular coin type.
36#[derive(Clone, Debug, SimpleObject)]
37pub(crate) struct Balance {
38    /// Coin type for the balance, such as 0x2::iota::IOTA
39    pub(crate) coin_type: MoveType,
40    /// How many coins of this type constitute the balance
41    pub(crate) coin_object_count: Option<UInt53>,
42    /// Total balance across all coin objects of the coin type
43    pub(crate) total_balance: Option<BigInt>,
44}
45
46/// Representation of a row of balance information from the DB. We read the
47/// balance as a `String` to deal with the large (bigger than 2^63 - 1)
48/// balances.
49#[derive(QueryableByName)]
50pub struct StoredBalance {
51    #[diesel(sql_type = Nullable<Text>)]
52    pub balance: Option<String>,
53    #[diesel(sql_type = Nullable<SqlBigInt>)]
54    pub count: Option<i64>,
55    #[diesel(sql_type = Text)]
56    pub coin_type: String,
57}
58
59pub(crate) type Cursor = cursor::JsonCursor<BalanceCursor>;
60
61/// The inner struct for the `Balance`'s cursor. The `coin_type` is used as the
62/// cursor, while the `checkpoint_viewed_at` sets the consistent upper bound for
63/// the cursor.
64#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug)]
65pub(crate) struct BalanceCursor {
66    #[serde(rename = "t")]
67    coin_type: String,
68    /// The checkpoint sequence number this was viewed at.
69    #[serde(rename = "c")]
70    checkpoint_viewed_at: UInt53,
71}
72
73impl Balance {
74    /// Query for the balance of coins owned by `address`, of coins with type
75    /// `coin_type`. Note that `coin_type` is the type of
76    /// `0x2::coin::Coin`'s type parameter, not the full type of the coin
77    /// object.
78    pub(crate) async fn query(
79        db: &Db,
80        address: IotaAddress,
81        coin_type: TypeTag,
82        checkpoint_viewed_at: u64,
83    ) -> Result<Option<Balance>, Error> {
84        let max_available_range = db.max_available_range;
85        let stored: Option<StoredBalance> = db
86            .execute_repeatable(move |conn| {
87                if !AvailableRange::is_checkpoint_in_backward_history_range(
88                    conn,
89                    checkpoint_viewed_at,
90                    max_available_range,
91                )? {
92                    return Ok::<_, diesel::result::Error>(None);
93                }
94
95                conn.result(move || {
96                    balance_query(address, Some(coin_type.clone()), checkpoint_viewed_at)
97                        .into_boxed()
98                })
99                .optional()
100            })
101            .await?;
102
103        stored.map(Balance::try_from).transpose()
104    }
105
106    /// Query the database for a `page` of coin balances. Each balance
107    /// represents the total balance for a particular coin type, owned by
108    /// `address`.
109    pub(crate) async fn paginate(
110        db: &Db,
111        page: Page<Cursor>,
112        address: IotaAddress,
113        checkpoint_viewed_at: u64,
114    ) -> Result<Connection<String, Balance>, Error> {
115        // If cursors are provided, defer to the `checkpoint_viewed_at` in the cursor if
116        // they are consistent. Otherwise, use the value from the parameter, or
117        // set to None. This is so that paginated queries are consistent with
118        // the previous query that created the cursor.
119        let cursor_viewed_at = page.validate_cursor_consistency()?;
120        let checkpoint_viewed_at = cursor_viewed_at.unwrap_or(checkpoint_viewed_at);
121
122        let max_available_range = db.max_available_range;
123
124        let Some((prev, next, results)) = db
125            .execute_repeatable(move |conn| {
126                if !AvailableRange::is_checkpoint_in_backward_history_range(
127                    conn,
128                    checkpoint_viewed_at,
129                    max_available_range,
130                )? {
131                    return Ok::<_, diesel::result::Error>(None);
132                }
133
134                let result = page.paginate_raw_query::<StoredBalance>(
135                    conn,
136                    checkpoint_viewed_at,
137                    balance_query(address, None, checkpoint_viewed_at),
138                )?;
139
140                Ok(Some(result))
141            })
142            .await?
143        else {
144            return Err(Error::Client(
145                "Requested data is outside the available range".to_string(),
146            ));
147        };
148
149        let mut conn = Connection::new(prev, next);
150        for stored in results {
151            let cursor = stored.cursor(checkpoint_viewed_at).encode_cursor();
152            let balance = Balance::try_from(stored)?;
153            conn.edges.push(Edge::new(cursor, balance));
154        }
155
156        Ok(conn)
157    }
158}
159
160impl RawPaginated<Cursor> for StoredBalance {
161    fn filter_ge(cursor: &Cursor, query: RawQuery) -> RawQuery {
162        filter!(query, "coin_type >= {}", cursor.coin_type.clone())
163    }
164
165    fn filter_le(cursor: &Cursor, query: RawQuery) -> RawQuery {
166        filter!(query, "coin_type <= {}", cursor.coin_type.clone())
167    }
168
169    fn order(asc: bool, query: RawQuery) -> RawQuery {
170        if asc {
171            return query.order_by("coin_type ASC");
172        }
173        query.order_by("coin_type DESC")
174    }
175}
176
177impl Target<Cursor> for StoredBalance {
178    fn cursor(&self, checkpoint_viewed_at: u64) -> Cursor {
179        Cursor::new(BalanceCursor {
180            coin_type: self.coin_type.clone(),
181            checkpoint_viewed_at: UInt53::new_unchecked(checkpoint_viewed_at),
182        })
183    }
184}
185
186impl Checkpointed for Cursor {
187    fn checkpoint_viewed_at(&self) -> u64 {
188        self.checkpoint_viewed_at.into()
189    }
190}
191
192impl ScanLimited for Cursor {}
193
194impl TryFrom<StoredBalance> for Balance {
195    type Error = Error;
196
197    fn try_from(s: StoredBalance) -> Result<Self, Error> {
198        let StoredBalance {
199            balance,
200            count,
201            coin_type,
202        } = s;
203        let total_balance = balance
204            .map(|b| BigInt::from_str(&b))
205            .transpose()
206            .map_err(|_| Error::Internal("Failed to read balance.".to_string()))?;
207
208        let coin_object_count = count.map(|c| UInt53::try_from(c as u64)).transpose()?;
209
210        let coin_type = TypeTag::from_str(&coin_type)
211            .map_err(|e| Error::Internal(format!("Failed to parse coin type: {e}")))?
212            .into();
213
214        Ok(Balance {
215            coin_type,
216            coin_object_count,
217            total_balance,
218        })
219    }
220}
221
222/// Builds the aggregating SQL that totals each coin type's balance for
223/// `address` at `checkpoint_viewed_at`, using the backward-diff tables.
224///
225/// The consistent set of objects at `checkpoint_viewed_at` is the union of two
226/// disjoint sources:
227///
228/// * Source A — `checkpointed_objects` rows for objects that have not changed since
229///   `checkpoint_viewed_at` (no `objects_backward_history` entry with `superseded_at_checkpoint >
230///   checkpoint_viewed_at`).
231/// * Source B — `objects_backward_history` rows for the version of each object current at
232///   `checkpoint_viewed_at`: the earliest version whose `superseded_at_checkpoint >
233///   checkpoint_viewed_at`. Synthetic rows (`NotYetCreated`, `WrappedOrDeleted`) drop out
234///   automatically — they carry NULL `owner_id`/`coin_type`, so the owner+coin filter excludes
235///   them.
236///
237/// Each object can match at most one source: A only returns objects that
238/// did not change after `checkpoint_viewed_at`, while B only returns objects
239/// that did. So `UNION ALL` already gives one row per `object_id` — no
240/// dedup needed before aggregation.
241fn balance_query(
242    address: IotaAddress,
243    coin_type: Option<TypeTag>,
244    checkpoint_viewed_at: u64,
245) -> RawQuery {
246    let checkpoint_viewed_at = checkpoint_viewed_at as i64;
247
248    let checkpointed = filter(
249        query!("SELECT object_id, coin_balance, coin_type FROM checkpointed_objects"),
250        address,
251        coin_type.clone(),
252    );
253    // Keep a candidate when its newest version was superseded at or before the
254    // checkpoint; see `consistent_checkpointed_objects` for the rationale.
255    let source_a = filter!(
256        query!(
257            "SELECT candidates.object_id, candidates.coin_balance, candidates.coin_type \
258             FROM ({}) candidates \
259             LEFT JOIN LATERAL (\
260                 SELECT changed.superseded_at_checkpoint \
261                 FROM objects_backward_history changed \
262                 WHERE changed.object_id = candidates.object_id \
263                 ORDER BY changed.object_version DESC \
264                 LIMIT 1\
265             ) latest ON true",
266            checkpointed
267        ),
268        format!(
269            "(latest.superseded_at_checkpoint IS NULL \
270              OR latest.superseded_at_checkpoint <= {checkpoint_viewed_at})"
271        )
272    );
273
274    // Distinct object_ids matching the owner/coin filter that changed after the
275    // checkpoint. The filtered columns are indexed on objects_backward_history, so
276    // this scans only matching coins.
277    let candidate_ids = filter!(
278        filter(
279            query!("SELECT DISTINCT object_id FROM objects_backward_history"),
280            address,
281            coin_type.clone(),
282        ),
283        format!("superseded_at_checkpoint > {checkpoint_viewed_at}")
284    );
285    let (candidate_ids_sql, binds) = candidate_ids.finish();
286
287    // The newest version already superseded by the checkpoint; the live version
288    // is the next one after it.
289    let newest_superseded = format!(
290        "SELECT superseded.object_version \
291         FROM objects_backward_history superseded \
292         WHERE superseded.object_id = candidate_ids.object_id \
293           AND superseded.superseded_at_checkpoint <= {checkpoint_viewed_at} \
294         ORDER BY superseded.object_version DESC \
295         LIMIT 1"
296    );
297
298    // For each candidate, fetch the version that was live at the checkpoint: the
299    // earliest one not yet superseded. A LATERAL join fetches that row per
300    // object_id. See `consistent::consistent_historical_objects` for the full
301    // rationale.
302    let live_rows = RawQuery::new(
303        format!(
304            "SELECT object_id, coin_balance, coin_type, owner_id, owner_type \
305             FROM ( \
306                 SELECT live.* \
307                 FROM ({candidate_ids_sql}) candidate_ids \
308                 CROSS JOIN LATERAL ( \
309                     SELECT objects_backward_history.* \
310                     FROM objects_backward_history \
311                     WHERE objects_backward_history.object_id = candidate_ids.object_id \
312                       AND objects_backward_history.object_version > COALESCE(({newest_superseded}), -1) \
313                     ORDER BY objects_backward_history.object_version ASC \
314                     LIMIT 1 \
315                 ) live \
316             ) AS objects_backward_history"
317        ),
318        binds,
319    );
320
321    // A coin is in candidate_ids if any of its versions superseded after the
322    // checkpoint matched the owner/coin filter, but the version live at the
323    // checkpoint might not. Re-apply the filter to drop those.
324    let source_b = query!(
325        "SELECT candidates.object_id, candidates.coin_balance, candidates.coin_type \
326         FROM ({}) candidates",
327        filter(live_rows, address, coin_type)
328    );
329
330    query!(
331        r#"SELECT
332            CAST(SUM(coin_balance) AS TEXT) as balance,
333            COUNT(*) as count,
334            coin_type
335        FROM (({}) UNION ALL ({})) candidates"#,
336        source_a,
337        source_b
338    )
339    .group_by("coin_type")
340}
341
342/// Applies the filtering criteria for balances to the input `RawQuery` and
343/// returns a new `RawQuery`.
344fn filter(mut query: RawQuery, owner: IotaAddress, coin_type: Option<TypeTag>) -> RawQuery {
345    query = filter!(
346        query,
347        format!(
348            "owner_id = '\\x{}'::bytea AND owner_type = {}",
349            hex::encode(owner.into_vec()),
350            OwnerType::Address as i16
351        )
352    );
353
354    if let Some(coin_type) = coin_type {
355        // `coin_type = X` already implies NOT NULL, so only add the
356        // `coin_type IS NOT NULL` filter in the else branch (listing all coins),
357        // to avoid two filters on `coin_type` here, which made the planner pick worse
358        // plans. (planner incorrectly assumes that `coin_type = X AND coin_type
359        // IS NOT NULL` will match less data than just `coin_type = X`)
360        query = filter!(
361            query,
362            "coin_type = {}",
363            coin_type.to_canonical_string(/* with_prefix */ true)
364        );
365    } else {
366        query = filter!(query, "coin_type IS NOT NULL");
367    };
368
369    query
370}