@pear-protocol/exchanges-sdk 0.2.0 → 0.4.0

package/dist/syncer/hyperliquid/syncer.test.js

@@ -0,0 +1,274 @@
+import { vi, describe, beforeEach, it, expect } from 'vitest';
+import { HyperliquidAccountSyncer } from './syncer';
+
+const { fetchInfoMock } = vi.hoisted(() => ({ fetchInfoMock: vi.fn() }));
+vi.mock("../../client/hyperliquid/rest", () => ({ fetchInfo: fetchInfoMock }));
+const account = {
+  exchangeIdentifier: "0x1111111111111111111111111111111111111111"
+};
+const instrument = {
+  id: "HL-BTC",
+  base: "BTC"
+};
+function rawFill(time, tid = time) {
+  return {
+    coin: "BTC",
+    px: "100000",
+    sz: "0.1",
+    side: "B",
+    time,
+    startPosition: "0",
+    dir: "Open Long",
+    closedPnl: "0",
+    hash: "0xabc",
+    oid: 123,
+    crossed: true,
+    fee: "1",
+    builderFee: "0.2",
+    tid,
+    feeToken: "USDC",
+    twapId: null
+  };
+}
+function createSyncer() {
+  return new HyperliquidAccountSyncer({
+    sdk: {},
+    connector: "hyperliquid",
+    account,
+    credentials: { signer_key: "sk" },
+    demo: true
+  });
+}
+describe("HyperliquidAccountSyncer fill mapping", () => {
+  beforeEach(() => {
+    fetchInfoMock.mockReset().mockImplementation(async (body) => {
+      if (body.type === "userTwapSliceFillsByTime") {
+        return [];
+      }
+      return [
+        {
+          coin: "BTC",
+          px: "100000",
+          sz: "0.1",
+          side: "B",
+          time: 17e11,
+          startPosition: "0",
+          dir: "Open Long",
+          closedPnl: "0",
+          hash: "0xabc",
+          oid: 123,
+          crossed: true,
+          fee: "1",
+          builderFee: "0.2",
+          tid: 456,
+          feeToken: "USDC",
+          twapId: null
+        }
+      ];
+    });
+  });
+  it("uses a globally unique identity, excludes builder fee from trade fee, and routes to testnet", async () => {
+    const syncer = createSyncer();
+    const fills = await syncer.listExternalFills({
+      since: /* @__PURE__ */ new Date(1699999e6),
+      instruments: [instrument],
+      openPositions: [],
+      provisionalFills: []
+    });
+    expect(fills).toEqual([
+      expect.objectContaining({
+        exchangeFillId: "1700000000000:BTC:456",
+        tradeFee: "0.8",
+        builderFee: "0.2"
+      })
+    ]);
+    expect(fetchInfoMock).toHaveBeenCalledWith(expect.objectContaining({ type: "userFillsByTime" }), true);
+    expect(fetchInfoMock).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "userFillsByTime", aggregateByTime: false }),
+      true
+    );
+    expect(fetchInfoMock).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "userTwapSliceFillsByTime", aggregateByTime: false }),
+      true
+    );
+  });
+  it("fails closed when a maker rebate cannot satisfy the backend external-fill fee contract", async () => {
+    fetchInfoMock.mockImplementation(async (body) => {
+      if (body.type === "userTwapSliceFillsByTime") return [];
+      return [
+        {
+          coin: "BTC",
+          px: "100000",
+          sz: "0.1",
+          side: "B",
+          time: 17e11,
+          startPosition: "0",
+          dir: "Open Long",
+          closedPnl: "0",
+          hash: "0xabc",
+          oid: 123,
+          crossed: false,
+          fee: "-0.08",
+          builderFee: "0.02",
+          tid: 456,
+          feeToken: "USDC",
+          twapId: null
+        }
+      ];
+    });
+    const syncer = createSyncer();
+    await expect(
+      syncer.listExternalFills({
+        since: /* @__PURE__ */ new Date(1699999e6),
+        instruments: [instrument],
+        openPositions: [],
+        provisionalFills: []
+      })
+    ).rejects.toThrow(
+      "Hyperliquid fill 1700000000000:BTC:456 has a negative net trade fee (-0.1); the backend external-fill contract does not accept Hyperliquid rebates."
+    );
+  });
+  it("warns when inclusive fill pagination cannot move past the current timestamp", async () => {
+    const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => void 0);
+    const event = {
+      coin: "BTC",
+      px: "100000",
+      sz: "0.1",
+      side: "B",
+      time: 1e3,
+      startPosition: "0",
+      dir: "Open Long",
+      closedPnl: "0",
+      hash: "0xabc",
+      oid: 123,
+      crossed: true,
+      fee: "1",
+      builderFee: "0.2",
+      tid: 456,
+      feeToken: "USDC",
+      twapId: null
+    };
+    fetchInfoMock.mockImplementation(
+      async (body) => body.type === "userFillsByTime" ? Array.from({ length: 2e3 }, () => event) : []
+    );
+    const syncer = createSyncer();
+    await syncer.listExternalFills({
+      since: /* @__PURE__ */ new Date(1e3),
+      instruments: [instrument],
+      openPositions: [],
+      provisionalFills: []
+    });
+    expect(consoleWarn).toHaveBeenCalledWith(
+      "Hyperliquid fills pagination stalled at timestamp 1000; returned history may be incomplete."
+    );
+    expect(fetchInfoMock).toHaveBeenCalledTimes(2);
+    consoleWarn.mockRestore();
+  });
+  it("counts raw fills before rejecting history older than the 10,000-fill retention boundary", async () => {
+    let page = 0;
+    fetchInfoMock.mockImplementation(async (body) => {
+      if (body.type !== "userFillsByTime") return [];
+      const firstTime = 1e3 + page * 2e3;
+      page += 1;
+      return Array.from({ length: 2e3 }, (_, index) => rawFill(firstTime + index));
+    });
+    const syncer = createSyncer();
+    await expect(
+      syncer.listExternalFills({
+        since: /* @__PURE__ */ new Date(0),
+        instruments: [instrument],
+        openPositions: [],
+        provisionalFills: []
+      })
+    ).rejects.toThrow(
+      "Hyperliquid fill history is incomplete: requested since 0 predates oldest reachable fill 1000 within the 10000-fill retention limit."
+    );
+    expect(fetchInfoMock).toHaveBeenCalledTimes(5);
+    expect(fetchInfoMock).toHaveBeenCalledWith(expect.objectContaining({ aggregateByTime: false }), true);
+  });
+  it("accepts a request exactly at the oldest reachable fill at the retention boundary", async () => {
+    let page = 0;
+    fetchInfoMock.mockImplementation(async (body) => {
+      if (body.type === "userTwapSliceFillsByTime") return [];
+      if (page >= 5) return [];
+      const firstTime = 1e3 + page * 2e3;
+      page += 1;
+      return Array.from({ length: 2e3 }, (_, index) => rawFill(firstTime + index));
+    });
+    const syncer = createSyncer();
+    const fills = await syncer.listExternalFills({
+      since: /* @__PURE__ */ new Date(1e3),
+      instruments: [instrument],
+      openPositions: [],
+      provisionalFills: []
+    });
+    expect(fills).toHaveLength(1e4);
+    expect(fetchInfoMock).toHaveBeenCalledTimes(7);
+  });
+});
+describe("HyperliquidAccountSyncer position and funding snapshots", () => {
+  beforeEach(() => {
+    fetchInfoMock.mockReset();
+  });
+  it("de-duplicates DEX descriptors and derives mark price from current position value", async () => {
+    fetchInfoMock.mockImplementation(async (body) => {
+      if (body.type === "perpDexs") return [null, null, { name: "xyz" }];
+      if (body.type === "clearinghouseState" && body.dex === "") {
+        return {
+          assetPositions: [
+            {
+              position: {
+                coin: "BTC",
+                szi: "2",
+                entryPx: "150",
+                positionValue: "400"
+              }
+            }
+          ]
+        };
+      }
+      if (body.type === "clearinghouseState") return { assetPositions: [] };
+      throw new Error(`Unexpected request: ${body.type}`);
+    });
+    const syncer = createSyncer();
+    const positions = await syncer.listExternalPositions({
+      instruments: [
+        {
+          ...instrument,
+          precision: { quantity: { contractSize: 1 } }
+        }
+      ]
+    });
+    expect(positions).toEqual([
+      expect.objectContaining({ symbol: "HL-BTC", size: "2", entryPrice: "150", markPrice: "200" })
+    ]);
+    expect(fetchInfoMock).toHaveBeenCalledTimes(3);
+  });
+  it("de-duplicates an inclusive funding boundary and stops when its cursor cannot advance", async () => {
+    const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => void 0);
+    const event = {
+      time: 1e3,
+      hash: "0xabc",
+      delta: {
+        type: "funding",
+        coin: "BTC",
+        usdc: "-2",
+        szi: "4",
+        fundingRate: "0.0001",
+        nSamples: null
+      }
+    };
+    fetchInfoMock.mockResolvedValue(Array.from({ length: 500 }, () => event));
+    const syncer = createSyncer();
+    const payments = await syncer.listExternalFunding({
+      since: /* @__PURE__ */ new Date(1e3),
+      instruments: [instrument]
+    });
+    expect(payments).toHaveLength(1);
+    expect(fetchInfoMock).toHaveBeenCalledTimes(1);
+    expect(consoleWarn).toHaveBeenCalledWith(
+      "Hyperliquid funding pagination stalled at timestamp 1000; returned history may be incomplete."
+    );
+    consoleWarn.mockRestore();
+  });
+});

