feat: add master vault by waelsy123 · Pull Request #126 · OffchainLabs/token-bridge-contracts

waelsy123 · 2025-09-29T12:52:10Z

This isolate the implementation for the master vault and its related factory and subvault.

contracts/tokenbridge/libraries/vault/MasterVault.sol

godzillaba · 2025-10-01T13:36:07Z

contracts/tokenbridge/libraries/vault/MasterVault.sol

+        if (address(oldSubVault) == address(0)) revert NoExistingSubVault();
+
+        uint256 _totalSupply = totalSupply();
+        uint256 assetReceived = oldSubVault.withdraw(oldSubVault.maxWithdraw(address(this)), address(this), address(this));


there is an edge case here - the subvault may not have enough liquidity to serve this big withdrawal all at once.

we probably need to make switching vaults more robust to those liquidity constaints.

the same could be said about depositing to the new vault, it could be such a large deposit that slippage starts to become a serious issue

we could do check whether maxWithdraw will return same amount of what master vault actually own

function withdraw(uint256 assets, address receiver, address owner) public returns (uint256 shares)

note ERC4626.withdraw returns share withdrawn not assetReceived

…tion

Make master vault upgradable

contracts/tokenbridge/libraries/vault/MasterVault.sol

* feat: access control roles * remove OwnableUpgradeable * add note about permissionless fee manager --------- Co-authored-by: Henry <11198460+godzillaba@users.noreply.github.com>

MasterVault: remove stored subvault exchange rate

MasterVault tighten rounding

contracts/tokenbridge/libraries/vault/MasterVault.sol

MasterVault storage packing

MasterVault fix setters

tests: add more scenario tests

contracts/tokenbridge/libraries/vault/MasterVault.sol

gzeoneth · 2026-01-28T19:59:29Z

contracts/tokenbridge/libraries/vault/IMasterVault.sol

+pragma solidity ^0.8.0;
+
+interface IMasterVault {
+    function setSubVault(address subVault, uint256 minSubVaultExchRateWad) external;


gzeoneth · 2026-01-28T20:02:37Z

contracts/tokenbridge/libraries/vault/MasterVault.sol

+
+    /// @dev Overridden to add EXTRA_DECIMALS to the underlying asset decimals
+    function decimals() public view override returns (uint8) {
+        return IERC20Metadata(address(asset)).decimals() + EXTRA_DECIMALS;


nit: erc20 can have no decimals

if a token has no decimals method, can we safely assume it's 18 decimals or it would default to zero?

gzeoneth · 2026-01-28T20:34:25Z

contracts/tokenbridge/libraries/vault/MasterVault.sol

+    /// @dev    Can only be called by the token bridge gateway
+    /// @param  assets The amount of underlying assets to deposit
+    /// @return shares The amount of vault shares minted to the depositor
+    function deposit(uint256 assets)


lack slippage protection

slippage will be handled by the gateway, similar to #166

gzeoneth · 2026-01-28T20:36:26Z

contracts/tokenbridge/libraries/vault/MasterVault.sol

+        uint256 totalAssetsUp = _totalAssetsLessProfit(MathUpgradeable.Rounding.Up);
+        uint256 totalAssetsDown = _totalAssetsLessProfit(MathUpgradeable.Rounding.Down);


maybe we should also allocate profit?

i'm indifferent, but i guess it is more capital efficient that way

contracts/tokenbridge/libraries/vault/MasterVault.sol

gzeoneth · 2026-01-28T20:40:47Z

contracts/tokenbridge/libraries/vault/MasterVault.sol

+            asset.safeTransfer(beneficiary, amountToTransfer);
+        }
+        if (amountToWithdraw > 0) {
+            subVault.withdraw(amountToWithdraw, beneficiary, address(this));


this does not check withdrawal limit with preview, might revert, should allow partial withdrawal
same applies to other subvault withdraw

gzeoneth · 2026-01-28T20:41:55Z

contracts/tokenbridge/libraries/vault/MasterVault.sol

+                    false, withdrawAmount, desiredWithdraw, minimumRebalanceAmount
+                );
+            }
+            subVault.withdraw(withdrawAmount, address(this), address(this));


dangerous no slippage protection rebalance, can be sandwiched

we used to have an exchange rate based slippage here. I'll reintroduce one

I believe if we use exchange rate approach then keeper can't be permissionless

gzeoneth · 2026-01-28T20:42:11Z

contracts/tokenbridge/libraries/vault/MasterVault.sol

+                    true, depositAmount, desiredDeposit, minimumRebalanceAmount
+                );
+            }
+            subVault.deposit(depositAmount, address(this));


dangerous no slippage protection rebalance, can be sandwiched

