Contract-Level Role-Based Admin & Governance

[Cedarich]

Summary

Introduce a more robust admin/governance model for the VaultixEscrow contract so that operational responsibilities (treasury, pausing, dispute resolution) are not all tied to a single address. This improves security, flexibility, and maintainability as the protocol grows.

Background

Right now, the contract primarily relies on a single treasury /admin for:

• Fee configuration

• Emergency pausing

• Potential dispute resolution logic
  As the protocol matures, we need clearer separation of concerns:

• A treasury that receives platform fees

• An operator/admin that can pause/resume the contract

• An arbitrator that can resolve disputes
  This also sets us up for future governance (multisig/DAO) without rewriting core logic.

Scope

Contract-level only, focused on lib.rs .

Requirements

• Introduce distinct roles (e.g.):
  • treasury (existing): receives fees
  • operator (new): can call set_paused , update fee parameters
  • arbitrator (new): can resolve disputes (where applicable)
• Store these roles in contract instance storage with clear keys.
• Add initialization/upgrade paths:
  • initialize_roles(env, operator: Address, arbitrator: Address) (or extend existing initialize safely).
  • Guard against re-initialization ( AlreadyInitialized -style error where appropriate).
• Update existing functions to use the correct role:
  • set_paused should require operator auth instead of (or in addition to) treasury.
  • Any dispute resolution-related functions should require arbitrator auth.
  • Fee updates should be restricted to operator or treasury as per design.
• Emit events when roles are set or updated (e.g. RoleUpdated(role, old, new) ).
• Ensure ContractPaused logic keeps working with the new role model.

Non-Goals

• On-chain DAO or multisig implementation.
• Off-chain governance UI.

Acceptance Criteria

• Clear role separation implemented and enforced via require_auth() checks.
• All role addresses persisted and retrievable via read-only getters.
• Events emitted on role changes with a consistent schema.
• Existing tests still pass.
• New tests cover:
  • Unauthorized addresses attempting admin/arb operations.
  • Happy-path flows for each role (treasury, operator, arbitrator).
  • Re-initialization attempts rejected where appropriate.

Testing

• Add/extend unit tests under test.rs to cover:
  • Correct role assignment during initialization.
  • Role-based access control for pausing, fee updates, and dispute resolution.
  • Negative tests for unauthorized callers.

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 200 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[AbuJulaybeeb]

@AbuJulaybeeb has applied to work on this issue as part of the Stellar Wave Program's 2nd wave.

Hi maintainer,
can i take on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @AbuJulaybeeb to this issue.

[bamiebot-maker]

@bamiebot-maker has applied to work on this issue as part of the Stellar Wave Program's 2nd wave.

hi i would love to work on this issues

ℹ️ Repo Maintainers: To accept this application, review their application or assign @bamiebot-maker to this issue.

[yusstyle]

@yusstyle has applied to work on this issue as part of the Stellar Wave Program's 2nd wave.

Hello, I’m very interested in this role separation and governance improvement task for the VaultixEscrow contract.
I’m confident I can implement distinct roles (treasury, operator, arbitrator), persist them securely in contract storage, enforce access control using require_auth(), emit consistent RoleUpdated events, and extend unit tests to cover both authorized and unauthorized flows.
I would be glad to apply and provide a clean, well-tested implementation in lib.rs and test.rs.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @yusstyle to this issue.

[drips-wave]

Congratulations, @AbuJulaybeeb! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on February 26, 2026.

🧑‍💻 @AbuJulaybeeb: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are issued when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