@layerzerolabs/protocol-stellar-v2 0.2.83 → 0.2.85

package/docs/oapp-guide.md

@@ -75,6 +75,77 @@ The `init_ownable_oapp` function:
 2. Stores the LayerZero endpoint address
 3. Sets a delegate on the endpoint
 
+## Access control
+
+OApps use a two-layer authorization model. The `Auth` trait returns the contract's authorizer — the owner under `#[lz_contract]`, or the contract itself under `#[lz_contract(multisig)]`. On top of that, `RoleBasedAccessControl` adds OpenZeppelin-style role membership so administrative actions can be delegated without surrendering ownership. A vanilla `#[lz_contract] #[oapp]` contract exposes both layers automatically.
+
+### Custom roles
+
+Declare a role as a `&str` constant and gate methods with `#[only_role]` (role check + `require_auth`) or `#[has_role]` (role check only — use when the address has already been authenticated to avoid a duplicate `require_auth` panic):
+
+```rust
+use common_macros::only_role;
+
+pub const CONFIG_MANAGER_ROLE: &str = "CONFIG_MANAGER";
+
+#[contract_impl]
+impl MyOApp {
+    #[only_role(operator, CONFIG_MANAGER_ROLE)]
+    pub fn set_config(env: &Env, value: u64, operator: &Address) {
+        // operator must hold CONFIG_MANAGER_ROLE
+    }
+}
+```
+
+The role argument is expanded to `Symbol::new(env, ROLE)` internally.
+
+### Managing roles
+
+The standard RBAC entry points are auto-exposed by `#[oapp]`:
+
+```rust
+let role = Symbol::new(env, "CONFIG_MANAGER");
+
+oapp_client.grant_role(&account, &role, &caller);     // authorizer or role-admin
+oapp_client.revoke_role(&account, &role, &caller);    // authorizer or role-admin
+oapp_client.renounce_role(&role, &account);           // self only
+oapp_client.set_role_admin(&role, &admin_role);       // authorizer only
+oapp_client.remove_role_admin(&role);                 // authorizer only
+
+oapp_client.has_role(&account, &role);                // Option<u32>
+oapp_client.get_role_admin(&role);                    // Option<Symbol>
+oapp_client.get_role_member_count(&role);             // u32
+oapp_client.get_role_member(&role, index);            // Address — panics if out of bounds
+oapp_client.get_existing_roles();                     // Vec<Symbol>, capped at 256
+```
+
+Operations emit `RoleGranted`, `RoleRevoked`, and `RoleAdminChanged` events; failures surface as `RbacError` variants (`Unauthorized`, `RoleNotHeld`, `AdminRoleNotFound`, `MaxRolesExceeded`, etc.).
+
+### Constructor-time setup
+
+Constructors run before an authorizer is in scope, so use the `_no_auth` helpers to seed roles:
+
+```rust
+use utils::rbac::{grant_role_no_auth, set_role_admin_no_auth};
+
+#[contract_impl]
+impl MyOApp {
+    pub fn __constructor(
+        env: &Env,
+        owner: &Address,
+        endpoint: &Address,
+        delegate: &Address,
+        config_manager: &Address,
+    ) {
+        init_ownable_oapp::<Self>(env, owner, endpoint, delegate);
+
+        let role = Symbol::new(env, "CONFIG_MANAGER");
+        grant_role_no_auth(env, config_manager, &role, owner);
+        set_role_admin_no_auth(env, &role, &Symbol::new(env, "CONFIG_ADMIN"));
+    }
+}
+```
+
 ## Peer management
 
 Before sending or receiving messages, configure peers for each destination chain:
@@ -217,10 +288,11 @@ See `contracts/oapps/counter/` for a complete example demonstrating:
 
 ## Key traits summary
 
-| Trait                | Purpose                          | Default behavior                            |
-| -------------------- | -------------------------------- | ------------------------------------------- |
-| `OAppCore`           | Peer management, endpoint access | Stores endpoint, manages peers              |
-| `OAppSenderInternal` | Send cross-chain messages        | Handles fee payment and message dispatch    |
-| `OAppReceiver`       | Receive cross-chain messages     | Clears payload, delegates to `__lz_receive` |
-| `LzReceiveInternal`  | Application message handling     | **Must implement**                          |
-| `OAppOptionsType3`   | Enforced execution options       | No enforced options                         |
+| Trait                    | Purpose                          | Default behavior                                                |
+| ------------------------ | -------------------------------- | --------------------------------------------------------------- |
+| `OAppCore`               | Peer management, endpoint access | Stores endpoint, manages peers                                  |
+| `OAppSenderInternal`     | Send cross-chain messages        | Handles fee payment and message dispatch                        |
+| `OAppReceiver`           | Receive cross-chain messages     | Clears payload, delegates to `__lz_receive`                     |
+| `LzReceiveInternal`      | Application message handling     | **Must implement**                                              |
+| `OAppOptionsType3`       | Enforced execution options       | No enforced options                                             |
+| `RoleBasedAccessControl` | Role-based access control        | Provided automatically; manages role grants and admin hierarchy |

package/docs/oft-guide.md

@@ -69,6 +69,8 @@ impl OFTInternal for MyOFT {
 }
 ```
 
+When the underlying token is a Stellar Classic Asset wrapped as a SAC, you can route mints through the [SAC Manager](#sac-manager) instead of granting raw SAC admin authority to the OFT contract.
+
 ### LockUnlock
 
 Locks tokens in contract on send, unlocks on receive. Use for wrapping existing tokens (OFT Adapter pattern).
@@ -318,6 +320,79 @@ oft.set_rate_limit(
 let available = oft.rate_limit_capacity(&Direction::Outbound, 30101);
 ```
 
