@layerzerolabs/protocol-stellar-v2 0.2.121 → 0.2.123

package/contracts/utils/src/ttl_configurable.rs

@@ -1,169 +0,0 @@
-use crate::{self as utils, auth::Auth, errors::TtlConfigurableError};
-use common_macros::{contract_trait, only_auth, storage};
-use soroban_sdk::{assert_with_error, contractevent, contracttype, Env, IntoVal, Val};
-
-/// Ledgers per day (~5 second close time).
-pub const LEDGERS_PER_DAY: u32 = (24 * 3600) / 5;
-
-/// Maximum TTL (1 year) allowed by the protocol.
-/// Note: Stellar's current maximum TTL is 6 months, but this constraint may change
-/// in the future. In order to preserve LayerZero's censorship-resistance and protect
-/// users from abusive parameter changes, a constant upper bound is enforced on the
-/// extend_to value.
-pub const MAX_TTL: u32 = 365 * LEDGERS_PER_DAY;
-
-/// TTL configuration: threshold (when to extend) and extend_to (target TTL).
-#[contracttype]
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub struct TtlConfig {
-    /// TTL threshold that triggers extension (in ledgers).
-    pub threshold: u32,
-    /// Target TTL after extension (in ledgers).
-    pub extend_to: u32,
-}
-
-impl TtlConfig {
-    /// Creates a new TTL config.
-    pub const fn new(threshold: u32, extend_to: u32) -> Self {
-        Self { threshold, extend_to }
-    }
-
-    /// Validates that threshold <= extend_to <= max_ttl.
-    pub fn is_valid(&self, max_ttl: u32) -> bool {
-        self.threshold <= self.extend_to && self.extend_to <= max_ttl
-    }
-}
-
-// =============================================================================
-// Events
-// =============================================================================
-
-/// Event emitted when TTL configs are set.
-#[contractevent]
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub struct TtlConfigsSet {
-    pub instance: Option<TtlConfig>,
-    pub persistent: Option<TtlConfig>,
-}
-
-/// Event emitted when TTL configs are frozen.
-#[contractevent]
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub struct TtlConfigsFrozen {}
-
-// =============================================================================
-// Storage for default implementation
-// =============================================================================
-
-/// Storage keys for TTL configuration.
-///
-/// Note: Auto-TTL extension is disabled for these instance storage entries to avoid infinite
-/// recursion. Extending TTL config storage would require reading the TTL config, which would
-/// trigger another extension, creating a deep loop.
-#[storage]
-pub enum TtlConfigStorage {
-    #[instance(bool)]
-    #[default(false)]
-    Frozen,
-
-    #[instance(TtlConfig)]
-    Instance,
-
-    #[instance(TtlConfig)]
-    Persistent,
-}
-
-/// Initializes TTL configs with the default values (threshold: 29 days, extend_to: 30 days).
-///
-/// This sets both instance and persistent TTL configs to `DEFAULT_TTL_CONFIG`.
-pub fn init_default_ttl_configs(env: &Env) {
-    let default_ttl_config = TtlConfig::new(29 * LEDGERS_PER_DAY, 30 * LEDGERS_PER_DAY);
-    TtlConfigStorage::set_instance(env, &default_ttl_config);
-    TtlConfigStorage::set_persistent(env, &default_ttl_config);
-}
-
-/// Extends instance storage TTL using the configured settings (if any).
-pub fn extend_instance_ttl(env: &Env) {
-    if let Some(TtlConfig { threshold, extend_to }) = TtlConfigStorage::instance(env) {
-        env.storage().instance().extend_ttl(threshold, extend_to);
-    }
-}
-
-/// Extends persistent storage TTL for a key using the configured settings (if any).
-pub fn extend_persistent_ttl<K: IntoVal<Env, Val>>(env: &Env, key: &K) {
-    if let Some(TtlConfig { threshold, extend_to }) = TtlConfigStorage::persistent(env) {
-        env.storage().persistent().extend_ttl(key, threshold, extend_to);
-    }
-}
-
-/// Trait for contracts that support configurable TTL (Time-To-Live) management.
-///
-/// Allows the contract authorizer to configure how long instance and persistent storage entries
-/// remain alive on Stellar.
-///
-/// The authorizer can also permanently freeze the configuration to prevent future changes,
-/// providing immutability guarantees to users.
-///
-/// Requires the `Auth` trait to be implemented, which can be provided by either:
-/// - `#[ownable]` macro for single-owner contracts
-/// - `#[multisig]` macro for multisig-controlled contracts
-#[contract_trait]
-pub trait TtlConfigurable: Auth {
-    /// Sets TTL configs for instance and persistent storage.
-    ///
-    /// - `None` values remove the corresponding config (disables auto-extension for that type)
-    /// - Validates that `threshold <= extend_to <= MAX_TTL`
-    ///
-    /// # Arguments
-    /// - `instance` - TTL config for instance storage
-    /// - `persistent` - TTL config for persistent storage
-    ///
-    /// # Panics
-    /// - `TtlConfigFrozen` if configs are frozen
-    /// - `InvalidTtlConfig` if validation fails
-    #[only_auth]
-    fn set_ttl_configs(
-        env: &soroban_sdk::Env,
-        instance: &Option<utils::ttl_configurable::TtlConfig>,
-        persistent: &Option<utils::ttl_configurable::TtlConfig>,
-    ) {
-        assert_with_error!(env, !Self::is_ttl_configs_frozen(env), TtlConfigurableError::TtlConfigFrozen);
-
-        let max_ttl = MAX_TTL.min(env.storage().max_ttl());
-        let all_valid = [instance, persistent].iter().all(|c| c.is_none_or(|cfg| cfg.is_valid(max_ttl)));
-        assert_with_error!(env, all_valid, TtlConfigurableError::InvalidTtlConfig);
-
-        TtlConfigStorage::set_or_remove_instance(env, instance);
-        TtlConfigStorage::set_or_remove_persistent(env, persistent);
-
-        TtlConfigsSet { instance: *instance, persistent: *persistent }.publish(env);
-    }
-
-    /// Returns the current TTL configs as (instance_config, persistent_config).
-    fn ttl_configs(
-        env: &soroban_sdk::Env,
-    ) -> (Option<utils::ttl_configurable::TtlConfig>, Option<utils::ttl_configurable::TtlConfig>) {
-        (TtlConfigStorage::instance(env), TtlConfigStorage::persistent(env))
-    }
-
-    /// Permanently freezes TTL configs, preventing any future modifications.
-    ///
-    /// This is irreversible and provides immutability guarantees to users.
-    /// Emits `TtlConfigsFrozen` event.
-    ///
-    /// # Panics
-    /// - `TtlConfigAlreadyFrozen` if already frozen
-    #[only_auth]
-    fn freeze_ttl_configs(env: &soroban_sdk::Env) {
-        assert_with_error!(env, !Self::is_ttl_configs_frozen(env), TtlConfigurableError::TtlConfigAlreadyFrozen);
-
-        TtlConfigStorage::set_frozen(env, &true);
-
-        TtlConfigsFrozen {}.publish(env);
-    }
-
-    /// Returns whether TTL configs are frozen.
-    fn is_ttl_configs_frozen(env: &soroban_sdk::Env) -> bool {
-        TtlConfigStorage::frozen(env)
-    }
-}

