@layerzerolabs/oapp-stellar-contracts 0.2.122

package/Cargo.toml

@@ -0,0 +1,44 @@
+[package]
+name = "oapp"
+version = "0.0.1"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["rlib"]
+doctest = false
+
+[dependencies]
+soroban-sdk = { version = "25.1.1", features = ["hazmat-address", "hazmat-crypto"] }
+utils = { path = "dependencies/common-utils-stellar-contracts" }
+common-macros = { path = "dependencies/common-utils-macros-stellar-contracts" }
+endpoint-v2 = { path = "dependencies/protocol-stellar-v2/endpoint-v2", default-features = false, features = [
+    "library",
+] }
+oapp-macros = { path = "dependencies/oapp-macros-stellar-contracts" }
+
+[dev-dependencies]
+soroban-sdk = { version = "25.1.1", features = ["hazmat-address", "hazmat-crypto", "testutils"] }
+utils = { path = "dependencies/common-utils-stellar-contracts", features = ["testutils"] }
+endpoint-v2 = { path = "dependencies/protocol-stellar-v2/endpoint-v2", default-features = false, features = [
+    "testutils",
+] }
+common-macros = { path = "dependencies/common-utils-macros-stellar-contracts" }
+oapp-macros = { path = "dependencies/oapp-macros-stellar-contracts" }
+trybuild = "1.0.114"
+insta = "1.44.3"
+prettyplease = "0.2.37"
+
+[profile.release]
+opt-level = "z"
+overflow-checks = true
+debug = 0
+strip = "symbols"
+debug-assertions = false
+panic = "abort"
+codegen-units = 1
+lto = true
+
+[profile.release-with-logs]
+inherits = "release"
+debug-assertions = true

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026 - LayerZero Labs Ltd.
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# `@layerzerolabs/oapp-stellar-contracts`
+
+Stellar/Soroban OApp framework (traits + `oapp-macros`).
+
+Developer guide: [docs/oapp-guide.md](../docs/oapp-guide.md).

package/clippy.toml

