clamp filler output for safety

Author: royvardhan

sdk/packages/simplex/filler-config-example.toml

@@ -49,6 +49,16 @@ hyperbridgeWsUrl = ""
 # maxPriorityFeePerGasBumpPercent = 8   # Percentage added to gasPrice for priority fee (default: 8)
 # maxFeePerGasBumpPercent = 10          # Percentage added to gasPrice for max fee (default: 10)
 
+# Overfill protection (optional)
+# Bounds per-leg loss when internal pricing is wrong (bug, stale cache, manipulated venue).
+# The filler clamps its computed output to at most (1 + maxOverfillBps) × user-requested amount.
+# After `maxConsecutiveClamps` consecutive orders where the clamp activated, the strategy
+# halts itself — likely a systemic pricing error — and requires operator restart.
+# If not provided, defaults will be used (maxOverfillBps = 100, maxConsecutiveClamps = 3)
+# [simplex.overfillProtection]
+# maxOverfillBps = 100          # 1% ceiling above user-requested output (default: 100)
+# maxConsecutiveClamps = 3      # Halt threshold (default: 3)
+
 
 # Logging level: trace, debug, info, warn, error
 logging = "debug"
@@ -90,7 +100,7 @@ triggerPercentage = 0.5
 type = "basic"
 # Filler BPS (basis points) curve based on order value
 # Uses polynomial interpolation to create a smooth curve through all points
-# - Small orders: Higher BPS to make filling worthwhile  
+# - Small orders: Higher BPS to make filling worthwhile
 # - Large orders: Lower BPS to be more competitive
 bpsCurve = [
     { amount = "100", value = 100 },      # $100 orders: 1% margin
@@ -99,6 +109,52 @@ bpsCurve = [
     { amount = "100000", value = 10 },    # $100000 orders: 0.1% margin
 ]
 
+# Per-chain confirmation policies for this strategy (optional).
+# Uses polynomial interpolation to create a smooth curve through all points.
+# The chain ID should match the numeric ID from the chain configuration.
+# Sensible defaults are merged in for chains you don't list (ETH, BSC, Polygon, Base, Arbitrum).
+[strategies.confirmationPolicies."1"]  # Ethereum Mainnet
+points = [
+    { amount = "5", value = 3 },
+    { amount = "500", value = 6 },
+    { amount = "5000", value = 12 },
+]
+
+[strategies.confirmationPolicies."56"]  # BSC Mainnet
+points = [
+    { amount = "1", value = 3 },
+    { amount = "500", value = 6 },
+    { amount = "5000", value = 15 },
+]
+
+[strategies.confirmationPolicies."42161"]  # Arbitrum Mainnet
+points = [
+    { amount = "2", value = 2 },
+    { amount = "1000", value = 5 },
+    { amount = "8000", value = 10 },
+]
+
+[strategies.confirmationPolicies."8453"]  # Base Mainnet
+points = [
+    { amount = "2", value = 2 },
+    { amount = "1000", value = 5 },
+    { amount = "8000", value = 10 },
+]
+
+[strategies.confirmationPolicies."137"]  # Polygon Mainnet
+points = [
+    { amount = "2", value = 2 },
+    { amount = "1000", value = 5 },
+    { amount = "8000", value = 10 },
+]
+
+[strategies.confirmationPolicies."130"]  # Unichain Mainnet
+points = [
+    { amount = "2", value = 2 },
+    { amount = "1000", value = 5 },
+    { amount = "8000", value = 10 },
+]
+
 # HyperFX strategy for exotic token swaps (e.g. stablecoin <-> cNGN)
 # Uncomment and configure to enable
 # [[strategies]]
@@ -164,66 +220,3 @@ rpcUrl = ""      # Unichain Mainnet
 bundlerUrl = ""
 
 
-# Confirmation policies per chain
-# Uses polynomial interpolation to create a smooth curve through all points
-# The chain ID should match the numeric ID from the chain configuration
-
-[confirmationPolicies."97"]  # BSC Testnet
-points = [
-    { amount = "1", value = 1 },
-    { amount = "1000", value = 5 },
-]
-
-[confirmationPolicies."10200"]  # Gnosis Chiado
-points = [
-    { amount = "1", value = 1 },
-    { amount = "1000", value = 5 },
-]
-
-[confirmationPolicies."1"]  # Ethereum Mainnet
-points = [
-    { amount = "5", value = 3 },
-    { amount = "500", value = 6 },
-    { amount = "5000", value = 12 },
-]
-
-[confirmationPolicies."56"]  # BSC Mainnet
-points = [
-    { amount = "1", value = 3 },
-    { amount = "500", value = 6 },
-    { amount = "5000", value = 15 },
-]
-
-[confirmationPolicies."11155111"]  # Sepolia
-points = [
-    { amount = "1", value = 1 },
-    { amount = "1000", value = 5 },
-]
-
-[confirmationPolicies."42161"]  # Arbitrum Mainnet
-points = [
-    { amount = "2", value = 2 },
-    { amount = "1000", value = 5 },
-    { amount = "8000", value = 10 },
-]
-
-[confirmationPolicies."8453"]  # Base Mainnet
-points = [
-    { amount = "2", value = 2 },
-    { amount = "1000", value = 5 },
-    { amount = "8000", value = 10 },
-]
-
-[confirmationPolicies."137"]  # Polygon Mainnet
-points = [
-    { amount = "2", value = 2 },
-    { amount = "1000", value = 5 },
-    { amount = "8000", value = 10 },
-]
-
-[confirmationPolicies."130"]  # Unichain Mainnet
-points = [
-    { amount = "2", value = 2 },
-    { amount = "1000", value = 5 },
-    { amount = "8000", value = 10 },
-]

sdk/packages/simplex/src/bin/simplex.ts

@@ -170,6 +170,16 @@ interface FillerTomlConfig {
 		solverAccountContractAddress?: string
 		/** Target gas units for EntryPoint deposits per chain. Defaults to 3,000,000. */
 		targetGasUnits?: number
+		/** Gas fee bump (percentages added to base gasPrice). Defaults: priority=8%, max=10%. */
+		gasFeeBump?: {
+			maxPriorityFeePerGasBumpPercent?: number
+			maxFeePerGasBumpPercent?: number
+		}
+		/** Overfill protection knobs. Defaults: maxOverfillBps=100, maxConsecutiveClamps=3. */
+		overfillProtection?: {
+			maxOverfillBps?: number
+			maxConsecutiveClamps?: number
+		}
 	}
 	strategies: StrategyConfig[]
 	chains: UserProvidedChainConfig[]
@@ -232,6 +242,8 @@ program
 				dataDir: options.dataDir,
 				rebalancing: config.rebalancing,
 				targetGasUnits: config.simplex.targetGasUnits,
+				gasFeeBump: config.simplex.gasFeeBump,
+				overfillProtection: config.simplex.overfillProtection,
 			}
 
 			const configService = new FillerConfigService(resolvedChains, fillerConfigForService)

