Add ConsensusV2 object support to sui-indexer{,alt} (#20486)

Updates `sum_coin_balances` and `wal_coin_balances` tables to add a
column for `coin_owner_kind`, so that balances can be tracked separately
for fastpath vs. consensus coins.

---

## Release notes

Check each box that your changes affect. If none of the boxes relate to
your changes, release notes aren't required.

For each box you select, include information after the relevant heading
that describes the impact of your changes that a user might notice and
any actions they must take to implement updates.

- [ ] Protocol: 
- [ ] Nodes (Validators and Full nodes): 
- [x] Indexer: Adds `coin_owner_kind` column to coin balances tables. 
- [ ] JSON-RPC: 
- [ ] GraphQL: 
- [ ] CLI: 
- [ ] Rust SDK:
- [ ] REST API:

crates/sui-indexer-alt/migrations/2024-10-27-150938_sum_obj_types/up.sql

@@ -17,6 +17,11 @@ CREATE TABLE IF NOT EXISTS sum_obj_types
     -- another object (kind 2), which relates to dynamic fields, and an object
     -- that is owned by another object's address (kind 1), which relates to
     -- transfer-to-object.
+    --
+    -- Warning: This column may look similar to the concept of "ObjectOwner"
+    -- but is NOT the same. For purposes of determining owner_kind, ConsensusV2
+    -- objects are mapped onto the variants described above based on their
+    -- authenticator.
     owner_kind                  SMALLINT      NOT NULL,
     -- The address for address-owned objects, and the parent object for
     -- object-owned objects.

crates/sui-indexer-alt/migrations/2024-10-28-144002_sum_coin_balances/up.sql

@@ -6,8 +6,7 @@ CREATE TABLE IF NOT EXISTS sum_coin_balances
 (
     object_id                   BYTEA         PRIMARY KEY,
     object_version              BIGINT        NOT NULL,
-    -- The address that owns this version of the coin (it is guaranteed to be
-    -- address-owned).
+    -- The address that owns this version of the coin.
     owner_id                    BYTEA         NOT NULL,
     -- The type of the coin, as a BCS-serialized `TypeTag`. This is only the
     -- marker type, and not the full object type (e.g. `0x0...02::sui::SUI`).

crates/sui-indexer-alt/migrations/2024-11-25-211949_obj_info/up.sql

@@ -21,6 +21,11 @@ CREATE TABLE IF NOT EXISTS obj_info
     -- another object (kind 2), which relates to dynamic fields, and an object
     -- that is owned by another object's address (kind 1), which relates to
     -- transfer-to-object.
+    --
+    -- Warning: This column may look similar to the concept of "ObjectOwner"
+    -- but is NOT the same. For purposes of determining owner_kind, ConsensusV2
+    -- objects are mapped onto the variants described above based on their
+    -- authenticator.
     owner_kind                  SMALLINT,
     -- The address for address-owned objects, and the parent object for
     -- object-owned objects.

crates/sui-indexer-alt/migrations/2024-12-02-185822_add_coin_balance_owner_kind/down.sql

@@ -0,0 +1,5 @@
+ALTER TABLE sum_coin_balances
+DROP COLUMN owner_kind;
+
+ALTER TABLE wal_coin_balances
+DROP COLUMN owner_kind;

crates/sui-indexer-alt/migrations/2024-12-02-185822_add_coin_balance_owner_kind/metadata.toml

@@ -0,0 +1 @@
+run_in_transaction = false

crates/sui-indexer-alt/migrations/2024-12-02-185822_add_coin_balance_owner_kind/up.sql

@@ -0,0 +1,6 @@
+ALTER TABLE sum_coin_balances
+ADD COLUMN coin_owner_kind SMALLINT NOT NULL DEFAULT 1;
+
+ALTER TABLE wal_coin_balances
+ADD COLUMN coin_owner_kind SMALLINT;
+UPDATE wal_coin_balances SET coin_owner_kind = 1 WHERE owner_id IS NOT NULL;

crates/sui-indexer-alt/migrations/2024-12-05-153042_add_coin_balance_owner_kind_indexes/down.sql

@@ -0,0 +1,2 @@
+CREATE INDEX CONCURRENTLY IF NOT EXISTS sum_coin_balances_owner_type
+ON sum_coin_balances (owner_id, coin_type, coin_balance, object_id, object_version);

crates/sui-indexer-alt/migrations/2024-12-05-153042_add_coin_balance_owner_kind_indexes/metadata.toml

@@ -0,0 +1 @@
+run_in_transaction = false

crates/sui-indexer-alt/migrations/2024-12-05-153042_add_coin_balance_owner_kind_indexes/up.sql

@@ -0,0 +1 @@
+DROP INDEX CONCURRENTLY IF EXISTS sum_coin_balances_owner_type;

crates/sui-indexer-alt/migrations/2024-12-05-162242_add_coin_balance_owner_kind_indexes/down.sql

@@ -0,0 +1 @@
+DROP INDEX CONCURRENTLY IF EXISTS sum_coin_balances_owner_kind_owner_id_type;

crates/sui-indexer-alt/migrations/2024-12-05-162242_add_coin_balance_owner_kind_indexes/metadata.toml

@@ -0,0 +1 @@
+run_in_transaction = false

crates/sui-indexer-alt/migrations/2024-12-05-162242_add_coin_balance_owner_kind_indexes/up.sql

@@ -0,0 +1,2 @@
+CREATE INDEX CONCURRENTLY IF NOT EXISTS sum_coin_balances_owner_kind_owner_id_type
+ON sum_coin_balances (coin_owner_kind, owner_id, coin_type, coin_balance, object_id, object_version);

crates/sui-indexer-alt/migrations/2024-12-05-162243_add_coin_balance_owner_kind_indexes/down.sql

@@ -0,0 +1,2 @@
+CREATE INDEX CONCURRENTLY IF NOT EXISTS wal_coin_balances_owner_type
+ON wal_coin_balances (owner_id, coin_type, coin_balance, object_id, object_version);

crates/sui-indexer-alt/migrations/2024-12-05-162243_add_coin_balance_owner_kind_indexes/metadata.toml

@@ -0,0 +1 @@
+run_in_transaction = false

crates/sui-indexer-alt/migrations/2024-12-05-162243_add_coin_balance_owner_kind_indexes/up.sql

@@ -0,0 +1 @@
+DROP INDEX CONCURRENTLY IF EXISTS wal_coin_balances_owner_type;

crates/sui-indexer-alt/migrations/2024-12-05-162244_add_coin_balance_owner_kind_indexes/down.sql

@@ -0,0 +1 @@
+DROP INDEX CONCURRENTLY IF EXISTS wal_coin_balances_owner_kind_owner_id_type;

crates/sui-indexer-alt/migrations/2024-12-05-162244_add_coin_balance_owner_kind_indexes/metadata.toml

@@ -0,0 +1 @@
+run_in_transaction = false

crates/sui-indexer-alt/migrations/2024-12-05-162244_add_coin_balance_owner_kind_indexes/up.sql

@@ -0,0 +1,2 @@
+CREATE INDEX CONCURRENTLY IF NOT EXISTS wal_coin_balances_owner_kind_owner_id_type
+ON wal_coin_balances (coin_owner_kind, owner_id, coin_type, coin_balance, object_id, object_version);

crates/sui-indexer-alt/src/handlers/sum_coin_balances.rs

@@ -21,7 +21,7 @@ use sui_types::{
 };
 
 use crate::{
-    models::objects::{StoredObjectUpdate, StoredSumCoinBalance},
+    models::objects::{StoredCoinOwnerKind, StoredObjectUpdate, StoredSumCoinBalance},
     schema::sum_coin_balances,
 };
 
@@ -98,9 +98,17 @@ impl Processor for SumCoinBalances {
                     continue;
                 };
 
-                // Coin balance only tracks address-owned objects
-                let Owner::AddressOwner(owner_id) = object.owner() else {
-                    continue;
+                // Coin balance only tracks address-owned or ConsensusV2 objects
+                let (coin_owner_kind, owner_id) = match object.owner() {
+                    Owner::AddressOwner(owner_id) => (StoredCoinOwnerKind::Fastpath, owner_id),
+                    // ConsensusV2 objects are treated as address-owned for now in indexers.
+                    // This will need to be updated if additional Authenticators are added.
+                    Owner::ConsensusV2 { authenticator, .. } => (
+                        StoredCoinOwnerKind::Consensus,
+                        authenticator.as_single_owner(),
+                    ),
+
+                    Owner::Immutable | Owner::ObjectOwner(_) | Owner::Shared { .. } => continue,
                 };
 
                 let Some(coin) = object.as_coin_maybe() else {
@@ -123,6 +131,7 @@ impl Processor for SumCoinBalances {
                                 owner_id: owner_id.to_vec(),
                                 coin_type: coin_type.clone(),
                                 coin_balance: coin.balance.value() as i64,
+                                coin_owner_kind,
                             }),
                         });
                     }
