chore: Refactor USDH Refiller to be more configurable #2800

dijanin-brat · 2025-12-04T14:58:59Z

We want to make USDH Refiller more configurable so it can top-up address on HyperEVM with USDH based on balances on both origin and destination chains.

dijanin-brat · 2025-12-04T15:09:38Z

src/refiller/RefillerConfig.ts

    }

    // Default minimum is 10 USDH. USDH only exists on HyperEVM and has 6 decimals.
    this.minUsdhRebalanceAmount = toBNWei(MIN_USDH_REBALANCE_AMOUNT ?? "10", 6);


I would maybe even prefer to move MIN_USDH_REBALANCE_AMOUNT to REFILL_BALANCES object level and we will be able to decide if we should check origin or destination balances based on this and not checkOriginChainBalance
wdyt?

Yeah, that's not a bad idea 👍

dijanin-brat · 2025-12-08T12:14:34Z

Before merging this PR, we should first update bot-configs

pxrl · 2025-12-09T14:03:07Z

src/refiller/Refiller.ts

+      this.logger.debug({
+        at: "Refiller#refillUsdh",
+        message: "Checking destination chain (HyperEVM) USDH balance",
+        destinationChainBalance: formatUnits(currentBalance, decimals),
+        triggerThreshold: formatUnits(triggerThreshold, decimals),
+        targetThreshold: formatUnits(targetThreshold, decimals),
+        shouldRefill,
+      });
+
+      // Early exit if destination chain balance is above trigger
+      if (!shouldRefill) {
+        this.logger.debug({
+          at: "Refiller#refillUsdh",
+          message: "Destination chain balance above trigger, skipping transfer",
+          destinationChainBalance: formatUnits(currentBalance, decimals),
+          triggerThreshold: formatUnits(triggerThreshold, decimals),
+        });
+        return;
+      }


I think it probably only makes sense to emit one of these messages, not both (i.e. in the case of !shouldRefill.

src/refiller/Refiller.ts

pxrl

A couple of minor questions - hopefully easy to resolve these so we can get this merged soon 👍

pxrl · 2025-12-12T14:41:05Z

src/refiller/Refiller.ts

-        message: "Rebalanced Arbitrum USDC to HyperEVM USDH",
-        nonMulticall: true,
-        mrkdwn: `Sent ${formatUnits(amountToTransfer, decimals)} USDC from Arbitrum to HyperEVM.`,
+    const originChainBalance = await usdc.balanceOf(this.baseSignerAddress.toNative());


Should this be accountAddress instead? (Based on line ~410 it seems like they should be interchangeable). Does it make sense for us to assert equality on accountAddress and this.baseSignerAddress.toNative() ?

We should check for USDC balance on Arbitrum for signer address (address from where we are sending funds) and that can be different them accountAddress (destination address where we are sending funds)

pxrl · 2025-12-12T14:43:33Z

src/refiller/Refiller.ts

+    const accountAddress = account.toNative();
+
+    // Early exit check: If checking destination chain balance, verify it's below trigger
+    if (!checkOriginChainBalance && currentBalance.gt(triggerThreshold)) {


Could we simplify the checkOriginChainBalance logic by always checking it, and enforcing the minimum rebalance amount, but defaulting that amount to 0? Then we can increase that limit when we want to impose a minimum, and otherwise it'd effectively revert to always rebalancing.

hmm, i don't see a big point for that one. We have 2 modes here:

We will send everything we have on origin if the balance is greater than amount X we specified

We will look for trigger amount on dst chain and if its below we want to refill it up to target amount

I don't really see anything meaningful in always rebalancing (specifically bcs this should be used either to top-up USDH relayer or to refill DB that we want to do manually)

Ah, I understand now. I think we've ended in a situation where we've mixed two things:

Rebalancing implementaiton of how to rebalance Arbitrum USDC -> HyperEVM USDH.

Business logic that determines when we want to rebalance, of which we have two sub cases:

Destination chain balance is under threshold.

Origin chain balance is over threshold.

The 2nd one is what we're currently using, and the 1st one is what we're aiming to enable here.

Interesting, the "origin balance over threshold" one is reminiscent of what we do with the InventoryClient, where we pull back funds from Spoke to Hub when we're over balance.

In any case, the thing that triggers me a bit is the need to add an extra variable to unlock this case. I think the place we ultimately want to end up in, is that we separate the decision-making/business logic from the underlying implementation of how we rebalance.

Not sure if we can get there in the time horizon for this PR, though. wdyt?

pxrl · 2025-12-12T14:46:03Z

src/refiller/Refiller.ts

+        minThreshold: formatUnits(this.config.minUsdhRebalanceAmount, decimals),
+        amountToTransfer: formatUnits(amountToTransfer, decimals),
+      });
+      return null;


What if we returned { usdc, amountToTransfer: bnZero, accountAddress } in this case? it's arguably simpler wherever this is used, because the caller only needs to check for amountToTransfer.gt(bnZero).

i am okey with that. Currently we are sending null so we can check if refillData exists, and if not we do an early exit. But we can change that to checking for amountToTransfer.gt(bnZero) here

Both approaches are fine with me tbh.

pxrl · 2026-01-09T12:14:33Z

src/refiller/Refiller.ts

+    const triggerThreshold = parseUnits(trigger.toString(), decimals);
+    const targetThreshold = parseUnits(target.toString(), decimals);
+    const accountAddress = account.toNative();
+
+    // Early exit check: If checking destination chain balance, verify it's below trigger
+    if (!checkOriginChainBalance && currentBalance.gt(triggerThreshold)) {


If we expect trigger and target to have the same scale, and we're only checking them relative to one another, do we actually need to normalise them by decimals , or can we just compare them directly?

We can compare them directly, but we are calculating how much should we transfer like this
const deficit = targetThreshold.sub(currentBalance);

So we will need targetThreshold normalized by decimals

pxrl · 2026-01-09T12:22:01Z

src/refiller/Refiller.ts

+    const accountAddress = account.toNative();
+
+    // Early exit check: If checking destination chain balance, verify it's below trigger
+    if (!checkOriginChainBalance && currentBalance.gt(triggerThreshold)) {


Ah, I understand now. I think we've ended in a situation where we've mixed two things:

Rebalancing implementaiton of how to rebalance Arbitrum USDC -> HyperEVM USDH.

Business logic that determines when we want to rebalance, of which we have two sub cases:

Destination chain balance is under threshold.

Origin chain balance is over threshold.

The 2nd one is what we're currently using, and the 1st one is what we're aiming to enable here.

Interesting, the "origin balance over threshold" one is reminiscent of what we do with the InventoryClient, where we pull back funds from Spoke to Hub when we're over balance.

In any case, the thing that triggers me a bit is the need to add an extra variable to unlock this case. I think the place we ultimately want to end up in, is that we separate the decision-making/business logic from the underlying implementation of how we rebalance.

Not sure if we can get there in the time horizon for this PR, though. wdyt?

chore: Refactor USDH Refiller to be more configurable

8655d5b

dijanin-brat self-assigned this Dec 4, 2025

dijanin-brat added the do not merge Don't merge until label is removed label Dec 4, 2025

dijanin-brat and others added 3 commits December 4, 2025 15:59

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

498d536

change message

02cc515

fix message

e67780c

dijanin-brat commented Dec 4, 2025

View reviewed changes

dijanin-brat and others added 3 commits December 5, 2025 10:33

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

1261af0

Fix amountToSend calculation

355f2df

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

aac034b

dijanin-brat marked this pull request as ready for review December 5, 2025 15:21

dijanin-brat requested review from bmzig, dohaki, mrice32, nicholaspai and pxrl as code owners December 5, 2025 15:21

dijanin-brat removed the do not merge Don't merge until label is removed label Dec 5, 2025

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

c7ee95f

dijanin-brat added the do not merge Don't merge until label is removed label Dec 8, 2025

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

51f71bf

pxrl reviewed Dec 9, 2025

View reviewed changes

dijanin-brat and others added 4 commits December 10, 2025 11:33

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

5e7e3b0

Refactor refillUsdh

036a8f7

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

2e54e96

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

200e609

pxrl reviewed Dec 12, 2025

View reviewed changes

dijanin-brat added 2 commits January 8, 2026 10:35

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

515b4ad

Merge branch 'master' into dijanin-brat/refactorUsdhRefiller

301322b

pxrl reviewed Jan 9, 2026

View reviewed changes

chore: Refactor USDH Refiller to be more configurable #2800

Are you sure you want to change the base?

chore: Refactor USDH Refiller to be more configurable #2800

Uh oh!

Conversation

dijanin-brat commented Dec 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dijanin-brat commented Dec 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pxrl left a comment

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants