@layerzerolabs/common-utils-stellar-contracts 0.2.122

package/Cargo.toml

@@ -0,0 +1,28 @@
+# Standalone framework crate (extracted from protocol-stellar-v2). Self-contained: explicit
+# version/edition/dep versions (not workspace-inherited) so it builds outside the protocol workspace
+# and vendors cleanly into consumers' dependencies/. Versions mirror the protocol's [workspace.dependencies].
+# Proc-macro crate lives in sibling package @layerzerolabs/common-utils-macros-stellar-contracts.
+[package]
+name = "utils"
+version = "0.0.1"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["rlib"]
+doctest = false
+
+[features]
+# Forwards Soroban test APIs so enabling utils/testutils alone is self-contained
+# for external consumers (no separate soroban-sdk/testutils required).
+testutils = ["soroban-sdk/testutils"]
+
+[dependencies]
+# exact-pinned (=): a bare "25.1.1" is a caret range that lets fresh resolution drift to soroban-sdk's
+# latest patch, which can raise its MSRV above the pinned rustc toolchain here (hit: 25.3.1 needs
+# rustc 1.91, this crate builds with 1.90) -- exact-pin so that can never happen silently.
+soroban-sdk = { version = "=25.1.1", features = ["hazmat-address", "hazmat-crypto"] }
+common-macros = { path = "dependencies/common-utils-macros-stellar-contracts" }
+
+[dev-dependencies]
+soroban-sdk = { version = "=25.1.1", features = ["hazmat-address", "hazmat-crypto", "testutils"] }

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/clippy.toml

