@layerzerolabs/protocol-stellar-v2 0.2.8 → 0.2.10

package/contracts/workers/executor/Cargo.toml

@@ -6,21 +6,24 @@ 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 }
-endpoint-v2 = { workspace = true, features = ["library"] }
+# workspace dependencies
 utils = { workspace = true }
-worker-common = { workspace = true }
-stellar-access = { workspace = true }
-stellar-macros = { workspace = true }
-stellar-contract-utils = { workspace = true }
+worker = { workspace = true }
 common-macros = { workspace = true }
 message-lib-common = { workspace = true }
+endpoint-v2 = { workspace = true, features = ["library"] }
 
 [dev-dependencies]
 soroban-sdk = { workspace = true, features = ["testutils"] }
-message-lib-common = { workspace = true, features = ["testutils"] }
+
 

package/contracts/workers/executor/src/errors.rs

@@ -0,0 +1,8 @@
+use common_macros::contract_error;
+
+#[contract_error]
+pub enum ExecutorError {
+    EidNotSupported,
+    Unauthorized,
+    UnauthorizedContext,
+}

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

@@ -1,18 +1,15 @@
+use common_macros::event;
 use endpoint_v2::Origin;
-use soroban_sdk::{contractevent, Address, Vec};
+use soroban_sdk::{Address, Vec};
 
 use crate::interfaces::{NativeDropParams, SetDstConfigParam};
 
-// === Executor Events ===
-
-#[contractevent(topics = ["DstConfigSet"])]
-#[derive(Clone, Eq, PartialEq)]
+#[event]
 pub struct DstConfigSet {
     pub params: Vec<SetDstConfigParam>,
 }
 
-#[contractevent(topics = ["NativeDropApplied"])]
-#[derive(Clone, Eq, PartialEq)]
+#[event]
 pub struct NativeDropApplied {
     pub origin: Origin,
     pub dst_eid: u32,

package/contracts/workers/executor/src/interfaces/executor.rs

@@ -1,28 +1,81 @@
 use endpoint_v2::Origin;
-use message_lib_common::ILayerZeroExecutor;
-use soroban_sdk::{contractclient, Address, Env, Vec};
-use worker_common::IWorker;
+use message_lib_common::interfaces::ILayerZeroExecutor;
+use soroban_sdk::{contractclient, contracttype, Address, Env, Vec};
+use worker::Worker;
 
-use crate::{
-    interfaces::{DstConfig, ExecutionParams, NativeDropParams, SetDstConfigParam},
-    ComposeParams,
-};
+/// Destination chain configuration for executor fee calculation.
+///
+/// Contains gas costs and fee parameters specific to each destination chain.
+/// These parameters are used by the fee library to calculate accurate execution fees.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct DstConfig {
+    /// Base gas cost for lzReceive execution on the destination chain.
+    pub lz_receive_base_gas: u64,
+    /// Fee multiplier in basis points for this destination (0 = use default multiplier).
+    pub multiplier_bps: u32,
+    /// Minimum fee margin in USD (scaled) to ensure profitability.
+    pub floor_margin_usd: u128,
+    /// Maximum native token value that can be transferred to the destination.
+    pub native_cap: u128,
+    /// Base gas cost per lzCompose call on the destination chain.
+    pub lz_compose_base_gas: u64,
+}
 
-/// IExecutor - Main executor interface that combines multiple executor capabilities
-/// Inherits from: IWorker and includes LayerZero execution methods
-#[contractclient(name = "ExecutorClient")]
-pub trait IExecutor: IWorker + ILayerZeroExecutor {
-    // === Destination Configuration ===
+/// Parameters for setting destination configuration.
+///
+/// Used when configuring executor settings for a specific destination chain.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SetDstConfigParam {
+    /// Destination endpoint ID (chain identifier).
+    pub dst_eid: u32,
+    /// Configuration for the destination chain.
+    pub dst_config: DstConfig,
+}
 
-    /// Get destination configuration for a specific endpoint
-    fn dst_config(env: &Env, dst_eid: u32) -> Option<DstConfig>;
+/// Parameters for a native token drop.
+///
+/// Used to specify native token transfers as part of executor options.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct NativeDropParams {
+    /// Receiver address for the native token transfer.
+    pub receiver: Address,
+    /// Amount of native tokens to transfer.
+    pub amount: i128,
+}
 
