0.7.28

kb_lib/src/db/dtos.rs

@@ -27,11 +27,14 @@ mod pool;
 mod pool_listing;
 mod pool_origin;
 mod pool_token;
+mod protocol_candidate;
+mod protocol_candidate_summary;
 mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
 mod trade_event;
+mod transaction_classification;
 mod wallet;
 mod wallet_holding;
 mod wallet_participation;
@@ -82,11 +85,14 @@ pub use pool::PoolDto;
 pub use pool_listing::PoolListingDto;
 pub use pool_origin::PoolOriginDto;
 pub use pool_token::PoolTokenDto;
+pub use protocol_candidate::ProtocolCandidateDto;
+pub use protocol_candidate_summary::ProtocolCandidateSummaryDto;
 pub use swap::SwapDto;
 pub use token::TokenDto;
 pub use token_burn_event::TokenBurnEventDto;
 pub use token_mint_event::TokenMintEventDto;
 pub use trade_event::TradeEventDto;
+pub use transaction_classification::TransactionClassificationDto;
 pub use wallet::WalletDto;
 pub use wallet_holding::WalletHoldingDto;
 pub use wallet_participation::WalletParticipationDto;

kb_lib/src/db/dtos/protocol_candidate.rs

@@ -0,0 +1,114 @@
+// file: kb_lib/src/db/dtos/protocol_candidate.rs
+
+//! Protocol candidate DTO.
+
+/// Application-facing protocol candidate DTO.
+///
+/// A protocol candidate records a program/instruction that should be inspected
+/// later because it may correspond to an unsupported DEX, launch surface,
+/// migration path or protocol-specific non-trade event.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ProtocolCandidateDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Related chain transaction id.
+    pub transaction_id: i64,
+    /// Optional related chain instruction id.
+    pub instruction_id: std::option::Option<i64>,
+    /// Transaction signature.
+    pub signature: std::string::String,
+    /// Optional Solana slot.
+    pub slot: std::option::Option<u64>,
+    /// Program id observed in the transaction instruction.
+    pub program_id: std::string::String,
+    /// Optional program name hint from parsed transaction data.
+    pub program_name_hint: std::option::Option<std::string::String>,
+    /// Optional candidate protocol code.
+    pub candidate_protocol: std::option::Option<std::string::String>,
+    /// Optional candidate surface code.
+    pub candidate_surface: std::option::Option<std::string::String>,
+    /// Human-readable reason.
+    pub reason: std::string::String,
+    /// Serialized JSON evidence.
+    pub evidence_json: std::string::String,
+    /// Creation timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl ProtocolCandidateDto {
+    /// Creates a protocol candidate DTO.
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        transaction_id: i64,
+        instruction_id: std::option::Option<i64>,
+        signature: std::string::String,
+        slot: std::option::Option<u64>,
+        program_id: std::string::String,
+        program_name_hint: std::option::Option<std::string::String>,
+        candidate_protocol: std::option::Option<std::string::String>,
+        candidate_surface: std::option::Option<std::string::String>,
+        reason: std::string::String,
+        evidence_json: std::string::String,
+    ) -> Self {
+        return Self {
+            id: None,
+            transaction_id,
+            instruction_id,
+            signature,
+            slot,
+            program_id,
+            program_name_hint,
+            candidate_protocol,
+            candidate_surface,
+            reason,
+            evidence_json,
+            created_at: chrono::Utc::now(),
+        };
+    }
+}
+
+impl TryFrom<crate::ProtocolCandidateEntity> for ProtocolCandidateDto {
+    type Error = crate::Error;
+
+    fn try_from(entity: crate::ProtocolCandidateEntity) -> Result<Self, Self::Error> {
+        let slot = match entity.slot {
+            Some(slot) => {
+                let slot_result = u64::try_from(slot);
+                match slot_result {
+                    Ok(slot) => Some(slot),
+                    Err(error) => {
+                        return Err(crate::Error::Db(format!(
+                            "cannot convert protocol candidate slot '{}' to u64: {}",
+                            slot, error
+                        )));
+                    },
+                }
+            },
+            None => None,
+        };
+        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::Error::Db(format!(
+                    "cannot parse protocol candidate created_at '{}': {}",
+                    entity.created_at, error
+                )));
+            },
+        };
+        return Ok(Self {
+            id: Some(entity.id),
+            transaction_id: entity.transaction_id,
+            instruction_id: entity.instruction_id,
+            signature: entity.signature,
+            slot,
+            program_id: entity.program_id,
+            program_name_hint: entity.program_name_hint,
+            candidate_protocol: entity.candidate_protocol,
+            candidate_surface: entity.candidate_surface,
+            reason: entity.reason,
+            evidence_json: entity.evidence_json,
+            created_at,
+        });
+    }
+}

kb_lib/src/db/dtos/protocol_candidate_summary.rs

