Generic Structured Investment Products (SIP) Engine

[Josephrp]

Type: Feature
Priority: P1 (High)
Labels: feature, backend, frontend, trading, structured-products
Epic: #XXX (Epic: Complete Remaining Features)
Estimated Effort: 3 weeks

---

Description

Implement a generic Structured Investment Products (SIP) engine for equity-linked notes, barrier options, and other structured financial products. Note: Securitization pools are fully implemented separately.

Current State:

• ✅ SecuritizationToken.sol contract exists (ERC-721 for tranches)
• ✅ SecuritizationNotarization.sol contract exists
• ✅ SecuritizationService fully implemented
• ✅ StructuredProductsTab.tsx fully implemented (for securitization pools: ABS, CLO, MBS, equity bundles, commodity bundles)
• ❌ StructuredProductTemplate model missing (for equity-linked notes, barrier options)
• ❌ StructuredProductInstance model missing
• ❌ ProductSubscription model missing
• ❌ StructuredProductsService missing (generic SIP pricing/issuance, not securitization)

Target State:

• Generic SIP templates (equity-linked notes, barrier options, buffer notes)
• Product instance issuance
• Investor subscriptions
• Pricing engine (Black-Scholes, Monte Carlo)
• Alpaca replication
• Blockchain tracking

Related Plan

dev/EPIC_IMPLEMENTATION_PLAN.md - Priority 4

Sub-Tasks

Database Models

• Create StructuredProductTemplate Model (app/db/models.py)

  • name, product_type (String): equity_linked_note, barrier_option, buffer_note
  • underlying_symbol (String)
  • payoff_formula (JSONB): Payoff definition
  • maturity_days (Integer)
  • principal, fees (Numeric)
  • created_by (Integer, FK to users.id)
  • is_active (Boolean)

• Create StructuredProductInstance Model

  • template_id (Integer, FK)
  • issuer_user_id (Integer, FK)
  • total_notional (Numeric)
  • issue_date, maturity_date (Date)
  • status (String): active, matured, cancelled
  • replication_trades (JSONB): Alpaca order IDs
  • current_value (Numeric)

• Create ProductSubscription Model

  • instance_id (Integer, FK)
  • investor_user_id (Integer, FK)
  • subscription_amount (Numeric)
  • subscription_date (Date)
  • status (String): pending, active, matured, cancelled

• Create Alembic Migration

  • Create all three tables
  • Add foreign keys and indexes

Backend Services

• Create StructuredProductsService (app/services/structured_products_service.py)

  • create_template() - Create product template
  • issue_product() - Issue product instance
  • price_product() - Calculate product pricing (Black-Scholes, Monte Carlo)
  • replicate_via_alpaca() - Create Alpaca trades for replication
  • subscribe() - Investor subscription
  • calculate_current_value() - Real-time valuation

• Enhance SecuritizationService (optional integration)

  • Link StructuredProductInstance to SecuritizationPool
  • Notarize product instances on blockchain

Frontend

• Update StructuredProductsTab (client/src/components/trading/StructuredProductsTab.tsx)

  • Add generic SIP tab/section (currently only securitization)
  • List available product templates
  • Create new template (structurer role)
  • Browse product instances
  • Subscribe to products (investor role)

• Create ProductTemplateForm (client/src/components/trading/ProductTemplateForm.tsx)

  • Product type selection
  • Underlying asset selection
  • Payoff formula configuration
  • Pricing preview

• Create ProductInstanceView (client/src/components/trading/ProductInstanceView.tsx)

  • Product details
  • Current value display
  • Performance chart
  • Subscription management

• Create ProductSubscriptionForm (client/src/components/trading/ProductSubscriptionForm.tsx)

  • Subscription amount input
  • Terms and conditions
  • Payment processing

API Endpoints

• Create Structured Products API (app/api/structured_products_routes.py)
  • POST /api/structured-products/templates - Create template
  • GET /api/structured-products/templates - List templates
  • POST /api/structured-products/instances - Issue product
  • GET /api/structured-products/instances - List instances
  • POST /api/structured-products/instances/{id}/subscribe - Subscribe
  • GET /api/structured-products/instances/{id}/pricing - Get pricing

Acceptance Criteria

1. ✅ Structurers can create SIP templates
2. ✅ Products can be issued to investors
3. ✅ Pricing engine calculates fair value
4. ✅ Products replicated via Alpaca trades
5. ✅ Subscriptions tracked and managed
6. ✅ Real-time valuation available
7. ✅ Blockchain tracking for product instances

Dependencies

• Alpaca Trading API (✅ Already implemented)
• Securitization system (for optional blockchain tracking)
• Pricing libraries (Black-Scholes, Monte Carlo)

Testing

• Unit tests for StructuredProductsService
• Integration tests for product creation and issuance
• Test pricing calculations
• Test Alpaca replication
• Test subscription flow

---

Created: 2026-01-26
Status: Open