From 18f87c3123e2c24cc94a6c31c304e0f345610d64 Mon Sep 17 00:00:00 2001 From: ryzen_xp Date: Sun, 29 Mar 2026 08:05:57 +0530 Subject: [PATCH] =?UTF-8?q?[DOCS]:=20DeFi=20protocols=20=E2=80=94=20DEX=20?= =?UTF-8?q?aggregator=20and=20Soroswap=20integration=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/defi/aggregator-guide.md | 50 +++++++++++++++++++++++++++++++ docs/defi/soroswap-integration.md | 41 +++++++++++++++++++++++++ packages/core/defi/README.md | 12 ++++++++ 3 files changed, 103 insertions(+) create mode 100644 docs/defi/aggregator-guide.md create mode 100644 docs/defi/soroswap-integration.md create mode 100644 packages/core/defi/README.md diff --git a/docs/defi/aggregator-guide.md b/docs/defi/aggregator-guide.md new file mode 100644 index 0000000..34892b3 --- /dev/null +++ b/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. diff --git a/docs/defi/soroswap-integration.md b/docs/defi/soroswap-integration.md new file mode 100644 index 0000000..5b0334a --- /dev/null +++ b/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 `fetchQuote(params)` method in `DexAggregatorService` that conforms to `RouteQuote`. +3. **Execution:** Implement a `buildSwapTransaction(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...' }) + }) + }) + } +})); +``` diff --git a/packages/core/defi/README.md b/packages/core/defi/README.md new file mode 100644 index 0000000..bc4c7d6 --- /dev/null +++ b/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)