@@ -0,0 +1,96 @@
+// file: kb_lib/src/db/dtos/protocol_candidate_summary.rs
+
+//! Protocol candidate summary DTO.
+
+/// Aggregated protocol candidate diagnostic row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ProtocolCandidateSummaryDto {
+    /// Program id observed in protocol candidates.
+    pub program_id: std::string::String,
+    /// Optional program name hint.
+    pub program_name_hint: std::option::Option<std::string::String>,
+    /// Optional candidate protocol.
+    pub candidate_protocol: std::option::Option<std::string::String>,
+    /// Optional candidate surface.
+    pub candidate_surface: std::option::Option<std::string::String>,
+    /// Candidate reason.
+    pub reason: std::string::String,
+    /// Number of candidate rows.
+    pub occurrence_count: u64,
+    /// Number of distinct transactions.
+    pub transaction_count: u64,
+    /// Latest observed slot.
+    pub last_slot: std::option::Option<u64>,
+    /// Latest candidate row id in this group.
+    pub latest_candidate_id: i64,
+    /// Latest signature in this group.
+    pub latest_signature: std::string::String,
+    /// Latest candidate creation timestamp.
+    pub latest_created_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl TryFrom<crate::ProtocolCandidateSummaryEntity> for ProtocolCandidateSummaryDto {
+    type Error = crate::Error;
+
+    fn try_from(entity: crate::ProtocolCandidateSummaryEntity) -> Result<Self, Self::Error> {
+        let occurrence_count_result = u64::try_from(entity.occurrence_count);
+        let occurrence_count = match occurrence_count_result {
+            Ok(occurrence_count) => occurrence_count,
+            Err(error) => {
+                return Err(crate::Error::Db(format!(
+                    "cannot convert protocol candidate occurrence_count '{}' to u64: {}",
+                    entity.occurrence_count, error
+                )));
+            },
+        };
+        let transaction_count_result = u64::try_from(entity.transaction_count);
+        let transaction_count = match transaction_count_result {
+            Ok(transaction_count) => transaction_count,
+            Err(error) => {
+                return Err(crate::Error::Db(format!(
+                    "cannot convert protocol candidate transaction_count '{}' to u64: {}",
+                    entity.transaction_count, error
+                )));
+            },
+        };
+        let last_slot = match entity.last_slot {
+            Some(last_slot) => {
+                let slot_result = u64::try_from(last_slot);
+                match slot_result {
+                    Ok(slot) => Some(slot),
+                    Err(error) => {
+                        return Err(crate::Error::Db(format!(
+                            "cannot convert protocol candidate last_slot '{}' to u64: {}",
+                            last_slot, error
+                        )));
+                    },
+                }
+            },
+            None => None,
+        };
+        let latest_created_at_result =
+            chrono::DateTime::parse_from_rfc3339(entity.latest_created_at.as_str());
+        let latest_created_at = match latest_created_at_result {
+            Ok(latest_created_at) => latest_created_at.with_timezone(&chrono::Utc),
+            Err(error) => {
+                return Err(crate::Error::Db(format!(
+                    "cannot parse protocol candidate latest_created_at '{}': {}",
+                    entity.latest_created_at, error
+                )));
+            },
+        };
+        return Ok(Self {
+            program_id: entity.program_id,
+            program_name_hint: entity.program_name_hint,
+            candidate_protocol: entity.candidate_protocol,
+            candidate_surface: entity.candidate_surface,
+            reason: entity.reason,
+            occurrence_count,
+            transaction_count,
+            last_slot,
+            latest_candidate_id: entity.latest_candidate_id,
+            latest_signature: entity.latest_signature,
+            latest_created_at,
+        });
+    }
+}

kb_lib/src/db/dtos/transaction_classification.rs

@@ -0,0 +1,130 @@
+// file: kb_lib/src/db/dtos/transaction_classification.rs
+
+//! Transaction classification DTO.
+
+/// Application-facing transaction classification DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct TransactionClassificationDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Related chain transaction id.
+    pub transaction_id: i64,
+    /// Transaction signature.
+    pub signature: std::string::String,
+    /// Optional Solana slot.
+    pub slot: std::option::Option<u64>,
+    /// Stable classification kind.
+    pub classification_kind: std::string::String,
+    /// Optional primary protocol name.
+    pub primary_protocol: std::option::Option<std::string::String>,
+    /// Optional primary program id.
+    pub primary_program_id: std::option::Option<std::string::String>,
+    /// Confidence level from 0 to 100.
+    pub confidence_level: i16,
+    /// Human-readable reason.
+    pub reason: std::string::String,
+    /// Serialized JSON evidence.
+    pub evidence_json: std::string::String,
+    /// Creation timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl TransactionClassificationDto {
+    /// Creates a new transaction classification DTO.
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        transaction_id: i64,
+        signature: std::string::String,
+        slot: std::option::Option<u64>,
+        classification_kind: std::string::String,
+        primary_protocol: std::option::Option<std::string::String>,
+        primary_program_id: std::option::Option<std::string::String>,
+        confidence_level: i16,
+        reason: std::string::String,
+        evidence_json: std::string::String,
+    ) -> Self {
+        let now = chrono::Utc::now();
+        return Self {
+            id: None,
+            transaction_id,
+            signature,
+            slot,
+            classification_kind,
+            primary_protocol,
+            primary_program_id,
+            confidence_level,
+            reason,
+            evidence_json,
+            created_at: now,
+            updated_at: now,
+        };
+    }
+}
+
+impl TryFrom<crate::TransactionClassificationEntity> for TransactionClassificationDto {
+    type Error = crate::Error;
+
+    fn try_from(entity: crate::TransactionClassificationEntity) -> Result<Self, Self::Error> {
+        let slot = match entity.slot {
+            Some(slot) => {
+                let slot_result = u64::try_from(slot);
+                match slot_result {
+                    Ok(slot) => Some(slot),
+                    Err(error) => {
+                        return Err(crate::Error::Db(format!(
+                            "cannot convert transaction classification slot '{}' to u64: {}",
+                            slot, error
+                        )));
+                    },
+                }
+            },
+            None => None,
+        };
+        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::Error::Db(format!(
+                    "cannot parse transaction classification 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::Error::Db(format!(
+                    "cannot parse transaction classification updated_at '{}': {}",
+                    entity.updated_at, error
+                )));
+            },
+        };
+        let confidence_level_result = i16::try_from(entity.confidence_level);
+        let confidence_level = match confidence_level_result {
+            Ok(confidence_level) => confidence_level,
+            Err(error) => {
+                return Err(crate::Error::Db(format!(
+                    "cannot convert transaction classification confidence_level '{}' to i16: {}",
+                    entity.confidence_level, error
+                )));
+            },
+        };
+        return Ok(Self {
+            id: Some(entity.id),
+            transaction_id: entity.transaction_id,
+            signature: entity.signature,
+            slot,
+            classification_kind: entity.classification_kind,
+            primary_protocol: entity.primary_protocol,
+            primary_program_id: entity.primary_program_id,
+            confidence_level,
+            reason: entity.reason,
+            evidence_json: entity.evidence_json,
+            created_at,
+            updated_at,
+        });
+    }
+}

