@layerzerolabs/protocol-stellar-v2 0.2.8

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

@@ -0,0 +1,23 @@
+use crate::interfaces::DstConfig;
+use common_macros::storage;
+use soroban_sdk::Address;
+use utils::ttl::DefaultTtlConfigProvider;
+
+// ============================================================================
+// Executor Storage
+// ============================================================================
+
+#[storage(DefaultTtlConfigProvider)]
+pub enum ExecutorData {
+    /// Endpoint V2 address
+    #[instance(Address)]
+    Endpoint,
+
+    /// Local endpoint ID (EID)
+    #[instance(u32)]
+    LocalEid,
+
+    /// Destination configuration per EID
+    #[persistent(DstConfig)]
+    DstConfig { eid: u32 },
+}

package/contracts/workers/lib.rs

@@ -0,0 +1,2 @@
+#![no_std]
+// This is an empty library crate that serves as a parent for workers packages

package/contracts/workers/worker-common/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "worker-common"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lib]
+crate-type = ["rlib"]
+doctest = false
+
+[dependencies]
+soroban-sdk = { workspace = true }
+utils = { workspace = true }
+common-macros = { workspace = true }
+stellar-access = { workspace = true }
+stellar-macros = { workspace = true }
+stellar-contract-utils = { workspace = true }

package/contracts/workers/worker-common/src/constants.rs

@@ -0,0 +1,17 @@
+use soroban_sdk::{symbol_short, Symbol};
+
+// ============================================================================
+// Role Constants (matching EVM Worker.sol)
+// ============================================================================
+
+/// MESSAGE_LIB_ROLE - Role for message libraries that can interact with the worker
+pub const MESSAGE_LIB_ROLE: Symbol = symbol_short!("MSG_LIB");
+
+/// ALLOWLIST - Role for addresses allowed to use the worker
+pub const ALLOWLIST: Symbol = symbol_short!("ALLOW");
+
+/// DENYLIST - Role for addresses denied from using the worker
+pub const DENYLIST: Symbol = symbol_short!("DENY");
+
+/// ADMIN_ROLE - Role for admins who can configure worker settings
+pub const ADMIN_ROLE: Symbol = symbol_short!("ADMIN");

package/contracts/workers/worker-common/src/errors.rs

@@ -0,0 +1,6 @@
+use common_macros::contract_error;
+
+#[contract_error]
+pub enum WorkerError {
+    NotAllowed = 12000,
+}

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

@@ -0,0 +1,34 @@
+use soroban_sdk::{contractevent, Address, Bytes};
+
+// === Worker Events ===
+// Note: Role-related events (RoleGranted, RoleRevoked, etc.) are emitted by OpenZeppelin AccessControl
+#[contractevent(topics = ["SetDefaultMultiplierBps"])]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SetDefaultMultiplierBps {
+    pub multiplier_bps: u32,
+}
+
+#[contractevent(topics = ["SetDepositAddress"])]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SetDepositAddress {
+    pub deposit_address: Address,
+}
+
+#[contractevent(topics = ["SetPriceFeed"])]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SetPriceFeed {
+    pub price_feed: Address,
+}
+
+#[contractevent(topics = ["SetSupportedOptionTypes"])]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SetSupportedOptionTypes {
+    pub dst_eid: u32,
+    pub option_types: Bytes,
+}
+
+#[contractevent(topics = ["SetWorkerFeeLib"])]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SetWorkerFeeLib {
+    pub fee_lib: Address,
+}

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

@@ -0,0 +1,35 @@
+use soroban_sdk::{contractclient, contracttype, Address, Bytes, Env};
+
+/// FeeParams - Parameters for standard fee calculation same with the Sui
+#[contracttype]
+#[derive(Clone, Debug)]
+pub struct FeeParams {
+    // message params
+    pub sender: Address,
+    pub dst_eid: u32,
+    pub calldata_size: u32,
+    pub options: Bytes,
+    // common configed params
+    pub price_feed: Address,
+    pub default_multiplier_bps: u32,
+    // by dst_eid configed params
+    pub lz_receive_base_gas: u64,
+    pub lz_compose_base_gas: u64,
+    pub floor_margin_usd: u128,
+    pub native_cap: u128,
+    pub multiplier_bps: u32,
+}
+
+/// IExecutorFeeLib - Interface for calculating executor fees
+/// This interface is called by the Executor contract to calculate fees
+/// It uses the PriceFeed interface to get price information
+#[contractclient(name = "ExecutorFeeLibClient")]
+pub trait IExecutorFeeLib {
+    /// Calculate fee (view function, standard params)
+    /// Called by get_fee in the Executor contract
+    fn get_fee(env: &Env, fee_lib: &Address, params: &FeeParams) -> i128;
+
+    /// Returns the current contract version.
+    /// Because not allow return u8, use u32 instead.
+    fn version(env: &Env) -> (u64, u32);
+}

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

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

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