package/contracts/utils/src/ttl_extendable.rs

@@ -1,25 +0,0 @@
-//! TtlExtendable trait for manual instance TTL extension.
-//!
-//! This module provides the `TtlExtendable` trait which allows external callers
-//! to extend a contract's instance storage TTL, keeping the contract alive.
-
-/// Trait for contracts that support manual instance TTL extension.
-///
-/// This trait provides a public contract function to extend the instance storage TTL,
-/// allowing external callers to keep the contract alive by paying for TTL extension.
-///
-/// Uses `#[soroban_sdk::contracttrait]` directly (not `#[common_macros::contract_trait]`)
-/// because auto TTL extension would be redundant for a trait whose purpose is manual
-/// TTL control.
-#[soroban_sdk::contracttrait]
-pub trait TtlExtendable {
-    /// Extends the instance TTL.
-    ///
-    /// # Arguments
-    ///
-    /// * `threshold` - The threshold to extend the TTL (if current TTL is below this, extend).
-    /// * `extend_to` - The TTL to extend to.
-    fn extend_instance_ttl(env: &soroban_sdk::Env, threshold: u32, extend_to: u32) {
-        env.storage().instance().extend_ttl(threshold, extend_to);
-    }
-}

package/contracts/utils/src/upgradeable.rs

