Merge pull request #1 from TradeOnDESK/feat/LD-1806-desk-plugin

[main][feat] LD-1806: DESK Plugin

Author: wangtangjim

plugins/deskPlugin/.env.example

@@ -0,0 +1,5 @@
+# DESK Exchange Plugin Configuration
+
+DESK_EXCHANGE_PRIVATE_KEY=
+
+DESK_EXCHANGE_NETWORK=

plugins/deskPlugin/.gitignore

@@ -0,0 +1,15 @@
+#dependencies
+node_modules/
+
+#env
+.env
+
+#build
+dist/
+
+#IDE
+.vscode/
+.idea/
+
+#test
+coverage/

plugins/deskPlugin/README.md

@@ -0,0 +1,95 @@
+# Desk Plugin
+
+A plugin for interacting with a trading desk/exchange, providing functionality for perpetual trading, account management, and order handling.
+
+## Features
+
+- Account summary retrieval
+- Perpetual trading execution
+- Order management (placing and canceling orders)
+
+## Installation
+
+```bash
+pnpm install @virtuals-protocol/desk-plugin
+```
+
+## Configuration
+
+The plugin requires the following environment variables:
+
+- `DESK_EXCHANGE_PRIVATE_KEY`: Your private key for authentication
+- `DESK_EXCHANGE_NETWORK`: Network to connect to (`mainnet` or `testnet`)
+
+## Usage
+
+### Initializing the Plugin
+
+```typescript
+import DeskPlugin from '@virtuals-protocol/desk-plugin'
+
+const deskPlugin = new DeskPlugin({
+  credentials: {
+    network: 'testnet', // or 'mainnet'
+    privateKey: 'YOUR_PRIVATE_KEY'
+  }
+})
+```
+
+### Available Functions
+
+#### Get Account Summary
+
+Retrieves a comprehensive summary of your account, including positions, orders, and collaterals.
+
+```typescript
+const summary = await deskPlugin.getAccountSummary.executable({}, logger)
+```
+
+#### Place Perpetual Trade
+
+Execute a perpetual trade with specified parameters.
+
+```typescript
+const tradeRequest = {
+  amount: '1',        // Desired amount
+  price: '10000',     // Market price
+  side: 'Long',       // 'Long' or 'Short'
+  symbol: 'BTC'       // Trading pair symbol (without 'USD')
+}
+
+const trade = await deskPlugin.perpTrade.executable(tradeRequest, logger)
+```
+
+#### Cancel Orders
+
+Cancel all open orders for the account.
+
+```typescript
+const cancelResult = await deskPlugin.cancelOrders.executable({}, logger)
+```
+
+## Response Format
+
+All functions return an `ExecutableGameFunctionResponse` with the following structure:
+
+```typescript
+{
+  status: ExecutableGameFunctionStatus;
+  feedback: string;
+}
+```
+
+## Testing
+
+To run the tests:
+
+```bash
+pnpm test
+```
+
+Make sure to set up the required environment variables before running tests.
+
+## License
+
+[License Type] - See LICENSE file for details

plugins/deskPlugin/__test__/deskPlugin.test.ts

@@ -0,0 +1,84 @@
+import { beforeAll, describe, expect, it, jest } from '@jest/globals'
+import { ExecutableGameFunctionResponse, ExecutableGameFunctionStatus, GameWorker } from '@virtuals-protocol/game'
+
+import { GAME_WORKER_FUNCTIONS, SUCCESS_MESSAGES } from '../src/constants'
+import DeskPlugin from '../src/deskPlugin'
+import { logger } from './log'
+
+describe('DeskPlugin', () => {
+  const DESK_EXCHANGE_PRIVATE_KEY: string = process.env.DESK_EXCHANGE_PRIVATE_KEY || ''
+  const DESK_EXCHANGE_NETWORK: 'mainnet' | 'testnet' = process.env.DESK_EXCHANGE_NETWORK as 'mainnet' | 'testnet'
+  let deskPlugin: DeskPlugin
+  let _logger: (msg: string) => void
+
+  // setup
+  beforeAll(async () => {
+    // clear caches
+    jest.resetModules()
+    // init desk plugin
+    deskPlugin = new DeskPlugin({
+      credentials: {
+        network: DESK_EXCHANGE_NETWORK,
+        privateKey: DESK_EXCHANGE_PRIVATE_KEY,
+      },
+    })
+    // apply logger
+    _logger = logger
+  })
+
+  // get worker
+  describe('getWorker', () => {
+    it('should return a GameWorker with default functions', () => {
+      const worker: GameWorker = deskPlugin.getWorker()
+      expect(worker).toBeDefined()
+      expect(worker.functions).toHaveLength(GAME_WORKER_FUNCTIONS.length)
+      expect(worker.functions.map((f: GameWorker['functions'][0]) => f.name)).toEqual(GAME_WORKER_FUNCTIONS)
+    })
+  })
+
+  // get account summary
+  describe('getAccountSummary', () => {
+    // success case
+    it('should return account summary', async () => {
+      const result: ExecutableGameFunctionResponse = await deskPlugin.getAccountSummary.executable({}, _logger)
+      expect(result).toBeDefined()
+      expect(result.status).toBe(ExecutableGameFunctionStatus.Done)
+      expect(result.feedback).toContain(SUCCESS_MESSAGES.ACCOUNT_SUMMARY)
+      expect(result.feedback).toContain(SUCCESS_MESSAGES.YOUR_POSITIONS)
+      expect(result.feedback).toContain(SUCCESS_MESSAGES.YOUR_ORDERS)
+      expect(result.feedback).toContain(SUCCESS_MESSAGES.YOUR_COLLATERALS)
+    })
+  })
+
+  // perp trade
+  describe('perpTrade', () => {
+    // success case (either found or not found)
+    it('should successfully place order', async () => {
+      const request: Partial<{ amount: string; price: string; side: string; symbol: string }> = {
+        // NOTE: desire amount
+        amount: 'YOUR_DESIRE_AMOUNT',
+        // NOTE: check up price on market info
+        price: 'YOUR_DESIRE_PRICE',
+        // NOTE: side, ex:`Long` or `Short`
+        side: 'YOUR_DESIRE_SIDE',
+        // NOTE: symbol without `USD`, ex: `BTC`
+        symbol: 'YOUR_DESIRE_SYMBOL',
+      }
+      const result: ExecutableGameFunctionResponse = await deskPlugin.perpTrade.executable(request, _logger)
+      expect(result).toBeDefined()
+      expect(result.status).toBe(ExecutableGameFunctionStatus.Done)
+      expect(result.feedback).toContain(SUCCESS_MESSAGES.PERP_TRADE)
+    })
+  })
+
+  // cancel orders
+  describe('cancelOrders', () => {
+    // success case (either found or not found any open orders)
+    it('should successfully cancel open orders', async () => {
+      const result: ExecutableGameFunctionResponse = await deskPlugin.cancelOrders.executable({}, _logger)
+      expect(result).toBeDefined()
+      expect(result.status).toBe(ExecutableGameFunctionStatus.Done)
+      expect(result.feedback).toContain(SUCCESS_MESSAGES.ORDER_CANCELLED)
+    })
+  })
+})

