Feature/distributed transaction coordinator

[bilkee]

Summary

Implements a distributed transaction coordinator that enables atomic multi-leg swaps (e.g., USD → EUR → JPY) using a Two-Phase Commit protocol on the Stellar/Soroban network. This eliminates partial fills, stranded assets, and failed arbitrage opportunities when executing complex multi-pool aggregations.

Related Issues

Closes #47
Implements the full acceptance criteria for the distributed transaction coordinator with atomic swap support.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that changes existing behaviour)
• Documentation only
• Refactor / chore (no functional change)

Changes

Entities & DTOs (3 files, 294 lines)

• TransactionBatch — batch lifecycle with statuses: created → preparing → prepared → committing → committed | rolled_back | failed | expired
• BatchLeg — individual swap legs with dependency tracking, conditional execution support, and execution metadata
• BatchAuditLog — immutable audit trail for every state transition (17 action types)
• CreateBatchDto, QueryBatchDto, ConditionalLegDto, BatchDetailResponse with class-validator + Swagger decorators

Transaction Graph Builder (299 lines)

• Constructs dependency graphs from swap legs via topological sort (Kahn's algorithm)
• Cycle detection with descriptive error messages
• Parallel execution layers — legs with no dependencies run concurrently for max throughput
• Implicit dependency detection (auto-links legs sharing the same asset pair)

State Consistency Checker (391 lines)

• Pre-execution: validates batch status, positive amounts, price bounds (minAmountOut/maxAmountOut), conditional leg config, duplicate dependency detection
• Post-prepare: verifies expected outputs are within price bounds, prepared count matches
• Post-commit: validates actual outputs meet minimums, non-negative, price bounds, tx hash presence
• Post-rollback: confirms no legs left in intermediate state
• Condition evaluator: supports price_gt, price_lt, price_gte, price_lte, amount_gt, amount_lt

Retry Logic (188 lines)

• Exponential backoff with decorrelated jitter (prevents thundering herd)
• Configurable max retries, base delay, max delay cap, jitter factor
• Retryable error classification: network/transport errors (ECONNREFUSED, timeout, 5xx, rate limits) vs non-retryable (contract traps, validation)
• Retry summary with timing and error history for audit

Atomic Batch Executor (734 lines) — Two-Phase Commit protocol:

• Prepare phase: loads execution graph, simulates each leg via Soroban RPC, optimizes gas via GasOptimizationEngine, evaluates conditional legs against current market data, records prepared state
• Commit phase: executes prepared legs in parallel dependency layers via ContractInvocationService, automatic rollback of all committed legs on any failure
• MEV protection: timestamp-based sequence numbers for transaction ordering
• Full audit logging at every state transition

Coordinator Service (535 lines)

• Orchestrates full 2PC lifecycle: executeBatch() (automatic) or prepareBatch() + commitBatch() (manual)
• Timeout handling with automatic expiry and rollback
• Batch cancellation with proper cleanup
• Statistics endpoint for monitoring (total batches, status counts, avg legs, completion rate)

Controller & Module (170 + 37 lines)

• 8 REST endpoints with Swagger docs, JWT auth guards
• TransactionCoordinatorModule registered in AppModule with StellarModule dependency

Tests (947 lines, 50 tests across 3 suites)

• TransactionGraphBuilderService: 12 tests — linear/parallel/chain graphs, cycle detection, self-dependency, invalid index, implicit deps, validation, ready-leg calculation
• StateConsistencyCheckerService: 20 tests — pre-execution/post-prepare/post-commit/post-rollback checks, condition evaluation for all operators, edge cases
• RetryLogicService: 18 tests — retry on transient errors, backoff calculation, jitter behavior, non-retryable detection, summary computation

Checklist

• I have read the CONTRIBUTING guide.
• npm run lint passes (new files clean; pre-existing lint errors unchanged).
• npx tsc --noEmit passes (zero type errors).
• npm run build succeeds.
• npm test passes — 50 new tests added for graph builder, consistency checker, and retry logic.
• All Stellar/Soroban network access goes through StellarModule services (ContractInvocationService, GasOptimizationEngine) — no direct Horizon/RPC calls.
• I did not commit secrets, private keys, or mainnet credentials.

Notes for Reviewers

Architecture: Follows existing NestJS patterns (TypeORM entities, module/service/controller, Swagger). The new TransactionCoordinatorModule is self-contained with a single dependency on StellarModule.

Key design decisions:

1. Parallel execution layers — legs are topologically sorted into layers; legs in the same layer have no dependencies and execute concurrently
2. Atomic rollback — if any leg in a layer fails, all previously committed legs are rolled back in reverse dependency order
3. Conditional legs — evaluated during prepare phase via Soroban simulation; legs whose conditions aren't met are skipped (not failed)
4. MEV resistance — batch sequence numbers derived from Date.now() to enforce timestamp-based ordering
5. Mock transactions — AtomicBatchExecutor produces mock tx hashes (consistent with existing StellarService.executeSettlement pattern) until real signing is wired up

Testing: The 3 tested services (graph builder, consistency checker, retry logic) are pure logic with no external dependencies. The executor and coordinator services would need mocked Stellar/Soroban services for integration tests (recommended as follow-up).