Merge pull request #602 from drift-labs/master

Indicative liquidity metrics for trades publisher

Author: jonthia-drift

.env.trades.local.example

@@ -0,0 +1,22 @@
+ENDPOINT=https://api.devnet.solana.com
+WS_ENDPOINT=wss://api.devnet.solana.com
+ENV=devnet
+
+RUNNING_LOCAL=true
+LOCAL_CACHE=true
+ELASTICACHE_HOST=localhost
+ELASTICACHE_PORT=6379
+REDIS_CLIENT=DLOB
+
+METRICS_PORT=9465
+INDICATIVE_QUOTES_MAX_AGE_MS=1000
+INDICATIVE_QUOTES_CACHE_TTL_MS=250
+
+ENABLE_MOCK_FILL_ENDPOINT=true
+MOCK_ONLY_MODE=true
+MOCK_FILL_PORT=9470
+
+MOCK_MARKET_TYPE=perp
+MOCK_MARKET_INDEX=0
+MOCK_QUOTES_JSON=[{"maker":"good-maker","side":"long","price":100,"size":2},{"maker":"bad-maker","side":"long","price":99,"size":1}]
+MOCK_FILLS_JSON=[{"maker":"good-maker","side":"long","fillPrice":100,"fillSize":1,"oraclePrice":100}]

.gitignore

