feat(adapter-stellar): add two-step Ownable support with ledger-based expiration (#271)

* docs(spec): add Stellar Ownable two-step transfer specification

Complete feature specification for extending the Stellar Access Control
module to support OpenZeppelin Ownable two-step ownership transfer with
ledger-based expiration.

Includes:
- spec.md: 23 functional requirements, 6 NFRs, 4 user stories
- plan.md: implementation approach and architecture decisions
- tasks.md: 64 implementation tasks organized by user story
- research.md: Phase 0 research findings
- data-model.md: entity definitions and relationships
- contracts/: TypeScript interface definitions
- quickstart.md: integration guide
- checklists/: requirements quality validation

* feat(adapter-stellar): add two-step Ownable foundation (Phase 1 & 2)

Add foundational infrastructure for Stellar Ownable two-step ownership
transfer with ledger-based expiration support.

Types (chain-agnostic):
- Add OwnershipState type ('owned' | 'pending' | 'expired' | 'renounced')
- Add PendingOwnershipTransfer interface with expirationBlock
- Extend OwnershipInfo with optional state and pendingTransfer
- Add hasTwoStepOwnable flag to AccessControlCapabilities

Adapter-stellar:
- Add getCurrentLedger() to query current ledger via Soroban RPC
- Add OWNERSHIP_TRANSFER_INITIATED event type to indexer client
- Add queryPendingOwnershipTransfer() method to detect pending transfers
- Add validateExpirationLedger() helper for client-side validation
- Update feature detection to identify two-step Ownable contracts

* feat(adapter-stellar): implement ownership status viewing (Phase 3)

Implement User Story 1 - View Contract Ownership Status with:

- Add getOwnership() method with full state determination (owned/pending/expired/renounced)
- Add readPendingOwner() on-chain query for expiration data (liveUntilLedger)
- Add getCurrentLedger() for expiration calculations
- Update indexer client to use OWNERSHIP_TRANSFER_STARTED event type
- Hybrid data sourcing: indexer for event detection, on-chain for expiration
- Add comprehensive unit tests (T015-T027) and integration tests
- Update spec files with indexer schema discovery notes

Note: Indexer does not store live_until_ledger, so expiration is queried
on-chain via get_pending_owner() contract method.

* feat(adapter-stellar): implement two-step ownership transfer initiation (Phase 4)

Add support for initiating two-step ownership transfers with expiration:
- Update assembleTransferOwnershipAction() to include live_until_ledger parameter
- Update transferOwnership() to require expirationLedger with client-side validation
- Add boundary condition check (expirationLedger == currentLedger is invalid per FR-020)
- Add specific error messages per FR-018
- Add INFO logging for transfer initiation per NFR-004
- Update AccessControlService interface for two-step transfer support

* feat(adapter-stellar): implement ownership acceptance (Phase 5)

Add acceptOwnership() method to complete the two-step ownership transfer flow.
Pending owners can now accept transfers before expiration.

- Add assembleAcceptOwnershipAction() in actions.ts
- Add acceptOwnership() method in service.ts with INFO logging
- Add comprehensive tests for acceptance flow (T039-T048)
- Mark Phase 5 tasks complete in tasks.md

* chore: rename spec from 001 to 006-stellar-ownable-support

Fix spec numbering to follow existing sequence (001-005 already used).
Rename directory and update all internal references.

* docs(spec): mark Phase 6 feature detection tasks complete

Phase 6 (User Story 4: Detect Ownable Contract Features) was already
implemented. Verified all tests pass and marked tasks T049-T056 complete.

* fix(adapter-stellar): add blockHeight to ownership transfer query

The GraphQL query for OWNERSHIP_TRANSFER_STARTED was missing the
blockHeight field, causing the fallback logic at line 609 to fail.
When ledger was falsy, parseInt(undefined, 10) returned NaN.

* feat(adapter-stellar): complete Phase 7 polish for two-step Ownable support

Phase 7 Polish & Cross-Cutting Concerns:
- Enhanced module-level JSDoc in index.ts with two-step Ownable documentation
- Added @example sections to service methods (getOwnership, transferOwnership, acceptOwnership)
- Added integration tests for full two-step transfer workflow
- Added edge case tests (boundary conditions, network errors)
- Added performance benchmark tests (NFR-001/NFR-002/NFR-003)
- Created changeset for minor version bump

Bug Fixes:
- Fixed missing admin field validation in queryPendingOwnershipTransfer
  (returns null instead of invalid OwnershipTransferStartedEvent with empty previousOwner)
- Fixed missing GraphQL error check for completion query response
  (now throws OperationFailed instead of silently treating errors as no completion)

Documentation:
- Updated quickstart.md with correct field names and imports
- Marked all Phase 7 tasks complete in tasks.md

* fix(adapter-stellar): remove redundant null check in readPendingOwner

Author: pasevin

.changeset/stellar-ownable-two-step-support.md

@@ -0,0 +1,35 @@
+---
+'@openzeppelin/ui-builder-adapter-stellar': minor
+'@openzeppelin/ui-builder-types': minor
+---
+
+feat(adapter-stellar): add two-step Ownable support with ledger-based expiration
+
+Implements OpenZeppelin Stellar Ownable two-step ownership transfer pattern:
+
+**New Features:**
+
+- `getOwnership()` now returns ownership state (owned/pending/expired/renounced) with pending transfer details
+- `transferOwnership()` supports expiration ledger parameter for two-step transfers
+- `acceptOwnership()` allows pending owners to complete ownership transfer
+- `getCurrentLedger()` helper to get current ledger sequence for expiration calculation
+- `validateExpirationLedger()` validation helper for client-side expiration checks
+- `hasTwoStepOwnable` capability flag in feature detection
+
+**Type Extensions:**
+
+- Added `OwnershipState` type for ownership states
+- Added `PendingOwnershipTransfer` interface for pending transfer details
+- Extended `OwnershipInfo` with `state` and `pendingTransfer` fields
+- Extended `AccessControlCapabilities` with `hasTwoStepOwnable` flag
+
+**Indexer Integration:**
+
+- Added `OWNERSHIP_TRANSFER_STARTED` event type support
+- Added `queryPendingOwnershipTransfer()` method to indexer client
+- Graceful degradation when indexer is unavailable
+
+**Non-Functional:**
+
+- Performance: Ownership queries < 3s, indexer queries < 1s, ledger queries < 500ms
+- Logging: INFO for ownership operations, WARN for indexer unavailability

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

@@ -73,26 +73,57 @@ export function assembleRevokeRoleAction(
 /**
  * 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
+  newOwner: string,
+  liveUntilLedger: number
 ): StellarTransactionData {
   logger.info(
     'assembleTransferOwnershipAction',
-    `Assembling transfer_ownership action to ${newOwner}`
+    `Assembling transfer_ownership action to ${newOwner} with expiration at ledger ${liveUntilLedger}`
   );
 
-  // Arguments for transfer_ownership(new_owner: Address)
+  // 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],
-    argTypes: ['Address'],
+    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: {},
   };

packages/adapter-stellar/src/access-control/feature-detection.ts

@@ -54,6 +54,9 @@ export function detectAccessControlCapabilities(
   // 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)
@@ -69,14 +72,19 @@ export function detectAccessControlCapabilities(
   const verifiedAgainstOZInterfaces = verifyOZInterface(
     functionNames,
     hasOwnable,
-    hasAccessControl
+    hasAccessControl,
+    hasTwoStepOwnable
   );
 
   // Collect notes about detected capabilities
   const notes: string[] = [];
 
   if (hasOwnable) {
-    notes.push('OpenZeppelin Ownable interface detected');
+    if (hasTwoStepOwnable) {
+      notes.push('OpenZeppelin two-step Ownable interface detected (with accept_ownership)');
+    } else {
+      notes.push('OpenZeppelin Ownable interface detected');
+    }
   }
 
   if (hasAccessControl) {
@@ -99,6 +107,7 @@ export function detectAccessControlCapabilities(
 
   return {
     hasOwnable,
+    hasTwoStepOwnable,
     hasAccessControl,
     hasEnumerableRoles,
     supportsHistory,
@@ -113,26 +122,39 @@ export function detectAccessControlCapabilities(
  * @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
  * @returns True if verified against OZ interfaces
  */
 function verifyOZInterface(
   functionNames: Set<string>,
   hasOwnable: boolean,
-  hasAccessControl: boolean
+  hasAccessControl: boolean,
+  hasTwoStepOwnable = false
 ): boolean {
   // If no OZ patterns detected, not applicable
   if (!hasOwnable && !hasAccessControl) {
     return false;
   }
 
-  // Verify Ownable optional functions (at least 2 of 3 should be present)
+  // 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 (ownableOptionalCount < 2) {
-      return false;
+    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;
+      }
     }
   }
 

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

@@ -4,6 +4,35 @@
  * 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
+ * - {@link readPendingOwner} - Reads pending owner info from on-chain state
+ *
+ * ## 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
+ *
+ * ## Feature Detection
+ *
+ * - {@link detectAccessControlCapabilities} - Detects Ownable/AccessControl support
+ * - `hasTwoStepOwnable` capability flag indicates two-step transfer support
+ *
+ * ## Indexer Client
+ *
+ * - {@link StellarIndexerClient} - Queries historical events and pending transfers
+ * - {@link OwnershipTransferStartedEvent} - Pending transfer event from indexer
+ *
+ * @module access-control
  */
 
 export * from './actions';