lynx-client 0.0.1-beta.12 → 0.0.1-beta.14

package/README.md

@@ -1,4 +1,371 @@
-# Lynx Client
+# Lynx Client SDK
 
-This project introduces a client to interact with Lynx.
-It has script examples and api calls to the app, and common logic used by other Lynx repositories.
+A TypeScript SDK for interacting with the Lynx trading protocol across multiple EVM-compatible blockchains.
+
+## Features
+
+- 🔒 Type-safe interfaces for all Lynx smart contracts
+- 🌐 Multi-chain support (16+ EVM chains)
+- 📊 Built-in utilities for price, leverage, and fraction conversions
+- 🏗️ Support for both CommonJS and ESM module systems
+- 🔍 Read-only lens contracts for efficient data aggregation
+- 💼 Complete trading lifecycle management
+
+## Installation
+
+```bash
+npm install lynx-client
+```
+
+```bash
+yarn add lynx-client
+```
+
+## Quick Start
+
+```typescript
+import { 
+  connectToLatestRegistry,
+  LynxSystemAddresses,
+  createTradersPortalService,
+  buildPositionRequestIdentifier,
+  buildPositionRequestParams
+} from 'lynx-client';
+import { ethers } from 'ethers';
+
+// Initialize provider
+const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');
+const signer = await provider.getSigner();
+
+// Get chain-specific addresses
+const addresses = LynxSystemAddresses.arbitrum; // or .sonic, .base, etc.
+
+// Connect to contracts
+const registry = connectToLatestRegistry(provider, addresses.registryProxyAddress);
+
+// Create a service for trader operations
+const tradersPortal = createTradersPortalService(signer, addresses.tradersPortalAddress);
+```
+
+## Core Concepts
+
+### Supported Chains
+
+#### Engine Chains
+The Lynx protocol is deployed on the following chains:
+
+- **Sonic** (146)
+- **Boba** (288)
+- **Flare** (14)
+- **Fantom** (250)
+
+#### Source Chains
+Assets can be bridged from these additional chains:
+
+- Ethereum Mainnet (1)
+- Optimism (10)
+- BSC (56)
+- Polygon (137)
+- Fuse (122)
+- Goat (2345)
+- Mantle (5000)
+- Base (8453)
+- Mode (34443)
+- Arbitrum (42161)
+- Celo (42220)
+- Linea (59144)
+- Zircuit (48900)
+
+```typescript
+import { LynxSystemAddresses, TSupportedChainIds } from 'lynx-client';
+
+// Get addresses for a specific chain
+const sonicAddresses = LynxSystemAddresses.sonic;
+const arbitrumAddresses = LynxSystemAddresses.arbitrum;
+```
+
+### Contract Services
+
+The SDK provides service wrappers for all Lynx contracts:
+
+#### Trading Operations
+
+```typescript
+import { 
+  createTradersPortalService,
+  buildPositionRequestIdentifier,
+  buildPositionRequestParams,
+  TOpenOrderType 
+} from 'lynx-client';
+
+const tradersPortal = createTradersPortalService(signer, tradersPortalAddress);
+
+// Build position parameters using human-readable values
+const identifier = buildPositionRequestIdentifier({
+  trader: await signer.getAddress(),
+  pairId: 1, // BTC/USD
+  settlementAsset: "0x...", // USDC address
+  positionIndex: 0
+});
+
+const params = buildPositionRequestParams({
+  isLong: true,
+  collateral: 100, // 100 USDC
+  leverage: 25, // 25x leverage
+  minPrice: 50000, // $50,000
+  maxPrice: 50100, // $50,100
+  takeProfit: 55000, // $55,000
+  stopLoss: 48000 // $48,000
+});
+
+// Open a position
+await tradersPortal.traderRequests.openNewPosition(
+  identifier,
+  params,
+  TOpenOrderType.MARKET,
+  "0x", // referrer domain
+  "0x", // referrer code
+  true, // run cap tests
+  ethers.parseEther("0.01") // native fee
+);
+```
+
+#### Lens Services (Read-Only Data)
+
+```typescript
+import { createLexLensService, createTradingFloorLensService } from 'lynx-client';
+
+// LEX Pool data (accepts both provider and signer)
+const lexLens = createLexLensService(signerOrProvider, lexLensAddress);
+const poolState = await lexLens.getLexPoolState(lexPoolAddress);
+const pairConfigs = await lexLens.getAllPairConfigurationsInLex(lexPoolAddress);
+
+// Trading floor data (accepts both provider and signer)
+const tradingFloorLens = createTradingFloorLensService(signerOrProvider, tradingFloorLensAddress);
+const position = await tradingFloorLens.getCompletePositionData(tradingFloorAddress, positionId);
+```
+
+### Utility Functions
+
+#### Price Conversions
+
+```typescript
+import { floatToPriceBn, priceBnToFloat } from 'lynx-client';
+
+// Convert human-readable price to contract format (8 decimals)
+const priceBn = floatToPriceBn(50000.50); // $50,000.50 → BigInt
+
+// Convert contract price to human-readable
+const price = priceBnToFloat(priceBn); // BigInt → 50000.50
+```
+
+#### Leverage Conversions
+
+```typescript
+import { floatUnitsToScaledLeverage, scaledLeverageToUnits } from 'lynx-client';
+
+// Convert human leverage to contract format
+const scaledLeverage = floatUnitsToScaledLeverage(25); // 25x → 2500
+
+// Convert contract leverage to human-readable
+const leverage = scaledLeverageToUnits(2500); // 2500 → 25x
+```
+
+#### Collateral Conversions
+
+```typescript
+import { floatToChipsBn, chipsBnToUnits } from 'lynx-client';
+
+// Convert human-readable amount to contract format (18 decimals)
+const collateralBn = floatToChipsBn(100.5); // 100.5 tokens → BigInt
+
+// Convert contract amount to human-readable
+const collateral = chipsBnToUnits(collateralBn); // BigInt → 100.5
+```
+
+#### Fraction Conversions
+
+```typescript
+import { floatToFractionBn, fractionBnToFloat } from 'lynx-client';
+
+// Convert percentage to contract format
+const fractionBn = floatToFractionBn(0.05); // 5% → 5000
+
+// Convert contract fraction to percentage
+const fraction = fractionBnToFloat(5000n); // 5000 → 0.05 (5%)
+```
+
+## Advanced Usage
+
+### Position Management
+
+```typescript
+// Update position with new TP/SL
+await tradersPortal.traderRequests.updatePositionDoubleFieldTpAndSl(
+  positionId,
+  floatToPriceBn(55000), // New TP: $55,000
+  floatToPriceBn(48000), // New SL: $48,000
+  ethers.parseEther("0.01") // Fee
+);
+
+// Close position at market
+await tradersPortal.traderRequests.setExistingPositionToMarketClose(
+  positionId,
+  floatToPriceBn(49900), // Min acceptable price
+  floatToPriceBn(50100), // Max acceptable price
+  ethers.parseEther("0.01") // Fee
+);
+```
+
+### Working with Triggers
+
+```typescript
+import { createTriggersService } from 'lynx-client';
+
+const triggers = createTriggersService(signer, triggersAddress);
+
+// Get trigger configurations
+const configs = await triggers.getTriggersConfigurations();
+const pairConfigs = await triggers.getPairConfigsInTriggers(1); // Pair ID 1
+```
+
+### LEX Pool Operations
+
+```typescript
+// Get complete LEX pool state
+const completeState = await lexLens.getCompleteStateForLex(lexPoolAddress);
+
+// Get supplier state
+const supplierState = await lexLens.getLexPoolSupplierState(
+  lexPoolAddress,
+  supplierAddress
+);
+
+// Get all fee configurations
+const feeConfigs = await lexLens.getAllFeeConfigurationsInLex(lexPoolAddress);
+```
+
+## Type Safety
+
+The SDK provides comprehensive TypeScript types for all contract interactions:
+
+```typescript
+import { 
+  TPositionRequestIdentifierStruct,
+  TPositionRequestParamsStruct,
+  TSinglePositionStruct,
+  TPairConfigsInTriggersStruct
+} from 'lynx-client';
+
+// All contract structs are properly typed
+const position = await tradingFloorLens.getCompletePositionData(tradingFloorAddress, id);
+console.log(position.trader); // string
+console.log(position.collateral); // bigint
+console.log(position.leverage); // bigint
+```
+
+## Error Handling
+
+The SDK validates inputs to prevent common errors:
+
+```typescript
+try {
+  // This will throw an error - can't use both price and fraction TP
+  const params = buildPositionRequestParams({
+    isLong: true,
+    collateral: 100,
+    leverage: 25,
+    minPrice: 50000,
+    maxPrice: 50100,
+    takeProfit: 55000, // Price-based TP
+    takeProfitByFraction: 0.1 // Fraction-based TP - ERROR!
+  });
+} catch (error) {
+  console.error("Cannot specify both takeProfit and takeProfitByFraction");
+}
+```
+
+## Constants and Enums
+
+```typescript
+import { 
+  TOpenOrderType,
+  TOrderCloseType,
+  TPositionField,
+  TPairIds,
+  CHIP_DECIMALS,
+  PRICES_SCALE,
+  LEVERAGE_MULTIPLIER_SCALE
+} from 'lynx-client';
+
+// Order types
+const marketOrder = TOpenOrderType.MARKET;
+const limitOrder = TOpenOrderType.LIMIT;
+
+// Pair IDs
+const btcUsd = TPairIds.BTC_USD;
+const ethUsd = TPairIds.ETH_USD;
+```
+
+## Best Practices
+
+1. **Always use builder functions** for creating position requests:
+   ```typescript
+   // ✅ Good
+   const params = buildPositionRequestParams({ ... });
+   
+   // ❌ Avoid manual construction
+   const params = { long: true, collateral: 100n, ... };
+   ```
+
+2. **Use utility functions** for conversions:
+   ```typescript
+   // ✅ Good
+   const priceBn = floatToPriceBn(50000);
+   
+   // ❌ Avoid manual calculations
+   const priceBn = BigInt(50000 * 10**8);
+   ```
+
+3. **Handle contract errors** appropriately:
+   ```typescript
+   try {
+     await tradersPortal.traderRequests.openNewPosition(...);
+   } catch (error) {
+     if (error.reason === "Insufficient collateral") {
+       // Handle specific error
+     }
+   }
+   ```
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+ISC
+
+## Support
+
+- [GitHub Issues](https://github.com/lynx-protocol/lynx-client/issues)
+- [Documentation](https://lynx-finance.gitbook.io/lynx-finance/)
+- [Discord](https://discord.gg/4CGxEYwrF2)

package/dist/cjs/index.js

@@ -51,3 +51,5 @@ __exportStar(require("./lib/typechain/factories/contracts/Peripheral/Lens/Intent
 __exportStar(require("./lib/typechain/factories/contracts/Peripheral/Lens/TriggersAndPortalLens__factory"), exports);
 __exportStar(require("./lib/typechain/factories/contracts/Peripheral/Lens/LexLens__factory"), exports);
 __exportStar(require("./lib/typechain/factories/contracts/Peripheral/Lens/TradingFloorLens__factory"), exports);
+// Developer Experience utilities
+__exportStar(require("./lib/devex"), exports);

package/dist/cjs/lib/chains/chainMappings.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENGINE_CHAIN_DISPLAY_NAME = exports.ENGINE_CHAIN_ID_BY_NAME = void 0;
+const chainConstants_1 = require("./chainConstants");
+// Engine chain mappings
+exports.ENGINE_CHAIN_ID_BY_NAME = {
+    sonic: chainConstants_1.CHAIN_ID_SONIC,
+    boba: chainConstants_1.CHAIN_ID_BOBA,
+    flare: chainConstants_1.CHAIN_ID_FLARE,
+    fantom: chainConstants_1.CHAIN_ID_FANTOM,
+};
+exports.ENGINE_CHAIN_DISPLAY_NAME = {
+    sonic: "Sonic",
+    boba: "Boba",
+    flare: "Flare",
+    fantom: "Fantom",
+};

package/dist/cjs/lib/contractsIntegration/IntentsVerifierLensService/IntentsVerifierLensService.js

@@ -5,8 +5,8 @@ const IntentsVerifierLens__factory_1 = require("../../typechain/factories/contra
 const ethersTypes_1 = require("../../utils/ethersTypes");
 const IIntentsVerifierLensService_1 = require("./IIntentsVerifierLensService");
 class IntentsVerifierLensService {
-    constructor(provider, address) {
-        this.contract = IntentsVerifierLens__factory_1.IntentsVerifierLens__factory.connect(address, provider);
+    constructor(signerOrProvider, address) {
+        this.contract = IntentsVerifierLens__factory_1.IntentsVerifierLens__factory.connect(address, signerOrProvider);
     }
     async getRequestBuildingInfoForChipsIntentsVerifier(account, actionType) {
         const result = await this.contract.getRequestBuildingInfoForChipsIntentsVerifier(account, BigInt(actionType));

package/dist/cjs/lib/contractsIntegration/LexLensService/LexLensService.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LexLensService = void 0;
+const LexLens__factory_1 = require("../../typechain/factories/contracts/Peripheral/Lens/LexLens__factory");
 const ethersTypes_1 = require("../../utils/ethersTypes");
 const ILexLensService_1 = require("./ILexLensService");
 class LexLensService {
-    constructor(contract) {
-        this.contract = contract;
+    constructor(signerOrProvider, contractAddress) {
+        this.contract = LexLens__factory_1.LexLens__factory.connect(contractAddress, signerOrProvider);
     }
     async getAllFeeConfigurationsInLex(lexPool) {
         const result = await this.contract.getAllFeeConfigurationsInLex(lexPool);
@@ -245,26 +246,5 @@ class LexLensService {
             })),
         };
     }
-    convertCompleteStateResult(result) {
-        const baseResult = (0, ethersTypes_1.ethersStructResponseToObject)(result, ILexLensService_1.EMPTY_COMPLETE_LEX_STATE, {
-            pairsStates: ILexLensService_1.EMPTY_LEX_PAIR_STATE_LENS,
-            groupsStates: ILexLensService_1.EMPTY_LEX_GROUP_STATE_LENS,
-        }, {
-            lexPoolState: ILexLensService_1.EMPTY_LEX_POOL_LENS_STATE,
-            poolAccountantState: ILexLensService_1.EMPTY_POOL_ACCOUNTANT_STATE_LENS,
-        });
-        // Apply number conversions
-        return {
-            ...baseResult,
-            pairsStates: baseResult.pairsStates.map(item => ({
-                ...item,
-                pairId: Number(item.pairId),
-            })),
-            groupsStates: baseResult.groupsStates.map(item => ({
-                ...item,
-                groupId: Number(item.groupId),
-            })),
-        };
-    }
 }
 exports.LexLensService = LexLensService;

package/dist/cjs/lib/contractsIntegration/OrderBookService/OrderBookService.js

@@ -2,16 +2,36 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrderBookService = void 0;
 const OrderBookV1__factory_1 = require("../../typechain/factories/contracts/Lynx/OrderBook/OrderBookV1__factory");
-class OrderBookService {
-    constructor(address, signerOrProvider) {
-        this.signerOrProvider = signerOrProvider;
-        this.orderBookContract = OrderBookV1__factory_1.OrderBookV1__factory.connect(address, signerOrProvider);
+class OrderManagement {
+    constructor(orderBookContract) {
+        this.orderBookContract = orderBookContract;
     }
-    // Order Management
     async getAllPendingUpdateOrderIds() {
         return this.orderBookContract.getAllPendingUpdateOrderIds();
     }
-    // Contract References
+    async allPendingUpdateOrderIds(index) {
+        return this.orderBookContract.allPendingUpdateOrderIds(index);
+    }
+    async pendingUpdateTradeFieldOrdersById(positionId) {
+        return this.orderBookContract.pendingUpdateTradeFieldOrdersById(positionId);
+    }
+    async readAndDeleteUpdatePositionOrder(positionId) {
+        return this.orderBookContract.readAndDeleteUpdatePositionOrder(positionId);
+    }
+    async storeUpdatePositionDoubleFieldOrder(positionId, orderType, fieldValueA, fieldValueB) {
+        return this.orderBookContract.storeUpdatePositionDoubleFieldOrder(positionId, orderType, fieldValueA, fieldValueB);
+    }
+    async storeUpdatePositionSingleFieldOrder(positionId, orderType, fieldValue) {
+        return this.orderBookContract.storeUpdatePositionSingleFieldOrder(positionId, orderType, fieldValue);
+    }
+    async updateOrderIdPositionInList(positionId) {
+        return this.orderBookContract.updateOrderIdPositionInList(positionId);
+    }
+}
+class ContractInfo {
+    constructor(orderBookContract) {
+        this.orderBookContract = orderBookContract;
+    }
     async registry() {
         return this.orderBookContract.registry();
     }
@@ -30,7 +50,22 @@ class OrderBookService {
     async pendingImplementation() {
         return this.orderBookContract.pendingImplementation();
     }
-    // Constants
+}
+class Administration {
+    constructor(orderBookContract) {
+        this.orderBookContract = orderBookContract;
+    }
+    async setTradingFloor(tradingFloor) {
+        return this.orderBookContract.setTradingFloor(tradingFloor);
+    }
+    async _become(orderBookProxy) {
+        return this.orderBookContract._become(orderBookProxy);
+    }
+}
+class Constants {
+    constructor(orderBookContract) {
+        this.orderBookContract = orderBookContract;
+    }
     async ACCURACY_IMPROVEMENT_SCALE() {
         return this.orderBookContract.ACCURACY_IMPROVEMENT_SCALE();
     }
@@ -44,4 +79,14 @@ class OrderBookService {
         return this.orderBookContract.PRECISION();
     }
 }
+class OrderBookService {
+    constructor(address, signerOrProvider) {
+        this.signerOrProvider = signerOrProvider;
+        this.orderBookContract = OrderBookV1__factory_1.OrderBookV1__factory.connect(address, signerOrProvider);
+        this.orderManagement = new OrderManagement(this.orderBookContract);
+        this.contractInfo = new ContractInfo(this.orderBookContract);
+        this.administration = new Administration(this.orderBookContract);
+        this.constants = new Constants(this.orderBookContract);
+    }
+}
 exports.OrderBookService = OrderBookService;

package/dist/cjs/lib/contractsIntegration/TradingFloorLensService/TradingFloorLensService.js

@@ -1,24 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TradingFloorLensService = void 0;
+const TradingFloorLens__factory_1 = require("../../typechain/factories/contracts/Peripheral/Lens/TradingFloorLens__factory");
 class TradingFloorLensService {
-    constructor(contract) {
-        this.contract = contract;
+    constructor(signerOrProvider, contractAddress) {
+        this.contract = TradingFloorLens__factory_1.TradingFloorLens__factory.connect(contractAddress, signerOrProvider);
     }
     async generatePositionHashId(settlementAsset, trader, pairId, index) {
         return await this.contract.generatePositionHashId(settlementAsset, trader, pairId, index);
     }
     async getAllPositionsDataForAllTraders(params) {
         // @ts-ignore
-        return await this.contract.getAllPositionsDataForAllTraders.staticCall(params);
+        const result = await this.contract.getAllPositionsDataForAllTraders.staticCall(params);
+        // Filter out empty positions (collateral = 0)
+        const filteredPositions = result.positions.filter((pos) => pos.collateral > 0n);
+        return {
+            ...result,
+            positions: filteredPositions
+        };
     }
     async getAllPositionsDataForAllTradersInDimension(tradingFloor, settlementAsset, arraySize) {
         // @ts-ignore
-        return await this.contract.getAllPositionsDataForAllTradersInDimension.staticCall(tradingFloor, settlementAsset, arraySize);
+        const result = await this.contract.getAllPositionsDataForAllTradersInDimension.staticCall(tradingFloor, settlementAsset, arraySize);
+        // Filter out empty positions (collateral = 0)
+        return result.filter((pos) => pos.collateral > 0n);
     }
     async getAllPositionsDataForTraderInDimension(tradingFloor, settlementAsset, trader) {
         // @ts-ignore
-        return await this.contract.getAllPositionsDataForTraderInDimension.staticCall(tradingFloor, settlementAsset, trader);
+        const result = await this.contract.getAllPositionsDataForTraderInDimension.staticCall(tradingFloor, settlementAsset, trader);
+        // Filter out empty positions (collateral = 0)
+        return result.filter((pos) => pos.collateral > 0n);
     }
     async getAllPositionsLiquidationInfo(params, phases) {
         if (phases !== undefined) {
@@ -36,11 +47,15 @@ class TradingFloorLensService {
     }
     async getPositionDataInPairsForTrader(tradingFloor, settlementAsset, trader, pairIds) {
         // @ts-ignore
-        return await this.contract.getPositionDataInPairsForTrader.staticCall(tradingFloor, settlementAsset, trader, pairIds);
+        const result = await this.contract.getPositionDataInPairsForTrader.staticCall(tradingFloor, settlementAsset, trader, pairIds);
+        // Filter out empty positions (collateral = 0)
+        return result.filter((pos) => pos.collateral > 0n);
     }
     async getPositionsDataInPairForTrader(tradingFloor, settlementAsset, trader, pairId) {
         // @ts-ignore
-        return await this.contract.getPositionsDataInPairForTrader.staticCall(tradingFloor, settlementAsset, trader, pairId);
+        const result = await this.contract.getPositionsDataInPairForTrader.staticCall(tradingFloor, settlementAsset, trader, pairId);
+        // Filter out empty positions (collateral = 0)
+        return result.filter((pos) => pos.collateral > 0n);
     }
     async getTradingFloorTradeParams(tradingFloor) {
         return await this.contract.getTradingFloorTradeParams(tradingFloor);

package/dist/cjs/lib/contractsIntegration/TriggersAndPortalLensService/TriggersAndPortalLensService.js

@@ -5,8 +5,8 @@ const TriggersAndPortalLens__factory_1 = require("../../typechain/factories/cont
 const ethersTypes_1 = require("../../utils/ethersTypes");
 const ITriggersAndPortalLensService_1 = require("./ITriggersAndPortalLensService");
 class TriggersAndPortalLensService {
-    constructor(provider, address) {
-        this.contract = TriggersAndPortalLens__factory_1.TriggersAndPortalLens__factory.connect(address, provider);
+    constructor(signerOrProvider, address) {
+        this.contract = TriggersAndPortalLens__factory_1.TriggersAndPortalLens__factory.connect(address, signerOrProvider);
     }
     async getPairConfigsInTriggers(triggers, pairId) {
         const result = await this.contract.getPairConfigsInTriggers(triggers, BigInt(pairId));

package/dist/cjs/lib/contractsIntegration/deployedContractsConnector.js

@@ -119,17 +119,15 @@ function connectToLeXLens(provider, address) {
 //
 // ***** Lens Services *****
 //
-function createIntentsVerifierLensService(provider, address) {
-    return new IntentsVerifierLensService_1.IntentsVerifierLensService(provider, address);
+function createIntentsVerifierLensService(signerOrProvider, address) {
+    return new IntentsVerifierLensService_1.IntentsVerifierLensService(signerOrProvider, address);
 }
-function createTriggersAndPortalLensService(provider, address) {
-    return new TriggersAndPortalLensService_1.TriggersAndPortalLensService(provider, address);
+function createTriggersAndPortalLensService(signerOrProvider, address) {
+    return new TriggersAndPortalLensService_1.TriggersAndPortalLensService(signerOrProvider, address);
 }
-function createTradingFloorLensService(provider, address) {
-    const contract = connectToTradingFloorLens(provider, address);
-    return new TradingFloorLensService_1.TradingFloorLensService(contract);
+function createTradingFloorLensService(signerOrProvider, address) {
+    return new TradingFloorLensService_1.TradingFloorLensService(signerOrProvider, address);
 }
-function createLexLensService(provider, address) {
-    const contract = connectToLeXLens(provider, address);
-    return new LexLensService_1.LexLensService(contract);
+function createLexLensService(signerOrProvider, address) {
+    return new LexLensService_1.LexLensService(signerOrProvider, address);
 }