feat(adapter-stellar): add enriched role assignments with grant timestamps (#264)

Add getCurrentRolesEnriched() method that returns role assignments enriched
with metadata about when each member was granted their role. This combines
on-chain state with indexer history to provide timestamped permission data.

Changes:
- Add EnrichedRoleMember and EnrichedRoleAssignment types
- Add queryLatestGrants() to StellarIndexerClient for batch querying grants
- Add getCurrentRolesEnriched() to StellarAccessControlService
- Graceful degradation when indexer is unavailable (returns data without timestamps)
- Add comprehensive unit and integration tests

Author: pasevin

packages/adapter-stellar/src/access-control/indexer-client.ts

@@ -60,6 +60,18 @@ interface IndexerRoleDiscoveryResponse {
   }>;
 }
 
+/**
+ * Grant information for a specific member
+ */
+export interface GrantInfo {
+  /** ISO8601 timestamp of the grant */
+  timestamp: string;
+  /** Transaction ID of the grant */
+  txId: string;
+  /** Block/ledger number of the grant */
+  ledger: number;
+}
+
 /**
  * Options for querying history
  */
@@ -303,6 +315,117 @@ export class StellarIndexerClient {
     }
   }
 
+  /**
+   * Query the latest grant events for a set of members with a specific role
+   *
+   * Returns the most recent ROLE_GRANTED event for each member address.
+   * This is used to enrich role assignments with grant timestamps.
+   *
+   * @param contractAddress The contract address
+   * @param roleId The role identifier to query
+   * @param memberAddresses Array of member addresses to look up
+   * @returns Promise resolving to a Map of address -> GrantInfo
+   * @throws IndexerUnavailable if indexer is not available
+   * @throws OperationFailed if query fails
+   */
+  async queryLatestGrants(
+    contractAddress: string,
+    roleId: string,
+    memberAddresses: string[]
+  ): Promise<Map<string, GrantInfo>> {
+    if (memberAddresses.length === 0) {
+      return new Map();
+    }
+
+    const isAvailable = await this.checkAvailability();
+    if (!isAvailable) {
+      throw new IndexerUnavailable(
+        'Indexer not available for this network',
+        contractAddress,
+        this.networkConfig.id
+      );
+    }
+
+    const endpoints = this.resolveIndexerEndpoints();
+    if (!endpoints.http) {
+      throw new ConfigurationInvalid(
+        'No indexer HTTP endpoint configured',
+        contractAddress,
+        'indexer.http'
+      );
+    }
+
+    logger.debug(
+      LOG_SYSTEM,
+      `Querying latest grants for ${memberAddresses.length} member(s) with role ${roleId}`
+    );
+
+    const query = this.buildLatestGrantsQuery();
+    const variables = {
+      contract: contractAddress,
+      role: roleId,
+      accounts: memberAddresses,
+    };
+
+    try {
+      const response = await fetch(endpoints.http, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ query, variables }),
+      });
+
+      if (!response.ok) {
+        throw new OperationFailed(
+          `Indexer query failed with status ${response.status}`,
+          contractAddress,
+          'queryLatestGrants'
+        );
+      }
+
+      const result = (await response.json()) as IndexerHistoryResponse;
+
+      if (result.errors && result.errors.length > 0) {
+        const errorMessages = result.errors.map((e) => e.message).join('; ');
+        throw new OperationFailed(
+          `Indexer query errors: ${errorMessages}`,
+          contractAddress,
+          'queryLatestGrants'
+        );
+      }
+
+      if (!result.data?.accessControlEvents?.nodes) {
+        logger.debug(LOG_SYSTEM, `No grant events found for role ${roleId}`);
+        return new Map();
+      }
+
+      // Build map of address -> latest grant info
+      // Since we order by TIMESTAMP_DESC, we take the first occurrence per account
+      const grantMap = new Map<string, GrantInfo>();
+      for (const entry of result.data.accessControlEvents.nodes) {
+        if (!grantMap.has(entry.account)) {
+          grantMap.set(entry.account, {
+            timestamp: entry.timestamp,
+            txId: entry.txHash,
+            ledger: parseInt(entry.blockHeight, 10),
+          });
+        }
+      }
+
+      logger.debug(
+        LOG_SYSTEM,
+        `Found grant info for ${grantMap.size} of ${memberAddresses.length} member(s)`
+      );
+
+      return grantMap;
+    } catch (error) {
+      logger.error(
+        LOG_SYSTEM,
+        `Failed to query latest grants: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw error;
+    }
+  }
+
   /**
    * Resolve indexer endpoints with config precedence
    * Priority:
@@ -454,6 +577,34 @@ export class StellarIndexerClient {
     `;
   }
 
+  /**
+   * Build GraphQL query for latest grants
+   * Queries ROLE_GRANTED events for a specific role and set of accounts
+   * Ordered by timestamp descending so first occurrence per account is the latest
+   */
+  private buildLatestGrantsQuery(): string {
+    return `
+      query LatestGrants($contract: String!, $role: String!, $accounts: [String!]!) {
+        accessControlEvents(
+          filter: {
+            contract: { equalTo: $contract }
+            role: { equalTo: $role }
+            account: { in: $accounts }
+            type: { equalTo: ROLE_GRANTED }
+          }
+          orderBy: TIMESTAMP_DESC
+        ) {
+          nodes {
+            account
+            txHash
+            timestamp
+            blockHeight
+          }
+        }
+      }
+    `;
+  }
+
   /**
    * Transform indexer entries to standard HistoryEntry format
    */

packages/adapter-stellar/src/access-control/service.ts

@@ -10,6 +10,8 @@ import type {
   AccessControlService,
   AccessSnapshot,
   ContractSchema,
+  EnrichedRoleAssignment,
+  EnrichedRoleMember,
   ExecutionConfig,
   HistoryEntry,
   OperationResult,
@@ -255,6 +257,129 @@ export class StellarAccessControlService implements AccessControlService {
     return readCurrentRoles(contractAddress, roleIds, this.networkConfig);
   }
 
+  /**
+   * Gets current role assignments with enriched member information including grant timestamps
+   *
+   * This method returns role assignments with detailed metadata about when each member
+   * was granted the role. If the indexer is unavailable, it gracefully degrades to
+   * returning members without timestamp information.
+   *
+   * @param contractAddress The contract address
+   * @returns Promise resolving to array of enriched role assignments
+   * @throws ConfigurationInvalid if the contract address is invalid or contract not registered
+   */
+  async getCurrentRolesEnriched(contractAddress: string): Promise<EnrichedRoleAssignment[]> {
+    // Validate contract address
+    validateContractAddress(contractAddress);
+
+    logger.info(
+      'StellarAccessControlService.getCurrentRolesEnriched',
+      `Reading enriched roles for ${contractAddress}`
+    );
+
+    // First, get the current role assignments via on-chain queries
+    const currentRoles = await this.getCurrentRoles(contractAddress);
+
+    if (currentRoles.length === 0) {
+      return [];
+    }
+
+    // Check indexer availability for enrichment
+    const indexerAvailable = await this.indexerClient.checkAvailability();
+
+    if (!indexerAvailable) {
+      logger.debug(
+        'StellarAccessControlService.getCurrentRolesEnriched',
+        'Indexer not available, returning roles without timestamps'
+      );
+      // Graceful degradation: return enriched structure without timestamps
+      return this.convertToEnrichedWithoutTimestamps(currentRoles);
+    }
+
+    // Enrich each role with grant timestamps from the indexer
+    const enrichedAssignments: EnrichedRoleAssignment[] = [];
+
+    for (const roleAssignment of currentRoles) {
+      const enrichedMembers = await this.enrichMembersWithGrantInfo(
+        contractAddress,
+        roleAssignment.role.id,
+        roleAssignment.members
+      );
+
+      enrichedAssignments.push({
+        role: roleAssignment.role,
+        members: enrichedMembers,
+      });
+    }
+
+    logger.debug(
+      'StellarAccessControlService.getCurrentRolesEnriched',
+      `Enriched ${enrichedAssignments.length} role(s) with grant timestamps`
+    );
+
+    return enrichedAssignments;
+  }
+
+  /**
+   * Converts standard role assignments to enriched format without timestamps
+   * Used when indexer is unavailable (graceful degradation)
+   */
+  private convertToEnrichedWithoutTimestamps(
+    roleAssignments: RoleAssignment[]
+  ): EnrichedRoleAssignment[] {
+    return roleAssignments.map((assignment) => ({
+      role: assignment.role,
+      members: assignment.members.map((address) => ({
+        address,
+        // Timestamps are undefined when indexer is unavailable
+      })),
+    }));
+  }
+
+  /**
+   * Enriches member addresses with grant information from the indexer
+   */
+  private async enrichMembersWithGrantInfo(
+    contractAddress: string,
+    roleId: string,
+    memberAddresses: string[]
+  ): Promise<EnrichedRoleMember[]> {
+    if (memberAddresses.length === 0) {
+      return [];
+    }
+
+    try {
+      // Query indexer for grant information
+      const grantInfoMap = await this.indexerClient.queryLatestGrants(
+        contractAddress,
+        roleId,
+        memberAddresses
+      );
+
+      // Build enriched members, using grant info when available
+      return memberAddresses.map((address) => {
+        const grantInfo = grantInfoMap.get(address);
+        if (grantInfo) {
+          return {
+            address,
+            grantedAt: grantInfo.timestamp,
+            grantedTxId: grantInfo.txId,
+            grantedLedger: grantInfo.ledger,
+          };
+        }
+        // No grant info found (shouldn't happen for current members, but handle gracefully)
+        return { address };
+      });
+    } catch (error) {
+      logger.warn(
+        'StellarAccessControlService.enrichMembersWithGrantInfo',
+        `Failed to fetch grant info for role ${roleId}, returning members without timestamps: ${error instanceof Error ? error.message : String(error)}`
+      );
+      // Graceful degradation on error
+      return memberAddresses.map((address) => ({ address }));
+    }
+  }
+
   /**
    * Grants a role to an account
    *