@layerzerolabs/protocol-stellar-v2 0.2.13 → 0.2.18

package/contracts/workers/executor-fee-lib/src/executor_fee_lib.rs

@@ -1,6 +1,7 @@
 use crate::{errors::ExecutorFeeLibError, executor_option};
-use common_macros::contract_impl;
-use soroban_sdk::{assert_with_error, contract, Address, Bytes, Env};
+use common_macros::{contract_impl, lz_contract};
+use soroban_sdk::{assert_with_error, Address, Bytes, Env};
+use utils::upgradeable::UpgradeableInternal;
 use worker::{FeeParams, IExecutorFeeLib, LayerZeroPriceFeedClient};
 
 // ============================================================================
@@ -11,7 +12,7 @@ use worker::{FeeParams, IExecutorFeeLib, LayerZeroPriceFeedClient};
 const V1_EID_THRESHOLD: u32 = 30000;
 
 /// Basis points denominator (10000 = 100%).
-const BPS_DENOMINATOR: i128 = 10000;
+const BPS_DENOMINATOR: u128 = 10000;
 
 /// Overhead percentage for ordered execution (102 = 2% overhead).
 const ORDERED_EXECUTION_OVERHEAD_PERCENT: u128 = 102;
@@ -24,124 +25,13 @@ const NATIVE_DECIMALS_RATE: u128 = 10_000_000;
 /// Provides fee calculation logic based on executor options, destination configuration,
 /// and current gas prices from the price feed. Handles fee multipliers, margins, and
 /// native token value conversions.
-#[contract]
+#[lz_contract(upgradeable)]
 pub struct ExecutorFeeLib;
 
 #[contract_impl]
 impl ExecutorFeeLib {
-    // ========================================================================
-    // Internal Functions
-    // ========================================================================
-
-    /// Decodes executor options and calculates total gas and native value.
-    ///
-    /// Parses encoded executor options, accumulates gas requirements (including
-    /// compose calls and ordered execution overhead), and returns the total native
-    /// value and gas needed.
-    ///
-    /// # Arguments
-    /// * `options` - Encoded executor options bytes
-    /// * `dst_eid` - Destination endpoint ID
-    /// * `lz_receive_base_gas` - Base gas for lzReceive execution
-    /// * `lz_compose_base_gas` - Base gas per lzCompose call
-    /// * `native_cap` - Maximum allowed native token value
-    ///
-    /// # Returns
-    /// Tuple of (total_native_value, total_gas).
-    fn decode_executor_options(
-        env: &Env,
-        options: &Bytes,
-        dst_eid: u32,
-        lz_receive_base_gas: u64,
-        lz_compose_base_gas: u64,
-        native_cap: u128,
-    ) -> (u128, u128) {
-        let options_agg = executor_option::parse_executor_options(env, options, Self::is_v1_eid(dst_eid), native_cap);
-
-        let mut total_gas = (lz_receive_base_gas as u128)
-            + options_agg.total_gas
-            + ((lz_compose_base_gas as u128) * (options_agg.num_lz_compose as u128));
-
-        if options_agg.ordered {
-            total_gas = (total_gas * ORDERED_EXECUTION_OVERHEAD_PERCENT) / 100;
-        }
-
-        (options_agg.total_value, total_gas)
-    }
-
-    /// Returns the effective multiplier in basis points.
-    ///
-    /// Uses destination-specific multiplier if set, otherwise falls back to default multiplier.
-    ///
-    /// # Arguments
-    /// * `params` - Fee parameters containing multiplier settings
-    ///
-    /// # Returns
-    /// Effective multiplier in basis points.
-    fn get_effective_multiplier_bps(params: &FeeParams) -> u32 {
-        if params.multiplier_bps == 0 {
-            params.default_multiplier_bps
-        } else {
-            params.multiplier_bps
-        }
-    }
-
-    /// Applies premium (multiplier and margin) to gas fee.
-    ///
-    /// Calculates fee with multiplier and floor margin, returning the maximum of both
-    /// to ensure profitability.
-    ///
-    /// # Arguments
-    /// * `fee` - Base gas fee
-    /// * `multiplier_bps` - Fee multiplier in basis points
-    /// * `margin_usd` - Minimum margin in USD (scaled)
-    /// * `native_price_usd` - Native token price in USD (scaled)
-    ///
-    /// # Returns
-    /// Fee with premium applied (max of multiplier fee and margin fee).
-    fn apply_premium_to_gas(fee: i128, multiplier_bps: u32, margin_usd: u128, native_price_usd: u128) -> i128 {
-        let fee_with_multiplier = (fee * multiplier_bps as i128) / BPS_DENOMINATOR;
-
-        if native_price_usd == 0 || margin_usd == 0 {
-            return fee_with_multiplier;
-        }
-
-        let fee_with_margin = ((margin_usd * NATIVE_DECIMALS_RATE) / native_price_usd) as i128 + fee;
-
-        fee_with_margin.max(fee_with_multiplier)
-    }
-
-    /// Converts native value and applies premium multiplier.
-    ///
-    /// Converts value using price ratio and applies multiplier in basis points.
-    ///
-    /// # Arguments
-    /// * `value` - Native value to convert
-    /// * `ratio` - Price ratio numerator
-    /// * `denom` - Price ratio denominator
-    /// * `multiplier_bps` - Fee multiplier in basis points
-    ///
-    /// # Returns
-    /// Converted and multiplied value, or 0 if input value is 0.
-    fn convert_and_apply_premium_to_value(value: u128, ratio: u128, denom: u128, multiplier_bps: u32) -> i128 {
-        if value == 0 {
-            return 0;
-        }
-        let converted = (value * ratio) / denom;
-        ((converted * multiplier_bps as u128) / BPS_DENOMINATOR as u128) as i128
-    }
-
-    /// Checks if an endpoint ID is a V1 endpoint.
-    ///
-    /// V1 endpoints (EID < 30000) have restrictions on executor options.
-    ///
-    /// # Arguments
-    /// * `eid` - Endpoint ID to check
-    ///
-    /// # Returns
-    /// `true` if the endpoint is a V1 endpoint, `false` otherwise.
-    fn is_v1_eid(eid: u32) -> bool {
-        eid < V1_EID_THRESHOLD
+    pub fn __constructor(env: &Env, owner: &Address) {
+        Self::init_owner(env, owner);
     }
 }
 
@@ -170,7 +60,7 @@ impl IExecutorFeeLib for ExecutorFeeLib {
     fn get_fee(env: &Env, _executor: &Address, params: &FeeParams) -> i128 {
         assert_with_error!(env, params.lz_receive_base_gas != 0, ExecutorFeeLibError::EidNotSupported);
 
-        let (total_value, total_gas) = Self::decode_executor_options(
+        let (total_value, total_gas) = decode_executor_options(
             env,
             &params.options,
             params.dst_eid,
@@ -186,16 +76,18 @@ impl IExecutorFeeLib for ExecutorFeeLib {
             &total_gas,
         );
 
-        let multiplier_bps = Self::get_effective_multiplier_bps(params);
+        let multiplier_bps = get_effective_multiplier_bps(params);
 
-        let mut fee = Self::apply_premium_to_gas(
+        let mut fee = apply_premium_to_gas(
+            env,
             fee_estimate.total_gas_fee,
             multiplier_bps,
             params.floor_margin_usd,
             fee_estimate.native_price_usd,
         );
 
-        fee += Self::convert_and_apply_premium_to_value(
+        fee += convert_and_apply_premium_to_value(
+            env,
             total_value,
             fee_estimate.price_ratio,
             fee_estimate.price_ratio_denominator,
@@ -213,3 +105,143 @@ impl IExecutorFeeLib for ExecutorFeeLib {
         (1, 1)
     }
 }
+
+// ============================================================================
+// Upgradeable Implementation
+// ============================================================================
+
+impl UpgradeableInternal for ExecutorFeeLib {
+    type MigrationData = ();
+
+    fn __migrate(_env: &Env, _migration_data: &Self::MigrationData) {
+        // No migration logic needed for initial upgrade capability
+    }
+}
+
+// ========================================================================
+// Helper Functions
+// ========================================================================
+
+/// Decodes executor options and calculates total gas and native value.
+///
+/// Parses encoded executor options, accumulates gas requirements (including
+/// compose calls and ordered execution overhead), and returns the total native
+/// value and gas needed.
+///
+/// # Arguments
+/// * `options` - Encoded executor options bytes
+/// * `dst_eid` - Destination endpoint ID
+/// * `lz_receive_base_gas` - Base gas for lzReceive execution
+/// * `lz_compose_base_gas` - Base gas per lzCompose call
+/// * `native_cap` - Maximum allowed native token value
+///
+/// # Returns
+/// Tuple of (total_native_value, total_gas).
+fn decode_executor_options(
+    env: &Env,
+    options: &Bytes,
+    dst_eid: u32,
+    lz_receive_base_gas: u64,
+    lz_compose_base_gas: u64,
+    native_cap: u128,
+) -> (u128, u128) {
+    let options_agg = executor_option::parse_executor_options(env, options, is_v1_eid(dst_eid), native_cap);
+
+    let mut total_gas = (lz_receive_base_gas as u128)
+        + options_agg.total_gas
+        + ((lz_compose_base_gas as u128) * (options_agg.num_lz_compose as u128));
+
+    if options_agg.ordered {
+        total_gas = (total_gas * ORDERED_EXECUTION_OVERHEAD_PERCENT) / 100;
+    }
+
+    (options_agg.total_value, total_gas)
+}
+
+/// Returns the effective multiplier in basis points.
+///
+/// Uses destination-specific multiplier if set, otherwise falls back to default multiplier.
+///
+/// # Arguments
+/// * `params` - Fee parameters containing multiplier settings
+///
+/// # Returns
+/// Effective multiplier in basis points.
+fn get_effective_multiplier_bps(params: &FeeParams) -> u32 {
+    if params.multiplier_bps == 0 {
+        params.default_multiplier_bps
+    } else {
+        params.multiplier_bps
+    }
+}
+
+/// Applies premium (multiplier and margin) to gas fee.
+///
+/// Calculates fee with multiplier and floor margin, returning the maximum of both
+/// to ensure profitability.
+///
+/// # Arguments
+/// * `fee` - Base gas fee
+/// * `multiplier_bps` - Fee multiplier in basis points
+/// * `margin_usd` - Minimum margin in USD (scaled)
+/// * `native_price_usd` - Native token price in USD (scaled)
+///
+/// # Example(scaled to 10^20)
+/// With margin_usd = $0.01 (0.01 * 10^20), native_price_usd = $0.32 (0.32 * 10^20), fee = 0:
+/// fee_with_margin = ((0.01 * 10^20 * 10^7) / (0.32 * 10^20)) + 0 = 312_500 stroops (0.03125 XLM)
+///
+/// # Returns
+/// Fee with premium applied (max of multiplier fee and margin fee).
+fn apply_premium_to_gas(env: &Env, fee: i128, multiplier_bps: u32, margin_usd: u128, native_price_usd: u128) -> i128 {
+    assert_with_error!(env, fee >= 0, ExecutorFeeLibError::InvalidFee);
+
+    let fee_with_multiplier = safe_u128_to_i128(env, (fee as u128 * multiplier_bps as u128) / BPS_DENOMINATOR);
+
+    if native_price_usd == 0 || margin_usd == 0 {
+        return fee_with_multiplier;
+    }
+
+    let margin_in_native = (margin_usd * NATIVE_DECIMALS_RATE) / native_price_usd;
+    let fee_with_margin = safe_u128_to_i128(env, margin_in_native) + fee;
+
+    fee_with_margin.max(fee_with_multiplier)
+}
+
+/// Converts native value and applies premium multiplier.
+///
+/// Converts value using price ratio and applies multiplier in basis points.
+///
+/// # Arguments
+/// * `value` - Native value to convert
+/// * `ratio` - Price ratio numerator
+/// * `denom` - Price ratio denominator
+/// * `multiplier_bps` - Fee multiplier in basis points
+///
+/// # Returns
+/// Converted and multiplied value, or 0 if input value is 0.
+fn convert_and_apply_premium_to_value(env: &Env, value: u128, ratio: u128, denom: u128, multiplier_bps: u32) -> i128 {
+    if value == 0 {
+        return 0;
+    }
+    let converted = (value * ratio) / denom;
+    safe_u128_to_i128(env, (converted * multiplier_bps as u128) / BPS_DENOMINATOR)
+}
+
+/// Checks if an endpoint ID is a V1 endpoint.
+///
+/// V1 endpoints (EID < 30000) have restrictions on executor options.
+///
+/// # Arguments
+/// * `eid` - Endpoint ID to check
+///
+/// # Returns
+/// `true` if the endpoint is a V1 endpoint, `false` otherwise.
+fn is_v1_eid(eid: u32) -> bool {
+    eid < V1_EID_THRESHOLD
+}
+
+/// Safely converts u128 to i128, panicking if value exceeds i128::MAX.
+fn safe_u128_to_i128(env: &Env, value: u128) -> i128 {
+    assert_with_error!(env, value <= i128::MAX as u128, ExecutorFeeLibError::Overflow);
+    value as i128
+}

package/contracts/workers/executor-helper/Cargo.toml

@@ -6,15 +6,10 @@ license.workspace = true
 publish = false
 
 [lib]
-crate-type = ["cdylib"]
+crate-type = ["cdylib", "rlib"]
 doctest = false
 
-[features]
-library = []
-testutils = []
-
 [dependencies]
-cfg-if = { workspace = true }
 soroban-sdk = { workspace = true }
 # workspace dependencies
 common-macros = { workspace = true }

package/contracts/workers/executor-helper/src/executor_helper.rs

@@ -1,11 +1,11 @@
 //! ABA-safe entry point for cross-chain message execution on Stellar.
 //! Prevents reentry into the Executor during OApp Atomic Batch Actions.
 
+use common_macros::contract_impl;
 use endpoint_v2::{
     LayerZeroComposerClient, LayerZeroEndpointV2Client, LayerZeroReceiverClient, MessagingComposerClient, Origin,
 };
 use executor::{ExecutorClient, NativeDropParams};
-use common_macros::contract_impl;
 use soroban_sdk::{contract, contracttype, token::TokenClient, Address, Bytes, BytesN, Env, Vec};
 
 /// Parameters for `lz_receive` execution.
@@ -40,28 +40,43 @@ pub struct ExecutorHelper;
 
 #[contract_impl]
 impl ExecutorHelper {
-    /// Executes `lz_receive` on the target OApp; falls back to `lz_receive_alert` on failure.
+    /// Executes `lz_receive` on the target OApp
     pub fn execute(env: &Env, executor: &Address, params: &ExecutionParams, value_payer: &Address) {
-        if params.value > 0 {
-            value_payer.require_auth();
+        if params.value != 0 {
+            transfer_value(env, value_payer, executor, params.value);
         }
-        Self::execute_internal(env, executor, params, value_payer);
+        LayerZeroReceiverClient::new(env, &params.receiver).lz_receive(
+            executor,
+            &params.origin,
+            &params.guid,
+            &params.message,
+            &params.extra_data,
+            &params.value,
+        );
     }
 
-    /// Executes `lz_compose` on the target composer; falls back to `lz_compose_alert` on failure.
-    pub fn compose(env: &Env, executor: &Address, params: &ComposeParams, value_payer: &Address) {
-        executor.require_auth();
-
-        let endpoint = if params.value > 0 {
-            let ep = ExecutorClient::new(env, executor).endpoint();
-            value_payer.require_auth();
-            transfer_value(env, &ep, value_payer, executor, params.value);
-            Some(ep)
-        } else {
-            None
-        };
+    /// Records a failed `lz_receive` execution for off-chain processing.
+    pub fn lz_receive_alert(env: &Env, executor: &Address, params: &ExecutionParams, reason: &Bytes) {
+        let endpoint = ExecutorClient::new(env, executor).endpoint();
+        LayerZeroEndpointV2Client::new(env, &endpoint).lz_receive_alert(
+            executor,
+            &params.origin,
+            &params.receiver,
+            &params.guid,
+            &params.gas_limit,
+            &params.value,
+            &params.message,
+            &params.extra_data,
+            reason,
+        );
+    }
 
-        let result = LayerZeroComposerClient::new(env, &params.to).try_lz_compose(
+    /// Executes `lz_compose` on the target composer
+    pub fn compose(env: &Env, executor: &Address, params: &ComposeParams, value_payer: &Address) {
+        if params.value != 0 {
+            transfer_value(env, value_payer, executor, params.value);
+        }
+        LayerZeroComposerClient::new(env, &params.to).lz_compose(
             executor,
             &params.from,
             &params.guid,
@@ -70,22 +85,23 @@ impl ExecutorHelper {
             &params.extra_data,
             &params.value,
         );
+    }
 
-        if result.is_err() {
-            let ep = endpoint.unwrap_or_else(|| ExecutorClient::new(env, executor).endpoint());
-            MessagingComposerClient::new(env, &ep).lz_compose_alert(
-                executor,
-                &params.from,
-                &params.to,
-                &params.guid,
-                &params.index,
-                &params.gas_limit,
-                &params.value,
-                &params.message,
-                &params.extra_data,
-                &Bytes::new(env),
-            );
-        }
+    /// Records a failed `lz_compose` execution for off-chain processing.
+    pub fn lz_compose_alert(env: &Env, executor: &Address, params: &ComposeParams, reason: &Bytes) {
+        let endpoint = ExecutorClient::new(env, executor).endpoint();
+        MessagingComposerClient::new(env, &endpoint).lz_compose_alert(
+            executor,
+            &params.from,
+            &params.to,
+            &params.guid,
+            &params.index,
+            &params.gas_limit,
+            &params.value,
+            &params.message,
+            &params.extra_data,
+            reason,
+        );
     }
 
     /// Delegates `native_drop` to the executor contract.
@@ -98,7 +114,6 @@ impl ExecutorHelper {
         oapp: &Address,
         params: &Vec<NativeDropParams>,
     ) {
-        admin.require_auth();
         ExecutorClient::new(env, executor).native_drop(admin, origin, &dst_eid, oapp, params);
     }
 
@@ -114,48 +129,13 @@ impl ExecutorHelper {
         execute_params: &ExecutionParams,
     ) {
         Self::native_drop(env, executor, admin, origin, dst_eid, oapp, native_drop_params);
-        Self::execute_internal(env, executor, execute_params, admin); // admin already authed above
-    }
-
-    fn execute_internal(env: &Env, executor: &Address, params: &ExecutionParams, value_payer: &Address) {
-        executor.require_auth();
-
-        let endpoint = if params.value > 0 {
-            let ep = ExecutorClient::new(env, executor).endpoint();
-            transfer_value(env, &ep, value_payer, executor, params.value);
-            Some(ep)
-        } else {
-            None
-        };
-
-        let result = LayerZeroReceiverClient::new(env, &params.receiver).try_lz_receive(
-            executor,
-            &params.origin,
-            &params.guid,
-            &params.message,
-            &params.extra_data,
-            &params.value,
-        );
-
-        if result.is_err() {
-            let ep = endpoint.unwrap_or_else(|| ExecutorClient::new(env, executor).endpoint());
-            LayerZeroEndpointV2Client::new(env, &ep).lz_receive_alert(
-                executor,
-                &params.origin,
-                &params.receiver,
-                &params.guid,
-                &params.gas_limit,
-                &params.value,
-                &params.message,
-                &params.extra_data,
-                &Bytes::new(env),
-            );
-        }
+        Self::execute(env, executor, execute_params, admin);
     }
 }
 
 #[inline]
-fn transfer_value(env: &Env, endpoint: &Address, payer: &Address, executor: &Address, value: i128) {
-    let native_token = LayerZeroEndpointV2Client::new(env, endpoint).native_token();
+fn transfer_value(env: &Env, payer: &Address, executor: &Address, value: i128) {
+    let endpoint = ExecutorClient::new(env, executor).endpoint();
+    let native_token = LayerZeroEndpointV2Client::new(env, &endpoint).native_token();
     TokenClient::new(env, &native_token).transfer(payer, executor, &value);
 }

package/contracts/workers/executor-helper/src/lib.rs

@@ -2,10 +2,4 @@
 
 mod executor_helper;
 
-cfg_if::cfg_if! {
-    // Include implementation when NOT in library mode, OR when testutils is enabled (for tests)
-    if #[cfg(any(not(feature = "library"), feature = "testutils"))] {
-
-        pub use executor_helper::*;
-    }
-}
+pub use executor_helper::*;

package/contracts/workers/price-feed/Cargo.toml

@@ -6,12 +6,11 @@ license.workspace = true
 publish = false
 
 [lib]
-crate-type = ["cdylib"]
+crate-type = ["cdylib", "rlib"]
 doctest = false
 
 [dependencies]
 soroban-sdk = { workspace = true }
-endpoint-v2 = { workspace = true, features = ["library"] }
 utils = { workspace = true }
 worker = { workspace = true }
 common-macros = { workspace = true }

package/contracts/workers/price-feed/src/errors.rs

@@ -2,8 +2,9 @@ use common_macros::contract_error;
 
 #[contract_error]
 pub enum PriceFeedError {
-    OnlyPriceUpdater,
     InvalidDenominator,
-    NotAnOpStack,
     NoPrice,
+    NotAnOpStack,
+    OnlyPriceUpdater,
+    Overflow,
 }

package/contracts/workers/price-feed/src/lib.rs

@@ -1,11 +1,10 @@
 #![no_std]
 
-mod errors;
-mod events;
-mod price_feed;
 mod storage;
-mod types;
 
-pub use errors::*;
+pub mod errors;
+pub mod events;
+pub mod price_feed;
+pub mod types;
+
 pub use price_feed::{LzPriceFeed, LzPriceFeedClient};
-pub use types::*;