contracts/tokenbridge/libraries/vault/MasterVault.sol

+    function rebalance() external whenNotPaused nonReentrant onlyKeeper {
+        // Check cooldown
+        uint256 timeSinceLastRebalance = block.timestamp - lastRebalanceTime;
+        if (timeSinceLastRebalance < rebalanceCooldown) {
+            revert RebalanceCooldownNotMet(timeSinceLastRebalance, rebalanceCooldown);
+        }
+
+        uint256 totalAssetsUp = _totalAssetsLessProfit(MathUpgradeable.Rounding.Up);
+        uint256 totalAssetsDown = _totalAssetsLessProfit(MathUpgradeable.Rounding.Down);
+        uint256 idleTargetUp =
+            totalAssetsUp.mulDiv(1e18 - targetAllocationWad, 1e18, MathUpgradeable.Rounding.Up);
+        uint256 idleTargetDown =
+            totalAssetsDown.mulDiv(1e18 - targetAllocationWad, 1e18, MathUpgradeable.Rounding.Down);
+        uint256 idleBalance = asset.balanceOf(address(this));
+
+        if (idleTargetDown <= idleBalance && idleBalance <= idleTargetUp) {
+            revert TargetAllocationMet();
+        }
+
+        if (idleBalance < idleTargetDown) {
+            // we need to withdraw from subvault
+            uint256 desiredWithdraw = idleTargetDown - idleBalance;
+            uint256 maxWithdrawable = subVault.maxWithdraw(address(this));
+            uint256 withdrawAmount =
+                desiredWithdraw < maxWithdrawable ? desiredWithdraw : maxWithdrawable;
+            if (withdrawAmount < minimumRebalanceAmount) {
+                revert RebalanceAmountTooSmall(
+                    false, withdrawAmount, desiredWithdraw, minimumRebalanceAmount
+                );
+            }
+            subVault.withdraw(withdrawAmount, address(this), address(this));
+            emit Rebalanced(false, desiredWithdraw, withdrawAmount);
+        } else {
+            // we need to deposit into subvault
+            uint256 desiredDeposit = idleBalance - idleTargetUp;
+            uint256 maxDepositable = subVault.maxDeposit(address(this));
+            uint256 depositAmount =
+                desiredDeposit < maxDepositable ? desiredDeposit : maxDepositable;
+            if (depositAmount < minimumRebalanceAmount) {
+                revert RebalanceAmountTooSmall(
+                    true, depositAmount, desiredDeposit, minimumRebalanceAmount
+                );
+            }
+            asset.safeApprove(address(subVault), depositAmount);
+            subVault.deposit(depositAmount, address(this));
+            emit Rebalanced(true, desiredDeposit, depositAmount);
+        }
+
+        lastRebalanceTime = uint40(block.timestamp);
+    }


contracts/tokenbridge/libraries/vault/MasterVault.sol

+    function rebalance() external whenNotPaused nonReentrant onlyKeeper {
+        // Check cooldown
+        uint256 timeSinceLastRebalance = block.timestamp - lastRebalanceTime;
+        if (timeSinceLastRebalance < rebalanceCooldown) {
+            revert RebalanceCooldownNotMet(timeSinceLastRebalance, rebalanceCooldown);
+        }
+
+        uint256 totalAssetsUp = _totalAssetsLessProfit(MathUpgradeable.Rounding.Up);
+        uint256 totalAssetsDown = _totalAssetsLessProfit(MathUpgradeable.Rounding.Down);
+        uint256 idleTargetUp =
+            totalAssetsUp.mulDiv(1e18 - targetAllocationWad, 1e18, MathUpgradeable.Rounding.Up);
+        uint256 idleTargetDown =
+            totalAssetsDown.mulDiv(1e18 - targetAllocationWad, 1e18, MathUpgradeable.Rounding.Down);
+        uint256 idleBalance = asset.balanceOf(address(this));
+
+        if (idleTargetDown <= idleBalance && idleBalance <= idleTargetUp) {
+            revert TargetAllocationMet();
+        }
+
+        if (idleBalance < idleTargetDown) {
+            // we need to withdraw from subvault
+            uint256 desiredWithdraw = idleTargetDown - idleBalance;
+            uint256 maxWithdrawable = subVault.maxWithdraw(address(this));
+            uint256 withdrawAmount =
+                desiredWithdraw < maxWithdrawable ? desiredWithdraw : maxWithdrawable;
+            if (withdrawAmount < minimumRebalanceAmount) {
+                revert RebalanceAmountTooSmall(
+                    false, withdrawAmount, desiredWithdraw, minimumRebalanceAmount
+                );
+            }
+            subVault.withdraw(withdrawAmount, address(this), address(this));
+            emit Rebalanced(false, desiredWithdraw, withdrawAmount);
+        } else {
+            // we need to deposit into subvault
+            uint256 desiredDeposit = idleBalance - idleTargetUp;
+            uint256 maxDepositable = subVault.maxDeposit(address(this));
+            uint256 depositAmount =
+                desiredDeposit < maxDepositable ? desiredDeposit : maxDepositable;
+            if (depositAmount < minimumRebalanceAmount) {
+                revert RebalanceAmountTooSmall(
+                    true, depositAmount, desiredDeposit, minimumRebalanceAmount
+                );
+            }
+            asset.safeApprove(address(subVault), depositAmount);
+            subVault.deposit(depositAmount, address(this));
+            emit Rebalanced(true, desiredDeposit, depositAmount);
+        }
+
+        lastRebalanceTime = uint40(block.timestamp);
+    }


