feat: implement ledger-bounded policy renewal with premium recalc, claim enforcement, and event emission

Author: GoodnessJohn

backend/src/policy/dto/renewal.dto.ts

@@ -0,0 +1,149 @@
+import {
+  IsString,
+  IsNotEmpty,
+  IsInt,
+  IsPositive,
+  IsOptional,
+  Min,
+  Max,
+  IsIn,
+} from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import type { PolicyTypeEnum, RegionTierEnum } from '../../rpc/soroban.service';
+
+export class BuildRenewalTransactionDto {
+  @ApiProperty({ description: 'Stellar address of the policyholder', example: 'GABC...' })
+  @IsString()
+  @IsNotEmpty()
+  holder!: string;
+
+  @ApiProperty({ description: 'Per-holder monotonic policy ID (u32)', example: 1 })
+  @Type(() => Number)
+  @IsInt()
+  @IsPositive()
+  policy_id!: number;
+
+  /**
+   * Age is required to deterministically recalculate the renewal premium using
+   * the same on-chain formula as policy initiation. Must match the original
+   * policy parameters to avoid premium manipulation.
+   */
+  @ApiProperty({ description: 'Policyholder age (must match original policy)', example: 35 })
+  @Type(() => Number)
+  @IsInt()
+  @Min(18)
+  @Max(120)
+  age!: number;
+
+  /**
+   * Risk score [0–100] used in the premium formula. Must be provided by the
+   * caller and validated against the original policy to prevent replay attacks
+   * where a lower risk score is substituted to reduce the renewal premium.
+   */
+  @ApiProperty({ description: 'Risk score 0–100 (must match original policy)', example: 5 })
+  @Type(() => Number)
+  @IsInt()
+  @Min(0)
+  @Max(100)
+  risk_score!: number;
+
+  /**
+   * Optional override for renewal duration in ledgers.
+   * Defaults to POLICY_DURATION_LEDGERS (~1 year) if omitted.
+   */
+  @ApiPropertyOptional({ description: 'Renewal duration in ledgers (default: ~1 year)', example: 6307200 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @IsPositive()
+  duration_ledgers?: number;
+
+  /**
+   * SEP-41 asset contract ID for premium payment.
+   * Must match the asset bound to the original policy (assetContractId).
+   * Omit to use the policy's existing asset.
+   */
+  @ApiPropertyOptional({ description: 'SEP-41 asset contract ID (defaults to policy asset)' })
+  @IsOptional()
+  @IsString()
+  asset?: string;
+}
+
+export class RenewalQuoteResponseDto {
+  @ApiProperty({ description: 'Renewal premium in stroops (i128 as string)', example: '50000000' })
+  premiumStroops!: string;
+
+  @ApiProperty({ description: 'Renewal premium in XLM', example: '5.0000000' })
+  premiumXlm!: string;
+
+  @ApiProperty({ description: 'Previous policy expiry ledger', example: 1000000 })
+  previousEndLedger!: number;
+
+  @ApiProperty({ description: 'New policy expiry ledger after renewal', example: 7307200 })
+  newEndLedger!: number;
+
+  @ApiProperty({ description: 'Current ledger at time of quote', example: 950000 })
+  currentLedger!: number;
+
+  @ApiProperty({ description: 'Ledger at which the renewal window opened', example: 879040 })
+  windowOpenLedger!: number;
+
+  @ApiProperty({ description: 'Exclusive ledger at which the renewal window closes', example: 1017280 })
+  windowCloseLedger!: number;
+
+  @ApiProperty({ description: 'Whether the premium was computed on-chain or via local fallback' })
+  premiumSource!: 'simulation' | 'local_fallback';
+}
+
+export class BuildRenewalTransactionResponseDto extends RenewalQuoteResponseDto {
+  @ApiProperty({ description: 'Base64-encoded unsigned transaction XDR for wallet signing' })
+  unsignedXdr!: string;
+
+  @ApiProperty({ description: 'Minimum resource fee in stroops' })
+  minResourceFee!: string;
+
+  @ApiProperty({ description: 'Base fee in stroops' })
+  baseFee!: string;
+
+  @ApiProperty({ description: 'Total estimated fee in stroops' })
+  totalEstimatedFee!: string;
+
+  @ApiProperty({ description: 'Total estimated fee in XLM' })
+  totalEstimatedFeeXlm!: string;
+
+  @ApiProperty({ description: 'Addresses that must sign Soroban auth entries' })
+  authRequirements!: Array<{ address: string; isContract: boolean }>;
+
+  @ApiProperty({ description: 'Memo convention note' })
+  memoConvention!: string;
+}
+
+/**
+ * PolicyRenewed event payload — emitted exactly once per successful renewal.
+ * Structured for off-chain indexing and timeline UIs.
+ *
+ * EVENT INTEGRITY:
+ *   - Emitted only after the unsigned transaction is successfully assembled.
+ *   - Contains previousEndLedger and newEndLedger for timeline reconstruction.
+ *   - termVersion allows UIs to detect term changes between renewal cycles.
+ *   - premiumPaidStroops enables cumulative premium tracking with checked arithmetic.
+ */
+export interface PolicyRenewedEvent {
+  /** Composite policy key: holderAddress:policyId */
+  policyCompositeId: string;
+  holderAddress: string;
+  policyId: number;
+  /** Ledger at which the previous term expired (inclusive end of old term). */
+  previousEndLedger: number;
+  /** Ledger at which the new term expires (inclusive end of new term). */
+  newEndLedger: number;
+  /** Renewal premium in stroops (i128 as string) — use BigInt for arithmetic. */
+  premiumPaidStroops: string;
+  /** Term version hash or identifier, if the policy terms changed at renewal. */
+  termVersion: string | null;
+  /** Ledger at which the renewal was requested (for audit trail). */
+  renewalRequestedAtLedger: number;
+  /** ISO-8601 wall-clock timestamp of the renewal request (approximate). */
+  renewalRequestedAt: string;
+}

backend/src/policy/policy.module.ts

@@ -1,11 +1,14 @@
 import { Module } from '@nestjs/common';
 import { PolicyController } from './policy.controller';
 import { PolicyService } from './policy.service';
+import { RenewalController } from './renewal.controller';
+import { RenewalService } from './renewal.service';
 import { RpcModule } from '../rpc/rpc.module';
 
 @Module({
   imports: [RpcModule],
-  controllers: [PolicyController],
-  providers: [PolicyService],
+  controllers: [PolicyController, RenewalController],
+  providers: [PolicyService, RenewalService],
+  exports: [RenewalService],
 })
 export class PolicyModule {}

backend/src/policy/renewal.constants.ts

@@ -0,0 +1,87 @@
+/**
+ * Ledger-bounded renewal window constants.
+ *
+ * RENEWAL WINDOW SEMANTICS
+ * ─────────────────────────────────────────────────────────────────────────────
+ * A renewal is valid when the current ledger falls within the half-open interval:
+ *
+ *   [policy.endLedger - RENEWAL_OPEN_LEDGERS_BEFORE_EXPIRY,
+ *    policy.endLedger + RENEWAL_GRACE_LEDGERS_AFTER_EXPIRY)
+ *
+ * Inclusive lower bound:
+ *   currentLedger >= policy.endLedger - RENEWAL_OPEN_LEDGERS_BEFORE_EXPIRY
+ *   Renewals attempted before this ledger are rejected with RENEWAL_TOO_EARLY.
+ *
+ * Exclusive upper bound:
+ *   currentLedger < policy.endLedger + RENEWAL_GRACE_LEDGERS_AFTER_EXPIRY
+ *   Renewals attempted at or after this ledger are rejected with RENEWAL_TOO_LATE.
+ *   The upper bound is exclusive so that a policy expiring at ledger N and a
+ *   grace period of G means the last valid renewal ledger is N+G-1.
+ *
+ * LEDGER TIME ASSUMPTIONS
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Stellar closes a ledger approximately every 5 seconds (SECONDS_PER_LEDGER).
+ * This is a statistical average; individual ledger close times vary ±1–2 s.
+ *
+ * SERVER-CLIENT SKEW CONSIDERATIONS
+ * ─────────────────────────────────────────────────────────────────────────────
+ * The backend fetches the authoritative ledger sequence from the Soroban RPC
+ * (server.getLatestLedger()) and uses that for all window checks.
+ *
+ * Frontend countdown UIs should:
+ *   1. Fetch currentLedger from GET /health or a dedicated /ledger endpoint.
+ *   2. Compute estimated wall-clock time as:
+ *        remainingLedgers * SECONDS_PER_LEDGER seconds
+ *   3. Add a UI buffer of ~2 ledgers (~10 s) to account for RPC propagation
+ *      lag and the time between the user clicking "Renew" and the backend
+ *      receiving the request.
+ *   4. Never rely on Date.now() alone — ledger sequence is the canonical clock.
+ *
+ * The backend does NOT add any skew buffer; it enforces the window exactly as
+ * defined by the constants below. Frontends should open the renewal UI slightly
+ * before RENEWAL_OPEN_LEDGERS_BEFORE_EXPIRY to absorb network latency.
+ */
+
+/** Approximate ledger close time in seconds (Stellar mainnet/testnet average). */
+export const SECONDS_PER_LEDGER = 5;
+
+/**
+ * Standard policy duration in ledgers (~1 year at 5 s/ledger).
+ * 365 days × 24 h × 3600 s / 5 s = 6,307,200 ledgers.
+ */
+export const POLICY_DURATION_LEDGERS = 6_307_200;
+
+/**
+ * How many ledgers before policy.endLedger the renewal window opens.
+ * Inclusive lower bound: currentLedger >= endLedger - RENEWAL_OPEN_LEDGERS_BEFORE_EXPIRY.
+ *
+ * Default: 120,960 ledgers ≈ 7 days (120,960 × 5 s = 604,800 s).
+ */
+export const RENEWAL_OPEN_LEDGERS_BEFORE_EXPIRY = 120_960;
+
+/**
+ * How many ledgers after policy.endLedger the grace window closes.
+ * Exclusive upper bound: currentLedger < endLedger + RENEWAL_GRACE_LEDGERS_AFTER_EXPIRY.
+ *
+ * Default: 17,280 ledgers ≈ 1 day (17,280 × 5 s = 86,400 s).
+ * The last valid renewal ledger is endLedger + RENEWAL_GRACE_LEDGERS_AFTER_EXPIRY - 1.
+ */
+export const RENEWAL_GRACE_LEDGERS_AFTER_EXPIRY = 17_280;
+
+/**
+ * Claim states that block renewal.
+ *
+ * OPEN-CLAIM RULE (product specification):
+ *   A policy with a claim in PENDING status (on-chain: "Processing") cannot be
+ *   renewed until the claim is finalized (APPROVED, PAID, or REJECTED).
+ *
+ *   Rationale: allowing renewal while a claim is unresolved creates ambiguity
+ *   about which policy term covers the outstanding liability. The contract
+ *   enforces this on-chain; the backend mirrors it to provide early rejection
+ *   with a clear error code before building an unsigned transaction.
+ *
+ *   APPROVED claims are NOT blocking: the claim has been decided; only payment
+ *   disbursement is pending, which does not affect the new policy term.
+ */
+export const BLOCKING_CLAIM_STATUSES = ['PENDING'] as const;
+export type BlockingClaimStatus = (typeof BLOCKING_CLAIM_STATUSES)[number];

backend/src/policy/renewal.controller.ts

@@ -0,0 +1,56 @@
+import { Controller, Post, Body, HttpCode, HttpStatus } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
+import { Throttle } from '@nestjs/throttler';
+import { RenewalService } from './renewal.service';
+import { BuildRenewalTransactionDto } from './dto/renewal.dto';
+
+@ApiTags('Policy')
+@Controller('policy')
+export class RenewalController {
+  constructor(private readonly renewalService: RenewalService) {}
+
+  /**
+   * POST /api/policy/renewal/quote
+   *
+   * Returns a renewal premium quote and window metadata without building a
+   * transaction. Safe to call repeatedly — no side effects.
+   *
+   * Errors: POLICY_NOT_FOUND, POLICY_INACTIVE, RENEWAL_TOO_EARLY,
+   *         RENEWAL_TOO_LATE, OPEN_CLAIM_BLOCKS_RENEWAL
+   */
+  @Post('renewal/quote')
+  @HttpCode(HttpStatus.OK)
+  @Throttle({ default: { limit: 30, ttl: 60_000 } })
+  @ApiOperation({ summary: 'Get renewal premium quote and window metadata' })
+  @ApiResponse({ status: 200, description: 'Renewal quote with window ledgers and premium' })
+  @ApiResponse({ status: 400, description: 'Window violation or open claim' })
+  @ApiResponse({ status: 404, description: 'Policy not found' })
+  @ApiResponse({ status: 429, description: 'Rate limited' })
+  async quoteRenewal(@Body() dto: BuildRenewalTransactionDto) {
+    return this.renewalService.quoteRenewal(dto);
+  }
+
+  /**
+   * POST /api/policy/renewal/build-transaction
+   *
+   * Returns unsigned XDR for Freighter / wallet-kit to sign.
+   * Emits a PolicyRenewed event exactly once on success.
+   * Rate-limited (10 req/min) to protect Soroban RPC quotas.
+   *
+   * Errors: POLICY_NOT_FOUND, POLICY_INACTIVE, RENEWAL_TOO_EARLY,
+   *         RENEWAL_TOO_LATE, OPEN_CLAIM_BLOCKS_RENEWAL, PREMIUM_OVERFLOW,
+   *         ACCOUNT_NOT_FOUND, CONTRACT_NOT_DEPLOYED, SIMULATION_FAILED
+   */
+  @Post('renewal/build-transaction')
+  @HttpCode(HttpStatus.OK)
+  @Throttle({ default: { limit: 10, ttl: 60_000 } })
+  @ApiOperation({ summary: 'Build unsigned renew_policy transaction' })
+  @ApiResponse({ status: 200, description: 'Unsigned XDR + fee estimates + renewal metadata' })
+  @ApiResponse({ status: 400, description: 'Window violation, open claim, or simulation error' })
+  @ApiResponse({ status: 404, description: 'Policy not found' })
+  @ApiResponse({ status: 429, description: 'Rate limited — protects RPC quotas' })
+  @ApiResponse({ status: 503, description: 'Contract not deployed or RPC unavailable' })
+  async buildRenewalTransaction(@Body() dto: BuildRenewalTransactionDto) {
+    return this.renewalService.buildRenewalTransaction(dto);
+  }
+}