@@ -0,0 +1,40 @@
+use soroban_sdk::{contractclient, contracttype, Address, Env};
+
+/// Struct to encapsulate the return values of estimate_fee_by_eid
+#[contracttype]
+#[derive(Clone, Debug)]
+pub struct EstimateFeeResult {
+    pub fee: i128,
+    pub price_ratio: u128,
+    pub price_ratio_denominator: u128,
+    pub native_price_usd: u128,
+}
+
+/// ILayerZeroPriceFeed - Interface for price feed contract
+/// This interface provides price information for fee calculation
+/// Called by ExecutorFeeLib to get pricing data
+#[contractclient(name = "LayerZeroPriceFeedClient")]
+pub trait ILayerZeroPriceFeed {
+    /// Estimate fee with detailed breakdown by endpoint ID
+    /// This is the main function called by ExecutorFeeLib
+    /// @param dst_eid - Destination endpoint ID
+    /// @param calldata_size - Size of the calldata in bytes
+    /// @param gas - Gas amount needed for execution
+    /// @return (fee, price_ratio, price_ratio_denominator, native_price_usd)
+    fn estimate_fee_by_eid(
+        env: &Env,
+        fee_lib: &Address,
+        dst_eid: u32,
+        calldata_size: u64,
+        gas: u128,
+    ) -> EstimateFeeResult;
+
+    /// Get the native token price in USD
+    /// @return native_token_price_usd - The price of the native token in USD
+    fn native_token_price_usd(env: &Env) -> u128;
+
+    /// Set the native token price in USD
+    /// @param price_updater - The address of the price updater
+    /// @param native_token_price_usd - The new price of the native token in USD
+    fn set_native_token_price_usd(env: &Env, price_updater: &Address, native_token_price_usd: u128);
+}

package/contracts/workers/worker-common/src/interfaces/worker.rs

@@ -0,0 +1,60 @@
+use soroban_sdk::{contractclient, Address, Bytes, Env};
+
+/// IWorker - Base worker interface for managing fees, price feeds, and admin operations
+/// Uses OpenZeppelin AccessControl for role-based access management
+#[contractclient(name = "WorkerClient")]
+pub trait IWorker {
+    // ========================================================================
+    // Mutable Functions
+    // ========================================================================
+
+    /// Set the paused state of the worker (requires DEFAULT_ADMIN_ROLE)
+    fn set_paused(env: &Env, paused: bool);
+
+    /// Set the default multiplier in basis points (ADMIN_ROLE only)
+    fn set_default_multiplier_bps(env: &Env, admin: &Address, multiplier_bps: u32);
+
+    /// Set the deposit address where fees are collected (admin only)
+    fn set_deposit_address(env: &Env, admin: &Address, deposit_address: &Address);
+
+    /// Set the price feed address (admin only)
+    fn set_price_feed(env: &Env, admin: &Address, price_feed: &Address);
+
+    /// Set supported option types for a destination endpoint (ADMIN_ROLE only)
+    fn set_supported_option_types(env: &Env, admin: &Address, eid: u32, option_types: Bytes);
+
+    /// Set the worker fee library address (ADMIN_ROLE only)
+    fn set_worker_fee_lib(env: &Env, admin: &Address, worker_fee_lib: &Address);
+
+    // ========================================================================
+    // View Functions
+    // ========================================================================
+
+    /// Check if the worker is paused
+    fn paused(env: &Env) -> bool;
+
+    /// Get the default multiplier in basis points
+    fn default_multiplier_bps(env: &Env) -> u32;
+
+    /// Get the deposit address
+    fn deposit_address(env: &Env) -> Address;
+
+    /// Get the current price feed address
+    fn price_feed(env: &Env) -> Address;
+
+    /// Get supported option types for a destination endpoint
+    fn get_supported_option_types(env: &Env, eid: u32) -> Bytes;
+
+    /// Get the worker fee library address
+    fn worker_fee_lib(env: &Env) -> Address;
+
+    /// Check if an address has ACL permission
+    /// ACL logic (matching EVM Worker.sol):
+    /// 1) if address has DENYLIST role -> deny
+    /// 2) else if allowlist is empty (size == 0) OR address has ALLOWLIST role -> allow
+    /// 3) else deny
+    fn has_acl(env: &Env, sender: &Address) -> bool;
+
+    /// Get the size of the allowlist (number of accounts with ALLOWLIST role)
+    fn allowlist_size(env: &Env) -> u32;
+}

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

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

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

