Merge pull request #574 from micmusjnr20/main

feat: Sequence Cache, Path Router, Offer Tracker & Claimable Balance Lifecycle

Author: Kingsman-99

src/claimableBalanceFallback.ts

@@ -5,6 +5,10 @@
  * does not exist or has no trustline for the asset, funds would otherwise be
  * stuck in the contract.  This module creates a Stellar claimable balance
  * instead, letting the payer claim it once their account is ready.
+ *
+ * Also provides a lifecycle manager that tracks claimable balances from
+ * creation through claim/expiry, polling Horizon for status changes and
+ * emitting typed events.
  */
 
 import {
@@ -14,10 +18,13 @@ import {
   Horizon,
   Operation,
   TransactionBuilder,
+  Keypair,
   BASE_FEE,
 } from "@stellar/stellar-sdk";
 import type { StellarSplitClientConfig } from "./client.js";
-import { ValidationError } from "./errors.js";
+import { ValidationError, ClaimableBalanceLifecycleError } from "./errors.js";
+import { TypedEventEmitter, type Unsubscribe } from "./events/TypedEventEmitter.js";
+import type { ClaimableBalanceRecord, ClaimableBalanceStatus } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // Error-pattern detection
@@ -234,3 +241,243 @@ async function _extractBalanceId(
   // Synthetic balance ID: prefixed with zeros so callers can detect it
   return `00000000${txHash}`;
 }
+
+// ---------------------------------------------------------------------------
+// Claimable Balance Lifecycle Manager
+// ---------------------------------------------------------------------------
+
+/** Events emitted by {@link ClaimableBalanceLifecycle}. */
+export interface ClaimableBalanceLifecycleEventMap {
+  [key: string]: unknown;
+  balanceClaimed: ClaimableBalanceRecord;
+  balanceExpired: ClaimableBalanceRecord;
+  error: { message: string; error: unknown };
+}
+
+/** Configuration for {@link ClaimableBalanceLifecycle}. */
+export interface ClaimableBalanceLifecycleConfig {
+  /** Polling interval in milliseconds. Default: 10_000 (10s). */
+  pollIntervalMs?: number;
+}
+
+/**
+ * Manages the full create-to-claim lifecycle of claimable balances.
+ *
+ * Tracks which balances are pending, detects claims and expirations via
+ * Horizon polling, and emits typed events so callers can surface the
+ * lifecycle state to users (e.g. notify recipients to claim, detect
+ * unclaimed balances past their predicate expiry).
+ *
+ * ```ts
+ * const lifecycle = new ClaimableBalanceLifecycle(horizonServer);
+ * lifecycle.on("balanceClaimed", (record) => console.log("Claimed:", record));
+ * lifecycle.on("balanceExpired", (record) => console.log("Expired:", record));
+ * lifecycle.start();
+ * ```
+ */
+export class ClaimableBalanceLifecycle extends TypedEventEmitter<ClaimableBalanceLifecycleEventMap> {
+  private readonly server: Horizon.Server;
+  private readonly pollIntervalMs: number;
+  private tracked: Map<string, ClaimableBalanceRecord> = new Map();
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private _running = false;
+
+  constructor(server: Horizon.Server, config: ClaimableBalanceLifecycleConfig = {}) {
+    super();
+    this.server = server;
+    this.pollIntervalMs = config.pollIntervalMs ?? 10_000;
+  }
+
+  /** Whether the lifecycle manager is currently polling. */
+  get running(): boolean {
+    return this._running;
+  }
+
+  /** Number of balances currently being tracked. */
+  get trackedCount(): number {
+    return this.tracked.size;
+  }
+
+  /**
+   * Start polling for claimable balance status changes.
+   */
+  start(): void {
+    if (this._running) return;
+    this._running = true;
+    this.poll();
+    this.pollTimer = setInterval(() => this.poll(), this.pollIntervalMs);
+  }
+
+  /**
+   * Stop polling.  Tracked balances are preserved.
+   */
+  stop(): void {
+    this._running = false;
+    if (this.pollTimer !== null) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+
+  /**
+   * Register a claimable balance for tracking.
+   *
+   * @param record - The balance to track.
+   */
+  track(record: ClaimableBalanceRecord): void {
+    this.tracked.set(record.balanceId, { ...record });
+  }
+
+  /**
+   * Remove a balance from tracking.
+   */
+  untrack(balanceId: string): void {
+    this.tracked.delete(balanceId);
+  }
+
+  /**
+   * Get all currently tracked balances.
+   */
+  listTracked(): ClaimableBalanceRecord[] {
+    return Array.from(this.tracked.values());
+  }
+
+  /**
+   * Claim a claimable balance on behalf of a recipient.
+   *
+   * @param balanceId - The claimable balance ID to claim.
+   * @param claimantSecret - Secret key of the claimant account.
+   * @param networkPassphrase - Stellar network passphrase.
+   * @returns Transaction hash of the claim submission.
+   */
+  async claimBalance(
+    balanceId: string,
+    claimantSecret: string,
+    networkPassphrase: string,
+  ): Promise<string> {
+    try {
+      const record = this.tracked.get(balanceId);
+      if (!record) {
+        throw new ClaimableBalanceLifecycleError(
+          `Balance ${balanceId} is not tracked`,
+          balanceId,
+        );
+      }
+
+      const keypair = Keypair.fromSecret(claimantSecret);
+      const account = await this.server.loadAccount(keypair.publicKey());
+      const sourceAccount = new Account(account.accountId(), account.sequenceNumber());
+
+      const tx = new TransactionBuilder(sourceAccount, {
+        fee: BASE_FEE,
+        networkPassphrase,
+      })
+        .addOperation(
+          Operation.claimClaimableBalance({
+            balanceId,
+          }),
+        )
+        .setTimeout(30)
+        .build();
+
+      tx.sign(keypair);
+      const result = await this.server.submitTransaction(tx);
+
+      record.status = "claimed";
+      record.claimedAt = Date.now();
+      this.emit("balanceClaimed", record);
+      this.tracked.delete(balanceId);
+
+      return result.hash;
+    } catch (err) {
+      if (err instanceof ClaimableBalanceLifecycleError) throw err;
+      throw new ClaimableBalanceLifecycleError(
+        `Failed to claim balance ${balanceId}: ${err instanceof Error ? err.message : String(err)}`,
+        balanceId,
+      );
+    }
+  }
+
+  /**
+   * Query all claimable balances for a given claimant from Horizon.
+   *
+   * @param claimant - Stellar address of the claimant.
+   * @returns List of claimable balance records.
+   */
+  async queryByClaimant(claimant: string): Promise<ClaimableBalanceRecord[]> {
+    try {
+      const page = await this.server.claimableBalances().claimant(claimant).call();
+      return page.records.map((r) => this.toRecord(r, claimant));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Manually trigger a poll cycle (useful for testing).
+   */
+  async pollNow(): Promise<void> {
+    await this.poll();
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+
+  private async poll(): Promise<void> {
+    if (!this._running) return;
+
+    for (const [balanceId, record] of this.tracked.entries()) {
+      try {
+        const fresh = await this.server
+          .claimableBalances()
+          .claimant(record.claimant)
+          .call();
+
+        const found = fresh.records.find((r) => r.id === balanceId);
+
+        if (!found) {
+          // Balance no longer exists — was claimed
+          record.status = "claimed";
+          record.claimedAt = record.claimedAt ?? Date.now();
+          this.emit("balanceClaimed", record);
+          this.tracked.delete(balanceId);
+        } else if (record.predicateExpiryLedger) {
+          // Check if the predicate has expired based on current ledger
+          // We approximate by checking last_modified_ledger
+          const currentLedger = found.last_modified_ledger;
+          if (currentLedger >= record.predicateExpiryLedger) {
+            record.status = "expired";
+            this.emit("balanceExpired", record);
+            this.tracked.delete(balanceId);
+          }
+        }
+      } catch (err) {
+        this.emit("error", {
+          message: `Poll error for balance ${balanceId}`,
+          error: err,
+        });
+      }
+    }
+  }
+
+  private toRecord(
+    r: Horizon.ServerApi.ClaimableBalanceRecord,
+    claimant: string,
+  ): ClaimableBalanceRecord {
+    // Attempt to extract creation time from the record; fall back to Date.now()
+    const raw = r as unknown as Record<string, unknown>;
+    const createdAt = raw.last_modified_time
+      ? new Date(raw.last_modified_time as string).getTime()
+      : Date.now();
+    return {
+      balanceId: r.id,
+      claimant,
+      asset: r.asset,
+      amount: r.amount,
+      status: "created",
+      createdAt,
+      claimedAt: null,
+    };
+  }
+}

src/errors.ts

@@ -1456,6 +1456,126 @@ export class PassphraseMismatchError extends StellarSplitError {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Sequence cache errors
+// ---------------------------------------------------------------------------
+
+/** Thrown when the sequence cache fails to fetch an account from Horizon. */
+export class SequenceCacheError extends StellarSplitError {
+  readonly accountId: string;
+
+  constructor(message: string, accountId: string) {
+    super(message, "SEQUENCE_CACHE_ERROR", { accountId }, message);
+    this.name = "SequenceCacheError";
+    this.accountId = accountId;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export function isSequenceCacheError(err: unknown): err is SequenceCacheError {
+  return err instanceof SequenceCacheError;
+}
+
+/** Thrown when a SEQUENCE_NUMBER_TOO_OLD error is detected at submission time. */
+export class SequenceNumberTooOldError extends StellarSplitError {
+  readonly accountId: string;
+  readonly cachedSequence: bigint;
+
+  constructor(accountId: string, cachedSequence: bigint) {
+    super(
+      `Sequence number too old for ${accountId} (cached: ${cachedSequence})`,
+      "SEQUENCE_NUMBER_TOO_OLD",
+      { accountId, cachedSequence: cachedSequence.toString() },
+    );
+    this.name = "SequenceNumberTooOldError";
+    this.accountId = accountId;
+    this.cachedSequence = cachedSequence;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export function isSequenceNumberTooOldError(err: unknown): err is SequenceNumberTooOldError {
+  return err instanceof SequenceNumberTooOldError;
+}
+
+// ---------------------------------------------------------------------------
+// Path router errors
+// ---------------------------------------------------------------------------
+
+/** Thrown when no DEX path could be found between two assets. */
+export class PathNotFoundError extends StellarSplitError {
+  readonly sourceAsset: string;
+  readonly destAsset: string;
+  readonly amount: bigint;
+
+  constructor(sourceAsset: string, destAsset: string, amount: bigint) {
+    super(
+      `No DEX path found from ${sourceAsset} to ${destAsset} for amount ${amount}`,
+      "PATH_NOT_FOUND",
+      { sourceAsset, destAsset, amount: amount.toString() },
+    );
+    this.name = "PathNotFoundError";
+    this.sourceAsset = sourceAsset;
+    this.destAsset = destAsset;
+    this.amount = amount;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export function isPathNotFoundError(err: unknown): err is PathNotFoundError {
+  return err instanceof PathNotFoundError;
+}
+
+/** Thrown when the path router encounters an unexpected error. */
+export class PathRouterError extends StellarSplitError {
+  constructor(message: string) {
+    super(message, "PATH_ROUTER_ERROR", undefined, message);
+    this.name = "PathRouterError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export function isPathRouterError(err: unknown): err is PathRouterError {
+  return err instanceof PathRouterError;
+}
+
+// ---------------------------------------------------------------------------
+// Offer tracker errors
+// ---------------------------------------------------------------------------
+
+/** Thrown when offer tracking or cancellation fails. */
+export class OfferTrackingError extends StellarSplitError {
+  constructor(message: string) {
+    super(message, "OFFER_TRACKING_ERROR", undefined, message);
+    this.name = "OfferTrackingError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export function isOfferTrackingError(err: unknown): err is OfferTrackingError {
+  return err instanceof OfferTrackingError;
+}
+
+// ---------------------------------------------------------------------------
+// Claimable balance lifecycle errors
+// ---------------------------------------------------------------------------
+
+/** Thrown when claimable balance lifecycle operations fail. */
+export class ClaimableBalanceLifecycleError extends StellarSplitError {
+  readonly balanceId: string;
+
+  constructor(message: string, balanceId: string) {
+    super(message, "CLAIMABLE_BALANCE_LIFECYCLE_ERROR", { balanceId }, message);
+    this.name = "ClaimableBalanceLifecycleError";
+    this.balanceId = balanceId;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export function isClaimableBalanceLifecycleError(err: unknown): err is ClaimableBalanceLifecycleError {
+  return err instanceof ClaimableBalanceLifecycleError;
+}
+
 export function isIPFSConfigError(err: unknown): err is IPFSConfigError {
   return err instanceof IPFSConfigError;
 }