0.1.0-pre.004

kb-store/src/contracts/entity/core.rs

@@ -0,0 +1,166 @@
+// file: kb-store/src/contracts/entity/core.rs
+// version: 1
+
+//! Core Solana SQL-like entities.
+
+/// Core transaction SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct CoreTransactionRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Whether the transaction failed on-chain.
+    pub failed: bool,
+    /// Optional canonical raw transaction row id used for lineage when available.
+    pub raw_transaction_id: std::option::Option<i64>,
+    /// Optional raw error JSON extracted from transaction metadata.
+    pub err_json: std::option::Option<serde_json::Value>,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Last update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Core account key SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct CoreAccountKeyRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Parent core transaction technical key.
+    pub transaction_id: i64,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Stable account index after static and loaded keys are resolved.
+    pub account_index: i32,
+    /// Account public key as non-empty base58 text.
+    pub account_key: std::string::String,
+    /// Source category for this account key.
+    pub source: crate::CoreAccountKeySource,
+    /// Whether the resolved account is writable for the transaction.
+    pub writable: bool,
+    /// Whether the resolved account signed the transaction.
+    pub signer: bool,
+    /// Whether the resolved account is executable when known.
+    pub executable: std::option::Option<bool>,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Core instruction SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct CoreInstructionRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Parent core transaction technical key.
+    pub transaction_id: i64,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Stable instruction path, for example `0` or `2/1`.
+    pub instruction_path: std::string::String,
+    /// Program id as non-empty base58 text.
+    pub program_id: std::string::String,
+    /// Instruction accounts as JSON, preserving unresolved forms when needed.
+    pub accounts_json: serde_json::Value,
+    /// Instruction payload JSON while it is still retained in the hot store.
+    pub payload_json: std::option::Option<serde_json::Value>,
+    /// Optional digest of the instruction payload after compaction or purge.
+    pub payload_json_hash: std::option::Option<std::string::String>,
+    /// Current processing state used by instruction-level replay.
+    pub processing_state: crate::CoreInstructionProcessingState,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Last lifecycle update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Core inner instruction SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct CoreInnerInstructionRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Parent core transaction technical key.
+    pub transaction_id: i64,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Parent top-level or inner instruction path.
+    pub parent_instruction_path: std::string::String,
+    /// Stable inner instruction path, for example `2/1`.
+    pub instruction_path: std::string::String,
+    /// Program id as non-empty base58 text.
+    pub program_id: std::string::String,
+    /// Inner instruction accounts as JSON.
+    pub accounts_json: serde_json::Value,
+    /// Inner instruction payload JSON while it is retained in the hot store.
+    pub payload_json: std::option::Option<serde_json::Value>,
+    /// Optional digest of the inner instruction payload after compaction or purge.
+    pub payload_json_hash: std::option::Option<std::string::String>,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Core log SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct CoreLogRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Parent core transaction technical key.
+    pub transaction_id: i64,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Log index preserving transaction log order.
+    pub log_index: i32,
+    /// Optional instruction path resolved from invocation depth when known.
+    pub instruction_path: std::option::Option<std::string::String>,
+    /// Optional program id resolved from the log line or invocation context.
+    pub program_id: std::option::Option<std::string::String>,
+    /// Original log text while it is retained in the hot store.
+    pub log_text: std::option::Option<std::string::String>,
+    /// Optional digest of the log text after compaction or purge.
+    pub log_text_hash: std::option::Option<std::string::String>,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Core balance change SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct CoreBalanceChangeRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Parent core transaction technical key.
+    pub transaction_id: i64,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Stable balance change index preserving extraction order.
+    pub balance_change_index: i32,
+    /// Balance change family.
+    pub balance_kind: crate::CoreBalanceChangeKind,
+    /// Optional account index when available.
+    pub account_index: std::option::Option<i32>,
+    /// Optional account public key when available.
+    pub account_key: std::option::Option<std::string::String>,
+    /// Optional SPL token mint for token balances.
+    pub mint: std::option::Option<std::string::String>,
+    /// Optional owner public key for token balances.
+    pub owner: std::option::Option<std::string::String>,
+    /// Pre-balance JSON value preserving RPC representation.
+    pub pre_balance_json: std::option::Option<serde_json::Value>,
+    /// Post-balance JSON value preserving RPC representation.
+    pub post_balance_json: std::option::Option<serde_json::Value>,
+    /// Delta JSON value preserving integer or decimal-safe representation.
+    pub delta_json: std::option::Option<serde_json::Value>,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}

kb-store/src/contracts/entity/event.rs

@@ -0,0 +1,46 @@
+// file: kb-store/src/contracts/entity/event.rs
+// version: 1
+
+//! Decoded and materialized event SQL-like entities.
+
+/// Decoded event SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct DecodedEventRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Stable instruction path, for example `0` or `2/1`.
+    pub instruction_path: std::string::String,
+    /// Program id as non-empty base58 text.
+    pub program_id: std::string::String,
+    /// Protocol family code.
+    pub protocol_code: std::string::String,
+    /// Protocol surface code.
+    pub surface_code: std::string::String,
+    /// Canonical event code.
+    pub event_code: std::string::String,
+    /// Decoded payload JSON.
+    pub payload_json: serde_json::Value,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Materialized event SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct MaterializedEventRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Source transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Source transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Materialized event family code.
+    pub materialized_family: std::string::String,
+    /// Materialized payload JSON.
+    pub payload_json: serde_json::Value,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}

