@megatao/sdk 1.1.0

package/cli/TEST_MANUAL.md

@@ -0,0 +1,577 @@
+# Manual CLI Testing Guide
+
+## Overview
+This guide provides comprehensive manual testing procedures for the Alpha Futures CLI, focusing on the collateral-first position opening paradigm and backward compatibility with the size-first paradigm.
+
+## Prerequisites
+
+1. **Environment Setup**
+   ```bash
+   cd /Users/er/Documents/Projects/ALPHA/alpha-futures/sdk
+   npm install
+   npm run build
+   ```
+
+2. **Configuration**
+   - Ensure `.env` file exists with valid RPC URL and private key
+   - Verify wallet has sufficient TAO balance
+   - Confirm contracts are deployed and addresses are correct
+
+3. **Check Current State**
+   ```bash
+   # View your wallet balance
+   npm run cli -- balance
+
+   # View existing positions
+   npm run cli -- position list
+   ```
+
+## Test Suite 1: Collateral-First Paradigm (New)
+
+### Test 1.1: Basic Long Position with Fractional Leverage
+**Objective:** Open a long position using collateral-first paradigm with fractional leverage
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 100 \
+  --leverage 3.5 \
+  --yes
+```
+
+**Expected Result:**
+- Position opens successfully
+- Position size: ~18,421 BITMIND tokens (at $0.019 price)
+- Position value: $350 (100 * 3.5)
+- Leverage: 3.5x
+- Success message displayed
+
+**Verification:**
+```bash
+npm run cli -- position list
+npm run cli -- position status <position-id>
+```
+
+### Test 1.2: Short Position with Fractional Leverage
+**Objective:** Open a short position with fractional leverage
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction short \
+  --collateral 50 \
+  --leverage 2.7 \
+  --yes
+```
+
+**Expected Result:**
+- Short position opens successfully
+- Position size calculated based on collateral * leverage / price
+- Leverage: 2.7x
+- Direction: SHORT
+
+### Test 1.3: Minimum Collateral Trade
+**Objective:** Test minimum viable collateral amount
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 0.01 \
+  --leverage 1.0 \
+  --yes
+```
+
+**Expected Result:**
+- Position opens with minimum collateral (0.01 TAO)
+- Position size calculated correctly
+- No errors or warnings
+
+### Test 1.4: Maximum Leverage Trade
+**Objective:** Test maximum allowed leverage (30x)
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 10 \
+  --leverage 30 \
+  --yes
+```
+
+**Expected Result:**
+- Position opens successfully
+- Warning about high leverage risk displayed
+- Leverage: 30x
+- Position value: $300 (10 * 30)
+
+### Test 1.5: Default Leverage (3x)
+**Objective:** Test that default leverage is applied when not specified
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 25 \
+  --yes
+```
+
+**Expected Result:**
+- Position opens with 3x default leverage
+- Position value: $75 (25 * 3)
+- No leverage specified in command output
+
+### Test 1.6: All Valid Fractional Leverage Increments
+**Objective:** Test various fractional leverage values (0.1x increments)
+
+```bash
+# Test 1.1x
+npm run cli -- position open --asset BITMIND --direction long --collateral 10 --leverage 1.1 --yes
+
+# Test 5.5x
+npm run cli -- position open --asset BITMIND --direction long --collateral 10 --leverage 5.5 --yes
+
+# Test 10.7x
+npm run cli -- position open --asset BITMIND --direction long --collateral 10 --leverage 10.7 --yes
+
+# Test 29.9x
+npm run cli -- position open --asset BITMIND --direction long --collateral 10 --leverage 29.9 --yes
+```
+
+**Expected Result:**
+- All positions open successfully
+- Each leverage value is accepted and applied correctly
+
+### Test 1.7: Interactive Mode
+**Objective:** Test interactive position opening
+
+```bash
+npm run cli -- position open --asset BITMIND --interactive
+```
+
+**Steps:**
+1. Select direction: LONG
+2. Enter collateral: 50
+3. Enter leverage: 3.5
+4. Confirm trade
+
+**Expected Result:**
+- Interactive prompts work correctly
+- Position parameters calculated and displayed
+- Position opens after confirmation
+
+## Test Suite 2: Error Cases and Validation
+
+### Test 2.1: Collateral Below Minimum
+**Objective:** Verify rejection of collateral below 0.01
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 0.001 \
+  --leverage 3.5 \
+  --yes
+```
+
+**Expected Result:**
+- ERROR: "Collateral must be at least 0.01 TAO"
+- Position NOT opened
+- Clear error message displayed
+
+### Test 2.2: Invalid Leverage Precision
+**Objective:** Verify rejection of non-0.1x increments
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 100 \
+  --leverage 3.14 \
+  --yes
+```
+
+**Expected Result:**
+- ERROR: "Leverage must be in 0.1x increments"
+- Position NOT opened
+- Suggestion to use valid increments
+
+### Test 2.3: Leverage Below Minimum
+**Objective:** Verify rejection of leverage < 1.0x
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 100 \
+  --leverage 0.5 \
+  --yes
+```
+
+**Expected Result:**
+- ERROR: "Leverage must be at least 1.0x"
+- Position NOT opened
+
+### Test 2.4: Leverage Above Maximum
+**Objective:** Verify rejection of leverage > 30x
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 100 \
+  --leverage 35 \
+  --yes
+```
+
+**Expected Result:**
+- ERROR: "Leverage cannot exceed 30x"
+- Position NOT opened
+
+### Test 2.5: Zero Collateral
+**Objective:** Verify rejection of zero collateral
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 0 \
+  --leverage 3.5 \
+  --yes
+```
+
+**Expected Result:**
+- ERROR: "Collateral must be greater than zero"
+- Position NOT opened
+
+### Test 2.6: Negative Collateral
+**Objective:** Verify rejection of negative collateral
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral -100 \
+  --leverage 3.5 \
+  --yes
+```
+
+**Expected Result:**
+- ERROR: Invalid collateral value
+- Position NOT opened
+
+### Test 2.7: Insufficient Balance
+**Objective:** Verify rejection when collateral exceeds balance
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 999999999 \
+  --leverage 3.5 \
+  --yes
+```
+
+**Expected Result:**
+- ERROR: "Insufficient balance"
+- Current balance displayed
+- Position NOT opened
+
+### Test 2.8: Mixed Paradigms (Should Fail)
+**Objective:** Verify error when mixing collateral and size parameters
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 100 \
+  --size 30 \
+  --yes
+```
+
+**Expected Result:**
+- ERROR: "Cannot mix collateral-first and size-first parameters"
+- Clear explanation of which paradigm to use
+- Position NOT opened
+
+## Test Suite 3: Size-First Paradigm (Backward Compatibility)
+
+### Test 3.1: Legacy Size and Margin Command
+**Objective:** Verify backward compatibility with size-first paradigm
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --size 30 \
+  --margin 10 \
+  --yes
+```
+
+**Expected Result:**
+- Position opens successfully
+- Uses size-first calculation method
+- Position size: 30 tokens
+- Margin: 10 TAO
+- Leverage calculated as size/margin
+
+### Test 3.2: Legacy Command with Default Margin
+**Objective:** Test size-first with default margin calculation
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --size 50 \
+  --yes
+```
+
+**Expected Result:**
+- Position opens successfully
+- Margin calculated from size and default leverage
+- Works as before (backward compatible)
+
+## Test Suite 4: Advanced Scenarios
+
+### Test 4.1: High Leverage Warning Display
+**Objective:** Verify warning is shown for leverage > 20x
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 100 \
+  --leverage 25
+```
+
+**Expected Result:**
+- WARNING displayed: "High leverage (25x) increases liquidation risk"
+- User prompted for confirmation (if not using --yes flag)
+- Position opens after confirmation
+
+### Test 4.2: Multiple Positions with Different Leverage
+**Objective:** Open multiple positions with varying leverage
+
+```bash
+# Conservative position
+npm run cli -- position open --asset BITMIND --direction long --collateral 100 --leverage 2.0 --yes
+
+# Moderate position
+npm run cli -- position open --asset BITMIND --direction long --collateral 100 --leverage 5.0 --yes
+
+# Aggressive position
+npm run cli -- position open --asset BITMIND --direction long --collateral 100 --leverage 15.0 --yes
+```
+
+**Expected Result:**
+- All three positions open successfully
+- Each has distinct leverage
+- List command shows all positions
+
+### Test 4.3: Small Token Price Handling
+**Objective:** Test with very small token prices
+
+```bash
+# Assuming a low-priced token
+npm run cli -- position open \
+  --asset <LOW_PRICE_TOKEN> \
+  --direction long \
+  --collateral 100 \
+  --leverage 5.0 \
+  --yes
+```
+
+**Expected Result:**
+- Large position size calculated correctly
+- No overflow errors
+- Position opens successfully
+
+### Test 4.4: Large Collateral Amount
+**Objective:** Test with large collateral values
+
+```bash
+npm run cli -- position open \
+  --asset BITMIND \
+  --direction long \
+  --collateral 10000 \
+  --leverage 10 \
+  --yes
+```
+
+**Expected Result:**
+- Position opens successfully
+- Large position size calculated correctly
+- No precision loss
+
+### Test 4.5: Rapid Sequential Positions
+**Objective:** Test opening multiple positions quickly
+
+```bash
+for i in {1..5}; do
+  npm run cli -- position open \
+    --asset BITMIND \
+    --direction long \
+    --collateral 10 \
+    --leverage 3.0 \
+    --yes
+done
+```
+
+**Expected Result:**
+- All 5 positions open successfully
+- No race conditions or conflicts
+- Each position has unique ID
+
+## Test Suite 5: Position Management
+
+### Test 5.1: View Position Details
+**Objective:** Verify position details display correctly
+
+```bash
+# Open a position first
+npm run cli -- position open --asset BITMIND --direction long --collateral 100 --leverage 3.5 --yes
+
+# View details
+npm run cli -- position status <position-id>
+```
+
+**Expected Result:**
+- Position details displayed:
+  - Position ID
+  - Asset
+  - Direction (LONG/SHORT)
+  - Collateral: 100 TAO
+  - Leverage: 3.5x
+  - Position size in tokens
+  - Entry price
+  - Current P&L
+
+### Test 5.2: Close Position
+**Objective:** Close a position and verify settlement
+
+```bash
+# Close the position
+npm run cli -- position close <position-id> --yes
+```
+
+**Expected Result:**
+- Position closes successfully
+- P&L calculated and displayed
+- Balance updated accordingly
+- Position removed from list
+
+### Test 5.3: List All Positions
+**Objective:** Verify position list display
+
+```bash
+npm run cli -- position list
+```
+
+**Expected Result:**
+- Table showing all open positions
+- Columns: ID, Asset, Direction, Collateral, Leverage, Size, Entry Price, P&L
+- Accurate and up-to-date information
+
+## Test Suite 6: Help and Documentation
+
+### Test 6.1: Command Help
+**Objective:** Verify help messages are accurate
+
+```bash
+npm run cli -- position open --help
+```
+
+**Expected Result:**
+- Help text displayed
+- Shows both collateral-first and size-first options
+- Examples provided
+- Clear descriptions
+
+### Test 6.2: Version Check
+**Objective:** Verify version information
+
+```bash
+npm run cli -- --version
+```
+
+**Expected Result:**
+- Current version displayed
+- Matches package.json version
+
+## Post-Test Cleanup
+
+After completing tests:
+
+```bash
+# Close all open positions
+npm run cli -- position list
+npm run cli -- position close <position-id-1> --yes
+npm run cli -- position close <position-id-2> --yes
+# ... repeat for all positions
+
+# Verify all closed
+npm run cli -- position list
+```
+
+## Test Results Template
+
+For each test, record:
+
+| Test ID | Test Name | Status | Notes |
+|---------|-----------|--------|-------|
+| 1.1 | Basic Long Position | ✅ PASS | Position opened with correct params |
+| 1.2 | Short Position | ✅ PASS | - |
+| ... | ... | ... | ... |
+
+## Common Issues and Troubleshooting
+
+### Issue: "Insufficient allowance"
+**Solution:** Approve TAO spending first
+```bash
+npm run cli -- approve <amount>
+```
+
+### Issue: "Transaction reverted"
+**Check:**
+- Sufficient balance
+- Contract not paused
+- Valid asset address
+- Network connectivity
+
+### Issue: "Price unavailable"
+**Check:**
+- Oracle is functioning
+- Asset is configured
+- Network connectivity
+
+### Issue: Command not found
+**Solution:** Ensure you're in the SDK directory and have run `npm install`
+
+## Success Criteria
+
+All tests should:
+- ✅ Execute without unexpected errors
+- ✅ Produce expected results
+- ✅ Display clear messages
+- ✅ Handle edge cases gracefully
+- ✅ Maintain backward compatibility
+
+## Reporting Issues
+
+If any test fails, report:
+1. Test ID and name
+2. Command used
+3. Expected result
+4. Actual result
+5. Error messages (if any)
+6. Environment details (Node version, OS, network)
+
+## Notes
+
+- Always test on testnet first
+- Keep test amounts small to minimize costs
+- Monitor gas prices during testing
+- Record transaction hashes for debugging
+- Test with multiple wallets if possible
+- Verify calculations independently