package/dist/syncer/lighter/funding.js

@@ -0,0 +1,25 @@
+import BigNumber from 'bignumber.js';
+
+function toFundingPaymentEntries(events, instrumentIds) {
+  return events.reduce((entries, event) => {
+    const instrumentId = event.market_id.toString();
+    if (!instrumentIds.has(instrumentId)) {
+      console.warn(`Lighter market id ${event.market_id} not found in instrument id map.`);
+      return entries;
+    }
+    const unsignedSize = new BigNumber(event.position_size).abs();
+    const signedSize = event.position_side === "short" ? unsignedSize.negated() : unsignedSize;
+    const fundingPerUnit = signedSize.isZero() ? "0" : new BigNumber(event.change).div(signedSize).toFixed();
+    entries.push({
+      connector: "lighter",
+      instrumentId,
+      fundingRate: event.rate,
+      notional: event.change,
+      fundingPerUnit,
+      timestamp: event.timestamp
+    });
+    return entries;
+  }, []);
+}
+
+export { toFundingPaymentEntries };

package/dist/syncer/lighter/funding.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { toFundingPaymentEntries } from './funding';
+
+describe("Lighter funding mapping", () => {
+  it("derives funding per unit against signed long and short exposure", () => {
+    const result = toFundingPaymentEntries(
+      [
+        fundingEvent({ funding_id: 1, position_side: "long", change: "-2" }),
+        fundingEvent({ funding_id: 2, position_side: "short", change: "2" })
+      ],
+      /* @__PURE__ */ new Set(["1"])
+    );
+    expect(result).toEqual([
+      {
+        connector: "lighter",
+        instrumentId: "1",
+        fundingRate: "0.0001",
+        notional: "-2",
+        fundingPerUnit: "-0.5",
+        timestamp: 1e3
+      },
+      {
+        connector: "lighter",
+        instrumentId: "1",
+        fundingRate: "0.0001",
+        notional: "2",
+        fundingPerUnit: "-0.5",
+        timestamp: 1e3
+      }
+    ]);
+  });
+  it("skips funding for unknown instruments", () => {
+    expect(toFundingPaymentEntries([fundingEvent({})], /* @__PURE__ */ new Set())).toEqual([]);
+  });
+});
+function fundingEvent(overrides) {
+  return {
+    timestamp: 1e3,
+    market_id: 1,
+    funding_id: 1,
+    change: "-2",
+    discount: "0",
+    rate: "0.0001",
+    position_size: "4",
+    position_side: "long",
+    ...overrides
+  };
+}