kb-store/src/contracts/entity/ledger.rs

@@ -0,0 +1,37 @@
+// file: kb-store/src/contracts/entity/ledger.rs
+// version: 1
+
+//! Processing ledger SQL-like entities.
+
+/// Processing ledger SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct ProcessingLedgerRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Processing stage name.
+    pub stage: std::string::String,
+    /// Processor implementation name.
+    pub processor_name: std::string::String,
+    /// Processor semantic version.
+    pub processor_version: std::string::String,
+    /// Stable input key, usually a transaction signature.
+    pub input_key: std::string::String,
+    /// Deterministic input hash.
+    pub input_hash: std::string::String,
+    /// Current processing status.
+    pub status: crate::ProcessingLedgerStatus,
+    /// Number of started attempts for this processor identity.
+    pub attempt_count: i32,
+    /// Optional start timestamp for the latest attempt.
+    pub started_at: std::option::Option<chrono::DateTime<chrono::Utc>>,
+    /// Optional finish timestamp for the latest terminal attempt.
+    pub finished_at: std::option::Option<chrono::DateTime<chrono::Utc>>,
+    /// Optional machine-readable error code.
+    pub error_code: std::option::Option<std::string::String>,
+    /// Optional diagnostic error message.
+    pub error_message: std::option::Option<std::string::String>,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Last update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}

kb-store/src/contracts/entity/raw.rs

@@ -0,0 +1,78 @@
+// file: kb-store/src/contracts/entity/raw.rs
+// version: 1
+
+//! Canonical Solana transaction and acquisition observation SQL-like entities.
+
+/// Canonical raw Solana transaction SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct RawTransactionRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Transaction signature as non-empty base58 text.
+    pub signature: std::string::String,
+    /// Transaction slot stored as SQL `BIGINT`.
+    pub slot: i64,
+    /// Canonical source-independent transaction document while retained in the hot store.
+    pub canonical_json: std::option::Option<serde_json::Value>,
+    /// Optional deterministic digest of the canonical document.
+    pub canonical_json_hash: std::option::Option<std::string::String>,
+    /// Version of the canonical transaction document contract.
+    pub canonical_format_version: i32,
+    /// Current raw payload retention state.
+    pub retention_state: crate::RawPayloadRetentionState,
+    /// Current processing state derived from this canonical transaction.
+    pub processing_state: crate::RawPayloadProcessingState,
+    /// Insert timestamp.
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    /// Last lifecycle update timestamp.
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+/// Transaction acquisition observation SQL-like row contract.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct TransactionObservationRow {
+    /// Technical primary key.
+    pub id: i64,
+    /// Optional linked canonical transaction row id.
+    pub raw_transaction_id: std::option::Option<i64>,
+    /// Stable observation key used for deduplication.
+    pub observation_key: std::string::String,
+    /// Optional transaction signature when known.
+    pub signature: std::option::Option<std::string::String>,
+    /// Optional transaction slot stored as SQL `BIGINT`.
+    pub slot: std::option::Option<i64>,
+    /// Provider code, for example `helius`, `triton` or `legacy_unknown`.
+    pub provider: std::string::String,
+    /// Optional endpoint code from the active configuration.
+    pub endpoint_code: std::option::Option<std::string::String>,
+    /// Acquisition protocol, for example `solana_http`, `solana_websocket` or `yellowstone_grpc`.
+    pub protocol: std::string::String,
+    /// Acquisition method, for example `getTransaction`, `transactionSubscribe` or `transactions`.
+    pub acquisition_method: std::string::String,
+    /// Acquisition origin category.
+    pub origin: crate::TransactionObservationOrigin,
+    /// Optional Solana commitment.
+    pub commitment: std::option::Option<std::string::String>,
+    /// Optional capture session identifier.
+    pub capture_session_id: std::option::Option<std::string::String>,
+    /// Optional configured filter code.
+    pub filter_code: std::option::Option<std::string::String>,
+    /// Optional first detection timestamp.
+    pub detected_at: std::option::Option<chrono::DateTime<chrono::Utc>>,
+    /// Timestamp at which the source payload was received locally.
+    pub received_at: chrono::DateTime<chrono::Utc>,
+    /// Optional timestamp at which canonical normalization completed.
+    pub normalized_at: std::option::Option<chrono::DateTime<chrono::Utc>>,
+    /// Timestamp at which the observation was persisted.
+    pub persisted_at: chrono::DateTime<chrono::Utc>,
+    /// Optional uncompressed source payload size in bytes.
+    pub payload_size_bytes: std::option::Option<i64>,
+    /// Optional digest of the source-specific payload without retaining that payload.
+    pub source_payload_hash: std::option::Option<std::string::String>,
+    /// Current observation status.
+    pub status: crate::TransactionObservationStatus,
+    /// Optional machine-readable error code.
+    pub error_code: std::option::Option<std::string::String>,
+    /// Optional diagnostic error message.
+    pub error_message: std::option::Option<std::string::String>,
+}