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//   - **System Roles**: Reserved system-role names (admin, devops, pool, etc.)
 25//     cannot be removed once registered. The constructor does not pre-populate
 26//     these role entries; callers register their addresses explicitly.
 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 with
 37//     `NewRBACWithAddress(addr)`, passing the intended owner explicitly.
 38//  2. **Role Registration**: Register roles using `RegisterRole(roleName, address)`.
 39//  3. **Authorization Check**: Verify if an address is authorized for a role using
 40//     `IsAuthorized(roleName, address)`.
 41//  4. **Role Management**: Update role addresses with `UpdateRoleAddress` or remove
 42//     non-system roles with `RemoveRole`.
 43//
 44// ## Example Usage
 45//
 46// The following example demonstrates how to use the RBAC package:
 47//
 48// ```gno
 49// package main
 50//
 51// import (
 52//
 53//	"gno.land/p/gnoswap/rbac/v1"
 54//
 55// )
 56//
 57//	func main() {
 58//	    // The owner is supplied explicitly; no constructor derives it from
 59//	    // an implicit origin caller.
 60//	    ownerAddr := address("g1...")
 61//	    manager := rbac.NewRBACWithAddress(ownerAddr)
 62//
 63//	    // Define example addresses
 64//	    adminAddr := address("g1...")
 65//	    userAddr  := address("g1...")
 66//
 67//	    // Register an "admin" role with adminAddr
 68//	    if err := manager.RegisterRole("admin", adminAddr); err != nil {
 69//	        panic(err)
 70//	    }
 71//
 72//	    // Register a custom "editor" role with userAddr
 73//	    if err := manager.RegisterRole("editor", userAddr); err != nil {
 74//	        panic(err)
 75//	    }
 76//
 77//	    // Check if adminAddr is authorized for the "admin" role
 78//	    if manager.IsAuthorized("admin", adminAddr) {
 79//	        println("Admin access granted")
 80//	    }
 81//
 82//	    // Check if userAddr is authorized for the "admin" role
 83//	    if !manager.IsAuthorized("admin", userAddr) {
 84//	        println("User does not have admin access")
 85//	    }
 86//
 87//	    // Update the editor role to a different address
 88//	    newEditorAddr := address("g1...")
 89//	    if err := manager.UpdateRoleAddress("editor", newEditorAddr); err != nil {
 90//	        panic(err)
 91//	    }
 92//
 93//	    // Get all role addresses
 94//	    allRoles := manager.GetAllRoleAddresses()
 95//	    for roleName, addr := range allRoles {
 96//	        println(roleName, "->", addr.String())
 97//	    }
 98//	}
 99//
100// ```
101//
102// ## System Roles
103//
104// The package reserves the following system-role names. A new RBAC manager
105// starts with no role entries, so callers must register each role and address
106// explicitly. Once registered, a system role cannot be removed:
107//
108//   - admin: System administrator role
109//   - devops: DevOps operations role
110//   - community_pool: Community pool management role
111//   - governance: Governance system role
112//   - gov_staker: Governance staker role
113//   - xgns: xGNS token role
114//   - pool: Pool management role
115//   - position: Position management role
116//   - router: Router role
117//   - staker: Staker role
118//   - emission: Emission management role
119//   - launchpad: Launchpad role
120//   - protocol_fee: Protocol fee management role
121//
122// ## Error Handling
123//
124// The package defines several error types:
125//
126//   - ErrRoleAlreadyExists: Attempting to register a role that already exists.
127//   - ErrRoleDoesNotExist: Attempting to access or modify a non-existent role.
128//   - ErrCannotRemoveSystemRole: Attempting to remove a registered system role.
129//   - ErrInvalidAddress: Providing an invalid address to UpdateRoleAddress or
130//     an ownership-transfer method. RegisterRole stores its supplied address
131//     without validating it.
132//   - ErrUnauthorized: Caller is not the owner when owner permission is required.
133//   - ErrNoPendingOwner: Attempting to accept ownership when no transfer is pending.
134//   - ErrPendingUnauthorized: Caller is not the pending owner when accepting ownership.
135//
136// ## Ownership Management
137//
138// The RBAC manager includes built-in two-step ownership transfer functionality:
139//
140//  1. Current owner calls TransferOwnershipBy to initiate transfer.
141//  2. New owner calls AcceptOwnershipBy to complete the transfer.
142//  3. Owner can drop ownership entirely using DropOwnershipBy.
143//
144// ## Limitations and Considerations
145//
146//   - Each role can only have one assigned address. For multi-address authorization,
147//     consider creating multiple roles or implementing a wrapper.
148//   - System roles are protected and cannot be removed to ensure system stability.
149//   - `RegisterRole` does not validate the supplied address. Address validation
150//     is performed by `UpdateRoleAddress` and ownership-transfer methods.
151//
152// Package rbac is intended for use in Gno smart contracts requiring simple,
153// address-based access control with role management capabilities.
154package rbac