@@ -139,11 +139,13 @@ src/**.js.map
 .idea
 
 .env
+.env.*.local
 lib
 src/playground.ts
 
 # redis files
 *.rdb
 *.log
 *.confg
-
+*.aof*
+*.conf

package.json

@@ -10,7 +10,7 @@
 		"@aws-sdk/util-retry": "^3.374.0",
 		"@coral-xyz/anchor": "^0.29.0",
 		"@drift-labs/common": "1.0.20",
-		"@drift-labs/sdk": "2.161.0-beta.4",
+		"@drift-labs/sdk": "2.162.0-beta.1",
 		"@opentelemetry/api": "^1.1.0",
 		"@opentelemetry/auto-instrumentations-node": "^0.31.1",
 		"@opentelemetry/exporter-prometheus": "^0.31.0",
@@ -71,6 +71,8 @@
 		"server-lite": "ts-node src/serverLite.ts",
 		"dlob-publish": "ts-node src/publishers/dlobPublisher.ts",
 		"trades-publish": "ts-node src/publishers/tradesPublisher.ts",
+		"trades-publish:local": "DOTENV_CONFIG_PATH=.env.trades.local ts-node -r dotenv/config src/publishers/tradesPublisher.ts",
+		"mock-jit:submit": "DOTENV_CONFIG_PATH=.env.trades.local ts-node -r dotenv/config src/scripts/submitMockJitMetricsData.ts",
 		"fees-publish": "ts-node src/publishers/priorityFeesPublisher.ts",
 		"pnl-publish": "ts-node src/scripts/publishUnsettledPnlUsers.ts",
 		"ws-manager": "ts-node src/wsConnectionManager.ts",
@@ -84,8 +86,8 @@
 		"lint": "eslint . --ext ts --quiet",
 		"lint:fix": "eslint . --ext ts --fix",
 		"playground": "ts-node src/playground.ts",
-		"test": "jest src/utils/tests/auctionParams.test.ts",
-		"test:watch": "jest src/utils/tests/auctionParams.test.ts --watch"
+		"test": "jest",
+		"test:watch": "jest --watch"
 	},
 	"jest": {
 		"preset": "ts-jest",

src/publishers/tests/tradeMetrics.test.ts

@@ -0,0 +1,328 @@
+import { describe, expect, it } from '@jest/globals';
+import { BASE_PRECISION, PRICE_PRECISION } from '@drift-labs/sdk';
+import {
+	getAbsoluteBpsDiff,
+	getCompetitiveLiquidity,
+	getIndicativeDirectionBucket,
+	getFillPrice,
+	getFillSide,
+	getFillTimestampMs,
+	getIndicativeBpsBucket,
+	getQuoteTimestampMs,
+	getQuoteValueOnBook,
+	getSignedBpsDiff,
+	isCompetitivePrice,
+	rawPriceToNumber,
+} from '../tradeMetrics';
+
+describe('tradeMetrics', () => {
+	describe('getFillPrice', () => {
+		it('computes the executed unit price', () => {
+			expect(
+				getFillPrice({
+					baseAssetAmountFilled: 2,
+					quoteAssetAmountFilled: 210,
+				})
+			).toBe(105);
+		});
+
+		it('returns undefined for zero base size', () => {
+			expect(
+				getFillPrice({
+					baseAssetAmountFilled: 0,
+					quoteAssetAmountFilled: 210,
+				})
+			).toBeUndefined();
+		});
+	});
+
+	describe('getFillTimestampMs', () => {
+		it('normalizes seconds to milliseconds', () => {
+			expect(getFillTimestampMs(1710000000)).toBe(1710000000000);
+		});
+
+		it('leaves millisecond timestamps unchanged', () => {
+			expect(getFillTimestampMs(1710000000000)).toBe(1710000000000);
+		});
+	});
+
+	describe('getQuoteTimestampMs', () => {
+		it('extracts the quote timestamp when present', () => {
+			expect(getQuoteTimestampMs({ ts: 1710000000000 })).toBe(1710000000000);
+		});
+
+		it('returns undefined for missing or invalid timestamps', () => {
+			expect(getQuoteTimestampMs(null)).toBeUndefined();
+			expect(getQuoteTimestampMs({ ts: 'bad-ts' })).toBeUndefined();
+		});
+	});
+
+	describe('getFillSide', () => {
+		it('infers the maker side from taker direction first', () => {
+			expect(getFillSide({ takerOrderDirection: 'long' })).toBe('short');
+			expect(getFillSide({ takerOrderDirection: 'short' })).toBe('long');
+		});
+
+		it('falls back to maker direction', () => {
+			expect(getFillSide({ makerOrderDirection: 'long' })).toBe('long');
+			expect(getFillSide({ makerOrderDirection: 'short' })).toBe('short');
+		});
+
+		it('returns undefined when neither side is available', () => {
+			expect(getFillSide({})).toBeUndefined();
+		});
+	});
+
+	describe('rawPriceToNumber', () => {
+		it('converts oracle-offset quotes to absolute prices', () => {
+			expect(rawPriceToNumber(2 * PRICE_PRECISION.toNumber(), 100)).toBe(102);
+		});
+	});
+
+	describe('isCompetitivePrice', () => {
+		it('treats bid prices at or above the fill price as competitive', () => {
+			expect(isCompetitivePrice('long', 101, 100)).toBe(true);
+			expect(isCompetitivePrice('long', 99, 100)).toBe(false);
+		});
+
+		it('treats ask prices at or below the fill price as competitive', () => {
+			expect(isCompetitivePrice('short', 99, 100)).toBe(true);
+			expect(isCompetitivePrice('short', 101, 100)).toBe(false);
+		});
+	});
+
+	describe('bps bucketing', () => {
+		it('computes absolute bps distance', () => {
+			expect(getAbsoluteBpsDiff(100.1, 100)).toBeCloseTo(10, 8);
+			expect(getAbsoluteBpsDiff(99.9, 100)).toBeCloseTo(10, 8);
+		});
+
+		it('computes signed bps distance', () => {
+			expect(getSignedBpsDiff(100.1, 100)).toBeCloseTo(10, 8);
+			expect(getSignedBpsDiff(99.9, 100)).toBeCloseTo(-10, 8);
+		});
+
+		it('maps bps distances into the configured buckets', () => {
+			expect(getIndicativeBpsBucket(0)).toBe('very_tight');
+			expect(getIndicativeBpsBucket(9.99)).toBe('very_tight');
+			expect(getIndicativeBpsBucket(10)).toBe('tight');
+			expect(getIndicativeBpsBucket(19.99)).toBe('tight');
+			expect(getIndicativeBpsBucket(20)).toBe('moderate');
+			expect(getIndicativeBpsBucket(29.99)).toBe('moderate');
+			expect(getIndicativeBpsBucket(30)).toBe('wide');
+			expect(getIndicativeBpsBucket(49.99)).toBe('wide');
+			expect(getIndicativeBpsBucket(50)).toBe('very_wide');
+			expect(getIndicativeBpsBucket(500)).toBe('very_wide');
+		});
+
+		it('maps signed bps distances into directional buckets', () => {
+			expect(getIndicativeDirectionBucket(10)).toBe('better');
+			expect(getIndicativeDirectionBucket(0)).toBe('equal');
+			expect(getIndicativeDirectionBucket(-10)).toBe('worse');
+		});
+	});
+
+	describe('getCompetitiveLiquidity', () => {
+		it('aggregates only bid levels that were competitive for a long maker', () => {
+			const liquidity = getCompetitiveLiquidity(
+				'mm-1',
+				{
+					marketIndex: 0,
+					marketType: 'perp',
+					oraclePrice: 100,
+				},
+				'long',
+				100,
+				{
+					ts: 1710000000000,
+					quotes: [
+						{
+							bid_price: 101 * PRICE_PRECISION.toNumber(),
+							bid_size: BASE_PRECISION.toNumber(),
+						},
+						{
+							bid_price: 100 * PRICE_PRECISION.toNumber(),
+							bid_size: 2 * BASE_PRECISION.toNumber(),
+						},
+						{
+							bid_price: 99 * PRICE_PRECISION.toNumber(),
+							bid_size: 4 * BASE_PRECISION.toNumber(),
+						},
+					],
+				}
+			);
+
+			expect(liquidity).toEqual({
+				maker: 'mm-1',
+				bestPrice: 101,
+				size: 3,
+				quoteValue: 301,
+				quoteTsMs: 1710000000000,
+			});
+		});
+
+		it('aggregates only ask levels that were competitive for a short maker', () => {
+			const liquidity = getCompetitiveLiquidity(
+				'mm-2',
+				{
+					marketIndex: 0,
+					marketType: 'perp',
+					oraclePrice: 100,
+				},
+				'short',
+				100,
+				{
+					ts: 1710000000000,
+					quotes: [
+						{
+							ask_price: 99 * PRICE_PRECISION.toNumber(),
+							ask_size: 1.5 * BASE_PRECISION.toNumber(),
+						},
+						{
+							ask_price: 100 * PRICE_PRECISION.toNumber(),
+							ask_size: 0.5 * BASE_PRECISION.toNumber(),
+						},
+						{
+							ask_price: 101 * PRICE_PRECISION.toNumber(),
+							ask_size: 10 * BASE_PRECISION.toNumber(),
+						},
+					],
+				}
+			);
+
+			expect(liquidity).toEqual({
+				maker: 'mm-2',
+				bestPrice: 99,
+				size: 2,
+				quoteValue: 198.5,
+				quoteTsMs: 1710000000000,
+			});
+		});
+
+		it('supports oracle-offset quotes', () => {
+			const liquidity = getCompetitiveLiquidity(
+				'mm-3',
+				{
+					marketIndex: 0,
+					marketType: 'perp',
+					oraclePrice: 100,
+				},
+				'long',
+				100,
+				{
+					ts: 1710000000000,
+					quotes: [
+						{
+							bid_price: PRICE_PRECISION.toNumber(),
+							bid_size: BASE_PRECISION.toNumber(),
+							is_oracle_offset: true,
+						},
+					],
+				}
+			);
+
+			expect(liquidity?.bestPrice).toBe(101);
+			expect(liquidity?.size).toBe(1);
+		});
+
+		it('uses spot market precision when provided', () => {
+			const liquidity = getCompetitiveLiquidity(
+				'mm-4',
+				{
+					marketIndex: 1,
+					marketType: 'spot',
+					oraclePrice: 10,
+				},
+				'long',
+				10,
+				{
+					ts: 1710000000000,
+					quotes: [
+						{
+							bid_price: 10 * PRICE_PRECISION.toNumber(),
+							bid_size: 2_000_000,
+						},
+					],
+				},
+				1_000_000
+			);
+
+			expect(liquidity?.size).toBe(2);
+		});
+
+		it('returns undefined when no levels were competitive', () => {
+			expect(
+				getCompetitiveLiquidity(
+					'mm-5',
+					{
+						marketIndex: 0,
+						marketType: 'perp',
+						oraclePrice: 100,
+					},
+					'long',
+					100,
+					{
+						ts: 1710000000000,
+						quotes: [
+							{
+								bid_price: 99 * PRICE_PRECISION.toNumber(),
+								bid_size: BASE_PRECISION.toNumber(),
+							},
+						],
+					}
+				)
+			).toBeUndefined();
+		});
+	});
+
+	describe('getQuoteValueOnBook', () => {
+		it('sums quote notional on the relevant side', () => {
+			expect(
+				getQuoteValueOnBook(
+					{
+						marketIndex: 0,
+						marketType: 'perp',
+						oraclePrice: 100,
+					},
+					'long',
+					{
+						ts: 1710000000000,
+						quotes: [
+							{
+								bid_price: 101 * PRICE_PRECISION.toNumber(),
+								bid_size: BASE_PRECISION.toNumber(),
+							},
+							{
+								bid_price: 100 * PRICE_PRECISION.toNumber(),
+								bid_size: 2 * BASE_PRECISION.toNumber(),
+							},
+						],
+					}
+				)
+			).toBe(301);
+		});
+
+		it('supports oracle offset prices', () => {
+			expect(
+				getQuoteValueOnBook(
+					{
+						marketIndex: 0,
+						marketType: 'perp',
+						oraclePrice: 100,
+					},
+					'long',
+					{
+						ts: 1710000000000,
+						quotes: [
+							{
+								bid_price: PRICE_PRECISION.toNumber(),
+								bid_size: BASE_PRECISION.toNumber(),
+								is_oracle_offset: true,
+							},
+						],
+					}
+				)
+			).toBe(101);
+		});
+	});
+});