0.7.15

kb_lib/src/db/dtos.rs

@@ -27,6 +27,8 @@ mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
+mod wallet;
+mod wallet_participation;
 
 pub use analysis_signal::KbAnalysisSignalDto;
 pub use chain_instruction::KbChainInstructionDto;
@@ -53,3 +55,5 @@ pub use swap::KbSwapDto;
 pub use token::KbTokenDto;
 pub use token_burn_event::KbTokenBurnEventDto;
 pub use token_mint_event::KbTokenMintEventDto;
+pub use wallet::KbWalletDto;
+pub use wallet_participation::KbWalletParticipationDto;

kb_lib/src/db/dtos/wallet.rs

@@ -0,0 +1,69 @@
+// file: kb_lib/src/db/dtos/wallet.rs
+
+//! Wallet DTO.
+
+/// Application-facing wallet DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct KbWalletDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Stable wallet address.
+    pub address: std::string::String,
+    /// Optional user-defined label.
+    pub label: std::option::Option<std::string::String>,
+    /// Creation timestamp.
+    pub first_seen_at: chrono::DateTime<chrono::Utc>,
+    /// Update timestamp.
+    pub last_seen_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl KbWalletDto {
+    /// Creates a new wallet DTO.
+    pub fn new(
+        address: std::string::String,
+        label: std::option::Option<std::string::String>,
+    ) -> Self {
+        let now = chrono::Utc::now();
+        Self {
+            id: None,
+            address,
+            label,
+            first_seen_at: now,
+            last_seen_at: now,
+        }
+    }
+}
+
+impl TryFrom<crate::KbWalletEntity> for KbWalletDto {
+    type Error = crate::KbError;
+
+    fn try_from(entity: crate::KbWalletEntity) -> Result<Self, Self::Error> {
+        let first_seen_at_result = chrono::DateTime::parse_from_rfc3339(&entity.first_seen_at);
+        let first_seen_at = match first_seen_at_result {
+            Ok(first_seen_at) => first_seen_at.with_timezone(&chrono::Utc),
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot parse wallet first_seen_at '{}': {}",
+                    entity.first_seen_at, error
+                )));
+            }
+        };
+        let last_seen_at_result = chrono::DateTime::parse_from_rfc3339(&entity.last_seen_at);
+        let last_seen_at = match last_seen_at_result {
+            Ok(last_seen_at) => last_seen_at.with_timezone(&chrono::Utc),
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot parse wallet last_seen_at '{}': {}",
+                    entity.last_seen_at, error
+                )));
+            }
+        };
+        Ok(Self {
+            id: Some(entity.id),
+            address: entity.address,
+            label: entity.label,
+            first_seen_at,
+            last_seen_at,
+        })
+    }
+}

kb_lib/src/db/dtos/wallet_participation.rs