@@ -0,0 +1,7 @@
+# Clippy configuration for Stellar protocol 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,43 @@
+{
+  "name": "@layerzerolabs/common-utils-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"
+  },
+  "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/common-utils-macros-stellar-contracts": "workspace:*"
+  },
+  "scripts": {
+    "build": "pnpm resolve-dependencies && pnpm exec lz-tool --script \"cargo build\" 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",
+    "resolve-dependencies": "pnpm exec build-utils-rust resolve",
+    "test": "pnpm resolve-dependencies && pnpm exec lz-tool --script \"cargo nextest run --features testutils\" 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/auth.rs

@@ -0,0 +1,48 @@
+//! Base authorization trait for owner-protected operations.
+//!
+//! The `Auth` trait provides a common interface for authorization that can be
+//! implemented by different access control patterns (e.g., single owner, multisig).
+
+use crate::{errors::AuthError, option_ext::OptionExt};
+use soroban_sdk::{contractclient, Address, Env};
+
+// ===========================================================================
+// Auth trait
+// ===========================================================================
+
+/// Base trait for authorization.
+///
+/// Provides the authorizer address for owner-protected operations. This trait
+/// is implemented by both `Ownable` (external owner) and `MultiSig` (self-owning).
+#[contractclient(name = "AuthClient")]
+pub trait Auth: Sized {
+    /// Returns the address that authorizes owner-protected operations.
+    ///
+    /// For `Ownable` contracts, this returns the stored owner address.
+    /// For `MultiSig` contracts, this returns the contract's own address
+    /// (self-owning pattern).
+    ///
+    /// Returns `None` when there is no authorizer (for example, when an Ownable
+    /// contract's owner has been renounced).
+    fn authorizer(env: &Env) -> Option<Address>;
+}
+
+// ===========================================================================
+// Auth helper functions
+// ===========================================================================
+
+/// Enforces authorization from the authorizer and returns the authorizer address.
+///
+/// Panics if the authorizer has not provided authorization for this invocation.
+pub fn enforce_auth<T: Auth>(env: &Env) -> Address {
+    let authorizer = T::authorizer(env).unwrap_or_panic(env, AuthError::AuthorizerNotFound);
+    authorizer.require_auth();
+    authorizer
+}
+
+/// Requires authorization from the authorizer.
+///
+/// Panics if the authorizer has not provided authorization for this invocation.
+pub fn require_auth<T: Auth>(env: &Env) {
+    let _ = enforce_auth::<T>(env);
+}

package/src/buffer_reader.rs

@@ -0,0 +1,194 @@
+use crate::{
+    buffer_writer::{ACCOUNT_PAYLOAD_TYPE, CONTRACT_PAYLOAD_TYPE},
+    bytes_ext::BytesExt,
+    errors::BufferReaderError,
+};
+use core::mem;
+use soroban_sdk::{
+    address_payload::AddressPayload, assert_with_error, panic_with_error, Address, Bytes, BytesN, Env, I256, U256,
+};
+
+/// Generates read methods for primitive integer types using big-endian byte order.
+///
+/// Each generated method reads a fixed number of bytes from the buffer, converts them
+/// from big-endian format to the target integer type, and advances the read position.
+///
+/// # Syntax
+/// ```ignore
+/// impl_read_int!(method_name, Type; ...);
+/// ```
+macro_rules! impl_read_int {
+    ($($method:ident, $type:ty);* $(;)?) => {
+        $(
+            pub fn $method(&mut self) -> $type {
+                <$type>::from_be_bytes(self.read_bytes(mem::size_of::<$type>() as u32).to_array())
+            }
+        )*
+    };
+}
+
+/// A sequential reader for parsing binary data from a byte buffer.
+///
+/// Maintains a position cursor that advances as data is read.
+/// All integer reads are big-endian.
+///
+/// # Example
+/// ```ignore
+/// let mut reader = BufferReader::new(&bytes);
+/// let value = reader.read_u32();
+/// let value = reader.read_bool();
+/// let addr = reader.read_address();
+/// ```
+pub struct BufferReader<'a> {
+    buffer: &'a Bytes,
+    pos: u32,
+}
+
+impl<'a> BufferReader<'a> {
+    /// Creates a new reader starting at position 0.
+    pub fn new(buffer: &'a Bytes) -> Self {
+        Self { buffer, pos: 0 }
+    }
+
+    /// Sets the read position to an absolute byte offset.
+    pub fn seek(&mut self, pos: u32) -> &mut Self {
+        assert_with_error!(self.buffer.env(), pos <= self.buffer.len(), BufferReaderError::InvalidLength);
+        self.pos = pos;
+        self
+    }
+
+    /// Advances the position by `len` bytes without reading.
+    pub fn skip(&mut self, len: u32) -> &mut Self {
+        self.seek(self.pos + len)
+    }
+
+    /// Moves the position backwards by `len` bytes.
+    pub fn rewind(&mut self, len: u32) -> &mut Self {
+        assert_with_error!(self.buffer.env(), self.pos >= len, BufferReaderError::InvalidLength);
+        self.pos -= len;
+        self
+    }
+
+    // Generates: read_u8 (1 byte), read_u16 (2 bytes), read_u32 (4 bytes), read_u64 (8 bytes), read_u128 (16 bytes)
+    impl_read_int!(read_u8, u8; read_u16, u16; read_u32, u32; read_u64, u64; read_u128, u128);
+    // Generate: read_i8 (1 byte), read_i16 (2 bytes), read_i32 (4 bytes), read_i64 (8 bytes), read_i128 (16 bytes)
+    impl_read_int!(read_i8, i8; read_i16, i16; read_i32, i32; read_i64, i64; read_i128, i128);
+
+    /// Reads a boolean (1 byte, non-zero = true).
+    pub fn read_bool(&mut self) -> bool {
+        self.read_u8() != 0
+    }
+
+    /// Reads a U256 (32 bytes, big-endian).
+    pub fn read_u256(&mut self) -> U256 {
+        U256::from_be_bytes(self.buffer.env(), &self.read_bytes(32))
+    }
+
+    /// Reads a I256 (32 bytes, big-endian).
+    pub fn read_i256(&mut self) -> I256 {
+        I256::from_be_bytes(self.buffer.env(), &self.read_bytes(32))
+    }
+
+    /// Reads a Stellar address (33 bytes: 1 type + 32 payload).
+    pub fn read_address(&mut self) -> Address {
+        let payload_type = self.read_u8();
+        let payload = self.read_address_payload();
+        self.compose_address(payload_type, payload)
+    }
+
+    /// Reads an address payload only from the buffer (32 bytes).
+    pub fn read_address_payload(&mut self) -> BytesN<32> {
+        self.read_bytes_n()
+    }
+
+    /// Reads N bytes as a fixed-size BytesN<N>.
+    pub fn read_bytes_n<const N: usize>(&mut self) -> BytesN<N> {
+        BytesN::<N>::from_array(self.buffer.env(), &self.read_array())
+    }
+
+    pub fn read_array<const N: usize>(&mut self) -> [u8; N] {
+        self.read_bytes(N as u32).to_array()
+    }
+
+    /// Reads `len` bytes from current position and advances.
+    pub fn read_bytes(&mut self, len: u32) -> Bytes {
+        let end = self.pos + len;
+        assert_with_error!(self.buffer.env(), self.buffer.len() >= end, BufferReaderError::InvalidLength);
+
+        let value = self.buffer.slice(self.pos..end);
+        self.pos = end;
+        value
+    }
+
+    /// Reads all bytes from current position to the end of the buffer.
+    pub fn read_bytes_until_end(&mut self) -> Bytes {
+        self.read_bytes(self.remaining_len())
+    }
+
+    /// Returns the current read position.
+    pub fn position(&self) -> u32 {
+        self.pos
+    }
+
+    /// Returns a reference to the underlying buffer.
+    pub fn buffer(&self) -> &Bytes {
+        self.buffer
+    }
+
+    /// Returns the total length of the buffer.
+    pub fn len(&self) -> u32 {
+        self.buffer.len()
+    }
+
+    /// Returns true if the buffer is empty.
+    pub fn is_empty(&self) -> bool {
+        self.buffer.is_empty()
+    }
+
+    /// Returns the number of bytes remaining after current position.
+    pub fn remaining_len(&self) -> u32 {
+        self.buffer.len() - self.pos
+    }
+
+    /// Returns the Soroban environment reference.
+    pub fn env(&self) -> &Env {
+        self.buffer.env()
+    }
+
+    // ============================================================================================
+    // Internal Functions
+    // ============================================================================================
+
+    /// Compose an address from its type byte and 32-byte payload.
+    fn compose_address(&self, payload_type: u8, payload: BytesN<32>) -> Address {
+        let addr_payload = match payload_type {
+            ACCOUNT_PAYLOAD_TYPE => AddressPayload::AccountIdPublicKeyEd25519(payload),
+            CONTRACT_PAYLOAD_TYPE => AddressPayload::ContractIdHash(payload),
+            _ => panic_with_error!(self.buffer.env(), BufferReaderError::InvalidAddressPayload),
+        };
+        Address::from_payload(self.buffer.env(), addr_payload)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_size_of_unsigned_integers() {
+        assert_eq!(mem::size_of::<u8>(), 1);
+        assert_eq!(mem::size_of::<u16>(), 2);
+        assert_eq!(mem::size_of::<u32>(), 4);
+        assert_eq!(mem::size_of::<u64>(), 8);
+        assert_eq!(mem::size_of::<u128>(), 16);
+    }
+
+    #[test]
+    fn test_size_of_signed_integers() {
+        assert_eq!(mem::size_of::<i8>(), 1);
+        assert_eq!(mem::size_of::<i16>(), 2);
+        assert_eq!(mem::size_of::<i32>(), 4);
+        assert_eq!(mem::size_of::<i64>(), 8);
+        assert_eq!(mem::size_of::<i128>(), 16);
+    }
+}

package/src/buffer_writer.rs

@@ -0,0 +1,138 @@
+use crate::{errors::BufferWriterError, option_ext::OptionExt};
+use soroban_sdk::{address_payload::AddressPayload, Address, Bytes, BytesN, Env, I256, U256};
+
+/// Generates write methods for primitive integer types using big-endian byte order.
+///
+/// Each generated method writes a fixed number of bytes to the buffer, converts the
+/// integer value to big-endian format, and advances the write position.
+///
+/// # Syntax
+/// ```ignore
+/// impl_write_int!(method_name, Type; ...);
+/// ```
+macro_rules! impl_write_int {
+    ($($method:ident, $type:ty);* $(;)?) => {
+        $(
+            pub fn $method(&mut self, value: $type) -> &mut Self {
+                self.buffer.extend_from_slice(&value.to_be_bytes());
+                self
+            }
+        )*
+    };
+}
+
+pub const ACCOUNT_PAYLOAD_TYPE: u8 = 0;
+pub const CONTRACT_PAYLOAD_TYPE: u8 = 1;
+
+/// A writer for serializing data to a byte buffer.
+///
+/// The writer maintains an internal byte buffer and provides methods to write
+/// various data types in big-endian format. All write operations return a
+/// mutable reference to the writer, enabling method chaining.
+///
+/// # Example
+/// ```ignore
+/// let mut writer = BufferWriter::new(&env);
+/// writer.write_u32(0x12345678)
+///       .write_bool(true)
+///       .write_bytes32(&bytes32);
+/// let bytes = writer.to_bytes();
+/// ```
+pub struct BufferWriter {
+    buffer: Bytes,
+}
+
+impl BufferWriter {
+    /// Create a new empty writer.
+    pub fn new(env: &Env) -> Self {
+        Self { buffer: Bytes::new(env) }
+    }
+
+    /// Create a new writer initialized with existing data.
+    pub fn from_bytes(buffer: Bytes) -> Self {
+        Self { buffer }
+    }
+
+    // Generates: write_u8 (1 byte), write_u16 (2 bytes), write_u32 (4 bytes), write_u64 (8 bytes), write_u128 (16 bytes)
+    impl_write_int!(write_u8, u8; write_u16, u16; write_u32, u32; write_u64, u64; write_u128, u128);
+    // Generate: write_i8 (1 byte), write_i16 (2 bytes), write_i32 (4 bytes), write_i64 (8 bytes), write_i128 (16 bytes)
+    impl_write_int!(write_i8, i8; write_i16, i16; write_i32, i32; write_i64, i64; write_i128, i128);
+
+    /// Write a boolean value to the buffer (true as 1, false as 0).
+    pub fn write_bool(&mut self, value: bool) -> &mut Self {
+        self.write_u8(if value { 1 } else { 0 })
+    }
+
+    /// Write an unsigned 256-bit integer in big-endian format.
+    pub fn write_u256(&mut self, value: U256) -> &mut Self {
+        self.buffer.append(&value.to_be_bytes());
+        self
+    }
+
+    /// Write a signed 256-bit integer in big-endian format.
+    pub fn write_i256(&mut self, value: I256) -> &mut Self {
+        self.buffer.append(&value.to_be_bytes());
+        self
+    }
+
+    /// Write an address type and payload to the buffer (33 bytes: 1 type + 32 payload).
+    pub fn write_address(&mut self, address: &Address) -> &mut Self {
+        let (payload_type, payload) = self.decompose_address(address);
+        self.write_u8(payload_type).write_bytes_n(&payload)
+    }
+
+    /// Write an address payload only to the buffer (32 bytes).
+    pub fn write_address_payload(&mut self, address: &Address) -> &mut Self {
+        let (_, payload) = self.decompose_address(address);
+        self.write_bytes_n(&payload)
+    }
+
+    /// Write a byte slice to the buffer (appends without length prefix).
+    pub fn write_bytes(&mut self, bytes: &Bytes) -> &mut Self {
+        self.buffer.append(bytes);
+        self
+    }
+
+    /// Write a fixed-size BytesN<N> to the buffer.
+    pub fn write_bytes_n<const N: usize>(&mut self, bytes_n: &BytesN<N>) -> &mut Self {
+        self.buffer.extend_from_array(&bytes_n.to_array());
+        self
+    }
+
+    pub fn write_array<const N: usize>(&mut self, array: &[u8; N]) -> &mut Self {
+        self.buffer.extend_from_array(array);
+        self
+    }
+
+    /// Get the complete buffer as a Bytes.
+    pub fn to_bytes(&self) -> Bytes {
+        self.buffer.clone()
+    }
+
+    /// Get the current length of the buffer.
+    pub fn len(&self) -> u32 {
+        self.buffer.len()
+    }
+
+    /// Check if the buffer is empty.
+    pub fn is_empty(&self) -> bool {
+        self.buffer.is_empty()
+    }
+
+    /// Get the environment from the buffer.
+    pub fn env(&self) -> &Env {
+        self.buffer.env()
+    }
+
+    // ============================================================================================
+    // Internal Functions
+    // ============================================================================================
+
+    /// Decompose an address into its type byte and 32-byte payload.
+    fn decompose_address(&self, address: &Address) -> (u8, BytesN<32>) {
+        match address.to_payload().unwrap_or_panic(self.buffer.env(), BufferWriterError::InvalidAddressPayload) {
+            AddressPayload::AccountIdPublicKeyEd25519(p) => (ACCOUNT_PAYLOAD_TYPE, p),
+            AddressPayload::ContractIdHash(p) => (CONTRACT_PAYLOAD_TYPE, p),
+        }
+    }
+}

package/src/bytes_ext.rs

@@ -0,0 +1,18 @@
+use crate::errors::BytesExtError;
+use soroban_sdk::{assert_with_error, Bytes};
+
+/// Extension trait for `Bytes` to convert to fixed-size arrays
+pub trait BytesExt {
+    /// Copies the entire bytes into a fixed-size array.
+    /// Panics if bytes length != N.
+    fn to_array<const N: usize>(&self) -> [u8; N];
+}
+
+impl BytesExt for Bytes {
+    fn to_array<const N: usize>(&self) -> [u8; N] {
+        assert_with_error!(self.env(), self.len() == N as u32, BytesExtError::LengthMismatch);
+        let mut buf = [0u8; N];
+        self.copy_into_slice(&mut buf);
+        buf
+    }
+}

package/src/errors.rs

@@ -0,0 +1,82 @@
+use common_macros::contract_error;
+
+// Utils library error codes: 1000-1099
+// See docs/error-spec.md for allocation rules
+
+/// BufferReaderError: 1000-1009
+#[contract_error]
+pub enum BufferReaderError {
+    InvalidLength = 1000,
+    InvalidAddressPayload,
+}
+
+/// BufferWriterError: 1010-1019
+#[contract_error]
+pub enum BufferWriterError {
+    InvalidAddressPayload = 1010,
+}
+
+/// TtlConfigurableError: 1020-1029
+#[contract_error]
+pub enum TtlConfigurableError {
+    InvalidTtlConfig = 1020,
+    TtlConfigFrozen,
+    TtlConfigAlreadyFrozen,
+}
+
+/// OwnableError: 1030-1039
+#[contract_error]
+pub enum OwnableError {
+    InvalidAuthorizer = 1030,
+    InvalidPendingOwner,
+    InvalidTtl,
+    NoPendingTransfer,
+    OwnerAlreadySet,
+    OwnerNotSet,
+    TransferInProgress,
+}
+
+/// BytesExtError: 1040-1049
+#[contract_error]
+pub enum BytesExtError {
+    LengthMismatch = 1040,
+}
+
+/// UpgradeableError: 1050-1059
+#[contract_error]
+pub enum UpgradeableError {
+    InvalidMigrationData = 1050,
+    MigrationNotAllowed,
+}
+
+/// MultiSigError: 1060-1069
+#[contract_error]
+pub enum MultiSigError {
+    AlreadyInitialized = 1060,
+    InvalidAuthorizer,
+    InvalidSigner,
+    SignatureError,
+    SignerAlreadyExists,
+    SignerNotFound,
+    TotalSignersLessThanThreshold,
+    UnsortedSigners,
+    ZeroThreshold,
+}
+
+/// AuthError: 1070-1079
+#[contract_error]
+pub enum AuthError {
+    AuthorizerNotFound = 1070,
+}
+
+/// RbacError: 1080-1089
+#[contract_error]
+pub enum RbacError {
+    AdminRoleNotFound = 1080,
+    IndexOutOfBounds,
+    MaxRolesExceeded,
+    RoleIsEmpty,
+    RoleNotFound,
+    RoleNotHeld,
+    Unauthorized,
+}

package/src/lib.rs

@@ -0,0 +1,20 @@
+#![no_std]
+
+pub mod auth;
+pub mod buffer_reader;
+pub mod buffer_writer;
+pub mod bytes_ext;
+pub mod errors;
+pub mod multisig;
+pub mod option_ext;
+pub mod ownable;
+pub mod rbac;
+pub mod ttl_configurable;
+pub mod ttl_extendable;
+pub mod upgradeable;
+
+#[cfg(test)]
+mod tests;
+
+#[cfg(any(test, feature = "testutils"))]
+pub mod testing_utils;