@megatao/sdk 1.1.0

package/docs/integration/VIEM_INTEGRATION.md

@@ -0,0 +1,294 @@
+# Viem Integration Guide
+
+## Overview
+
+The Alpha Futures SDK is built with [Viem](https://viem.sh/), a modern TypeScript library for interacting with Ethereum and EVM-compatible blockchains. Viem provides automatic type inference, optimal performance, and an excellent developer experience.
+
+## Key Benefits
+
+### 1. **Automatic Type Inference**
+- No code generation required
+- Types are inferred directly from ABI definitions
+- Always in sync with your contracts
+
+### 2. **Better Performance**
+- Smaller bundle sizes
+- Faster execution
+- Optimized for modern JavaScript environments
+
+### 3. **Enhanced Developer Experience**
+- Immediate IntelliSense support
+- Better error messages
+- Cleaner, more intuitive API
+
+## Installation
+
+```bash
+npm install @alpha-futures/sdk
+```
+
+## Quick Start
+
+### Basic Setup
+
+```typescript
+import { ViemContractFactory, type ContractAddresses } from '@alpha-futures/sdk';
+
+// Define contract addresses
+const contractAddresses: ContractAddresses = {
+  positionManager: '0x...',
+  marginAccount: '0x...',
+  fundingRate: '0x...',
+  orderBook: '0x...',
+  liquidationEngine: '0x...',
+  protocolVault: '0x...'
+};
+
+// Create factory instance
+const factory = ViemContractFactory.fromPrivateKey(
+  contractAddresses,
+  process.env.PRIVATE_KEY!,
+  process.env.RPC_URL!
+);
+```
+
+### Using with MetaMask or Web3 Provider
+
+```typescript
+// From an EIP-1193 provider (like MetaMask)
+const factory = await ViemContractFactory.fromProvider(
+  contractAddresses,
+  window.ethereum
+);
+```
+
+### Manual Client Creation
+
+```typescript
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const publicClient = createPublicClient({
+  chain: bittensorEVM,
+  transport: http(RPC_URL)
+});
+
+const walletClient = createWalletClient({
+  account: privateKeyToAccount(PRIVATE_KEY as `0x${string}`),
+  chain: bittensorEVM,
+  transport: http(RPC_URL)
+});
+```
+
+## Contract Interactions
+
+### Reading Contract State
+
+```typescript
+const positionManager = factory.createPositionManager();
+
+// Get position details
+const position = await positionManager.getPosition(positionId);
+console.log('Position size:', position.size);
+console.log('Is Long:', position.isLong);
+
+// Get user positions
+const positions = await positionManager.getUserPositions(userAddress);
+console.log('Active positions:', positions);
+```
+
+### Writing to Contracts
+
+```typescript
+const marginAccount = factory.createMarginAccount();
+
+// Deposit margin
+const depositHash = await marginAccount.deposit(
+  parseEther('100'), // amount
+  { value: parseEther('100') } // transaction options
+);
+
+// Wait for confirmation
+const receipt = await publicClient.waitForTransactionReceipt({ 
+  hash: depositHash 
+});
+```
+
+### Event Monitoring
+
+```typescript
+import { watchContractEvent } from 'viem';
+
+// Watch for position opened events
+const unwatch = watchContractEvent(publicClient, {
+  address: contractAddresses.positionManager,
+  abi: PositionManagerABI,
+  eventName: 'PositionOpened',
+  onLogs: (logs) => {
+    logs.forEach(log => {
+      console.log('New position:', {
+        positionId: log.args.positionId,
+        trader: log.args.trader,
+        size: log.args.size,
+        isLong: log.args.isLong
+      });
+    });
+  }
+});
+
+// Stop watching
+unwatch();
+```
+
+## Advanced Usage
+
+### Batch Operations
+
+```typescript
+// Read multiple values in one call
+const [balance, marginRatio, positions] = await Promise.all([
+  marginAccount.getBalance(userAddress),
+  marginAccount.getMarginRatio(userAddress),
+  positionManager.getUserPositions(userAddress)
+]);
+```
+
+### Gas Estimation
+
+```typescript
+// Estimate gas before sending transaction
+const gasEstimate = await positionManager.estimateGas.openPosition(
+  asset,
+  isLong,
+  size,
+  margin
+);
+
+// Send with custom gas limit
+const hash = await positionManager.openPosition(
+  asset,
+  isLong,
+  size,
+  margin,
+  { gas: gasEstimate * 120n / 100n } // 20% buffer
+);
+```
+
+### Error Handling
+
+```typescript
+import { ContractFunctionExecutionError } from 'viem';
+
+try {
+  await positionManager.openPosition(...);
+} catch (error) {
+  if (error instanceof ContractFunctionExecutionError) {
+    console.error('Contract error:', error.shortMessage);
+    // Access revert reason
+    const reason = error.reason;
+  }
+}
+```
+
+## Type Safety
+
+### Automatic Type Inference
+
+```typescript
+// Types are automatically inferred from ABIs
+const position = await positionManager.getPosition(1n);
+// position.size is typed as bigint
+// position.isLong is typed as boolean
+// position.trader is typed as Address
+```
+
+### Using Type Exports
+
+```typescript
+import type { Address, Hash, TransactionReceipt } from '@alpha-futures/sdk';
+
+// Use imported types
+const userAddress: Address = '0x...';
+const txHash: Hash = '0x...';
+```
+
+## Best Practices
+
+### 1. **Use Type-Safe ABIs**
+
+```typescript
+import { PositionManagerABI } from '@alpha-futures/sdk';
+
+// ABIs provide full type safety
+const contract = getContract({
+  address: contractAddress,
+  abi: PositionManagerABI,
+  client
+});
+```
+
+### 2. **Handle BigInt Properly**
+
+```typescript
+// Viem uses native BigInt
+const amount = parseEther('100'); // Returns bigint
+const formatted = formatEther(amount); // Returns string
+
+// Arithmetic operations
+const doubled = amount * 2n; // Note the 'n' suffix
+```
+
+### 3. **Use Proper Error Handling**
+
+```typescript
+try {
+  const hash = await contract.write.someFunction([...args]);
+  const receipt = await publicClient.waitForTransactionReceipt({ hash });
+  
+  if (receipt.status === 'reverted') {
+    throw new Error('Transaction reverted');
+  }
+} catch (error) {
+  // Handle specific error types
+}
+```
+
+### 4. **Optimize Read Operations**
+
+```typescript
+// Use multicall for multiple reads
+const results = await publicClient.multicall({
+  contracts: [
+    {
+      address: marginAccount.address,
+      abi: MarginAccountABI,
+      functionName: 'getBalance',
+      args: [userAddress]
+    },
+    {
+      address: positionManager.address,
+      abi: PositionManagerABI,
+      functionName: 'getUserPositions',
+      args: [userAddress]
+    }
+  ]
+});
+```
+
+## Migration from Ethers
+
+If you're migrating from Ethers.js:
+
+| Ethers.js | Viem |
+|-----------|------|
+| `ethers.utils.parseEther()` | `parseEther()` |
+| `ethers.utils.formatEther()` | `formatEther()` |
+| `BigNumber` | `bigint` |
+| `contract.connect(signer)` | Pass client to contract creation |
+| `await tx.wait()` | `await publicClient.waitForTransactionReceipt({ hash })` |
+
+## Resources
+
+- [Viem Documentation](https://viem.sh)
+- [Alpha Futures SDK Examples](../../examples)
+- [Contract ABIs](../../src/abi)

package/docs/reference/CLI_QUICK_REFERENCE.md

@@ -0,0 +1,197 @@
+# Alpha Futures CLI Quick Reference
+
+## Installation & Setup
+
+```bash
+# Install globally
+npm install -g @alpha-futures/sdk
+
+# Or use npx (no install needed)
+npx @alpha-futures/sdk --help
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your private key and RPC URL
+```
+
+## Common Commands
+
+### Account Management
+```bash
+alpha-futures account info                    # Show account summary
+alpha-futures account balance                 # Check margin balance
+alpha-futures account deposit --amount 1000   # Deposit TAO margin
+alpha-futures account withdraw --amount 500   # Withdraw TAO margin
+alpha-futures account history                 # View transaction history
+```
+
+### Position Management
+```bash
+alpha-futures position list                                           # List all positions
+alpha-futures position info 0x00000000000000000000000000000001      # Position details
+alpha-futures position open --asset ALPHA --size 1000 --leverage 3 --long   # Open long
+alpha-futures position open --asset ALPHA --size 1000 --leverage 3 --short  # Open short
+alpha-futures position close 0x00000000000000000000000000000001       # Close position
+alpha-futures position modify 0x00000000000000000000000000000001 --add 200    # Add margin
+alpha-futures position modify 0x00000000000000000000000000000001 --remove 100 # Remove margin
+```
+
+### Market Data
+```bash
+alpha-futures market prices                   # Current asset prices
+alpha-futures market funding-rates            # Current funding rates
+alpha-futures market open-interest            # Total open interest
+alpha-futures market stats                    # Market statistics
+alpha-futures market info --asset ALPHA       # Specific asset info
+```
+
+### Trading
+```bash
+alpha-futures trade market --asset ALPHA --size 1000 --long          # Market buy
+alpha-futures trade market --asset ALPHA --size 1000 --short         # Market sell
+alpha-futures trade limit --asset ALPHA --size 1000 --price 100 --long   # Limit order
+alpha-futures trade orders                                            # View open orders
+alpha-futures trade cancel --id 456                                   # Cancel order
+```
+
+### Liquidations
+```bash
+alpha-futures liquidation check               # Check liquidation status
+alpha-futures liquidation at-risk             # View at-risk positions
+alpha-futures liquidation execute 0x00000000000000000000000000000001  # Execute liquidation
+alpha-futures liquidation monitor             # Real-time monitoring
+```
+
+### Vault Operations
+```bash
+alpha-futures vault stats                     # Vault statistics
+alpha-futures vault balance                   # Vault TAO balance
+alpha-futures vault performance               # Vault P&L metrics
+```
+
+## Interactive Mode
+
+```bash
+alpha-futures interactive    # Launch interactive trading interface
+```
+
+Features:
+- Visual menus and prompts
+- Real-time price updates
+- Transaction confirmations
+- Input validation
+
+## Configuration Options
+
+### Command Line Flags
+```bash
+-n, --network <network>    # Network: mainnet, testnet, localhost
+-r, --rpc <url>           # Custom RPC endpoint
+-k, --key <privateKey>    # Private key (not recommended)
+-c, --config <path>       # Config file path
+--no-color                # Disable colored output
+--json                    # JSON output format
+```
+
+### Examples with Flags
+```bash
+# Use testnet
+alpha-futures -n testnet position list
+
+# Custom RPC
+alpha-futures -r https://your-rpc.com market prices
+
+# JSON output
+alpha-futures --json account info > account.json
+```
+
+## Environment Variables
+
+```bash
+NETWORK=mainnet           # Default network
+RPC_URL=https://...       # RPC endpoint
+PRIVATE_KEY=0x...         # Wallet private key
+DEFAULT_LEVERAGE=3        # Default leverage
+DEFAULT_SLIPPAGE=0.5      # Default slippage %
+GAS_PRICE_MULTIPLIER=1.1  # Gas price boost
+```
+
+## Tips & Shortcuts
+
+### Position Shortcuts
+```bash
+# Quick open with defaults
+alpha-futures position open -a ALPHA -s 1000 -l 3 --long
+
+# Bulk close all positions
+alpha-futures position list --json | jq '.[] | .id' | xargs -I {} alpha-futures position close --id {}
+```
+
+### Market Monitoring
+```bash
+# Watch funding rates
+watch -n 60 alpha-futures market funding-rates
+
+# Monitor your positions
+watch -n 30 alpha-futures position list
+```
+
+### Account Safety
+```bash
+# Check margin ratio
+alpha-futures account info | grep "Margin Ratio"
+
+# List positions near liquidation
+alpha-futures liquidation at-risk
+```
+
+## Error Codes
+
+- `INSUFFICIENT_MARGIN` - Not enough TAO deposited
+- `POSITION_NOT_FOUND` - Invalid position ID
+- `LEVERAGE_TOO_HIGH` - Exceeds maximum leverage
+- `MARKET_CLOSED` - Trading temporarily halted
+- `SLIPPAGE_EXCEEDED` - Price moved beyond tolerance
+
+## Getting Help
+
+```bash
+alpha-futures --help              # General help
+alpha-futures <command> --help    # Command-specific help
+alpha-futures help <command>      # Alternative help syntax
+```
+
+## Examples
+
+### Complete Trading Flow
+```bash
+# 1. Check balance
+alpha-futures account balance
+
+# 2. Deposit margin if needed
+alpha-futures account deposit --amount 1000
+
+# 3. Check market prices
+alpha-futures market prices
+
+# 4. Open position
+alpha-futures position open --asset ALPHA --size 500 --leverage 3 --long
+
+# 5. Monitor position
+alpha-futures position list
+
+# 6. Close with profit/loss
+alpha-futures position close 0x00000000000000000000000000000001
+```
+
+### Risk Management
+```bash
+# Set up monitoring
+alpha-futures position list --json > positions.json
+
+# Check margin ratios
+cat positions.json | jq '.[] | {id: .id, marginRatio: .marginRatio}'
+
+# Add margin to risky positions
+alpha-futures position modify 0x00000000000000000000000000000001 --add 200
+```