@openzeppelin/ui-builder-adapter-stellar 0.16.0 → 1.1.0

package/README.md

@@ -32,6 +32,92 @@ The Builder application’s “Customize” step passes an `ExecutionConfig` to
 
 ---
 
+## Access Control Support
+
+The Stellar adapter includes first-class support for OpenZeppelin Access Control and Ownable contracts through a dedicated service module.
+
+### Features
+
+- **Feature Detection**: Automatically detects contracts implementing AccessControl, Ownable, or both
+- **Role Management**: Query current roles, grant/revoke roles, check permissions
+- **Ownership Management**: Transfer ownership, query current owner
+- **Dynamic Role Discovery**: Automatically discover role IDs via indexer when not explicitly provided
+- **Historical Queries**: View complete history of role changes and ownership transfers via SubQuery indexer
+- **Server-Side Filtering**: Filter events by contract, role, account, and limit (when indexer is available)
+
+### Role Discovery
+
+Since OpenZeppelin's Stellar contracts don't expose a `get_all_roles()` method, the adapter supports multiple ways to obtain role identifiers:
+
+#### 1. Explicit Role IDs (Recommended for known contracts)
+
+```typescript
+const service = adapter.getAccessControlService();
+service.registerContract(contractAddress, schema, ['admin', 'minter', 'burner']);
+```
+
+#### 2. Dynamic Discovery via Indexer
+
+If no role IDs are provided, the service automatically queries the indexer for historical `ROLE_GRANTED` and `ROLE_REVOKED` events:
+
+```typescript
+// Register without role IDs - discovery happens automatically
+service.registerContract(contractAddress, schema);
+
+// Or explicitly discover roles
+const roles = await service.discoverKnownRoleIds(contractAddress);
+// => ['admin', 'minter', 'burner']
+```
+
+#### 3. Adding Roles Manually
+
+For newly created roles that haven't been granted yet (no historical events), you can add them manually:
+
+```typescript
+// Add roles that may not exist in historical events
+service.addKnownRoleIds(contractAddress, ['new_role', 'another_role']);
+```
+
+Role IDs are validated against Soroban Symbol constraints:
+
+- Must start with a letter or underscore
+- Can contain only alphanumeric characters and underscores
+- Maximum 32 characters
+
+### Indexer Integration
+
+For historical queries (e.g., `getHistory()`), the adapter integrates with the [Stellar Access Control Indexer](https://github.com/OpenZeppelin/stellar-access-control-indexer), a SubQuery project that indexes Access Control and Ownable events.
+
+#### Configuring the Indexer
+
+Add `indexerUri` to your `StellarNetworkConfig`:
+
+```typescript
+const stellarTestnet: StellarNetworkConfig = {
+  // ... other config
+  indexerUri: 'https://api.subquery.network/sq/openzeppelin/stellar-access-control-indexer',
+};
+```
+
+#### Deployment
+
+The indexer is production-ready and compatible with:
+
+- **SubQuery Network** (decentralized, recommended for production)
+- Self-hosted infrastructure (Docker)
+
+For deployment instructions, see the [Indexer Deployment Guide](https://github.com/OpenZeppelin/stellar-access-control-indexer/blob/main/DEPLOYMENT.md).
+
+#### Graceful Degradation
+
+If no indexer is configured or the indexer is unavailable:
+
+- On-chain queries (roles, ownership) work normally
+- Historical queries return an empty array with a warning
+- UI remains functional for all current-state operations
+
+---
+
 ## Wallet Integration & UI
 
 All wallet integration logic, UI components, facade hooks, and the UI context provider for Stellar are located in `src/wallet/`.
@@ -53,6 +139,7 @@ This adapter follows the standard module structure outlined in the main project
 ```text
 adapter-stellar/
 ├── src/
+│   ├── access-control/          # Access Control & Ownable support (service, indexer)
 │   ├── configuration/           # Adapter-specific configuration (RPC, explorer, execution)
 │   ├── contract/                # Contract loading & metadata
 │   ├── mapping/                 # Soroban ↔ form field mapping & generators