contracts/tokenbridge/libraries/vault/MasterVault.sol

+    function rebalance() external whenNotPaused nonReentrant onlyKeeper {
+        // Check cooldown
+        uint256 timeSinceLastRebalance = block.timestamp - lastRebalanceTime;
+        if (timeSinceLastRebalance < rebalanceCooldown) {
+            revert RebalanceCooldownNotMet(timeSinceLastRebalance, rebalanceCooldown);
+        }
+
+        uint256 totalAssetsUp = _totalAssetsLessProfit(MathUpgradeable.Rounding.Up);
+        uint256 totalAssetsDown = _totalAssetsLessProfit(MathUpgradeable.Rounding.Down);
+        uint256 idleTargetUp =
+            totalAssetsUp.mulDiv(1e18 - targetAllocationWad, 1e18, MathUpgradeable.Rounding.Up);
+        uint256 idleTargetDown =
+            totalAssetsDown.mulDiv(1e18 - targetAllocationWad, 1e18, MathUpgradeable.Rounding.Down);
+        uint256 idleBalance = asset.balanceOf(address(this));
+
+        if (idleTargetDown <= idleBalance && idleBalance <= idleTargetUp) {
+            revert TargetAllocationMet();
+        }
+
+        if (idleBalance < idleTargetDown) {
+            // we need to withdraw from subvault
+            uint256 desiredWithdraw = idleTargetDown - idleBalance;
+            uint256 maxWithdrawable = subVault.maxWithdraw(address(this));
+            uint256 withdrawAmount =
+                desiredWithdraw < maxWithdrawable ? desiredWithdraw : maxWithdrawable;
+            if (withdrawAmount < minimumRebalanceAmount) {
+                revert RebalanceAmountTooSmall(
+                    false, withdrawAmount, desiredWithdraw, minimumRebalanceAmount
+                );
+            }
+            subVault.withdraw(withdrawAmount, address(this), address(this));
+            emit Rebalanced(false, desiredWithdraw, withdrawAmount);
+        } else {
+            // we need to deposit into subvault
+            uint256 desiredDeposit = idleBalance - idleTargetUp;
+            uint256 maxDepositable = subVault.maxDeposit(address(this));
+            uint256 depositAmount =
+                desiredDeposit < maxDepositable ? desiredDeposit : maxDepositable;
+            if (depositAmount < minimumRebalanceAmount) {
+                revert RebalanceAmountTooSmall(
+                    true, depositAmount, desiredDeposit, minimumRebalanceAmount
+                );
+            }
+            asset.safeApprove(address(subVault), depositAmount);
+            subVault.deposit(depositAmount, address(this));
+            emit Rebalanced(true, desiredDeposit, depositAmount);
+        }
+
+        lastRebalanceTime = uint40(block.timestamp);
+    }


feat: add master vault

951c33c

cla-bot bot added the cla-signed label Sep 29, 2025

github-advanced-security bot found potential problems Sep 29, 2025

View reviewed changes

contracts/tokenbridge/libraries/vault/MasterVault.sol Fixed Show fixed Hide fixed

permission withdraw performence fees

fc89964

waelsy123 force-pushed the wa/master-vault-isolated branch from 590a713 to fc89964 Compare September 30, 2025 13:43

godzillaba marked this pull request as draft October 1, 2025 13:33

godzillaba reviewed Oct 1, 2025

View reviewed changes

waelsy123 added 11 commits October 1, 2025 15:45

feat: make master vault beacon upgradable

7922536

fixup! feat: make master vault beacon upgradable

6331e7a

satisify slither

5632d3d

remove unnecessary checks

2b8f151

fixup! feat: make master vault beacon upgradable

5348604

fix: set subvault in between depsoit and _subVaultExchRateWad calcula…

3a24b45

…tion

fixup! feat: make master vault beacon upgradable