-    /// Set destination configurations (admin only)
+// ============================================================================
+// IExecutor Trait
+// ============================================================================
+
+#[contractclient(name = "ExecutorClient")]
+pub trait IExecutor: Worker + ILayerZeroExecutor {
+    /// Sets destination-specific configurations for multiple endpoints.
+    ///
+    /// # Arguments
+    /// * `admin` - Admin address (must provide authorization)
+    /// * `params` - Vector of (dst_eid, DstConfig) pairs to set
     fn set_dst_config(env: &Env, admin: &Address, params: &Vec<SetDstConfigParam>);
 
-    // === Execution Functions ===
+    /// Returns the destination configuration for a specific endpoint.
+    ///
+    /// # Arguments
+    /// * `dst_eid` - Destination endpoint ID (chain identifier)
+    fn dst_config(env: &Env, dst_eid: u32) -> DstConfig;
 
-    /// Execute native token drops
+    /// Native token drops.
+    ///
+    /// Transfers native tokens to each receiver specified in the parameters and
+    /// tracks the success/failure status of each transfer.
+    ///
+    /// # Arguments
+    /// * `admin` - Admin address (must provide authorization)
+    /// * `origin` - Origin of the message
+    /// * `dst_eid` - Destination endpoint ID (chain identifier)
+    /// * `oapp` - OApp address
+    /// * `native_drop_params` - Vector of (receiver, amount) pairs to transfer
     fn native_drop(
         env: &Env,
         admin: &Address,
@@ -32,9 +85,6 @@ pub trait IExecutor: IWorker + ILayerZeroExecutor {
         native_drop_params: &Vec<NativeDropParams>,
     );
 
-    /// Execute v2 message
-    fn execute(env: &Env, admin: &Address, execution_params: &ExecutionParams);
-
-    /// Compose v2 message
-    fn compose(env: &Env, admin: &Address, compose_params: &ComposeParams);
+    /// Returns the endpoint address.
+    fn endpoint(env: &Env) -> Address;
 }

package/contracts/workers/executor/src/interfaces/mod.rs

@@ -1,5 +1,3 @@
 pub mod executor;
-pub mod types;
 
 pub use executor::*;
-pub use types::*;

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

@@ -1,10 +1,19 @@
 #![no_std]
 
-pub mod events;
-pub mod executor;
-pub mod interfaces;
-pub mod storage;
-
-pub use events::*;
-pub use executor::*;
+mod interfaces;
 pub use interfaces::*;
+
+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"))] {
+        mod errors;
+        mod events;
+        mod storage;
+        mod lz_executor;
+
+        pub use lz_executor::{LzExecutor, LzExecutorClient, WhitelistEntry};
+    }
+}
+
+// #[cfg(test)]
+// mod tests;

package/contracts/workers/executor/src/lz_executor.rs

@@ -0,0 +1,308 @@
+use crate::{
+    errors::ExecutorError,
+    events::{DstConfigSet, NativeDropApplied},
+    interfaces::{DstConfig, IExecutor, SetDstConfigParam},
+    storage::ExecutorStorage,
+    NativeDropParams,
+};
+use common_macros::{contract_impl, only_owner, ttl_configurable};
+use endpoint_v2::{FeeRecipient, LayerZeroEndpointV2Client, Origin};
+use message_lib_common::interfaces::ILayerZeroExecutor;
+use soroban_sdk::{
+    address_payload::AddressPayload,
+    auth::{Context, CustomAccountInterface},
+    contract, contractimpl, contracttype,
+    crypto::Hash,
+    token::TokenClient,
+    vec, Address, Bytes, BytesN, Env, Symbol, Vec,
+};
+use utils::option_ext::OptionExt;
+use utils::ownable::Ownable;
+use worker::{
+    assert_acl, assert_not_paused, assert_supported_message_lib, init_worker, require_admin_auth, ExecutorFeeLibClient,
+    FeeParams, Worker, set_admin_by_owner,
+};
+
+/// Signature data for Custom Account authorization.
+/// Contains the admin's public key and their Ed25519 signature over the authorization payload.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ExecutorSignature {
+    /// Admin's Ed25519 public key (32 bytes) - must correspond to a registered admin
+    pub public_key: BytesN<32>,
+    /// Ed25519 signature (64 bytes) over the signature_payload
+    pub signature: BytesN<64>,
+}
+
+/// Whitelist entry for authorized (contract, function) pairs.
+///
+/// Used to configure which contracts and functions can trigger Executor authorization.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct WhitelistEntry {
+    /// Contract address that is allowed to call the function.
+    pub contract: Address,
+    /// Function name that is whitelisted for this contract.
+    pub fn_name: Symbol,
+}
+
+/// LayerZero Executor contract for cross-chain message execution.
+#[contract]
+#[ttl_configurable]
+pub struct LzExecutor;
+
+#[contract_impl]
+impl LzExecutor {
+    /// Initializes the executor contract.
+    ///
+    /// Sets up ownership, worker configuration, endpoint address, and whitelisted functions.
+    ///
+    /// # Arguments
+    /// * `endpoint` - LayerZero Endpoint V2 contract address
+    /// * `owner` - Contract owner address
+    /// * `admins` - Initial admin addresses (must not be empty)
+    /// * `message_libs` - Supported message library addresses (e.g., ULN302)
+    /// * `price_feed` - Price feed contract address for fee calculations
+    /// * `default_multiplier_bps` - Default fee multiplier in basis points (10000 = 1x)
+    /// * `whitelist` - Initial whitelisted (contract, function) pairs for authorization
+    pub fn __constructor(
+        env: &Env,
+        endpoint: &Address,
+        owner: &Address,
+        admins: &Vec<Address>,
+        message_libs: &Vec<Address>,
+        price_feed: &Address,
+        default_multiplier_bps: u32,
+        whitelist: &Vec<WhitelistEntry>,
+    ) {
+        Self::init_owner(env, owner);
+        init_worker::<Self>(env, admins, message_libs, price_feed, default_multiplier_bps);
+        ExecutorStorage::set_endpoint(env, endpoint);
+
+        // Set initial whitelisted functions
+        for entry in whitelist.iter() {
+            ExecutorStorage::set_whitelisted_fn(env, &entry.contract, &entry.fn_name, &true);
+        }
+    }
+
+    /// Sets whether a (contract, function) pair is whitelisted.
+    /// When `allowed` is false, the entry is removed from storage to save space.
+    ///
+    /// Only the contract owner can call this function.
+    #[only_owner]
+    pub fn set_whitelisted_fn(env: &Env, contract: &Address, fn_name: &Symbol, allowed: bool) {
+        let value = if allowed { Some(true) } else { None };
+        ExecutorStorage::set_or_remove_whitelisted_fn(env, contract, fn_name, &value);
+    }
+
+    /// Returns whether a (contract, function) pair is whitelisted.
+    pub fn is_whitelisted_fn(env: &Env, contract: &Address, fn_name: &Symbol) -> bool {
+        ExecutorStorage::has_whitelisted_fn(env, contract, fn_name)
+    }
+
+    /// Withdraws a token from the contract to a specified address.
+    ///
+    /// # Arguments
+    /// * `token` - The token contract address
+    /// * `to` - The recipient address
+    /// * `amount` - The amount to withdraw
+    pub fn withdraw_token(env: &Env, admin: &Address, token: &Address, to: &Address, amount: i128) {
+        require_admin_auth::<Self>(env, admin);
+        TokenClient::new(env, token).transfer(&env.current_contract_address(), to, &amount);
+    }
+
+    /// Sets admin status for an address. Requires owner authorization.
+    ///
+    /// This is the multisig/quorum path for admin management.
+    ///
+    /// # Arguments
+    /// * `admin` - The address to set admin status for
+    /// * `active` - Whether the address should be an admin
+    pub fn set_admin(env: &Env, admin: &Address, active: bool) {
+        set_admin_by_owner::<Self>(env, admin, active);
+    }
+}
+
+// ============================================================================
+// IExecutor implementation
+// ============================================================================
+
+#[contract_impl]
+impl IExecutor for LzExecutor {
+    /// Sets destination-specific configurations for multiple endpoints.
+    fn set_dst_config(env: &Env, admin: &Address, params: &Vec<SetDstConfigParam>) {
+        require_admin_auth::<Self>(env, admin);
+
+        for param in params {
+            ExecutorStorage::set_dst_config(env, param.dst_eid, &param.dst_config);
+        }
+        DstConfigSet { params: params.clone() }.publish(env);
+    }
+
+    /// Returns the destination configuration for a specific endpoint.
+    fn dst_config(env: &Env, dst_eid: u32) -> DstConfig {
+        ExecutorStorage::dst_config(env, dst_eid).unwrap_or_panic(env, ExecutorError::EidNotSupported)
+    }
+
+    /// Native token drops.
+    ///
+    /// Transfers native tokens to each receiver specified in the parameters and
+    /// tracks the success/failure status of each transfer.
+    fn native_drop(
+        env: &Env,
+        admin: &Address,
+        origin: &Origin,
+        dst_eid: u32,
+        oapp: &Address,
+        native_drop_params: &Vec<NativeDropParams>,
+    ) {
+        require_admin_auth::<Self>(env, admin);
+
+        let endpoint_client = LayerZeroEndpointV2Client::new(env, &Self::endpoint(env));
+        let token_client = TokenClient::new(env, &endpoint_client.native_token());
+
+        // Transfer native tokens from admin to each receiver and track success/failure
+        let mut success = vec![env];
+        for param in native_drop_params {
+            success.push_back(token_client.try_transfer(admin, &param.receiver, &param.amount).is_ok());
+        }
+
+        // Emit event with transfer results
+        NativeDropApplied {
+            origin: origin.clone(),
+            dst_eid,
+            oapp: oapp.clone(),
+            native_drop_params: native_drop_params.clone(),
+            success,
+        }
+        .publish(env);
+    }
+
+    /// Returns the endpoint address from storage.
+    fn endpoint(env: &Env) -> Address {
+        ExecutorStorage::endpoint(env).unwrap()
+    }
+}
+
+// ============================================================================
+// ILayerZeroExecutor implementation (send-flow)
+// ============================================================================
+
+#[contract_impl]
+impl ILayerZeroExecutor for LzExecutor {
+    /// Assigns a job to the executor and returns fee recipient information.
+    fn assign_job(
+        env: &Env,
+        send_lib: &Address,
+        sender: &Address,
+        dst_eid: u32,
+        calldata_size: u32,
+        options: &Bytes,
+    ) -> FeeRecipient {
+        send_lib.require_auth();
+        assert_supported_message_lib::<Self>(env, send_lib);
+        // `get_fee` already asserts not_paused and acl, so we don't need to do it here again
+
+        let fee = Self::get_fee(env, send_lib, sender, dst_eid, calldata_size, options);
+        FeeRecipient { amount: fee, to: Self::deposit_address(env) }
+    }
+
+    /// Calculates the execution fee for a cross-chain message.
+    fn get_fee(
+        env: &Env,
+        _send_lib: &Address,
+        sender: &Address,
+        dst_eid: u32,
+        calldata_size: u32,
+        options: &Bytes,
+    ) -> i128 {
+        assert_not_paused::<Self>(env);
+        assert_acl::<Self>(env, sender);
+
+        let dst_config = Self::dst_config(env, dst_eid);
+        let fee_params = FeeParams {
+            sender: sender.clone(),
+            dst_eid,
+            calldata_size,
+            options: options.clone(),
+            price_feed: Self::price_feed(env),
+            default_multiplier_bps: Self::default_multiplier_bps(env),
+            lz_receive_base_gas: dst_config.lz_receive_base_gas,
+            lz_compose_base_gas: dst_config.lz_compose_base_gas,
+            floor_margin_usd: dst_config.floor_margin_usd,
+            native_cap: dst_config.native_cap,
+            multiplier_bps: dst_config.multiplier_bps,
+        };
+
+        ExecutorFeeLibClient::new(env, &Self::worker_fee_lib(env)).get_fee(&env.current_contract_address(), &fee_params)
+    }
+}
+
+// ============================================================================
+// CustomAccountInterface implementation, used for receive-flow execution
+// ============================================================================
+
+#[contractimpl]
+impl CustomAccountInterface for LzExecutor {
+    type Signature = ExecutorSignature;
+    type Error = ExecutorError;
+
+    /// Verifies authorization for the executor contract.
+    ///
+    /// The public key must correspond to a registered admin and must have signed the signature_payload.
+    /// Uses Ed25519 signature verification.
+    /// Only whitelisted function calls are authorized.
+    fn __check_auth(
+        env: Env,
+        signature_payload: Hash<32>,
+        auth_data: Self::Signature,
+        auth_contexts: Vec<Context>,
+    ) -> Result<(), Self::Error> {
+        Self::verify_admin_signature(&env, &signature_payload, &auth_data)?;
+        Self::validate_auth_contexts(&env, &auth_contexts)?;
+        Ok(())
+    }
+}
+
+impl LzExecutor {
+    /// Verifies that the signature is from a registered admin.
+    ///
+    /// Converts the public key to an address, checks admin registration,
+    /// and verifies the Ed25519 signature over the payload.
+    fn verify_admin_signature(
+        env: &Env,
+        signature_payload: &Hash<32>,
+        auth_data: &ExecutorSignature,
+    ) -> Result<(), ExecutorError> {
+        let admin = Address::from_payload(env, AddressPayload::AccountIdPublicKeyEd25519(auth_data.public_key.clone()));
+        if !Self::is_admin(env, &admin) {
+            return Err(ExecutorError::Unauthorized);
+        }
+        env.crypto().ed25519_verify(&auth_data.public_key, &signature_payload.clone().into(), &auth_data.signature);
+        Ok(())
+    }
+
+    /// Validates that the first auth context is a whitelisted (contract, function) pair.
+    /// Sub-invocations are trusted since they're controlled by the whitelisted contract.
+    fn validate_auth_contexts(env: &Env, contexts: &Vec<Context>) -> Result<(), ExecutorError> {
+        let first_context = contexts.first().ok_or(ExecutorError::UnauthorizedContext)?;
+
+        match first_context {
+            Context::Contract(contract_context) => {
+                // Check if (contract, fn_name) pair is whitelisted
+                if !Self::is_whitelisted_fn(env, &contract_context.contract, &contract_context.fn_name) {
+                    return Err(ExecutorError::UnauthorizedContext);
+                }
+            }
+            // Contract creation is not allowed
+            Context::CreateContractHostFn(_) | Context::CreateContractWithCtorHostFn(_) => {
+                return Err(ExecutorError::UnauthorizedContext);
+            }
+        }
+
+        Ok(())
+    }
+}
+
+#[contractimpl(contracttrait)]
+impl Worker for LzExecutor {}

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

