@steerprotocol/sdk 1.27.0 → 1.28.0

package/src/base/vault/single-asset/readmes/index.md

@@ -0,0 +1,174 @@
+# Single-Asset Deposit Documentation Index
+
+Welcome to the comprehensive documentation for the Steer Protocol Single-Asset Deposit functionality.
+
+## 📚 Documentation Overview
+
+### 🚀 Getting Started
+- **[Main README](../README.md)** - Complete overview and getting started guide
+- **[API Reference](./API_REFERENCE.md)** - Quick reference for all functions and types
+
+### 🔧 Core Functions
+- **[calculateSwapAmount](./calculateSwapAmount.md)** - Determines optimal swap amounts for balanced deposits
+- **[calculateLimitPrice](./calculateLimitPrice.md)** - Calculates slippage-protected price limits
+- **[simulateSwap](./simulateSwap.md)** - Simulates swaps with price impact analysis
+- **[estimateLpTokens](./estimateLpTokens.md)** - Estimates final LP tokens and deposit amounts
+
+## 🎯 Quick Navigation
+
+| I want to... | Go to... |
+|--------------|----------|
+| **Get started quickly** | [Main README](../README.md#quick-start) |
+| **See all available methods** | [API Reference](./API_REFERENCE.md#vaultclient-methods) |
+| **Understand swap calculations** | [calculateSwapAmount](./calculateSwapAmount.md) |
+| **Learn about slippage protection** | [calculateLimitPrice](./calculateLimitPrice.md) |
+| **Preview swap outcomes** | [simulateSwap](./simulateSwap.md) |
+| **Estimate LP token rewards** | [estimateLpTokens](./estimateLpTokens.md) |
+| **Handle errors properly** | [API Reference](./API_REFERENCE.md#error-handling) |
+| **See complete examples** | [API Reference](./API_REFERENCE.md#examples) |
+
+## 🏗️ Architecture Overview
+
+```mermaid
+graph TD
+    A[User Deposit Request] --> B[calculateSwapAmount]
+    B --> C[calculateLimitPrice]
+    C --> D[simulateSwap]
+    D --> E[estimateLpTokens]
+    E --> F[SingleAssetDepositClient]
+    F --> G[VaultClient.previewSingleAssetDeposit]
+    G --> H{User Approval?}
+    H -->|Yes| I[VaultClient.singleAssetDeposit]
+    H -->|No| J[Cancel]
+    I --> K[Transaction Hash]
+    
+    style A fill:#e1f5fe
+    style K fill:#c8e6c9
+    style J fill:#ffcdd2
+```
+
+## 📋 Function Dependencies
+
+```mermaid
+graph LR
+    A[calculateSwapAmount] --> B[calculateLimitPrice]
+    B --> C[simulateSwap]
+    C --> D[estimateLpTokens]
+    D --> E[SingleAssetDepositClient]
+    
+    F[Token Addresses] --> B
+    G[Pool State] --> A
+    G --> B
+    H[Vault State] --> D
+    I[Quoter Contract] --> C
+```
+
+## 🔍 Quick Code Examples
+
+### Basic Usage
+```typescript
+import { SteerClient, AMMType } from '@steerprotocol/sdk';
+
+const steerClient = new SteerClient({ /* config */ });
+
+// Preview deposit
+const preview = await steerClient.vaults.previewSingleAssetDeposit({
+  assets: parseEther('100'),
+  receiver: userAddress,
+  vault: vaultAddress,
+  isToken0: true,
+  depositSlippagePercent: 5n,
+  swapSlippageBP: 500,
+  ammType: AMMType.UniswapV3,
+}, poolAddress);
+
+// Execute deposit
+if (preview.success) {
+  const result = await steerClient.vaults.singleAssetDeposit(params);
+}
+```
+
+### Individual Function Usage
+```typescript
+// Calculate what needs to be swapped
+const swapAmount = await calculateSwapAmount(publicClient, params);
+
+// Get price protection
+const priceLimit = await calculateLimitPrice(publicClient, limitParams);
+
+// Preview the swap
+const swapResult = await simulateSwap(publicClient, swapParams, chainId);
+
+// Estimate final LP tokens
+const lpEstimate = await estimateLpTokens(publicClient, lpParams);
+```
+
+## 📊 Supported Networks & Contracts
+
+| Network | Status | Single Asset Deposit Contract |
+|---------|--------|-------------------------------|
+| Polygon | ✅ Live | `0x9903C4ED61A71d0d5C322097adfF752d6339F871` |
+| Ethereum | 🚧 Coming Soon | TBD |
+| Arbitrum | 🚧 Coming Soon | TBD |
+
+## ⚠️ Important Notes
+
+### Security Considerations
+- Always preview deposits before execution
+- Use appropriate slippage tolerances (typically 1-5%)
+- Validate all parameters before submission
+- Monitor price impact for large deposits
+
+### Performance Tips
+- Cache simulation results for repeated calls
+- Use reasonable slippage settings to avoid MEV
+- Batch multiple deposits when possible
+- Consider gas costs for small deposits
+
+### Common Pitfalls
+- ❌ Not previewing before execution
+- ❌ Using excessive slippage tolerances
+- ❌ Ignoring price impact warnings
+- ❌ Not validating token addresses
+- ❌ Insufficient error handling
+
+## 🧪 Testing Resources
+
+### Test Cases Covered
+- ✅ Token0 and Token1 deposits
+- ✅ Various slippage tolerances
+- ✅ Different pool states (balanced, imbalanced, empty)
+- ✅ Edge cases (very small/large amounts)
+- ✅ Error scenarios (invalid params, network issues)
+
+### Test File Locations
+- Unit Tests: `src/__tests__/base/vault/single-sided/`
+- Integration Tests: Real contract interactions
+- Mock Tests: Isolated function testing
+
+## 🤝 Contributing
+
+### Documentation Updates
+- Keep examples up to date with API changes
+- Add new test cases for edge scenarios
+- Update contract addresses when deployed
+- Improve error handling examples
+
+### Code Contributions
+- Follow existing patterns and naming conventions
+- Add comprehensive tests for new features
+- Update documentation for any API changes
+- Ensure backward compatibility where possible
+
+## 📞 Support
+
+- **GitHub Issues**: For bugs and feature requests
+- **Discord**: Community support and discussions
+- **Documentation**: You're reading it! 📖
+- **Examples**: See the `/examples` directory (if available)
+
+---
+
+*Last updated: [Current Date]*
+*SDK Version: Latest*
+*Documentation Version: 1.0*