swap: handle native balance drift and low bridge amounts

[Makyl]

Summary

Prevents an Exact-In native source from failing route reconstruction when its amount was previously calculated from the wallet balance minus reserved gas and the live balance changes before holdings are resolved again.

Insufficient-balance and bridge-fee errors now include human-readable token amounts and more useful source context. Bridge fees consuming the bridged amount are exposed separately as validation/amount_too_low so consumers can distinguish an uneconomical amount from an insufficient wallet balance.

Changes

• Skip the refreshed amountRaw > availableRaw validation for native source tokens while retaining it for ERC-20 sources.
• Include the token address and chain ID when a requested source has no usable balance.
• Include the token symbol and formatted requested and available amounts when an ERC-20 source exceeds its balance.
• Add ERROR_CODES.AMOUNT_TOO_LOW and Errors.amountTooLow(...) for routes whose bridge fees consume the bridged amount.
• Throw validation/amount_too_low with formatted bridge-fee and bridged-amount values from the standard Exact-In and fast-path routes.
• Import formatTokenBalance directly from its domain formatting module.
• Document the new public error code in the README and Nexus skill error catalog.

Testing

• npm run lint
• npm run typecheck
• npm test

Risk / Impact

• A genuinely excessive native source amount is no longer rejected by the refreshed holdings check and may fail later during transaction preparation or execution.
• ERC-20 source balance validation remains unchanged.
• Consumers that currently treat bridge fees exceeding the bridged amount as validation/insufficient_balance must handle the new validation/amount_too_low code instead.
• ERROR_CODES.AMOUNT_TOO_LOW additively extends the public ERROR_CODES object and ErrorCode union; existing codes and method signatures are unchanged.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nexus-sdk	Ready	Preview	Aug 13, 2026 1:08pm