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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openzeppelin/ui-builder-adapter-stellar",
-  "version": "0.16.0",
+  "version": "1.1.0",
   "description": "Stellar Adapter for UI Builder",
   "keywords": [
     "openzeppelin",
@@ -42,9 +42,9 @@
     "lossless-json": "^4.0.2",
     "lucide-react": "^0.510.0",
     "react-hook-form": "^7.62.0",
-    "@openzeppelin/ui-builder-types": "0.16.0",
-    "@openzeppelin/ui-builder-ui": "0.16.0",
-    "@openzeppelin/ui-builder-utils": "^0.16.0"
+    "@openzeppelin/ui-builder-types": "1.0.0",
+    "@openzeppelin/ui-builder-ui": "1.1.0",
+    "@openzeppelin/ui-builder-utils": "^1.1.0"
   },
   "devDependencies": {
     "@types/lodash": "^4.17.20",
@@ -79,6 +79,8 @@
     "lint:fix": "eslint . --fix",
     "lint:adapters": "node ../../lint-adapters.cjs",
     "test": "vitest run --passWithNoTests",
+    "test:unit": "vitest run --passWithNoTests --exclude '**/indexer-integration.test.ts'",
+    "test:integration": "vitest run --passWithNoTests test/access-control/indexer-integration.test.ts",
     "test:types": "vitest run src/contract/__tests__/complete-type-coverage.test.ts",
     "typecheck": "tsc --noEmit",
     "validate-stellar-types": "node scripts/check-stellar-sdk-types.js",

package/src/access-control/actions.ts

@@ -0,0 +1,214 @@
+/**
+ * Access Control Actions Module
+ *
+ * Assembles transaction data for access control operations (grant/revoke roles, transfer ownership)
+ * on Stellar (Soroban) contracts. These actions prepare transaction data that can be executed
+ * via the standard Stellar transaction execution flow.
+ */
+
+import { logger } from '@openzeppelin/ui-builder-utils';
+
+import type { StellarTransactionData } from '../transaction/formatter';
+
+/**
+ * Special placeholder value that gets replaced with the connected wallet address
+ * at transaction execution time. Used when the caller parameter should be the
+ * transaction sender (connected wallet).
+ *
+ * @see EoaExecutionStrategy - replaces this placeholder before building the transaction
+ * @see RelayerExecutionStrategy - also replaces this placeholder before building the transaction
+ */
+export const CALLER_PLACEHOLDER = '__CALLER__';
+
+/**
+ * Assembles transaction data for granting a role to an account
+ *
+ * Note: OpenZeppelin Stellar AccessControl (v0.5.x) requires a `caller` parameter for authorization.
+ * The caller is the address authorizing the role grant (must have admin privileges).
+ * Use CALLER_PLACEHOLDER to use the connected wallet address as the caller.
+ *
+ * @param contractAddress The contract address
+ * @param roleId The role identifier (Symbol)
+ * @param account The account address to grant the role to
+ * @param caller The address authorizing the grant (defaults to CALLER_PLACEHOLDER for connected wallet)
+ * @returns Transaction data ready for execution
+ */
+export function assembleGrantRoleAction(
+  contractAddress: string,
+  roleId: string,
+  account: string,
+  caller: string = CALLER_PLACEHOLDER
+): StellarTransactionData {
+  logger.info(
+    'assembleGrantRoleAction',
+    `Assembling grant_role action for ${roleId} to ${account} (caller: ${caller})`
+  );
+
+  // Arguments for grant_role(caller: Address, account: Address, role: Symbol) - v0.5.x signature
+  // Note: args are raw values that will be converted to ScVal by the transaction execution flow
+  // The caller parameter is required by OpenZeppelin Stellar AccessControl for authorization
+  return {
+    contractAddress,
+    functionName: 'grant_role',
+    args: [caller, account, roleId],
+    argTypes: ['Address', 'Address', 'Symbol'],
+    argSchema: undefined,
+    transactionOptions: {},
+  };
+}
+
+/**
+ * Assembles transaction data for revoking a role from an account
+ *
+ * Note: OpenZeppelin Stellar AccessControl (v0.5.x) requires a `caller` parameter for authorization.
+ * The caller is the address authorizing the role revocation (must have admin privileges).
+ * Use CALLER_PLACEHOLDER to use the connected wallet address as the caller.
+ *
+ * @param contractAddress The contract address
+ * @param roleId The role identifier (Symbol)
+ * @param account The account address to revoke the role from
+ * @param caller The address authorizing the revocation (defaults to CALLER_PLACEHOLDER for connected wallet)
+ * @returns Transaction data ready for execution
+ */
+export function assembleRevokeRoleAction(
+  contractAddress: string,
+  roleId: string,
+  account: string,
+  caller: string = CALLER_PLACEHOLDER
+): StellarTransactionData {
+  logger.info(
+    'assembleRevokeRoleAction',
+    `Assembling revoke_role action for ${roleId} from ${account} (caller: ${caller})`
+  );
+
+  // Arguments for revoke_role(caller: Address, account: Address, role: Symbol) - v0.5.x signature
+  // Note: args are raw values that will be converted to ScVal by the transaction execution flow
+  // The caller parameter is required by OpenZeppelin Stellar AccessControl for authorization
+  return {
+    contractAddress,
+    functionName: 'revoke_role',
+    args: [caller, account, roleId],
+    argTypes: ['Address', 'Address', 'Symbol'],
+    argSchema: undefined,
+    transactionOptions: {},
+  };
+}
+
+/**
+ * Assembles transaction data for transferring ownership of a contract
+ *
+ * For two-step Ownable contracts, this initiates a transfer that must be accepted
+ * by the pending owner before the expiration ledger.
+ *
+ * @param contractAddress The contract address
+ * @param newOwner The new owner address
+ * @param liveUntilLedger The ledger sequence by which the transfer must be accepted
+ * @returns Transaction data ready for execution
+ */
+export function assembleTransferOwnershipAction(
+  contractAddress: string,
+  newOwner: string,
+  liveUntilLedger: number
+): StellarTransactionData {
+  logger.info(
+    'assembleTransferOwnershipAction',
+    `Assembling transfer_ownership action to ${newOwner} with expiration at ledger ${liveUntilLedger}`
+  );
+
+  // Arguments for transfer_ownership(new_owner: Address, live_until_ledger: u32)
+  // Note: args are raw values that will be converted to ScVal by the transaction execution flow
+  return {
+    contractAddress,
+    functionName: 'transfer_ownership',
+    args: [newOwner, liveUntilLedger],
+    argTypes: ['Address', 'u32'],
+    argSchema: undefined,
+    transactionOptions: {},
+  };
+}
+
+/**
+ * Assembles transaction data for accepting a pending ownership transfer
+ *
+ * For two-step Ownable contracts, this completes a pending transfer initiated by
+ * the current owner. Must be called by the pending owner before the expiration ledger.
+ *
+ * @param contractAddress The contract address
+ * @returns Transaction data ready for execution
+ */
+export function assembleAcceptOwnershipAction(contractAddress: string): StellarTransactionData {
+  logger.info(
+    'assembleAcceptOwnershipAction',
+    `Assembling accept_ownership action for ${contractAddress}`
+  );
+
+  // accept_ownership() has no arguments - caller must be the pending owner
+  return {
+    contractAddress,
+    functionName: 'accept_ownership',
+    args: [],
+    argTypes: [],
+    argSchema: undefined,
+    transactionOptions: {},
+  };
+}
+
+/**
+ * Assembles transaction data for initiating an admin role transfer
+ *
+ * For two-step AccessControl contracts, this initiates an admin transfer that must
+ * be accepted by the pending admin before the expiration ledger.
+ *
+ * @param contractAddress The contract address
+ * @param newAdmin The new admin address
+ * @param liveUntilLedger The ledger sequence by which the transfer must be accepted
+ * @returns Transaction data ready for execution
+ */
+export function assembleTransferAdminRoleAction(
+  contractAddress: string,
+  newAdmin: string,
+  liveUntilLedger: number
+): StellarTransactionData {
+  logger.info(
+    'assembleTransferAdminRoleAction',
+    `Assembling transfer_admin_role action to ${newAdmin} with expiration at ledger ${liveUntilLedger}`
+  );
+
+  // Arguments for transfer_admin_role(new_admin: Address, live_until_ledger: u32)
+  // Note: args are raw values that will be converted to ScVal by the transaction execution flow
+  return {
+    contractAddress,
+    functionName: 'transfer_admin_role',
+    args: [newAdmin, liveUntilLedger],
+    argTypes: ['Address', 'u32'],
+    argSchema: undefined,
+    transactionOptions: {},
+  };
+}
+
+/**
+ * Assembles transaction data for accepting a pending admin transfer
+ *
+ * For two-step AccessControl contracts, this completes a pending admin transfer
+ * initiated by the current admin. Must be called by the pending admin before the
+ * expiration ledger.
+ *
+ * @param contractAddress The contract address
+ * @returns Transaction data ready for execution
+ */
+export function assembleAcceptAdminTransferAction(contractAddress: string): StellarTransactionData {
+  logger.info(
+    'assembleAcceptAdminTransferAction',
+    `Assembling accept_admin_transfer action for ${contractAddress}`
+  );
+
+  // accept_admin_transfer() has no arguments - caller must be the pending admin
+  return {
+    contractAddress,
+    functionName: 'accept_admin_transfer',
+    args: [],
+    argTypes: [],
+    argSchema: undefined,
+    transactionOptions: {},
+  };
+}

package/src/access-control/feature-detection.ts

@@ -0,0 +1,226 @@
+/**
+ * Feature Detection Module
+ *
+ * Detects access control capabilities of Stellar (Soroban) contracts by analyzing
+ * their function interfaces. Supports detection of Ownable and AccessControl patterns
+ * from OpenZeppelin Stellar Contracts.
+ */
+
+import type { AccessControlCapabilities, ContractSchema } from '@openzeppelin/ui-builder-types';
+import { UnsupportedContractFeatures } from '@openzeppelin/ui-builder-types';
+
+/**
+ * Known OpenZeppelin Ownable function signatures
+ */
+const OWNABLE_FUNCTIONS = {
+  required: ['get_owner'],
+  optional: ['transfer_ownership', 'accept_ownership', 'renounce_ownership'],
+} as const;
+
+/**
+ * Known OpenZeppelin AccessControl function signatures
+ */
+const ACCESS_CONTROL_FUNCTIONS = {
+  required: ['has_role', 'grant_role', 'revoke_role'],
+  optional: [
+    'get_role_admin',
+    'set_role_admin',
+    'get_admin',
+    'transfer_admin_role',
+    'accept_admin_transfer',
+    'renounce_admin',
+    'renounce_role',
+  ],
+} as const;
+
+/**
+ * Functions that indicate role enumeration support
+ */
+const ENUMERATION_FUNCTIONS = ['get_role_member_count', 'get_role_member'] as const;
+
+/**
+ * Detects access control capabilities of a Stellar contract
+ *
+ * @param contractSchema The contract schema to analyze
+ * @param indexerAvailable Whether an indexer is configured and available
+ * @returns Detected capabilities
+ */
+export function detectAccessControlCapabilities(
+  contractSchema: ContractSchema,
+  indexerAvailable = false
+): AccessControlCapabilities {
+  const functionNames = new Set(contractSchema.functions.map((fn) => fn.name));
+
+  // Detect Ownable
+  const hasOwnable = OWNABLE_FUNCTIONS.required.every((fnName) => functionNames.has(fnName));
+
+  // Detect two-step Ownable (has accept_ownership function)
+  const hasTwoStepOwnable = hasOwnable && functionNames.has('accept_ownership');
+
+  // Detect AccessControl
+  const hasAccessControl = ACCESS_CONTROL_FUNCTIONS.required.every((fnName) =>
+    functionNames.has(fnName)
+  );
+
+  // Detect two-step admin transfer (has accept_admin_transfer function)
+  const hasTwoStepAdmin = hasAccessControl && functionNames.has('accept_admin_transfer');
+
+  // Detect enumerable roles
+  const hasEnumerableRoles = ENUMERATION_FUNCTIONS.every((fnName) => functionNames.has(fnName));
+
+  // History is only available when indexer is configured
+  const supportsHistory = indexerAvailable;
+
+  // Verify the contract against OZ interfaces
+  const verifiedAgainstOZInterfaces = verifyOZInterface(
+    functionNames,
+    hasOwnable,
+    hasAccessControl,
+    hasTwoStepOwnable,
+    hasTwoStepAdmin
+  );
+
+  // Collect notes about detected capabilities
+  const notes: string[] = [];
+
+  if (hasOwnable) {
+    if (hasTwoStepOwnable) {
+      notes.push('OpenZeppelin two-step Ownable interface detected (with accept_ownership)');
+    } else {
+      notes.push('OpenZeppelin Ownable interface detected');
+    }
+  }
+
+  if (hasAccessControl) {
+    if (hasTwoStepAdmin) {
+      notes.push(
+        'OpenZeppelin two-step AccessControl interface detected (with accept_admin_transfer)'
+      );
+    } else {
+      notes.push('OpenZeppelin AccessControl interface detected');
+    }
+  }
+
+  if (hasEnumerableRoles) {
+    notes.push('Role enumeration supported (get_role_member_count, get_role_member)');
+  } else if (hasAccessControl) {
+    notes.push('Role enumeration not available - requires event reconstruction');
+  }
+
+  if (!indexerAvailable && (hasOwnable || hasAccessControl)) {
+    notes.push('History queries unavailable without indexer configuration');
+  }
+
+  if (!hasOwnable && !hasAccessControl) {
+    notes.push('No OpenZeppelin access control interfaces detected');
+  }
+
+  return {
+    hasOwnable,
+    hasTwoStepOwnable,
+    hasAccessControl,
+    hasTwoStepAdmin,
+    hasEnumerableRoles,
+    supportsHistory,
+    verifiedAgainstOZInterfaces,
+    notes: notes.length > 0 ? notes : undefined,
+  };
+}
+
+/**
+ * Verifies that the contract conforms to OpenZeppelin interfaces
+ *
+ * @param functionNames Set of function names in the contract
+ * @param hasOwnable Whether Ownable was detected
+ * @param hasAccessControl Whether AccessControl was detected
+ * @param hasTwoStepOwnable Whether two-step Ownable was detected
+ * @param hasTwoStepAdmin Whether two-step admin was detected
+ * @returns True if verified against OZ interfaces
+ */
+function verifyOZInterface(
+  functionNames: Set<string>,
+  hasOwnable: boolean,
+  hasAccessControl: boolean,
+  hasTwoStepOwnable = false,
+  hasTwoStepAdmin = false
+): boolean {
+  // If no OZ patterns detected, not applicable
+  if (!hasOwnable && !hasAccessControl) {
+    return false;
+  }
+
+  // Verify Ownable optional functions
+  // For two-step Ownable, require at least 3 of 4 optional functions
+  // For basic Ownable, at least 2 of 3 (excluding accept_ownership)
+  if (hasOwnable) {
+    const ownableOptionalCount = OWNABLE_FUNCTIONS.optional.filter((fnName) =>
+      functionNames.has(fnName)
+    ).length;
+
+    if (hasTwoStepOwnable) {
+      // Two-step Ownable should have at least 3 of 4 optional functions
+      // (transfer_ownership, accept_ownership, renounce_ownership, and accept_ownership is guaranteed)
+      if (ownableOptionalCount < 3) {
+        return false;
+      }
+    } else {
+      // Basic Ownable should have at least 2 of 3 optional functions
+      if (ownableOptionalCount < 2) {
+        return false;
+      }
+    }
+  }
+
+  // Verify AccessControl optional functions
+  // For two-step admin, require at least 5 of 7 optional functions
+  // For basic AccessControl, at least 4 of 7 should be present
+  if (hasAccessControl) {
+    const accessControlOptionalCount = ACCESS_CONTROL_FUNCTIONS.optional.filter((fnName) =>
+      functionNames.has(fnName)
+    ).length;
+
+    if (hasTwoStepAdmin) {
+      // Two-step admin should have at least 5 of 7 optional functions
+      // (transfer_admin_role, accept_admin_transfer guaranteed, plus others)
+      if (accessControlOptionalCount < 5) {
+        return false;
+      }
+    } else {
+      // Basic AccessControl should have at least 4 of 7 optional functions
+      if (accessControlOptionalCount < 4) {
+        return false;
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validates that a contract supports access control operations
+ *
+ * @param capabilities The detected capabilities
+ * @param contractAddress Optional contract address for error context
+ * @throws UnsupportedContractFeatures if contract doesn't support required operations
+ */
+export function validateAccessControlSupport(
+  capabilities: AccessControlCapabilities,
+  contractAddress?: string
+): asserts capabilities is
+  | (AccessControlCapabilities & { hasOwnable: true })
+  | (AccessControlCapabilities & { hasAccessControl: true }) {
+  if (!capabilities.hasOwnable && !capabilities.hasAccessControl) {
+    throw new UnsupportedContractFeatures(
+      'Contract does not implement OpenZeppelin Ownable or AccessControl interfaces',
+      contractAddress,
+      ['Ownable', 'AccessControl']
+    );
+  }
+
+  if (!capabilities.verifiedAgainstOZInterfaces) {
+    throw new UnsupportedContractFeatures(
+      'Contract interfaces do not conform to OpenZeppelin standards',
+      contractAddress
+    );
+  }
+}

package/src/access-control/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Access Control Module
+ *
+ * Exports access control functionality for Stellar (Soroban) contracts including
+ * capability detection, on-chain data reading, action assembly, validation, indexer client,
+ * and the AccessControlService.
+ *
+ * ## Two-Step Ownable Support
+ *
+ * This module provides full support for OpenZeppelin's two-step Ownable pattern:
+ * - {@link StellarAccessControlService.getOwnership} - Returns ownership state (owned/pending/expired/renounced)
+ * - {@link StellarAccessControlService.transferOwnership} - Initiates two-step transfer with expiration
+ * - {@link StellarAccessControlService.acceptOwnership} - Accepts pending ownership transfer
+ * - {@link getCurrentLedger} - Gets current ledger sequence for expiration calculation
+ * - {@link validateExpirationLedger} - Validates expiration ledger before submission
+ *
+ * ## Two-Step Admin Transfer Support
+ *
+ * This module provides full support for OpenZeppelin's two-step admin transfer pattern:
+ * - {@link StellarAccessControlService.getAdminInfo} - Returns admin state (active/pending/expired/renounced)
+ * - {@link StellarAccessControlService.transferAdminRole} - Initiates two-step admin transfer with expiration
+ * - {@link StellarAccessControlService.acceptAdminTransfer} - Accepts pending admin transfer
+ * - {@link AdminTransferInitiatedEvent} - Pending admin transfer event from indexer
+ *
+ * ## Action Assembly
+ *
+ * - {@link assembleGrantRoleAction} - Prepares grant_role transaction
+ * - {@link assembleRevokeRoleAction} - Prepares revoke_role transaction
+ * - {@link assembleTransferOwnershipAction} - Prepares transfer_ownership transaction with expiration
+ * - {@link assembleAcceptOwnershipAction} - Prepares accept_ownership transaction
+ * - {@link assembleTransferAdminRoleAction} - Prepares transfer_admin_role transaction with expiration
+ * - {@link assembleAcceptAdminTransferAction} - Prepares accept_admin_transfer transaction
+ *
+ * ## Feature Detection
+ *
+ * - {@link detectAccessControlCapabilities} - Detects Ownable/AccessControl support
+ * - `hasTwoStepOwnable` capability flag indicates two-step ownership transfer support
+ * - `hasTwoStepAdmin` capability flag indicates two-step admin transfer support
+ *
+ * ## Indexer Client
+ *
+ * - {@link StellarIndexerClient} - Queries historical events and pending transfers
+ * - {@link OwnershipTransferStartedEvent} - Pending ownership transfer event from indexer
+ * - {@link AdminTransferInitiatedEvent} - Pending admin transfer event from indexer
+ *
+ * @module access-control
+ */
+
+export * from './actions';
+export * from './feature-detection';
+export * from './indexer-client';
+export * from './onchain-reader';
+export * from './service';
+export * from './validation';