kb_lib/src/db/entities.rs

@@ -28,11 +28,14 @@ mod pool;
 mod pool_listing;
 mod pool_origin;
 mod pool_token;
+mod protocol_candidate;
+mod protocol_candidate_summary;
 mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
 mod trade_event;
+mod transaction_classification;
 mod wallet;
 mod wallet_holding;
 mod wallet_participation;
@@ -61,11 +64,14 @@ pub use pool::PoolEntity;
 pub use pool_listing::PoolListingEntity;
 pub use pool_origin::PoolOriginEntity;
 pub use pool_token::PoolTokenEntity;
+pub use protocol_candidate::ProtocolCandidateEntity;
+pub use protocol_candidate_summary::ProtocolCandidateSummaryEntity;
 pub use swap::SwapEntity;
 pub use token::TokenEntity;
 pub use token_burn_event::TokenBurnEventEntity;
 pub use token_mint_event::TokenMintEventEntity;
 pub use trade_event::TradeEventEntity;
+pub use transaction_classification::TransactionClassificationEntity;
 pub use wallet::WalletEntity;
 pub use wallet_holding::WalletHoldingEntity;
 pub use wallet_participation::WalletParticipationEntity;

kb_lib/src/db/entities/protocol_candidate.rs

@@ -0,0 +1,32 @@
+// file: kb_lib/src/db/entities/protocol_candidate.rs
+
+//! Protocol candidate entity.
+
+/// Persisted protocol candidate row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct ProtocolCandidateEntity {
+    /// Numeric primary key.
+    pub id: i64,
+    /// Related chain transaction id.
+    pub transaction_id: i64,
+    /// Optional related chain instruction id.
+    pub instruction_id: std::option::Option<i64>,
+    /// Transaction signature.
+    pub signature: std::string::String,
+    /// Optional Solana slot.
+    pub slot: std::option::Option<i64>,
+    /// Program id observed in the transaction instruction.
+    pub program_id: std::string::String,
+    /// Optional program name hint from parsed transaction data.
+    pub program_name_hint: std::option::Option<std::string::String>,
+    /// Optional candidate protocol code.
+    pub candidate_protocol: std::option::Option<std::string::String>,
+    /// Optional candidate surface code.
+    pub candidate_surface: std::option::Option<std::string::String>,
+    /// Human-readable reason.
+    pub reason: std::string::String,
+    /// Serialized JSON evidence.
+    pub evidence_json: std::string::String,
+    /// Creation timestamp encoded as RFC3339 UTC text.
+    pub created_at: std::string::String,
+}

kb_lib/src/db/entities/protocol_candidate_summary.rs

@@ -0,0 +1,30 @@
+// file: kb_lib/src/db/entities/protocol_candidate_summary.rs
+
+//! Protocol candidate summary entity.
+
+/// Aggregated protocol candidate diagnostic row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct ProtocolCandidateSummaryEntity {
+    /// Program id observed in protocol candidates.
+    pub program_id: std::string::String,
+    /// Optional program name hint.
+    pub program_name_hint: std::option::Option<std::string::String>,
+    /// Optional candidate protocol.
+    pub candidate_protocol: std::option::Option<std::string::String>,
+    /// Optional candidate surface.
+    pub candidate_surface: std::option::Option<std::string::String>,
+    /// Candidate reason.
+    pub reason: std::string::String,
+    /// Number of candidate rows.
+    pub occurrence_count: i64,
+    /// Number of distinct transactions.
+    pub transaction_count: i64,
+    /// Latest observed slot.
+    pub last_slot: std::option::Option<i64>,
+    /// Latest candidate row id in this group.
+    pub latest_candidate_id: i64,
+    /// Latest signature in this group.
+    pub latest_signature: std::string::String,
+    /// Latest candidate creation timestamp encoded as RFC3339 UTC text.
+    pub latest_created_at: std::string::String,
+}

kb_lib/src/db/entities/transaction_classification.rs

@@ -0,0 +1,32 @@
+// file: kb_lib/src/db/entities/transaction_classification.rs
+
+//! Transaction classification entity.
+
+/// Persisted transaction classification row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct TransactionClassificationEntity {
+    /// Numeric primary key.
+    pub id: i64,
+    /// Related chain transaction id.
+    pub transaction_id: i64,
+    /// Transaction signature.
+    pub signature: std::string::String,
+    /// Optional Solana slot.
+    pub slot: std::option::Option<i64>,
+    /// Stable classification kind.
+    pub classification_kind: std::string::String,
+    /// Optional primary protocol name.
+    pub primary_protocol: std::option::Option<std::string::String>,
+    /// Optional primary program id.
+    pub primary_program_id: std::option::Option<std::string::String>,
+    /// Confidence level from 0 to 100.
+    pub confidence_level: i64,
+    /// Human-readable reason.
+    pub reason: std::string::String,
+    /// Serialized JSON evidence.
+    pub evidence_json: 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

