@runesx/api-client 0.0.1

package/README.md

@@ -0,0 +1,47 @@
+# RunesX API Client
+
+A Node.js client for interacting with the RunesX platform API and WebSocket, enabling developers to build bots or scripts for real-time trading, liquidity management, and data monitoring.
+
+## Features
+- **WebSocket Integration**: Connect to the RunesX Socket.IO server to listen for real-time events like `pools_updated`, `coins_updated`, `wallets_updated`, `user_shares_updated`, and chat messages (`yard_message`).
+- **API Access**: Perform HTTP requests for wallet data, swaps, and liquidity operations.
+- **Store Management**: Manage coin, pool, wallet, and user share data with built-in buffering for WebSocket updates.
+- **Swap Estimation**: Estimate swap outcomes using DFS or BFS pathfinding algorithms.
+- **Liquidity Management**: Estimate, deposit, and withdraw liquidity for trading pairs.
+- **Monitoring**: Periodically monitor pool, wallet, and user share states.
+
+## Installation
+```bash
+npm install @runesx/api-client
+```
+
+## Usage
+
+1. Initialize the Client
+Create and initialize the client with your API key and endpoint URLs. This connects to the WebSocket and fetches initial data for pools, coins, wallets, and user shares.
+
+```javascript
+import { createRunesXClient } from '@runesx/api-client';
+
+const client = createRunesXClient({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://www.runesx.xyz/api',
+  socketUrl: 'https://www.runesx.xyz/api',
+});
+
+async function main() {
+  try {
+    const { pools, coins, wallets, userShares } = await client.initialize();
+    console.log('Initialized with:', {
+      poolCount: pools.length,
+      coinCount: coins.length,
+      walletCount: wallets.length,
+      userShareCount: userShares.length,
+    });
+  } catch (error) {
+    console.error('Initialization failed:', error.message);
+  }
+}
+
+main();
+```

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@runesx/api-client",
+  "version": "0.0.1",
+  "description": "A Node.js client for interacting with the RunesX platform API and WebSocket",
+  "main": "src/index.mjs",
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.mjs",
+    "dev": "nodemon src/index.mjs",
+    "lint": "eslint src",
+    "build": "echo 'No build step required'",
+    "prepublishOnly": "npm run lint",
+    "test": "jest"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "bignumber.js": "^9.1.2",
+    "socket.io-client": "^4.7.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.11.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^11.0.3",
+    "dotenv": "^16.4.5",
+    "eslint": "^9.11.1",
+    "eslint-plugin-import": "^2.30.0",
+    "eslint-plugin-n": "^17.0.0",
+    "eslint-plugin-promise": "^7.1.0",
+    "globals": "^15.9.0",
+    "jest": "^30.0.4",
+    "nodemon": "^3.1.4",
+    "semantic-release": "^22.0.12"
+  },
+  "files": [
+    "src/*.mjs",
+    "src/store/*.mjs",
+    "src/utils/*.mjs",
+    "src/workers/*.mjs"
+  ],
+  "keywords": [
+    "runesx",
+    "api",
+    "websocket",
+    "cryptocurrency",
+    "defi"
+  ],
+  "author": "RunesX",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runebase/runesx-api-key-example.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,50 @@
+// src/api.mjs
+import axios from 'axios';
+
+export function createApi(config) {
+  const api = axios.create({
+    baseURL: config.apiUrl,
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+      'Content-Type': 'application/json',
+    },
+  });
+
+  async function getWallets() {
+    try {
+      const response = await api.get('/wallets');
+      return response.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to fetch wallets');
+    }
+  }
+
+  async function postSwap({ amountIn, path, minAmountOut }) {
+    try {
+      const response = await api.post('/swap', { amountIn, path, minAmountOut });
+      return response.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to execute swap');
+    }
+  }
+
+  async function depositLiquidity({ coinA, coinB, amountA, amountB }) {
+    try {
+      const response = await api.post('/liquidity/deposit', { coinA, coinB, amountA, amountB });
+      return response.data.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to deposit liquidity');
+    }
+  }
+
+  async function withdrawLiquidity({ coinA, coinB, shares }) {
+    try {
+      const response = await api.post('/liquidity/withdraw', { coinA, coinB, shares });
+      return response.data.data;
+    } catch (error) {
+      throw new Error(error.response?.data?.error || 'Failed to withdraw liquidity');
+    }
+  }
+
+  return { getWallets, postSwap, depositLiquidity, withdrawLiquidity };
+}

