@layerzerolabs/protocol-stellar-v2 0.2.21 → 0.2.23

package/Cargo.lock

@@ -329,6 +329,7 @@ checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 name = "counter"
 version = "0.0.1"
 dependencies = [
+ "blocked-message-lib",
  "common-macros",
  "dvn",
  "dvn-fee-lib",
@@ -1676,7 +1677,7 @@ dependencies = [
  "soroban-env-macros",
  "soroban-wasmi",
  "static_assertions",
- "stellar-xdr 25.0.0",
+ "stellar-xdr",
  "wasmparser",
 ]
 
@@ -1738,15 +1739,15 @@ dependencies = [
  "quote",
  "serde",
  "serde_json",
- "stellar-xdr 25.0.0",
+ "stellar-xdr",
  "syn 2.0.108",
 ]
 
 [[package]]
 name = "soroban-ledger-snapshot"
-version = "25.0.1"
+version = "25.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "af1d4de49c32b4285f63a84764c57f36b32a177dfb7dad02e06d9f8cc77d6115"
+checksum = "99c5285c83e7a5581879b7a65033eae53b24ac9689975aa6887f1d8ee3e941c9"
 dependencies = [
  "serde",
  "serde_json",
@@ -1758,9 +1759,9 @@ dependencies = [
 
 [[package]]
 name = "soroban-sdk"
-version = "25.0.1"
+version = "25.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0ce2a038346959b8073f3fcab7d608441ccb4a963e7261053f135adbee1972f8"
+checksum = "b1262aa83e99a0fb3e8cd56d6e5ca4c28ac4f9871ac7173f65301a8b9a12c20f"
 dependencies = [
  "arbitrary",
  "bytes-lit",
@@ -1782,9 +1783,9 @@ dependencies = [
 
 [[package]]
 name = "soroban-sdk-macros"
-version = "25.0.1"
+version = "25.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "17eab1ea0b58aa644cd9b37818a0c5ac23f02db7cd064a6914647116ca4a5480"
+checksum = "93b62c526917a1e77b6dce3cd841b6c271f0fff344ea93ad92a8c45afe8051b6"
 dependencies = [
  "darling 0.20.11",
  "heck 0.5.0",
@@ -1794,57 +1795,45 @@ dependencies = [
  "quote",
  "sha2 0.10.9",
  "soroban-env-common",
- "soroban-spec 25.0.1",
+ "soroban-spec",
  "soroban-spec-rust",
- "stellar-xdr 25.0.0",
+ "stellar-xdr",
  "syn 2.0.108",
 ]
 
 [[package]]
 name = "soroban-spec"
-version = "23.4.0"
+version = "25.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c55623057d24c2a5326f519b56a756463f2aeb7ae62af0978fa0b9bab59d732d"
+checksum = "0186c943a78de7038ce7eee478f521f7a7665440101ae0d24b4a59833fb6d833"
 dependencies = [
  "base64 0.22.1",
- "stellar-xdr 23.0.0",
- "thiserror",
- "wasmparser",
-]
-
-[[package]]
-name = "soroban-spec"
-version = "25.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1bb240973e06456393328d0bdb3397e86bbe7369972b0a94ad13e51b55eacd65"
-dependencies = [
- "base64 0.22.1",
- "stellar-xdr 25.0.0",
+ "stellar-xdr",
  "thiserror",
  "wasmparser",
 ]
 
 [[package]]
 name = "soroban-spec-rust"
-version = "25.0.1"
+version = "25.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ce64a5ae92b7c0fe5c995ca47dccb83b12c0a60b0409f3b919b87afa41f64e2"
+checksum = "7a948196ed0633be3a4125e0c7a4fc0bb6337942e538813b1f171331738f9058"
 dependencies = [
  "prettyplease",
  "proc-macro2",
  "quote",
  "sha2 0.10.9",
- "soroban-spec 25.0.1",
- "stellar-xdr 25.0.0",
+ "soroban-spec",
+ "stellar-xdr",
  "syn 2.0.108",
  "thiserror",
 ]
 
 [[package]]
 name = "soroban-spec-typescript"
-version = "23.1.4"
+version = "25.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8df8961c70a7cba82798933b65a57c7108c4b6c228a0940aa5e30c2d7568a1d1"
+checksum = "25684cb264ba39bac049ba93fc66fd241993c9aefb82d60d60417736408ec61a"
 dependencies = [
  "base64 0.21.7",
  "heck 0.4.1",
@@ -1855,8 +1844,8 @@ dependencies = [
  "serde_derive",
  "serde_json",
  "sha2 0.9.9",
- "soroban-spec 23.4.0",
- "stellar-xdr 23.0.0",
+ "soroban-spec",
+ "stellar-xdr",
  "thiserror",
 ]
 
@@ -1922,24 +1911,6 @@ dependencies = [
  "heapless",
 ]
 
-[[package]]
-name = "stellar-xdr"
-version = "23.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "89d2848e1694b0c8db81fd812bfab5ea71ee28073e09ccc45620ef3cf7a75a9b"
-dependencies = [
- "base64 0.22.1",
- "cfg_eval",
- "crate-git-revision",
- "escape-bytes",
- "ethnum",
- "hex",
- "serde",
- "serde_with",
- "sha2 0.10.9",
- "stellar-strkey 0.0.13",
-]
-
 [[package]]
 name = "stellar-xdr"
 version = "25.0.0"

package/Cargo.toml

@@ -14,7 +14,8 @@ license = "MIT"
 version = "0.0.1"
 
 [workspace.dependencies]
-soroban-sdk = { version = "25.0.1", features = ["hazmat-address", "hazmat-crypto"] }
+soroban-sdk = { version = "25.1.0", features = ["hazmat-address", "hazmat-crypto"] }
+soroban-spec-typescript = "25.1.0" # used in tools/ts-bindings-gen
 
 # Third-party dependencies (production)
 cfg-if = { version = "1.0", default-features = false }
@@ -31,6 +32,9 @@ insta = "1.44.3"
 k256 = "0.13"
 prettyplease = "0.2.37"
 rand = "0.8"
+anyhow = "1.0"
+sha2 = "0.10"
+base64 = "0.22"
 sha3 = "0.10"
 trybuild = "1.0.114"
 
@@ -44,6 +48,7 @@ executor-fee-lib = { path = "contracts/workers/executor-fee-lib" }
 executor-helper = { path = "contracts/workers/executor-helper" }
 fee-lib-interfaces = { path = "contracts/workers/fee-lib-interfaces" }
 message-lib-common = { path = "contracts/message-libs/message-lib-common" }
+blocked-message-lib = { path = "contracts/message-libs/blocked-message-lib" }
 oapp = { path = "contracts/oapps/oapp" }
 oapp-macros = { path = "contracts/oapps/oapp-macros" }
 oft = { path = "contracts/oapps/oft" }

package/contracts/common-macros/src/auth.rs

@@ -2,7 +2,7 @@
 //!
 //! This module provides macros for implementing authorization patterns:
 //! - `#[ownable]` - Owner-based access control (external owner address)
-//! - `#[multisig]` - Multisig-based access control (self-owning pattern)
+//! - `#[multisig]` - MultiSig-based access control (self-owning pattern)
 //! - `#[only_auth]` - Authorization check attribute for functions
 
 use crate::utils;
@@ -16,9 +16,10 @@ use syn::{parse_quote, ItemFn, ItemStruct};
 
 /// Generates the ownable implementation from the `#[ownable]` attribute macro.
 ///
-/// This macro implements both `Auth` and `Ownable` traits for the contract:
+/// This macro implements `OwnableInitializer`, `Auth`, and `Ownable` traits for the contract:
+/// - `OwnableInitializer` provides `init_owner()` for constructor use
 /// - `Auth::authorizer()` returns the stored owner address
-/// - `Ownable` provides ownership management (transfer, renounce)
+/// - `Ownable` provides ownership management (transfer, propose, accept, renounce)
 pub fn generate_ownable_impl(input: TokenStream) -> TokenStream {
     let item_struct: ItemStruct = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse struct: {}", e));
     let name = &item_struct.ident;
@@ -43,14 +44,14 @@ pub fn generate_ownable_impl(input: TokenStream) -> TokenStream {
 }
 
 // ============================================================================
-// Multisig Macro Implementation
+// MultiSig Macro Implementation
 // ============================================================================
 
 /// Generates the multisig implementation from the `#[multisig]` attribute macro.
 ///
-/// This macro implements both `Auth` and `Multisig` traits for the contract:
+/// This macro implements both `Auth` and `MultiSig` traits for the contract:
 /// - `Auth::authorizer()` returns the contract's own address (self-owning pattern)
-/// - `Multisig` provides signature verification and signer management
+/// - `MultiSig` provides signature verification and signer management
 pub fn generate_multisig_impl(input: TokenStream) -> TokenStream {
     let item_struct: ItemStruct = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse struct: {}", e));
     let name = &item_struct.ident;
@@ -58,7 +59,7 @@ pub fn generate_multisig_impl(input: TokenStream) -> TokenStream {
     quote! {
         #item_struct
 
-        use utils::{auth::Auth as _, multisig::Multisig as _};
+        use utils::{auth::Auth as _, multisig::MultiSig as _};
 
         #[common_macros::contract_impl]
         impl utils::auth::Auth for #name {
@@ -68,7 +69,7 @@ pub fn generate_multisig_impl(input: TokenStream) -> TokenStream {
         }
 
         #[common_macros::contract_impl(contracttrait)]
-        impl utils::multisig::Multisig for #name {}
+        impl utils::multisig::MultiSig for #name {}
     }
 }
 
@@ -79,7 +80,7 @@ pub fn generate_multisig_impl(input: TokenStream) -> TokenStream {
 /// Prepends an auth check to a method using the `Auth` trait.
 ///
 /// Works with any contract that implements the `Auth` trait, including both
-/// `Ownable` and `Multisig` contracts.
+/// `Ownable` and `MultiSig` contracts.
 pub fn prepend_only_auth_check(input: TokenStream) -> TokenStream {
     let mut input_fn: ItemFn = syn::parse2(input).unwrap_or_else(|e| panic!("failed to parse function: {}", e));
 

package/contracts/common-macros/src/contract_ttl.rs

@@ -86,10 +86,7 @@ fn init_default_ttl_configs_stmt(env_param: &utils::EnvParam<'_>) -> syn::Stmt {
 /// Generates a statement that extends instance TTL if configured.
 fn extend_instance_ttl_stmt(env_param: &utils::EnvParam<'_>) -> syn::Stmt {
     let env_ref = env_param.as_ref_tokens();
-    let env_ident = env_param.ident;
     syn::parse_quote! {
-        if let Some(instance_ttl) = utils::ttl_configurable::TtlConfigStorage::instance(#env_ref) {
-            #env_ident.storage().instance().extend_ttl(instance_ttl.threshold, instance_ttl.extend_to);
-        }
+        utils::ttl_configurable::extend_instance_ttl(#env_ref);
     }
 }

package/contracts/common-macros/src/error.rs

@@ -2,9 +2,7 @@ use proc_macro2::TokenStream;
 use quote::quote;
 use syn::{parse_quote, spanned::Spanned, ExprLit, Fields, ItemEnum, Lit, Token};
 
-pub fn generate_error(attr: TokenStream, item: TokenStream) -> TokenStream {
-    assert!(attr.is_empty(), "contract_error attribute is not supported");
-
+pub fn generate_error(item: TokenStream) -> TokenStream {
     let mut data_enum: ItemEnum = syn::parse2(item).unwrap_or_else(|e| panic!("failed to parse enum: {}", e));
 
     // For variants without an explicit discriminant, assign sequential error codes starting at 1

package/contracts/common-macros/src/lib.rs

@@ -1,24 +1,17 @@
 //! Common procedural macros for Stellar smart contracts.
 //!
-//! This crate provides foundational macros for Stellar contract development:
-//! - **Storage macros** - Strongly-typed contract storage API generation
-//! - **Error macros** - Contract error enum generation
-//! - **Auth macros** - Authorization-based access control (ownable, multisig, only_auth)
-//! - **TTL macros** - Time-to-live configuration and automatic extension
-//! - **Wrapper macros** - Convenient macro combinations for common patterns
-//!
 //! # Quick Links
-//! - [`storage`] - Storage enum to API macro
 //! - [`contract_error`] - Error enum generation macro
-//! - [`ownable`] - Ownable trait implementation macro
-//! - [`multisig`] - Multisig trait implementation macro
+//! - [`contract_impl`] - Contract impl with automatic instance TTL extension
+//! - [`contract_trait`] - Contract trait with automatic instance TTL extension
+//! - [`lz_contract`] - Wrapper macro combining common LayerZero contract attributes
+//! - [`multisig`] - MultiSig trait implementation macro
 //! - [`only_auth`] - Auth-based access control attribute macro
+//! - [`ownable`] - Ownable trait implementation macro
+//! - [`storage`] - Storage enum to API macro
 //! - [`ttl_configurable`] - TTL configuration with freeze support
 //! - [`ttl_extendable`] - Manual instance TTL extension
-//! - [`contract_impl`] - Contract impl with automatic instance TTL extension
-//! - [`contract_trait`] - Contract trait with automatic instance TTL extension
 //! - [`upgradeable`] - Upgradeable trait implementation macro
-//! - [`lz_contract`] - Wrapper macro combining common LayerZero contract attributes
 //!
 
 use proc_macro::TokenStream;
@@ -43,7 +36,7 @@ mod tests;
 /// Generates strongly-typed storage API from enum variants.
 ///
 /// Transforms a storage enum into getter/setter/remove/set_or_remove/has/extend_ttl methods.
-/// TTL extension is automatic for persistent storage by default.
+/// TTL extension is automatic for persistent storage on get/set/has operations.
 ///
 /// # Example
 /// ```ignore
@@ -67,23 +60,25 @@ mod tests;
 ///     TempData,
 /// }
 ///
-/// // Generated API for each variant:
+/// // Generated API for instance storage (no extend_ttl method):
 /// DataKey::counter(&env)                               // -> Option<u32>
 /// DataKey::set_counter(&env, &value)                   // set value
 /// DataKey::has_counter(&env)                           // -> bool
 /// DataKey::remove_counter(&env)                        // remove entry
 /// DataKey::set_or_remove_counter(&env, &opt)           // set if Some, remove if None
-/// DataKey::extend_counter_ttl(&env, threshold, extend_to)  // manual TTL extension
 ///
-/// // With fields (keyed storage):
+/// // Generated API for persistent/temporary storage (includes extend_ttl):
 /// DataKey::nonce(&env, &user)                          // -> Option<u64>
 /// DataKey::set_nonce(&env, &user, &value)
+/// DataKey::has_nonce(&env, &user)                      // -> bool
+/// DataKey::remove_nonce(&env, &user)
 /// DataKey::set_or_remove_nonce(&env, &user, &opt)
+/// DataKey::extend_nonce_ttl(&env, &user, threshold, extend_to)  // manual TTL extension
 /// ```
 ///
 /// # Storage Types (required, exactly one per variant)
-/// - `#[instance(Type)]` - Stored with contract instance
-/// - `#[persistent(Type)]` - Durable ledger entries (TTL extended automatically)
+/// - `#[instance(Type)]` - Stored with contract instance (no extend_ttl method generated)
+/// - `#[persistent(Type)]` - Durable ledger entries (TTL auto-extended on get/set/has)
 /// - `#[temporary(Type)]` - Short-lived entries
 ///
 /// # Variant Attributes (optional)
@@ -91,42 +86,59 @@ mod tests;
 /// - `#[name("custom")]` - Override the generated function name base
 /// - `#[no_ttl_extension]` - Disable automatic TTL extension for this persistent variant
 #[proc_macro_attribute]
-pub fn storage(attr: TokenStream, item: TokenStream) -> TokenStream {
-    storage::generate_storage(attr.into(), item.into()).into()
+pub fn storage(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    storage::generate_storage(item.into()).into()
 }
 
 // ============================================================================
 // Error Macro
 // ============================================================================
 
-/// Generates a contract error enum with necessary derives.
+/// Generates a Soroban contract error enum with all required attributes and derives.
 ///
-/// Combines `#[contracterror]` from soroban-sdk with standard derives
-/// required for errors (Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)
-/// and `#[repr(u32)]`.
+/// This macro simplifies error enum definitions by automatically adding:
+/// - `#[contracterror]` from soroban-sdk for Soroban compatibility
+/// - `#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]` for standard error traits
+/// - `#[repr(u32)]` for stable ABI representation
+///
+/// # Discriminant Assignment
+///
+/// Variants without explicit discriminants are automatically assigned sequential values
+/// starting at 1. Explicit discriminants must be strictly increasing.
+///
+/// # Constraints
+///
+/// - All variants must be unit variants (no fields)
+/// - Explicit discriminants must be valid `u32` integer literals
+/// - Each discriminant must be greater than the previous one
+///
+/// # Examples
+///
+/// Basic usage with auto-assigned discriminants:
 ///
-/// # Example
 /// ```ignore
 /// #[contract_error]
 /// pub enum MyError {
-///     MyError1 = 1,
-///     MyError2 = 2,
+///     InvalidInput,    // = 1
+///     Unauthorized,    // = 2
+///     NotFound,        // = 3
 /// }
 /// ```
 ///
-/// Generated code:
+/// Mixed explicit and auto-assigned discriminants:
+///
 /// ```ignore
-/// #[contracterror]
-/// #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
-/// #[repr(u32)]
+/// #[contract_error]
 /// pub enum MyError {
-///     MyError1 = 1,
-///     MyError2 = 2,
+///     InvalidInput,    // = 1
+///     Unauthorized,    // = 2
+///     NotFound = 10,   // = 10 (explicit)
+///     Expired,         // = 11
 /// }
 /// ```
 #[proc_macro_attribute]
-pub fn contract_error(attr: TokenStream, item: TokenStream) -> TokenStream {
-    error::generate_error(attr.into(), item.into()).into()
+pub fn contract_error(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    error::generate_error(item.into()).into()
 }
 
 // ============================================================================
@@ -146,19 +158,20 @@ pub fn contract_error(attr: TokenStream, item: TokenStream) -> TokenStream {
 ///
 /// Generated code includes:
 /// - `OwnableInitializer` trait impl - Use `<Self as OwnableInitializer>::init_owner(env, owner)` to initialize
-/// - `Ownable` trait impl - `owner(env)`, `transfer_ownership(env, new_owner)`, `renounce_ownership(env)`
+/// - `Auth` trait impl - `authorizer(env)` returns the stored owner address
+/// - `Ownable` trait impl
 #[proc_macro_attribute]
 pub fn ownable(_attr: TokenStream, item: TokenStream) -> TokenStream {
     auth::generate_ownable_impl(item.into()).into()
 }
 
 // ============================================================================
-// Multisig Macro
+// MultiSig Macro
 // ============================================================================
 
 /// Generates multisig implementation with self-owning access control.
 ///
-/// Implements the `Multisig` trait and the `Auth` trait with self-owning pattern,
+/// Implements the `MultiSig` trait and the `Auth` trait with self-owning pattern,
 /// where the contract's own address is the authorizer. This allows multisig
 /// quorum approval to serve as the authorizer for owner-protected operations
 /// like TTL configuration and upgrades.
@@ -171,7 +184,7 @@ pub fn ownable(_attr: TokenStream, item: TokenStream) -> TokenStream {
 ///
 /// Generated code includes:
 /// - `Auth` trait impl - `authorizer(env)` returns `env.current_contract_address()`
-/// - `Multisig` trait impl - `set_signer(...)`, `set_threshold(...)`, `verify_signatures(...)`
+/// - `MultiSig` trait impl
 #[proc_macro_attribute]
 pub fn multisig(_attr: TokenStream, item: TokenStream) -> TokenStream {
     auth::generate_multisig_impl(item.into()).into()
@@ -187,7 +200,7 @@ pub fn multisig(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// using the `Auth` trait. The function will panic if called without authorization.
 ///
 /// Works with any contract that implements `Auth`, including both `Ownable` and
-/// `Multisig` contracts.
+/// `MultiSig` contracts.
 ///
 /// # Requirements
 /// - The function must have an `Env` parameter (by value or reference)
@@ -195,7 +208,7 @@ pub fn multisig(_attr: TokenStream, item: TokenStream) -> TokenStream {
 ///
 /// # Example
 /// ```ignore
-/// #[ownable]  // or implement Multisig
+/// #[ownable]  // or implement `#[multisig]`
 /// pub struct MyContract;
 ///
 /// #[soroban_sdk::contractimpl]
@@ -229,20 +242,13 @@ pub fn only_auth(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// providing TTL configuration management with auth-based access control.
 ///
 /// # Requirements
-/// The contract must implement the `Auth` trait (typically via `#[ownable]` or `Multisig`).
+/// The contract must implement the `Auth` trait (typically via `#[ownable]` or `#[multisig]`).
 ///
 /// # Example
 /// ```ignore
-/// #[ownable]  // or implement Multisig for self-owning contracts
+/// #[ownable]  // or `#[multisig]` for self-owning contracts
 /// #[ttl_configurable]
 /// pub struct MyContract;
-///
-/// #[contract_impl]
-/// impl MyContract {
-///     pub fn __constructor(env: &Env, owner: &Address) {
-///         <Self as utils::ownable::OwnableInitializer>::init_owner(env, owner);
-///     }
-/// }
 /// ```
 ///
 /// Generated code includes:
@@ -289,7 +295,7 @@ pub fn ttl_extendable(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// at the beginning of each contract entry function to keep the contract instance alive.
 ///
 /// # Requirements
-/// - The contract struct must have `#[ttl_configurable]` applied to provide `ttl_config()`
+/// - The contract struct must have `#[ttl_configurable]` applied to provide `ttl_configs()`
 /// - Methods must have an `Env` parameter to receive TTL extension
 ///
 /// # Behavior
@@ -317,9 +323,7 @@ pub fn ttl_extendable(_attr: TokenStream, item: TokenStream) -> TokenStream {
 /// #[soroban_sdk::contractimpl]
 /// impl MyContract {
 ///     pub fn my_method(env: &Env) {
-///         if let Some(ttl) = <Self as ::utils::ttl_configurable::TtlConfigurable>::ttl_config(env).0 {
-///             env.storage().instance().extend_ttl(ttl.threshold, ttl.extend_to);
-///         }
+///         utils::ttl_configurable::extend_instance_ttl(env);
 ///         // ... your code
 ///     }
 /// }
@@ -368,9 +372,7 @@ pub fn contract_impl(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// #[soroban_sdk::contracttrait]
 /// pub trait MyTrait {
 ///     fn my_method(env: &Env) {
-///         if let Some(ttl) = utils::ttl_configurable::TtlConfigStorage::instance(env) {
-///             env.storage().instance().extend_ttl(ttl.threshold, ttl.extend_to);
-///         }
+///         utils::ttl_configurable::extend_instance_ttl(env);
 ///         // ... your code
 ///     }
 ///
@@ -391,7 +393,7 @@ pub fn contract_trait(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// This macro implements `Upgradeable` using the trait's default methods (which include auth).
 ///
 /// # Requirements
-/// - The contract must implement the `Auth` trait (via `#[ownable]` or `Multisig`)
+/// - The contract must implement the `Auth` trait (via `#[ownable]` or `#[multisig]`)
 /// - By default, requires manual `UpgradeableInternal` implementation
 /// - With `no_migration` flag, auto-generates a no-op `UpgradeableInternal` impl
 ///
@@ -402,7 +404,7 @@ pub fn contract_trait(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// # Example
 /// ```ignore
 /// // Requires manual UpgradeableInternal implementation (default)
-/// #[ownable]
+/// #[ownable]  // or #[multisig]
 /// #[upgradeable]
 /// pub struct MyContract;
 ///
@@ -415,7 +417,7 @@ pub fn contract_trait(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// }
 ///
 /// // Auto-generates no-op UpgradeableInternal (for initial deployment)
-/// #[ownable]
+/// #[ownable]  // or #[multisig]
 /// #[upgradeable(no_migration)]
 /// pub struct MyContract;
 /// // No UpgradeableInternal impl needed!
@@ -424,6 +426,8 @@ pub fn contract_trait(attr: TokenStream, item: TokenStream) -> TokenStream {
 /// Generated code includes:
 /// - `upgrade(env, new_wasm_hash)` - Upgrades the contract WASM (auth required)
 /// - `migrate(env, migration_data)` - Runs migration after upgrade (auth required, XDR-decodes `Bytes` to `MigrationData`)
+/// - `freeze(env)` - Permanently freezes the contract, preventing any future upgrades (auth required, irreversible)
+/// - `is_frozen(env)` - Returns whether the contract is frozen (upgrades disabled)
 /// - `contractmeta!` with `binver` set to the Cargo package version (if not 0.0.0)
 #[proc_macro_attribute]
 pub fn upgradeable(attr: TokenStream, item: TokenStream) -> TokenStream {