@@ -27,11 +27,13 @@ mod pool;
 mod pool_listing;
 mod pool_origin;
 mod pool_token;
+mod protocol_candidate;
 mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
 mod trade_event;
+mod transaction_classification;
 mod wallet;
 mod wallet_holding;
 mod wallet_participation;
@@ -118,6 +120,12 @@ pub use pool_origin::query_pool_origins_list;
 pub use pool_origin::query_pool_origins_upsert;
 pub use pool_token::query_pool_tokens_list_by_pool_id;
 pub use pool_token::query_pool_tokens_upsert;
+pub use protocol_candidate::query_protocol_candidate_summaries_list_by_priority;
+pub use protocol_candidate::query_protocol_candidates_delete_by_transaction_id;
+pub use protocol_candidate::query_protocol_candidates_insert;
+pub use protocol_candidate::query_protocol_candidates_list_by_program_id;
+pub use protocol_candidate::query_protocol_candidates_list_by_transaction_id;
+pub use protocol_candidate::query_protocol_candidates_list_recent;
 pub use swap::query_swaps_list_recent;
 pub use swap::query_swaps_upsert;
 pub use token::query_tokens_get_by_id;
@@ -133,6 +141,10 @@ pub use trade_event::query_trade_events_get_by_decoded_event_id;
 pub use trade_event::query_trade_events_list_by_pair_id;
 pub use trade_event::query_trade_events_list_by_transaction_id;
 pub use trade_event::query_trade_events_upsert;
+pub use transaction_classification::query_transaction_classifications_get_by_signature;
+pub use transaction_classification::query_transaction_classifications_get_by_transaction_id;
+pub use transaction_classification::query_transaction_classifications_list_recent;
+pub use transaction_classification::query_transaction_classifications_upsert;
 pub use wallet::query_wallets_get_by_address;
 pub use wallet::query_wallets_list;
 pub use wallet::query_wallets_upsert;

kb_lib/src/db/queries/protocol_candidate.rs

