Role Manager 🔐

Access control management interface for smart contracts. Visualize roles, permissions, and execute administrative actions across multiple blockchain ecosystems.

Project Status

This project is currently in development.

Table of Contents

• Supported Ecosystems & Networks
• Contract Types & Features
• Monorepo Structure
• Getting Started
  • Prerequisites
  • Installation
• Available Scripts
• Local development with openzeppelin-ui and openzeppelin-adapters
• Project Structure
• Tech Stack
• Code Style
• Commit Convention
• Contributing
• License

Supported Ecosystems & Networks

Role Manager supports smart contracts across three blockchain ecosystems via dedicated adapter packages.

EVM

23 networks (11 mainnet, 12 testnet) via @openzeppelin/adapter-evm.

Mainnet	Testnet
Ethereum	Sepolia
Arbitrum One	Arbitrum Sepolia
Base	Base Sepolia
Polygon	Polygon Amoy
Polygon zkEVM	Polygon zkEVM Cardona
BNB Smart Chain	BSC Testnet
OP Mainnet	OP Sepolia
Avalanche C-Chain	Avalanche Fuji
Linea	Linea Sepolia
Scroll	Scroll Sepolia
ZkSync Era	ZkSync Era Sepolia
	Monad Testnet

Stellar

2 networks (1 mainnet, 1 testnet) via @openzeppelin/adapter-stellar.

Mainnet	Testnet
Stellar Public Network	Stellar Testnet

Polkadot

5 networks (3 mainnet, 2 testnet) via @openzeppelin/adapter-polkadot.

Mainnet	Testnet
Polkadot Hub	Polkadot Hub Testnet
Moonbeam	Moonbase Alpha
Moonriver

Contract Types & Features

The application detects OpenZeppelin contract standards via ABI analysis and adapts its UI and available operations accordingly. Contracts can implement multiple standards simultaneously (e.g., AccessControl + AccessControlEnumerable).

Contract Types

Standard	Description
Ownable	Single-owner access control pattern
AccessControl	Role-based access control with granular permissions for multiple roles

Contract Features

These features layer on top of the core contract types to provide additional capabilities.

Feature	Standard	Description
Two-Step Ownership	Ownable2Step	Ownership transfers require the new owner to explicitly accept, preventing accidental transfers to wrong addresses
Two-Step Admin	AccessControlDefaultAdminRules	Admin transfers require acceptance after a configurable delay, adding a safety window before the change takes effect
Enumerable Roles	AccessControlEnumerable	Roles and their members can be enumerated on-chain
History	—	On-chain history of role changes is available via an indexer

Supported Operations

Operation	Ownable	AccessControl	Notes
Grant Role		✓	Assign a role to an account
Revoke Role		✓	Remove a role from an account
Renounce Role		✓	Self-revoke a role
Transfer Ownership	✓		Two-step when Ownable2Step is detected
Accept Ownership	✓		Ownable2Step only
Renounce Ownership	✓		Permanently removes the owner
Transfer Admin		✓	AccessControlDefaultAdminRules only, with configurable delay
Accept Admin Transfer		✓	AccessControlDefaultAdminRules only
Cancel Admin Transfer		✓	AccessControlDefaultAdminRules only
Change Admin Delay		✓	AccessControlDefaultAdminRules only, change is itself delayed
Rollback Admin Delay		✓	AccessControlDefaultAdminRules only
Export Snapshot	✓	✓	Download contract access control state as JSON

Monorepo Structure

This project is organized as a monorepo with the following packages:

• apps/role-manager: The main React application for managing smart contract roles.
• packages/components: Shared React UI components.
• packages/hooks: Shared React hooks for state management and business logic.

Getting Started

Prerequisites

• Node.js: v20+ (LTS recommended)
• pnpm: v10+ (corepack enable recommended)

Installation

1. Clone the repository:

   git clone https://github.com/OpenZeppelin/role-manager.git
   cd role-manager

2. Install dependencies:

   pnpm install

3. Build all packages:

   pnpm build

4. Start the development server:

   pnpm dev

5. Open your browser and navigate to http://localhost:5173

Available Scripts

