Merge pull request #438 from memplethee-lab/feat/Options

Feat(Feature):  Options & Derivatives Contract Module

Author: DevMuhdishaq

src/app.module.ts

@@ -102,6 +102,13 @@ import { SocialTradingModule } from './social-trading/social-trading.module';
 import { TraderProfile } from './social-trading/entities/trader-profile.entity';
 import { CopySubscription } from './social-trading/entities/copy-subscription.entity';
 
+// Options & Derivatives (hedging, speculation, pricing)
+import { OptionsDerivativesModule } from './options-derivatives/options-derivatives.module';
+import { OptionContract } from './options-derivatives/entities/option-contract.entity';
+import { OptionPosition } from './options-derivatives/entities/option-position.entity';
+import { OptionCollateral } from './options-derivatives/entities/option-collateral.entity';
+import { VolatilitySurface } from './options-derivatives/entities/volatility-surface.entity';
+
 // Escrow & Settlement (atomic escrow, refunds, dispute hooks)
 import { EscrowSettlementModule } from './escrow-settlement/escrow-settlement.module';
 import { EscrowAccount } from './escrow-settlement/entities/escrow-account.entity';
@@ -211,6 +218,11 @@ import { TradingModule } from './trading/trading.module';
           MarginPairConfig,
           MarginPosition,
           MarginInterestAccrual,
+          // Options & Derivatives
+          OptionContract,
+          OptionPosition,
+          OptionCollateral,
+          VolatilitySurface,
           // Wallet & Payments Integration
           WalletLedger,
           LedgerEntry,
@@ -266,6 +278,9 @@ import { TradingModule } from './trading/trading.module';
 
     // ── Escrow & Settlement ──
     EscrowSettlementModule,
+    // ── Options & Derivatives ──
+    OptionsDerivativesModule,
+
     // ── Wallet & Payments Integration ──
     WalletModule,
     TradingModule,

src/options-derivatives/dto/buy-option.dto.ts

@@ -0,0 +1,15 @@
+import { IsInt, IsPositive, IsNumber, Min } from 'class-validator';
+
+export class BuyOptionDto {
+  @IsInt()
+  @IsPositive()
+  contractId: number;
+
+  @IsInt()
+  @IsPositive()
+  userId: number;
+
+  @IsNumber()
+  @Min(1)
+  quantity: number;
+}

src/options-derivatives/dto/create-option-contract.dto.ts

@@ -0,0 +1,63 @@
+import {
+  IsEnum,
+  IsInt,
+  IsNumber,
+  IsOptional,
+  IsPositive,
+  Min,
+  Max,
+} from 'class-validator';
+import { OptionType } from '../enums/option-type.enum';
+import { ExerciseStyle } from '../enums/exercise-style.enum';
+
+export class CreateOptionContractDto {
+  @IsEnum(OptionType)
+  optionType: OptionType;
+
+  @IsOptional()
+  @IsEnum(ExerciseStyle)
+  exerciseStyle?: ExerciseStyle;
+
+  @IsInt()
+  @IsPositive()
+  underlyingAssetId: number;
+
+  @IsNumber()
+  @IsPositive()
+  strikePrice: number;
+
+  @IsNumber()
+  @Min(1)
+  contractSize: number;
+
+  @IsOptional()
+  @IsNumber()
+  @IsPositive()
+  underlyingPrice?: number;
+
+  /** ISO date string for expiration. */
+  expirationDate: string;
+
+  @IsOptional()
+  @IsNumber()
+  @Min(0.01)
+  @Max(5)
+  impliedVolatility?: number;
+
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Max(0.25)
+  riskFreeRate?: number;
+
+  /** Number of contracts to mint. */
+  @IsOptional()
+  @IsNumber()
+  @Min(1)
+  totalSupply?: number;
+
+  /** Asset ID for collateral (for writers). */
+  @IsOptional()
+  @IsInt()
+  collateralAssetId?: number;
+}

src/options-derivatives/dto/exercise-option.dto.ts

@@ -0,0 +1,21 @@
+import { IsInt, IsPositive, IsNumber, IsOptional, Min } from 'class-validator';
+
+export class ExerciseOptionDto {
+  @IsInt()
+  @IsPositive()
+  contractId: number;
+
+  @IsInt()
+  @IsPositive()
+  userId: number;
+
+  /** Number of contracts to exercise. */
+  @IsNumber()
+  @Min(1)
+  quantity: number;
+
+  /** Current market price of underlying (used for settlement). */
+  @IsNumber()
+  @IsPositive()
+  currentPrice: number;
+}

src/options-derivatives/dto/update-volatility.dto.ts

@@ -0,0 +1,31 @@
+import { IsInt, IsPositive, IsNumber, IsOptional, Min, Max } from 'class-validator';
+
+export class UpdateVolatilityDto {
+  @IsInt()
+  @IsPositive()
+  assetId: number;
+
+  @IsNumber()
+  @IsPositive()
+  strikePrice: number;
+
+  /** ISO date string for expiration. */
+  expirationDate: string;
+
+  @IsNumber()
+  @Min(0.01)
+  @Max(10)
+  impliedVolatility: number;
+
+  @IsOptional()
+  @IsNumber()
+  bidIv?: number;
+
+  @IsOptional()
+  @IsNumber()
+  askIv?: number;
+
+  @IsOptional()
+  @IsNumber()
+  lastTradedIv?: number;
+}