@@ -0,0 +1,337 @@
+// file: kb_lib/src/db/queries/protocol_candidate.rs
+
+//! Queries for `k_sol_protocol_candidates`.
+
+/// Inserts one protocol candidate row.
+pub async fn query_protocol_candidates_insert(
+    database: &crate::Database,
+    dto: &crate::ProtocolCandidateDto,
+) -> Result<i64, crate::Error> {
+    let slot_i64 = match dto.slot {
+        Some(slot) => {
+            let slot_result = i64::try_from(slot);
+            match slot_result {
+                Ok(slot) => Some(slot),
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot convert protocol candidate slot '{}' to i64: {}",
+                        slot, error
+                    )));
+                },
+            }
+        },
+        None => None,
+    };
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO k_sol_protocol_candidates (
+    transaction_id,
+    instruction_id,
+    signature,
+    slot,
+    program_id,
+    program_name_hint,
+    candidate_protocol,
+    candidate_surface,
+    reason,
+    evidence_json,
+    created_at
+)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                "#,
+            )
+            .bind(dto.transaction_id)
+            .bind(dto.instruction_id)
+            .bind(dto.signature.clone())
+            .bind(slot_i64)
+            .bind(dto.program_id.clone())
+            .bind(dto.program_name_hint.clone())
+            .bind(dto.candidate_protocol.clone())
+            .bind(dto.candidate_surface.clone())
+            .bind(dto.reason.clone())
+            .bind(dto.evidence_json.clone())
+            .bind(dto.created_at.to_rfc3339())
+            .execute(pool)
+            .await;
+            match query_result {
+                Ok(query_result) => return Ok(query_result.last_insert_rowid()),
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot insert k_sol_protocol_candidates on sqlite: {}",
+                        error
+                    )));
+                },
+            }
+        },
+    }
+}
+
+/// Deletes protocol candidates for one transaction.
+///
+/// This is useful before recomputing candidates for a replayed transaction.
+pub async fn query_protocol_candidates_delete_by_transaction_id(
+    database: &crate::Database,
+    transaction_id: i64,
+) -> Result<u64, crate::Error> {
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+DELETE FROM k_sol_protocol_candidates
+WHERE transaction_id = ?
+                "#,
+            )
+            .bind(transaction_id)
+            .execute(pool)
+            .await;
+            match query_result {
+                Ok(query_result) => return Ok(query_result.rows_affected()),
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot delete k_sol_protocol_candidates for transaction_id '{}' on sqlite: {}",
+                        transaction_id, error
+                    )));
+                },
+            }
+        },
+    }
+}
+
+/// Lists protocol candidates for one transaction.
+pub async fn query_protocol_candidates_list_by_transaction_id(
+    database: &crate::Database,
+    transaction_id: i64,
+) -> Result<std::vec::Vec<crate::ProtocolCandidateDto>, crate::Error> {
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::ProtocolCandidateEntity>(
+                r#"
+SELECT
+    id,
+    transaction_id,
+    instruction_id,
+    signature,
+    slot,
+    program_id,
+    program_name_hint,
+    candidate_protocol,
+    candidate_surface,
+    reason,
+    evidence_json,
+    created_at
+FROM k_sol_protocol_candidates
+WHERE transaction_id = ?
+ORDER BY id ASC
+                "#,
+            )
+            .bind(transaction_id)
+            .fetch_all(pool)
+            .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot list k_sol_protocol_candidates for transaction_id '{}' on sqlite: {}",
+                        transaction_id, error
+                    )));
+                },
+            };
+            return protocol_candidate_entities_to_dtos(entities);
+        },
+    }
+}
+
+/// Lists protocol candidates for one program id.
+pub async fn query_protocol_candidates_list_by_program_id(
+    database: &crate::Database,
+    program_id: &str,
+    limit: u32,
+) -> Result<std::vec::Vec<crate::ProtocolCandidateDto>, crate::Error> {
+    if limit == 0 {
+        return Ok(std::vec::Vec::new());
+    }
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::ProtocolCandidateEntity>(
+                r#"
+SELECT
+    id,
+    transaction_id,
+    instruction_id,
+    signature,
+    slot,
+    program_id,
+    program_name_hint,
+    candidate_protocol,
+    candidate_surface,
+    reason,
+    evidence_json,
+    created_at
+FROM k_sol_protocol_candidates
+WHERE program_id = ?
+ORDER BY id DESC
+LIMIT ?
+                "#,
+            )
+            .bind(program_id.to_string())
+            .bind(i64::from(limit))
+            .fetch_all(pool)
+            .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot list k_sol_protocol_candidates for program_id '{}' on sqlite: {}",
+                        program_id, error
+                    )));
+                },
+            };
+            return protocol_candidate_entities_to_dtos(entities);
+        },
+    }
+}
+
+/// Lists recent protocol candidates ordered from newest to oldest.
+pub async fn query_protocol_candidates_list_recent(
+    database: &crate::Database,
+    limit: u32,
+) -> Result<std::vec::Vec<crate::ProtocolCandidateDto>, crate::Error> {
+    if limit == 0 {
+        return Ok(std::vec::Vec::new());
+    }
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::ProtocolCandidateEntity>(
+                r#"
+SELECT
+    id,
+    transaction_id,
+    instruction_id,
+    signature,
+    slot,
+    program_id,
+    program_name_hint,
+    candidate_protocol,
+    candidate_surface,
+    reason,
+    evidence_json,
+    created_at
+FROM k_sol_protocol_candidates
+ORDER BY id DESC
+LIMIT ?
+                "#,
+            )
+            .bind(i64::from(limit))
+            .fetch_all(pool)
+            .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot list recent k_sol_protocol_candidates on sqlite: {}",
+                        error
+                    )));
+                },
+            };
+            return protocol_candidate_entities_to_dtos(entities);
+        },
+    }
+}
+
+fn protocol_candidate_entities_to_dtos(
+    entities: std::vec::Vec<crate::ProtocolCandidateEntity>,
+) -> Result<std::vec::Vec<crate::ProtocolCandidateDto>, crate::Error> {
+    let mut dtos = std::vec::Vec::new();
+    for entity in entities {
+        let dto_result = crate::ProtocolCandidateDto::try_from(entity);
+        let dto = match dto_result {
+            Ok(dto) => dto,
+            Err(error) => return Err(error),
+        };
+        dtos.push(dto);
+    }
+    return Ok(dtos);
+}
+
+/// Lists protocol candidate summaries ordered by investigation priority.
+pub async fn query_protocol_candidate_summaries_list_by_priority(
+    database: &crate::Database,
+    limit: u32,
+) -> Result<std::vec::Vec<crate::ProtocolCandidateSummaryDto>, crate::Error> {
+    if limit == 0 {
+        return Ok(std::vec::Vec::new());
+    }
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::ProtocolCandidateSummaryEntity>(
+                    r#"
+WITH grouped AS (
+    SELECT
+        program_id,
+        program_name_hint,
+        candidate_protocol,
+        candidate_surface,
+        reason,
+        COUNT(*) AS occurrence_count,
+        COUNT(DISTINCT signature) AS transaction_count,
+        MAX(slot) AS last_slot,
+        MAX(id) AS latest_candidate_id
+    FROM k_sol_protocol_candidates
+    GROUP BY
+        program_id,
+        program_name_hint,
+        candidate_protocol,
+        candidate_surface,
+        reason
+)
+SELECT
+    grouped.program_id,
+    grouped.program_name_hint,
+    grouped.candidate_protocol,
+    grouped.candidate_surface,
+    grouped.reason,
+    grouped.occurrence_count,
+    grouped.transaction_count,
+    grouped.last_slot,
+    grouped.latest_candidate_id,
+    latest.signature AS latest_signature,
+    latest.created_at AS latest_created_at
+FROM grouped
+JOIN k_sol_protocol_candidates latest
+    ON latest.id = grouped.latest_candidate_id
+ORDER BY
+    grouped.transaction_count DESC,
+    grouped.occurrence_count DESC,
+    grouped.last_slot DESC,
+    grouped.latest_candidate_id DESC
+LIMIT ?
+                    "#,
+                )
+                .bind(i64::from(limit))
+                .fetch_all(pool)
+                .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot list k_sol_protocol_candidates summaries on sqlite: {}",
+                        error
+                    )));
+                },
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::ProtocolCandidateSummaryDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            return Ok(dtos);
+        },
+    }
+}

kb_lib/src/db/queries/transaction_classification.rs

