@pear-protocol/exchanges-sdk 0.6.0 → 0.6.1

package/dist/client/hyperliquid/rest.js

@@ -25,6 +25,9 @@ async function fetchClearinghouseState(user, dex, demo = false) {
 async function fetchUserAbstraction(user, demo = false) {
   return fetchInfo({ type: "userAbstraction", user }, demo);
 }
+async function fetchUserRole(user, demo = false) {
+  return fetchInfo({ type: "userRole", user }, demo);
+}
 async function fetchSpotClearinghouseState(user, demo = false) {
   return fetchInfo({ type: "spotClearinghouseState", user }, demo);
 }
@@ -32,4 +35,4 @@ async function fetchActiveAssetData(user, coin, demo = false) {
   return fetchInfo({ type: "activeAssetData", user, coin }, demo);
 }
 
-export { fetchActiveAssetData, fetchClearinghouseState, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction };
+export { fetchActiveAssetData, fetchClearinghouseState, fetchInfo, fetchPerpDexs, fetchSpotClearinghouseState, fetchUserAbstraction, fetchUserRole };

package/dist/helper/hyperliquid/helper.js

@@ -1,7 +1,17 @@
-import { fetchInfo } from '../../client/hyperliquid/rest';
+import { fetchInfo, fetchUserRole } from '../../client/hyperliquid/rest';
 
 function createHyperliquidHelper(demo = false) {
   return {
+    /**
+     * Checks that the address holds a Hyperliquid account, which the exchange only creates on the
+     * first deposit. This is account existence alone — builder-fee approval, Pear trade-account
+     * setup, and agent approval stay separate gates. A failed request throws rather than reporting
+     * an inactive account, so callers never mistake an outage for a user who has to deposit.
+     */
+    async checkAccountActivation(userAddress) {
+      const role = await fetchUserRole(userAddress, demo);
+      return role.role !== "missing";
+    },
     /** Checks that the requested API wallet exists and has not expired. */
     async checkApiWallet(params) {
       const agents = await fetchInfo(

package/dist/helper/hyperliquid/helper.test.js

@@ -1,14 +1,41 @@
 import { vi, describe, beforeEach, it, expect } from 'vitest';
 import { createHyperliquidHelper } from './helper';
 
-const { fetchInfoMock } = vi.hoisted(() => ({ fetchInfoMock: vi.fn() }));
-vi.mock("../../client/hyperliquid/rest", () => ({ fetchInfo: fetchInfoMock }));
+const { fetchInfoMock, fetchUserRoleMock } = vi.hoisted(() => ({
+  fetchInfoMock: vi.fn(),
+  fetchUserRoleMock: vi.fn()
+}));
+vi.mock("../../client/hyperliquid/rest", () => ({ fetchInfo: fetchInfoMock, fetchUserRole: fetchUserRoleMock }));
 const userAddress = "0x1111111111111111111111111111111111111111";
 const agentWalletAddress = "0x2222222222222222222222222222222222222222";
 const builderAddress = "0x3333333333333333333333333333333333333333";
+const masterAddress = "0x4444444444444444444444444444444444444444";
 describe("createHyperliquidHelper", () => {
   beforeEach(() => {
     fetchInfoMock.mockReset();
+    fetchUserRoleMock.mockReset();
+  });
+  it("reports an address Hyperliquid does not know as not activated", async () => {
+    fetchUserRoleMock.mockResolvedValue({ role: "missing" });
+    const activated = await createHyperliquidHelper(true).checkAccountActivation(userAddress);
+    expect(activated).toBe(false);
+    expect(fetchUserRoleMock).toHaveBeenCalledWith(userAddress, true);
+  });
+  it.each([
+    ["user", { role: "user" }],
+    ["agent", { role: "agent", data: { user: masterAddress } }],
+    ["vault", { role: "vault" }],
+    ["subAccount", { role: "subAccount", data: { master: masterAddress } }]
+  ])("reports the %s role as activated", async (_role, response) => {
+    fetchUserRoleMock.mockResolvedValue(response);
+    await expect(createHyperliquidHelper().checkAccountActivation(userAddress)).resolves.toBe(true);
+    expect(fetchUserRoleMock).toHaveBeenCalledWith(userAddress, false);
+  });
+  it("surfaces a failed role request as an error instead of an inactive account", async () => {
+    fetchUserRoleMock.mockRejectedValue(new Error("Hyperliquid info request failed: 429"));
+    await expect(createHyperliquidHelper().checkAccountActivation(userAddress)).rejects.toThrow(
+      "Hyperliquid info request failed: 429"
+    );
   });
   it("accepts unexpired and non-expiring API wallets on the selected network", async () => {
     fetchInfoMock.mockResolvedValue([

package/dist/index.d.ts

@@ -211,6 +211,7 @@ type CreateExchangeWsConfig = {
 declare function createExchangeWs<E extends Connector>(exchange: E, config: CreateExchangeWsConfig): Promise<ExchangeWsByConnector[E]>;
 
 interface HyperliquidHelper {
+    checkAccountActivation(userAddress: `0x${string}`): Promise<boolean>;
     checkApiWallet(params: CheckApiWalletParams): Promise<boolean>;
     checkBuilderFeeApproval(userAddress: `0x${string}`, builderAddress: `0x${string}`, requiredFeeTenthsBps?: number): Promise<boolean>;
 }

package/dist/syncer/base.js

@@ -49,6 +49,7 @@ class BaseAccountSyncer {
   // Phase B: Snapshot the exchange — fetch positions and fills since the watermark.
   async snapshotExchange(state) {
     const { openPositions, provisionalFills, instruments, watermark } = state;
+    const { firstSyncStartedAt } = watermark;
     const externalFills = await this.listExternalFills({
       since: new Date(watermark.sinceMs),
       instruments,
@@ -56,12 +57,16 @@ class BaseAccountSyncer {
       provisionalFills
     });
     const exchangePositions = await this.listExternalPositions({ instruments });
-    return { exchangePositions, externalFills };
+    return {
+      exchangePositions,
+      externalFills,
+      firstSyncStartedAt
+    };
   }
   // Phase C: Compute the sync payload and post it across the three sync endpoints.
   async computeAndPostSync(state, snapshot) {
     const { openPositions, entryBySymbol, provisionalFills, watermark } = state;
-    const { exchangePositions, externalFills } = snapshot;
+    const { exchangePositions, externalFills, firstSyncStartedAt } = snapshot;
     const payload = await computeSyncPayload({
       tradeAccountId: this.account.id,
       connector: this.connector,
@@ -83,7 +88,10 @@ class BaseAccountSyncer {
       await this.sdk.core.sync.fills.confirm(payload.confirmables);
     }
     const { firstSyncTrim } = payload;
-    let meta = payload.meta;
+    let meta = {
+      ...payload.meta,
+      ...firstSyncStartedAt === void 0 ? {} : { firstSyncStartedAt }
+    };
     if (firstSyncTrim) {
       console.log(
         `${this.connector}: first-sync trim \u2014 dropped ${firstSyncTrim.trimmedCount} pre-cutoff fills (cutoffTs=${firstSyncTrim.cutoffTs})`

package/dist/syncer/base.test.js

@@ -39,7 +39,12 @@ class FakeSyncer extends BaseAccountSyncer {
 }
 function makeSyncer(args) {
   const fills = {
-    since: vi.fn().mockResolvedValue({ sinceMs: 0, neverSynced: args.neverSynced, confirmedExchangeFillIds: [] }),
+    since: vi.fn().mockResolvedValue({
+      sinceMs: 0,
+      neverSynced: args.neverSynced,
+      firstSyncStartedAt: args.neverSynced ? FIRST_SYNC_STARTED_AT : void 0,
+      confirmedExchangeFillIds: []
+    }),
     reconcile: vi.fn().mockResolvedValue({}),
     confirm: vi.fn().mockResolvedValue({}),
     create: vi.fn().mockResolvedValue({}),
@@ -64,6 +69,7 @@ function makeSyncer(args) {
   return { syncer: new FakeSyncer(config), sync };
 }
 const NEWEST_TS = 105e4;
+const FIRST_SYNC_STARTED_AT = 1e6;
 function trimmableFills(btcEraTs) {
   return [
     extFill({ exchangeFillId: "a", symbol: "BTC", side: "BUY", quantity: "1", timestamp: btcEraTs.open }),
@@ -90,6 +96,17 @@ describe("BaseAccountSyncer \u2014 first-sync plumbing", () => {
     expect(sync.fills.create).toHaveBeenCalledTimes(1);
     expect(sync.fills.create.mock.calls[0]?.[0]?.exchangePositions).toBe(SOL_SNAPSHOT);
   });
+  it("captures an empty first-sync checkpoint before fetching fills", async () => {
+    const { syncer, sync } = makeSyncer({ neverSynced: true });
+    syncer.positionsFn.mockResolvedValue([]);
+    syncer.fillsFn.mockResolvedValue([]);
+    await syncer.synchronizeFills();
+    expect(sync.fills.since.mock.invocationCallOrder[0]).toBeLessThan(syncer.fillsFn.mock.invocationCallOrder[0] ?? 0);
+    expect(sync.fills.create.mock.calls[0]?.[0]?.meta).toEqual({
+      externalMaxTs: null,
+      firstSyncStartedAt: FIRST_SYNC_STARTED_AT
+    });
+  });
   it("bumps the posted watermark past the overlap window when trimmed fills fall inside it", async () => {
     const { syncer, sync } = makeSyncer({ neverSynced: true });
     syncer.positionsFn.mockResolvedValue(SOL_SNAPSHOT);
@@ -125,7 +142,7 @@ describe("BaseAccountSyncer \u2014 first-sync plumbing", () => {
     ]);
     await syncer.synchronizeFills();
     expect(syncer.positionsFn).toHaveBeenCalledTimes(1);
-    expect(sync.fills.create.mock.calls[0]?.[0]?.meta.externalMaxTs).toBe(NEWEST_TS);
+    expect(sync.fills.create.mock.calls[0]?.[0]?.meta).toEqual({ externalMaxTs: NEWEST_TS });
     expect(logSpy).not.toHaveBeenCalled();
   });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/exchanges-sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",
@@ -28,8 +28,8 @@
   },
   "dependencies": {
     "@pear-protocol/core-sdk": "^1.12.0",
-    "@pear-protocol/types": "^1.15.0",
-    "@pear-protocol/utils": "^0.4.0",
+    "@pear-protocol/types": "^1.15.1",
+    "@pear-protocol/utils": "^0.4.1",
     "bignumber.js": "^11.1.1",
     "partysocket": "^1.0.3",
     "viem": "^2.48.8"