@@ -0,0 +1,6 @@
+# Clippy configuration for Stellar contracts
+
+# Set the too_many_arguments threshold to 11.
+# This aligns with Stellar: contract functions are limited to 10 parameters, plus 1 for 'env'.
+# (Default is 7; raised here to prevent unnecessary clippy warnings on valid contract interfaces.)
+too-many-arguments-threshold = 11

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@layerzerolabs/oapp-stellar-contracts",
+  "version": "0.2.122",
+  "private": false,
+  "license": "MIT",
+  "files": [
+    "src",
+    "Cargo.toml",
+    "rust-toolchain.toml",
+    "rustfmt.toml",
+    "clippy.toml"
+  ],
+  "dependencies": {
+    "@layerzerolabs/common-utils-macros-stellar-contracts": "0.2.122",
+    "@layerzerolabs/protocol-stellar-v2": "0.2.122",
+    "@layerzerolabs/common-utils-stellar-contracts": "0.2.122",
+    "@layerzerolabs/oapp-macros-stellar-contracts": "0.2.122"
+  },
+  "devDependencies": {
+    "@layerzerolabs/build-utils-rust": "0.2.122",
+    "@layerzerolabs/vm-tooling-stellar": "0.2.122"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "externalRepoConfig": {
+    "targets": [
+      "audit-external",
+      "console-pen-test",
+      "monorepo-external",
+      "onesig-client"
+    ]
+  },
+  "implicitDependencies": {
+    "@layerzerolabs/protocol-stellar-v2": "workspace:*",
+    "@layerzerolabs/common-utils-stellar-contracts": "workspace:*",
+    "@layerzerolabs/common-utils-macros-stellar-contracts": "workspace:*",
+    "@layerzerolabs/oapp-macros-stellar-contracts": "workspace:*"
+  },
+  "scripts": {
+    "build": "pnpm resolve-dependencies && pnpm exec lz-tool --script \"cargo build --release\" stellar",
+    "clean": "rm -rf ./dependencies ./target ./node_modules",
+    "format": "pnpm exec lz-tool --script \"cargo fmt\" stellar",
+    "lint": "pnpm resolve-dependencies && pnpm exec lz-tool --script \"cargo clippy -- -D warnings\" stellar",
+    "lint:fix": "pnpm resolve-dependencies && pnpm exec lz-tool --script \"cargo clippy --fix --allow-dirty --allow-staged && cargo fmt\" stellar",
+    "resolve-dependencies": "pnpm exec build-utils-rust resolve",
+    "test": "pnpm resolve-dependencies && pnpm exec lz-tool --script \"cargo nextest run -E 'not test(/^ui_/)'\" stellar",
+    "test:snapshot:check": "pnpm exec turbo-snapshot check",
+    "test:snapshot:update": "pnpm exec turbo-snapshot update",
+    "test:ui": "pnpm resolve-dependencies && pnpm exec lz-tool --script \"cargo nextest run -E 'test(/^ui_/)'\" 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,15 @@
+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/src/errors.rs

@@ -0,0 +1,13 @@
+use common_macros::contract_error;
+
+// OApp library error codes: 2000-2099
+// See docs/error-spec.md for allocation rules
+
+/// OAppError: 2000-2099
+#[contract_error]
+pub enum OAppError {
+    InvalidOptions = 2000,
+    NoPeer,
+    OnlyPeer,
+    ZroTokenUnavailable,
+}

package/src/interfaces/mod.rs

@@ -0,0 +1,3 @@
+mod oapp_msg_inspector;
+
+pub use oapp_msg_inspector::*;

package/src/interfaces/oapp_msg_inspector.rs

@@ -0,0 +1,70 @@
+//! OApp Message Inspector interface.
+//!
+//! This module defines the `IOAppMsgInspector` trait that external inspector contracts
+//! must implement to validate outgoing LayerZero messages and options.
+//!
+//! Implementations can signal failure in two ways:
+//! - Return `false` to indicate the inspection failed.
+//! - Panic directly to abort the transaction immediately.
+//!
+//! ## Usage
+//!
+//! ### Returning a boolean
+//!
+//! ```ignore
+//! use oapp::interfaces::IOAppMsgInspector;
+//!
+//! pub struct MyInspector;
+//!
+//! #[contractimpl]
+//! impl IOAppMsgInspector for MyInspector {
+//!     fn inspect(env: &Env, oapp: &Address, message: &Bytes, options: &Bytes) -> bool {
+//!         is_valid(message, options)
+//!     }
+//! }
+//! ```
+//!
+//! ### Panicking on failure
+//!
+//! ```ignore
+//! use oapp::interfaces::IOAppMsgInspector;
+//!
+//! pub struct MyInspector;
+//!
+//! #[contractimpl]
+//! impl IOAppMsgInspector for MyInspector {
+//!     fn inspect(env: &Env, oapp: &Address, message: &Bytes, options: &Bytes) -> bool {
+//!         if !is_valid(message, options) {
+//!             panic_with_error!(env, MyError::InspectionFailed);
+//!         }
+//!         true
+//!     }
+//! }
+//! ```
+
+use soroban_sdk::{contractclient, Address, Bytes, Env};
+
+/// Interface for OApp message inspectors.
+///
+/// Contracts implementing this trait can be set as message inspectors on OFT contracts
+/// to validate outgoing messages and options before they are sent cross-chain.
+///
+/// Implementations may either return `false` to indicate failure, or panic directly
+/// to abort the transaction.
+#[contractclient(name = "OAppMsgInspectorClient")]
+pub trait IOAppMsgInspector {
+    /// Allows the inspector to examine LayerZero message contents and determine their validity.
+    ///
+    /// # Arguments
+    /// * `oapp` - The address of the OApp contract sending the message
+    /// * `message` - The message payload to be inspected.
+    /// * `options` - Additional LayerZero options for inspection.
+    ///
+    /// # Returns
+    /// * `bool` - `true` if the inspection passed, `false` if the message or options are invalid.
+    ///
+    /// # Panics
+    /// Implementations may choose to panic instead of returning `false` to abort the
+    /// transaction immediately with a specific error.
+    fn inspect(env: &Env, oapp: &Address, message: &Bytes, options: &Bytes) -> bool;
+}

package/src/lib.rs

@@ -0,0 +1,15 @@
+#![no_std]
+
+pub mod oapp_core;
+pub mod oapp_options_type3;
+pub mod oapp_receiver;
+pub mod oapp_sender;
+
+mod errors;
+mod interfaces;
+
+pub use errors::*;
+pub use interfaces::*;
+
+#[cfg(test)]
+mod tests;

package/src/oapp_core.rs

@@ -0,0 +1,143 @@
+use crate::{errors::OAppError, oapp_receiver::RECEIVER_VERSION, oapp_sender::SENDER_VERSION};
+use common_macros::{contract_trait, only_role, storage};
+use endpoint_v2::LayerZeroEndpointV2Client;
+use soroban_sdk::{contractevent, Address, BytesN, Env};
+use utils::{
+    option_ext::OptionExt,
+    ownable::{Ownable, OwnableInitializer},
+    rbac::{RoleBasedAccessControl, AUTHORIZER},
+};
+
+// =====================================================
+// OAppCore Storage and Events
+// =====================================================
+
+#[storage]
+pub enum OAppCoreStorage {
+    // Endpoint address - set once during initialization
+    #[instance(Address)]
+    Endpoint,
+
+    // Mapping from endpoint ID to remote peer address
+    #[persistent(BytesN<32>)]
+    Peer { eid: u32 },
+}
+
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PeerSet {
+    pub eid: u32,
+    pub peer: Option<BytesN<32>>,
+}
+
+// =====================================================
+// OAppCore Interface and Default Implementation
+// =====================================================
+
+#[contract_trait]
+pub trait OAppCore: Ownable + RoleBasedAccessControl {
+    /// Retrieves the OApp version information.
+    ///
+    /// # Returns
+    /// A tuple containing:
+    /// - `sender_version`: The version of the OAppSender
+    /// - `receiver_version`: The version of the OAppReceiver
+    fn oapp_version(_env: &soroban_sdk::Env) -> (u64, u64) {
+        (SENDER_VERSION, RECEIVER_VERSION)
+    }
+
+    /// Retrieves the LayerZero endpoint address associated with the OApp.
+    ///
+    /// # Returns
+    /// The LayerZero endpoint address
+    fn endpoint(env: &soroban_sdk::Env) -> soroban_sdk::Address {
+        OAppCoreStorage::endpoint(env).unwrap()
+    }
+
+    /// Retrieves the peer (OApp) associated with a corresponding endpoint.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    ///
+    /// # Returns
+    /// The peer address (OApp instance) associated with the corresponding endpoint
+    fn peer(env: &soroban_sdk::Env, eid: u32) -> Option<soroban_sdk::BytesN<32>> {
+        OAppCoreStorage::peer(env, eid)
+    }
+
+    /// Sets or removes the peer address (OApp instance) for a corresponding endpoint.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    /// * `peer` - The address of the peer to be associated with the corresponding endpoint, or None to remove the peer
+    /// * `operator` - The authorizer address
+    #[only_role(operator, AUTHORIZER)]
+    fn set_peer(
+        env: &soroban_sdk::Env,
+        eid: u32,
+        peer: &Option<soroban_sdk::BytesN<32>>,
+        operator: &soroban_sdk::Address,
+    ) {
+        OAppCoreStorage::set_or_remove_peer(env, eid, peer);
+        PeerSet { eid, peer: peer.clone() }.publish(env);
+    }
+
+    /// Sets the delegate address for the OApp Core.
+    ///
+    /// # Arguments
+    /// * `delegate` - The address of the delegate to be set, or None to remove the delegate
+    /// * `operator` - The authorizer address
+    #[only_role(operator, AUTHORIZER)]
+    fn set_delegate(env: &soroban_sdk::Env, delegate: &Option<soroban_sdk::Address>, operator: &soroban_sdk::Address) {
+        endpoint_client::<Self>(env).set_delegate(&env.current_contract_address(), delegate);
+    }
+}
+
+// =====================================================
+// Helper Functions
+// =====================================================
+
+/// Initializes the OApp with the specified configuration.
+///
+/// This function sets up the OApp by initializing ownership, storing the LayerZero endpoint,
+/// and setting a delegate address for the endpoint.
+///
+/// # Arguments
+/// * `env` - The Soroban environment
+/// * `owner` - The address that will own this OApp
+/// * `endpoint` - The LayerZero endpoint address to associate with this OApp
+/// * `delegate` - The delegate address to set on the endpoint for this OApp
+pub fn init_ownable_oapp<T: OAppCore + OwnableInitializer>(
+    env: &Env,
+    owner: &Address,
+    endpoint: &Address,
+    delegate: &Address,
+) {
+    T::init_owner(env, owner);
+    OAppCoreStorage::set_endpoint(env, endpoint);
+    LayerZeroEndpointV2Client::new(env, endpoint)
+        .set_delegate(&env.current_contract_address(), &Some(delegate.clone()));
+}
+
+/// Retrieves the peer address associated with a specific endpoint ID; panics if NOT set.
+///
+/// This is a safe getter that ensures a peer has been configured for the given endpoint.
+/// If no peer is set (i.e., the peer is `None`), it will panic with `OAppError::NoPeer`.
+///
+/// # Arguments
+/// * `env` - The Soroban environment
+/// * `eid` - The endpoint ID
+///
+/// # Returns
+/// The peer address (`BytesN<32>`) associated with the specified endpoint
+///
+/// # Panics
+/// Panics with `OAppError::NoPeer` if no peer is set for the given endpoint ID
+pub fn get_peer_or_panic<T: OAppCore>(env: &Env, eid: u32) -> BytesN<32> {
+    T::peer(env, eid).unwrap_or_panic(env, OAppError::NoPeer)
+}
+
+/// Returns a client for the LayerZero endpoint.
+pub fn endpoint_client<'a, T: OAppCore>(env: &'a Env) -> LayerZeroEndpointV2Client<'a> {
+    LayerZeroEndpointV2Client::new(env, &T::endpoint(env))
+}