@@ -0,0 +1,134 @@
+// file: kb_lib/src/db/dtos/wallet_participation.rs
+
+//! Wallet-participation DTO.
+
+/// Application-facing wallet-participation DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct KbWalletParticipationDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Related wallet id.
+    pub wallet_id: i64,
+    /// Related transaction id.
+    pub transaction_id: i64,
+    /// Optional related decoded event id.
+    pub decoded_event_id: std::option::Option<i64>,
+    /// Optional related pool id.
+    pub pool_id: std::option::Option<i64>,
+    /// Optional related pair id.
+    pub pair_id: std::option::Option<i64>,
+    /// Stable participation role.
+    pub role: std::string::String,
+    /// Stable unique key used for idempotent upserts.
+    pub unique_key: std::string::String,
+    /// Observation source kind.
+    pub source_kind: crate::KbObservationSourceKind,
+    /// Optional logical source endpoint name.
+    pub source_endpoint_name: std::option::Option<std::string::String>,
+    /// Creation timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl KbWalletParticipationDto {
+    /// Creates a new wallet-participation DTO.
+    pub fn new(
+        wallet_id: i64,
+        transaction_id: i64,
+        decoded_event_id: std::option::Option<i64>,
+        pool_id: std::option::Option<i64>,
+        pair_id: std::option::Option<i64>,
+        role: std::string::String,
+        source_kind: crate::KbObservationSourceKind,
+        source_endpoint_name: std::option::Option<std::string::String>,
+    ) -> Self {
+        let now = chrono::Utc::now();
+        let unique_key = kb_build_wallet_participation_unique_key(
+            wallet_id,
+            transaction_id,
+            decoded_event_id,
+            pool_id,
+            pair_id,
+            role.as_str(),
+        );
+
+        Self {
+            id: None,
+            wallet_id,
+            transaction_id,
+            decoded_event_id,
+            pool_id,
+            pair_id,
+            role,
+            unique_key,
+            source_kind,
+            source_endpoint_name,
+            created_at: now,
+            updated_at: now,
+        }
+    }
+}
+
+impl TryFrom<crate::KbWalletParticipationEntity> for KbWalletParticipationDto {
+    type Error = crate::KbError;
+
+    fn try_from(entity: crate::KbWalletParticipationEntity) -> Result<Self, Self::Error> {
+        let source_kind_result = crate::KbObservationSourceKind::from_i16(entity.source_kind);
+        let source_kind = match source_kind_result {
+            Ok(source_kind) => source_kind,
+            Err(error) => return Err(error),
+        };
+        let created_at_result = chrono::DateTime::parse_from_rfc3339(&entity.created_at);
+        let created_at = match created_at_result {
+            Ok(created_at) => created_at.with_timezone(&chrono::Utc),
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot parse wallet_participation created_at '{}': {}",
+                    entity.created_at, error
+                )));
+            }
+        };
+        let updated_at_result = chrono::DateTime::parse_from_rfc3339(&entity.updated_at);
+        let updated_at = match updated_at_result {
+            Ok(updated_at) => updated_at.with_timezone(&chrono::Utc),
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot parse wallet_participation updated_at '{}': {}",
+                    entity.updated_at, error
+                )));
+            }
+        };
+        Ok(Self {
+            id: Some(entity.id),
+            wallet_id: entity.wallet_id,
+            transaction_id: entity.transaction_id,
+            decoded_event_id: entity.decoded_event_id,
+            pool_id: entity.pool_id,
+            pair_id: entity.pair_id,
+            role: entity.role,
+            unique_key: entity.unique_key,
+            source_kind,
+            source_endpoint_name: entity.source_endpoint_name,
+            created_at,
+            updated_at,
+        })
+    }
+}
+
+fn kb_build_wallet_participation_unique_key(
+    wallet_id: i64,
+    transaction_id: i64,
+    decoded_event_id: std::option::Option<i64>,
+    pool_id: std::option::Option<i64>,
+    pair_id: std::option::Option<i64>,
+    role: &str,
+) -> std::string::String {
+    let decoded_event_id_value = decoded_event_id.unwrap_or_default();
+    let pool_id_value = pool_id.unwrap_or_default();
+    let pair_id_value = pair_id.unwrap_or_default();
+    format!(
+        "{}:{}:{}:{}:{}:{}",
+        wallet_id, transaction_id, decoded_event_id_value, pool_id_value, pair_id_value, role
+    )
+}

kb_lib/src/db/entities.rs

@@ -29,6 +29,8 @@ mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
+mod wallet;
+mod wallet_participation;
 
 pub use analysis_signal::KbAnalysisSignalEntity;
 pub use chain_instruction::KbChainInstructionEntity;
@@ -55,3 +57,5 @@ pub use swap::KbSwapEntity;
 pub use token::KbTokenEntity;
 pub use token_burn_event::KbTokenBurnEventEntity;
 pub use token_mint_event::KbTokenMintEventEntity;
+pub use wallet::KbWalletEntity;
+pub use wallet_participation::KbWalletParticipationEntity;

kb_lib/src/db/entities/wallet.rs

@@ -0,0 +1,18 @@
+// file: kb_lib/src/db/entities/wallet.rs
+
+//! Wallet entity.
+
+/// Persisted wallet row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct KbWalletEntity {
+    /// Numeric primary key.
+    pub id: i64,
+    /// Stable wallet address.
+    pub address: std::string::String,
+    /// Optional user-defined label.
+    pub label: std::option::Option<std::string::String>,
+    /// Creation timestamp encoded as RFC3339 UTC text.
+    pub first_seen_at: std::string::String,
+    /// Update timestamp encoded as RFC3339 UTC text.
+    pub last_seen_at: std::string::String,
+}

kb_lib/src/db/entities/wallet_participation.rs