@@ -172,6 +181,8 @@ impl Handler for SumCoinBalances {
                         sum_coin_balances::owner_id.eq(excluded(sum_coin_balances::owner_id)),
                         sum_coin_balances::coin_balance
                             .eq(excluded(sum_coin_balances::coin_balance)),
+                        sum_coin_balances::coin_owner_kind
+                            .eq(excluded(sum_coin_balances::coin_owner_kind)),
                     ))
                     .execute(conn),
             ),

crates/sui-indexer-alt/src/handlers/sum_obj_types.rs

@@ -98,8 +98,9 @@ impl Processor for SumObjTypes {
                                     Owner::ObjectOwner(_) => StoredOwnerKind::Object,
                                     Owner::Shared { .. } => StoredOwnerKind::Shared,
                                     Owner::Immutable => StoredOwnerKind::Immutable,
-                                    // TODO: Implement support for ConsensusV2 objects.
-                                    Owner::ConsensusV2 { .. } => todo!(),
+                                    // ConsensusV2 objects are treated as address-owned for now in indexers.
+                                    // This will need to be updated if additional Authenticators are added.
+                                    Owner::ConsensusV2 { .. } => StoredOwnerKind::Address,
                                 },
 
                                 owner_id: match object.owner() {

crates/sui-indexer-alt/src/handlers/wal_coin_balances.rs

@@ -49,6 +49,8 @@ impl Handler for WalCoinBalances {
                 coin_balance: value.update.as_ref().map(|o| o.coin_balance),
 
                 cp_sequence_number: value.cp_sequence_number as i64,
+
+                coin_owner_kind: value.update.as_ref().map(|o| o.coin_owner_kind),
             })
             .collect();
 