package/src/config.mjs

@@ -0,0 +1,8 @@
+// src/config.mjs
+export function createConfig(options = {}) {
+  return {
+    apiUrl: options.apiUrl || process.env.API_URL || 'http://localhost:3010',
+    socketUrl: options.socketUrl || process.env.SOCKET_URL || 'http://localhost:3010',
+    apiKey: options.apiKey || process.env.API_KEY || '',
+  };
+}

package/src/index.mjs

@@ -0,0 +1,80 @@
+// src/index.mjs
+import { setupSocket } from './socket.mjs';
+import { createApi } from './api.mjs';
+import { createConfig } from './config.mjs';
+import { getPools, getPool } from './store/poolStore.mjs';
+import { getCoins, getCoinByTicker } from './store/coinStore.mjs';
+import { getWallets as getWalletsStore, getWalletByTicker } from './store/walletStore.mjs';
+import { getUserShares, getUserShareByPoolId } from './store/userSharesStore.mjs';
+import { waitForStores } from './waitForStores.mjs';
+import { estimateLiquidityFrontend, checkRunesLiquidityFrontend, calculateShareAmounts } from './utils/liquidityUtils.mjs';
+import { estimateSwap } from './utils/swapUtils.mjs';
+
+export function createRunesXClient(options = {}) {
+  const config = createConfig(options);
+  let socket = null;
+  let initialized = false;
+  const api = createApi(config);
+
+  async function initialize() {
+    if (!config.apiKey) {
+      throw new Error('API_KEY is required');
+    }
+    socket = setupSocket(config).socket;
+    const { pools, coins, wallets, userShares } = await waitForStores(socket);
+    initialized = true;
+    return { pools, coins, wallets, userShares };
+  }
+
+  function ensureInitialized() {
+    if (!initialized) {
+      throw new Error('Client not initialized. Call initialize() first.');
+    }
+  }
+
+  return {
+    initialize,
+    getSocket: () => {
+      ensureInitialized();
+      return socket;
+    },
+    getPools,
+    getPool,
+    getCoins,
+    getCoinByTicker,
+    getWallets: getWalletsStore,
+    getWalletByTicker,
+    getUserShares,
+    getUserShareByPoolId,
+    postSwap: api.postSwap,
+    depositLiquidity: api.depositLiquidity,
+    withdrawLiquidity: api.withdrawLiquidity,
+    getWalletsApi: api.getWallets,
+    estimateSwap: (inputCoin, outputCoin, amountIn, maxHops = 6, algorithm = 'dfs') =>
+      estimateSwap(inputCoin, outputCoin, amountIn, getPools(), getCoins(), maxHops, algorithm),
+    estimateLiquidityFrontend,
+    checkRunesLiquidityFrontend: (coinA, coinB) =>
+      checkRunesLiquidityFrontend(coinA, coinB, getPools(), getCoins()),
+    calculateShareAmounts: () => calculateShareAmounts({ userShares: getUserShares(), pools: getPools() }),
+    monitorPool: (poolId, interval = 10000) => {
+      setInterval(() => {
+        const pool = getPool(poolId);
+        if (pool) {
+          console.log(`Monitoring pool ${poolId} (${pool.coinA.ticker}/${pool.coinB.ticker}):`, {
+            reserveA: pool.reserveA.toString(),
+            reserveB: pool.reserveB.toString(),
+            totalShares: pool.totalShares.toString(),
+            activeLiquidityProviders: pool.activeLiquidityProviders,
+          });
+        } else {
+          console.log(`Pool ${poolId} not found or not yet initialized`);
+        }
+      }, interval);
+    },
+    disconnect: () => {
+      if (socket) {
+        socket.disconnect();
+      }
+    },
+  };
+}

package/src/socket.mjs

