fix, test: circuit breaker param (#647)

* fix, test: circuit breaker param

* test: simplify

* test: sanity check unimind constant params

* test: fix build

* test: update Unimind config checks to Zod

Author: alanhwu

lib/util/constants.ts

@@ -1,5 +1,6 @@
 import { ChainId } from './chain'
 import { BigNumber } from 'ethers'
+import { z } from 'zod'
 
 export const WEBHOOK_CONFIG_BUCKET = 'order-webhook-notification-config'
 export const PRODUCTION_WEBHOOK_CONFIG_KEY = 'production.json'
@@ -46,8 +47,9 @@ export const DEFAULT_UNIMIND_PARAMETERS = JSON.stringify({
 export const UNIMIND_UPDATE_THRESHOLD = 25
 export const UNIMIND_CIRCUIT_BREAKER_MAX_BATCH = 5 // Circuit breaker active for batches 0-5
 export const UNIMIND_CIRCUIT_BREAKER_MIN_ORDERS = 4 // Order count to begin checking circuit breaker
-export const UNIMIND_CIRCUIT_BREAKER_FILL_RATE_THRESHOLD = 25 // Fill rate at or below this value triggers circuit breaker
+export const UNIMIND_CIRCUIT_BREAKER_FILL_RATE_THRESHOLD = 0.25 // Fill rate at or below this value triggers circuit breaker
 export const UNIMIND_DEV_SWAPPER_ADDRESS = '0x2b813964306D8F12bdaB5504073a52e5802f049D'
+
 // Direct pi and tau to use for curve; Not intrinsicValues
 export const PUBLIC_STATIC_PARAMETERS = {
   pi: 15,
@@ -58,6 +60,25 @@ export const PUBLIC_STATIC_PARAMETERS = {
 export const UNIMIND_MAX_TAU_BPS = 25
 export const UNIMIND_LARGE_PRICE_IMPACT_THRESHOLD = 1.25 // 1.25% price impact threshold
 
+// Sanity-check unimind constants at module load time so misconfigurations fail fast.
+const UnimindConstantsSchema = z.object({
+  updateThreshold: z.number().int().positive(),
+  circuitBreakerMaxBatch: z.number().int().nonnegative(),
+  circuitBreakerMinOrders: z.number().int().positive(),
+  circuitBreakerFillRateThreshold: z.number().min(0).max(1),
+  maxTauBps: z.number().positive(),
+  devSwapperAddress: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
+})
+
+UnimindConstantsSchema.parse({
+  updateThreshold: UNIMIND_UPDATE_THRESHOLD,
+  circuitBreakerMaxBatch: UNIMIND_CIRCUIT_BREAKER_MAX_BATCH,
+  circuitBreakerMinOrders: UNIMIND_CIRCUIT_BREAKER_MIN_ORDERS,
+  circuitBreakerFillRateThreshold: UNIMIND_CIRCUIT_BREAKER_FILL_RATE_THRESHOLD,
+  maxTauBps: UNIMIND_MAX_TAU_BPS,
+  devSwapperAddress: UNIMIND_DEV_SWAPPER_ADDRESS,
+})
+
 // When pi = 0, AMM will be favored over Dutch Auction
 export const USE_CLASSIC_PARAMETERS = {
   pi: 0,

package.json

@@ -80,7 +80,8 @@
     "express": "^4.18.2",
     "joi": "^17.7.0",
     "source-map-support": "^0.5.21",
-    "uuid": "^9.0.0"
+    "uuid": "^9.0.0",
+    "zod": "3"
   },
   "prettier": {
     "printWidth": 120,

test/integ/crons/unimind-algorithm.test.ts

@@ -5,7 +5,7 @@ import { DynamoUnimindParametersRepository } from '../../../lib/repositories/uni
 import { DutchOrdersRepository } from '../../../lib/repositories/dutch-orders-repository'
 import { DutchV3OrderEntity, ORDER_STATUS } from '../../../lib/entities'
 import { OrderType } from '@uniswap/uniswapx-sdk'
-import { DEFAULT_UNIMIND_PARAMETERS, UNIMIND_ALGORITHM_VERSION, UNIMIND_DEV_SWAPPER_ADDRESS, UNIMIND_UPDATE_THRESHOLD } from '../../../lib/util/constants'
+import { DEFAULT_UNIMIND_PARAMETERS, UNIMIND_ALGORITHM_VERSION, UNIMIND_DEV_SWAPPER_ADDRESS, UNIMIND_UPDATE_THRESHOLD, UNIMIND_CIRCUIT_BREAKER_MIN_ORDERS } from '../../../lib/util/constants'
 
 const dynamoConfig = {
   convertEmptyValues: true,
@@ -281,6 +281,90 @@ describe('updateParameters Test', () => {
       expect(pairData?.lastUpdatedAt).toBeDefined()
     })
 
+    it('should not trigger circuit breaker when fill rate is above threshold', async () => {
+      const cbPair = '0xCB01-0xCB02-42161'
+      const filledOrder: DutchV3OrderEntity = {
+        ...mockOrder,
+        pair: cbPair,
+        orderStatus: ORDER_STATUS.FILLED,
+        fillBlock: 315641562,
+        cosignerData: {
+          ...mockOrder.cosignerData,
+          decayStartBlock: 315641558,
+        },
+        priceImpact: 0.5,
+        usedUnimind: true,
+      }
+
+      // Insert UNIMIND_CIRCUIT_BREAKER_MIN_ORDERS filled orders
+      const orders: DutchV3OrderEntity[] = []
+      for (let i = 0; i < UNIMIND_CIRCUIT_BREAKER_MIN_ORDERS; i++) {
+        const order = { ...filledOrder, orderHash: `0xCB_FILLED_${i}` }
+        orders.push(order)
+        await ordersTable.putOrderAndUpdateNonceTransaction(order)
+      }
+
+      // Pair exists in early batch, no orders counted yet
+      await unimindParametersRepository.put({
+        pair: cbPair,
+        intrinsicValues: DEFAULT_UNIMIND_PARAMETERS,
+        count: 0,
+        version: UNIMIND_ALGORITHM_VERSION,
+        batchNumber: 2, // Within circuit breaker window (<= 5)
+        lastUpdatedAt: Math.floor(Date.now() / 1000),
+      })
+
+      await updateParameters(unimindParametersRepository, ordersTable, log)
+
+      const pairData = await unimindParametersRepository.getByPair(cbPair)
+      // Fill rate is 1.0 (100%), well above 25% threshold — circuit breaker should NOT fire
+      expect(pairData?.batchNumber).toBe(2) // Unchanged — no update triggered
+      expect(pairData?.count).toBe(UNIMIND_CIRCUIT_BREAKER_MIN_ORDERS) // Just incremented
+
+      // Cleanup
+      await ordersTable.deleteOrders(orders.map((o) => o.orderHash))
+    })
+
+    it('should trigger circuit breaker when fill rate is below threshold', async () => {
+      const cbPair = '0xCB03-0xCB04-42161'
+      const expiredOrder: DutchV3OrderEntity = {
+        ...mockOrder,
+        pair: cbPair,
+        orderStatus: ORDER_STATUS.EXPIRED,
+        fillBlock: undefined as any,
+        priceImpact: 0.5,
+        usedUnimind: true,
+      }
+
+      // Insert UNIMIND_CIRCUIT_BREAKER_MIN_ORDERS expired orders
+      const orders: DutchV3OrderEntity[] = []
+      for (let i = 0; i < UNIMIND_CIRCUIT_BREAKER_MIN_ORDERS; i++) {
+        const order = { ...expiredOrder, orderHash: `0xCB_EXPIRED_${i}` }
+        orders.push(order)
+        await ordersTable.putOrderAndUpdateNonceTransaction(order)
+      }
+
+      // Pair exists in early batch, no orders counted yet
+      await unimindParametersRepository.put({
+        pair: cbPair,
+        intrinsicValues: DEFAULT_UNIMIND_PARAMETERS,
+        count: 0,
+        version: UNIMIND_ALGORITHM_VERSION,
+        batchNumber: 2,
+        lastUpdatedAt: Math.floor(Date.now() / 1000),
+      })
+
+      await updateParameters(unimindParametersRepository, ordersTable, log)
+
+      const pairData = await unimindParametersRepository.getByPair(cbPair)
+      // Fill rate is 0.0, below 25% threshold — circuit breaker SHOULD fire
+      expect(pairData?.batchNumber).toBe(3) // Incremented — update was triggered
+      expect(pairData?.count).toBe(0) // Reset after update
+
+      // Cleanup
+      await ordersTable.deleteOrders(orders.map((o) => o.orderHash))
+    })
+
     it('should reset batchNumber to 0 on version mismatch', async () => {
       await unimindParametersRepository.put({
         pair: testPair,

test/unit/util/unimind-constants.test.ts

@@ -0,0 +1,7 @@
+// The Zod schema in constants.ts validates unimind constants at module load time.
+// This test simply verifies the module loads without throwing.
+describe('Unimind constants sanity checks', () => {
+  it('should pass Zod validation on import', () => {
+    expect(() => require('../../../lib/util/constants')).not.toThrow()
+  })
+})

yarn.lock

@@ -9258,3 +9258,8 @@ yocto-queue@^0.1.0:
   version "0.1.0"
   resolved "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz"
   integrity sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==
+
+zod@3:
+  version "3.25.76"
+  resolved "https://registry.yarnpkg.com/zod/-/zod-3.25.76.tgz#26841c3f6fd22a6a2760e7ccb719179768471e34"
+  integrity sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==