crates/sui-indexer-alt/src/models/objects.rs

@@ -51,6 +51,14 @@ pub enum StoredOwnerKind {
     Shared = 3,
 }
 
+#[derive(AsExpression, FromSqlRow, Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+#[diesel(sql_type = SmallInt)]
+#[repr(i16)]
+pub enum StoredCoinOwnerKind {
+    Fastpath = 0,
+    Consensus = 1,
+}
+
 #[derive(Insertable, Debug, Clone, FieldCount)]
 #[diesel(table_name = sum_coin_balances, primary_key(object_id))]
 pub struct StoredSumCoinBalance {
@@ -59,6 +67,7 @@ pub struct StoredSumCoinBalance {
     pub owner_id: Vec<u8>,
     pub coin_type: Vec<u8>,
     pub coin_balance: i64,
+    pub coin_owner_kind: StoredCoinOwnerKind,
 }
 
 #[derive(Insertable, Debug, Clone, FieldCount)]
@@ -83,6 +92,7 @@ pub struct StoredWalCoinBalance {
     pub coin_type: Option<Vec<u8>>,
     pub coin_balance: Option<i64>,
     pub cp_sequence_number: i64,
+    pub coin_owner_kind: Option<StoredCoinOwnerKind>,
 }
 
 #[derive(Insertable, Debug, Clone)]
@@ -133,6 +143,31 @@ where
     }
 }
 
