feat(kora): add swap_gas plugin + plugin infrastructure (#383)

* feat(kora)!: add gas_swap transaction plugin infrastructure

Refs: PRO-932

---------

Co-authored-by: Jo D <dev-jodee@users.noreply.github.com>
Co-authored-by: amilz <85324096+amilz@users.noreply.github.com>

Author: dev-jodee

.gitignore

@@ -11,6 +11,7 @@ generated/
 # SDK
 node_modules/
 dist/
+.pnpm-store/
 
 # Coverage reports
 coverage/

crates/lib/src/bundle/helper.rs

@@ -4,6 +4,7 @@ use crate::{
     constant::ESTIMATED_LAMPORTS_FOR_PAYMENT_INSTRUCTION,
     fee::fee::{FeeConfigUtil, TransactionFeeUtil},
     lighthouse::LighthouseUtil,
+    plugin::{PluginExecutionContext, TransactionPluginRunner},
     signer::bundle_signer::BundleSigner,
     token::token::TokenUtil,
     transaction::{TransactionUtil, VersionedTransactionResolved},
@@ -86,9 +87,11 @@ impl BundleProcessor {
         config: &Config,
         rpc_client: &Arc<RpcClient>,
         sig_verify: bool,
+        plugin_context: Option<PluginExecutionContext>,
         processing_mode: BundleProcessingMode<'a>,
     ) -> Result<Self, KoraError> {
         let validator = TransactionValidator::new(config, fee_payer)?;
+        let plugin_runner = TransactionPluginRunner::from_config(config);
         let mut resolved_transactions = Vec::with_capacity(encoded_txs.len());
         let mut total_required_lamports = 0u64;
         let mut all_bundle_instructions: Vec<Instruction> = Vec::new();
@@ -119,6 +122,11 @@ impl BundleProcessor {
             }
 
             validator.validate_transaction(config, &mut resolved_tx, rpc_client).await?;
+            if let Some(context) = plugin_context {
+                plugin_runner
+                    .run(&mut resolved_tx, config, rpc_client, &fee_payer, context)
+                    .await?;
+            }
 
             let fee_calc = FeeConfigUtil::estimate_kora_fee(
                 &mut resolved_tx,

crates/lib/src/config.rs

@@ -477,6 +477,19 @@ impl Default for CacheConfig {
     }
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, PartialEq, Eq, Hash)]
+#[serde(rename_all = "snake_case")]
+pub enum TransactionPluginType {
+    GasSwap,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, Default)]
+#[serde(default)]
+pub struct PluginsConfig {
+    /// List of enabled transaction plugins, executed for sign/signAndSend flows
+    pub enabled: Vec<TransactionPluginType>,
+}
+
 #[derive(Clone, Serialize, Deserialize, ToSchema)]
 #[serde(default)]
 pub struct KoraConfig {
@@ -488,6 +501,8 @@ pub struct KoraConfig {
     pub payment_address: Option<String>,
     pub cache: CacheConfig,
     pub usage_limit: UsageLimitConfig,
+    /// Transaction plugins executed during sign/signAndSend flows
+    pub plugins: PluginsConfig,
     /// Bundle support configuration
     pub bundle: BundleConfig,
     /// Lighthouse configuration for fee payer balance protection
@@ -507,6 +522,7 @@ impl Default for KoraConfig {
             payment_address: None,
             cache: CacheConfig::default(),
             usage_limit: UsageLimitConfig::default(),
+            plugins: PluginsConfig::default(),
             bundle: BundleConfig::default(),
             lighthouse: LighthouseConfig::default(),
             force_sig_verify: false,

crates/lib/src/mod.rs

@@ -13,6 +13,7 @@ pub mod lighthouse;
 pub mod log;
 pub mod metrics;
 pub mod oracle;
+pub mod plugin;
 pub mod rpc;
 pub mod rpc_server;
 pub mod sanitize;

crates/lib/src/plugin/mod.rs

@@ -0,0 +1,121 @@
+use async_trait::async_trait;
+use solana_client::nonblocking::rpc_client::RpcClient;
+use solana_sdk::pubkey::Pubkey;
+use std::collections::HashSet;
+
+use crate::{
+    config::{Config, TransactionPluginType},
+    error::KoraError,
+    transaction::VersionedTransactionResolved,
+};
+
+mod plugin_gas_swap;
+
+use plugin_gas_swap::GasSwapPlugin;
+
+#[derive(Debug, Clone, Copy)]
+pub enum PluginExecutionContext {
+    SignTransaction,
+    SignAndSendTransaction,
+    SignBundle,
+    SignAndSendBundle,
+}
+
+impl PluginExecutionContext {
+    pub(super) fn method_name(self) -> &'static str {
+        match self {
+            Self::SignTransaction => "signTransaction",
+            Self::SignAndSendTransaction => "signAndSendTransaction",
+            Self::SignBundle => "signBundle",
+            Self::SignAndSendBundle => "signAndSendBundle",
+        }
+    }
+}
+
+#[async_trait]
+trait TransactionPlugin: Send + Sync {
+    async fn validate(
+        &self,
+        transaction: &mut VersionedTransactionResolved,
+        _config: &Config,
+        _rpc_client: &RpcClient,
+        fee_payer: &Pubkey,
+        context: PluginExecutionContext,
+    ) -> Result<(), KoraError>;
+
+    /// Returns (errors, warnings) for this plugin's config requirements.
+    /// Called at startup by the config validator.
+    fn validate_config(&self, _config: &Config) -> (Vec<String>, Vec<String>) {
+        (vec![], vec![])
+    }
+}
+
+pub struct TransactionPluginRunner {
+    plugins: Vec<Box<dyn TransactionPlugin>>,
+}
+
+impl TransactionPluginRunner {
+    pub fn from_config(config: &Config) -> Self {
+        let mut enabled = HashSet::new();
+        let mut plugins: Vec<Box<dyn TransactionPlugin>> = Vec::new();
+
+        // TODO: WasmPlugin — operators should be able to register custom plugins via a config
+        // path (e.g. `plugins = [{type = "wasm", path = "my_plugin.wasm"}]`) without requiring a
+        // Kora source change or new release. A WasmPlugin implementing TransactionPlugin would
+        // load a .wasm module at startup and call it for each transaction. The migration is clean:
+        // WasmPlugin sits alongside typed built-ins until we're ready to drop hardcoded dispatch.
+        //
+        //   pub struct WasmPlugin { engine: wasmtime::Engine, module: wasmtime::Module }
+        //   impl TransactionPlugin for WasmPlugin { ... }
+        //
+        // TransactionPluginType would gain a `Wasm { path: PathBuf }` variant alongside GasSwap.
+        for plugin in &config.kora.plugins.enabled {
+            if !enabled.insert(plugin.clone()) {
+                continue;
+            }
+
+            match plugin {
+                TransactionPluginType::GasSwap => {
+                    plugins.push(Box::new(GasSwapPlugin));
+                }
+            }
+        }
+
+        Self { plugins }
+    }
+
+    pub fn validate_config(config: &Config) -> (Vec<String>, Vec<String>) {
+        let mut errors = Vec::new();
+        let mut warnings = Vec::new();
+        let mut seen = HashSet::new();
+
+        for plugin_type in &config.kora.plugins.enabled {
+            if !seen.insert(plugin_type.clone()) {
+                continue;
+            }
+            let plugin: Box<dyn TransactionPlugin> = match plugin_type {
+                TransactionPluginType::GasSwap => Box::new(GasSwapPlugin),
+            };
+            let (e, w) = plugin.validate_config(config);
+            errors.extend(e);
+            warnings.extend(w);
+        }
+
+        (errors, warnings)
+    }
+
+    pub async fn run(
+        &self,
+        transaction: &mut VersionedTransactionResolved,
+        config: &Config,
+        rpc_client: &RpcClient,
+        fee_payer: &Pubkey,
+        context: PluginExecutionContext,
+    ) -> Result<(), KoraError> {
+        for plugin in &self.plugins {
+            plugin.validate(transaction, config, rpc_client, fee_payer, context).await?;
+        }
+
+        Ok(())
+    }
+}