0.7.1 for Real ! - it was 0.7.0 before, not 0.7.1 !!

kb_lib/src/db/dtos.rs

@@ -19,21 +19,27 @@ mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
+mod chain_instruction;
+mod chain_slot;
+mod chain_transaction;
 
-pub use crate::db::dtos::analysis_signal::KbAnalysisSignalDto;
-pub use crate::db::dtos::db_metadata::KbDbMetadataDto;
-pub use crate::db::dtos::db_runtime_event::KbDbRuntimeEventDto;
-pub use crate::db::dtos::dex::KbDexDto;
-pub use crate::db::dtos::known_http_endpoint::KbKnownHttpEndpointDto;
-pub use crate::db::dtos::known_ws_endpoint::KbKnownWsEndpointDto;
-pub use crate::db::dtos::liquidity_event::KbLiquidityEventDto;
-pub use crate::db::dtos::observed_token::KbObservedTokenDto;
-pub use crate::db::dtos::onchain_observation::KbOnchainObservationDto;
-pub use crate::db::dtos::pair::KbPairDto;
-pub use crate::db::dtos::pool::KbPoolDto;
-pub use crate::db::dtos::pool_listing::KbPoolListingDto;
-pub use crate::db::dtos::pool_token::KbPoolTokenDto;
-pub use crate::db::dtos::swap::KbSwapDto;
-pub use crate::db::dtos::token::KbTokenDto;
-pub use crate::db::dtos::token_burn_event::KbTokenBurnEventDto;
-pub use crate::db::dtos::token_mint_event::KbTokenMintEventDto;
+pub use analysis_signal::KbAnalysisSignalDto;
+pub use db_metadata::KbDbMetadataDto;
+pub use db_runtime_event::KbDbRuntimeEventDto;
+pub use dex::KbDexDto;
+pub use known_http_endpoint::KbKnownHttpEndpointDto;
+pub use known_ws_endpoint::KbKnownWsEndpointDto;
+pub use liquidity_event::KbLiquidityEventDto;
+pub use observed_token::KbObservedTokenDto;
+pub use onchain_observation::KbOnchainObservationDto;
+pub use pair::KbPairDto;
+pub use pool::KbPoolDto;
+pub use pool_listing::KbPoolListingDto;
+pub use pool_token::KbPoolTokenDto;
+pub use swap::KbSwapDto;
+pub use token::KbTokenDto;
+pub use token_burn_event::KbTokenBurnEventDto;
+pub use token_mint_event::KbTokenMintEventDto;
+pub use chain_instruction::KbChainInstructionDto;
+pub use chain_slot::KbChainSlotDto;
+pub use chain_transaction::KbChainTransactionDto;

kb_lib/src/db/dtos/chain_instruction.rs

