From b7a6df24efd9b5dea4b4559c163d5d4ed528d5d5 Mon Sep 17 00:00:00 2001
From: indubala0103-hue <indubala0103@gmail.com>
Date: Wed, 30 Sep 2026 02:02:10 +0000
Subject: [PATCH] feat(backend): BE-050 time-locked escrow payout service +
 repair broken main
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements the escrow_payout backlog item (#803): time-locked escrow for
tutor earnings with accrual on confirmed contributions, unlock per the
tutor's payout schedule (BE-082), and a withdraw endpoint.

- EscrowPayoutService: accrue/list/balance/releaseUnlocked/withdraw with a
  locked → unlocked → withdrawn lifecycle. Withdrawal before unlock is
  rejected with ESCROW_LOCKED; the unlock job releases entries on schedule.
- REST surface at /api/v1/escrow (accrue, withdraw, release, entries,
  balance, withdrawals) with stroop amounts carried as strings on the wire.
- UsersModule wiring EscrowPayoutService to TutorPayoutScheduleService.
- Unit tests covering both acceptance criteria (163 unit tests pass).
- Migration 003: durable schema for escrow entries and withdrawals.

Also repairs pre-existing breakage on main so the suite and CI can pass:
- courses.controller.ts had two files concatenated (syntax error);
  restored both the v1 controller and the legacy /api/courses controller
  its e2e contract exercises, and registered CoursesService in the module.
- chat/registration.ts, health/wallet.ts, health/coverage.ts were stale
  duplicates importing modules that do not exist there; removed.
- Added the missing ChatRoomService its spec expects.
- TooManyRequestsException does not exist in @nestjs/common v10; defined
  it locally where chat moderation and submission protection need it.
- horizon.service: narrow balance asset_type before reading asset_code /
  asset_issuer (liquidity-pool shares carry neither); nextCursor derived
  from the last record so a full page still yields a cursor.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
---
 .../database/migrations/003_tutor_escrow.sql  |  56 +++++
 BackendAcademy/scripts/db-migrate.js          |   1 +
 BackendAcademy/src/app.module.ts              |   2 +
 BackendAcademy/src/chat/chat-room.service.ts  | 135 +++++++++++
 BackendAcademy/src/chat/moderation.service.ts |  12 +-
 BackendAcademy/src/chat/registration.ts       |  55 -----
 .../src/courses/courses.controller.ts         | 126 +++++-----
 BackendAcademy/src/courses/courses.module.ts  |  15 +-
 BackendAcademy/src/courses/dto/course.dto.ts  |   1 +
 BackendAcademy/src/health/coverage.ts         |  91 --------
 BackendAcademy/src/health/wallet.ts           |  55 -----
 .../social/submission-protection.service.ts   |  12 +-
 BackendAcademy/src/stellar/horizon.service.ts |  25 +-
 .../src/users/dto/escrow-payout.dto.ts        |  30 +++
 .../src/users/escrow-payout.controller.ts     | 106 +++++++++
 .../src/users/escrow-payout.service.spec.ts   | 168 ++++++++++++++
 .../src/users/escrow-payout.service.ts        | 218 ++++++++++++++++++
 BackendAcademy/src/users/users.module.ts      |  17 ++
 18 files changed, 848 insertions(+), 277 deletions(-)
 create mode 100644 BackendAcademy/database/migrations/003_tutor_escrow.sql
 create mode 100644 BackendAcademy/src/chat/chat-room.service.ts
 delete mode 100644 BackendAcademy/src/chat/registration.ts
 delete mode 100644 BackendAcademy/src/health/coverage.ts
 delete mode 100644 BackendAcademy/src/health/wallet.ts
 create mode 100644 BackendAcademy/src/users/dto/escrow-payout.dto.ts
 create mode 100644 BackendAcademy/src/users/escrow-payout.controller.ts
 create mode 100644 BackendAcademy/src/users/escrow-payout.service.spec.ts
 create mode 100644 BackendAcademy/src/users/escrow-payout.service.ts
 create mode 100644 BackendAcademy/src/users/users.module.ts

diff --git a/BackendAcademy/database/migrations/003_tutor_escrow.sql b/BackendAcademy/database/migrations/003_tutor_escrow.sql
new file mode 100644
index 0000000000..b2bb5ed4cf
--- /dev/null
+++ b/BackendAcademy/database/migrations/003_tutor_escrow.sql
@@ -0,0 +1,56 @@
+-- Migration 003: Time-locked tutor escrow (BE-050)
+--
+-- Durable representation of the in-memory EscrowPayoutService. The NestJS
+-- services are currently in-memory; this schema is what a future repository
+-- layer targets.
+--
+-- Design notes
+-- ─────────────
+-- • Amounts are BIGINT in stroops (1 XLM = 10^7 stroops) — the indivisible
+--   unit, mirroring the in-memory bigint handling.
+-- • accrual_id is the client-supplied idempotency key; UNIQUE per tutor so a
+--   replayed accrual is rejected by the database too.
+-- • unlocks_at is frozen at accrual time (computed from the tutor's schedule
+--   in effect then), so later schedule changes cannot shift existing rows.
+-- • state is enforced by CHECK; the transition locked → released is one-way.
+
+-- ── Escrow entries ──────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS tutor_escrow_entries (
+  escrow_id      TEXT PRIMARY KEY,
+  tutor_id       TEXT NOT NULL,
+  amount_stroops BIGINT NOT NULL CHECK (amount_stroops > 0),
+  accrued_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  unlocks_at     TIMESTAMPTZ NOT NULL,
+  state          TEXT NOT NULL DEFAULT 'locked' CHECK (state IN ('locked', 'released')),
+  released_at    TIMESTAMPTZ,
+  transaction_hash TEXT,
+  created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (tutor_id, escrow_id),
+  CHECK (released_at IS NULL OR state = 'released')
+);
+
+CREATE INDEX IF NOT EXISTS tutor_escrow_entries_tutor_state_idx ON tutor_escrow_entries (tutor_id, state);
+-- Drives the unlock job's "what is due?" scan.
+CREATE INDEX IF NOT EXISTS tutor_escrow_entries_state_unlocks_at_idx ON tutor_escrow_entries (state, unlocks_at);
+
+-- ── Withdrawals ─────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS tutor_escrow_withdrawals (
+  withdrawal_id  TEXT PRIMARY KEY,
+  tutor_id       TEXT NOT NULL,
+  amount_stroops BIGINT NOT NULL CHECK (amount_stroops > 0),
+  withdrawn_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  transaction_hash TEXT
+);
+
+CREATE INDEX IF NOT EXISTS tutor_escrow_withdrawals_tutor_idx ON tutor_escrow_withdrawals (tutor_id);
+
+-- ── Line items: which escrow entries a withdrawal consumed ─────────────────
+
+CREATE TABLE IF NOT EXISTS tutor_escrow_withdrawal_entries (
+  withdrawal_id TEXT NOT NULL REFERENCES tutor_escrow_withdrawals(withdrawal_id) ON DELETE CASCADE,
+  escrow_id     TEXT NOT NULL REFERENCES tutor_escrow_entries(escrow_id),
+  amount_stroops BIGINT NOT NULL CHECK (amount_stroops > 0),
+  PRIMARY KEY (withdrawal_id, escrow_id)
+);
diff --git a/BackendAcademy/scripts/db-migrate.js b/BackendAcademy/scripts/db-migrate.js
index a9177f9b32..26e2a2f89f 100644
--- a/BackendAcademy/scripts/db-migrate.js
+++ b/BackendAcademy/scripts/db-migrate.js
@@ -16,6 +16,7 @@ if (!databaseUrl) {
 const migrations = [
   'database/migrations/001_gamification_chat.sql',
   'database/migrations/002_courses_prerequisites.sql',
+  'database/migrations/003_tutor_escrow.sql',
 ];
 
 for (const migration of migrations) {
diff --git a/BackendAcademy/src/app.module.ts b/BackendAcademy/src/app.module.ts
index 498dc78e10..4e3055788b 100644
--- a/BackendAcademy/src/app.module.ts
+++ b/BackendAcademy/src/app.module.ts
@@ -14,6 +14,7 @@ import { SandboxModule } from './sandbox/sandbox.module';
 import { ProgressModule } from './progress/progress.module';
 import { CoursesModule } from './courses/courses.module';
 import { CertificatesModule } from './certificates/certificates.module';
+import { UsersModule } from './users/users.module';
 
 // Root application module: wires together global configuration/guards,
 // every feature module, and the top-level controllers/providers.
@@ -46,6 +47,7 @@ import { CertificatesModule } from './certificates/certificates.module';
     ProgressModule,
     CoursesModule,
     CertificatesModule,
+    UsersModule,
   ],
   // Top-level controllers not owned by a specific feature module:
   // AppController (root/basic routes) and HealthController
diff --git a/BackendAcademy/src/chat/chat-room.service.ts b/BackendAcademy/src/chat/chat-room.service.ts
new file mode 100644
index 0000000000..6e2bcb1bcc
--- /dev/null
+++ b/BackendAcademy/src/chat/chat-room.service.ts
@@ -0,0 +1,135 @@
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+
+/**
+ * Chat rooms with membership and paginated history (BE-094).
+ *
+ * In-memory like the other services so a repository can be swapped in later.
+ * The service is the source of truth for room membership: a user must join a
+ * room before its history is meaningful to them, and leaving stops their
+ * membership but keeps the message history intact for everyone else.
+ */
+
+export interface ChatRoom {
+  id: string;
+  name: string;
+  topic: string;
+  description: string;
+  createdAt: string;
+}
+
+export interface RoomMessage {
+  id: string;
+  roomId: string;
+  userId: string;
+  content: string;
+  createdAt: string;
+}
+
+export interface Paginated<T> {
+  items: T[];
+  page: number;
+  limit: number;
+  total: number;
+}
+
+interface PaginationOptions {
+  page?: number;
+  limit?: number;
+}
+
+const DEFAULT_PAGE_SIZE = 20;
+
+@Injectable()
+export class ChatRoomService {
+  private readonly rooms = new Map<string, ChatRoom>();
+  private readonly members = new Map<string, Set<string>>();
+  private readonly messages = new Map<string, RoomMessage[]>();
+
+  private nextRoomId = 1;
+  private nextMessageId = 1;
+
+  createRoom(input: { name: string; topic: string; description: string }): ChatRoom {
+    if (!input.name || !input.name.startsWith('#')) {
+      throw new BadRequestException('Room name must start with "#"');
+    }
+
+    const room: ChatRoom = {
+      id: `room_${this.nextRoomId++}`,
+      name: input.name,
+      topic: input.topic,
+      description: input.description,
+      createdAt: new Date().toISOString(),
+    };
+    this.rooms.set(room.id, room);
+    this.members.set(room.id, new Set());
+    this.messages.set(room.id, []);
+    return room;
+  }
+
+  getRoom(roomId: string): ChatRoom {
+    const room = this.rooms.get(roomId);
+    if (!room) throw new NotFoundException(`Room ${roomId} not found`);
+    return room;
+  }
+
+  listRooms(options: PaginationOptions = {}): Paginated<ChatRoom & { memberCount: number }> {
+    const { page = 1, limit = DEFAULT_PAGE_SIZE } = options;
+    const allRooms = [...this.rooms.values()].map((room) => ({
+      ...room,
+      memberCount: this.members.get(room.id)?.size ?? 0,
+    }));
+
+    return paginate(allRooms, page, limit);
+  }
+
+  joinRoom(roomId: string, userId: string): void {
+    this.getRoom(roomId);
+    this.members.get(roomId)!.add(userId);
+  }
+
+  leaveRoom(roomId: string, userId: string): boolean {
+    this.getRoom(roomId);
+    return this.members.get(roomId)!.delete(userId);
+  }
+
+  getRoomMembers(roomId: string): string[] {
+    this.getRoom(roomId);
+    return [...(this.members.get(roomId) ?? [])];
+  }
+
+  addMessage(roomId: string, input: { userId: string; content: string }): RoomMessage {
+    this.getRoom(roomId);
+
+    const message: RoomMessage = {
+      id: `msg_${this.nextMessageId++}`,
+      roomId,
+      userId: input.userId,
+      content: input.content,
+      createdAt: new Date().toISOString(),
+    };
+    this.messages.get(roomId)!.push(message);
+    return message;
+  }
+
+  /** Newest page first, matching how chat history is read back in the UI. */
+  getRoomHistory(roomId: string, options: PaginationOptions = {}): Paginated<RoomMessage> {
+    this.getRoom(roomId);
+    const { page = 1, limit = DEFAULT_PAGE_SIZE } = options;
+    const history = [...(this.messages.get(roomId) ?? [])].reverse();
+
+    return paginate(history, page, limit);
+  }
+}
+
+function paginate<T>(items: T[], page: number, limit: number): Paginated<T> {
+  const safePage = Math.max(1, Math.trunc(page));
+  const safeLimit = Math.min(Math.max(1, Math.trunc(limit)), 100);
+  const start = (safePage - 1) * safeLimit;
+
+  return {
+    items: items.slice(start, start + safeLimit),
+    page: safePage,
+    limit: safeLimit,
+    total: items.length,
+  };
+}
diff --git a/BackendAcademy/src/chat/moderation.service.ts b/BackendAcademy/src/chat/moderation.service.ts
index ec38d4397c..af93230365 100644
--- a/BackendAcademy/src/chat/moderation.service.ts
+++ b/BackendAcademy/src/chat/moderation.service.ts
@@ -1,4 +1,14 @@
-import { ForbiddenException, Injectable, TooManyRequestsException } from '@nestjs/common';
+import { ForbiddenException, HttpException, HttpStatus, Injectable } from '@nestjs/common';
+
+/**
+ * NestJS 10 ships no built-in 429 exception class, so the chat module defines
+ * the one it needs (BE-094 chat rate limiting).
+ */
+export class TooManyRequestsException extends HttpException {
+  constructor(message = 'Too many requests') {
+    super(message, HttpStatus.TOO_MANY_REQUESTS);
+  }
+}
 
 export interface ChatMessage {
   id: string;
diff --git a/BackendAcademy/src/chat/registration.ts b/BackendAcademy/src/chat/registration.ts
deleted file mode 100644
index 630bc81910..0000000000
--- a/BackendAcademy/src/chat/registration.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import { Injectable, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
-import { Subscription } from 'rxjs';
-import { DomainEventBus } from './domain-event-bus';
-import { XpEvent, XpEventType, XpLedgerEntry } from './xp.types';
-
-const XP_BY_EVENT: Record<XpEventType, number> = {
-  'task.passed': 10,
-  'course.completed': 100,
-  'streak.day': 5,
-  'contribution.created': 25,
-};
-
-@Injectable()
-export class XpService implements OnModuleInit, OnModuleDestroy {
-  private readonly ledger = new Map<string, XpLedgerEntry>();
-  private subscription?: Subscription;
-
-  constructor(private readonly eventBus: DomainEventBus) {}
-
-  onModuleInit(): void {
-    this.subscription = this.eventBus.subscribe((event) => this.award(event));
-  }
-
-  onModuleDestroy(): void {
-    this.subscription?.unsubscribe();
-  }
-
-  award(event: XpEvent): XpLedgerEntry | null {
-    if (this.ledger.has(event.eventId)) {
-      return null;
-    }
-
-    const entry: XpLedgerEntry = {
-      ...event,
-      points: XP_BY_EVENT[event.type],
-      occurredAt: event.occurredAt ?? new Date().toISOString(),
-      awardedAt: new Date().toISOString(),
-    };
-    this.ledger.set(event.eventId, entry);
-    return entry;
-  }
-
-  getBalance(userId: string): number {
-    return this.getLedger(userId).reduce((total, entry) => total + entry.points, 0);
-  }
-
-  getLedger(userId: string): XpLedgerEntry[] {
-    return [...this.ledger.values()].filter((entry) => entry.userId === userId);
-  }
-
-  getTotals(userId: string) {
-    const entries = this.getLedger(userId);
-    return { userId, totalXp: entries.reduce((total, entry) => total + entry.points, 0), entries };
-  }
-}
diff --git a/BackendAcademy/src/courses/courses.controller.ts b/BackendAcademy/src/courses/courses.controller.ts
index 9664271427..88deef271f 100644
--- a/BackendAcademy/src/courses/courses.controller.ts
+++ b/BackendAcademy/src/courses/courses.controller.ts
@@ -1,50 +1,3 @@
-import { Body, Controller, Get, HttpCode, Param, Post } from '@nestjs/common';
-import { CoursesService } from './courses.service';
-import { CreateCourseDto, CreateTaskDto, LearnerDto, SubmitTaskDto } from './dto/course.dto';
-
-@Controller('courses')
-export class CoursesController {
-  constructor(private readonly courses: CoursesService) {}
-
-  @Post()
-  create(@Body() dto: CreateCourseDto) {
-    return this.courses.create(dto);
-  }
-
-  @Get(':courseId')
-  get(@Param('courseId') courseId: string) {
-    return this.courses.get(courseId);
-  }
-
-  @Post(':courseId/enrollments')
-  enroll(@Param('courseId') courseId: string, @Body() dto: LearnerDto) {
-    return this.courses.enroll(courseId, dto.userId);
-  }
-
-  @Post(':courseId/enrollments/withdraw')
-  @HttpCode(200)
-  withdraw(@Param('courseId') courseId: string, @Body() dto: LearnerDto) {
-    return this.courses.withdraw(courseId, dto.userId);
-  }
-
-  @Post(':courseId/enrollments/complete')
-  @HttpCode(200)
-  complete(@Param('courseId') courseId: string, @Body() dto: LearnerDto) {
-    return this.courses.complete(courseId, dto.userId);
-  }
-
-  @Post(':courseId/tasks')
-  createTask(@Param('courseId') courseId: string, @Body() dto: CreateTaskDto) {
-    return this.courses.createTask(courseId, dto.taskId);
-  }
-
-  @Post(':courseId/tasks/:taskId/submissions')
-  submit(
-    @Param('courseId') courseId: string,
-    @Param('taskId') taskId: string,
-    @Body() dto: SubmitTaskDto,
-  ) {
-    return this.courses.submit(courseId, taskId, dto);
 import {
   Body,
   Controller,
@@ -55,6 +8,7 @@ import {
 } from '@nestjs/common';
 import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { CourseService } from './course.service';
+import { CoursesService } from './courses.service';
 import { EnrollmentService } from './enrollment.service';
 import { LessonService } from './lesson.service';
 import { CreateCourseDto } from './dto/create-course.dto';
@@ -63,6 +17,12 @@ import { EnrollDto } from './dto/enroll.dto';
 import { StartLessonDto } from './dto/start-lesson.dto';
 import { CompleteLessonDto } from './dto/complete-lesson.dto';
 import { CompleteCourseDto } from './dto/complete-course.dto';
+import {
+  CreateCourseDto as LegacyCreateCourseDto,
+  CreateTaskDto,
+  LearnerDto,
+  SubmitTaskDto,
+} from './dto/course.dto';
 
 /**
  * REST surface for the Learning Academy — courses, lessons, and enrollment.
@@ -126,26 +86,16 @@ export class CoursesController {
     return this.lessonService.findByCourse(courseId);
   }
 
-  // ── Enrollment ───────────────────────────────────────────────────────────
+  // ── Enrollment with prerequisite gating ──────────────────────────────────
 
   /**
-   * Enrol a user in a course.
+   * Enroll a user in a course.
    *
    * Returns 409 with a structured body when prerequisite courses have not been
-   * completed:
-   *
-   * ```json
-   * {
-   *   "statusCode": 409,
-   *   "error": "Conflict",
-   *   "message": "Prerequisites not met for course \"lifetimes-201\": complete ownership-101 first",
-   *   "code": "PREREQUISITES_NOT_MET",
-   *   "unmetPrerequisiteIds": ["ownership-101"]
-   * }
-   * ```
+   * completed.
    */
   @Post('enrollments')
-  @ApiOperation({ summary: 'Enrol a user in a course (blocked with 409 when prerequisites unmet)' })
+  @ApiOperation({ summary: 'Enroll a user in a course (gated on prerequisite courses)' })
   @ApiResponse({ status: 201, description: 'Enrollment created' })
   @ApiResponse({
     status: 409,
@@ -208,3 +158,57 @@ export class CoursesController {
     };
   }
 }
+
+/**
+ * Legacy `/api/courses` surface backed by `CoursesService` (capacity-tracked
+ * enrollments and task submissions with enrollment enforcement).
+ *
+ * The e2e contract in `test/courses.e2e-spec.ts` exercises these routes; kept
+ * alongside the v1 Learning Academy controller until callers migrate.
+ */
+@ApiTags('courses')
+@Controller('courses')
+export class LegacyCoursesController {
+  constructor(private readonly courses: CoursesService) {}
+
+  @Post()
+  create(@Body() dto: LegacyCreateCourseDto) {
+    return this.courses.create(dto);
+  }
+
+  @Get(':courseId')
+  get(@Param('courseId') courseId: string) {
+    return this.courses.get(courseId);
+  }
+
+  @Post(':courseId/enrollments')
+  enroll(@Param('courseId') courseId: string, @Body() dto: LearnerDto) {
+    return this.courses.enroll(courseId, dto.userId);
+  }
+
+  @Post(':courseId/enrollments/withdraw')
+  @HttpCode(200)
+  withdraw(@Param('courseId') courseId: string, @Body() dto: LearnerDto) {
+    return this.courses.withdraw(courseId, dto.userId);
+  }
+
+  @Post(':courseId/enrollments/complete')
+  @HttpCode(200)
+  complete(@Param('courseId') courseId: string, @Body() dto: LearnerDto) {
+    return this.courses.complete(courseId, dto.userId);
+  }
+
+  @Post(':courseId/tasks')
+  createTask(@Param('courseId') courseId: string, @Body() dto: CreateTaskDto) {
+    return this.courses.createTask(courseId, dto.taskId);
+  }
+
+  @Post(':courseId/tasks/:taskId/submissions')
+  submit(
+    @Param('courseId') courseId: string,
+    @Param('taskId') taskId: string,
+    @Body() dto: SubmitTaskDto,
+  ) {
+    return this.courses.submit(courseId, taskId, dto);
+  }
+}
diff --git a/BackendAcademy/src/courses/courses.module.ts b/BackendAcademy/src/courses/courses.module.ts
index c661cb4915..f873245ffb 100644
--- a/BackendAcademy/src/courses/courses.module.ts
+++ b/BackendAcademy/src/courses/courses.module.ts
@@ -1,8 +1,9 @@
 import { Module } from '@nestjs/common';
 import { QuizController } from './quiz.controller';
 import { QuizService } from './quiz.service';
-import { CoursesController } from './courses.controller';
+import { CoursesController, LegacyCoursesController } from './courses.controller';
 import { CourseService } from './course.service';
+import { CoursesService } from './courses.service';
 import { LessonService } from './lesson.service';
 import { EnrollmentService } from './enrollment.service';
 
@@ -12,10 +13,14 @@ import { EnrollmentService } from './enrollment.service';
  *
  * All providers are stateful in-memory, consistent with the
  * pattern used by GamificationModule, SocialModule, etc.
+ *
+ * `LegacyCoursesController` + `CoursesService` keep the original
+ * capacity-tracked enrollment/task-submission surface (`/api/courses`) that
+ * the e2e contract exercises.
  */
 @Module({
-  controllers: [CoursesController, QuizController],
-  providers: [CourseService, LessonService, EnrollmentService, QuizService],
-  exports: [CourseService, LessonService, EnrollmentService, QuizService],
+  controllers: [CoursesController, LegacyCoursesController, QuizController],
+  providers: [CourseService, CoursesService, LessonService, EnrollmentService, QuizService],
+  exports: [CourseService, CoursesService, LessonService, EnrollmentService, QuizService],
 })
-export class CoursesModule {}
\ No newline at end of file
+export class CoursesModule {}
diff --git a/BackendAcademy/src/courses/dto/course.dto.ts b/BackendAcademy/src/courses/dto/course.dto.ts
index 7e73c654e9..f57e5656f5 100644
--- a/BackendAcademy/src/courses/dto/course.dto.ts
+++ b/BackendAcademy/src/courses/dto/course.dto.ts
@@ -1,5 +1,6 @@
 import { ArrayUnique, IsArray, IsInt, IsNotEmpty, IsOptional, IsString, Min } from 'class-validator';
 
+/** Legacy /api/courses surface (CoursesService) — kept for the e2e contract. */
 export class CreateCourseDto {
   @IsString() @IsNotEmpty() courseId: string;
   @IsString() @IsNotEmpty() title: string;
diff --git a/BackendAcademy/src/health/coverage.ts b/BackendAcademy/src/health/coverage.ts
deleted file mode 100644
index ec38d4397c..0000000000
--- a/BackendAcademy/src/health/coverage.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-import { ForbiddenException, Injectable, TooManyRequestsException } from '@nestjs/common';
-
-export interface ChatMessage {
-  id: string;
-  userId: string;
-  channelId: string;
-  kind: 'dm' | 'room' | 'channel';
-  content: string;
-  createdAt: string;
-}
-
-export interface ModerationReport {
-  id: string;
-  reporterId: string;
-  messageId: string;
-  reason: string;
-  details: string;
-  status: 'open';
-  createdAt: string;
-}
-
-@Injectable()
-export class ModerationService {
-  private readonly messages: ChatMessage[] = [];
-  private readonly reports: ModerationReport[] = [];
-  private readonly violations = new Map<string, number>();
-  private readonly mutedUntil = new Map<string, number>();
-  private readonly rateWindows = new Map<string, number[]>();
-  private nextId = 1;
-
-  private readonly maxMessagesPerWindow = 20;
-  private readonly rateWindowMs = 60_000;
-  private readonly muteAfterViolations = 3;
-  private readonly muteDurationMs = 15 * 60_000;
-  private readonly abusiveWords = ['asshole', 'bitch', 'fuck', 'shit'];
-
-  sendMessage(input: Omit<ChatMessage, 'id' | 'createdAt'>): ChatMessage {
-    const now = Date.now();
-    this.assertRateLimit(input.userId, now);
-    const mutedUntil = this.mutedUntil.get(input.userId) ?? 0;
-    if (mutedUntil > now) {
-      throw new ForbiddenException(`User is muted until ${new Date(mutedUntil).toISOString()}`);
-    }
-
-    if (this.containsProfanity(input.content)) {
-      const count = (this.violations.get(input.userId) ?? 0) + 1;
-      this.violations.set(input.userId, count);
-      if (count >= this.muteAfterViolations) {
-        this.mutedUntil.set(input.userId, now + this.muteDurationMs);
-      }
-      throw new ForbiddenException('Message rejected by moderation');
-    }
-
-    const message: ChatMessage = { ...input, id: `msg_${this.nextId++}`, createdAt: new Date(now).toISOString() };
-    this.messages.push(message);
-    return message;
-  }
-
-  report(input: Omit<ModerationReport, 'id' | 'status' | 'createdAt'>): ModerationReport {
-    const report: ModerationReport = {
-      ...input,
-      id: `report_${this.nextId++}`,
-      status: 'open',
-      createdAt: new Date().toISOString(),
-    };
-    this.reports.push(report);
-    return report;
-  }
-
-  getQueue(): ModerationReport[] {
-    return [...this.reports];
-  }
-
-  isMuted(userId: string): boolean {
-    return (this.mutedUntil.get(userId) ?? 0) > Date.now();
-  }
-
-  private containsProfanity(content: string): boolean {
-    const normalized = content.toLowerCase().replace(/[^a-z0-9]+/g, ' ');
-    return this.abusiveWords.some((word) => new RegExp(`\\b${word}\\b`).test(normalized));
-  }
-
-  private assertRateLimit(userId: string, now: number): void {
-    const recent = (this.rateWindows.get(userId) ?? []).filter((timestamp) => now - timestamp < this.rateWindowMs);
-    if (recent.length >= this.maxMessagesPerWindow) {
-      throw new TooManyRequestsException('Chat rate limit exceeded');
-    }
-    recent.push(now);
-    this.rateWindows.set(userId, recent);
-  }
-}
diff --git a/BackendAcademy/src/health/wallet.ts b/BackendAcademy/src/health/wallet.ts
deleted file mode 100644
index 630bc81910..0000000000
--- a/BackendAcademy/src/health/wallet.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import { Injectable, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
-import { Subscription } from 'rxjs';
-import { DomainEventBus } from './domain-event-bus';
-import { XpEvent, XpEventType, XpLedgerEntry } from './xp.types';
-
-const XP_BY_EVENT: Record<XpEventType, number> = {
-  'task.passed': 10,
-  'course.completed': 100,
-  'streak.day': 5,
-  'contribution.created': 25,
-};
-
-@Injectable()
-export class XpService implements OnModuleInit, OnModuleDestroy {
-  private readonly ledger = new Map<string, XpLedgerEntry>();
-  private subscription?: Subscription;
-
-  constructor(private readonly eventBus: DomainEventBus) {}
-
-  onModuleInit(): void {
-    this.subscription = this.eventBus.subscribe((event) => this.award(event));
-  }
-
-  onModuleDestroy(): void {
-    this.subscription?.unsubscribe();
-  }
-
-  award(event: XpEvent): XpLedgerEntry | null {
-    if (this.ledger.has(event.eventId)) {
-      return null;
-    }
-
-    const entry: XpLedgerEntry = {
-      ...event,
-      points: XP_BY_EVENT[event.type],
-      occurredAt: event.occurredAt ?? new Date().toISOString(),
-      awardedAt: new Date().toISOString(),
-    };
-    this.ledger.set(event.eventId, entry);
-    return entry;
-  }
-
-  getBalance(userId: string): number {
-    return this.getLedger(userId).reduce((total, entry) => total + entry.points, 0);
-  }
-
-  getLedger(userId: string): XpLedgerEntry[] {
-    return [...this.ledger.values()].filter((entry) => entry.userId === userId);
-  }
-
-  getTotals(userId: string) {
-    const entries = this.getLedger(userId);
-    return { userId, totalXp: entries.reduce((total, entry) => total + entry.points, 0), entries };
-  }
-}
diff --git a/BackendAcademy/src/social/submission-protection.service.ts b/BackendAcademy/src/social/submission-protection.service.ts
index 57d444af52..b9979fad44 100644
--- a/BackendAcademy/src/social/submission-protection.service.ts
+++ b/BackendAcademy/src/social/submission-protection.service.ts
@@ -1,5 +1,15 @@
 import { createHash } from 'crypto';
-import { Injectable, TooManyRequestsException } from '@nestjs/common';
+import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
+
+/**
+ * NestJS 10 ships no built-in 429 exception class, so this module defines the
+ * one it needs; the subclass carries the Retry-After hint.
+ */
+export class TooManyRequestsException extends HttpException {
+  constructor(message = 'Too many requests') {
+    super(message, HttpStatus.TOO_MANY_REQUESTS);
+  }
+}
 
 export class SubmissionRateLimitException extends TooManyRequestsException {
   constructor(readonly retryAfterSeconds: number, message = 'Submission rate limit exceeded') {
diff --git a/BackendAcademy/src/stellar/horizon.service.ts b/BackendAcademy/src/stellar/horizon.service.ts
index 55f184ea90..8545d4081a 100644
--- a/BackendAcademy/src/stellar/horizon.service.ts
+++ b/BackendAcademy/src/stellar/horizon.service.ts
@@ -27,11 +27,19 @@ export class HorizonService {
       return {
         accountId: account.accountId(),
         sequence: account.sequence,
-        balances: account.balances.map((balance) => ({
-          assetCode: balance.asset_type === 'native' ? 'XLM' : balance.asset_code,
-          assetIssuer: balance.asset_type === 'native' ? undefined : balance.asset_issuer,
-          amount: balance.balance,
-        })),
+        balances: account.balances.map((balance) => {
+          // Liquidity-pool-share balances carry neither asset_code nor
+          // asset_issuer; only credit balances do, so narrow on asset_type
+          // before reading them.
+          const isNative = balance.asset_type === 'native';
+          const isLiquidityPool = balance.asset_type === 'liquidity_pool_shares';
+          const credit = isNative || isLiquidityPool ? undefined : balance;
+          return {
+            assetCode: isNative ? 'XLM' : credit?.asset_code,
+            assetIssuer: credit?.asset_issuer,
+            amount: balance.balance,
+          };
+        }),
       };
     } catch (error) {
       if ((error as { response?: { status?: number } }).response?.status === 404) {
@@ -54,9 +62,10 @@ export class HorizonService {
       return {
         accountId: publicKey,
         operations,
-        nextCursor: page.records.length === safeLimit
-          ? String(page.records[page.records.length - 1].paging_token ?? operations[operations.length - 1].id)
-          : null,
+        nextCursor:
+          page.records.length > 0
+            ? String(page.records[page.records.length - 1].paging_token ?? operations[operations.length - 1].id)
+            : null,
       };
     } catch {
       throw new ServiceUnavailableException('Unable to fetch Stellar transaction history');
diff --git a/BackendAcademy/src/users/dto/escrow-payout.dto.ts b/BackendAcademy/src/users/dto/escrow-payout.dto.ts
new file mode 100644
index 0000000000..478f51ca73
--- /dev/null
+++ b/BackendAcademy/src/users/dto/escrow-payout.dto.ts
@@ -0,0 +1,30 @@
+import { IsInt, IsNotEmpty, IsOptional, IsString, Min } from 'class-validator';
+
+export class AccrueEscrowDto {
+  @IsString()
+  @IsNotEmpty()
+  tutorId: string;
+
+  /** Client-supplied idempotency key; becomes the escrow entry id. */
+  @IsString()
+  @IsNotEmpty()
+  accrualId: string;
+
+  /** Amount in stroops (1 XLM = 10^7 stroops). Integer because a stroop is indivisible. */
+  @IsInt()
+  @Min(1)
+  amountStroops: number;
+}
+
+export class WithdrawEscrowDto {
+  @IsString()
+  @IsNotEmpty()
+  tutorId: string;
+}
+
+export class ReleaseUnlockedDto {
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  now?: string;
+}
diff --git a/BackendAcademy/src/users/escrow-payout.controller.ts b/BackendAcademy/src/users/escrow-payout.controller.ts
new file mode 100644
index 0000000000..8957e87877
--- /dev/null
+++ b/BackendAcademy/src/users/escrow-payout.controller.ts
@@ -0,0 +1,106 @@
+import { Body, Controller, Get, HttpCode, Param, Post } from '@nestjs/common';
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { AccrueEscrowDto, ReleaseUnlockedDto, WithdrawEscrowDto } from './dto/escrow-payout.dto';
+import { EscrowPayoutService } from './escrow-payout.service';
+
+/**
+ * REST surface for the tutor escrow payout (BE-050).
+ *
+ * Base path: /api/v1/escrow
+ *
+ * Like the other controllers it stays thin: the service owns the locking
+ * rules, and NestJS maps its exceptions to status codes:
+ *
+ *   ConflictException  (409) → accrual id replayed
+ *   BadRequestException(400) → withdrawal before unlock (code ESCROW_LOCKED)
+ *   NotFoundException  (404) → nothing to withdraw
+ *
+ * Stroop amounts are bigint internally and travel the wire as strings.
+ */
+@ApiTags('escrow')
+@Controller('v1/escrow')
+export class EscrowPayoutController {
+  constructor(private readonly escrowPayout: EscrowPayoutService) {}
+
+  @Post('accrue')
+  @ApiOperation({ summary: 'Accrue a confirmed contribution into time-locked escrow' })
+  accrue(@Body() dto: AccrueEscrowDto) {
+    const entry = this.escrowPayout.accrue(dto.tutorId, {
+      accrualId: dto.accrualId,
+      amountStroops: BigInt(dto.amountStroops),
+    });
+    // bigint is not JSON-serialisable, so the wire form is a string.
+    return { ...entry, amountStroops: entry.amountStroops.toString() };
+  }
+
+  @Post('withdraw')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Withdraw every unlocked escrow entry for a tutor' })
+  withdraw(@Body() dto: WithdrawEscrowDto) {
+    const withdrawal = this.escrowPayout.withdraw(dto.tutorId);
+    return {
+      ...withdrawal,
+      amountStroops: withdrawal.amountStroops.toString(),
+      entries: withdrawal.entries.map((entry) => ({
+        ...entry,
+        amountStroops: entry.amountStroops.toString(),
+      })),
+    };
+  }
+
+  @Post('release')
+  @HttpCode(200)
+  @ApiOperation({ summary: 'Run the unlock job: release every entry whose unlock time has arrived' })
+  release(@Body() dto: ReleaseUnlockedDto) {
+    const now = dto.now !== undefined ? Number(dto.now) : undefined;
+    const released = this.escrowPayout.releaseUnlocked(
+      now !== undefined && Number.isFinite(now) ? now : undefined,
+    );
+    return {
+      releasedCount: released.length,
+      released: released.map((entry) => ({
+        ...entry,
+        amountStroops: entry.amountStroops.toString(),
+      })),
+    };
+  }
+
+  @Get('tutors/:tutorId/entries')
+  @ApiOperation({ summary: "List a tutor's escrow entries" })
+  listEntries(@Param('tutorId') tutorId: string) {
+    return {
+      tutorId,
+      entries: this.escrowPayout.listEntries(tutorId).map((entry) => ({
+        ...entry,
+        amountStroops: entry.amountStroops.toString(),
+      })),
+    };
+  }
+
+  @Get('tutors/:tutorId/balance')
+  @ApiOperation({ summary: "Get a tutor's locked and available escrow balance" })
+  getBalance(@Param('tutorId') tutorId: string) {
+    const balance = this.escrowPayout.getBalance(tutorId);
+    return {
+      tutorId,
+      lockedStroops: balance.lockedStroops.toString(),
+      availableStroops: balance.availableStroops.toString(),
+    };
+  }
+
+  @Get('tutors/:tutorId/withdrawals')
+  @ApiOperation({ summary: "List a tutor's executed withdrawals" })
+  listWithdrawals(@Param('tutorId') tutorId: string) {
+    return {
+      tutorId,
+      withdrawals: this.escrowPayout.listWithdrawals(tutorId).map((withdrawal) => ({
+        ...withdrawal,
+        amountStroops: withdrawal.amountStroops.toString(),
+        entries: withdrawal.entries.map((entry) => ({
+          ...entry,
+          amountStroops: entry.amountStroops.toString(),
+        })),
+      })),
+    };
+  }
+}
diff --git a/BackendAcademy/src/users/escrow-payout.service.spec.ts b/BackendAcademy/src/users/escrow-payout.service.spec.ts
new file mode 100644
index 0000000000..43b377dd9d
--- /dev/null
+++ b/BackendAcademy/src/users/escrow-payout.service.spec.ts
@@ -0,0 +1,168 @@
+import { BadRequestException, ConflictException, NotFoundException } from '@nestjs/common';
+import { EscrowPayoutService } from './escrow-payout.service';
+import { TutorPayoutScheduleService } from './tutor-payout-schedule.service';
+
+/**
+ * BE-050 acceptance criteria:
+ *
+ * - "Withdrawal before unlock is rejected" — withdraw() before the schedule's
+ *   unlock time throws ESCROW_LOCKED, even though balance still reports the
+ *   funds as held.
+ * - "Unlock job releases on schedule" — releaseUnlocked() at/after the unlock
+ *   time flips the entries to released, after which withdrawal succeeds.
+ *
+ * Unlock times are computed with fixed offsets from the accrual time, so the
+ * tests never wait on real time; every timestamp is injected.
+ */
+describe('EscrowPayoutService', () => {
+  const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+  const MONTH_MS = 30 * 24 * 60 * 60 * 1000;
+
+  const T0 = 1_760_000_000_000; // fixed "accrual" moment
+  const DAY = 24 * 60 * 60 * 1000;
+
+  let service: EscrowPayoutService;
+  let scheduleService: TutorPayoutScheduleService;
+
+  beforeEach(() => {
+    scheduleService = new TutorPayoutScheduleService();
+    service = new EscrowPayoutService(scheduleService);
+  });
+
+  describe('accrue', () => {
+    it('creates a locked entry with the unlock time from the default (monthly) schedule', () => {
+      const entry = service.accrue('tutor-1', {
+        accrualId: 'a-1',
+        amountStroops: 1_000_000n,
+        accruedAt: T0,
+      });
+
+      expect(entry.state).toBe('locked');
+      expect(entry.amountStroops).toBe(1_000_000n);
+      expect(entry.accruedAt).toBe(T0);
+      expect(entry.unlocksAt).toBe(T0 + MONTH_MS);
+    });
+
+    it('honours a weekly schedule set before the accrual', () => {
+      scheduleService.setSchedule('tutor-1', 'weekly', T0 - DAY);
+
+      const entry = service.accrue('tutor-1', {
+        accrualId: 'a-1',
+        amountStroops: 500n,
+        accruedAt: T0,
+      });
+
+      expect(entry.unlocksAt).toBe(T0 + WEEK_MS);
+    });
+
+    it('rejects duplicate accrual ids (idempotency) and non-positive amounts', () => {
+      service.accrue('tutor-1', { accrualId: 'a-1', amountStroops: 100n, accruedAt: T0 });
+
+      expect(() =>
+        service.accrue('tutor-1', { accrualId: 'a-1', amountStroops: 100n, accruedAt: T0 }),
+      ).toThrow(ConflictException);
+      expect(() => service.accrue('tutor-1', { accrualId: 'a-2', amountStroops: 0n, accruedAt: T0 })).toThrow(
+        BadRequestException,
+      );
+      expect(() => service.accrue('tutor-1', { accrualId: 'a-3', amountStroops: -5n, accruedAt: T0 })).toThrow(
+        BadRequestException,
+      );
+    });
+  });
+
+  describe('withdraw before unlock is rejected', () => {
+    it('throws ESCROW_LOCKED with the earliest unlock while any entry is still locked', () => {
+      service.accrue('tutor-1', { accrualId: 'a-1', amountStroops: 100n, accruedAt: T0 });
+      service.accrue('tutor-1', { accrualId: 'a-2', amountStroops: 200n, accruedAt: T0 + DAY });
+
+      const beforeUnlock = T0 + DAY + 1;
+
+      expect(() => service.withdraw('tutor-1', beforeUnlock)).toThrow(BadRequestException);
+      try {
+        service.withdraw('tutor-1', beforeUnlock);
+      } catch (error) {
+        const response = (error as BadRequestException).getResponse() as {
+          code?: string;
+          earliestUnlockAt?: string;
+        };
+        expect(response.code).toBe('ESCROW_LOCKED');
+        expect(response.earliestUnlockAt).toBe(new Date(T0 + MONTH_MS).toISOString());
+      }
+
+      // The funds stay held, not lost or paid out.
+      expect(service.getBalance('tutor-1', beforeUnlock)).toEqual({
+        lockedStroops: 300n,
+        availableStroops: 0n,
+      });
+      expect(service.listWithdrawals('tutor-1')).toHaveLength(0);
+    });
+
+    it('throws NotFound when the tutor has no escrow entries at all', () => {
+      expect(() => service.withdraw('ghost', T0)).toThrow(NotFoundException);
+    });
+  });
+
+  describe('unlock job releases on schedule', () => {
+    it('releases exactly the entries whose unlock time has arrived', () => {
+      service.accrue('tutor-1', { accrualId: 'a-1', amountStroops: 100n, accruedAt: T0 });
+      // Accrues 10 days later, so it unlocks 10 days after tutor-1's entry.
+      service.accrue('tutor-2', { accrualId: 'a-2', amountStroops: 50n, accruedAt: T0 + 10 * DAY });
+
+      // Just before tutor-1's unlock: nothing released anywhere.
+      expect(service.releaseUnlocked(T0 + MONTH_MS - 1).map((e) => e.escrowId)).toEqual([]);
+
+      // At the unlock time: tutor-1's entry is released, tutor-2's is not.
+      const released = service.releaseUnlocked(T0 + MONTH_MS);
+      expect(released.map((e) => e.escrowId)).toEqual(['a-1']);
+      expect(released[0].state).toBe('unlocked');
+      expect(released[0].releasedAt).toBe(T0 + MONTH_MS);
+
+      // Running the job again before the next unlock is a no-op —
+      // already-released entries stay put.
+      expect(service.releaseUnlocked(T0 + 35 * DAY)).toEqual([]);
+    });
+
+    it('allows withdrawal once the unlock time arrives, and only of unlocked funds', () => {
+      service.accrue('tutor-1', { accrualId: 'a-1', amountStroops: 100n, accruedAt: T0 });
+      const later = service.accrue('tutor-1', {
+        accrualId: 'a-2',
+        amountStroops: 900n,
+        accruedAt: T0 + DAY,
+      });
+
+      const atUnlock = T0 + MONTH_MS;
+      const withdrawal = service.withdraw('tutor-1', atUnlock);
+
+      expect(withdrawal.amountStroops).toBe(100n); // only a-1 was unlocked
+      expect(withdrawal.entries).toEqual([{ escrowId: 'a-1', amountStroops: 100n }]);
+      expect(later.state).toBe('locked');
+
+      // After the second entry unlocks, the rest is withdrawable.
+      service.releaseUnlocked(later.unlocksAt);
+      const second = service.withdraw('tutor-1', later.unlocksAt);
+      expect(second.amountStroops).toBe(900n);
+      expect(service.getBalance('tutor-1', later.unlocksAt)).toEqual({
+        lockedStroops: 0n,
+        availableStroops: 0n,
+      });
+      expect(service.listWithdrawals('tutor-1')).toHaveLength(2);
+    });
+  });
+
+  describe('getLockedEntries and balances', () => {
+    it('classifies entries relative to `now`', () => {
+      service.accrue('tutor-1', { accrualId: 'a-1', amountStroops: 100n, accruedAt: T0 });
+
+      expect(service.getLockedEntries('tutor-1', T0)).toHaveLength(1);
+      expect(service.getLockedEntries('tutor-1', T0 + MONTH_MS)).toHaveLength(0);
+      expect(service.getBalance('tutor-1', T0)).toEqual({
+        lockedStroops: 100n,
+        availableStroops: 0n,
+      });
+      expect(service.getBalance('tutor-1', T0 + MONTH_MS)).toEqual({
+        lockedStroops: 0n,
+        availableStroops: 100n,
+      });
+    });
+  });
+});
diff --git a/BackendAcademy/src/users/escrow-payout.service.ts b/BackendAcademy/src/users/escrow-payout.service.ts
new file mode 100644
index 0000000000..9df5bd6741
--- /dev/null
+++ b/BackendAcademy/src/users/escrow-payout.service.ts
@@ -0,0 +1,218 @@
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { TutorPayoutScheduleService } from './tutor-payout-schedule.service';
+
+/**
+ * Time-locked escrow for tutor earnings (BE-050).
+ *
+ * EscrowPayoutService accrues a tutor's confirmed contributions into
+ * time-locked escrow entries, releases them once their unlock time arrives
+ * (per the tutor's payout schedule from BE-082), and exposes the withdraw
+ * endpoint's core operation: a withdrawal requested *before* the unlock time
+ * is rejected, so earnings stay locked to the schedule.
+ *
+ * Entry lifecycle: `locked` (still time-locked) → `unlocked` (past its unlock
+ * time, released by the unlock job or implicitly by a withdrawal) →
+ * `withdrawn` (paid out). `unlock`-ing is idempotent bookkeeping; only a
+ * withdrawal moves money.
+ *
+ * In-memory like the other services so a repository can be swapped in later
+ * without changing callers. Amounts are held in stroops (1 XLM = 10^7
+ * stroops), the indivisible unit, so no rounding is ever invented.
+ */
+
+export type EscrowState = 'locked' | 'unlocked' | 'withdrawn';
+
+export interface EscrowEntry {
+  escrowId: string;
+  tutorId: string;
+  /** Stroops held in this entry. */
+  amountStroops: bigint;
+  /** When the earnings were accrued (ms since epoch). */
+  accruedAt: number;
+  /** When this entry unlocks for withdrawal (ms since epoch). */
+  unlocksAt: number;
+  state: EscrowState;
+  /** Set when the entry is released by the unlock job or a withdrawal. */
+  releasedAt?: number;
+  /** Transaction hash of the on-chain release, when one is recorded. */
+  transactionHash?: string;
+}
+
+export interface WithdrawalResult {
+  withdrawalId: string;
+  tutorId: string;
+  amountStroops: bigint;
+  entries: Array<{ escrowId: string; amountStroops: bigint }>;
+  withdrawnAt: number;
+}
+
+@Injectable()
+export class EscrowPayoutService {
+  /** tutorId → escrow entries, oldest accrual first. */
+  private readonly escrow = new Map<string, EscrowEntry[]>();
+  /** Withdrawals already executed, across all tutors. */
+  private readonly withdrawals: WithdrawalResult[] = [];
+
+  private nextWithdrawalId = 1;
+
+  constructor(private readonly scheduleService: TutorPayoutScheduleService) {}
+
+  /**
+   * Accrues a confirmed contribution into escrow. The unlock time comes from
+   * the tutor's payout schedule at `accruedAt`, so later schedule changes
+   * never shift already-accrued earnings.
+   */
+  accrue(
+    tutorId: string,
+    input: { accrualId: string; amountStroops: bigint; accruedAt?: number },
+  ): EscrowEntry {
+    if (!tutorId) {
+      throw new BadRequestException('tutorId is required');
+    }
+    if (!input.accrualId) {
+      throw new BadRequestException('accrualId is required');
+    }
+    if (input.amountStroops <= 0n) {
+      throw new BadRequestException('amountStroops must be greater than zero');
+    }
+
+    const entries = this.escrow.get(tutorId) ?? [];
+    if (entries.some((entry) => entry.escrowId === input.accrualId)) {
+      throw new ConflictException(
+        `Escrow entry ${input.accrualId} already exists for tutor ${tutorId}`,
+      );
+    }
+
+    const unlock = this.scheduleService.computeUnlock(tutorId, input.accruedAt ?? Date.now());
+    const entry: EscrowEntry = {
+      escrowId: input.accrualId,
+      tutorId,
+      amountStroops: input.amountStroops,
+      accruedAt: unlock.accruedAt,
+      unlocksAt: unlock.unlocksAt,
+      state: 'locked',
+    };
+
+    entries.push(entry);
+    this.escrow.set(tutorId, entries);
+    return entry;
+  }
+
+  /** All escrow entries held for a tutor, oldest accrual first. */
+  listEntries(tutorId: string): EscrowEntry[] {
+    return [...(this.escrow.get(tutorId) ?? [])];
+  }
+
+  /** Entries still locked and not yet unlockable, as of `now`. */
+  getLockedEntries(tutorId: string, now: number = Date.now()): EscrowEntry[] {
+    return this.listEntries(tutorId).filter(
+      (entry) => entry.state === 'locked' && entry.unlocksAt > now,
+    );
+  }
+
+  /**
+   * The unlock job: flips every entry past its unlock time to `unlocked`.
+   *
+   * Idempotent — already-unlocked entries are left alone. A withdrawal does
+   * not depend on this having run: it pays anything past its unlock time.
+   * Returns the entries this run unlocked.
+   */
+  releaseUnlocked(now: number = Date.now()): EscrowEntry[] {
+    const released: EscrowEntry[] = [];
+    for (const entries of this.escrow.values()) {
+      for (const entry of entries) {
+        if (entry.state === 'locked' && entry.unlocksAt <= now) {
+          entry.state = 'unlocked';
+          entry.releasedAt = now;
+          released.push(entry);
+        }
+      }
+    }
+    return released;
+  }
+
+  /**
+   * Withdraws every entry past its unlock time for a tutor.
+   *
+   * A withdrawal requested before any entry's unlock time is rejected with
+   * `ESCROW_LOCKED`, naming the earliest unlock — that is the acceptance
+   * criterion: the schedule, not the caller, decides when funds move.
+   *
+   * Payable = not yet withdrawn and past its unlock time, whether or not the
+   * unlock job has explicitly run: time is the trigger, the job is just
+   * bookkeeping.
+   */
+  withdraw(tutorId: string, now: number = Date.now()): WithdrawalResult {
+    const entries = this.escrow.get(tutorId) ?? [];
+
+    const stillLocked = entries.filter((entry) => entry.state === 'locked');
+    const payable = entries.filter(
+      (entry) => entry.state !== 'withdrawn' && entry.unlocksAt <= now,
+    );
+
+    if (payable.length === 0) {
+      if (stillLocked.length > 0) {
+        const earliestUnlockAt = Math.min(...stillLocked.map((entry) => entry.unlocksAt));
+        const msRemaining = Math.max(0, earliestUnlockAt - now);
+        throw new BadRequestException({
+          error: `Escrow is time-locked: earliest unlock at ${new Date(earliestUnlockAt).toISOString()} (${msRemaining} ms remaining)`,
+          code: 'ESCROW_LOCKED',
+          earliestUnlockAt: new Date(earliestUnlockAt).toISOString(),
+          msRemaining,
+        });
+      }
+      throw new NotFoundException(`No withdrawable escrow entries for tutor ${tutorId}`);
+    }
+
+    // Mark exactly the entries being paid out, so the balance stays accurate
+    // for later withdrawals.
+    payable.forEach((entry) => {
+      if (entry.state === 'locked') {
+        // Implicitly run the unlock step for this entry.
+        entry.releasedAt = now;
+      }
+      entry.state = 'withdrawn';
+    });
+
+    const withdrawal: WithdrawalResult = {
+      withdrawalId: `wd-${this.nextWithdrawalId++}`,
+      tutorId,
+      amountStroops: payable.reduce((total, entry) => total + entry.amountStroops, 0n),
+      entries: payable.map((entry) => ({
+        escrowId: entry.escrowId,
+        amountStroops: entry.amountStroops,
+      })),
+      withdrawnAt: now,
+    };
+    this.withdrawals.push(withdrawal);
+    return withdrawal;
+  }
+
+  /** Splits a tutor's live (not withdrawn) balance into locked vs available. */
+  getBalance(
+    tutorId: string,
+    now: number = Date.now(),
+  ): { lockedStroops: bigint; availableStroops: bigint } {
+    let lockedStroops = 0n;
+    let availableStroops = 0n;
+    for (const entry of this.listEntries(tutorId)) {
+      if (entry.state === 'withdrawn') continue;
+      if (entry.unlocksAt <= now) {
+        availableStroops += entry.amountStroops;
+      } else {
+        lockedStroops += entry.amountStroops;
+      }
+    }
+    return { lockedStroops, availableStroops };
+  }
+
+  /** Withdrawals already executed for a tutor, oldest first. */
+  listWithdrawals(tutorId: string): WithdrawalResult[] {
+    return this.withdrawals.filter((withdrawal) => withdrawal.tutorId === tutorId);
+  }
+}
diff --git a/BackendAcademy/src/users/users.module.ts b/BackendAcademy/src/users/users.module.ts
new file mode 100644
index 0000000000..5dac36b0e5
--- /dev/null
+++ b/BackendAcademy/src/users/users.module.ts
@@ -0,0 +1,17 @@
+import { Module } from '@nestjs/common';
+import { EscrowPayoutController } from './escrow-payout.controller';
+import { EscrowPayoutService } from './escrow-payout.service';
+import { TutorPayoutScheduleService } from './tutor-payout-schedule.service';
+
+/**
+ * Tutor identity, payout schedule (BE-082) and escrow payout (BE-050).
+ *
+ * EscrowPayoutService depends on TutorPayoutScheduleService so unlock times
+ * are computed by the schedule owner rather than re-derived here.
+ */
+@Module({
+  controllers: [EscrowPayoutController],
+  providers: [EscrowPayoutService, TutorPayoutScheduleService],
+  exports: [EscrowPayoutService, TutorPayoutScheduleService],
+})
+export class UsersModule {}