@@ -1,23 +1,31 @@
-use crate::interfaces::DstConfig;
 use common_macros::storage;
-use soroban_sdk::Address;
-use utils::ttl::DefaultTtlConfigProvider;
+use soroban_sdk::{Address, Symbol};
 
-// ============================================================================
-// Executor Storage
-// ============================================================================
+use crate::DstConfig;
 
-#[storage(DefaultTtlConfigProvider)]
-pub enum ExecutorData {
-    /// Endpoint V2 address
+/// Storage keys for the Executor contract.
+///
+/// Manages persistent storage for destination configurations and instance storage
+/// for the endpoint address and whitelisted functions.
+#[storage]
+pub enum ExecutorStorage {
+    /// Destination chain configuration indexed by endpoint ID.
+    ///
+    /// Stores `DstConfig` for each destination endpoint, containing gas costs,
+    /// fee multipliers, and native caps.
+    #[persistent(DstConfig)]
+    DstConfig { eid: u32 },
+
+    /// LayerZero Endpoint V2 contract address.
+    ///
+    /// Used for receive-flow operations to interact with the endpoint.
     #[instance(Address)]
     Endpoint,
 
-    /// Local endpoint ID (EID)
-    #[instance(u32)]
-    LocalEid,
-
-    /// Destination configuration per EID
-    #[persistent(DstConfig)]
-    DstConfig { eid: u32 },
+    /// Whitelisted function for a specific contract.
+    ///
+    /// Only whitelisted (contract, function) pairs can trigger Executor authorization.
+    /// This allows fine-grained control over which contracts can call which functions.
+    #[instance(bool)]
+    WhitelistedFn { contract: Address, fn_name: Symbol },
 }

package/contracts/workers/executor-fee-lib/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "executor-fee-lib"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+doctest = false
+
+[dependencies]
+soroban-sdk = { workspace = true }
+# workspace dependencies
+utils = { workspace = true }
+worker = { workspace = true }
+common-macros = { workspace = true }
+message-lib-common = { workspace = true }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }
+

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

@@ -0,0 +1,15 @@
+use common_macros::contract_error;
+
+#[contract_error]
+pub enum ExecutorFeeLibError {
+    NoOptions,
+    UnsupportedOptionType,
+    ZeroLzReceiveGasProvided,
+    ZeroLzComposeGasProvided,
+    NativeAmountExceedsCap,
+    InvalidLzReceiveOption,
+    InvalidNativeDropOption,
+    InvalidLzComposeOption,
+    InvalidExecutorOptions,
+    EidNotSupported,
+}