Stellar Bridge Foundations: Congestion Signals, Session Recovery, Network Validation, and Lifecycle Hooks

packages/hooks/stellar/index.ts

@@ -0,0 +1 @@
+export * from "./transfer-lifecycle-hooks";

packages/hooks/stellar/transfer-lifecycle-hooks.ts

@@ -0,0 +1,29 @@
+export type StellarTransferContext = {
+  transferId: string;
+  from: string;
+  to: string;
+  amount: string;
+};
+
+export type StellarTransferHook = (ctx: StellarTransferContext) => void | Promise<void>;
+
+export class StellarTransferLifecycleHooks {
+  private preHooks: StellarTransferHook[] = [];
+  private postHooks: StellarTransferHook[] = [];
+
+  onPreTransfer(hook: StellarTransferHook): void {
+    this.preHooks.push(hook);
+  }
+
+  onPostTransfer(hook: StellarTransferHook): void {
+    this.postHooks.push(hook);
+  }
+
+  async runPreTransfer(ctx: StellarTransferContext): Promise<void> {
+    for (const hook of this.preHooks) await hook(ctx);
+  }
+
+  async runPostTransfer(ctx: StellarTransferContext): Promise<void> {
+    for (const hook of this.postHooks) await hook(ctx);
+  }
+}

src/analytics/congestion/stellar/index.ts

@@ -0,0 +1 @@
+export * from "./stellar-route-congestion-analyzer";

src/analytics/congestion/stellar/stellar-route-congestion-analyzer.ts

@@ -0,0 +1,35 @@
+export type StellarRouteSample = {
+  routeId: string;
+  latencyMs: number;
+  at: number;
+};
+
+export type StellarRouteCongestion = {
+  routeId: string;
+  averageLatencyMs: number;
+  spike: boolean;
+};
+
+export function analyzeStellarRouteCongestion(
+  samples: StellarRouteSample[],
+  spikeMultiplier = 1.6
+): StellarRouteCongestion[] {
+  const grouped = new Map<string, number[]>();
+  for (const s of samples) {
+    const bucket = grouped.get(s.routeId) ?? [];
+    bucket.push(s.latencyMs);
+    grouped.set(s.routeId, bucket);
+  }
+
+  const out: StellarRouteCongestion[] = [];
+  for (const [routeId, latencies] of grouped.entries()) {
+    const avg = latencies.reduce((a, b) => a + b, 0) / latencies.length;
+    const max = Math.max(...latencies);
+    out.push({
+      routeId,
+      averageLatencyMs: Math.round(avg),
+      spike: max > avg * spikeMultiplier,
+    });
+  }
+  return out;
+}

src/recovery/sessions/stellar/index.ts

@@ -0,0 +1 @@
+export * from "./stellar-bridge-session-recovery";

src/recovery/sessions/stellar/stellar-bridge-session-recovery.ts

@@ -0,0 +1,18 @@
+export type StellarBridgeSession = {
+  sessionId: string;
+  transferId: string;
+  status: "pending" | "completed" | "failed";
+  updatedAt: number;
+};
+
+export class StellarBridgeSessionRecovery {
+  private sessions = new Map<string, StellarBridgeSession>();
+
+  persist(session: StellarBridgeSession): void {
+    this.sessions.set(session.sessionId, session);
+  }
+
+  recoverInterruptedSessions(): StellarBridgeSession[] {
+    return Array.from(this.sessions.values()).filter((s) => s.status === "pending");
+  }
+}

src/wallets/validation/stellar/index.ts

@@ -0,0 +1 @@
+export * from "./stellar-wallet-network-validator";

src/wallets/validation/stellar/stellar-wallet-network-validator.ts

@@ -0,0 +1,21 @@
+export type StellarNetwork = "mainnet" | "testnet";
+
+export type StellarWalletNetworkValidation = {
+  expected: StellarNetwork;
+  detected: StellarNetwork;
+  valid: boolean;
+  warning?: string;
+};
+
+export function validateStellarWalletNetwork(
+  expected: StellarNetwork,
+  detected: StellarNetwork
+): StellarWalletNetworkValidation {
+  const valid = expected === detected;
+  return {
+    expected,
+    detected,
+    valid,
+    warning: valid ? undefined : `Wallet is on ${detected}, expected ${expected}.`,
+  };
+}