+impl<DB: Backend> serialize::ToSql<SmallInt, DB> for StoredCoinOwnerKind
+where
+    i16: serialize::ToSql<SmallInt, DB>,
+{
+    fn to_sql<'b>(&'b self, out: &mut serialize::Output<'b, '_, DB>) -> serialize::Result {
+        match self {
+            StoredCoinOwnerKind::Fastpath => 0.to_sql(out),
+            StoredCoinOwnerKind::Consensus => 1.to_sql(out),
+        }
+    }
+}
+
+impl<DB: Backend> deserialize::FromSql<SmallInt, DB> for StoredCoinOwnerKind
+where
+    i16: deserialize::FromSql<SmallInt, DB>,
+{
+    fn from_sql(raw: DB::RawValue<'_>) -> deserialize::Result<Self> {
+        Ok(match i16::from_sql(raw)? {
+            0 => StoredCoinOwnerKind::Fastpath,
+            1 => StoredCoinOwnerKind::Consensus,
+            o => return Err(format!("Unexpected StoredCoinOwnerKind: {o}").into()),
+        })
+    }
+}
+
 #[derive(Insertable, Debug, Clone, FieldCount)]
 #[diesel(table_name = obj_info, primary_key(object_id, cp_sequence_number))]
 pub struct StoredObjInfo {

crates/sui-indexer-alt/src/schema.rs

@@ -132,6 +132,7 @@ diesel::table! {
         owner_id -> Bytea,
         coin_type -> Bytea,
         coin_balance -> Int8,
+        coin_owner_kind -> Int2,
     }
 }
 
@@ -222,6 +223,7 @@ diesel::table! {
         coin_type -> Nullable<Bytea>,
         coin_balance -> Nullable<Int8>,
         cp_sequence_number -> Int8,
+        coin_owner_kind -> Nullable<Int2>,
     }
 }
 

crates/sui-indexer/src/types.rs

@@ -254,8 +254,11 @@ pub fn owner_to_owner_info(owner: &Owner) -> (OwnerType, Option<SuiAddress>) {
         Owner::ObjectOwner(address) => (OwnerType::Object, Some(*address)),
         Owner::Shared { .. } => (OwnerType::Shared, None),
         Owner::Immutable => (OwnerType::Immutable, None),
-        // TODO: Implement support for ConsensusV2 objects.
-        Owner::ConsensusV2 { .. } => todo!(),
+        // ConsensusV2 objects are treated as singly-owned for now in indexers.
+        // This will need to be updated if additional Authenticators are added.
+        Owner::ConsensusV2 { authenticator, .. } => {
+            (OwnerType::Address, Some(*authenticator.as_single_owner()))
+        }
     }
 }
 

crates/sui-mvr-indexer/src/types.rs

@@ -254,8 +254,11 @@ pub fn owner_to_owner_info(owner: &Owner) -> (OwnerType, Option<SuiAddress>) {
         Owner::ObjectOwner(address) => (OwnerType::Object, Some(*address)),
         Owner::Shared { .. } => (OwnerType::Shared, None),
         Owner::Immutable => (OwnerType::Immutable, None),
-        // TODO: Implement support for ConsensusV2 objects.
-        Owner::ConsensusV2 { .. } => todo!(),
+        // ConsensusV2 objects are treated as singly-owned for now in indexers.
+        // This will need to be updated if additional Authenticators are added.
+        Owner::ConsensusV2 { authenticator, .. } => {
+            (OwnerType::Address, Some(*authenticator.as_single_owner()))
+        }
     }
 }