src/options-derivatives/entities/option-collateral.entity.ts

@@ -0,0 +1,67 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  ManyToOne,
+  JoinColumn,
+  Index,
+  CreateDateColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import { OptionContract } from './option-contract.entity';
+import { VirtualAsset } from '../../database/entities/virtual-asset.entity';
+import { CollateralStatus } from '../enums/collateral-status.enum';
+
+@Entity('option_collaterals')
+@Index(['contractId', 'userId'])
+@Index(['userId', 'status'])
+export class OptionCollateral {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column()
+  @Index()
+  contractId: number;
+
+  @ManyToOne(() => OptionContract)
+  @JoinColumn({ name: 'contractId' })
+  contract: OptionContract;
+
+  @Column()
+  @Index()
+  userId: number;
+
+  @Column()
+  collateralAssetId: number;
+
+  @ManyToOne(() => VirtualAsset)
+  @JoinColumn({ name: 'collateralAssetId' })
+  collateralAsset: VirtualAsset;
+
+  /** Total amount of collateral locked. */
+  @Column('decimal', { precision: 18, scale: 8 })
+  lockedAmount: number;
+
+  /** Amount still locked (decreases as contracts are exercised/expired). */
+  @Column('decimal', { precision: 18, scale: 8 })
+  remainingAmount: number;
+
+  /** Number of contracts covered by this collateral. */
+  @Column('decimal', { precision: 18, scale: 8, default: 0 })
+  coveredContracts: number;
+
+  @Column({ type: 'varchar', default: CollateralStatus.LOCKED })
+  status: CollateralStatus;
+
+  @Column({ nullable: true })
+  lockedAt: Date;
+
+  @Column({ nullable: true })
+  releasedAt: Date;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}

src/options-derivatives/entities/option-contract.entity.ts

@@ -0,0 +1,104 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  ManyToOne,
+  JoinColumn,
+  Index,
+  CreateDateColumn,
+  UpdateDateColumn,
+} from 'typeorm';
+import { VirtualAsset } from '../../database/entities/virtual-asset.entity';
+import { OptionType } from '../enums/option-type.enum';
+import { OptionStatus } from '../enums/option-status.enum';
+import { ExerciseStyle } from '../enums/exercise-style.enum';
+
+@Entity('option_contracts')
+@Index(['underlyingAssetId', 'expirationDate'])
+@Index(['status', 'expirationDate'])
+export class OptionContract {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column({ type: 'varchar' })
+  optionType: OptionType;
+
+  @Column({ type: 'varchar', default: ExerciseStyle.EUROPEAN })
+  exerciseStyle: ExerciseStyle;
+
+  @Column()
+  @Index()
+  underlyingAssetId: number;
+
+  @ManyToOne(() => VirtualAsset)
+  @JoinColumn({ name: 'underlyingAssetId' })
+  underlyingAsset: VirtualAsset;
+
+  /** Strike price in quote asset units. */
+  @Column('decimal', { precision: 18, scale: 8 })
+  strikePrice: number;
+
+  @Column({ type: 'datetime' })
+  expirationDate: Date;
+
+  /** Contract size = number of underlying units per contract. */
+  @Column('decimal', { precision: 18, scale: 8, default: 1 })
+  contractSize: number;
+
+  /** Current market price of the underlying at creation. */
+  @Column('decimal', { precision: 18, scale: 8 })
+  underlyingPriceAtCreation: number;
+
+  /** Option premium per unit. */
+  @Column('decimal', { precision: 18, scale: 8 })
+  premium: number;
+
+  /** Implied volatility used for pricing (annualized). */
+  @Column('decimal', { precision: 10, scale: 8, default: 0.3 })
+  impliedVolatility: number;
+
+  /** Risk-free interest rate used for pricing. */
+  @Column('decimal', { precision: 10, scale: 8, default: 0.05 })
+  riskFreeRate: number;
+
+  /** Delta — option sensitivity to underlying price. */
+  @Column('decimal', { precision: 10, scale: 8, default: 0 })
+  delta: number;
+
+  /** Gamma — rate of change of delta. */
+  @Column('decimal', { precision: 10, scale: 8, default: 0 })
+  gamma: number;
+
+  /** Vega — sensitivity to volatility changes. */
+  @Column('decimal', { precision: 10, scale: 8, default: 0 })
+  vega: number;
+
+  /** Theta — time decay. */
+  @Column('decimal', { precision: 10, scale: 8, default: 0 })
+  theta: number;
+
+  /** Rho — sensitivity to interest rate changes. */
+  @Column('decimal', { precision: 10, scale: 8, default: 0 })
+  rho: number;
+
+  /** Total contracts available (initial supply). */
+  @Column('decimal', { precision: 18, scale: 8, default: 0 })
+  totalSupply: number;
+
+  /** Contracts still outstanding (unsold + unexercised). */
+  @Column('decimal', { precision: 18, scale: 8, default: 0 })
+  openInterest: number;
+
+  /** Whether option was in-the-money at last check. */
+  @Column({ default: false })
+  inTheMoney: boolean;
+
+  @Column({ type: 'varchar', default: OptionStatus.ACTIVE })
+  status: OptionStatus;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}