@layerzerolabs/protocol-stellar-v2 0.2.19 → 0.2.21

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

@@ -7,11 +7,8 @@ use crate::{
     storage::WorkerStorage,
 };
 use common_macros::contract_trait;
-use soroban_sdk::{assert_with_error, panic_with_error, Address, Bytes, Env, Vec};
-use utils::{
-    auth::{enforce_auth, require_auth, Auth},
-    option_ext::OptionExt,
-};
+use soroban_sdk::{assert_with_error, panic_with_error, Address, Env, Vec};
+use utils::auth::{self, Auth};
 
 /// Worker interface providing common functionality for LayerZero workers.
 ///
@@ -31,8 +28,8 @@ pub trait Worker: Auth {
     ///
     /// # Arguments
     /// * `paused` - `true` to pause, `false` to unpause
-    fn set_paused(env: &Env, paused: bool) {
-        let authorizer = enforce_auth::<Self>(env);
+    fn set_paused(env: &soroban_sdk::Env, paused: bool) {
+        let authorizer = auth::enforce_auth::<Self>(env);
         assert_with_error!(env, Self::paused(env) != paused, WorkerError::PauseStatusUnchanged);
 
         WorkerStorage::set_paused(env, &paused);
@@ -43,6 +40,19 @@ pub trait Worker: Auth {
         }
     }
 
+    /// Sets admin status for an address.
+    ///
+    /// Admins can configure worker settings like fee multipliers, deposit addresses,
+    /// and supported option types.
+    ///
+    /// # Arguments
+    /// * `admin` - The address to set admin status for
+    /// * `active` - `true` to add admin, `false` to remove
+    fn set_admin(env: &soroban_sdk::Env, admin: &soroban_sdk::Address, active: bool) {
+        auth::require_auth::<Self>(env);
+        set_admin_no_auth::<Self>(env, admin, active);
+    }
+
     /// Sets whether a message library is supported by this worker.
     ///
     /// Message libraries (e.g., ULN302) call workers to assign jobs. Only supported
@@ -51,8 +61,8 @@ pub trait Worker: Auth {
     /// # 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_auth::<Self>(env);
+    fn set_supported_message_lib(env: &soroban_sdk::Env, message_lib: &soroban_sdk::Address, supported: bool) {
+        auth::require_auth::<Self>(env);
         set_message_lib_no_auth::<Self>(env, message_lib, supported);
     }
 
@@ -65,8 +75,8 @@ pub trait Worker: Auth {
     /// # 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_auth::<Self>(env);
+    fn set_allowlist(env: &soroban_sdk::Env, oapp: &soroban_sdk::Address, allowed: bool) {
+        auth::require_auth::<Self>(env);
 
         let is_on_list = Self::is_on_allowlist(env, oapp);
         if allowed {
@@ -95,8 +105,8 @@ pub trait Worker: Auth {
     /// # 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_auth::<Self>(env);
+    fn set_denylist(env: &soroban_sdk::Env, oapp: &soroban_sdk::Address, denied: bool) {
+        auth::require_auth::<Self>(env);
         let is_on_list = Self::is_on_denylist(env, oapp);
 
         if denied {
@@ -123,7 +133,7 @@ pub trait Worker: Auth {
     /// # 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) {
+    fn set_default_multiplier_bps(env: &soroban_sdk::Env, admin: &soroban_sdk::Address, multiplier_bps: u32) {
         require_admin_auth::<Self>(env, admin);
         set_default_multiplier_bps_no_auth(env, multiplier_bps);
     }
@@ -135,7 +145,11 @@ pub trait Worker: Auth {
     /// # 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) {
+    fn set_deposit_address(
+        env: &soroban_sdk::Env,
+        admin: &soroban_sdk::Address,
+        deposit_address: &soroban_sdk::Address,
+    ) {
         require_admin_auth::<Self>(env, admin);
         WorkerStorage::set_deposit_address(env, deposit_address);
         SetDepositAddress { deposit_address: deposit_address.clone() }.publish(env);
@@ -146,11 +160,16 @@ pub trait Worker: Auth {
     /// # 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) {
+    /// * `option_types` - Supported option types. Each byte represents an option type.
+    fn set_supported_option_types(
+        env: &soroban_sdk::Env,
+        admin: &soroban_sdk::Address,
+        eid: u32,
+        option_types: &soroban_sdk::Bytes,
+    ) {
         require_admin_auth::<Self>(env, admin);
-        WorkerStorage::set_supported_option_types(env, eid, &option_types);
-        SetSupportedOptionTypes { dst_eid: eid, option_types }.publish(env);
+        WorkerStorage::set_supported_option_types(env, eid, option_types);
+        SetSupportedOptionTypes { dst_eid: eid, option_types: option_types.clone() }.publish(env);
     }
 
     /// Sets the worker fee library contract address.
@@ -160,7 +179,7 @@ pub trait Worker: Auth {
     /// # 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) {
+    fn set_worker_fee_lib(env: &soroban_sdk::Env, admin: &soroban_sdk::Address, worker_fee_lib: &soroban_sdk::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);
@@ -174,7 +193,7 @@ pub trait Worker: Auth {
     /// # 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) {
+    fn set_price_feed(env: &soroban_sdk::Env, admin: &soroban_sdk::Address, price_feed: &soroban_sdk::Address) {
         require_admin_auth::<Self>(env, admin);
         WorkerStorage::set_price_feed(env, price_feed);
         SetPriceFeed { price_feed: price_feed.clone() }.publish(env);
@@ -184,29 +203,29 @@ pub trait Worker: Auth {
     // View Functions
     // ========================================================================
 
+    /// Returns whether the worker is paused.
+    fn paused(env: &soroban_sdk::Env) -> bool {
+        WorkerStorage::paused(env)
+    }
+
     /// Returns whether an address is an admin.
     ///
     /// # Arguments
     /// * `admin` - The address to check
-    fn is_admin(env: &Env, admin: &Address) -> bool {
+    fn is_admin(env: &soroban_sdk::Env, admin: &soroban_sdk::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)
+    fn admins(env: &soroban_sdk::Env) -> soroban_sdk::Vec<soroban_sdk::Address> {
+        WorkerStorage::admins(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 {
+    fn is_supported_message_lib(env: &soroban_sdk::Env, message_lib: &soroban_sdk::Address) -> bool {
         Self::message_libs(env).contains(message_lib)
     }
 
@@ -214,23 +233,28 @@ pub trait Worker: Auth {
     ///
     /// # Returns
     /// Vector of supported message library contract addresses.
-    fn message_libs(env: &Env) -> Vec<Address> {
-        WorkerStorage::message_libs(env).unwrap_or(Vec::new(env))
+    fn message_libs(env: &soroban_sdk::Env) -> soroban_sdk::Vec<soroban_sdk::Address> {
+        WorkerStorage::message_libs(env)
     }
 
     /// Returns whether an OApp is on the allowlist.
     ///
     /// # Arguments
     /// * `oapp` - OApp contract address
-    fn is_on_allowlist(env: &Env, oapp: &Address) -> bool {
+    fn is_on_allowlist(env: &soroban_sdk::Env, oapp: &soroban_sdk::Address) -> bool {
         WorkerStorage::has_allowlist(env, oapp)
     }
 
+    /// Returns the number of addresses on the allowlist.
+    fn allowlist_size(env: &soroban_sdk::Env) -> u32 {
+        WorkerStorage::allowlist_size(env)
+    }
+
     /// Returns whether an OApp is on the denylist.
     ///
     /// # Arguments
     /// * `oapp` - OApp contract address
-    fn is_on_denylist(env: &Env, oapp: &Address) -> bool {
+    fn is_on_denylist(env: &soroban_sdk::Env, oapp: &soroban_sdk::Address) -> bool {
         WorkerStorage::has_denylist(env, oapp)
     }
 
@@ -242,42 +266,37 @@ pub trait Worker: Auth {
     /// 3. Otherwise → denied
     ///
     /// # Arguments
-    /// * `sender` - OApp contract address to check
-    fn has_acl(env: &Env, sender: &Address) -> bool {
-        !Self::is_on_denylist(env, sender) && (Self::allowlist_size(env) == 0 || Self::is_on_allowlist(env, sender))
-    }
-
-    /// Returns the number of addresses on the allowlist.
-    fn allowlist_size(env: &Env) -> u32 {
-        WorkerStorage::allowlist_size(env)
+    /// * `oapp` - OApp contract address to check
+    fn has_acl(env: &soroban_sdk::Env, oapp: &soroban_sdk::Address) -> bool {
+        !Self::is_on_denylist(env, oapp) && (Self::allowlist_size(env) == 0 || Self::is_on_allowlist(env, oapp))
     }
 
     /// Returns the default fee multiplier in basis points.
-    fn default_multiplier_bps(env: &Env) -> u32 {
-        WorkerStorage::default_multiplier_bps(env).unwrap_or(0)
+    fn default_multiplier_bps(env: &soroban_sdk::Env) -> u32 {
+        WorkerStorage::default_multiplier_bps(env)
     }
 
     /// 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)
+    fn deposit_address(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+        WorkerStorage::deposit_address(env)
     }
 
     /// 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> {
+    fn get_supported_option_types(env: &soroban_sdk::Env, eid: u32) -> Option<soroban_sdk::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)
+    fn worker_fee_lib(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+        WorkerStorage::worker_fee_lib(env)
+    }
+
+    /// Returns the price feed contract address.
+    fn price_feed(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
+        WorkerStorage::price_feed(env)
     }
 }
 
@@ -305,16 +324,8 @@ pub fn init_worker<T: Worker>(
     worker_fee_lib: &Address,
     deposit_address: &Address,
 ) {
-    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);
-    }
+    admins.iter().for_each(|admin| set_admin_no_auth::<T>(env, &admin, true));
+    message_libs.iter().for_each(|lib| 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);
@@ -373,16 +384,6 @@ pub fn assert_supported_message_lib<T: Worker>(env: &Env, message_lib: &Address)
 // Admin Setter Functions with authentication
 // ============================================================================================
 
-/// Sets admin status for an address by authorizer (owner/multisig).
-///
-/// # 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_auth::<T>(env);
-    set_admin_no_auth::<T>(env, admin, active);
-}
-
 /// Sets admin status for an address by admin.
 ///
 /// # Arguments
@@ -414,7 +415,6 @@ fn set_admin_no_auth<T: Worker>(env: &Env, admin: &Address, active: bool) {
         admins.push_back(admin.clone());
     } else {
         // Remove admin - ensure present
-        assert_with_error!(env, admins.len() > 1, WorkerError::AttemptingToRemoveOnlyAdmin);
         let Some(index) = admins.first_index_of(admin) else {
             panic_with_error!(env, WorkerError::AdminNotFound);
         };

package/docs/error-spec.md

@@ -0,0 +1,55 @@
+# Stellar LayerZero Protocol - Error Code Specification
+
+This document defines the error code allocation strategy for the Stellar LayerZero contracts.
+
+## Purpose
+
+Each library has a unique error code range to:
+
+- **Prevent collisions**: Avoid error code conflicts between different libraries
+- **Enable traceability**: Quickly identify which library an error originated from based on its code
+- **Simplify debugging**: Error codes are globally unique, making it easier to track and diagnose issues
+
+## Allocation Rules
+
+- **Contract-specific errors**: Each contract uses auto-incrementing error codes starting from 1. These are local to the contract and do not need global uniqueness since the contract address provides context.
+- **Library errors**: Libraries that are shared across multiple contracts use reserved ranges (1000+) to ensure global uniqueness.
+- **Library allocation**: Each library is allocated a 100-unit block (e.g., 1000-1099, 1100-1199). Total errors in one library should not exceed 100.
+- **Sub-range allocation**: Each error type within a library is allocated a 10-unit block. If an error type exceeds 10 errors, it extends into the next block but the following error type should start at the next 10-unit boundary.
+- **Auto-increment**: Within each error enum, values auto-increment from the starting value.
+
+## Error Code Ranges
+
+### Contract-Specific Errors (1-999)
+
+Contract-specific errors auto-increment from 1 and are scoped to each contract.
+
+| Contract          | Location                                        |
+| ----------------- | ----------------------------------------------- |
+| EndpointV2        | `endpoint-v2/src/errors.rs`                     |
+| ULN302            | `message-libs/uln-302/src/errors.rs`            |
+| Treasury          | `message-libs/treasury/src/errors.rs`           |
+| SimpleMessageLib  | `message-libs/simple-message-lib/src/errors.rs` |
+| DVN               | `workers/dvn/src/errors.rs`                     |
+| Executor          | `workers/executor/src/errors.rs`                |
+| DVN Fee Lib       | `workers/dvn-fee-lib/src/errors.rs`             |
+| Executor Fee Lib  | `workers/executor-fee-lib/src/errors.rs`        |
+| Price Feed        | `workers/price-feed/src/errors.rs`              |
+| LayerZero Views   | `layerzero-views/src/errors.rs`                 |
+| Counter (example) | `oapps/counter/src/errors.rs`                   |
+
+### Library Errors (1000+)
+
+Libraries shared across contracts use reserved ranges for global uniqueness.
+
+| Range     | Category     | Library            | Location                                        |
+| --------- | ------------ | ------------------ | ----------------------------------------------- |
+| 1000-1099 | Protocol Lib | utils              | `utils/src/errors.rs`                           |
+| 1100-1199 | Protocol Lib | message-lib-common | `message-libs/message-lib-common/src/errors.rs` |
+| 1200-1299 | Protocol Lib | worker             | `workers/worker/src/errors.rs`                  |
+| 1300-1999 | Protocol Lib | (reserved)         | Future protocol libs                            |
+| 2000-2099 | OApp Lib     | oapp               | `oapps/oapp/src/errors.rs`                      |
+| 2100-2999 | OApp Lib     | (reserved)         | Future OApp libs                                |
+| 3000-3099 | OFT Lib      | oft-core           | `oapps/oft-core/src/errors.rs`                  |
+| 3100-3199 | OFT Lib      | oft (extensions)   | `oapps/oft/src/extensions/`                     |
+| 3200-3999 | OFT Lib      | (reserved)         | Future OFT libs                                 |