@optionsfi/sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to the OptionsFi SDK will be documented in this file.
+
+## [0.2.0] - 2025-12-30
+
+### Added - Multi-Asset Support
+
+#### New Types
+- `AssetType`: Classification for crypto, tokenized_stock, and tokenized_treasury
+- `AssetDescriptor`: Complete asset metadata with price feeds and trading hours
+- `AssetRegistryEntry`: Asset descriptor with activation status
+- `AssetVolatility`: Volatility data structure for assets
+- `PriceFeedSource`: Enum for pyth, yahoo, switchboard, or custom feeds
+- `TradingHours`: Trading hours configuration for market-hours assets
+- `CorporateAction`: Corporate action tracking for tokenized stocks
+
+#### RFQ Enhancements
+- `RFQParams.anonymous`: Optional anonymization of vault identity in RFQ broadcasts
+- `RFQParams.minQuotes`: Configurable minimum number of quotes required before filling
+- `RFQParams.quoteTimeout`: Customizable timeout for quote collection periods
+- `Quote.validUntil`: Quote expiration timestamp for improved validation
+
+#### Asset Utilities
+- `createCryptoAsset()`: Helper for creating crypto asset descriptors
+- `createTokenizedStockAsset()`: Helper for tokenized stock descriptors
+- `createTokenizedTreasuryAsset()`: Helper for treasury descriptors
+- `validateAssetDescriptor()`: Validate asset descriptor completeness
+- `canCreateRFQ()`: Check if RFQ can be created (respects trading hours)
+- `isWithinTradingHours()`: Check if asset is within trading hours
+- `getUSEquityTradingHours()`: Default US equity market hours
+
+### Changed
+
+#### RFQ System Improvements
+- Enhanced multi-dealer quote collection with configurable thresholds
+- Improved quote expiry validation and lifecycle management
+- Better duplicate quote handling with automatic updates
+- Ranked quote responses for improved price transparency
+- Comprehensive status tracking (open, filled, expired, no_valid_quotes)
+- New polling endpoint for asynchronous quote collection workflows
+
+### Migration Guide
+
+#### For Existing Users
+
+No breaking changes. All new fields are optional and backward compatible.
+
+**Using Multi-Asset Support:**
+
+```typescript
+import { 
+  createCryptoAsset, 
+  createTokenizedStockAsset,
+  canCreateRFQ 
+} from '@optionsfi/sdk';
+
+// Create asset descriptors
+const solAsset = createCryptoAsset({
+  assetId: 'SOL',
+  name: 'Solana',
+  ticker: 'SOL',
+  mintAddress: 'So11111111111111111111111111111111111111112',
+  decimals: 9,
+  pythFeedId: '0xef0d8...'
+});
+
+const nvdaAsset = createTokenizedStockAsset({
+  assetId: 'NVDAX',
+  name: 'NVIDIA Token',
+  ticker: 'NVDAX',
+  mintAddress: 'G5VWnn...',
+  decimals: 6,
+  yahooTicker: 'NVDA'
+});
+
+// Check if RFQ can be created
+const { allowed, reason } = canCreateRFQ(nvdaAsset);
+if (!allowed) {
+  console.log(`Cannot create RFQ: ${reason}`);
+}
+```
+
+**Using Anonymous RFQs:**
+
+```typescript
+const rfqId = await rfqClient.createRFQ({
+  asset: 'NVDAX',
+  side: 'sell',
+  optionType: 'call',
+  strike: 150,
+  expiry: Math.floor(Date.now() / 1000) + 86400,
+  quantity: 100n * 10n**6n,
+  vaultAddress: myVault.toString(),
+  anonymous: true, // Vault address will be hidden from market makers
+  minQuotes: 3,    // Wait for at least 3 quotes
+  quoteTimeout: 45000 // 45 second timeout
+});
+```
+
+## [0.1.0] - 2024-12-26
+
+### Added
+- Initial SDK release
+- RFQClient for quote management
+- VaultInstructions for on-chain operations
+- OptionPricing utilities (Black-Scholes)
+- Validation and formatting utilities
+- TypeScript support
+- Comprehensive test suite
+
+[0.2.0]: https://github.com/optionsfi/optionsfi/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/optionsfi/optionsfi/releases/tag/v0.1.0

package/MIGRATION.md