@@ -0,0 +1,32 @@
+use common_macros::storage;
+use soroban_sdk::{Address, Bytes};
+use utils::ttl::DefaultTtlConfigProvider;
+
+// ============================================================================
+// Worker Storage
+// ============================================================================
+// Note: Access control (roles) are managed by OpenZeppelin AccessControl module
+// We only keep worker-specific data here
+
+#[storage(DefaultTtlConfigProvider)]
+pub enum WorkerData {
+    /// Address where fees are deposited
+    #[instance(Address)]
+    DepositAddress,
+
+    /// Price feed address for fee calculation
+    #[instance(Address)]
+    PriceFeed,
+
+    /// Worker fee library address
+    #[instance(Address)]
+    WorkerFeeLib,
+
+    /// Default multiplier in basis points for fee calculation
+    #[instance(u32)]
+    DefaultMultiplierBps,
+
+    /// Supported option types for a destination EID
+    #[persistent(Bytes)]
+    SupportedOptionTypes { eid: u32 },
+}

package/contracts/workers/worker-common/src/worker_common.rs

@@ -0,0 +1,166 @@
+use soroban_sdk::{Address, Bytes, Env, Vec};
+use stellar_access::access_control;
+use stellar_contract_utils::pausable::{self as pausable};
+use stellar_macros::{only_admin, only_role};
+
+use crate::{
+    constants::{ADMIN_ROLE, ALLOWLIST, DENYLIST, MESSAGE_LIB_ROLE},
+    events::{SetDefaultMultiplierBps, SetDepositAddress, SetPriceFeed, SetSupportedOptionTypes, SetWorkerFeeLib},
+    storage::WorkerData,
+};
+
+// ============================================================================
+// WorkerCommon - Encapsulates worker operations
+// ============================================================================
+
+/// WorkerCommon provides shared functionality for LayerZero workers (DVN and Executor)
+/// Uses OpenZeppelin AccessControl for role-based permissions
+pub struct WorkerCommon;
+
+impl WorkerCommon {
+    // ========================================================================
+    // Initialization (Constructor Helper)
+    // ========================================================================
+
+    /// Initialize worker with OpenZeppelin AccessControl
+    /// This should be called in the contract's constructor (__constructor)
+    pub fn initialize(
+        env: &Env,
+        role_admin: &Address,
+        message_libs: &Vec<Address>,
+        price_feed: &Address,
+        default_multiplier_bps: u32,
+        admins: &Vec<Address>,
+    ) {
+        // Set the DEFAULT_ADMIN_ROLE (the top-level admin)
+        access_control::set_admin(env, role_admin);
+
+        // Grant MESSAGE_LIB_ROLE to all message libraries
+        for i in 0..message_libs.len() {
+            let message_lib = message_libs.get(i).unwrap();
+            access_control::grant_role_no_auth(env, role_admin, &message_lib, &MESSAGE_LIB_ROLE);
+        }
+
+        // Grant ADMIN_ROLE to all admins
+        for i in 0..admins.len() {
+            let admin_addr = admins.get(i).unwrap();
+            access_control::grant_role_no_auth(env, role_admin, &admin_addr, &ADMIN_ROLE);
+        }
+
+        // Initialize worker-specific data
+        WorkerData::set_price_feed(env, price_feed);
+        WorkerData::set_default_multiplier_bps(env, &default_multiplier_bps);
+    }
+
+    // ========================================================================
+    // Mutable Functions
+    // ========================================================================
+
+    /// Set the paused state of the worker (requires DEFAULT_ADMIN_ROLE)
+    #[only_admin]
+    pub fn set_paused(env: &Env, paused: bool) {
+        if paused {
+            pausable::pause(env);
+        } else {
+            pausable::unpause(env);
+        }
+    }
+
+    /// Set the default multiplier in basis points (ADMIN_ROLE only)
+    #[only_role(admin, "ADMIN")]
+    pub fn set_default_multiplier_bps(env: &Env, admin: &Address, multiplier_bps: u32) {
+        WorkerData::set_default_multiplier_bps(env, &multiplier_bps);
+        SetDefaultMultiplierBps { multiplier_bps }.publish(env);
+    }
+
+    /// Set the deposit address where fees are collected (admin only)
+    #[only_role(admin, "ADMIN")]
+    pub fn set_deposit_address(env: &Env, admin: &Address, deposit_address: &Address) {
+        WorkerData::set_deposit_address(env, deposit_address);
+
+        SetDepositAddress { deposit_address: deposit_address.clone() }.publish(env);
+    }
+
+    /// Set the price feed address (admin only)
+    #[only_role(admin, "ADMIN")]
+    pub fn set_price_feed(env: &Env, admin: &Address, price_feed: &Address) {
+        WorkerData::set_price_feed(env, price_feed);
+
+        SetPriceFeed { price_feed: price_feed.clone() }.publish(env);
+    }
+
+    /// Set supported option types for a destination endpoint (ADMIN_ROLE only)
+    #[only_role(admin, "ADMIN")]
+    pub fn set_supported_option_types(env: &Env, admin: &Address, eid: u32, option_types: Bytes) {
+        WorkerData::set_supported_option_types(env, eid, &option_types);
+
+        SetSupportedOptionTypes { dst_eid: eid, option_types }.publish(env);
+    }
+
+    /// Set the worker fee library address (ADMIN_ROLE only)
+    #[only_role(admin, "ADMIN")]
+    pub fn set_worker_fee_lib(env: &Env, admin: &Address, worker_fee_lib: &Address) {
+        WorkerData::set_worker_fee_lib(env, worker_fee_lib);
+
+        SetWorkerFeeLib { fee_lib: worker_fee_lib.clone() }.publish(env);
+    }
+
+    // ========================================================================
+    // View Functions
+    // ========================================================================
+
+    /// Check if the worker is paused
+    pub fn paused(env: &Env) -> bool {
+        pausable::paused(env)
+    }
+
+    /// Get the default multiplier in basis points
+    pub fn default_multiplier_bps(env: &Env) -> u32 {
+        WorkerData::default_multiplier_bps(env).unwrap_or(0)
+    }
+
+    /// Get the deposit address
+    pub fn deposit_address(env: &Env) -> Address {
+        WorkerData::deposit_address(env).expect("deposit address not set")
+    }
+
+    /// Get the current price feed address
+    pub fn price_feed(env: &Env) -> Address {
+        WorkerData::price_feed(env).expect("price feed not set")
+    }
+
+    /// Get supported option types for a destination endpoint
+    pub fn get_supported_option_types(env: &Env, eid: u32) -> Bytes {
+        WorkerData::supported_option_types(env, eid).unwrap_or(Bytes::new(env))
+    }
+
+    /// Get the worker fee library address
+    pub fn worker_fee_lib(env: &Env) -> Address {
+        WorkerData::worker_fee_lib(env).expect("worker fee lib not set")
+    }
+
+    /// Check if an address has ACL permission
+    /// ACL logic (matching EVM Worker.sol):
+    /// 1) if address has DENYLIST role -> deny
+    /// 2) else if allowlist is empty (size == 0) OR address has ALLOWLIST role -> allow
+    /// 3) else deny
+    pub fn has_acl(env: &Env, sender: &Address) -> bool {
+        // Check denylist first
+        if access_control::has_role(env, sender, &DENYLIST).is_some() {
+            return false;
+        }
+
+        // Check allowlist size and membership
+        let allowlist_size = Self::allowlist_size(env);
+        if allowlist_size == 0 || access_control::has_role(env, sender, &ALLOWLIST).is_some() {
+            return true;
+        }
+
+        false
+    }
+
+    /// Get the size of the allowlist (number of accounts with ALLOWLIST role)
+    pub fn allowlist_size(env: &Env) -> u32 {
+        access_control::get_role_member_count(env, &ALLOWLIST)
+    }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@layerzerolabs/protocol-stellar-v2",
+  "version": "0.2.8",
+  "private": false,
+  "devDependencies": {
+    "@types/node": "^22.18.6",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "@layerzerolabs/common-node-utils": "0.2.8",
+    "@layerzerolabs/vm-tooling-stellar": "0.2.8"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "pnpm build:contracts && pnpm generate:sdk",
+    "build:contracts": "pnpm exec lz-tool stellar contract build",
+    "format": "pnpm exec lz-tool --script \"cargo fmt\" stellar",
+    "generate:sdk": "pnpm exec lz-tool --script \"cargo run -p ts-bindings-gen\" stellar",
+    "lint": "pnpm exec lz-tool --script \"cargo clippy -- -D warnings\" stellar",
+    "lint:fix": "pnpm exec lz-tool --script \"cargo clippy --fix --allow-dirty --allow-staged && cargo fmt\" stellar",
+    "test": "pnpm exec lz-tool --script \"cargo nextest run\" stellar"
+  }
+}

package/rust-toolchain.toml

@@ -0,0 +1,4 @@
+[toolchain]
+channel = "1.90.0"
+targets = ["wasm32v1-none"]
+components = ["rustfmt", "clippy"]

package/rustfmt.toml

@@ -0,0 +1,17 @@
+
+format_macro_bodies = true
+max_width = 120
+format_macro_matchers = true
+format_strings = true
+imports_granularity = "Crate"
+match_arm_blocks = false
+reorder_impl_items = true
+group_imports = "StdExternalCrate"
+use_field_init_shorthand = true
+use_small_heuristics = "Max"
+wrap_comments = true
+format_code_in_doc_comments = true
+
+# most of these are unstable, so we enable them
+unstable_features = true
+

package/sdk/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @layerzerolabs/lz-v2-stellar-sdk@0.0.1 build /home/runner/work/monorepo-internal/monorepo-internal/contracts/protocol/stellar/sdk
+> tsc
+