Merge pull request #200 from ryzen-xp/docs/DeFi-protocols

[DOCS]: DeFi protocols — DEX aggregator and Soroswap integration guide

Author: KevinMB0220

docs/defi/aggregator-guide.md

@@ -0,0 +1,50 @@
+# DEX Aggregator Guide
+
+## Overview
+`DexAggregatorService` queries multiple liquidity sources (SDEX via Horizon, Soroswap AMM) simultaneously to find the best execution price for a given asset pair. It currently supports routing and price comparison, culminating in an unsigned XDR transaction for client-side signing.
+
+## Routing Strategies and Quote Flow
+When `getAggregatedQuote` is called:
+1. **Request:** The service takes an `assetIn`, `assetOut`, and `amountIn`.
+2. **Route:** It concurrently queries all configured `LiquiditySource`s (`sdex`, `soroswap`).
+3. **Selection:** Results are filtered and sorted best-first (highest `amountOut`), returning an `AggregatedQuote`.
+
+### Quote Example
+```typescript
+import { DexAggregatorService } from '@galaxy-kj/core-defi';
+
+const aggregator = new DexAggregatorService(horizonServer, soroswapConfig);
+
+const quote = await aggregator.getAggregatedQuote({
+  assetIn: { code: 'XLM', type: 'native' },
+  assetOut: { code: 'USDC', issuer: 'GA...', type: 'credit_alphanum4' },
+  amountIn: '100',
+});
+
+console.log('Best source:', quote.bestRoute.source);
+console.log('Expected out:', quote.bestRoute.amountOut);
+```
+
+## Executing a Swap
+From a quote, you can construct an unsigned transaction using `executeAggregatedSwap`.
+
+```typescript
+const swapResult = await aggregator.executeAggregatedSwap({
+  signerPublicKey: 'GA...',
+  assetIn: { code: 'XLM', type: 'native' },
+  assetOut: { code: 'USDC', issuer: 'GA...', type: 'credit_alphanum4' },
+  amountIn: '100',
+  minAmountOut: '95', // Slippage protection
+});
+
+console.log('XDR to sign:', swapResult.xdr);
+```
+
+### Smart Wallet Integration
+The resulting `xdr` is left unsigned by design. It can be passed to the Smart Wallet integration (via passkey signatures) to authorize the swap transaction safely on behalf of the user.
+
+## Error Handling
+The aggregator manages several constraints:
+- **Price Impact:** `highImpactWarning` is flagged if the chosen route has a price impact >= 5%.
+- **Slippage Exceeded:** Controlled by passing `minAmountOut` during execution. If the actual return is lower, the transaction fails on-chain.
+- **Insufficient Liquidity / Network Errors:** Individual source quote failures are swallowed during aggregation, allowing the service to fallback to the remaining functioning sources. If no sources succeed, it throws an error.

docs/defi/soroswap-integration.md

@@ -0,0 +1,41 @@
+# Soroswap Protocol Integration
+
+## Overview
+Soroswap is integrated as a primary AMM liquidity source in the `DexAggregatorService`. It leverages the `@galaxy-kj/core-defi-protocols` package to interface with Soroswap smart contracts.
+
+## How it is Integrated
+1. **Pricing:** The `fetchSoroswapQuote` method initializes the protocol via `ProtocolFactory` and calls `getSwapQuote(assetIn, assetOut, amountIn)`.
+2. **Execution:** The `buildSoroswapSwapTransaction` calls the `swap` method on the protocol, returning the transaction hash (XDR) ready for signing.
+
+Docs for Soroswap: [Soroswap Documentation](https://docs.soroswap.finance/).
+
+## Adding New Protocol Sources
+To add a new protocol source (e.g., Aquarius):
+1. **Types:** Add the Source ID to the `LiquiditySource` union in `aggregator.types.ts`.
+2. **Quoting:** Implement a `fetch<Protocol>Quote(params)` method in `DexAggregatorService` that conforms to `RouteQuote`.
+3. **Execution:** Implement a `build<Protocol>SwapTransaction(params)` method to return an unsigned XDR string.
+4. **Registration:** Update the switch-cases inside `fetchQuoteFromSource` and `buildSwapTransaction`.
+
+## Testing and Mocking Protocal Responses
+To unit test the aggregator without hitting real networks, mock the `ProtocolFactory` in Jest:
+
+```typescript
+import { ProtocolFactory } from '@galaxy-kj/core-defi-protocols';
+
+jest.mock('@galaxy-kj/core-defi-protocols', () => ({
+  ...jest.requireActual('@galaxy-kj/core-defi-protocols'),
+  ProtocolFactory: {
+    getInstance: jest.fn().mockReturnValue({
+      createProtocol: jest.fn().mockReturnValue({
+        initialize: jest.fn().mockResolvedValue(true),
+        getSwapQuote: jest.fn().mockResolvedValue({
+          amountOut: '99',
+          priceImpact: '0.1',
+          path: []
+        }),
+        swap: jest.fn().mockResolvedValue({ hash: 'AAAA...' })
+      })
+    })
+  }
+}));
+```

packages/core/defi/README.md

@@ -0,0 +1,12 @@
+# @galaxy-kj/core-defi
+
+## Overview
+The `defi` package provides decentralized finance capabilities for the Galaxy DevKit. Its core feature is the `DexAggregatorService`, which coordinates price discovery across SDEX (Horizon path payments) and AMM protocols to find the best swap route for any asset pair.
+
+## Structure
+- `src/services/DexAggregatorService.ts`: Core aggregator service for routing and quotes.
+- `src/types/aggregator.types.ts`: Typings for liquidity sources, quotes, and swaps.
+
+For detailed integration guides, see:
+- [DEX Aggregator Guide](../../../docs/defi/aggregator-guide.md)
+- [Soroswap Integration Guide](../../../docs/defi/soroswap-integration.md)