@megatao/sdk 1.1.0

package/src/abi/README.md

@@ -0,0 +1,99 @@
+# ABI Integration
+
+This directory contains the Application Binary Interfaces (ABIs) for the Alpha Futures smart contracts.
+
+## Overview
+
+ABIs are JSON representations of smart contract interfaces that enable the SDK to interact with deployed contracts on the blockchain. They define:
+- Function signatures
+- Event definitions
+- Error types
+- Data structures
+
+## Generating ABIs
+
+ABIs are generated from the compiled contracts using the provided script:
+
+```bash
+# Generate ABIs from compiled contracts
+npm run generate:abis
+
+# Or directly
+npm run generate
+```
+
+## Prerequisites
+
+Before generating ABIs, ensure that:
+1. The contracts are compiled: `forge build` (run from the root directory)
+2. The compiled artifacts exist in the `out/` directory
+
+## File Structure
+
+```
+src/abi/
+├── README.md                      # This file
+├── index.ts                       # Main export file for all ABIs
+├── abis.ts                        # Type-safe ABI definitions for Viem
+├── MarginAccount.json             # MarginAccount contract ABI
+├── PositionManager.json           # PositionManager contract ABI
+├── FundingRateEngine.json         # FundingRateEngine contract ABI
+├── LiquidationEngine.json         # LiquidationEngine contract ABI
+├── ProtocolVault.json             # ProtocolVault contract ABI
+├── AlphaFuturesOrderBook.json     # OrderBook contract ABI
+├── AccessController.json          # AccessController contract ABI
+├── ConditionalOrderManager.json   # ConditionalOrderManager contract ABI
+├── MatchingEngineModule.json      # MatchingEngine module ABI
+├── CommitRevealModule.json        # CommitReveal module ABI
+└── ...                           # Other contract ABIs
+```
+
+## Usage with Viem
+
+The SDK uses Viem for automatic type inference from ABIs - no code generation needed:
+
+```typescript
+import { getContract } from 'viem';
+import { MarginAccountABI } from '../abi/abis';
+
+const contract = getContract({
+  address: '0x...',
+  abi: MarginAccountABI,
+  client: publicClient
+});
+
+// Full type safety and autocomplete
+const balance = await contract.read.getBalance(['0x...']);
+```
+
+## Type Safety
+
+Viem provides automatic type inference directly from your ABI definitions:
+- **Zero Code Generation**: Types are inferred at compile time
+- **Always Up-to-Date**: Types automatically update when ABIs change
+- **Full IntelliSense**: Complete autocomplete for all contract methods
+- **Type-Safe Parameters**: Function arguments are fully typed
+
+## Adding New Contracts
+
+To add a new contract to the ABI system:
+
+1. Add the contract name to the `CONTRACTS` array in `scripts/generate-abis.ts`
+2. Ensure the contract is compiled
+3. Run `npm run generate` to generate the ABI
+4. Update `ViemContractFactory.ts` to include the new contract
+5. Create a Viem wrapper class in `src/contracts/viem/` if needed
+
+## Manual ABI Updates
+
+If you need to manually update an ABI:
+1. Place the ABI JSON file in this directory
+2. Update `index.ts` to export the new ABI
+3. Update `abis.ts` with the type-safe ABI definition
+
+## Important Notes
+
+- ABIs are generated from compiled contracts, so always compile before generating
+- The generated ABI files should be committed to version control
+- If contract interfaces change, regenerate ABIs
+- The SDK uses Viem's automatic type inference - no TypeChain generation needed

package/src/abi/abis.ts

