@megatao/sdk 1.1.0

package/.env.example

@@ -0,0 +1,37 @@
+# Required Configuration
+PRIVATE_KEY=your_private_key_here
+
+# Network Configuration (optional)
+NETWORK=mainnet
+RPC_URL=https://your-rpc-endpoint.com
+
+# Contract Addresses (optional - uses defaults if not specified)
+POSITION_MANAGER_ADDRESS=0x0000000000000000000000000000000000000000
+MARGIN_ACCOUNT_ADDRESS=0x0000000000000000000000000000000000000000
+FUNDING_RATE_ADDRESS=0x0000000000000000000000000000000000000000
+LIQUIDATION_ENGINE_ADDRESS=0x0000000000000000000000000000000000000000
+PROTOCOL_VAULT_ADDRESS=0x0000000000000000000000000000000000000000
+PRICE_ORACLE_ADDRESS=0x0000000000000000000000000000000000000000
+
+# Trading Settings (optional)
+DEFAULT_LEVERAGE=3
+DEFAULT_SLIPPAGE=0.5
+MAX_LEVERAGE=10
+MIN_POSITION_SIZE=100
+
+# Gas Settings (optional)
+GAS_PRICE_MULTIPLIER=1.1
+MAX_GAS_PRICE=100
+GAS_LIMIT=500000
+
+# Display Settings (optional)
+DISPLAY_CURRENCY=USD
+DISPLAY_DECIMALS=2
+
+# API Keys (if using external services)
+COINGECKO_API_KEY=
+ETHERSCAN_API_KEY=
+
+# Development Settings
+DEBUG=false
+LOG_LEVEL=info

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 1.1.0
+
+- Maker/taker fee support
+- Configurable funding parameters
+- Improved error handling with full custom error decoding
+- `simulateAndWriteContract` walks viem error chain for decoded error names
+- Added `contractErrorName` and `contractErrorArgs` to simulation errors
+
+## 1.0.0
+
+- Initial release
+- Viem-based contract interactions for Alpha Futures protocol
+- Position management (open, close, liquidate)
+- Margin management (deposit, withdraw)
+- Order management (limit orders, cancel)
+- Market data queries (depth, spread, funding)
+- CLI tool (`alf`)

package/README.md

