@openzeppelin/adapter-stellar 1.0.0

package/src/__tests__/getDefaultServiceConfig.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+
+import type { StellarNetworkConfig } from '@openzeppelin/ui-types';
+
+import { getStellarDefaultServiceConfig } from '../configuration/network-services';
+
+/**
+ * Tests for getStellarDefaultServiceConfig function.
+ *
+ * Note: We test the pure function directly instead of instantiating StellarAdapter
+ * to avoid loading heavy Stellar SDK dependencies (WASM modules, etc.) which can
+ * cause memory issues during test execution.
+ */
+describe('getStellarDefaultServiceConfig', () => {
+  const createMockNetworkConfig = (
+    overrides: Partial<StellarNetworkConfig> = {}
+  ): StellarNetworkConfig =>
+    ({
+      id: 'stellar-testnet',
+      exportConstName: 'stellarTestnet',
+      name: 'Stellar Testnet',
+      ecosystem: 'stellar',
+      network: 'testnet',
+      type: 'testnet',
+      isTestnet: true,
+      sorobanRpcUrl: 'https://soroban-testnet.stellar.org',
+      networkPassphrase: 'Test SDF Network ; September 2015',
+      ...overrides,
+    }) as StellarNetworkConfig;
+
+  describe('rpc service', () => {
+    it('should return RPC config when sorobanRpcUrl is present', () => {
+      const networkConfig = createMockNetworkConfig();
+
+      const result = getStellarDefaultServiceConfig(networkConfig, 'rpc');
+
+      expect(result).toEqual({
+        sorobanRpcUrl: 'https://soroban-testnet.stellar.org',
+      });
+    });
+
+    it('should return null when sorobanRpcUrl is missing', () => {
+      const networkConfig = createMockNetworkConfig({
+        sorobanRpcUrl: undefined,
+      });
+
+      const result = getStellarDefaultServiceConfig(networkConfig, 'rpc');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('access-control-indexer service', () => {
+    it('should return indexer config when both URLs are present', () => {
+      const networkConfig = createMockNetworkConfig({
+        indexerUri: 'https://indexer.stellar.example/graphql',
+        indexerWsUri: 'wss://indexer.stellar.example/graphql',
+      });
+
+      const result = getStellarDefaultServiceConfig(networkConfig, 'access-control-indexer');
+
+      expect(result).toEqual({
+        indexerUri: 'https://indexer.stellar.example/graphql',
+        indexerWsUri: 'wss://indexer.stellar.example/graphql',
+      });
+    });
+
+    it('should return null when indexerUri is missing', () => {
+      const networkConfig = createMockNetworkConfig({
+        indexerWsUri: 'wss://indexer.stellar.example/graphql',
+      });
+
+      const result = getStellarDefaultServiceConfig(networkConfig, 'access-control-indexer');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null when indexerWsUri is missing', () => {
+      const networkConfig = createMockNetworkConfig({
+        indexerUri: 'https://indexer.stellar.example/graphql',
+      });
+
+      const result = getStellarDefaultServiceConfig(networkConfig, 'access-control-indexer');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null when neither indexer URL is present', () => {
+      const networkConfig = createMockNetworkConfig();
+
+      const result = getStellarDefaultServiceConfig(networkConfig, 'access-control-indexer');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('unknown service', () => {
+    it('should return null for unknown service IDs', () => {
+      const networkConfig = createMockNetworkConfig();
+
+      expect(getStellarDefaultServiceConfig(networkConfig, 'explorer')).toBeNull();
+      expect(getStellarDefaultServiceConfig(networkConfig, 'unknown')).toBeNull();
+    });
+  });
+});

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-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,238 @@
+/**
+ * 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-types';
+import { UnsupportedContractFeatures } from '@openzeppelin/ui-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');
+  }
+
+  // ── Stellar-specific capability flags ──────────────────────────────
+  // Stellar contracts have renounce_ownership but NOT renounce_role (uses revoke_role for self)
+  // Stellar has no cancel-admin-transfer or admin-delay-management concepts
+  const hasRenounceOwnership = hasOwnable && functionNames.has('renounce_ownership');
+  const hasRenounceRole = false; // Stellar uses revokeRole for self-revocation
+  const hasCancelAdminTransfer = false; // Not supported on Stellar
+  const hasAdminDelayManagement = false; // Not supported on Stellar
+
+  return {
+    hasOwnable,
+    hasTwoStepOwnable,
+    hasAccessControl,
+    hasTwoStepAdmin,
+    hasEnumerableRoles,
+    supportsHistory,
+    verifiedAgainstOZInterfaces,
+    notes: notes.length > 0 ? notes : undefined,
+    hasRenounceOwnership,
+    hasRenounceRole,
+    hasCancelAdminTransfer,
+    hasAdminDelayManagement,
+  };
+}
+
+/**
+ * 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';