@@ -0,0 +1,32 @@
+// file: kb_lib/src/db/entities/wallet_participation.rs
+
+//! Wallet-participation entity.
+
+/// Persisted wallet-participation row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct KbWalletParticipationEntity {
+    /// Numeric primary key.
+    pub id: i64,
+    /// Related wallet id.
+    pub wallet_id: i64,
+    /// Related transaction id.
+    pub transaction_id: i64,
+    /// Optional related decoded event id.
+    pub decoded_event_id: std::option::Option<i64>,
+    /// Optional related pool id.
+    pub pool_id: std::option::Option<i64>,
+    /// Optional related pair id.
+    pub pair_id: std::option::Option<i64>,
+    /// Stable participation role.
+    pub role: std::string::String,
+    /// Stable unique key used for idempotent upserts.
+    pub unique_key: std::string::String,
+    /// Observation source kind.
+    pub source_kind: i16,
+    /// Optional logical source endpoint name.
+    pub source_endpoint_name: std::option::Option<std::string::String>,
+    /// Creation timestamp encoded as RFC3339 UTC text.
+    pub created_at: std::string::String,
+    /// Update timestamp encoded as RFC3339 UTC text.
+    pub updated_at: std::string::String,
+}

kb_lib/src/db/queries.rs

@@ -31,6 +31,8 @@ mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
+mod wallet;
+mod wallet_participation;
 
 pub use analysis_signal::insert_analysis_signal;
 pub use analysis_signal::list_recent_analysis_signals;
@@ -98,3 +100,10 @@ pub use token_burn_event::list_recent_token_burn_events;
 pub use token_burn_event::upsert_token_burn_event;
 pub use token_mint_event::list_recent_token_mint_events;
 pub use token_mint_event::upsert_token_mint_event;
+pub use wallet::get_wallet_by_address;
+pub use wallet::list_wallets;
+pub use wallet::upsert_wallet;
+pub use wallet_participation::get_wallet_participation_by_unique_key;
+pub use wallet_participation::list_wallet_participations_by_pool_id;
+pub use wallet_participation::list_wallet_participations_by_wallet_id;
+pub use wallet_participation::upsert_wallet_participation;

kb_lib/src/db/queries/wallet.rs

@@ -0,0 +1,141 @@
+// file: kb_lib/src/db/queries/wallet.rs
+
+//! Queries for `kb_wallets`.
+
+/// Inserts or updates one wallet row and returns its stable internal id.
+pub async fn upsert_wallet(
+    database: &crate::KbDatabase,
+    dto: &crate::KbWalletDto,
+) -> Result<i64, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO kb_wallets (
+    address,
+    label,
+    first_seen_at,
+    last_seen_at
+)
+VALUES (?, ?, ?, ?)
+ON CONFLICT(address) DO UPDATE SET
+    label = COALESCE(excluded.label, kb_wallets.label),
+    last_seen_at = excluded.last_seen_at
+                "#,
+            )
+            .bind(dto.address.clone())
+            .bind(dto.label.clone())
+            .bind(dto.first_seen_at.to_rfc3339())
+            .bind(dto.last_seen_at.to_rfc3339())
+            .execute(pool)
+            .await;
+            if let Err(error) = query_result {
+                return Err(crate::KbError::Db(format!(
+                    "cannot upsert kb_wallets on sqlite: {}",
+                    error
+                )));
+            }
+            let id_result = sqlx::query_scalar::<sqlx::Sqlite, i64>(
+                r#"
+SELECT id
+FROM kb_wallets
+WHERE address = ?
+LIMIT 1
+                "#,
+            )
+            .bind(dto.address.clone())
+            .fetch_one(pool)
+            .await;
+            match id_result {
+                Ok(id) => Ok(id),
+                Err(error) => Err(crate::KbError::Db(format!(
+                    "cannot fetch kb_wallets id for address '{}' on sqlite: {}",
+                    dto.address, error
+                ))),
+            }
+        }
+    }
+}
+
+/// Returns one wallet identified by its address, if it exists.
+pub async fn get_wallet_by_address(
+    database: &crate::KbDatabase,
+    address: &str,
+) -> Result<std::option::Option<crate::KbWalletDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbWalletEntity>(
+                r#"
+SELECT
+    id,
+    address,
+    label,
+    first_seen_at,
+    last_seen_at
+FROM kb_wallets
+WHERE address = ?
+LIMIT 1
+                "#,
+            )
+            .bind(address)
+            .fetch_optional(pool)
+            .await;
+            let entity_option = match query_result {
+                Ok(entity_option) => entity_option,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot read kb_wallets '{}' on sqlite: {}",
+                        address, error
+                    )));
+                }
+            };
+            match entity_option {
+                Some(entity) => crate::KbWalletDto::try_from(entity).map(Some),
+                None => Ok(None),
+            }
+        }
+    }
+}
+
+/// Lists all persisted wallets ordered by address.
+pub async fn list_wallets(
+    database: &crate::KbDatabase,
+) -> Result<std::vec::Vec<crate::KbWalletDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbWalletEntity>(
+                r#"
+SELECT
+    id,
+    address,
+    label,
+    first_seen_at,
+    last_seen_at
+FROM kb_wallets
+ORDER BY address ASC
+                "#,
+            )
+            .fetch_all(pool)
+            .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot list kb_wallets on sqlite: {}",
+                        error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbWalletDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}

