doc.gno

  1// Package rbac provides a simple address-based Role-Based Access Control (RBAC)
  2// system for Gno smart contracts. It enables dynamic registration, update, and removal
  3// of roles with assigned addresses.
  4//
  5// ## Overview
  6//
  7// The RBAC package provides a manager that maintains an internal registry of roles.
  8// Each role is identified by a unique name and is associated with a single address.
  9// Authorization is performed by checking if a given address matches the role's assigned address.
 10//
 11// Key components of this package include:
 12//
 13//  1. **Role**: Represents a role with a name and an assigned address.
 14//  2. **RBAC Manager**: The core type (RBAC) that manages role registration, address
 15//     assignment, authorization verification, and role removal.
 16//  3. **Ownable2Step**: Provides two-step ownership transfer functionality integrated
 17//     into the RBAC manager.
 18//
 19// ## Key Features
 20//
 21//   - **Dynamic Role Management**: Roles can be registered, updated, and removed at runtime
 22//     without requiring contract redeployment.
 23//   - **Address-Based Authorization**: Each role is associated with a single address,
 24//     and authorization is verified by address matching.
 25//   - **System Roles**: Predefined system roles (admin, devops, pool, etc.) that cannot
 26//     be removed to ensure system integrity.
 27//   - **Two-Step Ownership Transfer**: Built-in secure ownership transfer mechanism
 28//     requiring explicit acceptance by the new owner.
 29//   - **Encapsulation**: Internal state (roles registry) is encapsulated within the RBAC
 30//     manager, preventing unintended external modifications.
 31//
 32// ## Workflow
 33//
 34// Typical usage of the RBAC package includes the following steps:
 35//
 36//  1. **Initialization**: Create a new RBAC manager using `New()` or `NewRBACWithAddress(addr)`.
 37//  2. **Role Registration**: Register roles using `RegisterRole(roleName, address)`.
 38//  3. **Authorization Check**: Verify if an address is authorized for a role using
 39//     `IsAuthorized(roleName, address)`.
 40//  4. **Role Management**: Update role addresses with `UpdateRoleAddress` or remove
 41//     non-system roles with `RemoveRole`.
 42//
 43// ## Example Usage
 44//
 45// The following example demonstrates how to use the RBAC package:
 46//
 47// ```gno
 48// package main
 49//
 50// import (
 51//	"gno.land/p/gnoswap/rbac"
 52//
 53// )
 54//
 55//	func main() {
 56//	    // Create a new RBAC manager (origin caller becomes owner)
 57//	    manager := rbac.New()
 58//
 59//	    // Define example addresses
 60//	    adminAddr := address("g1...")
 61//	    userAddr  := address("g1...")
 62//
 63//	    // Register an "admin" role with adminAddr
 64//	    if err := manager.RegisterRole("admin", adminAddr); err != nil {
 65//	        panic(err)
 66//	    }
 67//
 68//	    // Register a custom "editor" role with userAddr
 69//	    if err := manager.RegisterRole("editor", userAddr); err != nil {
 70//	        panic(err)
 71//	    }
 72//
 73//	    // Check if adminAddr is authorized for the "admin" role
 74//	    if manager.IsAuthorized("admin", adminAddr) {
 75//	        println("Admin access granted")
 76//	    }
 77//
 78//	    // Check if userAddr is authorized for the "admin" role
 79//	    if !manager.IsAuthorized("admin", userAddr) {
 80//	        println("User does not have admin access")
 81//	    }
 82//
 83//	    // Update the editor role to a different address
 84//	    newEditorAddr := address("g1...")
 85//	    if err := manager.UpdateRoleAddress("editor", newEditorAddr); err != nil {
 86//	        panic(err)
 87//	    }
 88//
 89//	    // Get all role addresses
 90//	    allRoles := manager.GetAllRoleAddresses()
 91//	    for roleName, addr := range allRoles {
 92//	        println(roleName, "->", addr.String())
 93//	    }
 94//	}
 95//
 96// ```
 97//
 98// ## System Roles
 99//
100// The package defines several system roles that cannot be removed:
101//
102//   - admin: System administrator role
103//   - devops: DevOps operations role
104//   - community_pool: Community pool management role
105//   - governance: Governance system role
106//   - gov_staker: Governance staker role
107//   - xgns: xGNS token role
108//   - pool: Pool management role
109//   - position: Position management role
110//   - router: Router role
111//   - staker: Staker role
112//   - emission: Emission management role
113//   - launchpad: Launchpad role
114//   - protocol_fee: Protocol fee management role
115//
116// ## Error Handling
117//
118// The package defines several error types:
119//
120// - ErrRoleAlreadyExists: Attempting to register a role that already exists.
121// - ErrRoleDoesNotExist: Attempting to access or modify a non-existent role.
122// - ErrCannotRemoveSystemRole: Attempting to remove a system role.
123// - ErrInvalidAddress: Providing an invalid or empty address.
124// - ErrUnauthorized: Caller is not the owner when owner permission is required.
125// - ErrNoPendingOwner: Attempting to accept ownership when no transfer is pending.
126// - ErrPendingUnauthorized: Caller is not the pending owner when accepting ownership.
127//
128// ## Ownership Management
129//
130// The RBAC manager includes built-in two-step ownership transfer functionality:
131//
132//  1. Current owner calls TransferOwnershipBy to initiate transfer.
133//  2. New owner calls AcceptOwnershipBy to complete the transfer.
134//  3. Owner can drop ownership entirely using DropOwnershipBy.
135//
136// ## Limitations and Considerations
137//
138//   - Each role can only have one assigned address. For multi-address authorization,
139//     consider creating multiple roles or implementing a wrapper.
140//   - System roles are protected and cannot be removed to ensure system stability.
141//   - Address validation checks for empty strings and calls IsValid() method.
142//
143// Package rbac is intended for use in Gno smart contracts requiring simple,
144// address-based access control with role management capabilities.
145package rbac