@layerzerolabs/protocol-stellar-v2 0.2.8 → 0.2.9

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

@@ -0,0 +1,459 @@
+use soroban_sdk::{assert_with_error, contracttrait, Address, Bytes, Env, Vec};
+use utils::{
+    option_ext::OptionExt,
+    ownable::{enforce_owner_auth, require_owner_auth, Ownable},
+};
+
+use crate::{
+    errors::WorkerError,
+    events::{
+        Paused, SetAdmin, SetAllowlist, SetDefaultMultiplierBps, SetDenylist, SetDepositAddress, SetPriceFeed,
+        SetSupportedMessageLib, SetSupportedOptionTypes, SetWorkerFeeLib, Unpaused,
+    },
+    storage::WorkerStorage,
+};
+
+/// Worker interface providing common functionality for LayerZero workers.
+#[contracttrait]
+pub trait Worker: Ownable + Sized {
+    // ========================================================================
+    // Manager Functions
+    // ========================================================================
+
+    /// Sets the paused state of the worker.
+    ///
+    /// When paused, the worker will reject new job assignments (e.g., assign_job, get_fee).
+    /// Existing jobs in progress are not affected.
+    ///
+    /// # Arguments
+    /// * `paused` - `true` to pause, `false` to unpause
+    fn set_paused(env: &Env, paused: bool) {
+        let owner = enforce_owner_auth::<Self>(env);
+        assert_with_error!(env, Self::paused(env) != paused, WorkerError::PauseStatusUnchanged);
+
+        WorkerStorage::set_paused(env, &paused);
+        if paused {
+            Paused { pauser: owner }.publish(env);
+        } else {
+            Unpaused { unpauser: owner }.publish(env);
+        }
+    }
+
+    /// Sets whether a message library is supported by this worker.
+    ///
+    /// Message libraries (e.g., ULN302) call workers to assign jobs. Only supported
+    /// libraries can interact with this worker.
+    ///
+    /// # Arguments
+    /// * `message_lib` - The message library contract address
+    /// * `supported` - `true` to add support, `false` to remove support
+    fn set_supported_message_lib(env: &Env, message_lib: &Address, supported: bool) {
+        require_owner_auth::<Self>(env);
+        set_message_lib_no_auth::<Self>(env, message_lib, supported);
+    }
+
+    /// Sets allowlist status for an OApp address.
+    ///
+    /// When the allowlist is empty, all OApps are allowed (unless on denylist).
+    /// When the allowlist is not empty, only allowlisted OApps are allowed.
+    /// Denylist always takes precedence over allowlist.
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp contract address
+    /// * `allowed` - `true` to add to allowlist, `false` to remove
+    fn set_allowlist(env: &Env, oapp: &Address, allowed: bool) {
+        require_owner_auth::<Self>(env);
+
+        let is_on_list = Self::is_on_allowlist(env, oapp);
+        if allowed {
+            // Add to allowlist - ensure not already present
+            assert_with_error!(env, !is_on_list, WorkerError::AlreadyOnAllowlist);
+            WorkerStorage::set_allowlist(env, oapp, &true);
+            // Increment allowlist size
+            let size = Self::allowlist_size(env);
+            WorkerStorage::set_allowlist_size(env, &(size + 1));
+        } else {
+            // Remove from allowlist - ensure present
+            assert_with_error!(env, is_on_list, WorkerError::NotOnAllowlist);
+            WorkerStorage::remove_allowlist(env, oapp);
+            // Decrement allowlist size
+            let size = Self::allowlist_size(env);
+            WorkerStorage::set_allowlist_size(env, &(size - 1));
+        }
+        SetAllowlist { oapp: oapp.clone(), allowed }.publish(env);
+    }
+
+    /// Sets denylist status for an OApp address.
+    ///
+    /// Denylisted OApps are blocked from using this worker, even if they're on
+    /// the allowlist (denylist takes precedence).
+    ///
+    /// # Arguments
+    /// * `oapp` - The OApp contract address
+    /// * `denied` - `true` to add to denylist, `false` to remove
+    fn set_denylist(env: &Env, oapp: &Address, denied: bool) {
+        require_owner_auth::<Self>(env);
+        let is_on_list = Self::is_on_denylist(env, oapp);
+
+        if denied {
+            // Add to denylist - ensure not already present
+            assert_with_error!(env, !is_on_list, WorkerError::AlreadyOnDenylist);
+            WorkerStorage::set_denylist(env, oapp, &true);
+        } else {
+            // Remove from denylist - ensure present
+            assert_with_error!(env, is_on_list, WorkerError::NotOnDenylist);
+            WorkerStorage::remove_denylist(env, oapp);
+        }
+        SetDenylist { oapp: oapp.clone(), denied }.publish(env);
+    }
+
+    // ========================================================================
+    // Admin(managed by the manager) Functions
+    // ========================================================================
+
+    /// Sets the default fee multiplier in basis points.
+    ///
+    /// The multiplier is applied to base fees during fee calculation. Used when
+    /// no destination-specific multiplier is configured.
+    ///
+    /// # Arguments
+    /// * `admin` - Admin address (must provide authorization)
+    /// * `multiplier_bps` - Multiplier in basis points (10000 = 1x, 12000 = 1.2x)
+    fn set_default_multiplier_bps(env: &Env, admin: &Address, multiplier_bps: u32) {
+        require_admin_auth::<Self>(env, admin);
+        set_default_multiplier_bps_no_auth(env, multiplier_bps);
+    }
+
+    /// Sets the deposit address where worker fees are collected.
+    ///
+    /// When jobs are assigned, fees are directed to this address.
+    ///
+    /// # Arguments
+    /// * `admin` - Admin address (must provide authorization)
+    /// * `deposit_address` - Address to receive collected fees
+    fn set_deposit_address(env: &Env, admin: &Address, deposit_address: &Address) {
+        require_admin_auth::<Self>(env, admin);
+        WorkerStorage::set_deposit_address(env, deposit_address);
+        SetDepositAddress { deposit_address: deposit_address.clone() }.publish(env);
+    }
+
+    /// Sets supported executor option types for a destination endpoint.
+    ///
+    /// # Arguments
+    /// * `admin` - Admin address (must provide authorization)
+    /// * `eid` - Destination endpoint ID (chain identifier)
+    /// * `option_types` - Encoded supported option types
+    fn set_supported_option_types(env: &Env, admin: &Address, eid: u32, option_types: Bytes) {
+        require_admin_auth::<Self>(env, admin);
+        WorkerStorage::set_supported_option_types(env, eid, &option_types);
+        SetSupportedOptionTypes { dst_eid: eid, option_types }.publish(env);
+    }
+
+    /// Sets the worker fee library contract address.
+    ///
+    /// The fee library calculates fees based on executor options and price feed data.
+    ///
+    /// # Arguments
+    /// * `admin` - Admin address (must provide authorization)
+    /// * `worker_fee_lib` - Fee library contract address implementing `IExecutorFeeLib`
+    fn set_worker_fee_lib(env: &Env, admin: &Address, worker_fee_lib: &Address) {
+        require_admin_auth::<Self>(env, admin);
+        WorkerStorage::set_worker_fee_lib(env, worker_fee_lib);
+        SetWorkerFeeLib { fee_lib: worker_fee_lib.clone() }.publish(env);
+    }
+
+    /// Sets the price feed contract address.
+    ///
+    /// The price feed provides gas prices and exchange rates for cross-chain
+    /// fee calculations.
+    ///
+    /// # Arguments
+    /// * `admin` - Admin address (must provide authorization)
+    /// * `price_feed` - Price feed contract address implementing `ILayerZeroPriceFeed`
+    fn set_price_feed(env: &Env, admin: &Address, price_feed: &Address) {
+        require_admin_auth::<Self>(env, admin);
+        WorkerStorage::set_price_feed(env, price_feed);
+        SetPriceFeed { price_feed: price_feed.clone() }.publish(env);
+    }
+
+    // ========================================================================
+    // View Functions
+    // ========================================================================
+
+    /// Returns whether an address is an admin.
+    ///
+    /// # Arguments
+    /// * `admin` - The address to check
+    fn is_admin(env: &Env, admin: &Address) -> bool {
+        Self::admins(env).contains(admin)
+    }
+
+    /// Returns all admin addresses.
+    fn admins(env: &Env) -> Vec<Address> {
+        WorkerStorage::admins(env).unwrap_or(Vec::new(env))
+    }
+
+    /// Returns whether the worker is paused.
+    fn paused(env: &Env) -> bool {
+        WorkerStorage::paused(env)
+    }
+
+    /// Returns whether a message library is supported.
+    ///
+    /// # Arguments
+    /// * `message_lib` - Message library contract address
+    fn is_supported_message_lib(env: &Env, message_lib: &Address) -> bool {
+        Self::message_libs(env).contains(message_lib)
+    }
+
+    /// Returns all supported message library addresses.
+    ///
+    /// # Returns
+    /// Vector of supported message library contract addresses.
+    fn message_libs(env: &Env) -> Vec<Address> {
+        WorkerStorage::message_libs(env).unwrap_or(Vec::new(env))
+    }
+
+    /// Returns whether an OApp is on the allowlist.
+    ///
+    /// # Arguments
+    /// * `oapp` - OApp contract address
+    fn is_on_allowlist(env: &Env, oapp: &Address) -> bool {
+        WorkerStorage::has_allowlist(env, oapp)
+    }
+
+    /// Returns whether an OApp is on the denylist.
+    ///
+    /// # Arguments
+    /// * `oapp` - OApp contract address
+    fn is_on_denylist(env: &Env, oapp: &Address) -> bool {
+        WorkerStorage::has_denylist(env, oapp)
+    }
+
+    /// Returns whether an OApp has access control list (ACL) permission.
+    ///
+    /// ACL evaluation order:
+    /// 1. If on denylist → denied
+    /// 2. If allowlist is empty OR on allowlist → allowed
+    /// 3. Otherwise → denied
+    ///
+    /// # Arguments
+    /// * `sender` - OApp contract address to check
+    fn has_acl(env: &Env, sender: &Address) -> bool {
+        if Self::is_on_denylist(env, sender) {
+            return false;
+        }
+        if Self::allowlist_size(env) == 0 || Self::is_on_allowlist(env, sender) {
+            return true;
+        }
+        false
+    }
+
+    /// Returns the number of addresses on the allowlist.
+    fn allowlist_size(env: &Env) -> u32 {
+        WorkerStorage::allowlist_size(env)
+    }
+
+    /// Returns the default fee multiplier in basis points.
+    fn default_multiplier_bps(env: &Env) -> u32 {
+        WorkerStorage::default_multiplier_bps(env).unwrap_or(0)
+    }
+
+    /// Returns the deposit address where fees are collected.
+    fn deposit_address(env: &Env) -> Address {
+        WorkerStorage::deposit_address(env).unwrap_or_panic(env, WorkerError::DepositAddressNotSet)
+    }
+
+    /// Returns the price feed contract address.
+    fn price_feed(env: &Env) -> Address {
+        WorkerStorage::price_feed(env).unwrap_or_panic(env, WorkerError::PriceFeedNotSet)
+    }
+
+    /// Returns supported option types for a destination endpoint.
+    ///
+    /// # Arguments
+    /// * `eid` - Destination endpoint ID (chain identifier)
+    fn get_supported_option_types(env: &Env, eid: u32) -> Option<Bytes> {
+        WorkerStorage::supported_option_types(env, eid)
+    }
+
+    /// Returns the worker fee library contract address.
+    fn worker_fee_lib(env: &Env) -> Address {
+        WorkerStorage::worker_fee_lib(env).unwrap_or_panic(env, WorkerError::WorkerFeeLibNotSet)
+    }
+}
+
+// ============================================================================================
+// Worker Initializer
+// ============================================================================================
+
+/// Initializes a worker contract with configuration.
+///
+/// This function should be called only once to initialize the worker once.
+///
+/// # Arguments
+/// * `admins` - Initial admin addresses (must not be empty)
+/// * `message_libs` - Supported message library addresses
+/// * `price_feed` - Price feed contract address
+/// * `default_multiplier_bps` - Default fee multiplier in basis points
+pub fn init_worker<T: Worker>(
+    env: &Env,
+    admins: &Vec<Address>,
+    message_libs: &Vec<Address>,
+    price_feed: &Address,
+    default_multiplier_bps: u32,
+) {
+    assert_with_error!(env, T::admins(env).is_empty(), WorkerError::ReInitialize);
+    assert_with_error!(env, !admins.is_empty(), WorkerError::NoAdminsProvided);
+
+    for admin in admins {
+        set_admin_no_auth::<T>(env, &admin, true);
+    }
+
+    for lib in message_libs {
+        set_message_lib_no_auth::<T>(env, &lib, true);
+    }
+
+    set_price_feed_no_auth(env, price_feed);
+    set_default_multiplier_bps_no_auth(env, default_multiplier_bps);
+}
+
+// ============================================================================================
+// Assert Helper Functions
+// ============================================================================================
+
+/// Requires admin authorization for the given address.
+///
+/// # Arguments
+/// * `admin` - The address to check for admin status
+///
+/// # Errors
+/// * `Unauthorized` - If the address is not an admin or authorization fails.
+pub fn require_admin_auth<T: Worker>(env: &Env, admin: &Address) {
+    admin.require_auth();
+    assert_with_error!(env, T::is_admin(env, admin), WorkerError::Unauthorized);
+}
+
+/// Asserts that an OApp has ACL permission, panics otherwise.
+///
+/// # Arguments
+/// * `sender` - OApp contract address to check
+///
+/// # Errors
+/// * `NotAllowed` - If the OApp is not allowed to use this worker.
+pub fn assert_acl<T: Worker>(env: &Env, sender: &Address) {
+    assert_with_error!(env, T::has_acl(env, sender), WorkerError::NotAllowed);
+}
+
+/// Asserts that the worker is not paused, panics otherwise.
+///
+/// # Errors
+/// * `WorkerIsPaused` - If the worker is currently paused.
+pub fn assert_not_paused<T: Worker>(env: &Env) {
+    assert_with_error!(env, !T::paused(env), WorkerError::WorkerIsPaused);
+}
+
+/// Asserts that a message library is supported, panics otherwise.
+///
+/// # Arguments
+/// * `message_lib` - Message library contract address to check
+///
+/// # Errors
+/// * `UnsupportedMessageLib` - If the message library is not supported.
+pub fn assert_supported_message_lib<T: Worker>(env: &Env, message_lib: &Address) {
+    assert_with_error!(env, T::is_supported_message_lib(env, message_lib), WorkerError::UnsupportedMessageLib);
+}
+
+// ============================================================================================
+// Internal Functions
+// ============================================================================================
+
+/// Sets admin status for an address without authentication.
+///
+/// Adds or removes an admin from the admin list and updates storage.
+///
+/// # Arguments
+/// * `admin` - Address to set admin status for
+/// * `active` - `true` to add admin, `false` to remove
+fn set_admin_no_auth<T: Worker>(env: &Env, admin: &Address, active: bool) {
+    let mut admins = T::admins(env);
+
+    if active {
+        // Add admin - ensure not already active
+        assert_with_error!(env, !admins.contains(admin), WorkerError::AdminAlreadyExists);
+        admins.push_back(admin.clone());
+    } else {
+        // Remove admin - ensure present
+        assert_with_error!(env, admins.contains(admin), WorkerError::AdminNotFound);
+        assert_with_error!(env, admins.len() > 1, WorkerError::AttemptingToRemoveOnlyAdmin);
+        let index = admins.first_index_of(admin).unwrap();
+        admins.remove(index);
+    }
+    WorkerStorage::set_admins(env, &admins);
+    SetAdmin { admin: admin.clone(), active }.publish(env);
+}
+
+/// Sets admin status for an address by owner.
+///
+/// # Arguments
+/// * `admin` - The address to set admin status for
+/// * `active` - `true` to add admin, `false` to remove
+pub fn set_admin_by_owner<T: Worker>(env: &Env, admin: &Address, active: bool) {
+    require_owner_auth::<T>(env);
+    set_admin_no_auth::<T>(env, admin, active);
+}
+
+/// Sets admin status for an address by admin.
+///
+/// # Arguments
+/// * `caller` - The admin calling this function (must provide authorization)
+/// * `admin` - The address to set admin status for
+/// * `active` - `true` to add admin, `false` to remove
+pub fn set_admin_by_admin<T: Worker>(env: &Env, caller: &Address, admin: &Address, active: bool) {
+    require_admin_auth::<T>(env, caller);
+    set_admin_no_auth::<T>(env, admin, active);
+}
+
+/// Sets message library support status without authentication.
+///
+/// Adds or removes a message library from the supported libraries list.
+///
+/// # Arguments
+/// * `message_lib` - Message library contract address
+/// * `supported` - `true` to add support, `false` to remove
+fn set_message_lib_no_auth<T: Worker>(env: &Env, message_lib: &Address, supported: bool) {
+    let mut libs = T::message_libs(env);
+
+    if supported {
+        // Add message lib - ensure not already supported
+        assert_with_error!(env, !libs.contains(message_lib), WorkerError::MessageLibAlreadySupported);
+        libs.push_back(message_lib.clone());
+        WorkerStorage::set_message_libs(env, &libs);
+    } else {
+        // Remove message lib - ensure present
+        assert_with_error!(env, libs.contains(message_lib), WorkerError::MessageLibNotSupported);
+        let index = libs.first_index_of(message_lib).unwrap();
+        libs.remove(index);
+        WorkerStorage::set_message_libs(env, &libs);
+    }
+
+    SetSupportedMessageLib { message_lib: message_lib.clone(), supported }.publish(env);
+}
+
+/// Sets the price feed contract address without authentication.
+///
+/// # Arguments
+/// * `price_feed` - Price feed contract address
+fn set_price_feed_no_auth(env: &Env, price_feed: &Address) {
+    WorkerStorage::set_price_feed(env, price_feed);
+    SetPriceFeed { price_feed: price_feed.clone() }.publish(env);
+}
+
+/// Sets the default fee multiplier in basis points without authentication.
+///
+/// # Arguments
+/// * `default_multiplier_bps` - Default multiplier in basis points (10000 = 1x)
+fn set_default_multiplier_bps_no_auth(env: &Env, multiplier_bps: u32) {
+    WorkerStorage::set_default_multiplier_bps(env, &multiplier_bps);
+    SetDefaultMultiplierBps { multiplier_bps }.publish(env);
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@layerzerolabs/protocol-stellar-v2",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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"
+    "@layerzerolabs/common-node-utils": "0.2.9",
+    "@layerzerolabs/vm-tooling-stellar": "0.2.9"
   },
   "publishConfig": {
     "access": "restricted",

package/sdk/dist/generated/bml.d.ts

@@ -4,6 +4,80 @@ import type { u32, u64, i128 } from '@stellar/stellar-sdk/contract';
 export * from '@stellar/stellar-sdk';
 export * as contract from '@stellar/stellar-sdk/contract';
 export * as rpc from '@stellar/stellar-sdk/rpc';
+export declare const EndpointError: {
+    1: {
+        message: string;
+    };
+    2: {
+        message: string;
+    };
+    3: {
+        message: string;
+    };
+    4: {
+        message: string;
+    };
+    5: {
+        message: string;
+    };
+    6: {
+        message: string;
+    };
+    7: {
+        message: string;
+    };
+    8: {
+        message: string;
+    };
+    9: {
+        message: string;
+    };
+    10: {
+        message: string;
+    };
+    11: {
+        message: string;
+    };
+    12: {
+        message: string;
+    };
+    13: {
+        message: string;
+    };
+    14: {
+        message: string;
+    };
+    15: {
+        message: string;
+    };
+    16: {
+        message: string;
+    };
+    17: {
+        message: string;
+    };
+    18: {
+        message: string;
+    };
+    19: {
+        message: string;
+    };
+    20: {
+        message: string;
+    };
+    21: {
+        message: string;
+    };
+    22: {
+        message: string;
+    };
+    23: {
+        message: string;
+    };
+    24: {
+        message: string;
+    };
+};
 /**
  * Parameters for sending a cross-chain message.
  */
@@ -190,13 +264,13 @@ export interface OutboundPacket {
  */
 export interface FeeRecipient {
     /**
-   * Address to receive the fee.
-   */
-    address: string;
-    /**
    * Amount of fee to pay.
    */
     amount: i128;
+    /**
+   * The address to send the fee to.
+   */
+    to: string;
 }
 /**
  * Result of send operation containing fees and encoded packet.
@@ -216,39 +290,39 @@ export interface FeesAndPacket {
     zro_fee_recipients: Array<FeeRecipient>;
 }
 export declare const BufferReaderError: {
-    10000: {
+    1000: {
         message: string;
     };
-    10001: {
+    1001: {
         message: string;
     };
 };
 export declare const BufferWriterError: {
-    10100: {
+    1100: {
         message: string;
     };
 };
 export declare const TtlError: {
-    10200: {
+    1200: {
         message: string;
     };
-    10201: {
+    1201: {
         message: string;
     };
-    10202: {
+    1202: {
         message: string;
     };
 };
 export declare const OwnableError: {
-    10300: {
+    1300: {
         message: string;
     };
-    10301: {
+    1301: {
         message: string;
     };
 };
 export declare const BytesExtError: {
-    10400: {
+    1400: {
         message: string;
     };
 };
@@ -269,7 +343,7 @@ export interface TtlConfig {
    */
     threshold: u32;
 }
-export type TtlConfigData = {
+export type TtlConfigStorage = {
     tag: "Frozen";
     values: void;
 } | {
@@ -278,9 +352,6 @@ export type TtlConfigData = {
 } | {
     tag: "Persistent";
     values: void;
-} | {
-    tag: "Temporary";
-    values: void;
 };
 export interface Client {
     /**