@layerzerolabs/protocol-stellar-v2 0.2.20 → 0.2.21

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

@@ -7,7 +7,7 @@ use crate::{
     storage::WorkerStorage,
 };
 use common_macros::contract_trait;
-use soroban_sdk::{assert_with_error, panic_with_error, Address, Bytes, Env, Vec};
+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.
@@ -28,7 +28,7 @@ pub trait Worker: Auth {
     ///
     /// # Arguments
     /// * `paused` - `true` to pause, `false` to unpause
-    fn set_paused(env: &Env, paused: bool) {
+    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);
 
@@ -48,7 +48,7 @@ pub trait Worker: Auth {
     /// # Arguments
     /// * `admin` - The address to set admin status for
     /// * `active` - `true` to add admin, `false` to remove
-    fn set_admin(env: &Env, admin: &Address, active: bool) {
+    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);
     }
@@ -61,7 +61,7 @@ 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) {
+    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);
     }
@@ -75,7 +75,7 @@ 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) {
+    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);
@@ -105,7 +105,7 @@ 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) {
+    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);
 
@@ -133,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);
     }
@@ -145,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);
@@ -157,7 +161,12 @@ pub trait Worker: Auth {
     /// * `admin` - Admin address (must provide authorization)
     /// * `eid` - Destination endpoint ID (chain identifier)
     /// * `option_types` - Supported option types. Each byte represents an option type.
-    fn set_supported_option_types(env: &Env, admin: &Address, eid: u32, option_types: &Bytes) {
+    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: option_types.clone() }.publish(env);
@@ -170,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);
@@ -184,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);
@@ -195,7 +204,7 @@ pub trait Worker: Auth {
     // ========================================================================
 
     /// Returns whether the worker is paused.
-    fn paused(env: &Env) -> bool {
+    fn paused(env: &soroban_sdk::Env) -> bool {
         WorkerStorage::paused(env)
     }
 
@@ -203,12 +212,12 @@ pub trait Worker: Auth {
     ///
     /// # 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> {
+    fn admins(env: &soroban_sdk::Env) -> soroban_sdk::Vec<soroban_sdk::Address> {
         WorkerStorage::admins(env)
     }
 
@@ -216,7 +225,7 @@ pub trait Worker: Auth {
     ///
     /// # 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)
     }
 
@@ -224,7 +233,7 @@ pub trait Worker: Auth {
     ///
     /// # Returns
     /// Vector of supported message library contract addresses.
-    fn message_libs(env: &Env) -> Vec<Address> {
+    fn message_libs(env: &soroban_sdk::Env) -> soroban_sdk::Vec<soroban_sdk::Address> {
         WorkerStorage::message_libs(env)
     }
 
@@ -232,12 +241,12 @@ pub trait Worker: Auth {
     ///
     /// # 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: &Env) -> u32 {
+    fn allowlist_size(env: &soroban_sdk::Env) -> u32 {
         WorkerStorage::allowlist_size(env)
     }
 
@@ -245,7 +254,7 @@ pub trait Worker: Auth {
     ///
     /// # 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)
     }
 
@@ -258,17 +267,17 @@ pub trait Worker: Auth {
     ///
     /// # Arguments
     /// * `oapp` - OApp contract address to check
-    fn has_acl(env: &Env, oapp: &Address) -> bool {
+    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 {
+    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) -> Option<Address> {
+    fn deposit_address(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
         WorkerStorage::deposit_address(env)
     }
 
@@ -276,17 +285,17 @@ pub trait Worker: Auth {
     ///
     /// # 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) -> Option<Address> {
+    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: &Env) -> Option<Address> {
+    fn price_feed(env: &soroban_sdk::Env) -> Option<soroban_sdk::Address> {
         WorkerStorage::price_feed(env)
     }
 }

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                                 |