@@ -0,0 +1,140 @@
+// file: kb_lib/src/db/dtos/chain_instruction.rs
+
+//! Application-facing normalized chain instruction DTO.
+
+/// Application-facing normalized chain instruction DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct KbChainInstructionDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Parent transaction id.
+    pub transaction_id: i64,
+    /// Optional parent instruction id for inner instructions.
+    pub parent_instruction_id: std::option::Option<i64>,
+    /// Outer instruction index.
+    pub instruction_index: u32,
+    /// Optional inner instruction index.
+    pub inner_instruction_index: std::option::Option<u32>,
+    /// Optional program id.
+    pub program_id: std::option::Option<std::string::String>,
+    /// Optional program name.
+    pub program_name: std::option::Option<std::string::String>,
+    /// Optional stack height.
+    pub stack_height: std::option::Option<u32>,
+    /// Serialized accounts JSON array.
+    pub accounts_json: std::string::String,
+    /// Optional serialized data JSON.
+    pub data_json: std::option::Option<std::string::String>,
+    /// Optional parsed type.
+    pub parsed_type: std::option::Option<std::string::String>,
+    /// Optional serialized parsed JSON.
+    pub parsed_json: std::option::Option<std::string::String>,
+    /// Creation timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl KbChainInstructionDto {
+    /// Creates a new chain instruction DTO.
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        transaction_id: i64,
+        parent_instruction_id: std::option::Option<i64>,
+        instruction_index: u32,
+        inner_instruction_index: std::option::Option<u32>,
+        program_id: std::option::Option<std::string::String>,
+        program_name: std::option::Option<std::string::String>,
+        stack_height: std::option::Option<u32>,
+        accounts_json: std::string::String,
+        data_json: std::option::Option<std::string::String>,
+        parsed_type: std::option::Option<std::string::String>,
+        parsed_json: std::option::Option<std::string::String>,
+    ) -> Self {
+        Self {
+            id: None,
+            transaction_id,
+            parent_instruction_id,
+            instruction_index,
+            inner_instruction_index,
+            program_id,
+            program_name,
+            stack_height,
+            accounts_json,
+            data_json,
+            parsed_type,
+            parsed_json,
+            created_at: chrono::Utc::now(),
+        }
+    }
+}
+
+impl TryFrom<crate::KbChainInstructionEntity> for KbChainInstructionDto {
+    type Error = crate::KbError;
+
+    fn try_from(entity: crate::KbChainInstructionEntity) -> Result<Self, Self::Error> {
+        let instruction_index_result = u32::try_from(entity.instruction_index);
+        let instruction_index = match instruction_index_result {
+            Ok(instruction_index) => instruction_index,
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot convert chain instruction instruction_index '{}' to u32: {}",
+                    entity.instruction_index, error
+                )));
+            }
+        };
+        let inner_instruction_index = match entity.inner_instruction_index {
+            Some(inner_instruction_index) => {
+                let inner_instruction_index_result = u32::try_from(inner_instruction_index);
+                match inner_instruction_index_result {
+                    Ok(inner_instruction_index) => Some(inner_instruction_index),
+                    Err(error) => {
+                        return Err(crate::KbError::Db(format!(
+                            "cannot convert chain instruction inner_instruction_index '{}' to u32: {}",
+                            inner_instruction_index, error
+                        )));
+                    }
+                }
+            }
+            None => None,
+        };
+        let stack_height = match entity.stack_height {
+            Some(stack_height) => {
+                let stack_height_result = u32::try_from(stack_height);
+                match stack_height_result {
+                    Ok(stack_height) => Some(stack_height),
+                    Err(error) => {
+                        return Err(crate::KbError::Db(format!(
+                            "cannot convert chain instruction stack_height '{}' to u32: {}",
+                            stack_height, 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::KbError::Db(format!(
+                    "cannot parse chain instruction created_at '{}': {}",
+                    entity.created_at, error
+                )));
+            }
+        };
+        Ok(Self {
+            id: Some(entity.id),
+            transaction_id: entity.transaction_id,
+            parent_instruction_id: entity.parent_instruction_id,
+            instruction_index,
+            inner_instruction_index,
+            program_id: entity.program_id,
+            program_name: entity.program_name,
+            stack_height,
+            accounts_json: entity.accounts_json,
+            data_json: entity.data_json,
+            parsed_type: entity.parsed_type,
+            parsed_json: entity.parsed_json,
+            created_at,
+        })
+    }
+}

kb_lib/src/db/dtos/chain_slot.rs

@@ -0,0 +1,95 @@
+// file: kb_lib/src/db/dtos/chain_slot.rs
+
+//! Application-facing normalized chain slot DTO.
+
+/// Application-facing normalized chain slot DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct KbChainSlotDto {
+    /// Slot number.
+    pub slot: u64,
+    /// Optional parent slot number.
+    pub parent_slot: std::option::Option<u64>,
+    /// Optional block time in unix seconds.
+    pub block_time_unix: std::option::Option<i64>,
+    /// Creation timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl KbChainSlotDto {
+    /// Creates a new chain slot DTO.
+    pub fn new(
+        slot: u64,
+        parent_slot: std::option::Option<u64>,
+        block_time_unix: std::option::Option<i64>,
+    ) -> Self {
+        let now = chrono::Utc::now();
+        Self {
+            slot,
+            parent_slot,
+            block_time_unix,
+            created_at: now,
+            updated_at: now,
+        }
+    }
+}
+
+impl TryFrom<crate::KbChainSlotEntity> for KbChainSlotDto {
+    type Error = crate::KbError;
+
+    fn try_from(entity: crate::KbChainSlotEntity) -> Result<Self, Self::Error> {
+        let slot_result = u64::try_from(entity.slot);
+        let slot = match slot_result {
+            Ok(slot) => slot,
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot convert chain slot '{}' to u64: {}",
+                    entity.slot, error
+                )));
+            }
+        };
+        let parent_slot = match entity.parent_slot {
+            Some(parent_slot) => {
+                let parent_slot_result = u64::try_from(parent_slot);
+                match parent_slot_result {
+                    Ok(parent_slot) => Some(parent_slot),
+                    Err(error) => {
+                        return Err(crate::KbError::Db(format!(
+                            "cannot convert chain parent_slot '{}' to u64: {}",
+                            parent_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::KbError::Db(format!(
+                    "cannot parse chain slot 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 chain slot updated_at '{}': {}",
+                    entity.updated_at, error
+                )));
+            }
+        };
+        Ok(Self {
+            slot,
+            parent_slot,
+            block_time_unix: entity.block_time_unix,
+            created_at,
+            updated_at,
+        })
+    }
+}

kb_lib/src/db/dtos/chain_transaction.rs

@@ -0,0 +1,115 @@
+// file: kb_lib/src/db/dtos/chain_transaction.rs
+
+//! Application-facing normalized chain transaction DTO.
+
+/// Application-facing normalized chain transaction DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct KbChainTransactionDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Transaction signature.
+    pub signature: std::string::String,
+    /// Optional slot number.
+    pub slot: std::option::Option<u64>,
+    /// Optional block time in unix seconds.
+    pub block_time_unix: std::option::Option<i64>,
+    /// Optional source endpoint name.
+    pub source_endpoint_name: std::option::Option<std::string::String>,
+    /// Optional version text.
+    pub version_text: std::option::Option<std::string::String>,
+    /// Optional serialized transaction error JSON.
+    pub err_json: std::option::Option<std::string::String>,
+    /// Optional serialized meta JSON.
+    pub meta_json: std::option::Option<std::string::String>,
+    /// Serialized full transaction JSON.
+    pub transaction_json: std::string::String,
+    /// Creation timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl KbChainTransactionDto {
+    /// Creates a new chain transaction DTO.
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        signature: std::string::String,
+        slot: std::option::Option<u64>,
+        block_time_unix: std::option::Option<i64>,
+        source_endpoint_name: std::option::Option<std::string::String>,
+        version_text: std::option::Option<std::string::String>,
+        err_json: std::option::Option<std::string::String>,
+        meta_json: std::option::Option<std::string::String>,
+        transaction_json: std::string::String,
+    ) -> Self {
+        let now = chrono::Utc::now();
+        Self {
+            id: None,
+            signature,
+            slot,
+            block_time_unix,
+            source_endpoint_name,
+            version_text,
+            err_json,
+            meta_json,
+            transaction_json,
+            created_at: now,
+            updated_at: now,
+        }
+    }
+}
+
+impl TryFrom<crate::KbChainTransactionEntity> for KbChainTransactionDto {
+    type Error = crate::KbError;
+
+    fn try_from(entity: crate::KbChainTransactionEntity) -> 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::KbError::Db(format!(
+                            "cannot convert chain transaction 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::KbError::Db(format!(
+                    "cannot parse chain transaction 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 chain transaction updated_at '{}': {}",
+                    entity.updated_at, error
+                )));
+            }
+        };
+        Ok(Self {
+            id: Some(entity.id),
+            signature: entity.signature,
+            slot,
+            block_time_unix: entity.block_time_unix,
+            source_endpoint_name: entity.source_endpoint_name,
+            version_text: entity.version_text,
+            err_json: entity.err_json,
+            meta_json: entity.meta_json,
+            transaction_json: entity.transaction_json,
+            created_at,
+            updated_at,
+        })
+    }
+}

kb_lib/src/db/entities.rs

@@ -21,21 +21,27 @@ mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
+mod chain_instruction;
+mod chain_slot;
+mod chain_transaction;
 
