@layerzerolabs/protocol-stellar-v2 0.2.8 → 0.2.9

package/contracts/workers/worker/src/events.rs

@@ -0,0 +1,62 @@
+use common_macros::event;
+use soroban_sdk::{Address, Bytes};
+
+#[event]
+pub struct SetAdmin {
+    pub admin: Address,
+    pub active: bool,
+}
+
+#[event]
+pub struct SetSupportedMessageLib {
+    pub message_lib: Address,
+    pub supported: bool,
+}
+
+#[event]
+pub struct SetAllowlist {
+    pub oapp: Address,
+    pub allowed: bool,
+}
+
+#[event]
+pub struct SetDenylist {
+    pub oapp: Address,
+    pub denied: bool,
+}
+
+#[event]
+pub struct Paused {
+    pub pauser: Address,
+}
+
+#[event]
+pub struct Unpaused {
+    pub unpauser: Address,
+}
+
+#[event]
+pub struct SetDefaultMultiplierBps {
+    pub multiplier_bps: u32,
+}
+
+#[event]
+pub struct SetDepositAddress {
+    pub deposit_address: Address,
+}
+
+#[event]
+pub struct SetPriceFeed {
+    pub price_feed: Address,
+}
+
+#[event]
+pub struct SetSupportedOptionTypes {
+    pub dst_eid: u32,
+    pub option_types: Bytes,
+}
+
+#[event]
+pub struct SetWorkerFeeLib {
+    pub fee_lib: Address,
+}

package/contracts/workers/worker/src/interfaces/dvn_fee_lib.rs

@@ -0,0 +1,75 @@
+use soroban_sdk::{contractclient, contracttype, Address, Bytes, Env};
+
+// ============================================================================
+// Fee Calculation Types
+// ============================================================================
+
+/// Parameters for DVN fee calculation.
+///
+/// Contains all inputs needed by the fee library to calculate verification fees
+/// for cross-chain messages. Includes message parameters, common configuration,
+/// and destination-specific settings.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct DvnFeeParams {
+    /// ============================================================================================
+    /// Message Parameters
+    /// ============================================================================================
+
+    /// The OApp sender address.
+    pub sender: Address,
+    /// Destination endpoint ID (chain identifier).
+    pub dst_eid: u32,
+    /// Number of block confirmations required.
+    pub confirmations: u64,
+    /// DVN options
+    pub options: Bytes,
+
+    /// ============================================================================================
+    /// Common Configuration
+    /// ============================================================================================
+
+    /// Price feed contract address for gas price and exchange rate data.
+    pub price_feed: Address,
+    /// Default fee multiplier in basis points (used if no dst-specific multiplier).
+    pub default_multiplier_bps: u32,
+    /// Number of required signatures (quorum).
+    pub quorum: u32,
+
+    /// ============================================================================================
+    /// Destination-Specific Configuration
+    /// ============================================================================================
+
+    /// Gas estimate for verification on destination chain.
+    pub gas: u128,
+    /// Destination-specific fee multiplier in basis points (0 = use default).
+    pub multiplier_bps: u32,
+    /// Minimum fee margin in USD (scaled).
+    pub floor_margin_usd: u128,
+}
+
+// ============================================================================
+// IDvnFeeLib Trait
+// ============================================================================
+
+/// Interface for DVN fee calculation.
+///
+/// Called by the DVN contract to calculate fees for verification jobs.
+/// Uses the PriceFeed interface to obtain gas prices and exchange rates.
+#[contractclient(name = "DvnFeeLibClient")]
+pub trait IDvnFeeLib {
+    /// Calculates the DVN fee for a verification job.
+    ///
+    /// The fee calculation considers:
+    /// - Gas costs for verification on destination chain
+    /// - Quorum size (number of required signatures)
+    /// - Configured multipliers and floor margins
+    /// - Price ratios between source and destination chains
+    ///
+    /// # Arguments
+    /// * `params` - Fee calculation parameters
+    ///
+    /// # Returns
+    /// The calculated fee in native token units (stroops for Stellar).
+    fn get_fee(env: &Env, params: &DvnFeeParams) -> i128;
+}

package/contracts/workers/worker/src/interfaces/executor_fee_lib.rs

