riskmarket-sdk 1.0.0

package/README.md

@@ -0,0 +1,418 @@
+# Risk market SDK
+
+A TypeScript SDK for interacting with Risk market smart contracts and APIs.
+
+## Features
+
+- 🔥 **Type-safe** - Full TypeScript support with comprehensive type definitions
+- 🎯 **Three-tier Architecture** - Organized into API, Transactions, and Utilities
+- 🔌 **Provider Agnostic** - Works with any ethers.js provider
+- ⚡ **Transaction Preparation** - Returns unsigned transactions for frontend signing
+- 🛡️ **Error Handling** - Robust error handling with custom error types
+- 📦 **Lightweight** - Minimal dependencies
+- 🧪 **Well Tested** - Comprehensive test coverage
+
+## Installation
+
+```bash
+npm install @yourorg/protocol-sdk ethers
+```
+
+Or with yarn:
+
+```bash
+yarn add @yourorg/protocol-sdk ethers
+```
+
+## Quick Start
+
+```typescript
+import { ProtocolSDK } from "@yourorg/protocol-sdk";
+import { ethers } from "ethers";
+import YourContractABI from "./abis/YourContract.json";
+
+// Initialize the SDK
+const provider = new ethers.JsonRpcProvider("YOUR_RPC_URL");
+
+const sdk = new ProtocolSDK({
+  apiBaseURL: "https://api.yourprotocol.com",
+  provider: provider,
+  contractAddress: "0x...", // Your contract address
+  abi: YourContractABI,
+  apiKey: "your-api-key", // Optional
+  chainId: 1,
+});
+
+// Use the SDK
+const markets = await sdk.api.getAllMarkets();
+console.log("Available markets:", markets);
+```
+
+## Architecture
+
+The SDK is organized into three main components:
+
+### 1. **APIClient** - Fetching API Data
+
+Handles all API requests to your backend server.
+
+```typescript
+// Get market data
+const marketData = await sdk.api.getMarketData("market-id");
+
+// Get user balance
+const balance = await sdk.api.getUserBalance(userAddress, tokenAddress);
+
+// Get transaction history
+const txHistory = await sdk.api.getTransactionHistory(userAddress);
+
+// Get token prices
+const prices = await sdk.api.getTokenPrices([token1, token2]);
+```
+
+### 2. **TransactionBuilder** - Creating Transactions
+
+Prepares unsigned transactions that can be signed by the user's wallet.
+
+```typescript
+// Prepare a swap transaction
+const swapTx = await sdk.tx.prepareSwapTransaction({
+  tokenIn: "0x...",
+  tokenOut: "0x...",
+  amount: sdk.utils.parseAmount("1.0", 18),
+  minAmountOut: sdk.utils.parseAmount("0.95", 18),
+  deadline: sdk.utils.getDeadline(20),
+});
+
+// Sign and send (in your frontend)
+const signer = provider.getSigner();
+const txResponse = await signer.sendTransaction(swapTx);
+const receipt = await txResponse.wait();
+console.log("Transaction confirmed:", receipt.hash);
+```
+
+### 3. **Utils** - Helper Functions
+
+Utility functions for common operations.
+
+```typescript
+// Validate addresses
+const isValid = sdk.utils.isValidAddress("0x...");
+
+// Format amounts
+const formatted = sdk.utils.formatAmount("1000000000000000000", 18); // "1.0"
+
+// Parse amounts
+const parsed = sdk.utils.parseAmount("1.5", 18); // "1500000000000000000"
+
+// Get deadline
+const deadline = sdk.utils.getDeadline(20); // 20 minutes from now
+
+// Shorten hash for display
+const short = sdk.utils.shortenHash(txHash); // "0x1234...abcd"
+```
+
+## Core Classes
+
+### ProtocolSDK (Main Class)
+
+The main entry point that combines all functionality.
+
+```typescript
+const sdk = new ProtocolSDK(config);
+
+// Access components
+sdk.api; // APIClient instance
+sdk.tx; // TransactionBuilder instance
+sdk.utils; // Utils class
+
+// Helper methods
+await sdk.getNetworkInfo();
+await sdk.getBlockNumber();
+await sdk.isConnected();
+await sdk.waitForTransaction(txHash);
+```
+
+### APIClient
+
+```typescript
+class APIClient {
+  async getMarketData(marketId: string): Promise<MarketData>;
+  async getAllMarkets(): Promise<MarketData[]>;
+  async getUserBalance(address: string, token: string): Promise<UserBalance>;
+  async getAllBalances(address: string): Promise<UserBalance[]>;
+  async getTransactionHistory(
+    address: string,
+    limit?: number
+  ): Promise<Transaction[]>;
+  async getTokenPrice(tokenAddress: string): Promise<string>;
+  async getTokenPrices(
+    tokenAddresses: string[]
+  ): Promise<Record<string, string>>;
+  async get<T>(endpoint: string, params?: any): Promise<T>;
+  async post<T>(endpoint: string, data: any): Promise<T>;
+}
+```
+
+### TransactionBuilder
+
+```typescript
+class TransactionBuilder {
+  async prepareSwapTransaction(params: SwapParams): Promise<TransactionRequest>;
+  async prepareDepositTransaction(
+    params: DepositParams
+  ): Promise<TransactionRequest>;
+  async prepareWithdrawTransaction(
+    params: WithdrawParams
+  ): Promise<TransactionRequest>;
+  async prepareApprovalTransaction(
+    token: string,
+    spender?: string,
+    amount?: string
+  ): Promise<TransactionRequest>;
+  async checkAllowance(
+    token: string,
+    owner: string,
+    spender?: string
+  ): Promise<string>;
+  async needsApproval(
+    token: string,
+    owner: string,
+    amount: string
+  ): Promise<boolean>;
+  async getTokenBalance(token: string, address: string): Promise<string>;
+  async estimateGas(tx: TransactionRequest): Promise<string>;
+  async getGasPrices(): Promise<GasPrices>;
+}
+```
+
+### Utils
+
+```typescript
+class Utils {
+  static isValidAddress(address: string): boolean;
+  static validateAddress(address: string): string;
+  static formatAmount(amount: string | bigint, decimals?: number): string;
+  static parseAmount(amount: string, decimals?: number): string;
+  static validateAmount(amount: string): void;
+  static getDeadline(minutes?: number): number;
+  static calculatePercentageChange(oldValue: string, newValue: string): string;
+  static addGasBuffer(
+    gasEstimate: bigint | string,
+    bufferPercent?: number
+  ): string;
+  static parseContractError(error: any): string;
+  static waitForTransaction(
+    txHash: string,
+    provider: Provider,
+    confirmations?: number
+  ): Promise<TransactionReceipt>;
+  static getGasPrices(provider: Provider): Promise<GasPrices>;
+  static getNetworkName(chainId: number): string;
+  static sleep(ms: number): Promise<void>;
+  static retry<T>(
+    fn: () => Promise<T>,
+    maxRetries?: number,
+    delayMs?: number
+  ): Promise<T>;
+  static shortenHash(
+    hash: string,
+    startLength?: number,
+    endLength?: number
+  ): string;
+  static isTransactionSuccessful(receipt: TransactionReceipt): boolean;
+}
+```
+
+## Complete Workflow Example
+
+Here's a complete example of using the SDK in a DApp:
+
+```typescript
+import { ProtocolSDK } from "@yourorg/protocol-sdk";
+import { ethers } from "ethers";
+
+async function performSwap() {
+  // 1. Initialize SDK
+  const provider = new ethers.BrowserProvider(window.ethereum);
+  const sdk = new ProtocolSDK({
+    apiBaseURL: "https://api.yourprotocol.com",
+    provider: await provider.provider,
+    contractAddress: "0x...",
+    abi: ContractABI,
+  });
+
+  // 2. Get user address
+  const signer = await provider.getSigner();
+  const userAddress = await signer.getAddress();
+
+  // 3. Fetch market data
+  const markets = await sdk.api.getAllMarkets();
+  console.log("Available markets:", markets);
+
+  // 4. Check token balance
+  const tokenAddress = "0xTokenAddress";
+  const balance = await sdk.tx.getTokenBalance(tokenAddress, userAddress);
+  console.log("Balance:", sdk.utils.formatAmount(balance, 18));
+
+  // 5. Check if approval is needed
+  const amount = sdk.utils.parseAmount("1.0", 18);
+  const needsApproval = await sdk.tx.needsApproval(
+    tokenAddress,
+    userAddress,
+    amount
+  );
+
+  // 6. If needed, approve
+  if (needsApproval) {
+    const approvalTx = await sdk.tx.prepareApprovalTransaction(tokenAddress);
+    const approveTxResponse = await signer.sendTransaction(approvalTx);
+    await approveTxResponse.wait();
+    console.log("Approval confirmed");
+  }
+
+  // 7. Prepare swap transaction
+  const swapTx = await sdk.tx.prepareSwapTransaction({
+    tokenIn: tokenAddress,
+    tokenOut: "0xTokenOutAddress",
+    amount: amount,
+    minAmountOut: sdk.utils.parseAmount("0.95", 18),
+    deadline: sdk.utils.getDeadline(20),
+  });
+
+  // 8. Sign and send
+  const txResponse = await signer.sendTransaction(swapTx);
+  console.log("Transaction sent:", txResponse.hash);
+
+  // 9. Wait for confirmation
+  const receipt = await sdk.waitForTransaction(txResponse.hash);
+
+  if (sdk.utils.isTransactionSuccessful(receipt)) {
+    console.log("✅ Swap successful!");
+
+    // 10. Fetch updated balance
+    const newBalance = await sdk.tx.getTokenBalance(tokenAddress, userAddress);
+    console.log("New balance:", sdk.utils.formatAmount(newBalance, 18));
+  } else {
+    console.error("❌ Transaction failed");
+  }
+}
+```
+
+## Error Handling
+
+The SDK uses custom error types for better error handling:
+
+```typescript
+import { SDKError, ErrorType } from "@yourorg/protocol-sdk";
+
+try {
+  await sdk.api.getMarketData("invalid-id");
+} catch (error) {
+  if (error instanceof SDKError) {
+    console.log("Error type:", error.type); // API_ERROR, TRANSACTION_ERROR, etc.
+    console.log("Message:", error.message);
+    console.log("Details:", error.details);
+  }
+}
+```
+
+Error types:
+
+- `API_ERROR` - API request failed
+- `TRANSACTION_ERROR` - Transaction preparation or execution failed
+- `VALIDATION_ERROR` - Invalid input parameters
+- `NETWORK_ERROR` - Network connectivity issues
+
+## TypeScript Support
+
+The SDK is fully typed. Import types as needed:
+
+```typescript
+import type {
+  SDKConfig,
+  SwapParams,
+  DepositParams,
+  MarketData,
+  UserBalance,
+  Transaction,
+} from "@yourorg/protocol-sdk";
+```
+
+## Constants
+
+The SDK exports useful constants:
+
+```typescript
+import { NETWORKS, GAS_LIMITS, MAX_UINT256 } from "@yourorg/protocol-sdk";
+
+console.log(NETWORKS.MAINNET); // { chainId: 1, name: 'Ethereum Mainnet', ... }
+console.log(GAS_LIMITS.SWAP); // 200000
+console.log(MAX_UINT256); // "0xfff..."
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+```
+
+## Project Structure
+
+```
+my-protocol-sdk/
+├── src/
+│   ├── api/
+│   │   └── APIClient.ts
+│   ├── transactions/
+│   │   └── TransactionBuilder.ts
+│   ├── utils/
+│   │   ├── helpers.ts
+│   │   └── constants.ts
+│   ├── types/
+│   │   └── index.ts
+│   ├── abi/
+│   │   └── ExampleABI.ts
+│   ├── ProtocolSDK.ts
+│   └── index.ts
+├── examples/
+│   └── usage.ts
+├── dist/            # Built files
+├── package.json
+├── tsconfig.json
+├── rollup.config.js
+└── README.md
+```
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: [https://docs.yourprotocol.com](https://docs.yourprotocol.com)
+- Issues: [GitHub Issues](https://github.com/yourorg/protocol-sdk/issues)
+- Discord: [Join our community](https://discord.gg/yourprotocol)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+# raingames-sdk

package/dist/ProtocolSDK.d.ts

@@ -0,0 +1,82 @@
+import { Provider } from 'ethers';
+import { APIClient } from './api/APIClient';
+import { TransactionBuilder } from './transactions/TransactionBuilder';
+import { Utils } from './utils/helpers';
+import { SDKConfig } from './types';
+/**
+ * Main SDK class that combines all functionality
+ *
+ * @example
+ * ```typescript
+ * import { ProtocolSDK } from '@yourorg/protocol-sdk';
+ * import { ethers } from 'ethers';
+ *
+ * const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');
+ *
+ * const sdk = new ProtocolSDK({
+ *   apiBaseURL: 'https://api.yourprotocol.com',
+ *   provider: provider,
+ *   contractAddress: '0x...',
+ *   abi: YourContractABI,
+ *   apiKey: 'your-api-key', // optional
+ * });
+ *
+ * // Use the SDK
+ * const markets = await sdk.api.getAllMarkets();
+ * const tx = await sdk.tx.prepareSwapTransaction({ ... });
+ * ```
+ */
+export declare class ProtocolSDK {
+    /** API client for fetching data */
+    api: APIClient;
+    /** Transaction builder for creating blockchain transactions */
+    tx: TransactionBuilder;
+    /** Utility functions */
+    utils: typeof Utils;
+    /** Provider instance */
+    provider: Provider;
+    /** Main contract address */
+    contractAddress: string;
+    /** Chain ID */
+    chainId?: number;
+    /**
+     * Initialize the SDK
+     * @param config - SDK configuration
+     */
+    constructor(config: SDKConfig);
+    /**
+     * Validate SDK configuration
+     */
+    private validateConfig;
+    /**
+     * Get network information
+     */
+    getNetworkInfo(): Promise<{
+        name: string;
+        chainId: number;
+    }>;
+    /**
+     * Get current block number
+     */
+    getBlockNumber(): Promise<number>;
+    /**
+     * Check if provider is connected
+     */
+    isConnected(): Promise<boolean>;
+    /**
+     * Get transaction receipt
+     * @param txHash - Transaction hash
+     */
+    getTransactionReceipt(txHash: string): Promise<import("ethers").TransactionReceipt | null>;
+    /**
+     * Wait for transaction confirmation
+     * @param txHash - Transaction hash
+     * @param confirmations - Number of confirmations to wait for
+     */
+    waitForTransaction(txHash: string, confirmations?: number): Promise<import("ethers").TransactionReceipt | null>;
+    /**
+     * Get SDK version
+     */
+    static getVersion(): string;
+}
+//# sourceMappingURL=ProtocolSDK.d.ts.map

package/dist/ProtocolSDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProtocolSDK.d.ts","sourceRoot":"","sources":["../src/ProtocolSDK.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAuB,MAAM,SAAS,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,WAAW;IACtB,mCAAmC;IAC5B,GAAG,EAAE,SAAS,CAAC;IAEtB,+DAA+D;IACxD,EAAE,EAAE,kBAAkB,CAAC;IAE9B,wBAAwB;IACjB,KAAK,EAAE,OAAO,KAAK,CAAC;IAE3B,wBAAwB;IACjB,QAAQ,EAAE,QAAQ,CAAC;IAE1B,4BAA4B;IACrB,eAAe,EAAE,MAAM,CAAC;IAE/B,eAAe;IACR,OAAO,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;gBACS,MAAM,EAAE,SAAS;IAkB7B;;OAEG;IACH,OAAO,CAAC,cAAc;IAsCtB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAC9B,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAeF;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAWvC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IASrC;;;OAGG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM;IAY1C;;;;OAIG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,GAAE,MAAU;IAIlE;;OAEG;IACH,MAAM,CAAC,UAAU,IAAI,MAAM;CAG5B"}

package/dist/ProtocolSDK.js

@@ -0,0 +1,129 @@
+import { APIClient } from './api/APIClient';
+import { TransactionBuilder } from './transactions/TransactionBuilder';
+import { Utils } from './utils/helpers';
+import { SDKError, ErrorType } from './types';
+/**
+ * Main SDK class that combines all functionality
+ *
+ * @example
+ * ```typescript
+ * import { ProtocolSDK } from '@yourorg/protocol-sdk';
+ * import { ethers } from 'ethers';
+ *
+ * const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');
+ *
+ * const sdk = new ProtocolSDK({
+ *   apiBaseURL: 'https://api.yourprotocol.com',
+ *   provider: provider,
+ *   contractAddress: '0x...',
+ *   abi: YourContractABI,
+ *   apiKey: 'your-api-key', // optional
+ * });
+ *
+ * // Use the SDK
+ * const markets = await sdk.api.getAllMarkets();
+ * const tx = await sdk.tx.prepareSwapTransaction({ ... });
+ * ```
+ */
+export class ProtocolSDK {
+    /**
+     * Initialize the SDK
+     * @param config - SDK configuration
+     */
+    constructor(config) {
+        // Validate configuration
+        this.validateConfig(config);
+        // Initialize components
+        this.provider = config.provider;
+        this.contractAddress = config.contractAddress;
+        this.chainId = config.chainId;
+        this.api = new APIClient(config.apiBaseURL, config.apiKey);
+        this.tx = new TransactionBuilder(config.provider, config.contractAddress, config.abi);
+        this.utils = Utils;
+    }
+    /**
+     * Validate SDK configuration
+     */
+    validateConfig(config) {
+        if (!config.apiBaseURL) {
+            throw new SDKError('apiBaseURL is required', ErrorType.VALIDATION_ERROR);
+        }
+        if (!config.provider) {
+            throw new SDKError('provider is required', ErrorType.VALIDATION_ERROR);
+        }
+        if (!config.contractAddress) {
+            throw new SDKError('contractAddress is required', ErrorType.VALIDATION_ERROR);
+        }
+        if (!config.abi || !Array.isArray(config.abi)) {
+            throw new SDKError('abi must be an array', ErrorType.VALIDATION_ERROR);
+        }
+        // Validate contract address format
+        if (!Utils.isValidAddress(config.contractAddress)) {
+            throw new SDKError('Invalid contract address', ErrorType.VALIDATION_ERROR);
+        }
+    }
+    /**
+     * Get network information
+     */
+    async getNetworkInfo() {
+        try {
+            const network = await this.provider.getNetwork();
+            return {
+                name: Utils.getNetworkName(Number(network.chainId)),
+                chainId: Number(network.chainId),
+            };
+        }
+        catch (error) {
+            throw new SDKError(`Failed to get network info: ${error}`, ErrorType.NETWORK_ERROR);
+        }
+    }
+    /**
+     * Get current block number
+     */
+    async getBlockNumber() {
+        try {
+            return await this.provider.getBlockNumber();
+        }
+        catch (error) {
+            throw new SDKError(`Failed to get block number: ${error}`, ErrorType.NETWORK_ERROR);
+        }
+    }
+    /**
+     * Check if provider is connected
+     */
+    async isConnected() {
+        try {
+            await this.provider.getBlockNumber();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get transaction receipt
+     * @param txHash - Transaction hash
+     */
+    async getTransactionReceipt(txHash) {
+        try {
+            return await this.provider.getTransactionReceipt(txHash);
+        }
+        catch (error) {
+            throw new SDKError(`Failed to get transaction receipt: ${error}`, ErrorType.NETWORK_ERROR, { txHash });
+        }
+    }
+    /**
+     * Wait for transaction confirmation
+     * @param txHash - Transaction hash
+     * @param confirmations - Number of confirmations to wait for
+     */
+    async waitForTransaction(txHash, confirmations = 1) {
+        return Utils.waitForTransaction(txHash, this.provider, confirmations);
+    }
+    /**
+     * Get SDK version
+     */
+    static getVersion() {
+        return '1.0.0'; // This should match package.json version
+    }
+}