@@ -0,0 +1,199 @@
+# @megatao/sdk
+
+TypeScript SDK for the Alpha Futures perpetual futures protocol on Bittensor EVM.
+
+## Installation
+
+```bash
+npm install @megatao/sdk
+```
+
+**Peer dependency:** requires `viem ^2.0.0`
+
+## Quick Start
+
+```typescript
+import { AlphaFuturesClient, parseEther } from '@megatao/sdk';
+
+const client = new AlphaFuturesClient('localhost', {
+  rpcUrl: 'http://localhost:8545',
+  privateKey: '0x...',
+});
+
+const alpha = client.getAlpha();
+
+await alpha.deposit(parseEther('100'));
+await alpha.openMarketPosition(
+  '0xMarketAddress',
+  true,              // isLong
+  parseEther('10'),  // margin
+  3000000000000000000n, // 3x leverage (1e18 format)
+  100n,              // maxSlippage (bps)
+);
+```
+
+## Architecture
+
+`AlphaFuturesClient` creates viem clients internally and exposes two contract wrappers:
+
+- **`client.getAlpha()`** → `AlphaViem` — all trading, margin, positions, orders, vault, and market operations
+- **`client.oracle`** → `PriceOracleViem` — price feeds from the on-chain oracle
+
+All value parameters use native `bigint`. Prices, leverage, and margin use **1e18** precision. Slippage is in **basis points**.
+
+## API Reference
+
+### Trading
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `openMarketPosition` | `market, isLong, margin, leverage, maxSlippage` | Open a market position with slippage protection |
+| `openMarketPositionWithStruct` | `MarketPositionParams` | Open position using a params struct |
+| `closePosition` | `positionId, sizeToClose` | Close (or partially close) a position |
+| `closeAllPositions` | `positionIds[]` | Batch-close multiple positions via multicall |
+| `multicall` | `{functionName, args}[]` | Batch arbitrary contract calls in one tx |
+| `placeLimitOrder` | `market, isBuy, margin, leverage, price, reduceOnlyType?` | Place a limit order on the orderbook |
+| `placeLimitOrderWithStruct` | `LimitOrderParams` | Place limit order using a params struct |
+| `cancelOrder` | `orderId` | Cancel a specific limit order |
+| `cancelAllOrders` | `market` | Cancel all orders in a market |
+
+### Margin
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `deposit` | `amount` | Deposit collateral (sends native value for native token) |
+| `withdraw` | `amount` | Withdraw available margin |
+| `getMarginBalance` | `trader` | Raw deposited balance (excludes unrealized PnL) |
+| `getAccountSummary` | `trader` | Balance, equity, unrealized PnL, locked and available margin |
+| `getLockedMargin` | `trader` | Margin locked in open positions |
+| `getAvailableMargin` | `trader` | Free margin available for new trades |
+| `getMaxUserDeposit` | — | Per-user deposit cap |
+| `getMaxGlobalDeposits` | — | Protocol-wide deposit cap |
+| `getTotalDeposits` | — | Total deposits across all users |
+
+### Positions
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `getPosition` | `positionId` | Full position data (margin, notional, entry price, etc.) |
+| `getPositionDetails` | `positionId` | Extended position details struct |
+| `getPositionId` | `trader, market` | Derive position ID from trader + market |
+| `hasPosition` | `trader, market` | Check if a position exists |
+| `getUserPositions` | `trader` | All position IDs for a trader |
+| `getUserPositionsSummary` | `trader` | Aggregate stats across all positions |
+| `calculateUnrealizedPnl` | `positionId` | Current unrealized PnL |
+| `getMarginRatio` | `positionId` | Current margin ratio |
+| `isLiquidatable` | `positionId` | Whether position can be liquidated |
+| `getLiquidationStatus` | `positionId` | Liquidatable flag, margin ratio, required margin, liq price |
+
+### Orders
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `getBestBid` | `market` | Best bid order ID |
+| `getBestAsk` | `market` | Best ask order ID |
+| `getUserOrders` | `trader, market` | All open order IDs for a trader in a market |
+| `getOrderDetails` | `orderId` | Order info (trader, direction, notional, price, reduceOnly) |
+
+### Markets
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `getMarketInfo` | `market` | OI, funding rate, active status, leverage/margin params |
+| `getMarketOpenInterest` | `market` | Long and short open interest |
+| `getFundingRate` | `market` | Current funding rate |
+| `getFundingState` | `market` | Rate, cumulative index, last update, next funding time |
+| `getMaxPositionSize` | `market` | Maximum allowed position size |
+| `getMarketDepth` | `market, isBuy, levels` | Orderbook depth levels and total liquidity |
+| `getBidAskSpread` | `market` | Current bid-ask spread info |
+| `getVWAP` | `market, size, isBuy` | Volume-weighted average price for a given size |
+| `estimateMarketImpact` | `market, size, isBuy` | Price impact estimate (avg/worst price, slippage) |
+| `getMarketLiquidityAnalysis` | `market` | Comprehensive liquidity analysis struct |
+
+### Oracle (`client.oracle`)
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `getPrice` | `asset` | Current price from on-chain reserves |
+| `getLatestPriceData` | `asset` | Price + timestamp |
+| `getPriceData` | `asset` | Price, timestamp, and confidence |
+| `getMultiplePrices` | `assets[]` | Batch price fetch for multiple assets |
+| `subscribeToPriceUpdates` | `callback, asset?` | Watch for PriceUpdated events |
+
+### Vault
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `getVaultStats` | — | Total reserves, available reserves, exposure, unrealized PnL |
+| `getVaultBalance` | — | Raw vault balance |
+| `getVaultState` | — | Full vault state struct |
+| `getVaultExposure` | `market` | Long/short/net exposure and utilization rate |
+
+### Execution
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `calculateVaultSlippage` | `market, size, isBuy` | Estimated slippage from vault fill |
+| `getOptimalExecutionPlan` | `market, size, isLong, maxSlippage` | Optimal split between orderbook and vault |
+| `getExecutionStrategyAnalysis` | `market, size, isLong, maxSlippage` | Detailed execution strategy breakdown |
+
+### Keeper / Liquidation
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `liquidatePosition` | `positionId` | Liquidate an under-margined position |
+| `claimKeeperRewards` | — | Claim accumulated keeper rewards |
+| `updateFundingRates` | `markets[]` | Trigger funding rate update for markets |
+
+### Events
+
+| Method | Description |
+|--------|-------------|
+| `parsePositionOpenedEvent(receipt)` | Extract PositionOpened from tx receipt |
+| `parsePositionClosedEvent(receipt)` | Extract PositionClosed from tx receipt |
+| `parseOrderPlacedEvent(receipt)` | Extract OrderPlaced from tx receipt |
+| `parseHybridOrderExecutedEvent(receipt)` | Extract HybridOrderExecuted from tx receipt |
+| `watchPositionOpenedEvent(callback)` | Subscribe to PositionOpened events |
+| `watchMarginDepositedEvent(callback)` | Subscribe to MarginDeposited events |
+| `watchMarginWithdrawnEvent(callback)` | Subscribe to MarginWithdrawn events |
+| `getPositionOpenedEvents(from?, to?, trader?)` | Query past PositionOpened events |
+| `getMarginDepositedEvents(from?, to?, trader?)` | Query past MarginDeposited events |
+| `getMarginWithdrawnEvents(from?, to?, trader?)` | Query past MarginWithdrawn events |
+
+### Helpers
+
+| Method | Description |
+|--------|-------------|
+| `waitForTransaction(hash)` | Wait for tx confirmation and return receipt |
+| `getContractAddress()` | Alpha contract address |
+| `getConstants()` | All protocol constants (precision, max leverage, fees, etc.) |
+| `readContract({functionName, args})` | Generic read for unlisted view functions |
+| `estimateGas(functionName, args)` | Estimate gas for any contract call |
+
+## Error Handling
+
+```typescript
+import { ContractError } from '@megatao/sdk';
+
+try {
+  await alpha.openMarketPosition(market, true, margin, leverage, slippage);
+} catch (err) {
+  if (err instanceof ContractError) {
+    console.error(err.contractName, err.method, err.message);
+  }
+}
+```
+
+## CLI
+
+The SDK ships a CLI binary called `alf`:
+
+```bash
+npx alf --help
+npx alf account balance
+npx alf position list
+```
+
+## License
+
+MIT

package/bin/alf

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+require('tsx/cjs');
+require('../cli/index.ts');

package/cli/README.md

@@ -0,0 +1,198 @@
+# Alpha Futures CLI
+
+A comprehensive command-line interface for interacting with the Alpha Futures perpetual futures protocol.
+
+## Installation
+
+```bash
+npm install -g @alpha-futures/sdk
+```
+
+Or run directly with npx:
+```bash
+npx @alpha-futures/sdk
+```
+
+## Quick Start
+
+### Set up your environment
+```bash
+# Configure your private key (never share this!)
+export PRIVATE_KEY=your_private_key_here
+
+# Or save it in the config
+alpha-futures config set privateKey YOUR_KEY
+```
+
+### Basic Commands
+
+```bash
+# Check your balance
+alpha-futures account balance
+
+# Deposit TAO to your margin account
+alpha-futures account deposit 100
+
+# Open a position
+alpha-futures trade market -a ALPHA -s buy -z 1000 -m 100
+
+# List your positions
+alpha-futures position list
+
+# Close a position
+alpha-futures position close 0x00000000000000000000000000000001
+```
+
+## Interactive Mode
+
+Start an interactive trading session:
+```bash
+alpha-futures interactive
+```
+
+## Commands Overview
+
+### Account Management
+- `account balance [address]` - Check margin account balance
+- `account deposit <amount>` - Deposit TAO to margin account
+- `account withdraw <amount>` - Withdraw TAO from margin account
+- `account history` - View transaction history
+
+### Position Management
+- `position list` - List all positions
+- `position info <positionId>` - Get detailed position information
+- `position open` - Open a new position (interactive)
+- `position close <positionId> [size]` - Close a position
+- `position modify <positionId>` - Add or remove margin
+
+**Note:** Position IDs must be in bytes16 format (32 hex characters after 0x).
+Use `position find` to get your position IDs. Example: `0x00000000000000000000000000000001`
+
+### Trading
+- `trade market` - Execute a market order
+- `trade limit` - Place a limit order (coming soon)
+- `trade quick` - Quick trade with prompts
+- `trade close-all` - Close all open positions
+- `trade calc` - Position sizing calculator
+
+### Market Data
+- `market price <asset>` - Get current price
+- `market funding [asset]` - View funding rates
+- `market oi [asset]` - View open interest
+- `market stats` - Protocol statistics
+- `market list` - List all markets
+
+### Liquidations
+- `liquidation check` - Check for liquidatable positions
+- `liquidation execute <id>` - Execute a liquidation
+- `liquidation monitor` - Monitor for opportunities
+- `liquidation history` - View liquidation history
+
+### Vault Information
+- `vault info` - Get vault overview
+- `vault exposure [asset]` - View vault exposure
+- `vault performance` - Performance metrics
+- `vault health` - Health check
+
+### Configuration
+- `config set <key> <value>` - Set configuration value
+- `config get <key>` - Get configuration value
+- `config list` - List all configuration
+- `config reset` - Reset to defaults
+
+## Configuration Options
+
+The CLI can be configured using:
+1. Command-line flags
+2. Environment variables
+3. Configuration file (`~/.alpha-futures/config.json`)
+
+### Available Options
+
+| Option | Flag | Environment | Description |
+|--------|------|-------------|-------------|
+| Network | `-n, --network` | `ALPHA_NETWORK` | Network to connect to |
+| RPC URL | `-r, --rpc` | `RPC_URL` | Custom RPC endpoint |
+| Private Key | `-k, --key` | `PRIVATE_KEY` | Private key for transactions |
+| Default Asset | - | - | Default trading asset |
+| Default Leverage | - | - | Default leverage (1-10) |
+| Confirmations | - | - | Require confirmations |
+
+## Examples
+
+### Open a 3x leveraged long position
+```bash
+alpha-futures trade market -a ALPHA -s buy -z 3000 -m 1000
+```
+
+### Monitor liquidations with auto-execution
+```bash
+alpha-futures liquidation monitor --auto --interval 10
+```
+
+### Watch a position in real-time
+```bash
+alpha-futures position info 0x00000000000000000000000000000001 --watch
+```
+
+### Quick deposit and trade
+```bash
+# Deposit 500 TAO
+alpha-futures account deposit 500
+
+# Open interactive trade
+alpha-futures trade quick
+```
+
+## Safety Tips
+
+1. **Never share your private key**
+2. **Always verify transaction details before confirming**
+3. **Start with small positions to understand the platform**
+4. **Monitor your margin ratio to avoid liquidations**
+5. **Understand funding rates before opening positions**
+
+## Advanced Usage
+
+### Using with scripts
+```bash
+# Get position data as JSON
+alpha-futures position list --json | jq '.positions[] | select(.asset=="ALPHA")'
+
+# Batch operations
+alpha-futures position list --json | \
+  jq -r '.positions[] | select(.pnl < 0) | .id' | \
+  xargs -I {} alpha-futures position close {}
+
+# Note: Position IDs in JSON output are already in correct bytes16 format
+```
+
+### Custom RPC endpoints
+```bash
+alpha-futures --rpc https://your-rpc-endpoint.com market price ALPHA
+```
+
+## Troubleshooting
+
+### Connection Issues
+- Check your internet connection
+- Verify RPC endpoint is accessible
+- Ensure private key is correctly formatted
+
+### Transaction Failures
+- Check account balance for sufficient funds
+- Verify gas price settings
+- Review error messages for specific issues
+
+### Getting Help
+```bash
+# Show general help
+alpha-futures --help
+
+# Show command-specific help
+alpha-futures trade market --help
+```
+
+## License
+
+MIT