@@ -0,0 +1,56 @@
+# Migration Guide for v0.2.0
+
+## Breaking Changes
+
+### Renamed Constants
+
+The following constants have been renamed for clarity:
+
+| Old Name | New Name | Reason |
+|----------|----------|--------|
+| `MOCK_USDC_MINT` | `DEVNET_USDC_MINT` | Clarifies this is official devnet USDC, not a mock |
+
+### New Exports
+
+- `MAINNET_USDC_MINT` - Official Circle USDC mint for mainnet-beta
+
+## Migration Steps
+
+### If you were using MOCK_USDC_MINT
+
+**Before (v0.1.0):**
+```typescript
+import { MOCK_USDC_MINT } from '@optionsfi/sdk';
+
+const usdcMint = MOCK_USDC_MINT;
+```
+
+**After (v0.2.0):**
+```typescript
+import { DEVNET_USDC_MINT, MAINNET_USDC_MINT } from '@optionsfi/sdk';
+
+// For devnet
+const usdcMint = DEVNET_USDC_MINT;
+
+// For mainnet
+const usdcMint = MAINNET_USDC_MINT;
+```
+
+## Repository Changes
+
+The SDK repository has been transferred to the OptionsFi organization:
+
+- **Old URL**: `https://github.com/feeniks01/optionsfi`
+- **New URL**: `https://github.com/optionsfi/optionsfi`
+
+All issue links, documentation links, and repository references have been updated.
+
+## No Other Breaking Changes
+
+All other APIs remain backward compatible. New features:
+- Multi-asset support (crypto, tokenized stocks, treasuries)
+- Anonymous RFQ support
+- Enhanced multi-dealer quote collection
+- Trading hours configuration (optional)
+
+See [CHANGELOG.md](./CHANGELOG.md) for full details.

package/README.md