@@ -0,0 +1,247 @@
+// src/socket.mjs
+import { io } from 'socket.io-client';
+
+import { setInitialPools, updatePool, resetPools } from './store/poolStore.mjs';
+import { setInitialCoins, updateCoin, resetCoins } from './store/coinStore.mjs';
+import { setInitialWallets, updateWallet, resetWallets } from './store/walletStore.mjs';
+import { setInitialUserShares, updateUserShare, resetUserShares } from './store/userSharesStore.mjs';
+
+export function setupSocket(config) {
+  const socket = io(config.socketUrl, {
+    auth: { authorization: `Bearer ${config.apiKey}` },
+    transports: ['websocket'],
+    reconnection: true,
+    reconnectionAttempts: Infinity,
+    reconnectionDelay: 1000,
+    reconnectionDelayMax: 5000,
+  });
+
+  const errorCount = { count: 0 }; // Track connection errors
+
+  socket.on('connect', () => {
+    console.log('Connected to Socket.IO server');
+    socket.emit('join_public');
+    console.log('Joined public room');
+    socket.emit('join_private');
+    console.log('Joined private room');
+    errorCount.count = 0;
+  });
+
+  socket.on('connect_error', (err) => {
+    console.log('Socket connect error:', err.message);
+    errorCount.count += 1;
+    if (errorCount.count >= 3) {
+      resetPools();
+      resetCoins();
+      resetWallets();
+      resetUserShares();
+    }
+  });
+
+  socket.on('disconnect', (reason) => {
+    console.log('Disconnected from Socket.IO server:', reason);
+    resetPools();
+    resetCoins();
+    resetWallets();
+    resetUserShares();
+  });
+
+  socket.on('reconnect_attempt', (attempt) => {
+    console.log(`Reconnect attempt #${attempt}`);
+  });
+
+  socket.on('reconnect', () => {
+    console.log('Reconnected to Socket.IO server');
+    socket.emit('join_public');
+    console.log('Rejoined public room');
+    socket.emit('join_private');
+    console.log('Rejoined private room');
+    resetPools();
+    resetCoins();
+    resetWallets();
+    resetUserShares();
+  });
+
+  socket.on('reconnect_error', (err) => {
+    console.log('Reconnect error:', err.message);
+    errorCount.count += 1;
+    if (errorCount.count >= 3) {
+      resetPools();
+      resetCoins();
+      resetWallets();
+      resetUserShares();
+    }
+  });
+
+  socket.on('error', (err) => {
+    console.log('Socket error:', err.message);
+  });
+
+  socket.on('pools_updated', ({ pools, isInitial }) => {
+    console.log('Received pools_updated:', { pools, isInitial });
+    if (isInitial) {
+      setInitialPools(pools);
+    } else {
+      pools.forEach(pool => updatePool(pool));
+    }
+  });
+
+  socket.on('coins_updated', ({ coins, isInitial }) => {
+    console.log('Received coins_updated:', { coins, isInitial });
+    if (isInitial) {
+      setInitialCoins(coins);
+    } else {
+      coins.forEach(coin => updateCoin(coin));
+    }
+  });
+
+  socket.on('wallets_updated', ({ wallets, isInitial }) => {
+    console.log('Received wallets_updated:', { wallets, isInitial });
+    if (isInitial) {
+      setInitialWallets(wallets);
+    } else {
+      wallets.forEach(wallet => updateWallet(wallet));
+    }
+  });
+
+  socket.on('user_shares_updated', ({ userShares, isInitial }) => {
+    console.log('Received user_shares_updated:', { userShares, isInitial });
+    if (isInitial) {
+      setInitialUserShares(userShares);
+    } else {
+      userShares.forEach(share => updateUserShare(share));
+    }
+  });
+
+  socket.on('volumeUpdate', ({ type, poolId, timestamp, volume }) => {
+    console.log('Volume update:', { type, poolId, timestamp, volume });
+  });
+
+  socket.on('operationUpdate', (operation) => {
+    console.log('Operation update:', operation);
+    // Assuming operation includes liquidity deposit/withdraw results
+    if (operation.type === 'liquidity_deposit' || operation.type === 'liquidity_withdraw') {
+      console.log(`Liquidity operation ${operation.type} completed:`, {
+        uid: operation.uid,
+        coinA: operation.coinA,
+        coinB: operation.coinB,
+        amountA: operation.amountA,
+        amountB: operation.amountB,
+        shares: operation.shares,
+        status: operation.status,
+      });
+    }
+  });
+  socket.on('status_updated', (data) => {
+    console.log('Status update:', data);
+  });
+
+  socket.on('deposit_address_generated', ({ requestId, chainId, address, memo }) => {
+    console.log('Deposit address generated:', { requestId, chainId, address, memo });
+  });
+
+  socket.on('deposit_processed', (data) => {
+    const { amount, coin, chain, confirmations, status, credited } = data;
+    const message =
+      status === 'confirmed' && credited
+        ? `Deposit of ${amount} ${coin.ticker} confirmed!`
+        : `Deposit of ${amount} ${coin.ticker} (confirming) [${confirmations}/${chain.requiredConfirmations}]`;
+    console.log('Deposit processed:', { message, data });
+  });
+
+  socket.on('withdrawal_processed', (data) => {
+    const { amount, coin, chain, confirmations, status, credited, createdAt } = data;
+    let message;
+    if (!createdAt) {
+      message = `Withdrawal of ${amount} ${coin.ticker} is stalled due to network congestion.`;
+    } else if (status === 'confirmed' && credited) {
+      message = `Withdrawal of ${amount} ${coin.ticker} confirmed!`;
+    } else {
+      message = `Withdrawal of ${amount} ${coin.ticker} (confirming) [${confirmations}/${chain.requiredConfirmations}]`;
+    }
+    console.log('Withdrawal processed:', { message, data });
+  });
+
+  socket.on('withdrawal_initiated', (data) => {
+    console.log('Withdrawal initiated:', data);
+  });
+
+  socket.on('withdrawal_pin_generated', ({ pinImage, ticker, amount, pendingWithdrawalId, expiresAt, dp, fee, memoRequired }) => {
+    console.log('Withdrawal pin generated:', {
+      ticker,
+      amount,
+      pinImage,
+      pendingWithdrawalId,
+      expiresAt,
+      dp,
+      fee,
+      memoRequired,
+    });
+  });
+
+  socket.on('withdrawal_queued', ({ pendingWithdrawalId, ticker }) => {
+    console.log('Withdrawal queued:', { pendingWithdrawalId, ticker });
+  });
+
+  socket.on('withdrawal_canceled', ({ ticker, amount }) => {
+    console.log('Withdrawal canceled:', { ticker, amount });
+  });
+
+  // socket.on('recent_yard_messages', (initialMessages) => {
+  //   console.log('Recent yard messages:', initialMessages);
+  // });
+
+  socket.on('yard_message', (message) => {
+    console.log('New chat message:', {
+      username: message.username,
+      text: message.text,
+      role: message.role,
+      timestamp: new Date(message.timestamp).toLocaleString(),
+    });
+  });
+
+  socket.on('message_deleted', ({ messageId }) => {
+    console.log('Message deleted:', { messageId });
+  });
+
+  socket.on('banned', ({ reason, bannedUntil }) => {
+    console.log('Banned from yard:', {
+      reason,
+      bannedUntil: new Date(bannedUntil).toLocaleString(),
+    });
+  });
+
+  socket.on('withdrawal_updated', ({ pendingWithdrawalId, expiresAt, stage }) => {
+    console.log('Withdrawal updated:', { pendingWithdrawalId, expiresAt, stage });
+  });
+
+  socket.on('withdrawal_expired', ({ pendingWithdrawalId, ticker, amount }) => {
+    console.log('Withdrawal expired:', { pendingWithdrawalId, ticker, amount });
+  });
+
+  socket.on('pong', () => {
+    console.log('Received pong from server');
+  });
+
+  const heartbeatInterval = setInterval(() => {
+    if (socket.connected) {
+      socket.emit('ping');
+    }
+  }, 30000);
+
+  socket.on('close', () => {
+    clearInterval(heartbeatInterval);
+    resetPools();
+    resetCoins();
+    resetWallets();
+    resetUserShares();
+  });
+
+  socket.on('connect', () => {
+    socket.emit('yard_message', {
+      text: 'Hello from RunesX API Key Example Bot!!',
+    });
+  });
+
+  return { socket };
+}

