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

package/src/access-control/validation.ts

@@ -0,0 +1,256 @@
+/**
+ * Address Validation Module for Access Control
+ *
+ * Centralizes address validation for access control operations.
+ * Uses Stellar-specific validation from the validation module and
+ * shared normalization utilities from @openzeppelin/ui-builder-utils.
+ */
+
+import { ConfigurationInvalid } from '@openzeppelin/ui-builder-types';
+import { normalizeAddress } from '@openzeppelin/ui-builder-utils';
+
+import { isValidAccountAddress, isValidContractAddress } from '../validation/address';
+
+/**
+ * Validates a Stellar contract address
+ *
+ * @param address The contract address to validate
+ * @param paramName Optional parameter name for error messages (defaults to 'contractAddress')
+ * @throws ConfigurationInvalid if the address is invalid
+ */
+export function validateContractAddress(address: string, paramName = 'contractAddress'): void {
+  if (!address || typeof address !== 'string' || address.trim() === '') {
+    throw new ConfigurationInvalid(
+      `${paramName} is required and must be a non-empty string`,
+      address,
+      paramName
+    );
+  }
+
+  if (!isValidContractAddress(address)) {
+    throw new ConfigurationInvalid(
+      `Invalid Stellar contract address: ${address}. Contract addresses must start with 'C' and be valid StrKey format.`,
+      address,
+      paramName
+    );
+  }
+}
+
+/**
+ * Validates a Stellar account address (for role grants, ownership transfers, etc.)
+ *
+ * @param address The account address to validate
+ * @param paramName Optional parameter name for error messages (defaults to 'account')
+ * @throws ConfigurationInvalid if the address is invalid
+ */
+export function validateAccountAddress(address: string, paramName = 'account'): void {
+  if (!address || typeof address !== 'string' || address.trim() === '') {
+    throw new ConfigurationInvalid(
+      `${paramName} is required and must be a non-empty string`,
+      address,
+      paramName
+    );
+  }
+
+  if (!isValidAccountAddress(address)) {
+    throw new ConfigurationInvalid(
+      `Invalid Stellar account address: ${address}. Account addresses must start with 'G' and be valid Ed25519 public keys.`,
+      address,
+      paramName
+    );
+  }
+}
+
+/**
+ * Validates a Stellar address that can be either an account or contract address
+ * (e.g., for ownership transfers where the new owner can be either type)
+ *
+ * @param address The address to validate (account or contract)
+ * @param paramName Optional parameter name for error messages (defaults to 'address')
+ * @throws ConfigurationInvalid if the address is invalid
+ */
+export function validateAddress(address: string, paramName = 'address'): void {
+  if (!address || typeof address !== 'string' || address.trim() === '') {
+    throw new ConfigurationInvalid(
+      `${paramName} is required and must be a non-empty string`,
+      address,
+      paramName
+    );
+  }
+
+  // Check if it's a valid account address OR contract address
+  if (!isValidAccountAddress(address) && !isValidContractAddress(address)) {
+    throw new ConfigurationInvalid(
+      `Invalid Stellar address: ${address}. Address must be a valid account address (starts with 'G') or contract address (starts with 'C').`,
+      address,
+      paramName
+    );
+  }
+}
+
+/**
+ * Validates both contract and account addresses for operations
+ *
+ * @param contractAddress The contract address
+ * @param accountAddress The account address
+ * @throws ConfigurationInvalid if either address is invalid
+ */
+export function validateAddresses(contractAddress: string, accountAddress: string): void {
+  validateContractAddress(contractAddress);
+  validateAccountAddress(accountAddress);
+}
+
+/**
+ * Normalizes a Stellar address using shared utils
+ * This is useful for case-insensitive and whitespace-insensitive comparison
+ *
+ * @param address The address to normalize
+ * @returns The normalized address
+ */
+export function normalizeStellarAddress(address: string): string {
+  return normalizeAddress(address);
+}
+
+/**
+ * Maximum length for a Soroban Symbol (role identifier)
+ * Soroban symbols are limited to 32 characters
+ */
+const MAX_ROLE_ID_LENGTH = 32;
+
+/**
+ * Valid pattern for Soroban Symbol characters
+ * Symbols can contain alphanumeric characters and underscores
+ */
+const VALID_ROLE_ID_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/**
+ * Validates a role identifier (Soroban Symbol)
+ *
+ * Role IDs must be:
+ * - Non-empty strings
+ * - Max 32 characters (Soroban Symbol limit)
+ * - Start with a letter or underscore
+ * - Contain only alphanumeric characters and underscores
+ *
+ * @param roleId The role identifier to validate
+ * @param paramName Optional parameter name for error messages
+ * @throws ConfigurationInvalid if the role ID is invalid
+ */
+export function validateRoleId(roleId: string, paramName = 'roleId'): void {
+  if (!roleId || typeof roleId !== 'string') {
+    throw new ConfigurationInvalid(
+      `${paramName} is required and must be a non-empty string`,
+      roleId,
+      paramName
+    );
+  }
+
+  const trimmed = roleId.trim();
+  if (trimmed === '') {
+    throw new ConfigurationInvalid(
+      `${paramName} cannot be empty or whitespace-only`,
+      roleId,
+      paramName
+    );
+  }
+
+  if (trimmed.length > MAX_ROLE_ID_LENGTH) {
+    throw new ConfigurationInvalid(
+      `${paramName} exceeds maximum length of ${MAX_ROLE_ID_LENGTH} characters: "${trimmed}" (${trimmed.length} chars)`,
+      roleId,
+      paramName
+    );
+  }
+
+  if (!VALID_ROLE_ID_PATTERN.test(trimmed)) {
+    throw new ConfigurationInvalid(
+      `${paramName} contains invalid characters: "${trimmed}". Role IDs must start with a letter or underscore and contain only alphanumeric characters and underscores.`,
+      roleId,
+      paramName
+    );
+  }
+}
+
+/**
+ * Validates an array of role identifiers
+ *
+ * @param roleIds The array of role identifiers to validate
+ * @param paramName Optional parameter name for error messages
+ * @throws ConfigurationInvalid if any role ID is invalid or if the array is invalid
+ * @returns The validated and deduplicated array of role IDs
+ */
+export function validateRoleIds(roleIds: string[], paramName = 'roleIds'): string[] {
+  if (!Array.isArray(roleIds)) {
+    throw new ConfigurationInvalid(`${paramName} must be an array`, String(roleIds), paramName);
+  }
+
+  // Validate each role ID
+  for (let i = 0; i < roleIds.length; i++) {
+    validateRoleId(roleIds[i], `${paramName}[${i}]`);
+  }
+
+  // Deduplicate and return
+  return [...new Set(roleIds.map((r) => r.trim()))];
+}
+
+/**
+ * Result of expiration ledger validation
+ *
+ * Returned by {@link validateExpirationLedger} to indicate whether
+ * a proposed expiration ledger is valid for a two-step ownership transfer.
+ *
+ * @example
+ * ```typescript
+ * const currentLedger = await getCurrentLedger(networkConfig);
+ * const result = validateExpirationLedger(expirationLedger, currentLedger);
+ * if (!result.valid) {
+ *   throw new ConfigurationInvalid(result.error!, String(expirationLedger), 'expirationLedger');
+ * }
+ * ```
+ */
+export interface ExpirationValidationResult {
+  /** Whether the expiration ledger is valid (must be strictly greater than current ledger) */
+  valid: boolean;
+  /** The current ledger sequence used for comparison */
+  currentLedger: number;
+  /** Human-readable error message if validation failed */
+  error?: string;
+}
+
+/**
+ * Validates an expiration ledger against the current ledger sequence
+ *
+ * For two-step Ownable contracts, the expiration ledger must be strictly greater
+ * than the current ledger (per FR-020: expirationLedger == currentLedger is invalid).
+ *
+ * @param expirationLedger The proposed expiration ledger sequence
+ * @param currentLedger The current ledger sequence number
+ * @returns Validation result with valid flag, currentLedger, and optional error message
+ *
+ * @example
+ * ```typescript
+ * const currentLedger = await getCurrentLedger(networkConfig);
+ * const result = validateExpirationLedger(expirationLedger, currentLedger);
+ * if (!result.valid) {
+ *   throw new ConfigurationInvalid(result.error, 'expirationLedger');
+ * }
+ * ```
+ */
+export function validateExpirationLedger(
+  expirationLedger: number,
+  currentLedger: number
+): ExpirationValidationResult {
+  // Per FR-020: expirationLedger must be strictly greater than currentLedger
+  if (expirationLedger <= currentLedger) {
+    return {
+      valid: false,
+      currentLedger,
+      error: `Expiration ledger ${expirationLedger} has already passed or equals current ledger. Current ledger is ${currentLedger}. Expiration must be strictly greater than current ledger.`,
+    };
+  }
+
+  return {
+    valid: true,
+    currentLedger,
+  };
+}

package/src/adapter.ts

@@ -1,6 +1,7 @@
 import type React from 'react';
 
 import type {
+  AccessControlService,
   AvailableUiKit,
   Connector,
   ContractAdapter,
@@ -28,6 +29,8 @@ import type {
 import { isStellarNetworkConfig } from '@openzeppelin/ui-builder-types';
 import { logger } from '@openzeppelin/ui-builder-utils';
 
+import { getCurrentLedger } from './access-control/onchain-reader';
+import { createStellarAccessControlService } from './access-control/service';
 import {
   getStellarNetworkServiceForms,
   testStellarNetworkServiceConnection,
@@ -83,6 +86,7 @@ import {
 export class StellarAdapter implements ContractAdapter {
   readonly networkConfig: StellarNetworkConfig;
   readonly initialAppServiceKitName: UiKitConfiguration['kitName'];
+  private readonly accessControlService: AccessControlService;
 
   constructor(networkConfig: StellarNetworkConfig) {
     if (!isStellarNetworkConfig(networkConfig)) {
@@ -90,6 +94,9 @@ export class StellarAdapter implements ContractAdapter {
     }
     this.networkConfig = networkConfig;
 
+    // Initialize Access Control Service
+    this.accessControlService = createStellarAccessControlService(networkConfig);
+
     // Set the network config in the wallet UI kit manager
     stellarUiKitManager.setNetworkConfig(networkConfig);
 
@@ -418,6 +425,13 @@ export class StellarAdapter implements ContractAdapter {
     return null;
   }
 
+  /**
+   * @inheritdoc
+   */
+  async getCurrentBlock(): Promise<number> {
+    return getCurrentLedger(this.networkConfig);
+  }
+
   /**
    * @inheritdoc
    */
@@ -615,6 +629,13 @@ export class StellarAdapter implements ContractAdapter {
       lastTransaction: 'Last Transaction',
     };
   }
+
+  /**
+   * @inheritdoc
+   */
+  public getAccessControlService(): AccessControlService {
+    return this.accessControlService;
+  }
 }
 
 // Also export as default to ensure compatibility with various import styles

package/src/configuration/network-services.ts

@@ -1,13 +1,17 @@
 import type { NetworkServiceForm, UserRpcProviderConfig } from '@openzeppelin/ui-builder-types';
+import { isValidUrl } from '@openzeppelin/ui-builder-utils';
 
 import { testStellarRpcConnection, validateStellarRpcEndpoint } from './rpc';
 
 /**
  * Returns the network service forms for Stellar networks.
- * Defines the UI configuration for the RPC service.
+ * Defines the UI configuration for the RPC and Indexer services.
+ *
+ * @param exclude Optional array of service IDs to exclude from the returned forms
+ * @returns Array of network service forms
  */
-export function getStellarNetworkServiceForms(): NetworkServiceForm[] {
-  return [
+export function getStellarNetworkServiceForms(exclude: string[] = []): NetworkServiceForm[] {
+  const forms: NetworkServiceForm[] = [
     {
       id: 'rpc',
       label: 'RPC Provider',
@@ -23,7 +27,37 @@ export function getStellarNetworkServiceForms(): NetworkServiceForm[] {
         },
       ],
     },
+    {
+      id: 'indexer',
+      label: 'Indexer',
+      description: 'Optional GraphQL indexer endpoint for historical access control data',
+      supportsConnectionTest: true,
+      fields: [
+        {
+          id: 'stellar-indexer-uri',
+          name: 'indexerUri',
+          type: 'text',
+          label: 'Indexer GraphQL HTTP Endpoint',
+          placeholder: 'https://indexer.example.com/graphql',
+          validation: { required: false, pattern: '^https?://.+' },
+          width: 'full',
+          helperText: 'Optional. Used for querying historical access control events.',
+        },
+        {
+          id: 'stellar-indexer-ws-uri',
+          name: 'indexerWsUri',
+          type: 'text',
+          label: 'Indexer GraphQL WebSocket Endpoint',
+          placeholder: 'wss://indexer.example.com/graphql',
+          validation: { required: false, pattern: '^wss?://.+' },
+          width: 'full',
+          helperText: 'Optional. Used for real-time subscriptions.',
+        },
+      ],
+    },
   ];
+
+  return forms.filter((form) => !exclude.includes(form.id));
 }
 
 /**
@@ -33,9 +67,37 @@ export async function validateStellarNetworkServiceConfig(
   serviceId: string,
   values: Record<string, unknown>
 ): Promise<boolean> {
-  if (serviceId !== 'rpc') return true;
-  const cfg = { url: String(values.sorobanRpcUrl || ''), isCustom: true } as UserRpcProviderConfig;
-  return validateStellarRpcEndpoint(cfg);
+  if (serviceId === 'rpc') {
+    const cfg = {
+      url: String(values.sorobanRpcUrl || ''),
+      isCustom: true,
+    } as UserRpcProviderConfig;
+    return validateStellarRpcEndpoint(cfg);
+  }
+
+  if (serviceId === 'indexer') {
+    // Validate indexerUri if provided
+    if (values.indexerUri !== undefined && values.indexerUri !== null && values.indexerUri !== '') {
+      if (!isValidUrl(String(values.indexerUri))) {
+        return false;
+      }
+    }
+
+    // Validate indexerWsUri if provided
+    if (
+      values.indexerWsUri !== undefined &&
+      values.indexerWsUri !== null &&
+      values.indexerWsUri !== ''
+    ) {
+      if (!isValidUrl(String(values.indexerWsUri))) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return true;
 }
 
 /**
@@ -45,7 +107,66 @@ export async function testStellarNetworkServiceConnection(
   serviceId: string,
   values: Record<string, unknown>
 ): Promise<{ success: boolean; latency?: number; error?: string }> {
-  if (serviceId !== 'rpc') return { success: true };
-  const cfg = { url: String(values.sorobanRpcUrl || ''), isCustom: true } as UserRpcProviderConfig;
-  return testStellarRpcConnection(cfg);
+  if (serviceId === 'rpc') {
+    const cfg = {
+      url: String(values.sorobanRpcUrl || ''),
+      isCustom: true,
+    } as UserRpcProviderConfig;
+    return testStellarRpcConnection(cfg);
+  }
+
+  if (serviceId === 'indexer') {
+    const indexerUri = values.indexerUri;
+
+    // If no indexer URI is provided, indexer is optional - return success (nothing to test)
+    if (!indexerUri || typeof indexerUri !== 'string' || indexerUri.trim() === '') {
+      return { success: true };
+    }
+
+    if (!isValidUrl(indexerUri)) {
+      return { success: false, error: 'Invalid indexer URI format' };
+    }
+
+    try {
+      const startTime = Date.now();
+      // Perform a simple GraphQL introspection query to test connectivity
+      const response = await fetch(indexerUri, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          query: '{ __typename }',
+        }),
+      });
+
+      const latency = Date.now() - startTime;
+
+      if (!response.ok) {
+        return {
+          success: false,
+          latency,
+          error: `HTTP ${response.status}: ${response.statusText}`,
+        };
+      }
+
+      const data = await response.json();
+      if (data.errors) {
+        return {
+          success: false,
+          latency,
+          error: `GraphQL errors: ${JSON.stringify(data.errors)}`,
+        };
+      }
+
+      return { success: true, latency };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  return { success: true };
 }

package/src/networks/mainnet.ts

@@ -16,4 +16,5 @@ export const stellarPublic: StellarNetworkConfig = {
   networkPassphrase: 'Public Global Stellar Network ; September 2015',
   explorerUrl: 'https://stellar.expert/explorer/public',
   iconComponent: NetworkStellar,
+  // indexerUri and indexerWsUri will be added here when stable mainnet indexer endpoints are available
 };

package/src/networks/testnet.ts

@@ -16,4 +16,5 @@ export const stellarTestnet: StellarNetworkConfig = {
   networkPassphrase: 'Test SDF Network ; September 2015',
   explorerUrl: 'https://stellar.expert/explorer/testnet',
   iconComponent: NetworkStellar,
+  // indexerUri and indexerWsUri will be added here when stable testnet indexer endpoints are available
 };

package/src/query/handler.ts

@@ -3,7 +3,6 @@ import {
   Address,
   BASE_FEE,
   Contract,
-  Keypair,
   nativeToScVal,
   rpc as StellarRpc,
   TransactionBuilder,
@@ -61,9 +60,12 @@ async function createSimulationTransaction(
 ): Promise<TransactionBuilder> {
   try {
     // Create a dummy source account for simulation
-    // We'll use a well-known testnet account for simulation
-    const dummyKeypair = Keypair.random();
-    const sourceAccount = new Account(dummyKeypair.publicKey(), '0');
+    // For simulations, we only need a valid public key - no private key required.
+    // Using a hardcoded test public key avoids Keypair.random() issues in test environments
+    // where @noble/curves crypto may not work correctly.
+    // This is a valid Stellar public key (the "zero" key derived from 32 zero bytes).
+    const SIMULATION_PUBLIC_KEY = 'GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF';
+    const sourceAccount = new Account(SIMULATION_PUBLIC_KEY, '0');
 
     // Create contract instance
     const contract = new Contract(contractAddress);

package/src/sac/xdr.ts

@@ -1,8 +1,7 @@
 import { xdr } from '@stellar/stellar-sdk';
+import stellarXdrJsonPackage from '@stellar/stellar-xdr-json/package.json' with { type: 'json' };
 import { parse, stringify } from 'lossless-json';
 
-import stellarXdrJsonPackage from '@stellar/stellar-xdr-json/package.json' assert { type: 'json' };
-
 import { logger } from '@openzeppelin/ui-builder-utils';
 
 /**

package/src/transaction/eoa.ts

@@ -14,6 +14,7 @@ import type {
 } from '@openzeppelin/ui-builder-types';
 import { logger, userRpcConfigService } from '@openzeppelin/ui-builder-utils';
 
+import { CALLER_PLACEHOLDER } from '../access-control/actions';
 import { valueToScVal } from '../transform/input-parser';
 import { getStellarWalletConnectionStatus, signTransaction } from '../wallet/connection';
 import { ExecutionStrategy } from './execution-strategy';
@@ -93,8 +94,14 @@ export class EoaExecutionStrategy implements ExecutionStrategy {
         networkPassphrase: stellarConfig.networkPassphrase,
       });
 
+      // Replace CALLER_PLACEHOLDER with the connected wallet address
+      // This supports OpenZeppelin Stellar access control functions that require a caller parameter
+      const resolvedArgs = txData.args.map((arg) =>
+        arg === CALLER_PLACEHOLDER ? connectedAddress : arg
+      );
+
       // Add the contract call operation (convert args to ScVal with comprehensive type support)
-      const scValArgs = txData.args.map((arg, index) => {
+      const scValArgs = resolvedArgs.map((arg, index) => {
         const argType = txData.argTypes[index];
         const argSchema = txData.argSchema?.[index]; // Pass schema for struct field type resolution
 

package/src/transaction/relayer.ts

@@ -27,6 +27,7 @@ import type {
 } from '@openzeppelin/ui-builder-types';
 import { logger } from '@openzeppelin/ui-builder-utils';
 
+import { CALLER_PLACEHOLDER } from '../access-control/actions';
 import { valueToScVal } from '../transform/input-parser';
 import { getStellarWalletConnectionStatus, signTransaction } from '../wallet/connection';
 import { ExecutionStrategy } from './execution-strategy';
@@ -371,7 +372,13 @@ export class RelayerExecutionStrategy implements ExecutionStrategy {
       networkPassphrase: stellarConfig.networkPassphrase,
     });
 
-    const scValArgs = txData.args.map((arg, index) => {
+    // Replace CALLER_PLACEHOLDER with the connected wallet address
+    // This supports OpenZeppelin Stellar access control functions that require a caller parameter
+    const resolvedArgs = txData.args.map((arg) =>
+      arg === CALLER_PLACEHOLDER ? connectedAddress : arg
+    );
+
+    const scValArgs = resolvedArgs.map((arg, index) => {
       const argType = txData.argTypes[index];
       const argSchema = txData.argSchema?.[index];
       return valueToScVal(arg, argType, argSchema);