package/src/oapp_options_type3.rs

@@ -0,0 +1,133 @@
+use crate::{self as oapp, errors::OAppError};
+use common_macros::{contract_trait, only_role, storage};
+use soroban_sdk::{assert_with_error, contractevent, contracttype, panic_with_error, Bytes, Env, Vec};
+use utils::{buffer_reader::BufferReader, rbac::{RoleBasedAccessControl, AUTHORIZER}};
+
+pub const OPTION_TYPE3: u16 = 3;
+
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct EnforcedOptionParam {
+    pub eid: u32,
+    pub msg_type: u32,
+    pub options: Option<Bytes>,
+}
+
+#[storage]
+pub enum OAppOptionsType3Storage {
+    #[persistent(Bytes)]
+    EnforcedOptions { eid: u32, msg_type: u32 },
+}
+
+#[contractevent]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct EnforcedOptionSet {
+    pub enforced_options: Vec<EnforcedOptionParam>,
+}
+
+// =========================================================================
+// OAppOptionsType3 Trait and Default Implementation
+// =========================================================================
+
+#[contract_trait]
+pub trait OAppOptionsType3: RoleBasedAccessControl {
+    /// Retrieves the enforced options for a given endpoint and message type.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    /// * `msg_type` - The OApp message type
+    ///
+    /// # Returns
+    /// The enforced options for the given endpoint and message type
+    fn enforced_options(env: &soroban_sdk::Env, eid: u32, msg_type: u32) -> Option<soroban_sdk::Bytes> {
+        OAppOptionsType3Storage::enforced_options(env, eid, msg_type)
+    }
+
+    /// Sets or removes the enforced options for specific endpoint and message type combinations.
+    ///
+    /// Only the `authorizer` of the OApp can call this function.
+    /// Provides a way for the OApp to enforce things like paying for PreCrime, AND/OR minimum dst lzReceive gas amounts etc.
+    /// These enforced options can vary as the potential options/execution on the remote may differ as per the msg_type.
+    /// e.g. Amount of lzReceive() gas necessary to deliver a lzCompose() message adds overhead you don't want to pay
+    /// if you are only making a standard LayerZero message ie. lzReceive() WITHOUT sendCompose().
+    ///
+    /// # Arguments
+    /// * `options` - A vector of EnforcedOptionParam structures specifying enforced options
+    /// * `operator` - The authorizer address
+    #[only_role(operator, AUTHORIZER)]
+    fn set_enforced_options(
+        env: &soroban_sdk::Env,
+        options: &soroban_sdk::Vec<oapp::oapp_options_type3::EnforcedOptionParam>,
+        operator: &soroban_sdk::Address,
+    ) {
+        for param in options {
+            if let Some(ref opts) = param.options {
+                assert_option_type3(env, opts);
+            }
+            OAppOptionsType3Storage::set_or_remove_enforced_options(env, param.eid, param.msg_type, &param.options);
+        }
+        EnforcedOptionSet { enforced_options: options.clone() }.publish(env);
+    }
+
+    /// Combines options for a given endpoint and message type.
+    ///
+    /// If there is an enforced lzReceive option:
+    /// - {gas_limit: 200k, value: 1 XLM} AND a caller supplies a lzReceive option: {gas_limit: 100k, value: 0.5 XLM}
+    /// - The resulting options will be {gas_limit: 300k, value: 1.5 XLM} when the message is executed on the remote lz_receive() function.
+    /// The presence of duplicated options is handled off-chain in the verifier/executor.
+    ///
+    /// # Arguments
+    /// * `eid` - The endpoint ID
+    /// * `msg_type` - The OApp message type
+    /// * `extra_options` - Additional options passed by the caller
+    ///
+    /// # Returns
+    /// The combination of caller specified options AND enforced options
+    fn combine_options(
+        env: &soroban_sdk::Env,
+        eid: u32,
+        msg_type: u32,
+        extra_options: &soroban_sdk::Bytes,
+    ) -> soroban_sdk::Bytes {
+        let enforced_options_opt = Self::enforced_options(env, eid, msg_type);
+
+        // No enforced options, pass whatever the caller supplied, even if it's empty or legacy type 1/2 options.
+        if enforced_options_opt.is_none() {
+            return extra_options.clone();
+        }
+
+        // No caller options, return enforced
+        let mut enforced_options = enforced_options_opt.unwrap(); // unwrap is safe because we checked if it is none above
+        if extra_options.is_empty() {
+            return enforced_options;
+        }
+
+        // If caller provided extra_options, must be type 3 as its the ONLY type that can be combined.
+        if extra_options.len() >= 2 {
+            assert_option_type3(env, extra_options);
+
+            // Remove the first 2 bytes containing the type from the extra_options and combine with enforced.
+            enforced_options.append(&extra_options.slice(2..));
+            return enforced_options;
+        }
+
+        // No valid set of options was found.
+        panic_with_error!(env, OAppError::InvalidOptions);
+    }
+}
+
+// =========================================================================
+// Helpers Functions
+// =========================================================================
+
+/// Asserts that the provided options are of type 3.
+///
+/// # Arguments
+/// * `options` - The options to be checked
+///
+/// # Panics
+/// If the options are not of type 3
+pub fn assert_option_type3(env: &Env, options: &Bytes) {
+    let options_type = BufferReader::new(options).read_u16();
+    assert_with_error!(env, options_type == OPTION_TYPE3, OAppError::InvalidOptions);
+}