Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
2026-02-28 14:39:40 -05:00
commit d803bfe2b1
7854 changed files with 3522914 additions and 0 deletions
--- a/npm/packages/agentic-synth/examples/crypto/README.md
+++ b/npm/packages/agentic-synth/examples/crypto/README.md
@@ -0,0 +1,673 @@
+# Cryptocurrency and Blockchain Data Generation Examples
+
+Comprehensive examples for generating realistic cryptocurrency trading, DeFi protocol, and blockchain data using agentic-synth.
+
+## Overview
+
+This directory contains production-ready examples for simulating:
+
+- **Exchange Data**: OHLCV, order books, trades, liquidity pools, arbitrage
+- **DeFi Scenarios**: Yield farming, liquidity provision, impermanent loss, gas prices
+- **Blockchain Data**: Transactions, wallets, tokens, NFTs, MEV patterns
+
+All examples include **24/7 market patterns** and **cross-exchange scenarios** for realistic crypto market simulation.
+
+## Files
+
+### 1. exchange-data.ts
+
+Cryptocurrency exchange data generation covering both CEX and DEX markets.
+
+**Examples:**
+- OHLCV data for multiple cryptocurrencies (BTC, ETH, SOL, AVAX, MATIC)
+- Real-time order book snapshots with bid/ask spreads
+- Trade execution data with maker/taker fees
+- AMM liquidity pool metrics
+- Cross-exchange arbitrage opportunities
+- 24/7 market data with timezone effects
+- Perpetual futures funding rates
+- Streaming market data feeds
+
+**Key Features:**
+```typescript
+// Generate realistic OHLCV with seasonality
+await generateOHLCV();
+
+// Order book with realistic spreads and depth
+await generateOrderBook();
+
+// 10k trades with realistic patterns
+await generateTrades();
+
+// DEX liquidity pool data
+await generateLiquidityPools();
+
+// Cross-exchange arbitrage
+await generateArbitrageOpportunities();
+```
+
+### 2. defi-scenarios.ts
+
+DeFi protocol simulations for yield farming, lending, and advanced strategies.
+
+**Examples:**
+- Yield farming across Aave, Compound, Curve, Convex, Yearn
+- Liquidity provision scenarios with LP token calculations
+- Impermanent loss simulations under various market conditions
+- Gas price data with network congestion patterns
+- Smart contract interaction sequences
+- Lending/borrowing position management
+- Staking rewards (liquid staking protocols)
+- MEV extraction scenarios
+
+**Key Features:**
+```typescript
+// Yield farming data
+await generateYieldFarmingData();
+
+// LP scenarios with IL analysis
+await generateLiquidityProvisionScenarios();
+
+// Impermanent loss under different conditions
+await generateImpermanentLossScenarios();
+
+// Gas price optimization
+await generateGasPriceData();
+
+// Smart contract interactions
+await generateSmartContractInteractions();
+```
+
+### 3. blockchain-data.ts
+
+On-chain data generation for transactions, wallets, and blockchain activity.
+
+**Examples:**
+- Transaction patterns across multiple networks (Ethereum, Polygon, Arbitrum, Optimism, Base)
+- Wallet behavior simulation (HODLers, traders, bots, whales)
+- Token transfer events (ERC-20, ERC-721, ERC-1155)
+- NFT marketplace activity and trading
+- MEV bundle construction and extraction
+- Block production and validator performance
+- Smart contract deployment tracking
+- Cross-chain bridge activity
+
+**Key Features:**
+```typescript
+// Generate realistic transactions
+await generateTransactionPatterns();
+
+// Wallet behavior patterns
+await generateWalletBehavior();
+
+// Token transfers
+await generateTokenTransfers();
+
+// NFT trading activity
+await generateNFTActivity();
+
+// MEV scenarios
+await generateMEVPatterns();
+```
+
+## Installation
+
+```bash
+# Install dependencies
+cd packages/agentic-synth
+npm install
+
+# Set up API keys
+cp .env.example .env
+# Add your GEMINI_API_KEY or OPENROUTER_API_KEY
+```
+
+## Usage
+
+### Running Individual Examples
+
+```typescript
+// Import specific examples
+import { generateOHLCV, generateArbitrageOpportunities } from './crypto/exchange-data.js';
+import { generateYieldFarmingData } from './crypto/defi-scenarios.js';
+import { generateWalletBehavior } from './crypto/blockchain-data.js';
+
+// Run examples
+const ohlcvData = await generateOHLCV();
+const arbOps = await generateArbitrageOpportunities();
+const yieldData = await generateYieldFarmingData();
+const wallets = await generateWalletBehavior();
+```
+
+### Running All Examples
+
+```typescript
+// Exchange data examples
+import { runExchangeDataExamples } from './crypto/exchange-data.js';
+await runExchangeDataExamples();
+
+// DeFi scenario examples
+import { runDeFiScenarioExamples } from './crypto/defi-scenarios.js';
+await runDeFiScenarioExamples();
+
+// Blockchain data examples
+import { runBlockchainDataExamples } from './crypto/blockchain-data.js';
+await runBlockchainDataExamples();
+```
+
+### Command Line Usage
+
+```bash
+# Run via Node.js
+node --experimental-modules examples/crypto/exchange-data.js
+node --experimental-modules examples/crypto/defi-scenarios.js
+node --experimental-modules examples/crypto/blockchain-data.js
+
+# Run via ts-node
+ts-node examples/crypto/exchange-data.ts
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+import { createSynth } from '@ruvector/agentic-synth';
+
+const synth = createSynth({
+  provider: 'gemini',           // or 'openrouter'
+  apiKey: process.env.GEMINI_API_KEY,
+  model: 'gemini-2.0-flash-exp', // or 'anthropic/claude-3.5-sonnet'
+  cacheStrategy: 'memory',       // Enable caching
+  cacheTTL: 3600                 // Cache for 1 hour
+});
+```
+
+### Provider Options
+
+**Gemini (Recommended for crypto data):**
+```typescript
+{
+  provider: 'gemini',
+  apiKey: process.env.GEMINI_API_KEY,
+  model: 'gemini-2.0-flash-exp'
+}
+```
+
+**OpenRouter (For Claude/GPT models):**
+```typescript
+{
+  provider: 'openrouter',
+  apiKey: process.env.OPENROUTER_API_KEY,
+  model: 'anthropic/claude-3.5-sonnet'
+}
+```
+
+## Key Features
+
+### 24/7 Market Patterns
+
+All examples include realistic 24/7 cryptocurrency market patterns:
+
+- **Asian Session**: Increased volatility, lower volume
+- **European Session**: Medium volatility, building volume
+- **US Session**: Highest volume, major moves
+- **Weekend Effect**: 30% lower volume typically
+- **Holiday Impact**: Reduced activity during major holidays
+
+```typescript
+const result = await synth.generateTimeSeries({
+  count: 168 * 12, // 1 week of 5-minute data
+  interval: '5m',
+  seasonality: true, // Enable session patterns
+  // ...
+});
+```
+
+### Cross-Exchange Arbitrage
+
+Realistic price differences and arbitrage opportunities:
+
+```typescript
+const arbOps = await generateArbitrageOpportunities();
+// Returns opportunities across Binance, Coinbase, Kraken, OKX
+// Includes:
+// - Price spreads
+// - Execution times
+// - Fee calculations
+// - Feasibility analysis
+```
+
+### Gas Price Optimization
+
+Network congestion modeling for transaction cost analysis:
+
+```typescript
+const gasData = await generateGasPriceData();
+// Includes:
+// - Base fee dynamics (EIP-1559)
+// - Priority fees
+// - Network congestion levels
+// - Cost estimates for different transaction types
+```
+
+### Impermanent Loss Calculations
+
+Accurate IL simulation for liquidity providers:
+
+```typescript
+const ilData = await generateImpermanentLossScenarios();
+// Formula: 2 * sqrt(priceRatio) / (1 + priceRatio) - 1
+// Includes:
+// - Price divergence analysis
+// - Fee compensation
+// - Break-even calculations
+// - Recommendations
+```
+
+## Data Schemas
+
+### OHLCV Schema
+
+```typescript
+{
+  timestamp: string,      // ISO 8601
+  symbol: string,         // e.g., "BTC/USDT"
+  open: number,
+  high: number,           // >= max(open, close, low)
+  low: number,            // <= min(open, close, high)
+  close: number,
+  volume: number,
+  vwap: number,          // Volume-weighted average price
+  trades: number         // Number of trades
+}
+```
+
+### Order Book Schema
+
+```typescript
+{
+  timestamp: string,
+  exchange: string,
+  symbol: string,
+  bids: [
+    { price: number, quantity: number, total: number }
+  ],
+  asks: [
+    { price: number, quantity: number, total: number }
+  ],
+  spread: number,        // asks[0].price - bids[0].price
+  midPrice: number,      // (bids[0].price + asks[0].price) / 2
+  liquidity: {
+    bidDepth: number,
+    askDepth: number,
+    totalDepth: number
+  }
+}
+```
+
+### Trade Schema
+
+```typescript
+{
+  tradeId: string,
+  timestamp: string,
+  exchange: string,
+  symbol: string,
+  side: 'buy' | 'sell',
+  orderType: 'market' | 'limit' | 'stop' | 'stop_limit',
+  price: number,
+  quantity: number,
+  total: number,
+  fee: number,
+  feeAsset: string,
+  makerTaker: 'maker' | 'taker',
+  latency: number        // milliseconds
+}
+```
+
+### Liquidity Pool Schema
+
+```typescript
+{
+  timestamp: string,
+  dex: string,
+  poolAddress: string,
+  tokenA: string,
+  tokenB: string,
+  reserveA: number,
+  reserveB: number,
+  totalLiquidity: number,
+  price: number,         // reserveB / reserveA
+  volume24h: number,
+  fees24h: number,
+  apy: number,
+  impermanentLoss: number
+}
+```
+
+## Use Cases
+
+### 1. Trading Algorithm Development
+
+Generate realistic market data for backtesting trading strategies:
+
+```typescript
+const historicalData = await generateOHLCV();
+const orderBook = await generateOrderBook();
+const trades = await generateTrades();
+
+// Use for:
+// - Strategy backtesting
+// - Order execution simulation
+// - Market impact analysis
+```
+
+### 2. DeFi Protocol Testing
+
+Test DeFi applications with realistic scenarios:
+
+```typescript
+const yieldData = await generateYieldFarmingData();
+const lpScenarios = await generateLiquidityProvisionScenarios();
+const gasData = await generateGasPriceData();
+
+// Use for:
+// - APY calculation testing
+// - IL mitigation strategies
+// - Gas optimization
+```
+
+### 3. Risk Analysis
+
+Simulate various market conditions for risk assessment:
+
+```typescript
+const ilScenarios = await generateImpermanentLossScenarios();
+const lendingScenarios = await generateLendingScenarios();
+
+// Use for:
+// - Portfolio risk assessment
+// - Liquidation analysis
+// - Stress testing
+```
+
+### 4. Blockchain Analytics
+
+Generate on-chain data for analytics platforms:
+
+```typescript
+const txPatterns = await generateTransactionPatterns();
+const wallets = await generateWalletBehavior();
+const nftActivity = await generateNFTActivity();
+
+// Use for:
+// - Wallet profiling
+// - Transaction pattern analysis
+// - Network activity monitoring
+```
+
+### 5. MEV Research
+
+Study MEV extraction patterns and strategies:
+
+```typescript
+const mevPatterns = await generateMEVPatterns();
+const arbOps = await generateArbitrageOpportunities();
+
+// Use for:
+// - MEV strategy development
+// - Sandwich attack analysis
+// - Flashbot simulation
+```
+
+## Performance Optimization
+
+### Caching
+
+Enable caching for repeated queries:
+
+```typescript
+const synth = createSynth({
+  cacheStrategy: 'memory',
+  cacheTTL: 3600  // 1 hour
+});
+
+// First call: generates data
+const data1 = await synth.generateTimeSeries({...});
+
+// Second call: returns cached data
+const data2 = await synth.generateTimeSeries({...}); // Fast!
+```
+
+### Batch Generation
+
+Generate multiple datasets in parallel:
+
+```typescript
+const batches = [
+  { count: 100, interval: '1h' },
+  { count: 200, interval: '5m' },
+  { count: 50, interval: '1d' }
+];
+
+const results = await synth.generateBatch('timeseries', batches, 3);
+// Processes 3 batches concurrently
+```
+
+### Streaming
+
+Use streaming for real-time data generation:
+
+```typescript
+for await (const tick of synth.generateStream('timeseries', {
+  count: 100,
+  interval: '1s',
+  metrics: ['price', 'volume']
+})) {
+  console.log('New tick:', tick);
+  // Process data in real-time
+}
+```
+
+## Best Practices
+
+1. **Use Appropriate Intervals**
+   - 1s-1m: High-frequency trading, tick data
+   - 5m-1h: Intraday trading, short-term analysis
+   - 4h-1d: Swing trading, daily analysis
+   - 1d-1w: Long-term analysis, backtesting
+
+2. **Set Realistic Constraints**
+   - Use market-appropriate price ranges
+   - Set sensible volatility levels (0.1-0.3 for crypto)
+   - Include seasonality for realistic patterns
+
+3. **Validate Generated Data**
+   - Check for price consistency (high >= max(open, close, low))
+   - Verify volume patterns
+   - Ensure timestamp ordering
+
+4. **Optimize for Scale**
+   - Use caching for repeated queries
+   - Batch generation for multiple datasets
+   - Stream data for real-time applications
+
+5. **Security Considerations**
+   - Never hardcode API keys
+   - Use environment variables
+   - Implement rate limiting
+   - Validate all inputs
+
+## Examples Output
+
+### OHLCV Data Sample
+
+```json
+{
+  "timestamp": "2025-01-22T10:00:00.000Z",
+  "symbol": "BTC/USDT",
+  "open": 42150.50,
+  "high": 42380.25,
+  "low": 42080.00,
+  "close": 42295.75,
+  "volume": 125.48,
+  "vwap": 42225.33,
+  "trades": 342
+}
+```
+
+### Arbitrage Opportunity Sample
+
+```json
+{
+  "timestamp": "2025-01-22T10:15:32.000Z",
+  "symbol": "ETH/USDT",
+  "buyExchange": "binance",
+  "sellExchange": "coinbase",
+  "buyPrice": 2245.50,
+  "sellPrice": 2258.25,
+  "spread": 12.75,
+  "spreadPercent": 0.568,
+  "profitUSD": 127.50,
+  "feasible": true
+}
+```
+
+### Impermanent Loss Sample
+
+```json
+{
+  "timestamp": "2025-01-22T10:00:00.000Z",
+  "scenario": "high_volatility",
+  "priceRatio": 1.5,
+  "impermanentLoss": -2.02,
+  "impermanentLossPercent": -2.02,
+  "hodlValue": 10000,
+  "lpValue": 9798,
+  "feesEarned": 150,
+  "netProfit": -52,
+  "recommendation": "rebalance"
+}
+```
+
+## Troubleshooting
+
+### API Rate Limits
+
+If you hit rate limits:
+
+```typescript
+const synth = createSynth({
+  maxRetries: 5,
+  timeout: 60000  // Increase timeout
+});
+```
+
+### Memory Issues
+
+For large datasets:
+
+```typescript
+// Use streaming instead of batch generation
+for await (const data of synth.generateStream(...)) {
+  processData(data);
+  // Process one at a time
+}
+```
+
+### Data Quality Issues
+
+If generated data doesn't meet requirements:
+
+```typescript
+// Add more specific constraints
+const result = await synth.generateTimeSeries({
+  // ...
+  constraints: {
+    custom: [
+      'high >= Math.max(open, close, low)',
+      'low <= Math.min(open, close, high)',
+      'volume > 1000',
+      'realistic market microstructure'
+    ]
+  }
+});
+```
+
+## Integration Examples
+
+### With Trading Bots
+
+```typescript
+import { generateOHLCV, generateOrderBook } from './crypto/exchange-data.js';
+
+async function backtestStrategy() {
+  const historicalData = await generateOHLCV();
+  const orderBook = await generateOrderBook();
+
+  // Run your trading strategy
+  const results = runBacktest(historicalData, orderBook);
+
+  return results;
+}
+```
+
+### With DeFi Protocols
+
+```typescript
+import { generateYieldFarmingData, generateGasPriceData } from './crypto/defi-scenarios.js';
+
+async function optimizeYield() {
+  const yieldData = await generateYieldFarmingData();
+  const gasData = await generateGasPriceData();
+
+  // Calculate optimal farming strategy
+  const strategy = calculateOptimal(yieldData, gasData);
+
+  return strategy;
+}
+```
+
+### With Analytics Platforms
+
+```typescript
+import { generateWalletBehavior, generateTransactionPatterns } from './crypto/blockchain-data.js';
+
+async function analyzeUserBehavior() {
+  const wallets = await generateWalletBehavior();
+  const transactions = await generateTransactionPatterns();
+
+  // Perform analytics
+  const insights = analyzePatterns(wallets, transactions);
+
+  return insights;
+}
+```
+
+## Contributing
+
+To add new crypto data examples:
+
+1. Follow existing patterns in the example files
+2. Include realistic constraints and validations
+3. Add comprehensive documentation
+4. Include sample outputs
+5. Test with multiple data sizes
+
+## Resources
+
+- [agentic-synth Documentation](../../README.md)
+- [Crypto Market Data Standards](https://www.ccxt.pro/)
+- [DeFi Protocol Documentation](https://defillama.com/)
+- [Blockchain Data APIs](https://www.alchemy.com/)
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/ruvnet/ruvector/issues
+- Documentation: https://github.com/ruvnet/ruvector/tree/main/packages/agentic-synth
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details