sdk/packages/simplex/src/services/FillerConfigService.ts

@@ -57,6 +57,13 @@ export interface RebalancingConfig {
 	}
 }
 
+export interface OverfillProtectionConfig {
+	/** Ceiling bps above user-requested output; filler clamps its computed output to this. Default 100 (1%). */
+	maxOverfillBps?: number
+	/** Consecutive clamped evaluations before the strategy halts itself. Default 3. */
+	maxConsecutiveClamps?: number
+}
+
 export interface FillerConfig {
 	maxConcurrentOrders: number
 	logging?: LogLevel
@@ -75,6 +82,11 @@ export interface FillerConfig {
 	 * Defaults to 3,000,000 if not set.
 	 */
 	targetGasUnits?: number
+	/**
+	 * Overfill protection knobs. If omitted, defaults are used
+	 * (maxOverfillBps=100, maxConsecutiveClamps=3).
+	 */
+	overfillProtection?: OverfillProtectionConfig
 }
 
 /**
@@ -364,4 +376,14 @@ export class FillerConfigService {
 	getTargetGasUnits(): bigint {
 		return BigInt(this.fillerConfig?.targetGasUnits ?? 3_000_000)
 	}
+
+	/** Ceiling bps above user-requested output. Default 100 (1%). */
+	getMaxOverfillBps(): bigint {
+		return BigInt(this.fillerConfig?.overfillProtection?.maxOverfillBps ?? 100)
+	}
+
+	/** Consecutive clamped evaluations before the strategy halts. Default 3. */
+	getMaxConsecutiveClamps(): number {
+		return this.fillerConfig?.overfillProtection?.maxConsecutiveClamps ?? 3
+	}
 }

sdk/packages/simplex/src/strategies/basic.ts