@@ -0,0 +1,84 @@
+use soroban_sdk::{contractclient, contracttype, Address, Bytes, Env};
+
+// ============================================================================
+// Fee Calculation Types
+// ============================================================================
+
+/// Parameters for executor fee calculation.
+///
+/// Contains all inputs needed by the fee library to calculate execution fees
+/// for cross-chain messages. Includes message parameters, common configuration,
+/// and destination-specific settings.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct FeeParams {
+    /// ============================================================================================
+    /// Message Parameters
+    /// ============================================================================================
+
+    /// The OApp sender address.
+    pub sender: Address,
+    /// Destination endpoint ID (chain identifier).
+    pub dst_eid: u32,
+    /// Size of the message calldata in bytes.
+    pub calldata_size: u32,
+    /// Encoded executor options (lzReceive gas, lzCompose, nativeDrop, etc.).
+    pub options: Bytes,
+
+    /// ============================================================================================
+    /// Common Configuration
+    /// ============================================================================================
+
+    /// Price feed contract address for gas price and exchange rate data.
+    pub price_feed: Address,
+    /// Default fee multiplier in basis points (used if no dst-specific multiplier).
+    pub default_multiplier_bps: u32,
+
+    /// ============================================================================================
+    /// Destination-Specific Configuration
+    /// ============================================================================================
+
+    /// Base gas for lzReceive execution on destination chain.
+    pub lz_receive_base_gas: u64,
+    /// Base gas for each lzCompose call on destination chain.
+    pub lz_compose_base_gas: u64,
+    /// Minimum fee margin in USD (scaled).
+    pub floor_margin_usd: u128,
+    /// Maximum native token value that can be sent.
+    pub native_cap: u128,
+    /// Destination-specific fee multiplier in basis points (0 = use default).
+    pub multiplier_bps: u32,
+}
+
+// ============================================================================
+// IExecutorFeeLib Trait
+// ============================================================================
+
+/// Interface for executor fee calculation.
+///
+/// Called by the Executor contract to calculate fees for message execution.
+/// Uses the PriceFeed interface to obtain gas prices and exchange rates.
+#[contractclient(name = "ExecutorFeeLibClient")]
+pub trait IExecutorFeeLib {
+    /// Calculates the executor fee for a cross-chain message.
+    ///
+    /// The fee calculation considers:
+    /// - Gas costs for lzReceive and lzCompose operations
+    /// - Native token value transfers
+    /// - Price ratios between source and destination chains
+    /// - Configured multipliers and floor margins
+    ///
+    /// # Arguments
+    /// * `executor` - The executor contract address
+    /// * `params` - Fee calculation parameters
+    ///
+    /// # Returns
+    /// The calculated fee in native token units (stroops for Stellar).
+    fn get_fee(env: &Env, executor: &Address, params: &FeeParams) -> i128;
+
+    /// Returns the fee library contract version.
+    ///
+    /// # Returns
+    /// Tuple of (major version, minor version).
+    fn version(env: &Env) -> (u64, u32);
+}

package/contracts/workers/{worker-common → worker}/src/interfaces/mod.rs

@@ -1,7 +1,7 @@
+pub mod dvn_fee_lib;
 pub mod executor_fee_lib;
 pub mod price_feed;
-pub mod worker;
 
+pub use dvn_fee_lib::*;
 pub use executor_fee_lib::*;
 pub use price_feed::*;
-pub use worker::*;

package/contracts/workers/worker/src/interfaces/price_feed.rs

@@ -0,0 +1,85 @@
+use soroban_sdk::{contractclient, contracttype, Address, Env};
+
+// ================================================
+// Price Feed Types
+// ================================================
+
+/// Gas price information for a destination endpoint.
+///
+/// Contains the exchange rate and gas costs needed for cross-chain fee calculations.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Price {
+    /// Price ratio = (remote native token price / local native token price) * PRICE_RATIO_DENOMINATOR.
+    /// Used to convert destination chain gas costs to source chain native token.
+    pub price_ratio: u128,
+    /// Gas price in the smallest unit (wei for EVM, stroops for Stellar).
+    pub gas_price_in_unit: u64,
+    /// Gas cost per byte of calldata on the destination chain.
+    pub gas_per_byte: u32,
+}
+
+/// Fee estimation result with detailed breakdown.
+///
+/// Contains the calculated fee and all intermediate values used in the calculation.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct FeeEstimate {
+    /// Total gas fee in source chain native token units.
+    pub total_gas_fee: i128,
+    /// Price ratio used for the calculation.
+    pub price_ratio: u128,
+    /// Denominator for the price ratio (typically 10^20).
+    pub price_ratio_denominator: u128,
+    /// Source chain native token price in USD (scaled).
+    pub native_price_usd: u128,
+}
+
+// ================================================
+// ILayerZeroPriceFeed Trait
+// ================================================
+
+/// Price feed interface for cross-chain fee calculations.
+///
+/// Provides gas prices, exchange rates, and fee estimation for destination chains.
+/// Called by ExecutorFeeLib to calculate execution fees. The price feed aggregates
+/// data from multiple sources to provide accurate cross-chain pricing information.
+#[contractclient(name = "LayerZeroPriceFeedClient")]
+pub trait ILayerZeroPriceFeed {
+    /// Returns the USD price of the source chain native token.
+    ///
+    /// # Returns
+    /// Native token price in USD (scaled by appropriate decimals).
+    fn native_token_price_usd(env: &Env) -> u128;
+
+    /// Returns gas price information for a destination endpoint.
+    ///
+    /// # Arguments
+    /// * `dst_eid` - Destination endpoint ID (chain identifier)
+    ///
+    /// # Returns
+    /// `Price` containing price_ratio, gas_price_in_unit, and gas_per_byte.
+    fn get_price(env: &Env, dst_eid: u32) -> Price;
+
+    /// Returns the denominator used for price ratio calculations.
+    ///
+    /// # Returns
+    /// Price ratio denominator (typically 10^20 for precision).
+    fn get_price_ratio_denominator(env: &Env) -> u128;
+
+    /// Estimates the fee for executing on a destination chain.
+    ///
+    /// This is the primary function called by ExecutorFeeLib for fee calculations.
+    /// It combines gas costs, calldata costs, and exchange rates to estimate the
+    /// total fee in source chain native token.
+    ///
+    /// # Arguments
+    /// * `fee_lib` - The fee library contract address (for caller identification)
+    /// * `dst_eid` - Destination endpoint ID (chain identifier)
+    /// * `calldata_size` - Size of the message calldata in bytes
+    /// * `gas` - Gas amount needed for execution on destination
+    ///
+    /// # Returns
+    /// `FeeEstimate` with total_gas_fee, price_ratio, price_ratio_denominator, and native_price_usd.
+    fn estimate_fee_by_eid(env: &Env, fee_lib: &Address, dst_eid: u32, calldata_size: u32, gas: u128) -> FeeEstimate;
+}

package/contracts/workers/worker/src/lib.rs

@@ -0,0 +1,14 @@
+#![no_std]
+
+pub mod errors;
+pub mod events;
+pub mod interfaces;
+pub mod storage;
+
+mod worker;
+
+pub use interfaces::*;
+pub use worker::*;
+
+// #[cfg(test)]
+// mod tests;

package/contracts/workers/worker/src/storage.rs

@@ -0,0 +1,63 @@
+use common_macros::storage;
+use soroban_sdk::{Address, Bytes, Vec};
+
+/// Storage keys for the Worker contract.
+#[storage]
+pub enum WorkerStorage {
+    /// Whether the worker is paused (prevents new job assignments).
+    #[instance(bool)]
+    #[default(false)]
+    Paused,
+
+    /// Address where worker fees are collected.
+    #[instance(Address)]
+    DepositAddress,
+
+    /// Price feed contract address for cross-chain fee calculations.
+    #[instance(Address)]
+    PriceFeed,
+
+    /// Worker fee library contract address for fee calculation logic.
+    #[instance(Address)]
+    WorkerFeeLib,
+
+    /// Default fee multiplier in basis points (10000 = 1x).
+    #[instance(u32)]
+    DefaultMultiplierBps,
+
+    /// Supported executor option types for a destination endpoint.
+    ///
+    /// Encoded bytes defining which option types (lzReceive, lzCompose, nativeDrop, etc.)
+    /// are supported for a specific destination chain.
+    #[persistent(Bytes)]
+    SupportedOptionTypes { eid: u32 },
+
+    /// List of supported message library addresses (e.g., ULN302).
+    #[persistent(Vec<Address>)]
+    MessageLibs,
+
+    /// Allowlist status for an OApp address.
+    ///
+    /// When allowlist is empty, all non-denylisted OApps are allowed.
+    #[persistent(bool)]
+    Allowlist { oapp: Address },
+
+    /// Denylist status for an OApp address.
+    ///
+    /// Denylisted OApps are blocked regardless of allowlist status.
+    #[persistent(bool)]
+    Denylist { oapp: Address },
+
+    /// Counter for the number of addresses on the allowlist.
+    ///
+    /// Used to efficiently check if allowlist is empty (empty = allow all non-denylisted).
+    #[instance(u32)]
+    #[default(0)]
+    AllowlistSize,
+
+    /// Admin addresses with configuration permissions.
+    ///
+    /// Admins can modify worker settings but cannot change ownership.
+    #[persistent(Vec<Address>)]
+    Admins,
+}