@@ -0,0 +1,131 @@
+/**
+ * Type-safe ABI definitions using Viem and ABIType
+ * This file provides properly typed ABIs that enable automatic type inference
+ *
+ * Alpha.json contains the complete monolithic contract ABI including:
+ * - Trading operations (open/close positions)
+ * - Margin management
+ * - Orderbook functionality
+ * - Position management
+ * - Vault operations
+ * - Admin functions
+ * - Price oracle integration
+ * - Access control
+ */
+
+import { type Abi } from 'viem';
+import AlphaABIJSON from './Alpha.json';
+
+// ERC20 Token ABI (for TAO and other collateral tokens)
+export const ERC20ABI = [
+  {
+    type: 'function',
+    name: 'transfer',
+    inputs: [
+      { name: 'to', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+    ],
+    outputs: [{ name: 'success', type: 'bool' }],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'transferFrom',
+    inputs: [
+      { name: 'from', type: 'address' },
+      { name: 'to', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+    ],
+    outputs: [{ name: 'success', type: 'bool' }],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'approve',
+    inputs: [
+      { name: 'spender', type: 'address' },
+      { name: 'amount', type: 'uint256' },
+    ],
+    outputs: [{ name: 'success', type: 'bool' }],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'balanceOf',
+    inputs: [{ name: 'account', type: 'address' }],
+    outputs: [{ name: 'balance', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'allowance',
+    inputs: [
+      { name: 'owner', type: 'address' },
+      { name: 'spender', type: 'address' },
+    ],
+    outputs: [{ name: 'remaining', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'decimals',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint8' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'symbol',
+    inputs: [],
+    outputs: [{ name: '', type: 'string' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'name',
+    inputs: [],
+    outputs: [{ name: '', type: 'string' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'event',
+    name: 'Transfer',
+    inputs: [
+      { name: 'from', type: 'address', indexed: true },
+      { name: 'to', type: 'address', indexed: true },
+      { name: 'value', type: 'uint256', indexed: false },
+    ],
+  },
+  {
+    type: 'event',
+    name: 'Approval',
+    inputs: [
+      { name: 'owner', type: 'address', indexed: true },
+      { name: 'spender', type: 'address', indexed: true },
+      { name: 'value', type: 'uint256', indexed: false },
+    ],
+  },
+] as const satisfies Abi;
+
+// Price Oracle ABI (for standalone oracle contract)
+export const PriceOracleABI = [
+  {
+    type: 'function',
+    name: 'calculatePriceFromReserves',
+    inputs: [{ name: 'netUid', type: 'uint16' }],
+    outputs: [{ name: '', type: 'uint256' }],
+    stateMutability: 'view',
+  },
+] as const satisfies Abi;
+
+// Export all ABIs as a typed object
+export const ABIs = {
+  Alpha: AlphaABIJSON as Abi,
+  ERC20: ERC20ABI,
+  PriceOracle: PriceOracleABI,
+} as const;
+
+// Type exports for better developer experience
+export type ERC20ABI = typeof ERC20ABI;
+export type PriceOracleABI = typeof PriceOracleABI;
+export type AlphaABI = typeof AlphaABIJSON;

package/src/abi/index.ts

@@ -0,0 +1,13 @@
+/**
+ * ABI exports for Alpha Futures Protocol
+ *
+ * Alpha.json: Complete monolithic contract ABI
+ * ERC20ABI: Standard ERC20 token interface for TAO and collateral
+ * PriceOracleABI: Standalone price oracle contract interface
+ */
+
+export { ABIs, ERC20ABI, PriceOracleABI } from './abis';
+export type { ERC20ABI as ERC20ABIType, PriceOracleABI as PriceOracleABIType } from './abis';
+
+// Export Alpha ABI type from abis.ts to avoid duplication
+export type { AlphaABI } from './abis';

package/src/config/contracts.config.ts

@@ -0,0 +1,186 @@
+/**
+ * Contract configuration management for Alpha Futures SDK
+ * Handles loading and managing contract addresses across different networks
+ */
+
+// Contract configuration management
+import { NETWORK_CONFIGS, isValidNetwork } from '../constants/networks';
+
+import { Address } from 'viem';
+
+export interface ContractAddresses {
+  alpha: Address;
+  priceOracle: Address;
+  collateralToken: Address;
+}
+
+export interface DeploymentInfo {
+  network: string;
+  chainId: number;
+  deploymentDate: string;
+  deployer: string;
+  contracts: {
+    [contractName: string]: {
+      address: string;
+      transactionHash: string;
+      blockNumber: number;
+      constructorArguments?: unknown[];
+    };
+  };
+  configuration?: {
+    [key: string]: string | number;
+  };
+}
+
+export class ContractsConfig {
+  private static instance: ContractsConfig;
+  private deployments: Map<string, DeploymentInfo> = new Map();
+  private overrides: Map<string, Partial<ContractAddresses>> = new Map();
+
+  private constructor() {
+    // No filesystem loading - use static network configurations only
+  }
+
+  /**
+   * Gets the singleton instance
+   */
+  public static getInstance(): ContractsConfig {
+    if (!ContractsConfig.instance) {
+      ContractsConfig.instance = new ContractsConfig();
+    }
+    return ContractsConfig.instance;
+  }
+
+  /**
+   * Gets contract addresses for a network
+   */
+  public getContractAddresses(network: string): ContractAddresses {
+    if (!isValidNetwork(network)) {
+      throw new Error(`Invalid network: ${network}`);
+    }
+
+    // Start with default addresses from network config
+    const networkConfig = NETWORK_CONFIGS[network];
+    const addresses: ContractAddresses = {
+      alpha:
+        networkConfig.contracts.alpha || ('0x0000000000000000000000000000000000000000' as Address),
+      priceOracle:
+        networkConfig.contracts.priceOracle ||
+        ('0x0000000000000000000000000000000000000000' as Address),
+      collateralToken:
+        networkConfig.contracts.collateralToken ||
+        ('0x0000000000000000000000000000000000000000' as Address),
+    };
+
+    // Apply deployment addresses if available
+    const deployment = this.deployments.get(network);
+    if (deployment) {
+      for (const [contractName, contractData] of Object.entries(deployment.contracts)) {
+        const key = this.normalizeContractName(contractName);
+        if (key in addresses) {
+          (addresses as any)[key] = contractData.address;
+        }
+      }
+    }
+
+    // Apply any overrides
+    const overrides = this.overrides.get(network);
+    if (overrides) {
+      Object.assign(addresses, overrides);
+    }
+
+    return addresses;
+  }
+
+  /**
+   * Normalizes contract names to match the expected format
+   */
+  private normalizeContractName(name: string): string {
+    // Convert from PascalCase to camelCase
+    const camelCase = name.charAt(0).toLowerCase() + name.slice(1);
+
+    // Handle special cases
+    const mappings: { [key: string]: string } = {
+      collateralToken: 'collateralToken',
+      CollateralToken: 'collateralToken',
+    };
+
+    return mappings[camelCase] || camelCase;
+  }
+
+  /**
+   * Sets contract address overrides for a network
+   */
+  public setContractOverrides(network: string, overrides: Partial<ContractAddresses>): void {
+    if (!isValidNetwork(network)) {
+      throw new Error(`Invalid network: ${network}`);
+    }
+    this.overrides.set(network, overrides);
+  }
+
+  /**
+   * Clears contract address overrides for a network
+   */
+  public clearContractOverrides(network: string): void {
+    this.overrides.delete(network);
+  }
+
+  /**
+   * Gets deployment information for a network
+   */
+  public getDeploymentInfo(network: string): DeploymentInfo | undefined {
+    return this.deployments.get(network);
+  }
+
+  /**
+   * Updates contract configuration with new addresses
+   */
+  public updateNetworkConfig(network: string, addresses: ContractAddresses): void {
+    if (!isValidNetwork(network)) {
+      throw new Error(`Invalid network: ${network}`);
+    }
+
+    // Update the network config
+    NETWORK_CONFIGS[network].contracts = addresses;
+
+    // Also update in deployments if exists
+    const deployment = this.deployments.get(network);
+    if (deployment) {
+      for (const [key, address] of Object.entries(addresses)) {
+        const contractName = key.charAt(0).toUpperCase() + key.slice(1);
+        if (!deployment.contracts[contractName]) {
+          deployment.contracts[contractName] = {
+            address,
+            transactionHash: '0x0',
+            blockNumber: 0,
+          };
+        } else {
+          deployment.contracts[contractName].address = address;
+        }
+      }
+    }
+  }
+
+  /**
+   * Validates that all required contracts are deployed for a network
+   */
+  public validateDeployment(network: string): { valid: boolean; missing: string[] } {
+    const addresses = this.getContractAddresses(network);
+    const required = ['alpha', 'priceOracle', 'collateralToken'];
+
+    const missing = required.filter(
+      (contract) =>
+        !addresses[contract as keyof ContractAddresses] ||
+        addresses[contract as keyof ContractAddresses] ===
+          '0x0000000000000000000000000000000000000000',
+    );
+
+    return {
+      valid: missing.length === 0,
+      missing,
+    };
+  }
+}
+
+// Export singleton instance
+export const contractsConfig = ContractsConfig.getInstance();

package/src/config/environments/alpha.config.ts

@@ -0,0 +1,139 @@
+/**
+ * Alpha Environment Configuration (Bittensor Mainnet - Testing)
+ *
+ * Collateral: Mock wTAO with 18 decimals
+ * Markets: 12 Bittensor subnets
+ * Network: Bittensor Finney (Chain ID: 964)
+ *
+ * LAST SYNCED: 2026-02-13
+ * DEPLOYMENT: deployments/alpha/deployment.json
+ *
+ * NOTE: This environment is deployed on Bittensor mainnet.
+ * Deployment Timestamp: 1769197297 (January 2026)
+ * Deployer: 0xa3A00185748B64eDA4149745415080cBA720E720
+ */
+
+import { NetworkConfig } from '../../types';
+
+export const ALPHA_CONFIG: NetworkConfig = {
+  chainId: 964,
+  name: 'Alpha Futures - Bittensor Mainnet',
+  rpcUrl: 'https://bittensor-finney.api.onfinality.io/public', // Primary RPC
+  blockExplorer: 'https://evm.taostats.io/',
+  contracts: {
+    alpha: '0x5E29Ac73dFbc5906971343a191c1fc37C41286f7', // Alpha Futures Protocol (Proxy)
+    priceOracle: '0x30583DDB209128566A5433DA3384023d3575b20d',
+    collateralToken: '0x0000000000000000000000000000000000000000', // Mock wTAO Token
+  },
+  collateralTokenInfo: {
+    symbol: 'TAO',
+    decimals: 18,
+    name: 'TAO',
+  },
+  markets: [
+    {
+      id: 64,
+      name: 'Chutes',
+      marketAddress: '0x0000000000000000000000000000000000000040',
+      symbol: 'CHUTES',
+      displayName: 'Chutes (SN64)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 51,
+      name: 'lium.io',
+      marketAddress: '0x0000000000000000000000000000000000000033',
+      symbol: 'LIUM',
+      displayName: 'lium.io (SN51)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 62,
+      name: 'Ridges',
+      marketAddress: '0x000000000000000000000000000000000000003e',
+      symbol: 'RIDGES',
+      displayName: 'Ridges (SN62)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 4,
+      name: 'Targon',
+      marketAddress: '0x0000000000000000000000000000000000000004',
+      symbol: 'TARGON',
+      displayName: 'Targon (SN4)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 8,
+      name: 'Vanta',
+      marketAddress: '0x0000000000000000000000000000000000000008',
+      symbol: 'VANTA',
+      displayName: 'Vanta (SN8)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 120,
+      name: 'Affine',
+      marketAddress: '0x0000000000000000000000000000000000000078',
+      symbol: 'AFFINE',
+      displayName: 'Affine (SN120)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 3,
+      name: 'templar',
+      marketAddress: '0x0000000000000000000000000000000000000003',
+      symbol: 'TEMPLAR',
+      displayName: 'templar (SN3)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 44,
+      name: 'Score',
+      marketAddress: '0x000000000000000000000000000000000000002c',
+      symbol: 'SCORE',
+      displayName: 'Score (SN44)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 9,
+      name: 'iota',
+      marketAddress: '0x0000000000000000000000000000000000000009',
+      symbol: 'IOTA',
+      displayName: 'iota (SN9)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 56,
+      name: 'Gradients',
+      marketAddress: '0x0000000000000000000000000000000000000038',
+      symbol: 'GRADIENTS',
+      displayName: 'Gradients (SN56)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 75,
+      name: 'Hippius',
+      marketAddress: '0x000000000000000000000000000000000000004b',
+      symbol: 'HIPPIUS',
+      displayName: 'Hippius (SN75)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 34,
+      name: 'BitMind',
+      marketAddress: '0x0000000000000000000000000000000000000022',
+      symbol: 'BITMIND',
+      displayName: 'BitMind (SN34)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 65534,
+      name: 'MTSOS',
+      marketAddress: '0x000000000000000000000000000000000000FFFE',
+      symbol: 'MTSOS',
+      displayName: 'MegaTAO Sum-of-Subnets Index',
+      hasOraclePrice: true,
+    },
+  ],
+};

package/src/config/environments/beta.config.ts

@@ -0,0 +1,130 @@
+/**
+ * Beta Environment Configuration (Staging)
+ *
+ * Uses Mock USDC with 6 decimals
+ * 2 generic markets: ALPHA_BTC, ALPHA_ETH
+ * Initial vault: 1,000 USDC
+ *
+ * LAST SYNCED: 2025-12-09
+ * DEPLOYMENT: deployments/beta/deployment.json
+ *
+ * Deployed: 2025-12-08
+ * Same collateral/oracle as alpha environment
+ */
+
+import { NetworkConfig } from '../../types';
+
+export const BETA_CONFIG: NetworkConfig = {
+  chainId: 964,
+  name: 'Alpha Futures - Beta Staging',
+  rpcUrl: 'https://bittensor-finney.api.onfinality.io/public',
+  blockExplorer: 'https://evm.taostats.io/',
+  contracts: {
+    alpha: '0xa57D785194De368d8944c39b4c2d2F7A3F548132',
+    priceOracle: '0x6541318525de2FBB108a35Ecd57b14E9A5418fCC',
+    collateralToken: '0x26804e3F75e7ABA449FD0B46479E0a196417bFA6', // Mock USDC
+  },
+  collateralTokenInfo: {
+    symbol: 'USDC',
+    decimals: 6,
+    name: 'Mock USDC',
+  },
+  markets: [
+    {
+      id: 64,
+      name: 'Chutes',
+      marketAddress: '0x0000000000000000000000000000000000000040',
+      symbol: 'CHUTES',
+      displayName: 'Chutes (SN64)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 51,
+      name: 'lium.io',
+      marketAddress: '0x0000000000000000000000000000000000000033',
+      symbol: 'LIUM',
+      displayName: 'lium.io (SN51)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 62,
+      name: 'Ridges',
+      marketAddress: '0x000000000000000000000000000000000000003e',
+      symbol: 'RIDGES',
+      displayName: 'Ridges (SN62)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 4,
+      name: 'Targon',
+      marketAddress: '0x0000000000000000000000000000000000000004',
+      symbol: 'TARGON',
+      displayName: 'Targon (SN4)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 8,
+      name: 'Vanta',
+      marketAddress: '0x0000000000000000000000000000000000000008',
+      symbol: 'VANTA',
+      displayName: 'Vanta (SN8)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 120,
+      name: 'Affine',
+      marketAddress: '0x0000000000000000000000000000000000000078',
+      symbol: 'AFFINE',
+      displayName: 'Affine (SN120)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 3,
+      name: 'templar',
+      marketAddress: '0x0000000000000000000000000000000000000003',
+      symbol: 'TEMPLAR',
+      displayName: 'templar (SN3)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 44,
+      name: 'Score',
+      marketAddress: '0x000000000000000000000000000000000000002c',
+      symbol: 'SCORE',
+      displayName: 'Score (SN44)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 9,
+      name: 'iota',
+      marketAddress: '0x0000000000000000000000000000000000000009',
+      symbol: 'IOTA',
+      displayName: 'iota (SN9)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 56,
+      name: 'Gradients',
+      marketAddress: '0x0000000000000000000000000000000000000038',
+      symbol: 'GRADIENTS',
+      displayName: 'Gradients (SN56)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 75,
+      name: 'Hippius',
+      marketAddress: '0x000000000000000000000000000000000000004b',
+      symbol: 'HIPPIUS',
+      displayName: 'Hippius (SN75)',
+      hasOraclePrice: true,
+    },
+    {
+      id: 34,
+      name: 'BitMind',
+      marketAddress: '0x0000000000000000000000000000000000000022',
+      symbol: 'BITMIND',
+      displayName: 'BitMind (SN34)',
+      hasOraclePrice: true,
+    },
+  ],
+};