[shekwolonathanielbala-cyber]

#438 Spike 574: Integrate Soroswap and Classic DEX Liquidity Pools

Summary

Implement a feature-flagged liquidity pool integration supporting Soroswap and Stellar's classic liquidity pool operations, including PHASELQ-XLM pools and Chamber swaps. This spike establishes a secure, idempotent, and observable end-to-end flow covering funding, pool interactions, settlement, indexing, and UI display.

The implementation addresses existing architectural gaps in settlement accounting, liquidity pool balance handling, trustline preflight checks, reserve and quote retrieval, market pricing, wash-trading detection, and pool seed capital management.

Changes

• Smart Contracts: Extend the Phase Protocol to support liquidity-related operations, settlement safeguards, and the required contract-level invariants.
• Stellar Integration: Add and update Soroswap and classic DEX helpers for pool discovery, quotes, deposits, withdrawals, swaps, and asset resolution.
• API Routes: Integrate classic liquidity operations and update market and offer endpoints to support pool-aware trading and settlement.
• Market Storage: Extend market persistence and concurrency controls to prevent silent overwrites and preserve consistent state during overlapping requests.
• Wash-Trading Prevention: Detect and flag self-provisioning, self-swapping, replay attempts, and suspicious volume manipulation; exclude invalid activity from aggregates.
• Distributor Accounting: Update distributor ledger, refill, and issuer-payment flows to support safe liquidity pool funding and preserve accounting invariants.
• Idempotency and Concurrency: Enforce appropriate replay protection, version-guarded writes, and deterministic behavior under retries and concurrent operations.
• Resilience: Add or integrate safeguards for RPC, Horizon, and gateway failures, including failover, stale-on-error handling, and appropriate retry behavior.
• Feature Flags: Introduce dedicated "phase-*" flags, defaulting to off, with documented rollback procedures and no regression when disabled.
• Internationalization: Route all user-facing strings and errors through "lib/phase-copy.ts" and "pickCopy(lang)", supporting English and Spanish.
• Documentation: Update the liquidity rewards terminal documentation, architecture records, technical documentation, environment configuration, and relevant API contracts.

Security and Reliability

• Preserve client-side wallet signing through Freighter and Stellar Wallet Kit.
• Keep privileged and issuer keys within their existing authorized server-side boundaries.
• Validate pool assets, trustlines, quotes, slippage, and contract configuration before executing operations.
• Prevent duplicate processing and unsafe settlement through layered idempotency and concurrency controls.
• Use closed-label metrics without wallet addresses, signal identifiers, or user-generated text.
• Preserve normalized domain errors, including the existing biometric trust gate error mapping.
• Keep testnet-specific assumptions explicitly fenced from mainnet behavior.

Testing and Validation

• Verify the complete testnet flow: Friendbot funding → trustline setup → asset funding → pool operation or swap → transaction verification → indexing → UI display.
• Record transaction hashes and contract IDs, with configuration sourced from environment variables and synchronized documentation.
• Test Soroswap and classic liquidity pool paths independently.
• Verify replay protection, duplicate submissions, expired requests, and retries following serverless timeouts.
• Validate concurrent writes, version conflicts, deterministic queue behavior, and CRDT merge semantics.
• Test self-deal, sybil, wash-trading, tampered-input, and volume-drift detection.
• Verify RPC, gateway, and Horizon failover, stale-on-error behavior, circuit breakers, and "Retry-After" propagation.
• Confirm English and Spanish translations and normalized error handling.
• Update and verify feature-flag documentation and rollback behavior.
• Run existing tests, "tsc --noEmit", and Vitest with all new flags disabled to confirm no regressions.

Migration and Rollback

All new functionality remains disabled by default until the end-to-end testnet proof and required validation are complete.

Contract upgrades or redeployments, contract ID changes, database migrations, environment updates, and associated documentation must be coordinated. Additive database migrations should preserve existing data, while JSON sidecar data must remain inert when the feature is disabled.

Rollback consists of disabling the new feature flags and reverting the relevant documentation changes. Any on-chain changes, stranded assets, or contract state require an explicit recovery plan because disabling application flags does not reverse blockchain transactions or contract upgrades.

Scope and Limitations

• Testnet validation only.
• No production facilitator keys or mainnet deployment.
• No shared-database migration.
• Any expansion beyond the defined 16-file scope requires a separate issue or spike.

Issue Closure

Closes #438

[drips-wave]

@shekwolonathanielbala-cyber Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[shekwolonathanielbala-cyber]

Please merge