@@ -0,0 +1,263 @@
+// file: kb_lib/src/db/queries/transaction_classification.rs
+
+//! Queries for `k_sol_transaction_classifications`.
+
+/// Inserts or updates one transaction classification row.
+pub async fn query_transaction_classifications_upsert(
+    database: &crate::Database,
+    dto: &crate::TransactionClassificationDto,
+) -> Result<i64, crate::Error> {
+    let slot_i64 = match dto.slot {
+        Some(slot) => {
+            let slot_result = i64::try_from(slot);
+            match slot_result {
+                Ok(slot) => Some(slot),
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot convert transaction classification slot '{}' to i64: {}",
+                        slot, error
+                    )));
+                },
+            }
+        },
+        None => None,
+    };
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO k_sol_transaction_classifications (
+    transaction_id,
+    signature,
+    slot,
+    classification_kind,
+    primary_protocol,
+    primary_program_id,
+    confidence_level,
+    reason,
+    evidence_json,
+    created_at,
+    updated_at
+)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(transaction_id) DO UPDATE SET
+    signature = excluded.signature,
+    slot = excluded.slot,
+    classification_kind = excluded.classification_kind,
+    primary_protocol = excluded.primary_protocol,
+    primary_program_id = excluded.primary_program_id,
+    confidence_level = excluded.confidence_level,
+    reason = excluded.reason,
+    evidence_json = excluded.evidence_json,
+    updated_at = excluded.updated_at
+                "#,
+            )
+            .bind(dto.transaction_id)
+            .bind(dto.signature.clone())
+            .bind(slot_i64)
+            .bind(dto.classification_kind.clone())
+            .bind(dto.primary_protocol.clone())
+            .bind(dto.primary_program_id.clone())
+            .bind(i64::from(dto.confidence_level))
+            .bind(dto.reason.clone())
+            .bind(dto.evidence_json.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::Error::Db(format!(
+                    "cannot upsert k_sol_transaction_classifications on sqlite: {}",
+                    error
+                )));
+            }
+
+            let id_result = sqlx::query_scalar::<sqlx::Sqlite, i64>(
+                r#"
+SELECT id
+FROM k_sol_transaction_classifications
+WHERE transaction_id = ?
+LIMIT 1
+                "#,
+            )
+            .bind(dto.transaction_id)
+            .fetch_one(pool)
+            .await;
+            match id_result {
+                Ok(id) => return Ok(id),
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot fetch k_sol_transaction_classifications id for transaction_id '{}' on sqlite: {}",
+                        dto.transaction_id, error
+                    )));
+                },
+            }
+        },
+    }
+}
+
+/// Reads one transaction classification by transaction id.
+pub async fn query_transaction_classifications_get_by_transaction_id(
+    database: &crate::Database,
+    transaction_id: i64,
+) -> Result<std::option::Option<crate::TransactionClassificationDto>, crate::Error> {
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::TransactionClassificationEntity>(
+                    r#"
+SELECT
+    id,
+    transaction_id,
+    signature,
+    slot,
+    classification_kind,
+    primary_protocol,
+    primary_program_id,
+    confidence_level,
+    reason,
+    evidence_json,
+    created_at,
+    updated_at
+FROM k_sol_transaction_classifications
+WHERE transaction_id = ?
+LIMIT 1
+                    "#,
+                )
+                .bind(transaction_id)
+                .fetch_optional(pool)
+                .await;
+            let entity_option = match query_result {
+                Ok(entity_option) => entity_option,
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot fetch k_sol_transaction_classifications for transaction_id '{}' on sqlite: {}",
+                        transaction_id, error
+                    )));
+                },
+            };
+            match entity_option {
+                Some(entity) => {
+                    let dto_result = crate::TransactionClassificationDto::try_from(entity);
+                    match dto_result {
+                        Ok(dto) => return Ok(Some(dto)),
+                        Err(error) => return Err(error),
+                    }
+                },
+                None => return Ok(None),
+            }
+        },
+    }
+}
+
+/// Reads one transaction classification by signature.
+pub async fn query_transaction_classifications_get_by_signature(
+    database: &crate::Database,
+    signature: &str,
+) -> Result<std::option::Option<crate::TransactionClassificationDto>, crate::Error> {
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::TransactionClassificationEntity>(
+                    r#"
+SELECT
+    id,
+    transaction_id,
+    signature,
+    slot,
+    classification_kind,
+    primary_protocol,
+    primary_program_id,
+    confidence_level,
+    reason,
+    evidence_json,
+    created_at,
+    updated_at
+FROM k_sol_transaction_classifications
+WHERE signature = ?
+LIMIT 1
+                    "#,
+                )
+                .bind(signature.to_string())
+                .fetch_optional(pool)
+                .await;
+            let entity_option = match query_result {
+                Ok(entity_option) => entity_option,
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot fetch k_sol_transaction_classifications for signature '{}' on sqlite: {}",
+                        signature, error
+                    )));
+                },
+            };
+            match entity_option {
+                Some(entity) => {
+                    let dto_result = crate::TransactionClassificationDto::try_from(entity);
+                    match dto_result {
+                        Ok(dto) => return Ok(Some(dto)),
+                        Err(error) => return Err(error),
+                    }
+                },
+                None => return Ok(None),
+            }
+        },
+    }
+}
+
+/// Lists recent transaction classifications ordered from newest to oldest.
+pub async fn query_transaction_classifications_list_recent(
+    database: &crate::Database,
+    limit: u32,
+) -> Result<std::vec::Vec<crate::TransactionClassificationDto>, crate::Error> {
+    if limit == 0 {
+        return Ok(std::vec::Vec::new());
+    }
+    match database.connection() {
+        crate::DatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::TransactionClassificationEntity>(
+                    r#"
+SELECT
+    id,
+    transaction_id,
+    signature,
+    slot,
+    classification_kind,
+    primary_protocol,
+    primary_program_id,
+    confidence_level,
+    reason,
+    evidence_json,
+    created_at,
+    updated_at
+FROM k_sol_transaction_classifications
+ORDER BY id DESC
+LIMIT ?
+                    "#,
+                )
+                .bind(i64::from(limit))
+                .fetch_all(pool)
+                .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::Error::Db(format!(
+                        "cannot list k_sol_transaction_classifications on sqlite: {}",
+                        error
+                    )));
+                },
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::TransactionClassificationDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+
+                dtos.push(dto);
+            }
+            return Ok(dtos);
+        },
+    }
+}