@@ -1,103 +0,0 @@
-use crate::{self as utils, auth::Auth, errors::UpgradeableError, option_ext::OptionExt, rbac::RoleBasedAccessControl};
-use common_macros::{contract_trait, only_auth, only_role, storage};
-use soroban_sdk::{assert_with_error, xdr::FromXdr, Bytes, BytesN, Env};
-
-/// Role for upgrading the contract and running migrations.
-pub const UPGRADER_ROLE: &str = "UPGRADER_ROLE";
-
-/// Trait for contracts with upgrade and migration support (Auth-based).
-///
-/// Implements a two-phase upgrade pattern:
-/// 1. `upgrade` - Updates WASM bytecode and sets migration flag
-/// 2. `migrate` - Runs state migration and clears the flag
-///
-/// Requires implementing [`UpgradeableInternal`] and [`Auth`].
-#[contract_trait]
-pub trait Upgradeable: UpgradeableInternal + Auth {
-    /// Upgrades the contract to new WASM bytecode.
-    #[only_auth]
-    fn upgrade(env: &soroban_sdk::Env, new_wasm_hash: &soroban_sdk::BytesN<32>) {
-        upgrade(env, new_wasm_hash);
-    }
-
-    /// Runs migration logic after an upgrade.
-    #[only_auth]
-    fn migrate(env: &soroban_sdk::Env, migration_data: &soroban_sdk::Bytes) {
-        migrate::<Self>(env, migration_data);
-    }
-}
-
-/// Trait for contracts with upgrade and migration support (RBAC-based).
-///
-/// Same two-phase upgrade pattern as [`Upgradeable`], but access control uses
-/// `UPGRADER_ROLE` instead of Auth. Requires implementing [`UpgradeableInternal`]
-/// and [`RoleBasedAccessControl`].
-#[contract_trait]
-pub trait UpgradeableRbac: UpgradeableInternal + RoleBasedAccessControl {
-    /// Upgrades the contract to new WASM bytecode.
-    #[only_role(operator, UPGRADER_ROLE)]
-    fn upgrade(env: &soroban_sdk::Env, new_wasm_hash: &soroban_sdk::BytesN<32>, operator: &soroban_sdk::Address) {
-        upgrade(env, new_wasm_hash);
-    }
-
-    /// Runs migration logic after an upgrade.
-    #[only_role(operator, UPGRADER_ROLE)]
-    fn migrate(env: &soroban_sdk::Env, migration_data: &soroban_sdk::Bytes, operator: &soroban_sdk::Address) {
-        migrate::<Self>(env, migration_data);
-    }
-}
-
-/// Trait for defining contract-specific migration logic.
-/// Must be implemented by contracts using [`Upgradeable`] or [`UpgradeableRbac`].
-pub trait UpgradeableInternal {
-    /// The XDR-decodable type for migration data. Use `()` if not needed.
-    type MigrationData: FromXdr;
-
-    /// Migration logic called by `migrate`. Implement state transformations here.
-    fn __migrate(env: &Env, migration_data: &Self::MigrationData);
-}
-
-// ============================================
-// Helper Functions
-// ============================================
-
-/// Core upgrade logic: set migrating flag and update WASM.
-///
-/// # Arguments
-/// - `new_wasm_hash` - The hash of the new WASM bytecode
-fn upgrade(env: &Env, new_wasm_hash: &BytesN<32>) {
-    UpgradeableStorage::set_migrating(env, &true);
-    env.deployer().update_current_contract_wasm(new_wasm_hash.clone());
-}
-
-/// Core migration logic: parse migration data, call `__migrate`, clear flag.
-///
-/// # Arguments
-/// - `migration_data` - The migration data
-///
-/// # Panics
-/// - `MigrationNotAllowed` if no migration is in progress
-/// - `InvalidMigrationData` if the migration data cannot be parsed into the contract's `MigrationData` type
-fn migrate<T: UpgradeableInternal>(env: &Env, migration_data: &Bytes) {
-    assert_with_error!(env, UpgradeableStorage::migrating(env), UpgradeableError::MigrationNotAllowed);
-
-    let parsed_data = T::MigrationData::from_xdr(env, migration_data)
-        .ok()
-        .unwrap_or_panic(env, UpgradeableError::InvalidMigrationData);
-    T::__migrate(env, &parsed_data);
-
-    UpgradeableStorage::set_migrating(env, &false);
-}
-
-// ============================================
-// Storage
-// ============================================
-
-/// Storage for upgrade state.
-#[storage]
-pub enum UpgradeableStorage {
-    /// Whether a migration is pending.
-    #[instance(bool)]
-    #[default(false)]
-    Migrating,
-}

package/contracts/workers/Cargo.toml

@@ -1,13 +0,0 @@
-[package]
-name = "workers"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-publish = false
-
-[lib]
-path = "lib.rs"
-
-[dependencies]
-
-

package/contracts/workers/lib.rs

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

package/docs/error-spec.md

@@ -1,55 +0,0 @@
-# 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                                 |