@@ -27,6 +27,14 @@ export class BasicFiller implements FillerStrategy {
 	private bpsPolicy: FillerBpsPolicy
 	private signer: SigningAccount
 	private logger = getLogger("basic-simplex")
+	/** Consecutive orders where overfill clamp activated. Reset on a clean evaluation. */
+	private consecutiveClamps = 0
+	/** Once set, the filler refuses all orders until restart — likely systemic pricing error. */
+	private halted = false
+	/** Ceiling bps above user-requested output. Sourced from filler config. */
+	private readonly maxOverfillBps: bigint
+	/** Consecutive clamped evaluations before halting. Sourced from filler config. */
+	private readonly maxConsecutiveClamps: number
 	confirmationPolicy: { getConfirmationBlocks: (chainId: number, amountUsd: number) => number }
 
 	constructor(
@@ -46,6 +54,8 @@ export class BasicFiller implements FillerStrategy {
 				confirmationPolicy.getConfirmationBlocks(chainId, new Decimal(amountUsd)),
 		}
 		this.signer = signer
+		this.maxOverfillBps = configService.getMaxOverfillBps()
+		this.maxConsecutiveClamps = configService.getMaxConsecutiveClamps()
 	}
 
 	/**
@@ -55,6 +65,10 @@ export class BasicFiller implements FillerStrategy {
 	 * @returns True if the strategy can fill the order
 	 */
 	async canFill(order: Order): Promise<boolean> {
+		if (this.halted) {
+			this.logger.warn({ orderId: order.id }, "BasicFiller halted — rejecting order")
+			return false
+		}
 		try {
 			// Validate basic structure
 			if (order.inputs.length === 0 || order.inputs.length !== order.output.assets.length) {
@@ -127,6 +141,10 @@ export class BasicFiller implements FillerStrategy {
 	 * @returns The profit in USD (Number), or 0 if not profitable or output amounts don't meet minimum
 	 */
 	async calculateProfitability(order: Order): Promise<number> {
+		if (this.halted) {
+			this.logger.warn({ orderId: order.id }, "BasicFiller halted — rejecting order")
+			return 0
+		}
 		try {
 			const { decimals: destFeeTokenDecimals } = await this.contractService.getFeeTokenWithDecimals(
 				order.destination,
@@ -212,6 +230,7 @@ export class BasicFiller implements FillerStrategy {
 		const basisPoints = 10000n
 		let totalProfitNormalized = 0n
 		const fillerOutputs: TokenInfo[] = []
+		let anyLegClamped = false
 
 		for (let i = 0; i < order.inputs.length; i++) {
 			const input = order.inputs[i]
@@ -228,17 +247,17 @@ export class BasicFiller implements FillerStrategy {
 
 			// Calculate max output filler will provide based on their bps
 			// Formula: inputAmount * (10000 - fillerBps) / 10000
-			const fillerMaxOutput = (convertedInputAmount * (basisPoints - fillerBps)) / basisPoints
+			const bpsOutput = (convertedInputAmount * (basisPoints - fillerBps)) / basisPoints
 
 			// Reject if user expects more than filler can provide
-			if (output.amount > fillerMaxOutput) {
+			if (output.amount > bpsOutput) {
 				this.logger.debug(
 					{
 						index: i,
 						inputAmount: input.amount.toString(),
 						inputDecimals,
 						userExpects: output.amount.toString(),
-						fillerWillProvide: fillerMaxOutput.toString(),
+						fillerWillProvide: bpsOutput.toString(),
 						outputDecimals,
 						fillerBps: fillerBps.toString(),
 					},
@@ -247,6 +266,25 @@ export class BasicFiller implements FillerStrategy {
 				return { isValid: false, profitFromSlippage: 0n }
 			}
 
+			// Clamp to at most (1 + maxOverfillBps) × user-requested to bound loss on pricing errors.
+			const overfillCeiling = (output.amount * (10000n + this.maxOverfillBps)) / 10000n
+			let fillerMaxOutput = bpsOutput
+			if (bpsOutput > overfillCeiling) {
+				this.logger.warn(
+					{
+						orderId: order.id,
+						index: i,
+						userRequested: output.amount.toString(),
+						unclamped: bpsOutput.toString(),
+						clamped: overfillCeiling.toString(),
+						maxOverfillBps: this.maxOverfillBps.toString(),
+					},
+					"Overfill clamp activated",
+				)
+				fillerMaxOutput = overfillCeiling
+				anyLegClamped = true
+			}
+
 			// Store the filler's calculated output for this token
 			fillerOutputs.push({
 				token: output.token,
@@ -262,6 +300,8 @@ export class BasicFiller implements FillerStrategy {
 			totalProfitNormalized += profitNormalized
 		}
 
+		this.recordOrderOutcome(anyLegClamped, order.id)
+
 		// Cache filler outputs for use during order execution
 		this.contractService.cacheService.setFillerOutputs(order.id!, fillerOutputs)
 		this.logger.debug(
@@ -275,6 +315,26 @@ export class BasicFiller implements FillerStrategy {
 		return { isValid: true, profitFromSlippage: totalProfitNormalized }
 	}
 
+	/**
+	 * Update consecutive-clamp counter after a successful order evaluation.
+	 * Halts the filler if maxConsecutiveClamps is reached — a pattern that strongly
+	 * suggests a systemic pricing bug rather than benign one-off over-provision.
+	 */
+	private recordOrderOutcome(clamped: boolean, orderId: string | undefined) {
+		if (clamped) {
+			this.consecutiveClamps += 1
+			if (this.consecutiveClamps >= this.maxConsecutiveClamps) {
+				this.halted = true
+				this.logger.error(
+					{ orderId, consecutiveClamps: this.consecutiveClamps, maxConsecutiveClamps: this.maxConsecutiveClamps },
+					"BasicFiller HALTED — overfill clamp triggered consecutively; restart required after investigation",
+				)
+			}
+		} else {
+			this.consecutiveClamps = 0
+		}
+	}
+
 	/**
 	 * Executes the order fill.
 	 * If hyperbridge is provided, submits a bid (solver selection mode).