+## SAC Manager
+
+Wraps a Stellar Asset Contract (SAC) behind role-based admin so OFT MintBurn can mint without granting raw SAC admin authority to the OFT contract. Useful when the underlying token is a Stellar Classic Asset.
+
+The SAC Manager:
+
+- Becomes the admin of the underlying SAC
+- Exposes a `mint` entry point that the OFT calls during credit
+- Gates SAC admin operations (`mint`, `clawback`, `set_authorized`, `set_admin`) behind RBAC roles
+- Inherits ownership and role management from `Ownable` and `RoleBasedAccessControl`
+
+### Trust Model Requirement
+
+**The issuer account must be locked (master weight set to 0).** In Stellar classic assets, transfers from/to the issuer are equivalent to minting/burning. The issuer can always mint more tokens and perform other classic operations directly, even when an explicit admin (this contract) is set. If the issuer account is not locked, the RBAC model enforced by this contract can be bypassed, breaking the trust model.
+
+### Roles
+
+Four roles guard the wrapped admin operations. Roles are passed as `Symbol` values to `grant_role`:
+
+- `MINTER_ROLE`: authorizes `mint` (granted to the OFT contract for the credit path)
+- `CLAWBACK_ROLE`: authorizes `clawback`
+- `BLACKLISTER_ROLE`: authorizes `set_authorized`
+- `ADMIN_MANAGER_ROLE`: authorizes `set_admin`
+
+### Initialization
+
+Deploy the SAC Manager and grant `MINTER_ROLE` to the OFT contract:
+
+```rust
+use soroban_sdk::{Env, Address, Symbol};
+
+// Deploy the SAC Manager bound to the SAC and an owner
+let manager = env.register(SACManager, (&sac_token, &owner));
+let manager_client = SACManagerClient::new(&env, &manager);
+
+// Grant MINTER_ROLE to the OFT contract so it can mint on credit
+let minter_role = Symbol::new(&env, "MINTER_ROLE");
+manager_client.grant_role(&oft_address, &minter_role, &owner);
+
+// Make the manager the admin of the SAC
+sac_client.set_admin(&manager);
+```
+
+### SAC admin operations
+
+Each operation is gated by an `#[only_role(operator, ROLE)]` check. The `operator` argument must hold the role and authorize the call.
+
+```rust
+fn mint(env: &Env, to: &Address, amount: i128, operator: &Address);            // MINTER_ROLE
+fn clawback(env: &Env, from: &Address, amount: i128, operator: &Address);      // CLAWBACK_ROLE
+fn set_authorized(env: &Env, id: &Address, authorize: bool, operator: &Address); // BLACKLISTER_ROLE
+fn set_admin(env: &Env, new_admin: &Address, operator: &Address);              // ADMIN_MANAGER_ROLE
+```
+
+`mint` and `clawback` proxy to the SAC's corresponding admin functions. `clawback` additionally requires the SAC issuer to have the `ClawbackEnabled` flag set; `set_authorized` requires the `Revocable` flag.
+
+### Integrating with OFT MintBurn
+
+1. Deploy the SAC and lock its issuer (master weight = 0).
+2. Deploy the SAC Manager with the SAC address and owner.
+3. Make the SAC Manager the admin of the SAC via `sac_client.set_admin(&manager)`.
+4. Deploy the OFT in MintBurn mode, configured with the SAC as the token and the SAC Manager as the mint authority.
+5. Grant `MINTER_ROLE` on the SAC Manager to the OFT contract address.
+
+On send, the OFT burns directly on the SAC via SEP-41 `burn(sender, amount)` — this is signed by the sender and does not go through the SAC Manager. On receive, the OFT calls `manager.mint(to, amount, oft_address)`, which the SAC Manager forwards to the SAC.
+
+### Ownership and role management
+
+The SAC Manager inherits standard ownership and RBAC entry points:
+
+- `owner`, `pending_owner`, `transfer_ownership`, `begin_ownership_transfer`, `accept_ownership`
+- `grant_role`, `revoke_role`, `renounce_role`, `set_role_admin`, `remove_role_admin`
+
 ## Key traits summary
 
 | Trait         | Purpose                   | Exposed |

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@layerzerolabs/protocol-stellar-v2",
-  "version": "0.2.83",
+  "version": "0.2.85",
   "private": false,
   "license": "LZBL-1.3",
   "devDependencies": {
     "@types/node": "^22.18.6",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "@layerzerolabs/stellar-ts-bindings-gen": "0.2.83",
-    "@layerzerolabs/vm-tooling-stellar": "0.2.83",
-    "@layerzerolabs/common-node-utils": "0.2.83"
+    "@layerzerolabs/stellar-ts-bindings-gen": "0.2.85",
+    "@layerzerolabs/vm-tooling-stellar": "0.2.85",
+    "@layerzerolabs/common-node-utils": "0.2.85"
   },
   "publishConfig": {
     "access": "public",

package/sdk/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@layerzerolabs/lz-v2-stellar-sdk",
-    "version": "0.2.83",
+    "version": "0.2.85",
     "private": false,
     "description": "TypeScript SDK for endpoint-v2 Stellar contract",
     "repository": {