@@ -0,0 +1,227 @@
+# @optionsfi/sdk
+
+TypeScript SDK for OptionsFi, a decentralized options settlement protocol built on Solana. Enables developers to build applications with covered call vaults, RFQ-based options trading, and support for multiple asset types.
+
+## Features
+
+- 🌐 **Multi-Asset Support** - Trade options on crypto, tokenized stocks, and tokenized treasuries
+- 🔌 **RFQ System** - Request quotes from multiple market makers with competitive pricing
+- 📊 **Options Pricing** - Black-Scholes calculations with Greeks and volatility tools
+- 🏦 **Vault Operations** - Interact with on-chain covered call vaults
+- 🔒 **Anonymous RFQs** - Privacy-preserving quote requests for large institutional flows
+- ✅ **Type-Safe** - Comprehensive TypeScript types with runtime validation
+
+## Installation
+
+```bash
+npm install @optionsfi/sdk
+# or
+yarn add @optionsfi/sdk
+# or
+pnpm add @optionsfi/sdk
+```
+
+**Peer Dependencies:**
+
+```bash
+npm install @coral-xyz/anchor @solana/web3.js
+```
+
+These allow you to use your preferred versions of Anchor and Solana web3.js.
+
+## Quick Start
+
+### Creating an RFQ
+
+```typescript
+import { RFQClient, DEVNET_CONFIG } from '@optionsfi/sdk';
+
+// Initialize client
+const client = new RFQClient(DEVNET_CONFIG);
+await client.connect();
+
+// Create an RFQ for selling covered calls
+const rfqId = await client.createRFQ({
+  asset: 'NVDAX',
+  side: 'sell',
+  optionType: 'call',
+  strike: 150, // $150 strike
+  expiry: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60, // 1 week
+  quantity: BigInt(1000 * 1e6), // 1000 tokens
+  vaultAddress: 'your-vault-address',
+});
+
+// Subscribe to quotes
+client.subscribeToQuotes(rfqId, (quote) => {
+  console.log(`Quote from ${quote.marketMaker}: ${quote.premium} USDC`);
+});
+```
+
+### Option Pricing
+
+```typescript
+import { OptionPricing } from '@optionsfi/sdk';
+
+// Calculate Black-Scholes fair value
+const prices = OptionPricing.blackScholes({
+  spot: 145.50,
+  strike: 150,
+  timeToExpiry: 7 / 365, // 1 week
+  riskFreeRate: 0.05,
+  volatility: 0.45,
+});
+
+console.log('Call price:', prices.call);
+console.log('Put price:', prices.put);
+console.log('Call delta:', prices.delta.call);
+
+// Validate a quote against fair value
+const validation = OptionPricing.validateQuote(premiumFromQuote, prices.call);
+if (!validation.isValid) {
+  console.log('Quote rejected:', validation.reason);
+}
+```
+
+### Working with Vaults
+
+```typescript
+import { VaultInstructions, deriveVaultPda } from '@optionsfi/sdk';
+import { Connection } from '@solana/web3.js';
+
+const connection = new Connection('https://api.devnet.solana.com');
+
+// SDK includes bundled vault IDL - no need to provide it
+const instructions = new VaultInstructions(connection);
+await instructions.initialize();
+
+// Fetch vault data
+const vault = await instructions.fetchVault('NVDAX');
+console.log('Total assets:', vault.totalAssets);
+console.log('Current epoch:', vault.epoch);
+
+// Check remaining capacity
+const capacity = VaultInstructions.getRemainingCapacity(vault);
+console.log('Remaining capacity:', capacity);
+
+// Build transaction instruction
+const [vaultPda] = deriveVaultPda('NVDAX');
+const ix = await instructions.recordNotionalExposure({
+  vault: vaultPda,
+  authority: walletPublicKey,
+  notionalTokens: BigInt(1000 * 1e6),
+  premium: BigInt(50 * 1e6),
+});
+```
+
+## API Reference
+
+### RFQClient
+
+Main client for interacting with the RFQ infrastructure.
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Connect to the RFQ router WebSocket |
+| `disconnect()` | Disconnect from the router |
+| `createRFQ(params)` | Create a new RFQ |
+| `subscribeToQuotes(rfqId, callback)` | Subscribe to quotes |
+| `executeOption(rfqId, quoteId, wallet)` | Execute an option trade |
+| `cancelRFQ(rfqId)` | Cancel an open RFQ |
+| `onEvent(callback)` | Subscribe to all events |
+
+### OptionPricing
+
+Static utilities for option pricing.
+
+| Method | Description |
+|--------|-------------|
+| `blackScholes(params)` | Calculate option prices |
+| `calculateCoveredCallPremium(params)` | Premium for covered calls |
+| `premiumToBps(premium, spot)` | Convert premium to bps |
+| `validateQuote(premium, fairValue)` | Validate quote against fair |
+| `suggestStrike(spot, deltaBps)` | Suggest strike price |
+| `calculateHistoricalVolatility(prices)` | Calculate vol from prices |
+| `calculateImpliedVolatility(...)` | Derive IV from price |
+
+### VaultInstructions
+
+Build transactions for the vault program.
+
+| Method | Description |
+|--------|-------------|
+| `fetchVault(assetId)` | Fetch vault account data |
+| `recordNotionalExposure(params)` | Record option exposure |
+| `collectPremium(params)` | Collect premium from MM |
+| `paySettlement(params)` | Pay ITM settlement |
+| `advanceEpoch(params)` | Advance to next epoch |
+
+### Utilities
+
+```typescript
+import {
+  // Formatting
+  formatTokenAmount,
+  parseTokenAmount,
+  formatUSDC,
+  parseUSDC,
+  formatTimeToExpiry,
+  shortenAddress,
+  
+  // Validation
+  validateRFQParams,
+  validateBlackScholesParams,
+  
+  // Constants
+  VAULT_PROGRAM_ID,
+  deriveVaultPda,
+  PYTH_PRICE_FEEDS,
+} from '@optionsfi/sdk';
+```
+
+## Configuration
+
+### Networks
+
+```typescript
+import { DEVNET_CONFIG, MAINNET_CONFIG } from '@optionsfi/sdk';
+
+// Use devnet for testing
+const client = new RFQClient(DEVNET_CONFIG);
+
+// Use mainnet for production
+const client = new RFQClient(MAINNET_CONFIG);
+
+// Custom configuration
+const client = new RFQClient({
+  rpcUrl: 'https://my-rpc.com',
+  rfqRouterUrl: 'wss://rfq.optionsfi.xyz',
+  programId: 'A4jgqct3bwTwRmHECHdPpbH3a8ksaVb7rny9pMUGFo94',
+  network: 'mainnet-beta',
+});
+```
+
+## Documentation
+
+For comprehensive guides and API documentation, visit [docs.optionsfi.xyz](https://docs.optionsfi.xyz).
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/optionsfi/optionsfi/issues)
+- **Documentation**: [docs.optionsfi.xyz](https://docs.optionsfi.xyz)
+- **Website**: [optionsfi.xyz](https://optionsfi.xyz)
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting pull requests.
+
+## Security
+
+For security concerns, please email security@optionsfi.xyz. Do not open public issues for security vulnerabilities.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+---
+
+Built with ❤️ by the OptionsFi team