kb_lib/src/db/queries/wallet_participation.rs

@@ -0,0 +1,224 @@
+// file: kb_lib/src/db/queries/wallet_participation.rs
+
+//! Queries for `kb_wallet_participations`.
+
+/// Inserts or updates one wallet-participation row and returns its stable internal id.
+pub async fn upsert_wallet_participation(
+    database: &crate::KbDatabase,
+    dto: &crate::KbWalletParticipationDto,
+) -> Result<i64, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO kb_wallet_participations (
+    wallet_id,
+    transaction_id,
+    decoded_event_id,
+    pool_id,
+    pair_id,
+    role,
+    unique_key,
+    source_kind,
+    source_endpoint_name,
+    created_at,
+    updated_at
+)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(unique_key) DO UPDATE SET
+    updated_at = excluded.updated_at
+                "#,
+            )
+            .bind(dto.wallet_id)
+            .bind(dto.transaction_id)
+            .bind(dto.decoded_event_id)
+            .bind(dto.pool_id)
+            .bind(dto.pair_id)
+            .bind(dto.role.clone())
+            .bind(dto.unique_key.clone())
+            .bind(dto.source_kind.to_i16())
+            .bind(dto.source_endpoint_name.clone())
+            .bind(dto.created_at.to_rfc3339())
+            .bind(dto.updated_at.to_rfc3339())
+            .execute(pool)
+            .await;
+            if let Err(error) = query_result {
+                return Err(crate::KbError::Db(format!(
+                    "cannot upsert kb_wallet_participations on sqlite: {}",
+                    error
+                )));
+            }
+            let id_result = sqlx::query_scalar::<sqlx::Sqlite, i64>(
+                r#"
+SELECT id
+FROM kb_wallet_participations
+WHERE unique_key = ?
+LIMIT 1
+                "#,
+            )
+            .bind(dto.unique_key.clone())
+            .fetch_one(pool)
+            .await;
+            match id_result {
+                Ok(id) => Ok(id),
+                Err(error) => Err(crate::KbError::Db(format!(
+                    "cannot fetch kb_wallet_participations id for unique_key '{}' on sqlite: {}",
+                    dto.unique_key, error
+                ))),
+            }
+        }
+    }
+}
+
+/// Returns one wallet-participation identified by its unique key, if it exists.
+pub async fn get_wallet_participation_by_unique_key(
+    database: &crate::KbDatabase,
+    unique_key: &str,
+) -> Result<std::option::Option<crate::KbWalletParticipationDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbWalletParticipationEntity>(
+                r#"
+SELECT
+    id,
+    wallet_id,
+    transaction_id,
+    decoded_event_id,
+    pool_id,
+    pair_id,
+    role,
+    unique_key,
+    source_kind,
+    source_endpoint_name,
+    created_at,
+    updated_at
+FROM kb_wallet_participations
+WHERE unique_key = ?
+LIMIT 1
+                    "#,
+            )
+            .bind(unique_key)
+            .fetch_optional(pool)
+            .await;
+            let entity_option = match query_result {
+                Ok(entity_option) => entity_option,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot read kb_wallet_participations by unique_key '{}' on sqlite: {}",
+                        unique_key, error
+                    )));
+                }
+            };
+            match entity_option {
+                Some(entity) => crate::KbWalletParticipationDto::try_from(entity).map(Some),
+                None => Ok(None),
+            }
+        }
+    }
+}
+
+/// Lists wallet-participation rows for one wallet id.
+pub async fn list_wallet_participations_by_wallet_id(
+    database: &crate::KbDatabase,
+    wallet_id: i64,
+) -> Result<std::vec::Vec<crate::KbWalletParticipationDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbWalletParticipationEntity>(
+                r#"
+SELECT
+    id,
+    wallet_id,
+    transaction_id,
+    decoded_event_id,
+    pool_id,
+    pair_id,
+    role,
+    unique_key,
+    source_kind,
+    source_endpoint_name,
+    created_at,
+    updated_at
+FROM kb_wallet_participations
+WHERE wallet_id = ?
+ORDER BY created_at ASC, id ASC
+                    "#,
+            )
+            .bind(wallet_id)
+            .fetch_all(pool)
+            .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot list kb_wallet_participations by wallet_id '{}' on sqlite: {}",
+                        wallet_id, error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbWalletParticipationDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}
+
+/// Lists wallet-participation rows for one pool id.
+pub async fn list_wallet_participations_by_pool_id(
+    database: &crate::KbDatabase,
+    pool_id: i64,
+) -> Result<std::vec::Vec<crate::KbWalletParticipationDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbWalletParticipationEntity>(
+                r#"
+SELECT
+    id,
+    wallet_id,
+    transaction_id,
+    decoded_event_id,
+    pool_id,
+    pair_id,
+    role,
+    unique_key,
+    source_kind,
+    source_endpoint_name,
+    created_at,
+    updated_at
+FROM kb_wallet_participations
+WHERE pool_id = ?
+ORDER BY created_at ASC, id ASC
+                    "#,
+            )
+            .bind(pool_id)
+            .fetch_all(pool)
+            .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot list kb_wallet_participations by pool_id '{}' on sqlite: {}",
+                        pool_id, error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbWalletParticipationDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}

