core: add liquidity reservation and locking for concurrent loan creation

[EmeditWeb]

Problem

loans.service.createLoan() reads available pool liquidity during credit
assessment, then builds the funding XDR for the user to sign. Nothing
reserves that liquidity between the check and on-chain settlement, so two
concurrent loan requests can each pass the availability check against the
same funds. The second fund_loan then reverts on-chain with
InsufficientLiquidity after the user has already signed — wasting fees
and leaving a dangling provisional loan. There is no distributed lock or
reservation around the assess → build → submit sequence.

Before Starting

Read ALL of these before writing any code:

• context/architecture-context.md
• context/code-standards.md
• context/progress-tracker.md

What To Build

A liquidity reservation layer that serializes commitment of pool funds:

1. A Redis-backed distributed lock (or reservation ledger) keyed to the pool
   so concurrent loan creations cannot over-commit available liquidity.
2. Reserve the assessed amount atomically before returning the funding XDR;
   release the reservation on confirmed settlement, on failure, or on TTL
   expiry so a signed-but-never-submitted loan cannot lock funds forever.
3. Reconcile reservations against on-chain locked_liquidity so reservations
   never drift from reality.

Files To Touch

• src/modules/loans/loans.service.ts
• src/modules/liquidity/* (reservation ledger)
• src/common/* (Redis lock utility)
• corresponding *.spec.ts

Acceptance Criteria

• Concurrent loan creations cannot over-commit available liquidity
• Reservation acquired before funding XDR is returned
• Reservations expire (TTL) and release on failure/settlement
• Reservation totals reconciled against on-chain locked liquidity
• Concurrency test proves no double-spend under parallel requests

Mandatory Checks Before Opening PR

• All context/ files read and understood
• context/progress-tracker.md updated
• npm run build passes with zero TypeScript errors
• npm test passes — test count not decreased
• No new any types introduced
• Swagger decorators on any new endpoint
• Migration file created for any schema changes
• PR references this issue number

[Danielodingz]

Hey maintainer, please i would like to work on this issue.

[Lanhubs]

I can take ownership of this issue. Preventing race conditions and over-commitment of pool funds using distributed consensus locks and atomic reservations is standard practice in my backend and ledger engineering workflow.

Proposed Implementation Strategy
Redis-Backed Distributed Lock & TTL Reservation: I will implement a robust Redis-backed lock utility in src/common/ (utilizing redlock or atomic Lua scripting). Inside loans.service.createLoan(), the system will acquire a distributed lock keyed to the specific liquidity pool before evaluating credit and pool depth. Once inside the lock, the service will create an atomic reservation entry with a strict TTL (Time-To-Live). This ensures that if a user builds a funding XDR but never submits it to the blockchain network, the reservation safely expires and releases the blocked liquidity back to the pool.

Lifecycle State Machine: I will wire up the reservation engine in src/modules/liquidity/ to update its internal state dynamically based on transaction outcomes. Reservations will be explicitly cleared or marked as finalized upon confirmed settlement or immediate transaction failure.

On-Chain Reconciliation: I will introduce a sync worker or update the validation loop to reconcile active in-memory reservations directly against the on-chain locked_liquidity metrics to completely prevent state drift over time.

Concurrency Validation: I will author deterministic integration tests running parallel requests via Promise.all to verify that concurrent loan evaluation requests cannot double-spend or over-allocate available pool liquidity under heavy race conditions.