fix: address review feedback on validation, errors, and native token address

- Correct native token sentinel to the 40-char EIP-55 address (fixes 2 failing tests)
- Throw ZeroExValidationError from the constructor and for exact-in/exact-out
  validation (neither/both amounts) via a shared _assertExactlyOneAmount helper
- Guard swidge against illiquid routes after /quote
- Align defaultSlippage JSDoc and swidge @throws with actual behavior
- Expand test coverage: exact-out/slippage min-amount fallbacks, transaction
  revert and timeout errors, and the api-client apiKey guard (85% -> 93%)
- Ignore generated coverage/ output

Author: jlin27

.gitignore

@@ -1,5 +1,6 @@
 node_modules/
 types/
+coverage/
 *.log
 .env
 .DS_Store

README.md

@@ -135,7 +135,7 @@ Call `getSupportedChains()` to retrieve the full list at runtime.
 
 The 0x Swap API accepts **any liquid ERC-20 token by contract address**. There is no supported token list — `getSupportedTokens()` throws `NotImplementedError`. Pass token addresses directly to `quoteSwidge` and `swidge`.
 
-For native ETH (or any chain's native token) as a **buy token**, use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeeeE` or the alias `'native'`. Selling native ETH is not supported by the AllowanceHolder flow — wrap to WETH first.
+For native ETH (or any chain's native token) as a **buy token**, use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` or the alias `'native'`. Selling native ETH is not supported by the AllowanceHolder flow — wrap to WETH first.
 
 ---
 

src/0x-protocol.js

@@ -40,15 +40,15 @@ import { ZeroExFeeLimitExceededError, ZeroExInsufficientLiquidityError, ZeroExRe
  * @property {number | string} chainId - The EVM chain ID of the bound wallet account. Required.
  * @property {string} apiKey - The 0x API key. Required.
  * @property {string} [baseUrl] - The 0x API base URL. Defaults to 'https://api.0x.org'.
- * @property {number} [defaultSlippage] - Default slippage tolerance as a decimal (e.g. 0.005 = 0.5%). Defaults to 0.005.
+ * @property {number} [defaultSlippage] - Default slippage tolerance as a decimal (e.g. 0.005 = 0.5%). If omitted, no slippage parameter is sent and the 0x API default applies.
  * @property {boolean} [skipApproval] - Skip automatic ERC-20 approval before executing a swap.
  * @property {number | bigint} [maxNetworkFeeBps] - Maximum acceptable network fee in basis points of the input amount.
  * @property {number | bigint} [maxProtocolFeeBps] - Maximum acceptable protocol fee in basis points of the input amount.
  */
 
 // 0x uses this checksummed sentinel for native ETH / chain native token.
 // Must use the EIP-55 checksummed form — the 0x API rejects the all-lowercase variant.
-const NATIVE_TOKEN_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeeeE'
+const NATIVE_TOKEN_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
 const NATIVE_TOKEN_ADDRESS_LOWER = NATIVE_TOKEN_ADDRESS.toLowerCase()
 
 // Identifiers callers may pass to mean "native token"
@@ -120,10 +120,10 @@ export default class ZeroExProtocol extends SwidgeProtocol {
     super(account, config)
 
     if (!config.apiKey) {
-      throw new Error('ZeroExProtocol requires config.apiKey.')
+      throw new ZeroExValidationError('ZeroExProtocol requires config.apiKey.')
     }
     if (config.chainId == null) {
-      throw new Error('ZeroExProtocol requires config.chainId identifying the EVM chain of the bound account.')
+      throw new ZeroExValidationError('ZeroExProtocol requires config.chainId identifying the EVM chain of the bound account.')
     }
 
     /**
@@ -153,9 +153,7 @@ export default class ZeroExProtocol extends SwidgeProtocol {
    * @throws {ZeroExInsufficientLiquidityError} If no route is available.
    */
   async quoteSwidge (options) {
-    if (options.fromTokenAmount == null && options.toTokenAmount == null) {
-      throw new ZeroExValidationError('Either fromTokenAmount (exact-in) or toTokenAmount (exact-out) must be provided.')
-    }
+    this._assertExactlyOneAmount(options)
 
     const chainId = Number(this._config.chainId)
 
@@ -231,7 +229,7 @@ export default class ZeroExProtocol extends SwidgeProtocol {
    * @param {SwidgeOptions} options
    * @param {SwidgeProtocolConfig} [config] - Per-call overrides for fee caps.
    * @returns {Promise<SwidgeResult>}
-   * @throws {Error} If no full account was provided at construction.
+   * @throws {ZeroExReadOnlyError} If no full account was provided at construction.
    * @throws {ZeroExFeeLimitExceededError} If a fee cap is exceeded.
    */
   async swidge (options, config) {
@@ -246,6 +244,8 @@ export default class ZeroExProtocol extends SwidgeProtocol {
         `Cross-chain bridging is not supported. toChain (${options.toChain}) must match the configured chainId (${chainId}).`
       )
     }
+    this._assertExactlyOneAmount(options)
+
     const sellToken = this._normalizeToken(options.fromToken)
     const buyToken = this._normalizeToken(options.toToken)
     const taker = await this._account.getAddress()
@@ -269,6 +269,10 @@ export default class ZeroExProtocol extends SwidgeProtocol {
 
     const quote = await this._api.quote(chainId, params)
 
+    if (!quote.liquidityAvailable) {
+      throw new ZeroExInsufficientLiquidityError({ sellToken, buyToken, chainId })
+    }
+
     this._checkFeeLimits(quote, sellToken, config)
 
     const sellAmount = BigInt(quote.sellAmount)
@@ -405,6 +409,25 @@ export default class ZeroExProtocol extends SwidgeProtocol {
   // Protected helpers
   // ---------------------------------------------------------------------------
 
+  /**
+   * Asserts that exactly one of fromTokenAmount (exact-in) or toTokenAmount
+   * (exact-out) is provided.
+   *
+   * @protected
+   * @param {SwidgeOptions} options
+   * @throws {ZeroExValidationError} If neither or both amounts are provided.
+   */
+  _assertExactlyOneAmount (options) {
+    const hasIn = options.fromTokenAmount != null
+    const hasOut = options.toTokenAmount != null
+    if (!hasIn && !hasOut) {
+      throw new ZeroExValidationError('Either fromTokenAmount (exact-in) or toTokenAmount (exact-out) must be provided.')
+    }
+    if (hasIn && hasOut) {
+      throw new ZeroExValidationError('Provide either fromTokenAmount (exact-in) or toTokenAmount (exact-out), not both.')
+    }
+  }
+
   /**
    * Resolves the taker address from the bound account or the options recipient.
    *

tests/0x-protocol.test.js

@@ -1,7 +1,8 @@
 import { beforeEach, describe, expect, jest, test } from '@jest/globals'
 
 import ZeroExProtocol from '../index.js'
-import { ZeroExApiError, ZeroExFeeLimitExceededError, ZeroExInsufficientLiquidityError, ZeroExReadOnlyError } from '../src/errors.js'
+import ZeroExApiClient from '../src/api-client.js'
+import { ZeroExApiError, ZeroExFeeLimitExceededError, ZeroExInsufficientLiquidityError, ZeroExReadOnlyError, ZeroExValidationError, ZeroExTransactionRevertedError, ZeroExTimeoutError } from '../src/errors.js'
 import { NotImplementedError } from '@tetherto/wdk-wallet'
 
 const BASE_URL = 'https://api.0x.org'
@@ -178,6 +179,12 @@ describe('ZeroExProtocol', () => {
       ).rejects.toThrow()
     })
 
+    test('throws when both fromTokenAmount and toTokenAmount given', async () => {
+      await expect(
+        protocol.quoteSwidge({ fromToken: USDC, toToken: WETH, fromTokenAmount: 1n, toTokenAmount: 1n })
+      ).rejects.toThrow(ZeroExValidationError)
+    })
+
     test('throws when toChain differs from configured chainId', async () => {
       await expect(
         protocol.quoteSwidge({ fromToken: USDC, toToken: WETH, fromTokenAmount: 1n, toChain: 42161 })
@@ -191,6 +198,34 @@ describe('ZeroExProtocol', () => {
       ).resolves.toBeDefined()
     })
 
+    test('derives toTokenAmountMin from slippage when minBuyAmount is absent (exact-in)', async () => {
+      const { minBuyAmount, ...noMin } = PRICE_RESPONSE
+      global.fetch = mockFetch({ '/swap/allowance-holder/price': noMin })
+
+      const quote = await protocol.quoteSwidge({
+        fromToken: USDC,
+        toToken: WETH,
+        fromTokenAmount: 100000000n,
+        slippage: 0.01
+      })
+
+      expect(quote.toTokenAmountMin > 0n).toBe(true)
+      expect(quote.toTokenAmountMin < quote.toTokenAmount).toBe(true)
+    })
+
+    test('sets toTokenAmountMin to the requested amount for exact-out without minBuyAmount', async () => {
+      const { minBuyAmount, ...noMin } = PRICE_RESPONSE
+      global.fetch = mockFetch({ '/swap/allowance-holder/price': noMin })
+
+      const quote = await protocol.quoteSwidge({
+        fromToken: USDC,
+        toToken: WETH,
+        toTokenAmount: 500000000000000n
+      })
+
+      expect(quote.toTokenAmountMin).toBe(500000000000000n)
+    })
+
     test('wraps 0x API errors', async () => {
       global.fetch = mockFetch({
         '/swap/allowance-holder/price': {
@@ -209,7 +244,7 @@ describe('ZeroExProtocol', () => {
 
       const call = global.fetch.mock.calls[0][0]
       expect(new URL(call).searchParams.get('sellToken')).toBe(
-        '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
+        '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'
       )
     })
   })
@@ -286,6 +321,42 @@ describe('ZeroExProtocol', () => {
       ).rejects.toThrow('Cross-chain bridging is not supported')
     })
 
+    test('throws when both fromTokenAmount and toTokenAmount given', async () => {
+      await expect(
+        protocol.swidge({ fromToken: USDC, toToken: WETH, fromTokenAmount: 1n, toTokenAmount: 1n })
+      ).rejects.toThrow(ZeroExValidationError)
+    })
+
+    test('throws ZeroExInsufficientLiquidityError when quote has no liquidity', async () => {
+      global.fetch = mockFetch({
+        '/swap/allowance-holder/quote': { ...QUOTE_RESPONSE, liquidityAvailable: false }
+      })
+
+      await expect(
+        protocol.swidge({ fromToken: USDC, toToken: WETH, fromTokenAmount: 100000000n })
+      ).rejects.toThrow(ZeroExInsufficientLiquidityError)
+
+      expect(account.sendTransaction).not.toHaveBeenCalled()
+    })
+
+    test('throws ZeroExTransactionRevertedError when the approval tx reverts', async () => {
+      account.getTransactionReceipt.mockResolvedValue({ status: 0 })
+
+      await expect(
+        protocol.swidge({ fromToken: USDC, toToken: WETH, fromTokenAmount: 100000000n })
+      ).rejects.toThrow(ZeroExTransactionRevertedError)
+
+      expect(account.sendTransaction).not.toHaveBeenCalled()
+    })
+
+    test('_waitForReceipt throws ZeroExTimeoutError when no receipt appears before the deadline', async () => {
+      const acc = { getTransactionReceipt: jest.fn(async () => null) }
+
+      await expect(
+        protocol._waitForReceipt(acc, '0xdeadbeef', { intervalMs: 1, timeoutMs: 5 })
+      ).rejects.toThrow(ZeroExTimeoutError)
+    })
+
     test('throws ZeroExReadOnlyError when no account is bound', async () => {
       const p = new ZeroExProtocol(undefined, { chainId: 1, apiKey: 'key' })
       await expect(
@@ -493,3 +564,9 @@ describe('ZeroExProtocol', () => {
     })
   })
 })
+
+describe('ZeroExApiClient', () => {
+  test('throws without an apiKey', () => {
+    expect(() => new ZeroExApiClient({})).toThrow('apiKey')
+  })
+})