db0feb1

fixup! feat: make master vault beacon upgradable

1e0c267

fix: remove not used beacon address from storage

4aad0dd

fixup! feat: make master vault beacon upgradable

9ff2c39

feat: make master vault upgradable

e9d49e5

Make master vault upgradable

github-advanced-security bot found potential problems Oct 22, 2025

View reviewed changes

contracts/tokenbridge/libraries/vault/MasterVault.sol Fixed Show fixed Hide fixed

contracts/tokenbridge/libraries/vault/MasterVault.sol Fixed Show fixed Hide fixed

contracts/tokenbridge/libraries/vault/MasterVault.sol Fixed Show fixed Hide fixed

github-advanced-security bot found potential problems Nov 6, 2025

View reviewed changes

contracts/tokenbridge/libraries/vault/MasterVault.sol Fixed Show fixed Hide fixed

waelsy123 force-pushed the wa/master-vault-isolated branch from fdd512f to e9d49e5 Compare November 6, 2025 14:11

waelsy123 and others added 8 commits November 7, 2025 09:35

feat: access control roles (#132)

cd1a25d

* feat: access control roles * remove OwnableUpgradeable * add note about permissionless fee manager --------- Co-authored-by: Henry <11198460+godzillaba@users.noreply.github.com>

add MasterVault contract natspec

72956ed

remove subVaultExchRateWad

35c2a3c

remove unused errors

9b4809c

remove switchSubVault

a05eddc

Merge branch 'ha/mv-remove-switch-func' into ha/mv-docs

fc74ddd

role comment

302d590

Merge pull request #133 from OffchainLabs/ha/mv-remove-stored-exch-rate

bd1dffb

MasterVault: remove stored subvault exchange rate

waelsy123 and others added 3 commits January 15, 2026 20:16

Merge pull request #162 from OffchainLabs/ha/safer-principal-tracking

610870c

Merge pull request #161 from OffchainLabs/ha/mv-docs

a3db478

Merge pull request #160 from OffchainLabs/ha/mv-tighten-rounding

f89d010

MasterVault tighten rounding

github-advanced-security bot found potential problems Jan 15, 2026

View reviewed changes

contracts/tokenbridge/libraries/vault/MasterVault.sol Fixed Show fixed Hide fixed

contracts/tokenbridge/libraries/vault/MasterVault.sol Fixed Show fixed Hide fixed

contracts/tokenbridge/libraries/vault/MasterVault.sol Fixed Show fixed Hide fixed

godzillaba and others added 17 commits January 15, 2026 13:16

pack storage

85a27b1

Merge branch 'wa/master-vault-isolated' into ha/mv-storage-packing

e336fbe

fmt

7de28e9

update comment

3866f91

add error PerformanceFeeUnchanged

33b0506

improve docs, create constants, add minimum cooldown

0ededc8

Merge pull request #164 from OffchainLabs/ha/mv-storage-packing

9372ad8

MasterVault storage packing

... or sublinear previewDeposit

db943e6

Merge pull request #165 from OffchainLabs/ha/mv-fix-setters

3ac7d1e

MasterVault fix setters

test: fix master vault core tests

650cc76

set principalPriceWad to 1e18 when vault hold no assets yet

592ea0e

add virtual asset

057cb5f

fix +1 virtual asset comments

603d26d

Merge pull request #168 from OffchainLabs/fix/init-principalPriceWad

5f365a6

Merge pull request #167 from OffchainLabs/ybb/tests

339356a

tests: add more scenario tests

e7b8835

Merge pull request #170 from OffchainLabs/ybb/more-tests2

6740ad5

tests: add more scenario tests

waelsy123 marked this pull request as ready for review January 22, 2026 21:26

waelsy123 requested a review from gzeoneth January 22, 2026 21:26

gzeoneth requested changes Jan 28, 2026

View reviewed changes

waelsy123 and others added 4 commits January 29, 2026 14:11

fix: keeper can be address(0)

3eacbce

fix: implement IMasterVault interface

2fb5df2

fix: approve assets to subvault only during the deposit

b8d2e36

Merge pull request #171 from OffchainLabs/fix/keeper-address-zero

32f2e22

github-advanced-security bot found potential problems Jan 30, 2026

View reviewed changes

waelsy123 mentioned this pull request Feb 8, 2026

feat: yield bearing bridge #177

Open

		uint256 totalAssetsUp = _totalAssetsLessProfit(MathUpgradeable.Rounding.Up);
		uint256 totalAssetsDown = _totalAssetsLessProfit(MathUpgradeable.Rounding.Down);

Conversation

waelsy123 commented Sep 29, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

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!

Check warning

Check warning

Check warning

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants