Merge pull request #274 from Polymarket/fix/dev-398-perps-order-update-race

fix(client): prevent perps order update race

Author: cesarenaldi

.changeset/perps-order-update-race.md

@@ -0,0 +1,5 @@
+---
+"@polymarket/client": patch
+---
+
+Prevent Perps `placeOrder` from missing private order updates that arrive before the command acknowledgement. High-level placement now generates a client order ID when callers omit it.

AGENTS.md

@@ -60,6 +60,7 @@
 ## Platform Invariants
 
 - A market's minimum tick size may become finer, such as `0.01` to `0.001`, but it cannot become coarser, such as `0.001` to `0.01`. SDK caching and recovery logic may rely on this monotonic behavior and should not add defensive handling for tick-size coarsening.
+- When a Perps order is submitted with a client order ID, every corresponding private order update echoes that same client order ID. SDK order-placement workflows may rely on this invariant for pre-acknowledgement correlation.
 
 ## TypeScript config
 

packages/client/src/websockets/perps/actions/trading.test.ts

@@ -3,7 +3,7 @@ import { PerpsTimeInForce } from '@polymarket/bindings/perps';
 import { describe, expect, it } from 'vitest';
 import { createPerpsOpTypedDataPayload } from '../signing';
 import {
-  type PerpsTradingTransport,
+  type PerpsCommandExecutor,
   postPerpsOrders,
   toPerpsCommandBodyOp,
   updatePerpsMargin,
@@ -17,8 +17,8 @@ const UPDATE_MARGIN_DATA_HASH =
 describe('Perps trading actions', () => {
   describe('createPerpsOpTypedDataPayload', () => {
     it('signs entry orders with backend-compatible createOrders bytes', async () => {
-      const transport: PerpsTradingTransport = {
-        async sendSignedWsCommand(request) {
+      const client: PerpsCommandExecutor = {
+        async executeCommand(request, responseSchema) {
           const payload = createPerpsOpTypedDataPayload({
             chainId: 31_337,
             op: request.op,
@@ -45,12 +45,12 @@ describe('Perps trading actions', () => {
             type: 'createOrders',
           });
 
-          return request.responseSchema.parse([{ oid: 123, status: 'ok' }]);
+          return responseSchema.parse([{ oid: 123, status: 'ok' }]);
         },
       };
 
       await expect(
-        postPerpsOrders(transport, {
+        postPerpsOrders(client, {
           orders: [
             {
               instrumentId: 1,
@@ -66,8 +66,8 @@ describe('Perps trading actions', () => {
     });
 
     it('serializes reduce-only entry orders', async () => {
-      const transport: PerpsTradingTransport = {
-        async sendSignedWsCommand(request) {
+      const client: PerpsCommandExecutor = {
+        async executeCommand(request, responseSchema) {
           expect(toPerpsCommandBodyOp(request.op)).toEqual({
             args: [
               {
@@ -83,12 +83,12 @@ describe('Perps trading actions', () => {
             type: 'createOrders',
           });
 
-          return request.responseSchema.parse([{ oid: 123, status: 'ok' }]);
+          return responseSchema.parse([{ oid: 123, status: 'ok' }]);
         },
       };
 
       await expect(
-        postPerpsOrders(transport, {
+        postPerpsOrders(client, {
           orders: [
             {
               instrumentId: 1,
@@ -104,8 +104,8 @@ describe('Perps trading actions', () => {
     });
 
     it('signs isolated margin adjustments with backend-compatible bytes', async () => {
-      const transport: PerpsTradingTransport = {
-        async sendSignedWsCommand(request) {
+      const client: PerpsCommandExecutor = {
+        async executeCommand(request, responseSchema) {
           const payload = createPerpsOpTypedDataPayload({
             chainId: 31_337,
             op: request.op,
@@ -126,12 +126,12 @@ describe('Perps trading actions', () => {
             type: 'updateMargin',
           });
 
-          return request.responseSchema.parse({ status: 'ok' });
+          return responseSchema.parse({ status: 'ok' });
         },
       };
 
       await expect(
-        updatePerpsMargin(transport, {
+        updatePerpsMargin(client, {
           amount: '-1234567890.123456789012345678',
           instrumentId: 7,
         }),