package/dist/syncer/lighter/syncer.js

@@ -1,6 +1,7 @@
 import BigNumber from 'bignumber.js';
-import { fetchTradesSince } from '../../client/lighter/rest';
+import { fetchAccount, fetchTradesSince, fetchPositionFundingSince } from '../../client/lighter/rest';
 import { BaseAccountSyncer } from '../base';
+import { toFundingPaymentEntries } from './funding';
 
 const LIGHTER_FEE_TICK_DENOMINATOR = new BigNumber(1e6);
 class LighterAccountSyncer extends BaseAccountSyncer {
@@ -9,84 +10,135 @@ class LighterAccountSyncer extends BaseAccountSyncer {
   apiPrivateKey;
   constructor(config) {
     super(config);
-    const creds = config.credentials;
+    const credentials = config.credentials;
     this.accountIndex = Number(config.account.exchangeIdentifier);
-    this.apiKeyIndex = creds.api_key_index;
-    this.apiPrivateKey = creds.api_private_key;
+    this.apiKeyIndex = credentials.api_key_index;
+    this.apiPrivateKey = credentials.api_private_key;
+  }
+  async listExternalPositions({
+    instruments
+  }) {
+    const contractSizeByInstrumentId = new Map(
+      instruments.map((instrument) => [instrument.id, instrument.precision.quantity.contractSize])
+    );
+    const response = await fetchAccount(this.accountIndex, this.demo);
+    const rawPositions = response.accounts?.[0]?.positions ?? [];
+    return rawPositions.reduce((positions, rawPosition) => {
+      const instrumentId = rawPosition.market_id.toString();
+      const signedSize = new BigNumber(rawPosition.position).times(rawPosition.sign);
+      if (signedSize.isZero()) return positions;
+      const contractSize = contractSizeByInstrumentId.get(instrumentId) ?? 1;
+      const size = signedSize.abs().times(contractSize).toFixed();
+      const side = rawPosition.sign === 1 ? "BUY" : "SELL";
+      const markPrice = new BigNumber(rawPosition.position_value).abs().div(size).toFixed();
+      positions.push({
+        symbol: instrumentId,
+        size,
+        side,
+        entryPrice: rawPosition.avg_entry_price,
+        markPrice
+      });
+      return positions;
+    }, []);
   }
   async listExternalFills({
     since,
     instruments
   }) {
+    this.assertAuthenticatedSyncAvailable();
     const { token } = await this.sdk.core.misc.lighter.createAuthToken({
       accountIndex: this.accountIndex,
       apiKeyIndex: this.apiKeyIndex,
       apiPrivateKey: this.apiPrivateKey
     });
-    const trades = await fetchTradesSince(this.accountIndex, token, since);
+    const trades = await fetchTradesSince(this.accountIndex, token, since, this.demo);
     const instrumentIds = new Set(instruments.map((instrument) => instrument.id));
-    return trades.toSorted((a, b) => a.timestamp - b.timestamp).reduce((acc, trade) => {
-      const instrumentId = trade.market_id.toString();
+    return trades.toSorted((a, b) => a.timestamp - b.timestamp).reduce((fills, rawFill) => {
+      const instrumentId = rawFill.market_id.toString();
       if (!instrumentIds.has(instrumentId)) {
-        console.warn(`Lighter market id ${trade.market_id} not found in instrument id map.`);
-        return acc;
+        console.warn(`Lighter market id ${rawFill.market_id} not found in instrument id map.`);
+        return fills;
       }
-      const accountSide = this.getAccountSide(trade);
-      if (!accountSide) return acc;
+      const accountSide = this.getAccountSide(rawFill);
+      if (!accountSide) return fills;
       const side = accountSide === "ask" ? "SELL" : "BUY";
-      acc.push({
+      fills.push({
         connector: "lighter",
-        exchangeFillId: trade.trade_id_str ?? trade.trade_id.toString(),
-        cloid: this.getClientOrderId(trade, accountSide),
+        exchangeFillId: rawFill.trade_id_str ?? rawFill.trade_id.toString(),
+        cloid: this.getClientOrderId(rawFill, accountSide),
         symbol: instrumentId,
-        price: trade.price,
-        quantity: trade.size,
+        price: rawFill.price,
+        quantity: rawFill.size,
         side,
-        reduceOnly: this.isReduceOnly(trade),
-        timestamp: trade.timestamp,
-        tradeFee: this.getTradeFee(trade, accountSide),
-        builderFee: this.getIntegratorFee(trade, accountSide),
-        liquidation: trade.type === "liquidation" ? { mark: trade.price } : null
+        reduceOnly: this.isReduceOnly(rawFill),
+        timestamp: rawFill.timestamp,
+        tradeFee: this.getTradeFee(rawFill, accountSide),
+        builderFee: this.getIntegratorFee(rawFill, accountSide),
+        liquidation: rawFill.type === "liquidation" ? { mark: rawFill.price } : null
       });
-      return acc;
+      return fills;
     }, []);
   }
-  isReduceOnly(trade) {
-    if (trade.type === "liquidation" || trade.type === "deleverage" || trade.type === "market-settlement") {
+  async listExternalFunding({
+    since,
+    instruments
+  }) {
+    this.assertAuthenticatedSyncAvailable();
+    const { token } = await this.sdk.core.misc.lighter.createAuthToken({
+      accountIndex: this.accountIndex,
+      apiKeyIndex: this.apiKeyIndex,
+      apiPrivateKey: this.apiPrivateKey
+    });
+    const fundingEvents = await fetchPositionFundingSince(this.accountIndex, token, since, this.demo);
+    const instrumentIds = new Set(instruments.map((instrument) => instrument.id));
+    return toFundingPaymentEntries(fundingEvents, instrumentIds);
+  }
+  isReduceOnly(rawFill) {
+    if (rawFill.type === "liquidation" || rawFill.type === "deleverage" || rawFill.type === "market-settlement") {
       return true;
     }
-    const accountSide = this.getAccountSide(trade);
+    const accountSide = this.getAccountSide(rawFill);
     if (!accountSide) {
       return false;
     }
-    const positionSizeBefore = this.getPositionSizeBefore(trade, accountSide);
+    const positionSignChanged = this.isMaker(rawFill, accountSide) ? rawFill.maker_position_sign_changed : rawFill.taker_position_sign_changed;
+    if (positionSignChanged) {
+      return false;
+    }
+    const positionSizeBefore = this.getPositionSizeBefore(rawFill, accountSide);
     if (positionSizeBefore.isZero()) {
       return false;
     }
     return positionSizeBefore.isPositive() && accountSide === "ask" || positionSizeBefore.isNegative() && accountSide === "bid";
   }
-  getAccountSide(trade) {
-    if (trade.ask_account_id === this.accountIndex) return "ask";
-    if (trade.bid_account_id === this.accountIndex) return "bid";
+  getAccountSide(rawFill) {
+    if (rawFill.ask_account_id === this.accountIndex) return "ask";
+    if (rawFill.bid_account_id === this.accountIndex) return "bid";
     return null;
   }
-  getClientOrderId(trade, side) {
-    return (side === "ask" ? trade.ask_client_id_str : trade.bid_client_id_str) || null;
+  getClientOrderId(rawFill, side) {
+    return (side === "ask" ? rawFill.ask_client_id_str : rawFill.bid_client_id_str) || null;
   }
-  isMaker(trade, side) {
-    return side === "ask" ? trade.is_maker_ask : !trade.is_maker_ask;
+  isMaker(rawFill, side) {
+    return side === "ask" ? rawFill.is_maker_ask : !rawFill.is_maker_ask;
   }
-  getPositionSizeBefore(trade, side) {
-    const value = this.isMaker(trade, side) ? trade.maker_position_size_before : trade.taker_position_size_before;
+  getPositionSizeBefore(rawFill, side) {
+    const value = this.isMaker(rawFill, side) ? rawFill.maker_position_size_before : rawFill.taker_position_size_before;
     return new BigNumber(value ?? 0);
   }
-  getTradeFee(trade, side) {
-    const rateTick = this.isMaker(trade, side) ? trade.maker_fee : trade.taker_fee;
-    return this.feeTickToAmount(rateTick, trade.usd_amount);
+  getTradeFee(rawFill, side) {
+    const rateTick = this.isMaker(rawFill, side) ? rawFill.maker_fee : rawFill.taker_fee;
+    return this.feeTickToAmount(rateTick, rawFill.usd_amount);
   }
-  getIntegratorFee(trade, side) {
-    const rateTick = this.isMaker(trade, side) ? trade.integrator_maker_fee : trade.integrator_taker_fee;
-    return this.feeTickToAmount(rateTick, trade.usd_amount);
+  getIntegratorFee(rawFill, side) {
+    const rateTick = this.isMaker(rawFill, side) ? rawFill.integrator_maker_fee : rawFill.integrator_taker_fee;
+    return this.feeTickToAmount(rateTick, rawFill.usd_amount);
+  }
+  /** Prevents testnet reads from silently minting a mainnet auth token. */
+  assertAuthenticatedSyncAvailable() {
+    if (this.demo) {
+      throw new Error("Lighter demo authenticated sync is unavailable because backend signing is mainnet-only");
+    }
   }
   // Lighter fees come as ppm rates (÷1e6), not amounts — the charged fee is that rate times the trade's USD notional.
   feeTickToAmount(rateTick, usdAmount) {