kb_lib/src/db/schema.rs

@@ -274,6 +274,26 @@ pub(crate) async fn ensure_schema(database: &crate::KbDatabase) -> Result<(), cr
             if let Err(error) = result {
                 return Err(error);
             }
+            let result = create_kb_wallets_table(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_wallet_participations_table(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_wallet_participations_wallet_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_wallet_participations_pool_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_wallet_participations_transaction_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
             Ok(())
         }
     }
@@ -1498,3 +1518,93 @@ ON kb_pool_origins(founding_transaction_id)
     )
     .await
 }
+
+async fn create_kb_wallets_table(pool: &sqlx::SqlitePool) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_wallets_table",
+        r#"
+CREATE TABLE IF NOT EXISTS kb_wallets (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    address TEXT NOT NULL UNIQUE,
+    label TEXT NULL,
+    first_seen_at TEXT NOT NULL,
+    last_seen_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_wallet_participations_table(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_wallet_participations_table",
+        r#"
+CREATE TABLE IF NOT EXISTS kb_wallet_participations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    wallet_id INTEGER NOT NULL,
+    transaction_id INTEGER NOT NULL,
+    decoded_event_id INTEGER NULL,
+    pool_id INTEGER NULL,
+    pair_id INTEGER NULL,
+    role TEXT NOT NULL,
+    unique_key TEXT NOT NULL UNIQUE,
+    source_kind INTEGER NOT NULL,
+    source_endpoint_name TEXT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY(wallet_id) REFERENCES kb_wallets(id) ON DELETE CASCADE,
+    FOREIGN KEY(transaction_id) REFERENCES kb_chain_transactions(id) ON DELETE CASCADE,
+    FOREIGN KEY(decoded_event_id) REFERENCES kb_dex_decoded_events(id) ON DELETE SET NULL,
+    FOREIGN KEY(pool_id) REFERENCES kb_pools(id) ON DELETE SET NULL,
+    FOREIGN KEY(pair_id) REFERENCES kb_pairs(id) ON DELETE SET NULL
+)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_idx_wallet_participations_wallet_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_wallet_participations_wallet_id",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_wallet_participations_wallet_id
+ON kb_wallet_participations(wallet_id)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_idx_wallet_participations_pool_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_wallet_participations_pool_id",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_wallet_participations_pool_id
+ON kb_wallet_participations(pool_id)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_idx_wallet_participations_transaction_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_wallet_participations_transaction_id",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_wallet_participations_transaction_id
+ON kb_wallet_participations(transaction_id)
+        "#,
+    )
+    .await
+}