-pub use crate::db::entities::analysis_signal::KbAnalysisSignalEntity;
-pub use crate::db::entities::db_metadata::KbDbMetadataEntity;
-pub use crate::db::entities::db_runtime_event::KbDbRuntimeEventEntity;
-pub use crate::db::entities::dex::KbDexEntity;
-pub use crate::db::entities::known_http_endpoint::KbKnownHttpEndpointEntity;
-pub use crate::db::entities::known_ws_endpoint::KbKnownWsEndpointEntity;
-pub use crate::db::entities::liquidity_event::KbLiquidityEventEntity;
-pub use crate::db::entities::observed_token::KbObservedTokenEntity;
-pub use crate::db::entities::onchain_observation::KbOnchainObservationEntity;
-pub use crate::db::entities::pair::KbPairEntity;
-pub use crate::db::entities::pool::KbPoolEntity;
-pub use crate::db::entities::pool_listing::KbPoolListingEntity;
-pub use crate::db::entities::pool_token::KbPoolTokenEntity;
-pub use crate::db::entities::swap::KbSwapEntity;
-pub use crate::db::entities::token::KbTokenEntity;
-pub use crate::db::entities::token_burn_event::KbTokenBurnEventEntity;
-pub use crate::db::entities::token_mint_event::KbTokenMintEventEntity;
+pub use analysis_signal::KbAnalysisSignalEntity;
+pub use db_metadata::KbDbMetadataEntity;
+pub use db_runtime_event::KbDbRuntimeEventEntity;
+pub use dex::KbDexEntity;
+pub use known_http_endpoint::KbKnownHttpEndpointEntity;
+pub use known_ws_endpoint::KbKnownWsEndpointEntity;
+pub use liquidity_event::KbLiquidityEventEntity;
+pub use observed_token::KbObservedTokenEntity;
+pub use onchain_observation::KbOnchainObservationEntity;
+pub use pair::KbPairEntity;
+pub use pool::KbPoolEntity;
+pub use pool_listing::KbPoolListingEntity;
+pub use pool_token::KbPoolTokenEntity;
+pub use swap::KbSwapEntity;
+pub use token::KbTokenEntity;
+pub use token_burn_event::KbTokenBurnEventEntity;
+pub use token_mint_event::KbTokenMintEventEntity;
+pub use chain_instruction::KbChainInstructionEntity;
+pub use chain_slot::KbChainSlotEntity;
+pub use chain_transaction::KbChainTransactionEntity;

kb_lib/src/db/entities/chain_instruction.rs

@@ -0,0 +1,34 @@
+// file: kb_lib/src/db/entities/chain_instruction.rs
+
+//! Database entity for one normalized Solana instruction row.
+
+/// Persisted Solana instruction row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct KbChainInstructionEntity {
+    /// Internal row id.
+    pub id: i64,
+    /// Parent transaction id.
+    pub transaction_id: i64,
+    /// Optional parent instruction id for inner instructions.
+    pub parent_instruction_id: std::option::Option<i64>,
+    /// Top-level instruction index.
+    pub instruction_index: i64,
+    /// Optional inner instruction index.
+    pub inner_instruction_index: std::option::Option<i64>,
+    /// Optional program id.
+    pub program_id: std::option::Option<std::string::String>,
+    /// Optional program name.
+    pub program_name: std::option::Option<std::string::String>,
+    /// Optional stack height.
+    pub stack_height: std::option::Option<i64>,
+    /// Accounts JSON array.
+    pub accounts_json: std::string::String,
+    /// Optional data JSON.
+    pub data_json: std::option::Option<std::string::String>,
+    /// Optional parsed type.
+    pub parsed_type: std::option::Option<std::string::String>,
+    /// Optional parsed payload JSON.
+    pub parsed_json: std::option::Option<std::string::String>,
+    /// Creation timestamp.
+    pub created_at: std::string::String,
+}

kb_lib/src/db/entities/chain_slot.rs

@@ -0,0 +1,19 @@
+
+// file: kb_lib/src/db/entities/chain_slot.rs
+
+//! Database entity for one observed Solana slot.
+
+/// Persisted Solana slot row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct KbChainSlotEntity {
+    /// Slot number.
+    pub slot: i64,
+    /// Optional parent slot number.
+    pub parent_slot: std::option::Option<i64>,
+    /// Optional block time in unix seconds.
+    pub block_time_unix: std::option::Option<i64>,
+    /// Creation timestamp.
+    pub created_at: std::string::String,
+    /// Update timestamp.
+    pub updated_at: std::string::String,
+}

kb_lib/src/db/entities/chain_transaction.rs

@@ -0,0 +1,30 @@
+// file: kb_lib/src/db/entities/chain_transaction.rs
+
+//! Database entity for one resolved Solana transaction.
+
+/// Persisted Solana transaction row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct KbChainTransactionEntity {
+    /// Internal row id.
+    pub id: i64,
+    /// Transaction signature.
+    pub signature: std::string::String,
+    /// Optional slot number.
+    pub slot: std::option::Option<i64>,
+    /// Optional block time in unix seconds.
+    pub block_time_unix: std::option::Option<i64>,
+    /// Optional logical endpoint name that resolved the transaction.
+    pub source_endpoint_name: std::option::Option<std::string::String>,
+    /// Optional version text.
+    pub version_text: std::option::Option<std::string::String>,
+    /// Optional transaction error JSON.
+    pub err_json: std::option::Option<std::string::String>,
+    /// Optional transaction meta JSON.
+    pub meta_json: std::option::Option<std::string::String>,
+    /// Full transaction JSON.
+    pub transaction_json: std::string::String,
+    /// Creation timestamp.
+    pub created_at: std::string::String,
+    /// Update timestamp.
+    pub updated_at: std::string::String,
+}

kb_lib/src/db/queries.rs

@@ -23,46 +23,58 @@ mod swap;
 mod token;
 mod token_burn_event;
 mod token_mint_event;
+mod chain_instruction;
+mod chain_slot;
+mod chain_transaction;
 
-pub use crate::db::queries::analysis_signal::insert_analysis_signal;
-pub use crate::db::queries::analysis_signal::list_recent_analysis_signals;
-pub use crate::db::queries::db_metadata::get_db_metadata;
-pub use crate::db::queries::db_metadata::list_db_metadata;
-pub use crate::db::queries::db_metadata::upsert_db_metadata;
-pub use crate::db::queries::db_runtime_event::insert_db_runtime_event;
-pub use crate::db::queries::db_runtime_event::list_recent_db_runtime_events;
-pub use crate::db::queries::dex::get_dex_by_code;
-pub use crate::db::queries::dex::list_dexes;
-pub use crate::db::queries::dex::upsert_dex;
-pub use crate::db::queries::known_http_endpoint::get_known_http_endpoint;
-pub use crate::db::queries::known_http_endpoint::list_known_http_endpoints;
-pub use crate::db::queries::known_http_endpoint::upsert_known_http_endpoint;
-pub use crate::db::queries::known_ws_endpoint::get_known_ws_endpoint;
-pub use crate::db::queries::known_ws_endpoint::list_known_ws_endpoints;
-pub use crate::db::queries::known_ws_endpoint::upsert_known_ws_endpoint;
-pub use crate::db::queries::liquidity_event::list_recent_liquidity_events;
-pub use crate::db::queries::liquidity_event::upsert_liquidity_event;
-pub use crate::db::queries::observed_token::get_observed_token_by_mint;
-pub use crate::db::queries::observed_token::list_observed_tokens;
-pub use crate::db::queries::observed_token::upsert_observed_token;
-pub use crate::db::queries::onchain_observation::insert_onchain_observation;
-pub use crate::db::queries::onchain_observation::list_recent_onchain_observations;
-pub use crate::db::queries::pair::get_pair_by_pool_id;
-pub use crate::db::queries::pair::list_pairs;
-pub use crate::db::queries::pair::upsert_pair;
-pub use crate::db::queries::pool::get_pool_by_address;
-pub use crate::db::queries::pool::list_pools;
-pub use crate::db::queries::pool::upsert_pool;
-pub use crate::db::queries::pool_listing::get_pool_listing_by_pool_id;
-pub use crate::db::queries::pool_listing::list_pool_listings;
-pub use crate::db::queries::pool_listing::upsert_pool_listing;
-pub use crate::db::queries::pool_token::list_pool_tokens_by_pool_id;
-pub use crate::db::queries::pool_token::upsert_pool_token;
-pub use crate::db::queries::swap::list_recent_swaps;
-pub use crate::db::queries::swap::upsert_swap;
-pub use crate::db::queries::token::get_token_by_mint;
-pub use crate::db::queries::token::upsert_token;
-pub use crate::db::queries::token_burn_event::list_recent_token_burn_events;
-pub use crate::db::queries::token_burn_event::upsert_token_burn_event;
-pub use crate::db::queries::token_mint_event::list_recent_token_mint_events;
-pub use crate::db::queries::token_mint_event::upsert_token_mint_event;
+pub use analysis_signal::insert_analysis_signal;
+pub use analysis_signal::list_recent_analysis_signals;
+pub use db_metadata::get_db_metadata;
+pub use db_metadata::list_db_metadata;
+pub use db_metadata::upsert_db_metadata;
+pub use db_runtime_event::insert_db_runtime_event;
+pub use db_runtime_event::list_recent_db_runtime_events;
+pub use dex::get_dex_by_code;
+pub use dex::list_dexes;
+pub use dex::upsert_dex;
+pub use known_http_endpoint::get_known_http_endpoint;
+pub use known_http_endpoint::list_known_http_endpoints;
+pub use known_http_endpoint::upsert_known_http_endpoint;
+pub use known_ws_endpoint::get_known_ws_endpoint;
+pub use known_ws_endpoint::list_known_ws_endpoints;
+pub use known_ws_endpoint::upsert_known_ws_endpoint;
+pub use liquidity_event::list_recent_liquidity_events;
+pub use liquidity_event::upsert_liquidity_event;
+pub use observed_token::get_observed_token_by_mint;
+pub use observed_token::list_observed_tokens;
+pub use observed_token::upsert_observed_token;
+pub use onchain_observation::insert_onchain_observation;
+pub use onchain_observation::list_recent_onchain_observations;
+pub use pair::get_pair_by_pool_id;
+pub use pair::list_pairs;
+pub use pair::upsert_pair;
+pub use pool::get_pool_by_address;
+pub use pool::list_pools;
+pub use pool::upsert_pool;
+pub use pool_listing::get_pool_listing_by_pool_id;
+pub use pool_listing::list_pool_listings;
+pub use pool_listing::upsert_pool_listing;
+pub use pool_token::list_pool_tokens_by_pool_id;
+pub use pool_token::upsert_pool_token;
+pub use swap::list_recent_swaps;
+pub use swap::upsert_swap;
+pub use token::get_token_by_mint;
+pub use token::upsert_token;
+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 chain_instruction::list_chain_instructions_by_transaction_id;
+pub use chain_instruction::insert_chain_instruction;
+pub use chain_instruction::delete_chain_instructions_by_transaction_id;
+pub use chain_slot::list_recent_chain_slots;
+pub use chain_slot::upsert_chain_slot;
+pub use chain_slot::get_chain_slot;
+pub use chain_transaction::list_recent_chain_transactions;
+pub use chain_transaction::upsert_chain_transaction;
+pub use chain_transaction::get_chain_transaction_by_signature;

kb_lib/src/db/queries/chain_instruction.rs

@@ -0,0 +1,246 @@
+// file: kb_lib/src/db/queries/chain_instruction.rs
+
+//! Queries for `kb_chain_instructions`.
+
+/// Inserts one normalized chain instruction row.
+pub async fn insert_chain_instruction(
+    database: &crate::KbDatabase,
+    dto: &crate::KbChainInstructionDto,
+) -> Result<i64, crate::KbError> {
+    let instruction_index_result = i64::from(dto.instruction_index);
+    let inner_instruction_index = match dto.inner_instruction_index {
+        Some(inner_instruction_index) => Some(i64::from(inner_instruction_index)),
+        None => None,
+    };
+    let stack_height = match dto.stack_height {
+        Some(stack_height) => Some(i64::from(stack_height)),
+        None => None,
+    };
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO kb_chain_instructions (
+    transaction_id,
+    parent_instruction_id,
+    instruction_index,
+    inner_instruction_index,
+    program_id,
+    program_name,
+    stack_height,
+    accounts_json,
+    data_json,
+    parsed_type,
+    parsed_json,
+    created_at
+)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                "#,
+            )
+            .bind(dto.transaction_id)
+            .bind(dto.parent_instruction_id)
+            .bind(instruction_index_result)
+            .bind(inner_instruction_index)
+            .bind(dto.program_id.clone())
+            .bind(dto.program_name.clone())
+            .bind(stack_height)
+            .bind(dto.accounts_json.clone())
+            .bind(dto.data_json.clone())
+            .bind(dto.parsed_type.clone())
+            .bind(dto.parsed_json.clone())
+            .bind(dto.created_at.to_rfc3339())
+            .execute(pool)
+            .await;
+            let insert_result = match query_result {
+                Ok(insert_result) => insert_result,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot insert kb_chain_instructions on sqlite: {}",
+                        error
+                    )));
+                }
+            };
+            Ok(insert_result.last_insert_rowid())
+        }
+    }
+}
+
+/// Lists instructions for one transaction ordered from outer to inner.
+pub async fn list_chain_instructions_by_transaction_id(
+    database: &crate::KbDatabase,
+    transaction_id: i64,
+) -> Result<std::vec::Vec<crate::KbChainInstructionDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbChainInstructionEntity>(
+                r#"
+SELECT
+    id,
+    transaction_id,
+    parent_instruction_id,
+    instruction_index,
+    inner_instruction_index,
+    program_id,
+    program_name,
+    stack_height,
+    accounts_json,
+    data_json,
+    parsed_type,
+    parsed_json,
+    created_at
+FROM kb_chain_instructions
+WHERE transaction_id = ?
+ORDER BY instruction_index ASC, inner_instruction_index ASC, id ASC
+                "#,
+            )
+            .bind(transaction_id)
+            .fetch_all(pool)
+            .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot list kb_chain_instructions for transaction_id '{}' on sqlite: {}",
+                        transaction_id, error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbChainInstructionDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}
+
+/// Deletes all instructions for one transaction id.
+pub async fn delete_chain_instructions_by_transaction_id(
+    database: &crate::KbDatabase,
+    transaction_id: i64,
+) -> Result<(), crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+DELETE FROM kb_chain_instructions
+WHERE transaction_id = ?
+                "#,
+            )
+            .bind(transaction_id)
+            .execute(pool)
+            .await;
+            if let Err(error) = query_result {
+                return Err(crate::KbError::Db(format!(
+                    "cannot delete kb_chain_instructions for transaction_id '{}' on sqlite: {}",
+                    transaction_id, error
+                )));
+            }
+            Ok(())
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    async fn make_database() -> crate::KbDatabase {
+        let tempdir = tempfile::tempdir().expect("tempdir must succeed");
+        let database_path = tempdir.path().join("chain_instruction.sqlite3");
+        let config = crate::KbDatabaseConfig {
+            enabled: true,
+            backend: crate::KbDatabaseBackend::Sqlite,
+            sqlite: crate::KbSqliteDatabaseConfig {
+                path: database_path.to_string_lossy().to_string(),
+                create_if_missing: true,
+                busy_timeout_ms: 5000,
+                max_connections: 1,
+                auto_initialize_schema: true,
+                use_wal: true,
+            },
+        };
+        crate::KbDatabase::connect_and_initialize(&config)
+            .await
+            .expect("database init must succeed")
+    }
+
+    async fn make_transaction(database: &crate::KbDatabase) -> i64 {
+        let dto = crate::KbChainTransactionDto::new(
+            "sig-chain-instruction-1".to_string(),
+            None,
+            None,
+            Some("mainnet_public_http".to_string()),
+            Some("legacy".to_string()),
+            None,
+            None,
+            r#"{"transaction":{"message":{"instructions":[]}}}"#.to_string(),
+        );
+        crate::upsert_chain_transaction(database, &dto)
+            .await
+            .expect("chain transaction upsert must succeed")
+    }
+
+    #[tokio::test]
+    async fn chain_instruction_insert_list_delete_works() {
+        let database = make_database().await;
+        let transaction_id = make_transaction(&database).await;
+        let outer_dto = crate::KbChainInstructionDto::new(
+            transaction_id,
+            None,
+            0,
+            None,
+            Some(crate::SPL_TOKEN_PROGRAM_ID.to_string()),
+            Some("spl-token".to_string()),
+            Some(1),
+            r#"["AccountA","AccountB"]"#.to_string(),
+            Some(r#""raw-data-outer""#.to_string()),
+            Some("transfer".to_string()),
+            Some(r#"{"type":"transfer","info":{"amount":"10"}}"#.to_string()),
+        );
+        let outer_instruction_id = crate::insert_chain_instruction(&database, &outer_dto)
+            .await
+            .expect("outer instruction insert must succeed");
+        assert!(outer_instruction_id > 0);
+        let inner_dto = crate::KbChainInstructionDto::new(
+            transaction_id,
+            Some(outer_instruction_id),
+            0,
+            Some(0),
+            Some(crate::SPL_TOKEN_PROGRAM_ID.to_string()),
+            Some("spl-token".to_string()),
+            Some(2),
+            r#"["InnerA","InnerB"]"#.to_string(),
+            Some(r#""raw-data-inner""#.to_string()),
+            Some("mintTo".to_string()),
+            Some(r#"{"type":"mintTo","info":{"amount":"5"}}"#.to_string()),
+        );
+        let inner_instruction_id = crate::insert_chain_instruction(&database, &inner_dto)
+            .await
+            .expect("inner instruction insert must succeed");
+        assert!(inner_instruction_id > outer_instruction_id);
+        let listed = crate::list_chain_instructions_by_transaction_id(&database, transaction_id)
+            .await
+            .expect("chain instruction list must succeed");
+        assert_eq!(listed.len(), 2);
+        assert_eq!(listed[0].parent_instruction_id, None);
+        assert_eq!(listed[0].instruction_index, 0);
+        assert_eq!(listed[0].inner_instruction_index, None);
+        assert_eq!(listed[0].parsed_type, Some("transfer".to_string()));
+        assert_eq!(listed[1].parent_instruction_id, Some(outer_instruction_id));
+        assert_eq!(listed[1].instruction_index, 0);
+        assert_eq!(listed[1].inner_instruction_index, Some(0));
+        assert_eq!(listed[1].parsed_type, Some("mintTo".to_string()));
+        crate::delete_chain_instructions_by_transaction_id(&database, transaction_id)
+            .await
+            .expect("chain instruction delete must succeed");
+        let listed_after_delete =
+            crate::list_chain_instructions_by_transaction_id(&database, transaction_id)
+                .await
+                .expect("chain instruction list after delete must succeed");
+        assert_eq!(listed_after_delete.len(), 0);
+    }
+}

kb_lib/src/db/queries/chain_slot.rs

@@ -0,0 +1,221 @@
+// file: kb_lib/src/db/queries/chain_slot.rs
+
+//! Queries for `kb_chain_slots`.
+
+/// Inserts or updates one normalized chain slot row.
+pub async fn upsert_chain_slot(
+    database: &crate::KbDatabase,
+    dto: &crate::KbChainSlotDto,
+) -> Result<u64, crate::KbError> {
+    let slot_result = i64::try_from(dto.slot);
+    let slot = match slot_result {
+        Ok(slot) => slot,
+        Err(error) => {
+            return Err(crate::KbError::Db(format!(
+                "cannot convert chain slot '{}' to i64: {}",
+                dto.slot, error
+            )));
+        }
+    };
+    let parent_slot = match dto.parent_slot {
+        Some(parent_slot) => {
+            let parent_slot_result = i64::try_from(parent_slot);
+            match parent_slot_result {
+                Ok(parent_slot) => Some(parent_slot),
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot convert chain parent_slot '{}' to i64: {}",
+                        parent_slot, error
+                    )));
+                }
+            }
+        }
+        None => None,
+    };
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO kb_chain_slots (
+    slot,
+    parent_slot,
+    block_time_unix,
+    created_at,
+    updated_at
+)
+VALUES (?, ?, ?, ?, ?)
+ON CONFLICT(slot) DO UPDATE SET
+    parent_slot = excluded.parent_slot,
+    block_time_unix = excluded.block_time_unix,
+    updated_at = excluded.updated_at
+                "#,
+            )
+            .bind(slot)
+            .bind(parent_slot)
+            .bind(dto.block_time_unix)
+            .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_chain_slots on sqlite: {}",
+                    error
+                )));
+            }
+            Ok(dto.slot)
+        }
+    }
+}
+
+/// Reads one chain slot row by slot number.
+pub async fn get_chain_slot(
+    database: &crate::KbDatabase,
+    slot: u64,
+) -> Result<std::option::Option<crate::KbChainSlotDto>, crate::KbError> {
+    let slot_result = i64::try_from(slot);
+    let slot_i64 = match slot_result {
+        Ok(slot_i64) => slot_i64,
+        Err(error) => {
+            return Err(crate::KbError::Db(format!(
+                "cannot convert requested chain slot '{}' to i64: {}",
+                slot, error
+            )));
+        }
+    };
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbChainSlotEntity>(
+                r#"
+SELECT
+    slot,
+    parent_slot,
+    block_time_unix,
+    created_at,
+    updated_at
+FROM kb_chain_slots
+WHERE slot = ?
+LIMIT 1
+                "#,
+            )
+            .bind(slot_i64)
+            .fetch_optional(pool)
+            .await;
+            let entity_option = match query_result {
+                Ok(entity_option) => entity_option,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot fetch kb_chain_slots for slot '{}' on sqlite: {}",
+                        slot, error
+                    )));
+                }
+            };
+            match entity_option {
+                Some(entity) => {
+                    let dto_result = crate::KbChainSlotDto::try_from(entity);
+                    match dto_result {
+                        Ok(dto) => Ok(Some(dto)),
+                        Err(error) => Err(error),
+                    }
+                }
+                None => Ok(None),
+            }
+        }
+    }
+}
+
+/// Lists recent chain slots ordered from newest to oldest.
+pub async fn list_recent_chain_slots(
+    database: &crate::KbDatabase,
+    limit: u32,
+) -> Result<std::vec::Vec<crate::KbChainSlotDto>, crate::KbError> {
+    if limit == 0 {
+        return Ok(std::vec::Vec::new());
+    }
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbChainSlotEntity>(
+                r#"
+SELECT
+    slot,
+    parent_slot,
+    block_time_unix,
+    created_at,
+    updated_at
+FROM kb_chain_slots
+ORDER BY slot DESC
+LIMIT ?
+                "#,
+            )
+            .bind(i64::from(limit))
+            .fetch_all(pool)
+            .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot list kb_chain_slots on sqlite: {}",
+                        error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbChainSlotDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    async fn make_database() -> crate::KbDatabase {
+        let tempdir = tempfile::tempdir().expect("tempdir must succeed");
+        let database_path = tempdir.path().join("chain_slot.sqlite3");
+        let config = crate::KbDatabaseConfig {
+            enabled: true,
+            backend: crate::KbDatabaseBackend::Sqlite,
+            sqlite: crate::KbSqliteDatabaseConfig {
+                path: database_path.to_string_lossy().to_string(),
+                create_if_missing: true,
+                busy_timeout_ms: 5000,
+                max_connections: 1,
+                auto_initialize_schema: true,
+                use_wal: true,
+            },
+        };
+        crate::KbDatabase::connect_and_initialize(&config)
+            .await
+            .expect("database init must succeed")
+    }
+
+    #[tokio::test]
+    async fn chain_slot_roundtrip_works() {
+        let database = make_database().await;
+        let dto = crate::KbChainSlotDto::new(424242, Some(424241), Some(1_777_777_777));
+        let slot = crate::upsert_chain_slot(&database, &dto)
+            .await
+            .expect("chain slot upsert must succeed");
+        assert_eq!(slot, 424242);
+        let fetched = crate::get_chain_slot(&database, 424242)
+            .await
+            .expect("chain slot fetch must succeed")
+            .expect("chain slot must exist");
+        assert_eq!(fetched.slot, 424242);
+        assert_eq!(fetched.parent_slot, Some(424241));
+        assert_eq!(fetched.block_time_unix, Some(1_777_777_777));
+        let listed = crate::list_recent_chain_slots(&database, 10)
+            .await
+            .expect("chain slot list must succeed");
+        assert_eq!(listed.len(), 1);
+        assert_eq!(listed[0].slot, 424242);
+        assert_eq!(listed[0].parent_slot, Some(424241));
+        assert_eq!(listed[0].block_time_unix, Some(1_777_777_777));
+    }
+}

kb_lib/src/db/queries/chain_transaction.rs

@@ -0,0 +1,265 @@
+// file: kb_lib/src/db/queries/chain_transaction.rs
+
+//! Queries for `kb_chain_transactions`.
+
+/// Inserts or updates one normalized chain transaction row.
+pub async fn upsert_chain_transaction(
+    database: &crate::KbDatabase,
+    dto: &crate::KbChainTransactionDto,
+) -> Result<i64, crate::KbError> {
+    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::KbError::Db(format!(
+                        "cannot convert chain transaction slot '{}' to i64: {}",
+                        slot, error
+                    )));
+                }
+            }
+        }
+        None => None,
+    };
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO kb_chain_transactions (
+    signature,
+    slot,
+    block_time_unix,
+    source_endpoint_name,
+    version_text,
+    err_json,
+    meta_json,
+    transaction_json,
+    created_at,
+    updated_at
+)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(signature) DO UPDATE SET
+    slot = excluded.slot,
+    block_time_unix = excluded.block_time_unix,
+    source_endpoint_name = excluded.source_endpoint_name,
+    version_text = excluded.version_text,
+    err_json = excluded.err_json,
+    meta_json = excluded.meta_json,
+    transaction_json = excluded.transaction_json,
+    updated_at = excluded.updated_at
+                "#,
+            )
+            .bind(dto.signature.clone())
+            .bind(slot_i64)
+            .bind(dto.block_time_unix)
+            .bind(dto.source_endpoint_name.clone())
+            .bind(dto.version_text.clone())
+            .bind(dto.err_json.clone())
+            .bind(dto.meta_json.clone())
+            .bind(dto.transaction_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::KbError::Db(format!(
+                    "cannot upsert kb_chain_transactions on sqlite: {}",
+                    error
+                )));
+            }
+            let id_result = sqlx::query_scalar::<sqlx::Sqlite, i64>(
+                r#"
+SELECT id
+FROM kb_chain_transactions
+WHERE signature = ?
+LIMIT 1
+                "#,
+            )
+            .bind(dto.signature.clone())
+            .fetch_one(pool)
+            .await;
+            match id_result {
+                Ok(id) => Ok(id),
+                Err(error) => Err(crate::KbError::Db(format!(
+                    "cannot fetch kb_chain_transactions id for signature '{}' on sqlite: {}",
+                    dto.signature, error
+                ))),
+            }
+        }
+    }
+}
+
+/// Reads one chain transaction row by signature.
+pub async fn get_chain_transaction_by_signature(
+    database: &crate::KbDatabase,
+    signature: &str,
+) -> Result<std::option::Option<crate::KbChainTransactionDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbChainTransactionEntity>(
+                r#"
+SELECT
+    id,
+    signature,
+    slot,
+    block_time_unix,
+    source_endpoint_name,
+    version_text,
+    err_json,
+    meta_json,
+    transaction_json,
+    created_at,
+    updated_at
+FROM kb_chain_transactions
+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::KbError::Db(format!(
+                        "cannot fetch kb_chain_transactions for signature '{}' on sqlite: {}",
+                        signature, error
+                    )));
+                }
+            };
+            match entity_option {
+                Some(entity) => {
+                    let dto_result = crate::KbChainTransactionDto::try_from(entity);
+                    match dto_result {
+                        Ok(dto) => Ok(Some(dto)),
+                        Err(error) => Err(error),
+                    }
+                }
+                None => Ok(None),
+            }
+        }
+    }
+}
+
+/// Lists recent chain transactions ordered from newest to oldest.
+pub async fn list_recent_chain_transactions(
+    database: &crate::KbDatabase,
+    limit: u32,
+) -> Result<std::vec::Vec<crate::KbChainTransactionDto>, crate::KbError> {
+    if limit == 0 {
+        return Ok(std::vec::Vec::new());
+    }
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query_as::<sqlx::Sqlite, crate::KbChainTransactionEntity>(
+                r#"
+SELECT
+    id,
+    signature,
+    slot,
+    block_time_unix,
+    source_endpoint_name,
+    version_text,
+    err_json,
+    meta_json,
+    transaction_json,
+    created_at,
+    updated_at
+FROM kb_chain_transactions
+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::KbError::Db(format!(
+                        "cannot list kb_chain_transactions on sqlite: {}",
+                        error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbChainTransactionDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    async fn make_database() -> crate::KbDatabase {
+        let tempdir = tempfile::tempdir().expect("tempdir must succeed");
+        let database_path = tempdir.path().join("chain_transaction.sqlite3");
+        let config = crate::KbDatabaseConfig {
+            enabled: true,
+            backend: crate::KbDatabaseBackend::Sqlite,
+            sqlite: crate::KbSqliteDatabaseConfig {
+                path: database_path.to_string_lossy().to_string(),
+                create_if_missing: true,
+                busy_timeout_ms: 5000,
+                max_connections: 1,
+                auto_initialize_schema: true,
+                use_wal: true,
+            },
+        };
+        crate::KbDatabase::connect_and_initialize(&config)
+            .await
+            .expect("database init must succeed")
+    }
+
+    #[tokio::test]
+    async fn chain_transaction_roundtrip_works() {
+        let database = make_database().await;
+        let slot_dto = crate::KbChainSlotDto::new(515151, Some(515150), Some(1_700_000_001));
+        crate::upsert_chain_slot(&database, &slot_dto)
+            .await
+            .expect("chain slot upsert must succeed");
+        let dto = crate::KbChainTransactionDto::new(
+            "sig-chain-transaction-1".to_string(),
+            Some(515151),
+            Some(1_700_000_001),
+            Some("helius_primary_http".to_string()),
+            Some("0".to_string()),
+            None,
+            Some(r#"{"fee":5000}"#.to_string()),
+            r#"{"slot":515151,"transaction":{"message":{"instructions":[]}}}"#.to_string(),
+        );
+        let transaction_id = crate::upsert_chain_transaction(&database, &dto)
+            .await
+            .expect("chain transaction upsert must succeed");
+        assert!(transaction_id > 0);
+        let fetched =
+            crate::get_chain_transaction_by_signature(&database, "sig-chain-transaction-1")
+                .await
+                .expect("chain transaction fetch must succeed")
+                .expect("chain transaction must exist");
+        assert_eq!(fetched.id, Some(transaction_id));
+        assert_eq!(fetched.signature, "sig-chain-transaction-1");
+        assert_eq!(fetched.slot, Some(515151));
+        assert_eq!(fetched.block_time_unix, Some(1_700_000_001));
+        assert_eq!(
+            fetched.source_endpoint_name,
+            Some("helius_primary_http".to_string())
+        );
+        assert_eq!(fetched.version_text, Some("0".to_string()));
+        assert_eq!(fetched.meta_json, Some(r#"{"fee":5000}"#.to_string()));
+        let listed = crate::list_recent_chain_transactions(&database, 10)
+            .await
+            .expect("chain transaction list must succeed");
+        assert_eq!(listed.len(), 1);
+        assert_eq!(listed[0].signature, "sig-chain-transaction-1");
+        assert_eq!(listed[0].slot, Some(515151));
+    }
+}

kb_lib/src/db/schema.rs

@@ -190,10 +190,35 @@ pub(crate) async fn ensure_schema(database: &crate::KbDatabase) -> Result<(), cr
             if let Err(error) = result {
                 return Err(error);
             }
+            let result = create_kb_chain_slots_table(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_chain_transactions_table(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_chain_transactions_slot(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_chain_instructions_table(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_chain_instructions_transaction_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_chain_instructions_program_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
             let result = update_schema_version_metadata(database).await;
             if let Err(error) = result {
                 return Err(error);
             }
+
             Ok(())
         }
     }
@@ -1029,6 +1054,126 @@ ON kb_token_burn_events (executed_at)
     .await
 }
 
+/// Creates `kb_chain_slots`.
+async fn create_kb_chain_slots_table(pool: &sqlx::SqlitePool) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_chain_slots_table",
+        r#"
+CREATE TABLE IF NOT EXISTS kb_chain_slots (
+    slot INTEGER NOT NULL PRIMARY KEY,
+    parent_slot INTEGER NULL,
+    block_time_unix INTEGER NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await
+}
+
+/// Creates `kb_chain_transactions`.
+async fn create_kb_chain_transactions_table(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_chain_transactions_table",
+        r#"
+CREATE TABLE IF NOT EXISTS kb_chain_transactions (
+    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    signature TEXT NOT NULL UNIQUE,
+    slot INTEGER NULL,
+    block_time_unix INTEGER NULL,
+    source_endpoint_name TEXT NULL,
+    version_text TEXT NULL,
+    err_json TEXT NULL,
+    meta_json TEXT NULL,
+    transaction_json TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY(slot) REFERENCES kb_chain_slots(slot)
+)
+        "#,
+    )
+    .await
+}
+
+/// Creates index on `kb_chain_transactions(slot)`.
+async fn create_kb_idx_chain_transactions_slot(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_chain_transactions_slot",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_chain_transactions_slot
+ON kb_chain_transactions (slot)
+        "#,
+    )
+    .await
+}
+
+/// Creates `kb_chain_instructions`.
+async fn create_kb_chain_instructions_table(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_chain_instructions_table",
+        r#"
+CREATE TABLE IF NOT EXISTS kb_chain_instructions (
+    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    transaction_id INTEGER NOT NULL,
+    parent_instruction_id INTEGER NULL,
+    instruction_index INTEGER NOT NULL,
+    inner_instruction_index INTEGER NULL,
+    program_id TEXT NULL,
+    program_name TEXT NULL,
+    stack_height INTEGER NULL,
+    accounts_json TEXT NOT NULL,
+    data_json TEXT NULL,
+    parsed_type TEXT NULL,
+    parsed_json TEXT NULL,
+    created_at TEXT NOT NULL,
+    FOREIGN KEY(transaction_id) REFERENCES kb_chain_transactions(id),
+    FOREIGN KEY(parent_instruction_id) REFERENCES kb_chain_instructions(id)
+)
+        "#,
+    )
+    .await
+}
+
+/// Creates index on `kb_chain_instructions(transaction_id)`.
+async fn create_kb_idx_chain_instructions_transaction_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_chain_instructions_transaction_id",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_chain_instructions_transaction_id
+ON kb_chain_instructions (transaction_id)
+        "#,
+    )
+    .await
+}
+
+/// Creates index on `kb_chain_instructions(program_id)`.
+async fn create_kb_idx_chain_instructions_program_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_chain_instructions_program_id",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_chain_instructions_program_id
+ON kb_chain_instructions (program_id)
+        "#,
+    )
+    .await
+}
+
 /// Updates the persisted schema version metadata entry.
 async fn update_schema_version_metadata(
     database: &crate::KbDatabase,

kb_lib/src/db/types.rs

@@ -13,13 +13,13 @@ mod pool_token_role;
 mod runtime_event_level;
 mod swap_trade_side;
 
-pub use crate::db::types::analysis_signal_severity::KbAnalysisSignalSeverity;
-pub use crate::db::types::database_backend::KbDatabaseBackend;
-pub use crate::db::types::liquidity_event_kind::KbLiquidityEventKind;
-pub use crate::db::types::observation_source_kind::KbObservationSourceKind;
-pub use crate::db::types::observed_token_status::KbObservedTokenStatus;
-pub use crate::db::types::pool_kind::KbPoolKind;
-pub use crate::db::types::pool_status::KbPoolStatus;
-pub use crate::db::types::pool_token_role::KbPoolTokenRole;
-pub use crate::db::types::runtime_event_level::KbDbRuntimeEventLevel;
-pub use crate::db::types::swap_trade_side::KbSwapTradeSide;
+pub use analysis_signal_severity::KbAnalysisSignalSeverity;
+pub use database_backend::KbDatabaseBackend;
+pub use liquidity_event_kind::KbLiquidityEventKind;
+pub use observation_source_kind::KbObservationSourceKind;
+pub use observed_token_status::KbObservedTokenStatus;
+pub use pool_kind::KbPoolKind;
+pub use pool_status::KbPoolStatus;
+pub use pool_token_role::KbPoolTokenRole;
+pub use runtime_event_level::KbDbRuntimeEventLevel;
+pub use swap_trade_side::KbSwapTradeSide;