balances: expose usable amounts and prioritize non-Ethereum sources

[Makyl]

Summary

Make source funding safer and more explicit by prioritizing non-Ethereum Mayan bridge sources and exposing balances before and after native-token reservations. Delegated EOAs on Monad now retain an additional 10 MON without adding a sequential RPC wait to swap preflight.

Changes

• Order eligible Mayan bridge sources with Ethereum last, while retaining usable USD descending order within the non-Ethereum and Ethereum groups.
• Keep Mayan gas drop and swing-leg selection aligned with the new priority order.
• Add required totalBalance and usableBalance fields to public TokenBalance and ChainBalance results, with balance retained as a deprecated alias for usableBalance.
• Preserve pre-reservation native amounts through swap balance normalization; ERC-20 and bridge balances currently report matching total and usable amounts.
• On Monad (chain 143), check EIP-7702 delegation only when the user has a positive MON balance and reserve an additional 10 MON for delegated EOAs, clamped at zero.
• Run the Monad delegation-code read concurrently with representative native-fee estimation using the same public client.
• Update public documentation, bridge/swap flow documentation, type-surface coverage, balance normalization tests, and Monad reservation regression tests.

Testing

• npm run lint
• npm run typecheck
• npm test

Risk / Impact

Medium. Mayan may now consume smaller non-Ethereum balances before a larger Ethereum balance, which can change selected legs and which leg carries destination gas drop. The public balance shape gains required fields, while the existing balance field remains available as a deprecated compatibility alias. Monad native source capacity is reduced by an additional 10 MON only for delegated EOAs; delegation detection and fee estimation are concurrent, and low balances are clamped to zero. Regression coverage exercises source ordering, public type shape, total/usable normalization, delegated and undelegated Monad accounts, low-balance clamping, and concurrent RPC startup.

[vercel]

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

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