improve: Add utility functions for inventory equivalence remapping and Binance deposit matching by nicholaspai · Pull Request #3108 · across-protocol/relayer

nicholaspai · 2026-03-25T15:38:18Z

Summary

New utility functions that support the larger inventory accounting refactor (split from #3073).

TokenUtils: getInventoryEquivalentL1TokenAddress, getInventoryBalanceContributorTokens, isL2OnlyEquivalentToken — generic resolution of L2-only tokens (pathUSD, USDH) to their inventory-equivalent L1 token via TOKEN_EQUIVALENCE_REMAPPING
RunningBalanceUtils: getLatestRunningBalances — extracted from InventoryClient for shared use by InventoryClient and Monitor
BinanceUtils: getOutstandingBinanceDeposits — pure function for matching Binance deposits against withdrawals across multiple L2s, handling batched withdrawals correctly. Exports BinanceDeposit type
BNUtils: Fix floatToBN overflow when input has many decimal digits (e.g. 5654.8610313399695 * 10^13 > MAX_SAFE_INTEGER). Also handles scientific notation for very small numbers

Upstream dependencies

None — merges directly to master.

Downstream PRs

Client layer (BundleDataApproxClient, InventoryClient, TokenClient)
Adapter layer (BaseChainAdapter, BinanceCEXBridge)
Monitor simplification

Test plan

16 new unit tests pass (BNUtils, BinanceUtils, TokenUtils)

🤖 Generated with Claude Code

…inance deposit matching, and floatToBN fix - TokenUtils: getInventoryEquivalentL1TokenAddress, getInventoryBalanceContributorTokens, isL2OnlyEquivalentToken - RunningBalanceUtils: getLatestRunningBalances extracted for shared use - BinanceUtils: getOutstandingBinanceDeposits for cross-L2 deposit matching, export BinanceDeposit type - BNUtils: Fix floatToBN MAX_SAFE_INTEGER overflow via string manipulation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

nicholaspai · 2026-03-25T15:39:42Z

src/utils/RunningBalanceUtils.ts

+ * @param bundleDataApproxClient BundleDataApproxClient for upcoming deposits/refunds.
+ * @returns Dictionary keyed by chain ID of running balance results.
+ */
+export async function getLatestRunningBalances(


Note, this is copied from InventoryClient._getLatestRunningBalances

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c7d85415a5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-25T15:42:28Z

src/utils/RunningBalanceUtils.ts

+    const upcomingDeposits = bundleDataApproxClient.getUpcomingDeposits(chainId, l1Token);
+    const upcomingRefunds = bundleDataApproxClient.getUpcomingRefunds(chainId, l1Token);
+
+    // Updated running balance is last known running balance minus deposits plus upcoming refunds.
+    const latestRunningBalance = lastValidatedRunningBalance.sub(upcomingDeposits).add(upcomingRefunds);


Convert upcoming amounts to L1 decimals before balance math

lastValidatedRunningBalance is in hub/L1 token units, but BundleDataApproxClient.getUpcomingDeposits and getUpcomingRefunds return amounts in the spoke token’s native decimals (see the existing conversion logic in InventoryClient._getLatestRunningBalances). Subtracting/adding these values directly here mis-scales running balances whenever L2 and L1 decimals differ, which can cause incorrect excess-balance calculations and repayment-chain selection.

Useful? React with 👍 / 👎.

This is a good callout, however this function isn't used in any clients in this PR and the downstream PR (#3109) fixes this and makes sure that the BundleDataApproxClient functions return values in L1 units so I don't think this is necessary

nicholaspai · 2026-03-25T15:53:19Z

@codex please respond to all unresolved comment threads

chatgpt-codex-connector · 2026-03-25T15:53:34Z

To use Codex here, create an environment for this repo.

pxrl · 2026-03-25T16:11:43Z

src/utils/BinanceUtils.ts

+  assert(
+    withdrawals.every((withdrawal) => withdrawal.network === BINANCE_NETWORKS[CHAIN_IDs.MAINNET]),
+    "Withdrawals must be for the Mainnet network"
+  );


Do we intend to constrain this to mainnet, or just t ensure that each withdrawal is for the same chainId?

Constraining to mainnet is something we'd like to avoid moving forward, since ideally we can withdraw on any chain.

I don't think this function works unless all withdrawals are to the same chain, otherwise how can we differentiate between deposits that are supposed to be withdrawn to mainnet vs another chain?

Yeah, but do we require that it's always a withdrawal to mainnet? Could we instead just verify that all withdrawal networks are equal, rather than that they are all mainnet?

pxrl · 2026-03-25T16:15:39Z

src/utils/BNUtils.ts

-  const bnAmount = BigNumber.from(Math.round(scaledAmount));
+  // Convert to a fixed-point decimal string to avoid scientific notation (e.g. "1.234e-9")
+  // that JavaScript produces for very small or very large numbers.
+  const strFloat = typeof float === "string" ? float : float.toFixed(20).replace(/0+$/, "").replace(/\.$/, "");


Is 20 decimal places significant in this context? i.e. does node switch to scientific notation beyond that, or something?

i ended up rewriting floatToBN with the help of codex here 2d70db5

src/utils/RunningBalanceUtils.ts

src/utils/TokenUtils.ts

Co-authored-by: Paul <108695806+pxrl@users.noreply.github.com>

nicholaspai · 2026-03-25T17:31:42Z

@codex

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c874c1f7e6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-25T17:36:41Z

src/utils/BNUtils.ts

+  // that JavaScript produces for very small or very large numbers. toFixed(20) is used because
+  // JavaScript's Number has ~15-17 significant digits of precision, so 20 decimal places captures
+  // everything the float can represent. Trailing zeros are stripped since they don't affect the value.
+  const strFloat = typeof float === "string" ? float : float.toFixed(20).replace(/0+$/, "").replace(/\.$/, "");


Parse numeric amounts without IEEE-754 artifact expansion

Converting number inputs with toFixed(20) bakes in binary floating-point artifacts (for example 0.3 becomes 0.29999999999999998890), and the subsequent decimal rescaling turns that artifact into token units; this makes floatToBN(0.3, 18) produce 299999999999999988 instead of 300000000000000000. Because Binance amount paths pass number values into floatToBN, this regression can under/over-count bridge amounts and cause exact-amount reconciliation failures.

Useful? React with 👍 / 👎.

Number(0.3) is already 0.29999999999999998890... in IEEE 754 — the imprecision exists before floatToBN is called. The old code had the same issue (it just happened to round correctly for simple cases via Math.round). For exact amounts, callers should pass strings (which bypass toFixed entirely). The Binance API returns numeric floats so some precision loss is inherent at the source.

nicholaspai · 2026-03-25T18:15:54Z

@codex

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2d70db5d8d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/utils/RunningBalanceUtils.ts

nicholaspai requested review from bmzig, dohaki, mrice32 and pxrl as code owners March 25, 2026 15:38

nicholaspai commented Mar 25, 2026

View reviewed changes

nicholaspai mentioned this pull request Mar 25, 2026

improve: Use inventory equivalence remapping in BundleDataApproxClient, InventoryClient, TokenClient #3109

Merged

3 tasks

chatgpt-codex-connector bot reviewed Mar 25, 2026

View reviewed changes

nicholaspai mentioned this pull request Mar 25, 2026

fix: Binance CEX pending withdrawal logic and adapter zero-amount cleanup #3110

Merged

2 tasks

Merge branch 'master' into npai/utils-token-binance-bn

6a1e0bb

nicholaspai mentioned this pull request Mar 25, 2026

refactor: Simplify Monitor balance reporting and delete TokenTransferClient #3111

Merged

4 tasks

pxrl reviewed Mar 25, 2026

View reviewed changes

nicholaspai and others added 2 commits March 25, 2026 13:23

Update src/utils/TokenUtils.ts

8f2f2c5

Co-authored-by: Paul <108695806+pxrl@users.noreply.github.com>

paul comments

3b5d034

nicholaspai requested a review from pxrl March 25, 2026 17:24

Merge branch 'master' into npai/utils-token-binance-bn

c874c1f

chatgpt-codex-connector bot reviewed Mar 25, 2026

View reviewed changes

bmzig previously approved these changes Mar 25, 2026

View reviewed changes

rewrite floatToBN

2d70db5

nicholaspai dismissed bmzig’s stale review via 2d70db5 March 25, 2026 17:51

chatgpt-codex-connector bot reviewed Mar 25, 2026

View reviewed changes

src/utils/RunningBalanceUtils.ts Show resolved Hide resolved

Merge branch 'master' into npai/utils-token-binance-bn

fea2ab6

nicholaspai merged commit df85270 into master Mar 25, 2026
1 of 2 checks passed

nicholaspai deleted the npai/utils-token-binance-bn branch March 25, 2026 21:13

Conversation

nicholaspai commented Mar 25, 2026

Summary

Upstream dependencies

Downstream PRs

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicholaspai commented Mar 25, 2026

Uh oh!

chatgpt-codex-connector bot commented Mar 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nicholaspai commented Mar 25, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicholaspai commented Mar 25, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants