0.7.9

kb_lib/src/db/dtos.rs

@@ -23,6 +23,9 @@ mod chain_instruction;
 mod chain_slot;
 mod chain_transaction;
 mod dex_decoded_event;
+mod launch_surface;
+mod launch_surface_key;
+mod launch_attribution;
 
 pub use analysis_signal::KbAnalysisSignalDto;
 pub use db_metadata::KbDbMetadataDto;
@@ -45,3 +48,6 @@ pub use chain_instruction::KbChainInstructionDto;
 pub use chain_slot::KbChainSlotDto;
 pub use chain_transaction::KbChainTransactionDto;
 pub use dex_decoded_event::KbDexDecodedEventDto;
+pub use launch_surface::KbLaunchSurfaceDto;
+pub use launch_surface_key::KbLaunchSurfaceKeyDto;
+pub use launch_attribution::KbLaunchAttributionDto;

kb_lib/src/db/dtos/launch_attribution.rs

@@ -0,0 +1,104 @@
+// file: kb_lib/src/db/dtos/launch_attribution.rs
+
+//! Launch attribution DTO.
+
+/// Application-facing launch attribution DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct KbLaunchAttributionDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Related launch surface id.
+    pub launch_surface_id: i64,
+    /// Related transaction id.
+    pub transaction_id: i64,
+    /// Related decoded event id.
+    pub decoded_event_id: i64,
+    /// Optional related pool id.
+    pub pool_id: std::option::Option<i64>,
+    /// Optional related pair id.
+    pub pair_id: std::option::Option<i64>,
+    /// Optional related matched key id.
+    pub matched_key_id: std::option::Option<i64>,
+    /// Decoded protocol name.
+    pub protocol_name: std::string::String,
+    /// Match kind used for attribution.
+    pub match_kind: std::string::String,
+    /// Matched value used for attribution.
+    pub matched_value: std::string::String,
+    /// Attribution timestamp.
+    pub attributed_at: chrono::DateTime<chrono::Utc>,
+    /// Update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl KbLaunchAttributionDto {
+    /// Creates a new launch attribution DTO.
+    pub fn new(
+        launch_surface_id: i64,
+        transaction_id: i64,
+        decoded_event_id: i64,
+        pool_id: std::option::Option<i64>,
+        pair_id: std::option::Option<i64>,
+        matched_key_id: std::option::Option<i64>,
+        protocol_name: std::string::String,
+        match_kind: std::string::String,
+        matched_value: std::string::String,
+    ) -> Self {
+        let now = chrono::Utc::now();
+        Self {
+            id: None,
+            launch_surface_id,
+            transaction_id,
+            decoded_event_id,
+            pool_id,
+            pair_id,
+            matched_key_id,
+            protocol_name,
+            match_kind,
+            matched_value,
+            attributed_at: now,
+            updated_at: now,
+        }
+    }
+}
+
+impl TryFrom<crate::KbLaunchAttributionEntity> for KbLaunchAttributionDto {
+    type Error = crate::KbError;
+
+    fn try_from(entity: crate::KbLaunchAttributionEntity) -> Result<Self, Self::Error> {
+        let attributed_at_result = chrono::DateTime::parse_from_rfc3339(&entity.attributed_at);
+        let attributed_at = match attributed_at_result {
+            Ok(attributed_at) => attributed_at.with_timezone(&chrono::Utc),
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot parse launch_attribution attributed_at '{}': {}",
+                    entity.attributed_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 launch_attribution updated_at '{}': {}",
+                    entity.updated_at, error
+                )));
+            }
+        };
+        Ok(Self {
+            id: Some(entity.id),
+            launch_surface_id: entity.launch_surface_id,
+            transaction_id: entity.transaction_id,
+            decoded_event_id: entity.decoded_event_id,
+            pool_id: entity.pool_id,
+            pair_id: entity.pair_id,
+            matched_key_id: entity.matched_key_id,
+            protocol_name: entity.protocol_name,
+            match_kind: entity.match_kind,
+            matched_value: entity.matched_value,
+            attributed_at,
+            updated_at,
+        })
+    }
+}

kb_lib/src/db/dtos/launch_surface.rs

@@ -0,0 +1,79 @@
+// file: kb_lib/src/db/dtos/launch_surface.rs
+
+//! Launch surface DTO.
+
+/// Application-facing launch surface DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct KbLaunchSurfaceDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Stable short code.
+    pub code: std::string::String,
+    /// Display name.
+    pub name: std::string::String,
+    /// Optional protocol family hint.
+    pub protocol_family: std::option::Option<std::string::String>,
+    /// Whether the surface is enabled.
+    pub is_enabled: bool,
+    /// Creation timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl KbLaunchSurfaceDto {
+    /// Creates a new launch surface DTO.
+    pub fn new(
+        code: std::string::String,
+        name: std::string::String,
+        protocol_family: std::option::Option<std::string::String>,
+        is_enabled: bool,
+    ) -> Self {
+        let now = chrono::Utc::now();
+        Self {
+            id: None,
+            code,
+            name,
+            protocol_family,
+            is_enabled,
+            created_at: now,
+            updated_at: now,
+        }
+    }
+}
+
+impl TryFrom<crate::KbLaunchSurfaceEntity> for KbLaunchSurfaceDto {
+    type Error = crate::KbError;
+
+    fn try_from(entity: crate::KbLaunchSurfaceEntity) -> Result<Self, Self::Error> {
+        let created_at_result = chrono::DateTime::parse_from_rfc3339(&entity.created_at);
+        let created_at = match created_at_result {
+            Ok(created_at) => created_at.with_timezone(&chrono::Utc),
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot parse launch_surface 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 launch_surface updated_at '{}': {}",
+                    entity.updated_at, error
+                )));
+            }
+        };
+        Ok(Self {
+            id: Some(entity.id),
+            code: entity.code,
+            name: entity.name,
+            protocol_family: entity.protocol_family,
+            is_enabled: entity.is_enabled != 0,
+            created_at,
+            updated_at,
+        })
+    }
+}

kb_lib/src/db/dtos/launch_surface_key.rs

@@ -0,0 +1,74 @@
+// file: kb_lib/src/db/dtos/launch_surface_key.rs
+
+//! Launch surface key DTO.
+
+/// Application-facing launch surface key DTO.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct KbLaunchSurfaceKeyDto {
+    /// Optional numeric primary key.
+    pub id: std::option::Option<i64>,
+    /// Related launch surface id.
+    pub launch_surface_id: i64,
+    /// Stable key kind.
+    pub match_kind: std::string::String,
+    /// Stable key value.
+    pub match_value: std::string::String,
+    /// Creation timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl KbLaunchSurfaceKeyDto {
+    /// Creates a new launch surface key DTO.
+    pub fn new(
+        launch_surface_id: i64,
+        match_kind: std::string::String,
+        match_value: std::string::String,
+    ) -> Self {
+        let now = chrono::Utc::now();
+        Self {
+            id: None,
+            launch_surface_id,
+            match_kind,
+            match_value,
+            created_at: now,
+            updated_at: now,
+        }
+    }
+}
+
+impl TryFrom<crate::KbLaunchSurfaceKeyEntity> for KbLaunchSurfaceKeyDto {
+    type Error = crate::KbError;
+
+    fn try_from(entity: crate::KbLaunchSurfaceKeyEntity) -> Result<Self, Self::Error> {
+        let created_at_result = chrono::DateTime::parse_from_rfc3339(&entity.created_at);
+        let created_at = match created_at_result {
+            Ok(created_at) => created_at.with_timezone(&chrono::Utc),
+            Err(error) => {
+                return Err(crate::KbError::Db(format!(
+                    "cannot parse launch_surface_key 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 launch_surface_key updated_at '{}': {}",
+                    entity.updated_at, error
+                )));
+            }
+        };
+        Ok(Self {
+            id: Some(entity.id),
+            launch_surface_id: entity.launch_surface_id,
+            match_kind: entity.match_kind,
+            match_value: entity.match_value,
+            created_at,
+            updated_at,
+        })
+    }
+}

kb_lib/src/db/entities.rs

@@ -25,6 +25,9 @@ mod chain_instruction;
 mod chain_slot;
 mod chain_transaction;
 mod dex_decoded_event;
+mod launch_surface;
+mod launch_surface_key;
+mod launch_attribution;
 
 pub use analysis_signal::KbAnalysisSignalEntity;
 pub use db_metadata::KbDbMetadataEntity;
@@ -47,3 +50,6 @@ pub use chain_instruction::KbChainInstructionEntity;
 pub use chain_slot::KbChainSlotEntity;
 pub use chain_transaction::KbChainTransactionEntity;
 pub use dex_decoded_event::KbDexDecodedEventEntity;
+pub use launch_surface::KbLaunchSurfaceEntity;
+pub use launch_surface_key::KbLaunchSurfaceKeyEntity;
+pub use launch_attribution::KbLaunchAttributionEntity;

kb_lib/src/db/entities/launch_attribution.rs

@@ -0,0 +1,32 @@
+// file: kb_lib/src/db/entities/launch_attribution.rs
+
+//! Launch attribution entity.
+
+/// Persisted launch attribution row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct KbLaunchAttributionEntity {
+    /// Numeric primary key.
+    pub id: i64,
+    /// Related launch surface id.
+    pub launch_surface_id: i64,
+    /// Related transaction id.
+    pub transaction_id: i64,
+    /// Related decoded event id.
+    pub decoded_event_id: i64,
+    /// Optional related pool id.
+    pub pool_id: std::option::Option<i64>,
+    /// Optional related pair id.
+    pub pair_id: std::option::Option<i64>,
+    /// Optional related matched key id.
+    pub matched_key_id: std::option::Option<i64>,
+    /// Decoded protocol name.
+    pub protocol_name: std::string::String,
+    /// Match kind used for attribution.
+    pub match_kind: std::string::String,
+    /// Matched value used for attribution.
+    pub matched_value: std::string::String,
+    /// Attribution timestamp encoded as RFC3339 UTC text.
+    pub attributed_at: std::string::String,
+    /// Update timestamp encoded as RFC3339 UTC text.
+    pub updated_at: std::string::String,
+}

kb_lib/src/db/entities/launch_surface.rs

@@ -0,0 +1,22 @@
+// file: kb_lib/src/db/entities/launch_surface.rs
+
+//! Launch surface entity.
+
+/// Persisted launch surface row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct KbLaunchSurfaceEntity {
+    /// Numeric primary key.
+    pub id: i64,
+    /// Stable short code.
+    pub code: std::string::String,
+    /// Display name.
+    pub name: std::string::String,
+    /// Optional protocol family hint.
+    pub protocol_family: std::option::Option<std::string::String>,
+    /// Whether the surface is enabled.
+    pub is_enabled: i64,
+    /// 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/entities/launch_surface_key.rs

@@ -0,0 +1,20 @@
+// file: kb_lib/src/db/entities/launch_surface_key.rs
+
+//! Launch surface key entity.
+
+/// Persisted launch surface matching key row.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, sqlx::FromRow)]
+pub struct KbLaunchSurfaceKeyEntity {
+    /// Numeric primary key.
+    pub id: i64,
+    /// Related launch surface id.
+    pub launch_surface_id: i64,
+    /// Stable key kind, for example `config_account` or `creator`.
+    pub match_kind: std::string::String,
+    /// Stable key value.
+    pub match_value: 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,6 +27,9 @@ mod chain_instruction;
 mod chain_slot;
 mod chain_transaction;
 mod dex_decoded_event;
+mod launch_surface;
+mod launch_surface_key;
+mod launch_attribution;
 
 pub use analysis_signal::insert_analysis_signal;
 pub use analysis_signal::list_recent_analysis_signals;
@@ -82,3 +85,12 @@ pub use chain_transaction::get_chain_transaction_by_signature;
 pub use dex_decoded_event::get_dex_decoded_event_by_key;
 pub use dex_decoded_event::list_dex_decoded_events_by_transaction_id;
 pub use dex_decoded_event::upsert_dex_decoded_event;
+pub use launch_surface::upsert_launch_surface;
+pub use launch_surface::get_launch_surface_by_code;
+pub use launch_surface::list_launch_surfaces;
+pub use launch_surface_key::upsert_launch_surface_key;
+pub use launch_surface_key::get_launch_surface_key_by_match;
+pub use launch_surface_key::list_launch_surface_keys_by_surface_id;
+pub use launch_attribution::upsert_launch_attribution;
+pub use launch_attribution::get_launch_attribution_by_decoded_event_id;
+pub use launch_attribution::list_launch_attributions_by_pool_id;

kb_lib/src/db/queries/launch_attribution.rs

@@ -0,0 +1,181 @@
+// file: kb_lib/src/db/queries/launch_attribution.rs
+
+//! Queries for `kb_launch_attributions`.
+
+/// Inserts or updates one launch attribution row and returns its stable internal id.
+pub async fn upsert_launch_attribution(
+    database: &crate::KbDatabase,
+    dto: &crate::KbLaunchAttributionDto,
+) -> Result<i64, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO kb_launch_attributions (
+    launch_surface_id,
+    transaction_id,
+    decoded_event_id,
+    pool_id,
+    pair_id,
+    matched_key_id,
+    protocol_name,
+    match_kind,
+    matched_value,
+    attributed_at,
+    updated_at
+)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(decoded_event_id) DO UPDATE SET
+    launch_surface_id = excluded.launch_surface_id,
+    transaction_id = excluded.transaction_id,
+    pool_id = excluded.pool_id,
+    pair_id = excluded.pair_id,
+    matched_key_id = excluded.matched_key_id,
+    protocol_name = excluded.protocol_name,
+    match_kind = excluded.match_kind,
+    matched_value = excluded.matched_value,
+    updated_at = excluded.updated_at
+                "#,
+            )
+            .bind(dto.launch_surface_id)
+            .bind(dto.transaction_id)
+            .bind(dto.decoded_event_id)
+            .bind(dto.pool_id)
+            .bind(dto.pair_id)
+            .bind(dto.matched_key_id)
+            .bind(dto.protocol_name.clone())
+            .bind(dto.match_kind.clone())
+            .bind(dto.matched_value.clone())
+            .bind(dto.attributed_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_launch_attributions on sqlite: {}",
+                    error
+                )));
+            }
+            let id_result = sqlx::query_scalar::<sqlx::Sqlite, i64>(
+                r#"
+SELECT id
+FROM kb_launch_attributions
+WHERE decoded_event_id = ?
+LIMIT 1
+                "#,
+            )
+            .bind(dto.decoded_event_id)
+            .fetch_one(pool)
+            .await;
+            match id_result {
+                Ok(id) => Ok(id),
+                Err(error) => Err(crate::KbError::Db(format!(
+                    "cannot fetch kb_launch_attributions id for decoded_event_id '{}' on sqlite: {}",
+                    dto.decoded_event_id, error
+                ))),
+            }
+        }
+    }
+}
+
+/// Returns one launch attribution identified by its decoded-event id, if it exists.
+pub async fn get_launch_attribution_by_decoded_event_id(
+    database: &crate::KbDatabase,
+    decoded_event_id: i64,
+) -> Result<std::option::Option<crate::KbLaunchAttributionDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::KbLaunchAttributionEntity>(
+                    r#"
+SELECT
+    id,
+    launch_surface_id,
+    transaction_id,
+    decoded_event_id,
+    pool_id,
+    pair_id,
+    matched_key_id,
+    protocol_name,
+    match_kind,
+    matched_value,
+    attributed_at,
+    updated_at
+FROM kb_launch_attributions
+WHERE decoded_event_id = ?
+LIMIT 1
+                    "#,
+                )
+                .bind(decoded_event_id)
+                .fetch_optional(pool)
+                .await;
+            let entity_option = match query_result {
+                Ok(entity_option) => entity_option,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot read kb_launch_attributions by decoded_event_id '{}' on sqlite: {}",
+                        decoded_event_id, error
+                    )));
+                }
+            };
+            match entity_option {
+                Some(entity) => crate::KbLaunchAttributionDto::try_from(entity).map(Some),
+                None => Ok(None),
+            }
+        }
+    }
+}
+
+/// Lists all launch attributions attached to one pool id.
+pub async fn list_launch_attributions_by_pool_id(
+    database: &crate::KbDatabase,
+    pool_id: i64,
+) -> Result<std::vec::Vec<crate::KbLaunchAttributionDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::KbLaunchAttributionEntity>(
+                    r#"
+SELECT
+    id,
+    launch_surface_id,
+    transaction_id,
+    decoded_event_id,
+    pool_id,
+    pair_id,
+    matched_key_id,
+    protocol_name,
+    match_kind,
+    matched_value,
+    attributed_at,
+    updated_at
+FROM kb_launch_attributions
+WHERE pool_id = ?
+ORDER BY attributed_at ASC, id ASC
+                    "#,
+                )
+                .bind(pool_id)
+                .fetch_all(pool)
+                .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot list kb_launch_attributions by pool_id '{}' on sqlite: {}",
+                        pool_id, error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbLaunchAttributionDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}

kb_lib/src/db/queries/launch_surface.rs

@@ -0,0 +1,153 @@
+// file: kb_lib/src/db/queries/launch_surface.rs
+
+//! Queries for `kb_launch_surfaces`.
+
+/// Inserts or updates one launch surface row and returns its stable internal id.
+pub async fn upsert_launch_surface(
+    database: &crate::KbDatabase,
+    dto: &crate::KbLaunchSurfaceDto,
+) -> Result<i64, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO kb_launch_surfaces (
+    code,
+    name,
+    protocol_family,
+    is_enabled,
+    created_at,
+    updated_at
+)
+VALUES (?, ?, ?, ?, ?, ?)
+ON CONFLICT(code) DO UPDATE SET
+    name = excluded.name,
+    protocol_family = excluded.protocol_family,
+    is_enabled = excluded.is_enabled,
+    updated_at = excluded.updated_at
+                "#,
+            )
+            .bind(dto.code.clone())
+            .bind(dto.name.clone())
+            .bind(dto.protocol_family.clone())
+            .bind(if dto.is_enabled { 1_i64 } else { 0_i64 })
+            .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_launch_surfaces on sqlite: {}",
+                    error
+                )));
+            }
+            let id_result = sqlx::query_scalar::<sqlx::Sqlite, i64>(
+                r#"
+SELECT id
+FROM kb_launch_surfaces
+WHERE code = ?
+LIMIT 1
+                "#,
+            )
+            .bind(dto.code.clone())
+            .fetch_one(pool)
+            .await;
+            match id_result {
+                Ok(id) => Ok(id),
+                Err(error) => Err(crate::KbError::Db(format!(
+                    "cannot fetch kb_launch_surfaces id for code '{}' on sqlite: {}",
+                    dto.code, error
+                ))),
+            }
+        }
+    }
+}
+
+/// Returns one launch surface identified by its stable short code, if it exists.
+pub async fn get_launch_surface_by_code(
+    database: &crate::KbDatabase,
+    code: &str,
+) -> Result<std::option::Option<crate::KbLaunchSurfaceDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::KbLaunchSurfaceEntity>(
+                    r#"
+SELECT
+    id,
+    code,
+    name,
+    protocol_family,
+    is_enabled,
+    created_at,
+    updated_at
+FROM kb_launch_surfaces
+WHERE code = ?
+LIMIT 1
+                    "#,
+                )
+                .bind(code)
+                .fetch_optional(pool)
+                .await;
+            let entity_option = match query_result {
+                Ok(entity_option) => entity_option,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot read kb_launch_surfaces '{}' on sqlite: {}",
+                        code, error
+                    )));
+                }
+            };
+            match entity_option {
+                Some(entity) => crate::KbLaunchSurfaceDto::try_from(entity).map(Some),
+                None => Ok(None),
+            }
+        }
+    }
+}
+
+/// Lists all persisted launch surfaces ordered by code.
+pub async fn list_launch_surfaces(
+    database: &crate::KbDatabase,
+) -> Result<std::vec::Vec<crate::KbLaunchSurfaceDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::KbLaunchSurfaceEntity>(
+                    r#"
+SELECT
+    id,
+    code,
+    name,
+    protocol_family,
+    is_enabled,
+    created_at,
+    updated_at
+FROM kb_launch_surfaces
+ORDER BY code ASC
+                    "#,
+                )
+                .fetch_all(pool)
+                .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot list kb_launch_surfaces on sqlite: {}",
+                        error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbLaunchSurfaceDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}

kb_lib/src/db/queries/launch_surface_key.rs

@@ -0,0 +1,153 @@
+// file: kb_lib/src/db/queries/launch_surface_key.rs
+
+//! Queries for `kb_launch_surface_keys`.
+
+/// Inserts or updates one launch-surface matching key and returns its stable internal id.
+pub async fn upsert_launch_surface_key(
+    database: &crate::KbDatabase,
+    dto: &crate::KbLaunchSurfaceKeyDto,
+) -> Result<i64, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result = sqlx::query(
+                r#"
+INSERT INTO kb_launch_surface_keys (
+    launch_surface_id,
+    match_kind,
+    match_value,
+    created_at,
+    updated_at
+)
+VALUES (?, ?, ?, ?, ?)
+ON CONFLICT(match_kind, match_value) DO UPDATE SET
+    launch_surface_id = excluded.launch_surface_id,
+    updated_at = excluded.updated_at
+                "#,
+            )
+            .bind(dto.launch_surface_id)
+            .bind(dto.match_kind.clone())
+            .bind(dto.match_value.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_launch_surface_keys on sqlite: {}",
+                    error
+                )));
+            }
+            let id_result = sqlx::query_scalar::<sqlx::Sqlite, i64>(
+                r#"
+SELECT id
+FROM kb_launch_surface_keys
+WHERE match_kind = ? AND match_value = ?
+LIMIT 1
+                "#,
+            )
+            .bind(dto.match_kind.clone())
+            .bind(dto.match_value.clone())
+            .fetch_one(pool)
+            .await;
+            match id_result {
+                Ok(id) => Ok(id),
+                Err(error) => Err(crate::KbError::Db(format!(
+                    "cannot fetch kb_launch_surface_keys id for '{}:{}' on sqlite: {}",
+                    dto.match_kind, dto.match_value, error
+                ))),
+            }
+        }
+    }
+}
+
+/// Returns one launch-surface matching key identified by its kind and value, if it exists.
+pub async fn get_launch_surface_key_by_match(
+    database: &crate::KbDatabase,
+    match_kind: &str,
+    match_value: &str,
+) -> Result<std::option::Option<crate::KbLaunchSurfaceKeyDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::KbLaunchSurfaceKeyEntity>(
+                    r#"
+SELECT
+    id,
+    launch_surface_id,
+    match_kind,
+    match_value,
+    created_at,
+    updated_at
+FROM kb_launch_surface_keys
+WHERE match_kind = ? AND match_value = ?
+LIMIT 1
+                    "#,
+                )
+                .bind(match_kind)
+                .bind(match_value)
+                .fetch_optional(pool)
+                .await;
+            let entity_option = match query_result {
+                Ok(entity_option) => entity_option,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot read kb_launch_surface_keys '{}:{}' on sqlite: {}",
+                        match_kind, match_value, error
+                    )));
+                }
+            };
+            match entity_option {
+                Some(entity) => crate::KbLaunchSurfaceKeyDto::try_from(entity).map(Some),
+                None => Ok(None),
+            }
+        }
+    }
+}
+
+/// Lists all launch-surface matching keys attached to one launch surface id.
+pub async fn list_launch_surface_keys_by_surface_id(
+    database: &crate::KbDatabase,
+    launch_surface_id: i64,
+) -> Result<std::vec::Vec<crate::KbLaunchSurfaceKeyDto>, crate::KbError> {
+    match database.connection() {
+        crate::KbDatabaseConnection::Sqlite(pool) => {
+            let query_result =
+                sqlx::query_as::<sqlx::Sqlite, crate::KbLaunchSurfaceKeyEntity>(
+                    r#"
+SELECT
+    id,
+    launch_surface_id,
+    match_kind,
+    match_value,
+    created_at,
+    updated_at
+FROM kb_launch_surface_keys
+WHERE launch_surface_id = ?
+ORDER BY match_kind ASC, match_value ASC
+                    "#,
+                )
+                .bind(launch_surface_id)
+                .fetch_all(pool)
+                .await;
+            let entities = match query_result {
+                Ok(entities) => entities,
+                Err(error) => {
+                    return Err(crate::KbError::Db(format!(
+                        "cannot list kb_launch_surface_keys by surface_id '{}' on sqlite: {}",
+                        launch_surface_id, error
+                    )));
+                }
+            };
+            let mut dtos = std::vec::Vec::new();
+            for entity in entities {
+                let dto_result = crate::KbLaunchSurfaceKeyDto::try_from(entity);
+                let dto = match dto_result {
+                    Ok(dto) => dto,
+                    Err(error) => return Err(error),
+                };
+                dtos.push(dto);
+            }
+            Ok(dtos)
+        }
+    }
+}

kb_lib/src/db/schema.rs

@@ -230,6 +230,30 @@ pub(crate) async fn ensure_schema(database: &crate::KbDatabase) -> Result<(), cr
             if let Err(error) = result {
                 return Err(error);
             }
+            let result = create_kb_launch_surfaces_table(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_launch_surface_keys_table(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_launch_surface_keys_surface_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_launch_attributions_table(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_launch_attributions_surface_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
+            let result = create_kb_idx_launch_attributions_pool_id(pool).await;
+            if let Err(error) = result {
+                return Err(error);
+            }
             Ok(())
         }
     }
@@ -1253,3 +1277,118 @@ ON kb_dex_decoded_events (transaction_id, instruction_id, event_kind)
     )
     .await
 }
+
+async fn create_kb_launch_surfaces_table(pool: &sqlx::SqlitePool) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_launch_surfaces_table",
+        r#"
+CREATE TABLE IF NOT EXISTS kb_launch_surfaces (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    code TEXT NOT NULL UNIQUE,
+    name TEXT NOT NULL,
+    protocol_family TEXT NULL,
+    is_enabled INTEGER NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_launch_surface_keys_table(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_launch_surface_keys_table",
+        r#"
+CREATE TABLE IF NOT EXISTS kb_launch_surface_keys (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    launch_surface_id INTEGER NOT NULL,
+    match_kind TEXT NOT NULL,
+    match_value TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY(launch_surface_id) REFERENCES kb_launch_surfaces(id) ON DELETE CASCADE,
+    UNIQUE(match_kind, match_value)
+)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_idx_launch_surface_keys_surface_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_launch_surface_keys_surface_id",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_launch_surface_keys_surface_id
+ON kb_launch_surface_keys(launch_surface_id)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_launch_attributions_table(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_launch_attributions_table",
+        r#"
+CREATE TABLE IF NOT EXISTS kb_launch_attributions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    launch_surface_id INTEGER NOT NULL,
+    transaction_id INTEGER NOT NULL,
+    decoded_event_id INTEGER NOT NULL UNIQUE,
+    pool_id INTEGER NULL,
+    pair_id INTEGER NULL,
+    matched_key_id INTEGER NULL,
+    protocol_name TEXT NOT NULL,
+    match_kind TEXT NOT NULL,
+    matched_value TEXT NOT NULL,
+    attributed_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY(launch_surface_id) REFERENCES kb_launch_surfaces(id) ON DELETE CASCADE,
+    FOREIGN KEY(transaction_id) REFERENCES kb_chain_transactions(id) ON DELETE CASCADE,
+    FOREIGN KEY(decoded_event_id) REFERENCES kb_dex_decoded_events(id) ON DELETE CASCADE,
+    FOREIGN KEY(pool_id) REFERENCES kb_pools(id) ON DELETE SET NULL,
+    FOREIGN KEY(pair_id) REFERENCES kb_pairs(id) ON DELETE SET NULL,
+    FOREIGN KEY(matched_key_id) REFERENCES kb_launch_surface_keys(id) ON DELETE SET NULL
+)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_idx_launch_attributions_surface_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_launch_attributions_surface_id",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_launch_attributions_surface_id
+ON kb_launch_attributions(launch_surface_id)
+        "#,
+    )
+    .await
+}
+
+async fn create_kb_idx_launch_attributions_pool_id(
+    pool: &sqlx::SqlitePool,
+) -> Result<(), crate::KbError> {
+    execute_sqlite_schema_statement(
+        pool,
+        "create_kb_idx_launch_attributions_pool_id",
+        r#"
+CREATE INDEX IF NOT EXISTS kb_idx_launch_attributions_pool_id
+ON kb_launch_attributions(pool_id)
+        "#,
+    )
+    .await
+}