plugins/deskPlugin/__test__/log.ts

@@ -0,0 +1,5 @@
+import { log } from 'console'
+
+export const logger = (msg: string): void => {
+  log(msg)
+}

plugins/deskPlugin/eslint.config.mjs

@@ -0,0 +1,57 @@
+import js from '@eslint/js'
+import configPrettier from 'eslint-config-prettier'
+import importPlugin from 'eslint-plugin-import'
+import prettierPlugin from 'eslint-plugin-prettier'
+import simpleImportSortPlugin from 'eslint-plugin-simple-import-sort'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  { ignores: ['dist', 'node_modules', 'coverage'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.ts'],
+    languageOptions: {
+      ecmaVersion: 2020,
+    },
+    plugins: {
+      import: importPlugin,
+      configPrettier: configPrettier,
+      prettier: prettierPlugin,
+      'simple-import-sort': simpleImportSortPlugin,
+    },
+    rules: {
+      'no-console': 1,
+      'prettier/prettier': [
+        'error',
+        {
+          printWidth: 120,
+          semi: false,
+          singleQuote: true,
+          tabWidth: 2,
+          trailingComma: 'all',
+        },
+      ],
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-inferrable-types': 'off',
+      '@typescript-eslint/array-type': ['error', { default: 'generic' }],
+      '@typescript-eslint/typedef': [
+        1,
+        {
+          arrayDestructuring: true,
+          arrowParameter: true,
+          memberVariableDeclaration: true,
+          objectDestructuring: true,
+          parameter: true,
+          propertyDeclaration: true,
+          variableDeclaration: true,
+          variableDeclarationIgnoreFunction: true,
+        },
+      ],
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+      'import/first': 'error',
+      'import/newline-after-import': 'error',
+      'import/no-duplicates': 'error',
+    },
+  },
+)

plugins/deskPlugin/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    setupFiles: ['<rootDir>/jest.setup.js'],
+}

plugins/deskPlugin/jest.setup.js

@@ -0,0 +1 @@
+require('dotenv').config({ path: '.env' });

plugins/deskPlugin/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@game-node/desk-exchange-plugin",
+    "version": "1.0.0",
+    "description": "DESK Exchange Plugin for ...",
+    "main": "dist/index.js",
+    "dependencies": {
+        "@virtuals-protocol/game": "^0.1.7"
+    },
+    "devDependencies": {
+        "@desk-exchange/typescript-sdk": "1.0.3",
+        "@eslint/js": "9.15.0",
+        "@jest/globals": "29.7.0",
+        "@types/jest": "29.5.14",
+        "@types/node": "20.0.0",
+        "eslint": "9.15.0",
+        "eslint-config-prettier": "9.1.0",
+        "eslint-plugin-import": "2.31.0",
+        "eslint-plugin-prettier": "5.2.1",
+        "eslint-plugin-simple-import-sort": "12.1.1",
+        "jest": "29.7.0",
+        "ts-jest": "29.2.5",
+        "tsup": "8.3.5",
+        "typescript-eslint": "8.16.0"
+    },
+    "scripts": {
+        "build": "tsup --format esm --dts",
+        "dev": "tsup --watch --format esm --dts",
+        "lint": "eslint . --config eslint.config.mjs",
+        "test": "jest --coverage"
+    }
+}