Script	Description
pnpm dev	Start the development server (role-manager app)
pnpm dev:all	Start all packages in watch mode
pnpm build	Build all packages and apps
pnpm build:packages	Build only packages (components, hooks)
pnpm build:app	Build only the role-manager app
pnpm test	Run tests across all packages
pnpm test:all	Run all tests in parallel
pnpm test:coverage	Run tests with coverage reports
pnpm typecheck	Run TypeScript type checking
pnpm lint	Run ESLint across all packages
pnpm lint:fix	Fix ESLint issues
pnpm format	Format code with Prettier
pnpm format:check	Check formatting without changes
pnpm fix-all	Run Prettier then ESLint fix
pnpm commit	Create a commit using Commitizen
pnpm changeset	Create a changeset for versioning
pnpm clean	Clean build artifacts

Local development with openzeppelin-ui and openzeppelin-adapters

This project can consume packages from openzeppelin-ui (@openzeppelin/ui-*) and openzeppelin-adapters (@openzeppelin/adapter-*). See docs/LOCAL_DEVELOPMENT.md for clone layout, troubleshooting, and workflow details.

1. Enable local UI + adapter packages:

   pnpm dev:local

   This delegates to the published oz-ui-dev CLI, which builds and packs the configured families from your local checkouts before reinstalling Role Manager against those packed artifacts.

2. Enable only local UI packages:

   pnpm dev:uikit:local

3. Enable only local adapter packages:

   pnpm dev:adapters:local

4. Switch back to npm packages (before committing):

   pnpm dev:npm

5. Custom paths (optional):

   LOCAL_UI_PATH=/path/to/openzeppelin-ui LOCAL_ADAPTERS_PATH=/path/to/openzeppelin-adapters pnpm dev:local

Project Structure

role-manager/
├── apps/
│ └── role-manager/ # Main React application
│ ├── src/ # Application source code
│ ├── index.html # HTML entry point
│ ├── vite.config.ts # Vite configuration
│ └── package.json # App dependencies
├── packages/
│ ├── components/ # Shared UI components
│ │ ├── src/
│ │ ├── tsup.config.ts # Build configuration
│ │ └── package.json
│ └── hooks/ # Shared React hooks
│ ├── src/
│ ├── tsup.config.ts # Build configuration
│ └── package.json
├── scripts/ # Development helper scripts
├── specs/ # Feature specifications
├── test/ # Shared test setup
├── .changeset/ # Versioning configuration
├── .github/ # GitHub Actions workflows
├── .husky/ # Git hooks
├── package.json # Root workspace configuration
├── pnpm-workspace.yaml # PNPM workspace definition
├── tsconfig.base.json # Base TypeScript configuration
├── eslint.config.cjs # ESLint configuration
├── tailwind.config.cjs # Tailwind CSS configuration
└── vitest.shared.config.ts # Shared test configuration

Tech Stack

• React 19: Modern React with hooks and concurrent features
• TypeScript 5: Type-safe development
• Vite 7: Fast development server and build tool
• Tailwind CSS: Utility-first CSS framework
• Vitest: Fast unit testing framework
• tsup: TypeScript library bundler
• pnpm: Fast, disk-efficient package manager
• ESLint + Prettier: Code quality and formatting
• Husky + lint-staged: Git hooks for quality gates
• Commitlint: Conventional commit enforcement
• Changesets: Version management and changelogs

Code Style

Git Hooks

This project uses Husky to enforce code quality:

• pre-commit: Runs lint-staged (Prettier → ESLint)
• pre-push: Runs full lint and format check
• commit-msg: Enforces conventional commit format

Formatting

For consistent code formatting:

# Format and lint all files
pnpm fix-all

Commit Convention

This project follows Conventional Commits. Use the interactive commit tool:

pnpm commit

Examples:

feat(role-manager): add role visualization component
fix(hooks): resolve state update race condition
docs: update README with setup instructions
chore: update dependencies

Contributing

1. Create a feature branch from main
2. Make your changes following the code style guidelines
3. Write tests for new functionality
4. Create a changeset: pnpm changeset
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

This project uses @openzeppelin/ui-components for shared UI components.