kb_lib/src/db/schema.rs

@@ -230,6 +230,94 @@ pub(crate) async fn ensure_schema(database: &crate::Database) -> Result<(), crat
             if let Err(error) = result {
                 return Err(error);
             }
+            let result = create_tbl_transaction_classifications(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_uix_transaction_classifications_transaction_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_transaction_classifications_kind(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_tbl_protocol_candidates(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_protocol_candidates_transaction_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_protocol_candidates_program_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_tbl_pool_lifecycle_events(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_pool_lifecycle_events_transaction_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_pool_lifecycle_events_pool_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_uix_pool_lifecycle_events_decoded_event_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_tbl_fee_events(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_fee_events_transaction_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_fee_events_pool_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_uix_fee_events_decoded_event_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_tbl_reward_events(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_reward_events_transaction_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_reward_events_pool_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_uix_reward_events_decoded_event_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_tbl_pool_admin_events(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_pool_admin_events_transaction_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_idx_pool_admin_events_pool_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_uix_pool_admin_events_decoded_event_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
             let result = create_tbl_launch_surfaces(pool).await;
             if let Err(error) = result {
                 return Err(error);
@@ -1878,3 +1966,413 @@ ON k_sol_pair_analytic_signals(pair_id)
     )
     .await;
 }
+
+/// Creates `k_sol_transaction_classifications`.
+async fn create_tbl_transaction_classifications(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_tbl_transaction_classifications",
+        r#"
+CREATE TABLE IF NOT EXISTS k_sol_transaction_classifications (
+    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    transaction_id INTEGER NOT NULL,
+    signature TEXT NOT NULL,
+    slot INTEGER NULL,
+    classification_kind TEXT NOT NULL,
+    primary_protocol TEXT NULL,
+    primary_program_id TEXT NULL,
+    confidence_level INTEGER NOT NULL,
+    reason TEXT NOT NULL,
+    evidence_json TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await;
+}
+
+/// Creates unique index on `k_sol_transaction_classifications(transaction_id)`.
+async fn create_uix_transaction_classifications_transaction_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_uix_transaction_classifications_transaction_id",
+        r#"
+CREATE UNIQUE INDEX IF NOT EXISTS uix_transaction_classifications_transaction_id
+ON k_sol_transaction_classifications (transaction_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_transaction_classifications(classification_kind)`.
+async fn create_idx_transaction_classifications_kind(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_transaction_classifications_kind",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_transaction_classifications_kind
+ON k_sol_transaction_classifications (classification_kind)
+        "#,
+    )
+    .await;
+}
+
+/// Creates `k_sol_protocol_candidates`.
+async fn create_tbl_protocol_candidates(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_tbl_protocol_candidates",
+        r#"
+CREATE TABLE IF NOT EXISTS k_sol_protocol_candidates (
+    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    transaction_id INTEGER NOT NULL,
+    instruction_id INTEGER NULL,
+    signature TEXT NOT NULL,
+    slot INTEGER NULL,
+    program_id TEXT NOT NULL,
+    program_name_hint TEXT NULL,
+    candidate_protocol TEXT NULL,
+    candidate_surface TEXT NULL,
+    reason TEXT NOT NULL,
+    evidence_json TEXT NOT NULL,
+    created_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_protocol_candidates(transaction_id)`.
+async fn create_idx_protocol_candidates_transaction_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_protocol_candidates_transaction_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_protocol_candidates_transaction_id
+ON k_sol_protocol_candidates (transaction_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_protocol_candidates(program_id)`.
+async fn create_idx_protocol_candidates_program_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_protocol_candidates_program_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_protocol_candidates_program_id
+ON k_sol_protocol_candidates (program_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates `k_sol_pool_lifecycle_events`.
+async fn create_tbl_pool_lifecycle_events(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_tbl_pool_lifecycle_events",
+        r#"
+CREATE TABLE IF NOT EXISTS k_sol_pool_lifecycle_events (
+    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    transaction_id INTEGER NOT NULL,
+    decoded_event_id INTEGER NULL,
+    dex_id INTEGER NULL,
+    pool_id INTEGER NULL,
+    pair_id INTEGER NULL,
+    signature TEXT NOT NULL,
+    slot INTEGER NULL,
+    protocol_name TEXT NOT NULL,
+    program_id TEXT NOT NULL,
+    event_kind TEXT NOT NULL,
+    pool_account TEXT NULL,
+    token_a_mint TEXT NULL,
+    token_b_mint TEXT NULL,
+    payload_json TEXT NOT NULL,
+    executed_at TEXT NOT NULL,
+    created_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_pool_lifecycle_events(transaction_id)`.
+async fn create_idx_pool_lifecycle_events_transaction_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_pool_lifecycle_events_transaction_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_pool_lifecycle_events_transaction_id
+ON k_sol_pool_lifecycle_events (transaction_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_pool_lifecycle_events(pool_id)`.
+async fn create_idx_pool_lifecycle_events_pool_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_pool_lifecycle_events_pool_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_pool_lifecycle_events_pool_id
+ON k_sol_pool_lifecycle_events (pool_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates partial unique index on `k_sol_pool_lifecycle_events(decoded_event_id)`.
+async fn create_uix_pool_lifecycle_events_decoded_event_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_uix_pool_lifecycle_events_decoded_event_id",
+        r#"
+CREATE UNIQUE INDEX IF NOT EXISTS uix_pool_lifecycle_events_decoded_event_id
+ON k_sol_pool_lifecycle_events (decoded_event_id)
+WHERE decoded_event_id IS NOT NULL
+        "#,
+    )
+    .await;
+}
+
+/// Creates `k_sol_fee_events`.
+async fn create_tbl_fee_events(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_tbl_fee_events",
+        r#"
+CREATE TABLE IF NOT EXISTS k_sol_fee_events (
+    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    transaction_id INTEGER NOT NULL,
+    decoded_event_id INTEGER NULL,
+    dex_id INTEGER NULL,
+    pool_id INTEGER NULL,
+    pair_id INTEGER NULL,
+    signature TEXT NOT NULL,
+    slot INTEGER NULL,
+    protocol_name TEXT NOT NULL,
+    program_id TEXT NOT NULL,
+    event_kind TEXT NOT NULL,
+    pool_account TEXT NULL,
+    actor_wallet TEXT NULL,
+    fee_token_mint TEXT NULL,
+    fee_amount_raw TEXT NULL,
+    payload_json TEXT NOT NULL,
+    executed_at TEXT NOT NULL,
+    created_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_fee_events(transaction_id)`.
+async fn create_idx_fee_events_transaction_id(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_fee_events_transaction_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_fee_events_transaction_id
+ON k_sol_fee_events (transaction_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_fee_events(pool_id)`.
+async fn create_idx_fee_events_pool_id(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_fee_events_pool_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_fee_events_pool_id
+ON k_sol_fee_events (pool_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates partial unique index on `k_sol_fee_events(decoded_event_id)`.
+async fn create_uix_fee_events_decoded_event_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_uix_fee_events_decoded_event_id",
+        r#"
+CREATE UNIQUE INDEX IF NOT EXISTS uix_fee_events_decoded_event_id
+ON k_sol_fee_events (decoded_event_id)
+WHERE decoded_event_id IS NOT NULL
+        "#,
+    )
+    .await;
+}
+
+/// Creates `k_sol_reward_events`.
+async fn create_tbl_reward_events(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_tbl_reward_events",
+        r#"
+CREATE TABLE IF NOT EXISTS k_sol_reward_events (
+    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    transaction_id INTEGER NOT NULL,
+    decoded_event_id INTEGER NULL,
+    dex_id INTEGER NULL,
+    pool_id INTEGER NULL,
+    pair_id INTEGER NULL,
+    signature TEXT NOT NULL,
+    slot INTEGER NULL,
+    protocol_name TEXT NOT NULL,
+    program_id TEXT NOT NULL,
+    event_kind TEXT NOT NULL,
+    pool_account TEXT NULL,
+    actor_wallet TEXT NULL,
+    reward_token_mint TEXT NULL,
+    reward_amount_raw TEXT NULL,
+    payload_json TEXT NOT NULL,
+    executed_at TEXT NOT NULL,
+    created_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_reward_events(transaction_id)`.
+async fn create_idx_reward_events_transaction_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_reward_events_transaction_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_reward_events_transaction_id
+ON k_sol_reward_events (transaction_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_reward_events(pool_id)`.
+async fn create_idx_reward_events_pool_id(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_reward_events_pool_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_reward_events_pool_id
+ON k_sol_reward_events (pool_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates partial unique index on `k_sol_reward_events(decoded_event_id)`.
+async fn create_uix_reward_events_decoded_event_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_uix_reward_events_decoded_event_id",
+        r#"
+CREATE UNIQUE INDEX IF NOT EXISTS uix_reward_events_decoded_event_id
+ON k_sol_reward_events (decoded_event_id)
+WHERE decoded_event_id IS NOT NULL
+        "#,
+    )
+    .await;
+}
+
+/// Creates `k_sol_pool_admin_events`.
+async fn create_tbl_pool_admin_events(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_tbl_pool_admin_events",
+        r#"
+CREATE TABLE IF NOT EXISTS k_sol_pool_admin_events (
+    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    transaction_id INTEGER NOT NULL,
+    decoded_event_id INTEGER NULL,
+    dex_id INTEGER NULL,
+    pool_id INTEGER NULL,
+    pair_id INTEGER NULL,
+    signature TEXT NOT NULL,
+    slot INTEGER NULL,
+    protocol_name TEXT NOT NULL,
+    program_id TEXT NOT NULL,
+    event_kind TEXT NOT NULL,
+    pool_account TEXT NULL,
+    actor_wallet TEXT NULL,
+    admin_action TEXT NULL,
+    payload_json TEXT NOT NULL,
+    executed_at TEXT NOT NULL,
+    created_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_pool_admin_events(transaction_id)`.
+async fn create_idx_pool_admin_events_transaction_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_pool_admin_events_transaction_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_pool_admin_events_transaction_id
+ON k_sol_pool_admin_events (transaction_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates index on `k_sol_pool_admin_events(pool_id)`.
+async fn create_idx_pool_admin_events_pool_id(pool: &sqlx::SqlitePool) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_idx_pool_admin_events_pool_id",
+        r#"
+CREATE INDEX IF NOT EXISTS idx_pool_admin_events_pool_id
+ON k_sol_pool_admin_events (pool_id)
+        "#,
+    )
+    .await;
+}
+
+/// Creates partial unique index on `k_sol_pool_admin_events(decoded_event_id)`.
+async fn create_uix_pool_admin_events_decoded_event_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::Error> {
+    return execute_sqlite_schema_statement(
+        pool,
+        "create_uix_pool_admin_events_decoded_event_id",
+        r#"
+CREATE UNIQUE INDEX IF NOT EXISTS uix_pool_admin_events_decoded_event_id
+ON k_sol_pool_admin_events (decoded_event_id)
+WHERE decoded_event_id IS NOT NULL
+        "#,
+    )
+    .await;
+}