package/src/store/coinStore.mjs

@@ -0,0 +1,113 @@
+import { BigNumber } from 'bignumber.js';
+
+const coinStore = {
+  coins: new Map(), // Store coin data by coin ID
+  isInitialReceived: false, // Track if initial coin data is received
+  pendingUpdates: [], // Buffer for updates before initial data
+};
+
+// Initialize coins with initial data
+const setInitialCoins = (coins) => {
+  coinStore.coins.clear();
+  coins.forEach(coin => {
+    coinStore.coins.set(coin.id, {
+      id: coin.id,
+      ticker: coin.ticker,
+      dp: coin.dp,
+      projectName: coin.projectName,
+      status: coin.status,
+      runesComplianceRequirement: coin.runesComplianceRequirement || false,
+      updatedAt: coin.updatedAt,
+      CoinChains: coin.CoinChains || [],
+    });
+  });
+  coinStore.isInitialReceived = true;
+  console.log(`Initialized with ${coins.length} coins`);
+
+  // Process buffered updates
+  if (coinStore.pendingUpdates.length > 0) {
+    console.log(`Processing ${coinStore.pendingUpdates.length} buffered coin updates`);
+    coinStore.pendingUpdates.forEach(({ coins }) => {
+      coins.forEach(coin => updateCoin(coin));
+    });
+    coinStore.pendingUpdates = [];
+  }
+};
+
+// Update a single coin
+const updateCoin = (coin) => {
+  if (!coinStore.isInitialReceived) {
+    console.log('Buffering coin update, initial data not yet received:', coin);
+    coinStore.pendingUpdates.push({ coins: [coin] });
+    return;
+  }
+
+  const existingCoin = coinStore.coins.get(coin.id);
+  const incomingUpdatedAt = new Date(coin.updatedAt).getTime();
+
+  if (existingCoin) {
+    const existingUpdatedAt = new Date(existingCoin.updatedAt).getTime();
+    if (incomingUpdatedAt <= existingUpdatedAt) {
+      console.log(`Skipping stale update for coin ${coin.id}`);
+      return;
+    }
+
+    console.log(`Updating coin ${coin.id} (${coin.ticker}):`, {
+      ticker: coin.ticker,
+      dp: coin.dp,
+      projectName: coin.projectName,
+      status: coin.status,
+      runesComplianceRequirement: coin.runesComplianceRequirement,
+      CoinChains: coin.CoinChains,
+    });
+
+    Object.assign(existingCoin, {
+      ticker: coin.ticker,
+      dp: coin.dp,
+      projectName: coin.projectName,
+      status: coin.status,
+      runesComplianceRequirement: coin.runesComplianceRequirement || false,
+      updatedAt: coin.updatedAt,
+      CoinChains: coin.CoinChains || existingCoin.CoinChains,
+    });
+  } else if (coin.ticker && coin.status && new BigNumber(coin.dp || 0).gte(0)) {
+    console.log(`Adding new coin ${coin.id}:`, coin);
+    coinStore.coins.set(coin.id, {
+      id: coin.id,
+      ticker: coin.ticker,
+      dp: coin.dp,
+      projectName: coin.projectName,
+      status: coin.status,
+      runesComplianceRequirement: coin.runesComplianceRequirement || false,
+      updatedAt: coin.updatedAt,
+      CoinChains: coin.CoinChains || [],
+    });
+  } else {
+    console.warn(`Ignoring update for unknown coin ${coin.id} with incomplete data`);
+  }
+};
+
+// Get all coins
+const getCoins = () => {
+  return Array.from(coinStore.coins.values());
+};
+
+// Get a specific coin by ID
+const getCoin = (coinId) => {
+  return coinStore.coins.get(coinId);
+};
+
+// Get a specific coin by ticker
+const getCoinByTicker = (ticker) => {
+  return Array.from(coinStore.coins.values()).find(coin => coin.ticker === ticker);
+};
+
+// Reset store on disconnect or error
+const resetCoins = () => {
+  coinStore.coins.clear();
+  coinStore.isInitialReceived = false;
+  coinStore.pendingUpdates = [];
+  console.log('Reset coin state due to disconnect or error');
+};
+
+export { coinStore, setInitialCoins, updateCoin, getCoins, getCoin, getCoinByTicker, resetCoins };