RBAC

Role-based access control management realm.

Overview

RBAC realm manages role addresses and permissions for the GnoSwap protocol, integrating with the access package.

Configuration

• Admin/Governance Control: Role management by admin or governance
• Dynamic Roles: Add/remove at runtime
• Access Integration: Syncs with access package
• Owner-Managed Admin Role: admin role is bound to RBAC owner and cannot be updated via UpdateRoleAddress

Key Functions

RegisterRole(cur realm, roleName string, roleAddress address)

Registers new role in system. Only callable by admin or governance.

RemoveRole(cur realm, roleName string)

Removes existing role. Only callable by admin or governance. System roles cannot be removed.

UpdateRoleAddress(cur realm, roleName string, addr address)

Updates address for role. Only callable by admin or governance. The admin role is not updatable via this function and is managed through ownership transfer.

GetRoleAddress(roleName string) (address, error)

Returns address for role.

IsOwner(addr address) bool

Returns true if addr is the current owner.

IsPendingOwner(addr address) bool

Returns true if addr is the pending owner.

GetOwner() address

Returns the current owner address.

GetPendingOwner() address

Returns the pending owner address.

TransferOwnership(cur realm, newOwner address)

Initiates two-step ownership transfer. Only callable by current owner.

AcceptOwnership(cur realm)

Accepts pending ownership transfer. Only callable by pending owner. Also updates the admin role address and syncs it to the access package.

Usage

 1// Register new role (requires admin or governance)
 2RegisterRole(cross, "new_role", roleAddress)
 3
 4// Update role address
 5UpdateRoleAddress(cross, "staker", newAddress)
 6
 7// Admin role is updated via ownership transfer
 8TransferOwnership(cross, newAdmin)
 9AcceptOwnership(cross)
10
11// Get role address
12addr, err := GetRoleAddress("router")
13
14// Transfer ownership (two-step)
15TransferOwnership(cross, newAdmin)  // Step 1: Initiate
16AcceptOwnership(cross)               // Step 2: Accept (by newAdmin)

Contract Upgrade

RBAC enables seamless contract upgrades through role address updates. Versioned contracts (with paths like v1) can be upgraded by deploying new versions and updating role addresses.

Upgrade Process

1. Deploy new contract version (e.g., v2 contracts)
2. Update role addresses to point to new contracts
3. Verify distribution flows to new contract addresses

Upgradeable Components

All versioned contracts under gno.land/r/gnoswap/{version}/ are upgradeable:

• pool - Liquidity pool management
• position - Position management
• router - Swap routing engine
• staker - Staking and rewards
• governance - Governance system (governance, staker, xgns)
• launchpad - Token launch platform
• protocol_fee - Fee collection
• community_pool - Community treasury

Example: GNS Distribution Upgrade

 1// Before upgrade - GNS distributed to v1 contracts
 2mintAndDistribute() // → v1 staker, devops, community_pool
 3
 4// Upgrade process - update role addresses
 5rbac.UpdateRoleAddress("staker", newV2StakerAddr)
 6rbac.UpdateRoleAddress("devops", newV2DevOpsAddr)
 7rbac.UpdateRoleAddress("community_pool", newV2CommunityPoolAddr)
 8
 9// After upgrade - GNS distributed to v2 contracts
10mintAndDistribute() // → v2 staker, devops, community_pool

This approach ensures zero-downtime upgrades with atomic role address switches, maintaining protocol continuity while enabling feature updates and bug fixes.

Test Example

The upgrade mechanism is demonstrated in the test file: upgrade scenario test

 1// Test scenario steps:
 2// 1. Initialize emission and mint GNS to v1 contracts
 3// 2. Update role addresses to point to v2 contracts
 4// 3. Verify GNS now flows to v2 contracts
 5
 6func changeDistributionTarget() {
 7    // Update all role addresses atomically
 8    rbac.UpdateRoleAddress("staker", newStakerAddr)
 9    rbac.UpdateRoleAddress("gov_staker", newGovStakerAddr)
10    rbac.UpdateRoleAddress("devops", newDevOpsAddr)
11    rbac.UpdateRoleAddress("community_pool", newCommunityPoolAddr)
12}

The test validates that after role updates, GNS distribution switches from v1 to v2 contracts without any protocol downtime or loss of funds.

Security

• Admin-only role management
• Synchronized with access package
• Ownership transfer capability
• Role validation before updates