Merge pull request #624 from scriptnovaa/feat/stellar-wave-532-535

Pagination envelope, memo validation, webhook DLQ, Horizon network URLs

Author: Jambox11

.env.example

@@ -4,6 +4,9 @@
 # Never commit .env to version control.
 # ============================================================
 
+# Stellar Configuration
+STELLAR_HORIZON_TESTNET_URL=https://horizon-testnet.stellar.org
+STELLAR_HORIZON_MAINNET_URL=https://horizon.stellar.org
 # ------------------------------------------------------------
 # Database
 # Required: PostgreSQL connection string (Prisma)

src/balance-indexer/balance-indexer.service.ts

@@ -8,6 +8,7 @@ import {
 import { PrismaService } from '../prisma/prisma.service';
 import { StellarHorizonService } from './stellar-horizon.service';
 import { ConfigService } from '@nestjs/config';
+import { WalletNetwork } from '../wallets/domain/wallet.model';
 import { WebhookEventEmitterService } from '../webhooks/webhook-event-emitter.service';
 import { BalanceRepository } from './balance.repository';
 import { BalanceCacheService } from './balance-cache.service';
@@ -413,8 +414,10 @@ export class BalanceIndexerService implements OnModuleInit, OnModuleDestroy {
         throw new NotFoundException(`Wallet ${walletId} not found`);
       }
 
+      // Check if account exists on-chain (on the wallet's own network)
       const accountExists = await this.stellarHorizonService.accountExists(
         wallet.publicKey,
+        wallet.network as WalletNetwork,
       );
 
       if (!accountExists) {
@@ -444,6 +447,11 @@ export class BalanceIndexerService implements OnModuleInit, OnModuleDestroy {
         return result;
       }
 
+      // Fetch balances from Horizon
+      const horizonBalances = await this.stellarHorizonService.getAccountBalances(
+        wallet.publicKey,
+        wallet.network as WalletNetwork,
+      );
       const horizonBalances =
         await this.stellarHorizonService.getAccountBalances(wallet.publicKey);
 
@@ -559,6 +567,7 @@ export class BalanceIndexerService implements OnModuleInit, OnModuleDestroy {
 
     const horizonBalances = await this.stellarHorizonService.getAccountBalances(
       wallet.publicKey,
+      wallet.network as WalletNetwork,
     );
     const onChainBalance = horizonBalances.find((b) =>
       this.assetsMatch(b.asset, asset),

src/balance-indexer/stellar-horizon.service.ts

@@ -6,6 +6,13 @@ import {
 import { ConfigService } from '@nestjs/config';
 import { Server } from 'stellar-sdk';
 import { Asset, AssetType, BalanceUpdate } from './domain/balance.model';
+import { WalletNetwork } from '../wallets/domain/wallet.model';
+
+export interface HorizonAccountResponse {
+  id: string;
+  sequence: string;
+  balances: HorizonBalance[];
+}
 import { RequestContextService } from '../common/request-context/request-context.service';
 import {
   CircuitBreaker,
@@ -22,6 +29,22 @@ export interface HorizonBalance {
 @Injectable()
 export class StellarHorizonService {
   private readonly logger = new Logger(StellarHorizonService.name);
+  private readonly horizonUrls: Record<WalletNetwork, string>;
+
+  constructor(private readonly configService: ConfigService) {
+    this.horizonUrls = {
+      [WalletNetwork.TESTNET]: this.configService.get<string>(
+        'STELLAR_HORIZON_TESTNET_URL',
+        'https://horizon-testnet.stellar.org',
+      ),
+      [WalletNetwork.MAINNET]: this.configService.get<string>(
+        'STELLAR_HORIZON_MAINNET_URL',
+        'https://horizon.stellar.org',
+      ),
+    };
+
+    this.logger.log(
+      `Initialized Stellar Horizon clients: testnet=${this.horizonUrls[WalletNetwork.TESTNET]}, mainnet=${this.horizonUrls[WalletNetwork.MAINNET]}`,
   private readonly horizonUrl: string;
   private readonly maxRetries: number;
   private readonly retryBackoffMs: number;
@@ -37,7 +60,14 @@ export class StellarHorizonService {
       'STELLAR_HORIZON_URL',
       'https://horizon-testnet.stellar.org',
     );
+  }
 
+  /**
+   * Resolves the Horizon base URL for a given network. Defaults to testnet
+   * when no network is specified, matching prior (single-URL) behavior.
+   */
+  private resolveUrl(network: WalletNetwork = WalletNetwork.TESTNET): string {
+    return this.horizonUrls[network];
     this.maxRetries = this.configService.get<number>(
       'STELLAR_HORIZON_MAX_RETRIES',
       3,
@@ -120,6 +150,11 @@ export class StellarHorizonService {
   /**
    * Fetches account balances from Stellar Horizon
    */
+  async getAccountBalances(
+    publicKey: string,
+    network: WalletNetwork = WalletNetwork.TESTNET,
+  ): Promise<BalanceUpdate[]> {
+    const horizonUrl = this.resolveUrl(network);
   async getAccountBalances(publicKey: string): Promise<BalanceUpdate[]> {
     const requestId = this.requestContext.getRequestId();
     const logPrefix = requestId ? `[${requestId}] ` : '';
@@ -130,6 +165,7 @@ export class StellarHorizonService {
       );
 
       // Simplified mock implementation
+      const response = await this.mockHorizonRequest(publicKey, horizonUrl);
       const response = await this.withRetry(
         () => this.mockHorizonRequest(publicKey),
         `getAccountBalances(${publicKey.substring(0, 8)}...)`,
@@ -162,6 +198,12 @@ export class StellarHorizonService {
   /**
    * Checks if an account exists on-chain
    */
+  async accountExists(
+    publicKey: string,
+    network: WalletNetwork = WalletNetwork.TESTNET,
+  ): Promise<boolean> {
+    try {
+      await this.mockHorizonRequest(publicKey, this.resolveUrl(network));
   async accountExists(publicKey: string): Promise<boolean> {
     const requestId = this.requestContext.getRequestId();
     const logPrefix = requestId ? `[${requestId}] ` : '';
@@ -270,4 +312,36 @@ export class StellarHorizonService {
         throw new Error(`Unknown asset type: ${horizonBalance.asset_type}`);
     }
   }
+
+  /**
+   * Mock Horizon request (replace with real stellar-sdk in production)
+   */
+  private async mockHorizonRequest(
+    publicKey: string,
+    horizonUrl: string,
+  ): Promise<HorizonAccountResponse> {
+    this.logger.debug(`Requesting account ${publicKey} from ${horizonUrl}`);
+
+    // Simulate API call delay
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Mock response with realistic data
+    return {
+      id: publicKey,
+      sequence: '123456789',
+      balances: [
+        {
+          asset_type: 'native',
+          balance: '1000.5000000',
+        },
+        {
+          asset_type: 'credit_alphanum4',
+          asset_code: 'USDC',
+          asset_issuer:
+            'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
+          balance: '500.0000000',
+        },
+      ],
+    };
+  }
 }

src/common/pagination/pagination.util.ts

@@ -0,0 +1,68 @@
+import { BadRequestException } from '@nestjs/common';
+
+export interface PaginationQuery {
+  page?: string;
+  limit?: string;
+}
+
+export interface PaginationParams {
+  page: number;
+  limit: number;
+  skip: number;
+}
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  meta: PaginationMeta;
+}
+
+export const DEFAULT_PAGE = 1;
+export const DEFAULT_PAGE_SIZE = 20;
+export const MAX_PAGE_SIZE = 100;
+
+/**
+ * Shared pagination envelope for list APIs (wallet/payment/transaction/custody flows).
+ * Validates page/limit query params consistently instead of each module rolling its own.
+ */
+export function parsePagination(query: PaginationQuery): PaginationParams {
+  const page =
+    query.page !== undefined ? Number(query.page) : DEFAULT_PAGE;
+  const limit =
+    query.limit !== undefined ? Number(query.limit) : DEFAULT_PAGE_SIZE;
+
+  if (!Number.isInteger(page) || page < 1) {
+    throw new BadRequestException('page must be a positive integer');
+  }
+
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_PAGE_SIZE) {
+    throw new BadRequestException(
+      `limit must be an integer between 1 and ${MAX_PAGE_SIZE}`,
+    );
+  }
+
+  return { page, limit, skip: (page - 1) * limit };
+}
+
+export function buildPaginatedResponse<T>(
+  data: T[],
+  total: number,
+  page: number,
+  limit: number,
+): PaginatedResult<T> {
+  return {
+    data,
+    meta: {
+      page,
+      limit,
+      total,
+      totalPages: limit > 0 ? Math.ceil(total / limit) : 0,
+    },
+  };
+}

src/common/stellar/memo.util.ts

@@ -0,0 +1,73 @@
+import { BadRequestException } from '@nestjs/common';
+
+export enum MemoType {
+  NONE = 'MEMO_NONE',
+  TEXT = 'MEMO_TEXT',
+  ID = 'MEMO_ID',
+  HASH = 'MEMO_HASH',
+  RETURN = 'MEMO_RETURN',
+}
+
+export interface MemoInput {
+  type: MemoType;
+  value?: string;
+}
+
+const MEMO_TEXT_MAX_BYTES = 28;
+const MEMO_ID_MAX = BigInt('18446744073709551615'); // uint64 max
+const MEMO_HASH_HEX_LENGTH = 64; // 32 bytes, hex-encoded
+
+/**
+ * Validates a Stellar transaction memo against the protocol's per-type constraints:
+ * https://developers.stellar.org/docs/encyclopedia/memos
+ */
+export function validateMemo(memo?: MemoInput): void {
+  if (!memo || memo.type === MemoType.NONE) {
+    return;
+  }
+
+  const { type, value } = memo;
+
+  if (value === undefined || value === '') {
+    throw new BadRequestException(`memo.value is required for ${type}`);
+  }
+
+  switch (type) {
+    case MemoType.TEXT: {
+      const byteLength = Buffer.byteLength(value, 'utf8');
+      if (byteLength > MEMO_TEXT_MAX_BYTES) {
+        throw new BadRequestException(
+          `memo of type MEMO_TEXT must be at most ${MEMO_TEXT_MAX_BYTES} bytes, got ${byteLength}`,
+        );
+      }
+      break;
+    }
+
+    case MemoType.ID: {
+      if (!/^\d+$/.test(value)) {
+        throw new BadRequestException(
+          'memo of type MEMO_ID must be an unsigned integer string',
+        );
+      }
+      if (BigInt(value) > MEMO_ID_MAX) {
+        throw new BadRequestException(
+          `memo of type MEMO_ID must not exceed ${MEMO_ID_MAX.toString()}`,
+        );
+      }
+      break;
+    }
+
+    case MemoType.HASH:
+    case MemoType.RETURN: {
+      if (!/^[0-9a-fA-F]+$/.test(value) || value.length !== MEMO_HASH_HEX_LENGTH) {
+        throw new BadRequestException(
+          `memo of type ${type} must be a ${MEMO_HASH_HEX_LENGTH}-character hex string (32 bytes)`,
+        );
+      }
+      break;
+    }
+
+    default:
+      throw new BadRequestException(`Unsupported memo type: ${type}`);
+  }
+}

src/payments/payments.controller.ts

@@ -6,6 +6,7 @@ import {
   Patch,
   Param,
   Delete,
+  Query,
   UseGuards,
   Query,
 } from '@nestjs/common';
@@ -18,6 +19,7 @@ import {
   ApiQuery,
 } from '@nestjs/swagger';
 import { PaymentsService } from './payments.service';
+import { PaginationQuery } from '../common/pagination/pagination.util';
 import { CreatePaymentDto } from './dto/create-payment.dto';
 import { UpdatePaymentDto } from './dto/update-payment.dto';
 import { PaymentsFilterDto } from './dto/payments-filter.dto';
@@ -172,6 +174,8 @@ export class PaymentsController {
     },
   })
   @Get()
+  findAll(@Query() query: PaginationQuery) {
+    return this.paymentsService.findAll(query);
   findAll(
     @Query() pagination: PaginationDto,
     @Query() filters: PaymentsFilterDto,

src/payments/payments.service.ts

@@ -9,6 +9,12 @@ import { EventEmitter2 } from '@nestjs/event-emitter';
 import { CreatePaymentDto } from './dto/create-payment.dto';
 import { UpdatePaymentDto } from './dto/update-payment.dto';
 import { PrismaService } from '../prisma/prisma.service';
+import { LimitsService } from '../limits/limits.service';
+import {
+  PaginationQuery,
+  parsePagination,
+  buildPaginatedResponse,
+} from '../common/pagination/pagination.util';
 import { WalletsService } from '../wallets/wallets.service';
 import {
   PAYMENT_LIMITS_PORT,
@@ -128,6 +134,19 @@ export class PaymentsService {
     return payment;
   }
 
+  async findAll(query: PaginationQuery = {}) {
+    const { page, limit, skip } = parsePagination(query);
+
+    const [data, total] = await Promise.all([
+      this.prisma.payment.findMany({
+        skip,
+        take: limit,
+        orderBy: { createdAt: 'desc' },
+      }),
+      this.prisma.payment.count(),
+    ]);
+
+    return buildPaginatedResponse(data, total, page, limit);
   async findAll(
     pagination: PaginationDto,
     filters: PaymentsFilterDto,

src/transactions/dto/create-transaction.dto.ts

@@ -1,3 +1,4 @@
+import { MemoType } from '../../common/stellar/memo.util';
 import {
   IsEnum,
   IsNotEmpty,
@@ -39,6 +40,11 @@ export class TransactionAssetDto {
   issuer?: string;
 }
 
+export class TransactionMemoDto {
+  type: MemoType;
+  value?: string;
+}
+
 export class CreateTransactionDto {
   /** Positive decimal string, up to 7 decimal places (Stellar precision) */
   @IsString()
@@ -57,6 +63,7 @@ export class CreateTransactionDto {
   @IsOptional()
   @IsUUID()
   receiverWalletId?: string;
+  memo?: TransactionMemoDto;
 
   /** Optional memo — max 28 bytes (Stellar text memo limit) */
   @IsOptional()