Deep Dive: Trading Module (pwrtrade)

Narrative

The Trading module manages the complete lifecycle of mortgage trades -- from creation through designation, settlement, and archival. A trade represents a commitment to deliver loans or securities to an investor at a specified price on a specified date. The module supports six trade type families (MBS, whole loan, best efforts, futures, eurodollar, treasury) plus options on most types.

---

Trade Lifecycle

---

Trade Types

Type	Family	Entity Types	AOTs	Pair-Offs	Cash Grid	Contract Size
MBS	mbs	Securities or Pools	Yes	Yes	No	No
Whole Loan (Mandatory)	wl	Pools	Yes	Yes	Yes	No
Whole Loan (Best Efforts)	be	Pools	No	No	Yes	No
Futures	fc	Securities	No	Yes	No	Yes
Eurodollar	euro	N/A	No	Yes	No	Yes
Treasury	ts	Securities	No	Yes	No	No
Options (all types)	varies	Pair-offs only	No	Yes	No	Varies

---

Designation Process

Cascade Designation

For bulk designation across multiple trades:

1. User sets market price and tail trade option
2. For each trade: calculate target amount based on tolerance and price comparison
3. Iterate available entities, designating up to available or remaining need
4. If tail trade requested: create phantom trade for leftover securities

---

Settlement Process

Unsettlement reverses: clears actual_settlement_date, moves loans from loan_shipped back to loan, clears pool_settle_override_date.

---

Business Rules

Designation Rules

• Securities can be split across trades (partial designated amount)
• Pools always designate at 100% (full pool amount; cannot split)
• Pair-offs must be contra-trades: sell ↔ buy of same trade type
• AOTs allowed only for MBS and mandatory WL
• An AOT cannot be undesignated if it has its own entities designated
• Settled trades are read-only (no designation changes)
• Designation date auto-sets on first entity, auto-clears when last removed

Tolerance Rules

tolerance_amount = ROUND(trade_amount * tolerance / 100, 2)
minimum_allowed = ROUND(trade_amount - tolerance_amount, 2)
maximum_allowed = ROUND(trade_amount + tolerance_amount, 2)

• Above-tolerance designation is a hard block (cannot save)
• Below-tolerance designation is a warning (user can proceed)
• Tolerance auto-computes from instrument or system default
• variance_override = 'y' skips auto-computation
• Tolerance capped at 999.999999 to prevent overflow
• Only applies to MBS, WL, BE sell trades that are unsettled

Settlement Rules

• Phantom trades cannot be settled
• Trades with no designated entities cannot be settled
• Out-of-tolerance trades can settle with user confirmation
• WL settlement: loans move from loan to loan_shipped
• Security settlement: only when security is 100% designated to settled trades

Contract Size Rules (Futures/Eurodollar)

trade_amount = num_contracts * contract_size

• Validated that trade_amount % contract_size == 0

---

Key Calculations

Designated Amount

total_designated = SUM(security designations) + SUM(pool designations)
                 + SUM(pair-off amounts) + SUM(AOT amounts)

Notification Date

notification_date = settlement_date - 2 business days
(skips weekends and holidays)

Cash Grid Pricing (WL Trades)

• Grid type: note (use note rate) or pass (note rate - servicing fee)
• Each loan's effective rate is matched to cash grid rate tiers
• Unmatched loans are priced at the next lowest rate tier

Margin Activity

• Margin activity is tracked in pscat_margin_activity
• Margin threshold and minimum transfer amount are per-counterparty
• Margin calculations compare mark-to-market values against limits

---

Data Model

Table	Purpose
pscat_trades	Master trade records
pscat_trades_securities_rel	Trade-to-security designation junction
pscat_trades_pools_relation	Trade-to-pool designation junction
pscat_pair_offs	Pair-off trade designations
pscat_trades_assignments	AOT trade assignments
pscat_trades_rollover_rel	Rollover relationship tree
pscat_trades_builder_rel	Eurodollar trade builder relationships
pscat_trade_cash_grid	Trade-specific cash grid data
pscat_cash_grid_syntax	Cash grid syntax definitions
pscat_securities	Security definitions
pscat_pools	Pool definitions
pscat_pool_security_relation	Pool-to-security junction
pscat_instruments	Instrument configuration
pscat_trade_counterparties	Investor/counterparty records
pscat_margin_activity	Margin call tracking
pscat_current_values	System defaults (tolerance)
loan	Active loans (pre-settlement)
loan_shipped	Settled loans (post-settlement)

Key NVOs

NVO	Purpose
n_cst_trades	Core trade logic: designation, tolerance, settlement, rollover
n_cst_securities	Security logic: pool balances, designation checks
n_cst_trades_cash_grids	WL cash grid pricing: rate matching, servicing fee calc