openbook-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OpenBook CLI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,209 @@
+# OpenBook CLI
+
+A comprehensive command-line interface for interacting with OpenBook and Serum DEX markets on Solana.
+
+## 🚀 Features
+
+- **Auto-detection**: Automatically detects OpenBook vs Serum markets
+- **Real-time data**: Fetches live order book data from the blockchain
+- **Market management**: Add and list known markets
+- **Universal support**: Works with any market address (known or unknown)
+- **Separate storage**: Maintains separate files for OpenBook and Serum markets
+
+## 📦 Installation
+
+```bash
+npm install -g openbook-cli
+```
+
+Or install locally:
+
+```bash
+npm install openbook-cli
+```
+
+## 🎯 Quick Start
+
+```bash
+# Fetch market data (auto-detects OpenBook/Serum)
+openbook-cli Gc4tfUHRNnpVwvASfQD3q26G8GNmLYuz4KzB4QNkNuiQ
+
+# Add market to known markets
+openbook-cli 8nqjw5UVN65GyfdqiXnfJNbDVBgbk8RpFFd7uACXenbx --add
+
+# List OpenBook markets
+openbook-cli --list
+
+# List Serum markets
+openbook-cli --list --serum
+```
+
+## 📋 Commands
+
+### Fetch Market Data
+```bash
+openbook-cli <market_address>
+```
+Fetches real-time market information and order book data.
+
+### Add Market to Known Markets
+```bash
+openbook-cli <market_address> --add
+```
+Adds a market to the persistent storage for future quick access.
+
+### List Known Markets
+```bash
+# List OpenBook markets
+openbook-cli --list
+
+# List Serum markets
+openbook-cli --list --serum
+```
+
+## 🔍 Auto-Detection
+
+The CLI automatically detects whether a market belongs to OpenBook or Serum by checking the market account owner:
+
+- **OpenBook**: `srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX`
+- **Serum**: `9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin`
+
+## 📊 Data Storage
+
+The CLI maintains separate files for different market types:
+
+- `known_openbook_markets.json` - OpenBook markets and token symbols
+- `known_serum_markets.json` - Serum markets and token symbols
+
+## 🎨 Token Symbol Resolution
+
+### Known Tokens
+Automatically recognizes common tokens:
+- **SOL**: `So11111111111111111111111111111111111111112`
+- **USDC**: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
+- **ATLAS**: `HjFijcGWKgfDwGpFX2rqFwEU9jtEgFuRQAJe1ERXFsA3`
+
+### Unknown Tokens
+For unknown tokens, the system:
+1. Attempts to fetch Metaplex metadata
+2. Falls back to first 8 characters of the mint address
+3. Displays as: `First8Chars` (e.g., `BV1soTdX`)
+
+## 📈 Order Book Data
+
+The CLI fetches live order book data directly from the blockchain:
+- **Bids**: Buy orders sorted by price (highest first)
+- **Asks**: Sell orders sorted by price (lowest first)
+- **Depth**: Configurable depth (default: 15 levels)
+
+### Market Statistics
+- **Total Bids/Asks**: Number of orders on each side
+- **Best Bid/Ask**: Highest bid and lowest ask prices
+- **Spread**: Difference between best ask and best bid
+- **Spread %**: Spread as a percentage of best bid
+
+## 🛠️ Development
+
+### Prerequisites
+- Node.js >= 16.0.0
+- TypeScript
+
+### Setup
+```bash
+git clone https://github.com/yourusername/openbook-cli.git
+cd openbook-cli
+npm install
+```
+
+### Build
+```bash
+npm run build
+```
+
+### Development
+```bash
+npm run dev
+```
+
+## 📝 Examples
+
+### Basic Market Fetch
+```bash
+# Fetch any market (auto-detects type)
+openbook-cli Gc4tfUHRNnpVwvASfQD3q26G8GNmLYuz4KzB4QNkNuiQ
+```
+
+### Add New Markets
+```bash
+# Add OpenBook market
+openbook-cli EgnTFXgaQ8CzVSQJyTD2sT3Yx8esLgKf5e6YGvQfm2U7 --add
+
+# Add Serum market
+openbook-cli 8nqjw5UVN65GyfdqiXnfJNbDVBgbk8RpFFd7uACXenbx --add
+```
+
+### List Markets
+```bash
+# List OpenBook markets
+openbook-cli --list
+
+# List Serum markets
+openbook-cli --list --serum
+```
+
+## 🔧 Configuration
+
+The CLI uses the following configuration:
+
+- **RPC Endpoint**: Default Solana RPC
+- **Market Files**: Stored in the current directory
+- **Token Symbols**: Cached for faster access
+
+## 🚨 Error Handling
+
+### Common Issues
+1. **Market not found**: Invalid market address
+2. **Network issues**: Connection problems to Solana RPC
+3. **Token metadata unavailable**: Missing Metaplex data
+4. **Program ownership mismatch**: Market belongs to different program
+
+### Error Messages
+- `❌ Market account not found` - Invalid market address
+- `❌ Market verification failed` - Program ownership issue
+- `No Metaplex metadata found` - Token symbol resolution failed
+
+## 📊 Performance
+
+### Response Times
+- **Known markets**: ~2-3 seconds
+- **Unknown markets**: ~3-5 seconds (includes metadata fetch)
+- **Order book data**: ~1-2 seconds
+
+### Network Usage
+- Each market fetch requires multiple RPC calls
+- Order book data is fetched in real-time
+- Token metadata is cached after first fetch
+
+## 🔒 Security
+
+### Data Sources
+- All data comes directly from Solana blockchain
+- No third-party API dependencies
+- Real-time verification of market ownership
+
+### Market Validation
+- Verifies market account exists
+- Checks program ownership
+- Validates token mint addresses
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🤝 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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+// Run the CLI
+(0, index_1.main)().catch((error) => {
+    console.error('❌ CLI Error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;AAEA,mCAA+B;AAE/B,cAAc;AACd,IAAA,YAAI,GAAE,CAAC,KAAK,CAAC,CAAC,KAAU,EAAE,EAAE;IACxB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { Market } from "@project-serum/serum";
+interface OrderBookLevel {
+    price: number;
+    size: number;
+    side: 'bid' | 'ask';
+}
+interface MarketInfo {
+    address: string;
+    baseMint: string;
+    quoteMint: string;
+    baseSymbol: string;
+    quoteSymbol: string;
+    minOrderSize: number;
+    priceTick: number;
+    eventQueueLength: number;
+    requestQueueLength: number;
+    bidsLength: number;
+    asksLength: number;
+}
+declare function getMarketInfo(marketAddress: string, useSerum?: boolean): Promise<MarketInfo>;
+declare function loadOpenBookMarket(marketAddress: string, useSerum?: boolean): Promise<Market>;
+declare function getRealOrderBook(marketAddress: string, depth?: number, useSerum?: boolean): Promise<{
+    bids: OrderBookLevel[];
+    asks: OrderBookLevel[];
+}>;
+declare function getOrderBook(marketAddress: string, depth?: number): Promise<{
+    bids: OrderBookLevel[];
+    asks: OrderBookLevel[];
+}>;
+declare function getMarketStats(marketAddress: string, useSerum?: boolean): Promise<{
+    totalBids: number;
+    totalAsks: number;
+    bestBid: number | null;
+    bestAsk: number | null;
+    spread: number | null;
+    spreadPercentage: number | null;
+}>;
+declare function displayOrderBook(marketAddress: string, depth?: number, useSerum?: boolean): Promise<void>;
+declare function displayMarketInfo(marketAddress: string, useSerum?: boolean): Promise<void>;
+declare function listKnownMarkets(useSerum?: boolean): void;
+declare function main(): Promise<void>;
+export { getMarketInfo, getOrderBook, getMarketStats, displayOrderBook, displayMarketInfo, listKnownMarkets, loadOpenBookMarket, getRealOrderBook };
+export { main };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAY9C,UAAU,cAAc;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;CACvB;AAED,UAAU,UAAU;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACtB;AA+ED,iBAAe,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAiDlG;AA8BD,iBAAe,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBnG;AAED,iBAAe,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC;IAC3G,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,IAAI,EAAE,cAAc,EAAE,CAAC;CAC1B,CAAC,CA2CD;AAED,iBAAe,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,OAAO,CAAC;IAC5E,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,IAAI,EAAE,cAAc,EAAE,CAAC;CAC1B,CAAC,CAYD;AAED,iBAAe,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC,CAAC,CAsBD;AAED,iBAAe,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDnH;AAED,iBAAe,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAwChG;AAED,iBAAS,gBAAgB,CAAC,QAAQ,GAAE,OAAe,GAAG,IAAI,CAQzD;AAmHD,iBAAe,IAAI,kBAwFlB;AAGD,OAAO,EACH,aAAa,EACb,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EACnB,CAAC;AAGF,OAAO,EAAE,IAAI,EAAE,CAAC"}