Contents

• Contents
• Overview
  • TL;DR
  • Vault Bridge Token
  • Migration Manager
  • Custom Token
  • Native Converter
• Get Started
• Documentation
• Deployments
• Usage
• License

Overview

Vault Bridge enables chains and apps to generate native yield on TVL by putting bridged assets to work.

The protocol is comprised of:

• One primary chain ("Layer X")
  • Vault Bridge Token
  • Migration Manager
• Many secondary chains ("Layer Y")
  • Custom Token
  • Native Converter

TL;DR

Select assets are bridged from Layer X to Layer Y. These assets are deposited into Vault Bridge Token contract on Layer X, which mints and bridges vbToken to Layer Y. Deposited assets are used to generate yield on Layer X, while bridged vbTokens are used in DeFi on Layer Y. Generated yield gets distributed to chains and apps participating in the revenue sharing program.

Native Converter contract can be deployed on Layer Y to enable acquisition of vbToken on Layer Y without having to bridge from Layer X. Accumulated backing in Native Converter on Layer Y gets migrated to Layer X and deposited into Vault Bridge Token contract.

Vault Bridge Token

A Vault Bridge Token is:

• ERC-20 token
• ERC-4626 vault
• Unified Bridge extension

Assets in high demand with available yield strategies, such as WETH and USDC, can get their versions of vbTokens. The underlying asset is deposited into Vault Bridge Token contract, and vbToken is minted in a 1:1 ratio. The same can be withdrawn by burning vbToken. Vault Bridge Token contract doubles a pseudo bridge, so vbToken can be minted and bridged, or claimed and redeemed, in a single call. Deposited underlying assets are put into an external, ERC-4626 compatible vault ("yield vault") where they generate yield. Yield is distributed to chains and apps that participate in the revenue sharing program. Vault Bridge Token contracts also includes functionality that enables minting of vbToken directly on Layer Y via Native Converter, with backing migration to Layer X via Migration Manager.

Migration Manager

The Migration Manager is:

• Vault Bridge Token dependency

vbTokens can be minted directly on Layer Y. In order for an underlying asset that backs vbToken minted on Layer Y to be deposited in Vault Bridge Token contract on Layer X, backing is migrated to Layer X via Native Converter and Migration Manager. Migration Manager completes migrations by interacting with Vault Bridge Token contract. All vbTokens share the same Migration Manager contract.

Custom Token

A Custom Token is:

• ERC-20 token

Bridged vbToken can be upgraded to Custom Token on Layer Y. This enables custom behavior, such as bridged vbETH to integrate WETH9 interface, replacing WETH on Layer Y.

Native Converter

A Native Converter is:

• Vault Bridge Token extension
• Unified Bridge extension

Native Converter can be deployed on Layer Y to enable minting of vbToken directly on Layer Y by converting the bridged underlying asset, in a 1:1 ratio. The same can be deconverted to by burning bridged vbToken. Accumulated backing in Native Converter on Layer Y can be migrated to Layer X to be deposited into Vault Bridge Token contract via Migration Manger. For this reason, liqudity for deconverting to the bridged underlying token on Layer Y is guaranteed only up to a certain percentage. Native Converter doubles a bridge extension, so vbToken can be deconverted and bridged in a single call.

Get Started

Getting started should be easy as Vault Bridge Token contracts follow the ERC-4626 interface. Variants of the standard ERC-4626 functions include depositAndBridge and claimAndRedeem. Please see Documentation for more information.

If your chain is part of Agglayer, you can start using the official vbTokens immediately. Please note that you will get vbToken when bridging, not the underlying token, therefore activity should be incentivized in vbToken. You must participate in the revenue sharing program in order to receive yield. Contact our team if interested in revenue sharing.

If your chain is not part of Agglayer, you can start using the official vbTokens immediately. Please note that you will need to use a third-party bridge to bridge vbTokens to your chain, and Native Converter functionality will not be supported. You must participate in the revenue sharing program in order to receive yield. Contact our team if interested in revenue sharing.

Full support for non-Agglayer chains, third-party bridges, as well as non-EVM chains is coming soon. Contact our team to register interest.

Documentation

• General Documentation
• Technical Reference
• In addition to General Documentation and Technical Reference, the source code is 100% documented and you are encouraged to check it out.

Deployments

Usage

Clone:

git clone git@github.com:agglayer/vault-bridge.git

Install:

forge soldeer install & npm install

Build:

forge build

Test:

forge test

Coverage:

forge coverage --ir-minimum --report lcov && genhtml -o coverage lcov.info

License

This codebase is licensed under Source Available License.

See LICENSE-SOURCE-AVAILABLE.

Your use of this software constitutes acceptance of these license terms.

Contents

• WETH
• GenericCustomToken
• GenericNativeConverter

Contents

• WETH
• WETHNativeConverter

WETH

Git Source

Inherits: CustomToken

Author: See https://github.com/agglayer/vault-bridge

based on https://github.com/gnosis/canonical-weth/blob/master/contracts/WETH9.sol

State Variables

_WETH_STORAGE

The storage slot at which WETH storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.WETH.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _WETH_STORAGE = hex"df8caff5d0161908572492829df972cd19b1aabe3c3078d95299408cd561dc00";

Functions

constructor

constructor();

onlyNativeConverter

modifier onlyNativeConverter();

onlyIfGasTokenIsEth

modifier onlyIfGasTokenIsEth();

reinitialize

function reinitialize(
    address owner_,
    uint8 originalUnderlyingTokenDecimals_,
    address lxlyBridge_,
    address nativeConverter_
) external reinitializer(2);

_getWETHStorage

function _getWETHStorage() private pure returns (WETHStorage storage $);

bridgeBackingToLayerX

function bridgeBackingToLayerX(uint256 amount)
    external
    whenNotPaused
    onlyIfGasTokenIsEth
    onlyNativeConverter
    nonReentrant;

receive

receive() external payable whenNotPaused onlyIfGasTokenIsEth nonReentrant;

deposit

Same as WETH9 deposit function.

function deposit() external payable whenNotPaused onlyIfGasTokenIsEth nonReentrant;

_deposit

function _deposit() internal;

withdraw

Same as WETH9 withdraw function, but liqudity is guaranteed only up to a certain percentage.

function withdraw(uint256 value) external whenNotPaused onlyIfGasTokenIsEth nonReentrant;

Events

Deposit

event Deposit(address indexed from, uint256 value);

Withdrawal

event Withdrawal(address indexed to, uint256 value);

Errors

AssetsTooLarge

error AssetsTooLarge(uint256 availableAssets, uint256 requestedAssets);

FunctionNotSupportedOnThisNetwork

error FunctionNotSupportedOnThisNetwork();

Structs

WETHStorage

Storage of WETH contract.

It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions when using with upgradeable contracts.

Note: storage-location: erc7201:agglayer.vault-bridge.WETH.storage

struct WETHStorage {
    bool _gasTokenIsEth;
}

WETHNativeConverter

Git Source

Inherits: NativeConverter

Author: See https://github.com/agglayer/vault-bridge

State Variables

_WETH_NATIVE_CONVERTER_STORAGE

The storage slot at which WETHNativeConverter storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.WETHNativeConverter.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _WETH_NATIVE_CONVERTER_STORAGE =
    hex"f9565ea242552c2a1a216404344b0c8f6a3093382a21dd5bd6f5dc2ff1934d00";

Functions

onlyIfGasTokenIsEth

modifier onlyIfGasTokenIsEth();

constructor

constructor();

initialize

function initialize(
    address owner_,
    address customToken_,
    address underlyingToken_,
    address lxlyBridge_,
    uint32 layerXNetworkId_,
    uint256 nonMigratableBackingPercentage_,
    address migrationManager_,
    uint256 nonMigratableGasBackingPercentage_
) external initializer;

nonMigratableGasBackingPercentage

function nonMigratableGasBackingPercentage() public view returns (uint256);

_getWETHNativeConverterStorage

function _getWETHNativeConverterStorage() private pure returns (WETHNativeConverterStorage storage $);

migratableGasBacking

function migratableGasBacking() public view returns (uint256);

migrateGasBackingToLayerX

It is known that this can lead to WETH not being able to perform withdrawals, because of a lack of gas backing.

However, this is acceptable, because WETH is a vault backed token so its backing should actually be staked.

Users can still bridge WETH back to Layer X to receive wETH or ETH.

This special function allows the NativeConverter owner to migrate the gas backing of the WETH Custom Token

It simply takes the amount of gas token from the WETH contract

and performs the migration using a special CrossNetworkInstruction called _1_WRAP_GAS_TOKEN_AND_COMPLETE_MIGRATION

It instructs vbETH on Layer X to first wrap the gas token and then deposit it to complete the migration.

function migrateGasBackingToLayerX(uint256 amount)
    external
    whenNotPaused
    onlyIfGasTokenIsEth
    onlyRole(MIGRATOR_ROLE)
    nonReentrant;

receive

receive() external payable whenNotPaused onlyIfGasTokenIsEth;

setNonMigratableGasBackingPercentage

function setNonMigratableGasBackingPercentage(uint256 nonMigratableGasBackingPercentage_)
    external
    onlyRole(DEFAULT_ADMIN_ROLE)
    nonReentrant;

Events

NonMigratableGasBackingPercentageSet

event NonMigratableGasBackingPercentageSet(uint256 nonMigratableGasBackingPercentage_);

Errors

FunctionNotSupportedOnThisNetwork

error FunctionNotSupportedOnThisNetwork();

InvalidNonMigratableGasBackingPercentage

error InvalidNonMigratableGasBackingPercentage();

Structs

WETHNativeConverterStorage

Storage of WETHNativeConverter contract.

It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions when using with upgradeable contracts.

Note: storage-location: erc7201:agglayer.vault-bridge.WETHNativeConverter.storage

struct WETHNativeConverterStorage {
    WETH _weth;
    bool _gasTokenIsEth;
    uint256 nonMigratableGasBackingPercentage;
}

GenericCustomToken

Git Source

Inherits: CustomToken

Author: See https://github.com/agglayer/vault-bridge

This contract can be used to deploy Custom Tokens that do not require any customization.

Functions

constructor

constructor();

reinitialize

function reinitialize(
    address owner_,
    uint8 originalUnderlyingTokenDecimals_,
    address lxlyBridge_,
    address nativeConverter_
) external reinitializer(2);

GenericNativeConverter

Git Source

Inherits: NativeConverter

Author: See https://github.com/agglayer/vault-bridge

This contract can be used to deploy Native Converters that do not require any customization.

Functions

constructor

constructor();

initialize

function initialize(
    address owner_,
    address customToken_,
    address underlyingToken_,
    address lxlyBridge_,
    uint32 layerXLxlyId_,
    uint256 nonMigratableBackingPercentage_,
    address migrationManager_
) external initializer;

Contents

• ERC20PermitUser
• IBridgeMessageReceiver
• ILxLyBridge
• IVaultBridgeTokenInitializer
• IWETH9
• Versioned

ERC20PermitUser

Git Source

Author: See https://github.com/agglayer/vault-bridge

Mimics the behavior of LxLy Bridge for validating and using ERC-20 permits.

State Variables

_PERMIT_SELECTOR_ERC_2612

Calculated as bytes4(keccak256(bytes("permit(address,address,uint256,uint256,uint8,bytes32,bytes32)"))).

bytes4 private constant _PERMIT_SELECTOR_ERC_2612 = hex"d505accf";

_PERMIT_SELECTOR_DAI

bytes4 private constant _PERMIT_SELECTOR_DAI = hex"8fcbaf0c";

Functions

_permit

function _permit(address token, uint256 minimumAmount, bytes calldata permitData) internal;

Errors

InvalidOwnerInERC20Permit

error InvalidOwnerInERC20Permit(address owner, address expectedOwner);

InvalidSpenderInERC20Permit

error InvalidSpenderInERC20Permit(address spender, address expectedSpender);

InvalidAmountInERC20Permit

error InvalidAmountInERC20Permit(uint256 amount, uint256 minimumAmount);

InvalidSelectorInERC20Permit

error InvalidSelectorInERC20Permit(bytes4 selector);

IBridgeMessageReceiver

Git Source

Author: See https://github.com/agglayer/vault-bridge

Functions

onMessageReceived

function onMessageReceived(address originAddress, uint32 originNetwork, bytes memory data) external payable;

ILxLyBridge

Git Source

Author: See https://github.com/agglayer/vault-bridge

Functions

networkID

function networkID() external view returns (uint32);

gasTokenAddress

function gasTokenAddress() external view returns (address);

gasTokenNetwork

function gasTokenNetwork() external view returns (uint32);

bridgeAsset

function bridgeAsset(
    uint32 destinationNetwork,
    address destinationAddress,
    uint256 amount,
    address token,
    bool forceUpdateGlobalExitRoot,
    bytes calldata permitData
) external payable;

claimAsset

function claimAsset(
    bytes32[32] calldata smtProofLocalExitRoot,
    bytes32[32] calldata smtProofRollupExitRoot,
    uint256 globalIndex,
    bytes32 mainnetExitRoot,
    bytes32 rollupExitRoot,
    uint32 originNetwork,
    address originTokenAddress,
    uint32 destinationNetwork,
    address destinationAddress,
    uint256 amount,
    bytes calldata metadata
) external;

claimMessage

function claimMessage(
    bytes32[32] calldata smtProofLocalExitRoot,
    bytes32[32] calldata smtProofRollupExitRoot,
    uint256 globalIndex,
    bytes32 mainnetExitRoot,
    bytes32 rollupExitRoot,
    uint32 originNetwork,
    address originAddress,
    uint32 destinationNetwork,
    address destinationAddress,
    uint256 amount,
    bytes calldata metadata
) external;

bridgeMessage

function bridgeMessage(
    uint32 destinationNetwork,
    address destinationAddress,
    bool forceUpdateGlobalExitRoot,
    bytes calldata metadata
) external payable;

wrappedAddressIsNotMintable

function wrappedAddressIsNotMintable(address wrappedAddress) external view returns (bool isNotMintable);

IVaultBridgeTokenInitializer

Git Source

Author: See https://github.com/agglayer/vault-bridge

This interface exists because of a limitiation in the Solidity compiler.

Functions

initialize

Vault Bridge Token delegates the initialization to this contract.

Please refer to __VaultBridgeToken_init in VaultBridgeToken.sol for more information.

function initialize(VaultBridgeToken.InitializationParameters calldata initParams) external;

IWETH9

Git Source

Inherits: IERC20

Author: See https://github.com/agglayer/vault-bridge

Functions

deposit

Deposit ether to get wrapped ether

function deposit() external payable;

withdraw

Withdraw wrapped ether to get ether

function withdraw(uint256) external;

Versioned

Git Source

Author: See https://github.com/agglayer/vault-bridge

Functions

version

The version of the contract.

function version() public pure returns (string memory);

Contents

• vbETH
• GenericVaultBridgeToken

Contents

• VbETH

VbETH

Git Source

Inherits: VaultBridgeToken

Author: See https://github.com/agglayer/vault-bridge

CAUTION! As-is, this contract MUST NOT be used on a network if the gas token is not ETH.

Functions

constructor

constructor();

initialize

function initialize(address initializer_, VaultBridgeToken.InitializationParameters calldata initParams)
    external
    initializer;

depositGasToken

deposit ETH to get vbETH

function depositGasToken(address receiver) external payable whenNotPaused nonReentrant returns (uint256 shares);

depositGasTokenAndBridge

deposit ETH to get vbETH and bridge to an L2

function depositGasTokenAndBridge(
    address destinationAddress,
    uint32 destinationNetworkId,
    bool forceUpdateGlobalExitRoot
) external payable whenNotPaused nonReentrant returns (uint256 shares);

mintWithGasToken

function mintWithGasToken(uint256 shares, address receiver)
    external
    payable
    whenNotPaused
    nonReentrant
    returns (uint256 assets);

_receiveUnderlyingTokenViaMsgValue

function _receiveUnderlyingTokenViaMsgValue(address from, uint256 assets) internal;

Errors

ContractNotSupportedOnThisNetwork

error ContractNotSupportedOnThisNetwork();

IncorrectMsgValue

error IncorrectMsgValue(uint256 msgValue, uint256 requestedAssets);

GenericVaultBridgeToken

Git Source

Inherits: VaultBridgeToken

Author: See https://github.com/agglayer/vault-bridge

This contract can be used to deploy vbTokens that do not require any customization.

Functions

constructor

constructor();

initialize

function initialize(address initializer_, VaultBridgeToken.InitializationParameters calldata initParams)
    external
    initializer;

CustomToken

Git Source

Inherits: Initializable, AccessControlUpgradeable, PausableUpgradeable, ReentrancyGuardUpgradeable, ERC20PermitUpgradeable, Versioned

Author: See https://github.com/agglayer/vault-bridge

A Custom Token is an optional ERC-20 token on Layer Ys to represent the 'native' version of the original underlying token from Layer X on Layer Y, ideally (or, simply, the upgraded version of the bridged vbToken).

A base contract used to create Custom Tokens.

@note IMPORTANT: Custom Token MUST be used as the new implementation for the bridged vbToken or be custom mapped to the corresponding vbToken on LxLy Bridge on Layer Y, and MUST give the minting and burning permission to LxLy Bridge and Native Converter. It MAY have a transfer fee.

State Variables

_CUSTOM_TOKEN_STORAGE

The storage slot at which Custom Token storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.CustomToken.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _CUSTOM_TOKEN_STORAGE = hex"0300d81ec8b5c42d6bd2cedd81ce26f1003c52753656b7512a8eef168b702500";

PAUSER_ROLE

bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

Functions

onlyLxlyBridgeAndNativeConverter

Checks if the sender is LxLy Bridge or Native Converter.

This modifier is used to restrict the minting and burning of Custom Token.

modifier onlyLxlyBridgeAndNativeConverter();

__CustomToken_init

Preserves the name and symbol of the bridged vbToken.

function __CustomToken_init(
    address owner_,
    uint8 originalUnderlyingTokenDecimals_,
    address lxlyBridge_,
    address nativeConverter_
) internal onlyInitializing;

Parameters

decimals

The number of decimals of Custom Token.

The number of decimals is the same as that of the original underlying token on Layer X.

function decimals() public view override returns (uint8);

lxlyBridge

LxLy Bridge, which connects AggLayer networks.

function lxlyBridge() public view returns (address);

nativeConverter

The address of Native Converter for this Custom Token.

function nativeConverter() public view returns (address);

_getCustomTokenStorage

Returns a pointer to the ERC-7201 storage namespace.

function _getCustomTokenStorage() private pure returns (CustomTokenStorage storage $);

transfer

Pausable ERC-20 transfer function.

function transfer(address to, uint256 value) public override whenNotPaused returns (bool);

transferFrom

Pausable ERC-20 transferFrom function.

function transferFrom(address from, address to, uint256 value) public override whenNotPaused returns (bool);

approve

Pausable ERC-20 approve function.

function approve(address spender, uint256 value) public override whenNotPaused returns (bool);

permit

Pausable ERC-20 Permit permit function.

function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)
    public
    override
    whenNotPaused;

mint

Mints Custom Tokens to the recipient.

This function can be called by LxLy Bridge and Native Converter only.

function mint(address account, uint256 value) external whenNotPaused onlyLxlyBridgeAndNativeConverter nonReentrant;

Parameters

burn

Burns Custom Tokens from a holder.

This function can be called by LxLy Bridge and Native Converter only.

function burn(address account, uint256 value) external whenNotPaused onlyLxlyBridgeAndNativeConverter nonReentrant;

pause

Prevents usage of functions with the whenNotPaused modifier.

This function can be called by a pauser only.

function pause() external onlyRole(PAUSER_ROLE) nonReentrant;

unpause

Allows usage of functions with the whenNotPaused modifier.

This function can be called by the owner only.

function unpause() external onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;

Events

NotMinted

event NotMinted(uint256 indexed value);

Errors

Unauthorized

error Unauthorized();

InvalidOwner

error InvalidOwner();

InvalidOriginalUnderlyingTokenDecimals

error InvalidOriginalUnderlyingTokenDecimals();

InvalidLxLyBridge

error InvalidLxLyBridge();

InvalidNativeConverter

error InvalidNativeConverter();

Structs

CustomTokenStorage

Storage of Custom Token contract.

It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions when using with upgradeable contracts.

Note: storage-location: erc7201:agglayer.vault-bridge.CustomToken.storage

struct CustomTokenStorage {
    uint8 decimals;
    address lxlyBridge;
    address nativeConverter;
}

MigrationManager

Git Source

Inherits: IBridgeMessageReceiver, Initializable, AccessControlUpgradeable, PausableUpgradeable, ReentrancyGuardTransientUpgradeable, Versioned

Author: See https://github.com/agglayer/vault-bridge

Migration Manager is a singleton contract on Layer X.

Backing for Custom Tokens minted by Native Converters on Layer Ys can be migrated to Migration Manager on Layer X. Migration Manager completes migrations by calling completeMigration on the corresponidng vbToken, which mints vbToken and bridges it to address zero on the Layer Ys, effectively locking the backing in LxLy Bridge. Please refer to onMessageReceived for more information.

Main functionality.

Other functionality.

Libraries.

External contracts.

This contract exists to prevent manipulation of vbTokens' internal accounting through reentrancy (specifically, claiming assets on LxLy Bridge to vbToken mid-execution).

State Variables

_MIGRATION_MANAGER_STORAGE

The storage slot at which Migration Manager storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.MigrationManager.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _MIGRATION_MANAGER_STORAGE =
    hex"30cf29e424d82bdf294fbec113ef39ac73137edfdb802b37ef3fc9ad433c5000";

PAUSER_ROLE

bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

Functions

onlyLxLyBridge

Checks if the sender is LxLy Bridge.

modifier onlyLxLyBridge();

receive

receive() external payable;

constructor

constructor();

initialize

Initializes the Migration Manager contract.

function initialize(address owner_, address lxlyBridge_, address wrappedGasToken_) external initializer;

Parameters

lxlyBridge

LxLy Bridge, which connects AggLayer networks.

function lxlyBridge() public view returns (ILxLyBridge);

nativeConvertersConfiguration

Tells which vbToken Native Converter on Layer a Y belongs to.

function nativeConvertersConfiguration(uint32 layerYLxlyId, address nativeConverter)
    public
    view
    returns (TokenPair memory tokenPair);

Parameters

_getMigrationManagerStorage

Returns a pointer to the ERC-7201 storage namespace.

function _getMigrationManagerStorage() private pure returns (MigrationManagerStorage storage $);

configureNativeConverters

Maps Native Converters on Layer Ys to vbToken and underlying token on Layer X.

This function can be called by the owner only.

CAUTION! Misconfiguration could allow an attacker to gain unauthorized access to vbToken and other contracts.

function configureNativeConverters(
    uint32[] calldata layerYLxlyIds,
    address[] calldata nativeConverters,
    address payable vbToken
) external onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;

Parameters

onMessageReceived

When Native Converter migrates backing, it calls both bridgeAsset and bridgeMessage on LxLy Bridge to migrateBackingToLayerX.

The asset must be claimed before the message on LxLy Bridge.

The message tells vbToken how much Custom Token must be backed by vbToken, which is minted and bridged to address zero on the respective Layer Y. This action provides liquidity when bridging Custom Token to from Layer Ys to Layer X and increments the pessimistic proof.

This function can be called by LxLy Bridge only.

function onMessageReceived(address originAddress, uint32 originNetwork, bytes memory data)
    external
    payable
    whenNotPaused
    onlyLxLyBridge
    nonReentrant;

pause

Prevents usage of functions with the whenNotPaused modifier.

This function can be called by the owner only.

function pause() external onlyRole(PAUSER_ROLE) nonReentrant;

unpause

Allows usage of functions with the whenNotPaused modifier.

This function can be called by the owner only.

function unpause() external onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;

Events

NativeConverterConfigured

event NativeConverterConfigured(uint32 indexed layerYLxlyId, address indexed nativeConverter, address indexed vbToken);

Errors

InvalidOwner

error InvalidOwner();

InvalidLxLyBridge

error InvalidLxLyBridge();

InvalidWrappedGasToken

error InvalidWrappedGasToken();

NonMatchingInputLengths

error NonMatchingInputLengths();

InvalidLayerYLxLyId

error InvalidLayerYLxLyId();

InvalidNativeConverter

error InvalidNativeConverter();

InvalidUnderlyingToken

error InvalidUnderlyingToken();

Unauthorized

error Unauthorized();

CannotWrapGasToken

error CannotWrapGasToken();

InsufficientUnderlyingTokenBalanceAfterWrapping

error InsufficientUnderlyingTokenBalanceAfterWrapping(uint256 newBalance, uint256 expectedBalance);

Structs

TokenPair

Used for mapping Native Converters to vbTokens.

struct TokenPair {
    VaultBridgeToken vbToken;
    IERC20 underlyingToken;
}

MigrationManagerStorage

Storage of the Migration Manager contract.

It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions when using with upgradeable contracts.

Note: storage-location: erc7201:agglayer.vault-bridge.MigrationManager.storage

struct MigrationManagerStorage {
    ILxLyBridge lxlyBridge;
    uint32 _lxlyId;
    mapping(uint32 layerYLxLyId => mapping(address nativeConverter => TokenPair tokenPair))
        nativeConvertersConfiguration;
    IWETH9 _wrappedGasToken;
}

Enums

CrossNetworkInstruction

Used in cross-network communication.

enum CrossNetworkInstruction {
    _0_COMPLETE_MIGRATION,
    _1_WRAP_GAS_TOKEN_AND_COMPLETE_MIGRATION
}

NativeConverter

Git Source

Inherits: Initializable, AccessControlUpgradeable, PausableUpgradeable, ReentrancyGuardUpgradeable, ERC20PermitUser, Versioned

Author: See https://github.com/agglayer/vault-bridge

Native Converter is an optional contract on Layer Ys that converts the underlying token (usually the bridge-wrapped version of the original underlying token from Layer X) to Custom Token, and vice versa, on demand. It can also migrate backing for Custom Token it has minted to Layer X, where vbToken will be minted and locked in LxLy Bridge. Please refer to migrateBackingToLayerX for more information.

A base contract used to create Native Converters.

@note (ATTENTION) This contract MUST have mint and burn permission on Custom Token. Please refer to CustomToken.sol for more information.

@note IMPORTANT: The underlying token MUST NOT be a rebasing token, and MUST NOT have transfer hooks (i.e., enable reentrancy); it MAY have a transfer fee.

State Variables

_NATIVE_CONVERTER_STORAGE

The storage slot at which Native Converter storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.NativeConverter.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _NATIVE_CONVERTER_STORAGE =
    hex"a14770e0debfe4b8406a01c33ee3a7bbe0acc66b3bde7c71854bf7d080a9c600";

MIGRATOR_ROLE

bytes32 public constant MIGRATOR_ROLE = keccak256("MIGRATOR_ROLE");

PAUSER_ROLE

bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

Functions

__NativeConverter_init

The customToken and underlyingToken MUST have the same number of decimals. @note (ATTENTION) The decimals of the customToken and underlyingToken will default to 18 if they revert on decimals.

function __NativeConverter_init(
    address owner_,
    address customToken_,
    address underlyingToken_,
    address lxlyBridge_,
    uint32 layerXLxlyId_,
    uint256 nonMigratableBackingPercentage_,
    address migrationManager_
) internal onlyInitializing;

Parameters

customToken

The upgraded version of the bridged vbToken.

function customToken() public view returns (IERC20);

underlyingToken

The token that represent the original underlying token on Layer Y.

function underlyingToken() public view returns (IERC20);

backingOnLayerY

The amount of the underlying token that backs Custom Token minted by Native Converter on Layer Y that has not been migrated to Layer X.

The amount is used in accounting and may be different from Native Converter's underlying token balance. @note IMPORTANT: You may do as you wish with surplus underlying token balance, but you MUST NOT designate it as backing.

function backingOnLayerY() public view returns (uint256);

lxlyId

The LxLy ID of this network.

function lxlyId() public view returns (uint32);

lxlyBridge

LxLy Bridge, which connects AggLayer networks.

function lxlyBridge() public view returns (ILxLyBridge);

layerXLxlyId

The LxLy ID of Layer X.

function layerXLxlyId() public view returns (uint32);

nonMigratableBackingPercentage

The percentage of backing that should remain in Native Converter when migrating backing to Layer X, based on the total supply of Custom Token.

It is possible to game the system by manipulating the total supply of Custom Token, so this is more of a soft limit.

function nonMigratableBackingPercentage() public view returns (uint256);

Returns

migrationManager

The address of the Migration Manager on Layer X.

function migrationManager() public view returns (MigrationManager);

_getNativeConverterStorage

Returns a pointer to the ERC-7201 storage namespace.

function _getNativeConverterStorage() private pure returns (NativeConverterStorage storage $);

convert

Deposit a specific amount of the underlying token and get Custom Token.

function convert(uint256 assets, address receiver) external whenNotPaused nonReentrant returns (uint256 shares);

Parameters

Returns

_convert

Deposit a specific amount of the underlying token and get Custom Token.

function _convert(uint256 assets, address receiver) internal returns (uint256 shares);

Parameters

Returns

convertWithPermit

Deposit a specific amount of the underlying token and get Custom Token.

Uses EIP-2612 permit to transfer the underlying token from the sender to self.

function convertWithPermit(uint256 assets, address receiver, bytes calldata permitData)
    external
    whenNotPaused
    nonReentrant
    returns (uint256 shares);

Parameters

Returns

maxDeconvert

How much Custom Token a specific user can burn. (Deconverting Custom Token burns it and unlocks the underlying token).

function maxDeconvert(address owner) external view returns (uint256 maxShares);

_simulateDeconvert

Calculates the amount of Custom Token that can be deconverted right now.

function _simulateDeconvert(uint256 shares, bool force) internal view returns (uint256 deconvertedShares);

Parameters

deconvert

Burn a specific amount of Custom Token to unlock a respective amount of the underlying token.

function deconvert(uint256 shares, address receiver) external whenNotPaused nonReentrant returns (uint256 assets);

Parameters

Returns

deconvertAndBridge

Burn a specific amount of Custom Token to unlock a respective amount of the underlying token, and bridge it to another network.

function deconvertAndBridge(
    uint256 shares,
    address receiver,
    uint32 destinationNetworkId,
    bool forceUpdateGlobalExitRoot
) external whenNotPaused nonReentrant returns (uint256 assets);

Parameters

Returns

_deconvert

Burn a specific amount of Custom Token to unlock a respective amount of the underlying token, and optionally bridge it to another network.

function _deconvert(uint256 shares, uint32 destinationNetworkId, address receiver, bool forceUpdateGlobalExitRoot)
    internal
    returns (uint256 assets);

Parameters

Returns

_convertToShares

Tells how much a specific amount of underlying token is worth in Custom Token.

The underlying token backs vbToken 1:1.

function _convertToShares(uint256 assets) internal pure returns (uint256 shares);

Parameters

Returns

_convertToAssets

Tells how much a specific amount of Custom Token is worth in the underlying token.

vbToken is backed by the underlying token 1:1.

function _convertToAssets(uint256 shares) internal pure returns (uint256 assets);

Parameters

Returns

migratableBacking

The maximum amount of backing that can be migrated to Layer X.

function migratableBacking() public view returns (uint256);

migrateBackingToLayerX

Migrates a specific amount of backing to Layer X.

This action provides vbToken liquidity on LxLy Bridge on Layer X.

The bridged asset and message must be claimed manually on LxLy Bridge on Layer X to complete the migration.

This function can be called by a migrator only.

The migration can be completed by anyone on Layer X.

Consider calling this function periodically; anyone can complete a migration on Layer X.

function migrateBackingToLayerX(uint256 assets) external whenNotPaused onlyRole(MIGRATOR_ROLE) nonReentrant;

setNonMigratableBackingPercentage

Sets the percentage of backing that should remain in Native Converter after a migration, based on the total supply of Custom Token.

It is possible to game the system by manipulating the total supply of Custom Token, so this is a soft limit.

This function can be called by the owner only.

function setNonMigratableBackingPercentage(uint256 nonMigratableBackingPercentage_)
    external
    onlyRole(DEFAULT_ADMIN_ROLE)
    nonReentrant;

Parameters

_receiveUnderlyingToken

Transfers the underlying token from an external account to itself.

@note CAUTION! This function MUST NOT introduce reentrancy/cross-entrancy vulnerabilities.

function _receiveUnderlyingToken(address from, uint256 value) internal returns (uint256 receivedValue);

Returns

_sendUnderlyingToken

Transfers the underlying token to an external account.

@note CAUTION! This function MUST NOT introduce reentrancy/cross-entrancy vulnerabilities.

function _sendUnderlyingToken(address to, uint256 value) internal;

pause

Prevents usage of functions with the whenNotPaused modifier.

This function can be called by a pauser only.

function pause() external onlyRole(PAUSER_ROLE) nonReentrant;

unpause

Allows usage of functions with the whenNotPaused modifier.

This function can be called by the owner only.

function unpause() external onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;

Events

MigrationStarted

event MigrationStarted(uint256 indexed mintedCustomToken, uint256 indexed migratedBacking);

NonMigratableBackingPercentageSet

event NonMigratableBackingPercentageSet(uint256 nonMigratableBackingPercentage);

Errors

InvalidOwner

error InvalidOwner();

InvalidCustomToken

error InvalidCustomToken();

InvalidUnderlyingToken

error InvalidUnderlyingToken();

InvalidLxLyBridge

error InvalidLxLyBridge();

InvalidLayerXLxlyId

error InvalidLayerXLxlyId();

InvalidMigrationManager

error InvalidMigrationManager();

NonMatchingTokenDecimals

error NonMatchingTokenDecimals(uint8 customTokenDecimals, uint8 underlyingTokenDecimals);

InvalidAssets

error InvalidAssets();

InvalidReceiver

error InvalidReceiver();

InvalidPermitData

error InvalidPermitData();

InvalidShares

error InvalidShares();

InvalidNonMigratableBackingPercentage

error InvalidNonMigratableBackingPercentage();

AssetsTooLarge

error AssetsTooLarge(uint256 availableAssets, uint256 requestedAssets);

InvalidDestinationNetworkId

error InvalidDestinationNetworkId();

OnlyMigrator

error OnlyMigrator();

Structs

NativeConverterStorage

Storage of Native Converter contract.

It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions when using with upgradeable contracts.

Note: storage-location: erc7201:agglayer.vault-bridge.NativeConverter.storage

struct NativeConverterStorage {
    CustomToken customToken;
    IERC20 underlyingToken;
    uint256 backingOnLayerY;
    uint32 lxlyId;
    ILxLyBridge lxlyBridge;
    uint32 layerXLxlyId;
    uint256 nonMigratableBackingPercentage;
    address migrationManager;
    bool _underlyingTokenIsNotMintable;
}

VaultBridgeToken

Git Source

Inherits: Initializable, AccessControlUpgradeable, PausableUpgradeable, ReentrancyGuardTransientUpgradeable, IERC4626, ERC20PermitUpgradeable, ERC20PermitUser, Versioned

Author: See https://github.com/agglayer/vault-bridge

A vbToken is an ERC-20 token, ERC-4626 vault, and LxLy Bridge extension, enabling deposits and bridging of select assets, such as WBTC, WETH, USDT, USDC, and USDS, while putting the assets to work to produce yield.

A base contract used to create vbTokens.

@note IMPORTANT: In order to not drive the complexity of the Vault Bridge protocol up, vbToken MUST NOT have transfer, deposit, or withdrawal fees. The underlying token on Layer X MUST NOT have a transfer fee; this contract will revert if it detects a transfer fee. The underlying token and Custom Token on Layer Ys MAY have transfer fees. The yield vault SHOULD NOT have deposit and/or withdrawal fees; however, it is expected that produced yield will offset any costs incurred when depositing to and withdrawing from the yield vault for the purpose of producing yield or rebalancing the internal reserve. The price of the yield vault's shares MUST NOT decrease (e.g., no bad debt realization); still, this contract implements solvency checks for protection with a configurable slippage parameter. Additionally, the underlying token MUST NOT be a rebasing token, and MUST NOT have transfer hooks (i.e., does not enable reentrancy/crossentrancy).

State Variables

REBALANCER_ROLE

bytes32 public constant REBALANCER_ROLE = keccak256("REBALANCER_ROLE");

YIELD_COLLECTOR_ROLE

bytes32 public constant YIELD_COLLECTOR_ROLE = keccak256("YIELD_COLLECTOR_ROLE");

PAUSER_ROLE

bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");

_VAULT_BRIDGE_TOKEN_STORAGE

The storage slot at which Vault Bridge Token storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.VaultBridgeToken.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _VAULT_BRIDGE_TOKEN_STORAGE =
    hex"f082fbc4cfb4d172ba00d34227e208a31ceb0982bc189440d519185302e44700";

Functions

onlyYieldRecipient

Checks if the sender is the yield recipient.

modifier onlyYieldRecipient();

onlyLxLyBridge

Checks if the sender is LxLy Bridge.

modifier onlyLxLyBridge();

onlyMigrationManager

Checks if the sender is Migration Manager.

modifier onlyMigrationManager();

onlySelf

Checks if the sender is the vbToken itself.

modifier onlySelf();

delegatedToPart2

Delegates the call to VaultBridgeTokenPart2.

modifier delegatedToPart2();

__VaultBridgeToken_init

function __VaultBridgeToken_init(address initializer_, InitializationParameters calldata initParams)
    internal
    onlyInitializing;

Parameters

underlyingToken

The underlying token that backs vbToken.

function underlyingToken() public view returns (IERC20);

decimals

The number of decimals of vbToken.

The number of decimals is the same as that of the underlying token, or 18 if the underlying token reverted on decimals.

function decimals() public view override(ERC20Upgradeable, IERC20Metadata) returns (uint8);

minimumReservePercentage

vbTokens can maintain an internal reserve of the underlying token for serving withdrawals from first (as opposed to staking all assets).

The owner can rebalance the reserve by calling rebalanceReserve when it is below or above the minimumReservePercentage. The reserve may also be rebalanced automatically on deposits and withdrawals.

function minimumReservePercentage() public view returns (uint256);

Returns

reservedAssets

vbTokens can maintain an internal reserve of the underlying token for serving withdrawals from first (as opposed to staking all assets).

How much of the underlying token is in the internal reserve.

function reservedAssets() public view returns (uint256);

yieldVault

An external, ERC-4246 compliant vault into which the underlying token is deposited to produce yield.

function yieldVault() public view returns (IERC4626);

yieldRecipient

The address that receives yield produced by the yield vault.

The yield collector collects yield, while the yield recipient receives it.

function yieldRecipient() public view returns (address);

lxlyId

The LxLy ID of this network.

function lxlyId() public view returns (uint32);

lxlyBridge

LxLy Bridge, which connects AggLayer networks.

function lxlyBridge() public view returns (ILxLyBridge);

migrationFeesFund

A dedicated fund for covering any fees on Layer Y during a migration of backing to Layer X. Please refer to completeMigration for more information.

function migrationFeesFund() public view returns (uint256);

minimumYieldVaultDeposit

The minimum amount of the underlying token that triggers a yield vault deposit.

Amounts below this value will be reserved regardless of the reserve percentage, in order to save gas for users.

The limit does not apply when rebalancing the reserve.

function minimumYieldVaultDeposit() public view returns (uint256);

migrationManager

The address of Migration Manager. Please refer to MigrationManager.sol for more information.

function migrationManager() public view returns (address);

yieldVaultMaximumSlippagePercentage

The maximum slippage percentage when depositing into or withdrawing from the yield vault.

function yieldVaultMaximumSlippagePercentage() public view returns (uint256);

Returns

_getVaultBridgeTokenStorage

Returns a pointer to the ERC-7201 storage namespace.

function _getVaultBridgeTokenStorage() private pure returns (VaultBridgeTokenStorage storage $);

asset

The underlying token that backs vbToken.

function asset() public view returns (address assetTokenAddress);

totalAssets

The total backing of vbToken in the underlying token in real-time.

function totalAssets() public view returns (uint256 totalManagedAssets);

convertToShares

Tells how much a specific amount of underlying token is worth in vbToken.

The underlying token backs vbToken 1:1.

function convertToShares(uint256 assets) public pure returns (uint256 shares);

convertToAssets

Tells how much a specific amount of vbToken is worth in the underlying token.

vbToken is backed by the underlying token 1:1.

function convertToAssets(uint256 shares) public pure returns (uint256 assets);

maxDeposit

How much underlying token can deposited for a specific user right now. (Depositing the underlying token mints vbToken).

function maxDeposit(address) external view returns (uint256 maxAssets);

previewDeposit

How much vbToken would be minted if a specific amount of the underlying token were deposited right now.

function previewDeposit(uint256 assets) external view whenNotPaused returns (uint256 shares);

deposit

Deposit a specific amount of the underlying token and mint vbToken.

function deposit(uint256 assets, address receiver) external whenNotPaused nonReentrant returns (uint256 shares);

depositAndBridge

Deposit a specific amount of the underlying token, and bridge minted vbToken to another network.

The receiver in the ERC-4626 Deposit event will be this contract.

function depositAndBridge(uint256 assets, address receiver, uint32 destinationNetworkId, bool forceUpdateGlobalExitRoot)
    external
    whenNotPaused
    nonReentrant
    returns (uint256 shares);

_deposit

Locks the underlying token, mints vbToken, and optionally bridges it to another network.

If bridging to another network, the receiver in the ERC-4626 Deposit event will be this contract.

function _deposit(
    uint256 assets,
    uint32 destinationNetworkId,
    address receiver,
    bool forceUpdateGlobalExitRoot,
    uint256 maxShares
) internal returns (uint256 shares, uint256 spentAssets);

Parameters

_depositUsingCustomReceivingFunction

Locks the underlying token, mints vbToken, and optionally bridges it to another network.

If bridging to another network, the receiver in the ERC-4626 Deposit event will be this contract.

function _depositUsingCustomReceivingFunction(
    function(address, uint256) internal receiveUnderlyingToken,
    uint256 assets,
    uint32 destinationNetworkId,
    address receiver,
    bool forceUpdateGlobalExitRoot,
    uint256 maxShares
) internal returns (uint256 shares, uint256 spentAssets);

Parameters

depositWithPermit

Deposit a specific amount of the underlying token and mint vbToken.

Uses EIP-2612 permit to transfer the underlying token from the sender to self.

function depositWithPermit(uint256 assets, address receiver, bytes calldata permitData)
    external
    whenNotPaused
    nonReentrant
    returns (uint256 shares);

depositWithPermitAndBridge

Deposit a specific amount of the underlying token, and bridge minted vbToken to another network.

Uses EIP-2612 permit to transfer the underlying token from the sender to self.

The receiver in the ERC-4626 Deposit event will be this contract.

function depositWithPermitAndBridge(
    uint256 assets,
    address receiver,
    uint32 destinationNetworkId,
    bool forceUpdateGlobalExitRoot,
    bytes calldata permitData
) external whenNotPaused nonReentrant returns (uint256 shares);

_depositWithPermit

Locks the underlying token, mints vbToken, and optionally bridges it to another network.

Uses EIP-2612 permit to transfer the underlying token from the sender to self.

function _depositWithPermit(
    uint256 assets,
    bytes calldata permitData,
    uint32 destinationNetworkId,
    address receiver,
    bool forceUpdateGlobalExitRoot,
    uint256 maxShares
) internal returns (uint256 shares, uint256 spentAssets);

Parameters

maxMint

How much vbToken can be minted to a specific user right now. (Minting vbToken locks the underlying token).

function maxMint(address) external view returns (uint256 maxShares);

previewMint

How much underlying token would be required to mint a specific amount of vbToken right now.

function previewMint(uint256 shares) external view whenNotPaused returns (uint256 assets);

mint

Mint a specific amount of vbToken by locking the required amount of the underlying token.

function mint(uint256 shares, address receiver) external whenNotPaused nonReentrant returns (uint256 assets);

maxWithdraw

How much underlying token can be withdrawn from a specific user right now. (Withdrawing the underlying token burns vbToken).

function maxWithdraw(address owner) external view returns (uint256 maxAssets);

previewWithdraw

How much vbToken would be burned if a specific amount of the underlying token were withdrawn right now.

function previewWithdraw(uint256 assets) external view whenNotPaused returns (uint256 shares);

_simulateWithdraw

Calculates the amount of the underlying token that could be withdrawn right now.

This function is used for estimation purposes only.

@note IMPORTANT: reservedAssets must be up-to-date before using this function!

function _simulateWithdraw(uint256 assets, bool force) internal view returns (uint256 withdrawnAssets);

Parameters

withdraw

Withdraw a specific amount of the underlying token by burning the required amount of vbToken.

function withdraw(uint256 assets, address receiver, address owner)
    external
    whenNotPaused
    nonReentrant
    returns (uint256 shares);

_withdraw

Withdraw a specific amount of the underlying token by burning the required amount of vbToken.

function _withdraw(uint256 assets, address receiver, address owner) internal returns (uint256 shares);

maxRedeem

How much vbToken can be redeemed for a specific user. (Redeeming vbToken burns it and unlocks the underlying token).

function maxRedeem(address owner) external view returns (uint256 maxShares);

previewRedeem

How much underlying token would be unlocked if a specific amount of vbToken were redeemed and burned right now.

function previewRedeem(uint256 shares) external view whenNotPaused returns (uint256 assets);

redeem

Burn a specific amount of vbToken and unlock the respective amount of the underlying token.

function redeem(uint256 shares, address receiver, address owner)
    external
    whenNotPaused
    nonReentrant
    returns (uint256 assets);

claimAndRedeem

Claim vbToken from LxLy Bridge and redeem it.

function claimAndRedeem(
    bytes32[32] calldata smtProofLocalExitRoot,
    bytes32[32] calldata smtProofRollupExitRoot,
    uint256 globalIndex,
    bytes32 mainnetExitRoot,
    bytes32 rollupExitRoot,
    address destinationAddress,
    uint256 amount,
    address receiver,
    bytes calldata metadata
) external whenNotPaused nonReentrant returns (uint256 assets);

transfer

Pausable ERC-20 transfer function.

function transfer(address to, uint256 value) public override(ERC20Upgradeable, IERC20) whenNotPaused returns (bool);

transferFrom

Pausable ERC-20 transferFrom function.

function transferFrom(address from, address to, uint256 value)
    public
    override(ERC20Upgradeable, IERC20)
    whenNotPaused
    returns (bool);

approve

Pausable ERC-20 approve function.

function approve(address spender, uint256 value)
    public
    override(ERC20Upgradeable, IERC20)
    whenNotPaused
    returns (bool);

permit

Pausable ERC-20 Permit permit function.

function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)
    public
    override
    whenNotPaused;

stakedAssets

The amount of the underlying token in the yield vault, as reported by the yield vault in real-time.

function stakedAssets() public view returns (uint256);

reservePercentage

The reserve percentage in real-time.

The reserve is based on the total supply of vbToken, and does not account for uncompleted migrations of backing from Layer Ys to Layer X. Please refer to completeMigration for more information.

function reservePercentage() public view returns (uint256);

yield

The amount of yield available for collection.

function yield() public view returns (uint256);

backingDifference

The difference between the total assets and the minimum assets required to back the total supply of vbToken in real-time.

function backingDifference() public view returns (bool positive, uint256 difference);

rebalanceReserve

Rebalances the internal reserve by withdrawing the underlying token from, or depositing the underlying token into, the yield vault.

This function can be called by a rebalancer only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function rebalanceReserve() external virtual delegatedToPart2;

_rebalanceReserve

Rebalances the internal reserve by withdrawing the underlying token from, or depositing the underlying token into, the yield vault.

function _rebalanceReserve(bool force, bool allowRebalanceDown) internal;

Parameters

collectYield

Transfers yield produced by the yield vault to the yield recipient in the form of vbToken.

Does not rebalance the reserve after collecting yield to allow usage while the contract is paused.

This function can be called by a yield collector only.

Increases the net collected yield.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function collectYield() external virtual delegatedToPart2;

burn

Burns a specific amount of vbToken.

This function can be used if the yield recipient has collected an unrealistic amount of yield over time.

This function can be called by the yield recipient only.

Decreases the net collected yield.

Does not rebalance the reserve after burning to allow usage while the contract is paused.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function burn(uint256 shares) external virtual delegatedToPart2;

donateAsYield

Adds a specific amount of the underlying token to the reserve by transferring it from the sender.

This function can be used to restore backing difference by donating the underlying token.

This function can be called by anyone.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function donateAsYield(uint256 assets) external virtual delegatedToPart2;

donateForCompletingMigration

Adds a specific amount of the underlying token to a dedicated fund for covering any fees on Layer Y during a migration of backing to Layer X by transferring it from the sender. Please refer to completeMigration for more information.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function donateForCompletingMigration(uint256 assets) external virtual delegatedToPart2;

completeMigration

Completes a migration of backing from a Layer Y to Layer X by minting and locking the required amount of vbToken in LxLy Bridge.

Anyone can trigger the execution of this function by claiming the asset and message on LxLy Bridge. Please refer to NativeConverter.sol for more information.

Backing for Custom Token minted by Native Converter on Layer Ys can be migrated to Layer X.

When Native Converter migrates backing, it calls both bridgeAsset and bridgeMessage on LxLy Bridge to migrateBackingToLayerX.

The asset must be claimed before the message on LxLy Bridge.

The message tells vbToken how much Custom Token must be backed by vbToken, which is minted and bridged to address zero on the respective Layer Y. This action provides liquidity when bridging Custom Token to from Layer Ys to Layer X and increments the pessimistic proof.

This function can be called by Migraton Manager only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function completeMigration(uint32 originNetwork, uint256 shares, uint256 assets) external virtual delegatedToPart2;

Parameters

drainYieldVault

Drains the yield vault by redeeming yield vault shares. Assets will be put into the internal reserve.

This function may utilize availabe yield to ensure successful draining if there is larger slippage. Consider collecting yield before calling this function to disable this behavior.

This function can be called by the owner only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function drainYieldVault(uint256 shares, bool exact) external virtual delegatedToPart2;

Parameters

setMinimumReservePercentage

Sets the minimum reserve percentage.

@note (ATTENTION) Automatic reserve rebalancing will be disabled for values greater than 1e18 (100%).

This function can be called by the owner only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function setMinimumReservePercentage(uint256 minimumReservePercentage_) external virtual delegatedToPart2;

Parameters

setYieldVault

Sets the yield vault.

@note CAUTION! Use drainYieldVault to drain the current yield vault completely before changing it. Any yield vault shares that are not redeemed will not count toward the underlying token backing after changing the yield vault.

This function can be called by the owner only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function setYieldVault(address yieldVault_) external virtual delegatedToPart2;

setYieldRecipient

Sets the yield recipient.

Yield will be collected before changing the recipient.

This function can be called by the owner only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function setYieldRecipient(address yieldRecipient_) external virtual delegatedToPart2;

setMinimumYieldVaultDeposit

The minimum amount of the underlying token that triggers a yield vault deposit.

Amounts below this value will be reserved regardless of the reserve percentage, in order to save gas for users.

The limit does not apply when rebalancing the reserve.

This function can be called by the owner only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function setMinimumYieldVaultDeposit(uint256 minimumYieldVaultDeposit_) external virtual delegatedToPart2;

Parameters

setYieldVaultMaximumSlippagePercentage

The maximum slippage percentage when depositing into or withdrawing from the yield vault.

@note IMPORTANT: Any losses incurred due to slippage (and not fully covered by produced yield) will need to be covered by whomever is responsible for this contract.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function setYieldVaultMaximumSlippagePercentage(uint256 maximumSlippagePercentage) external virtual delegatedToPart2;

Parameters

_calculateAmountToReserve

Calculates the amount of assets to reserve (as opposed to depositing into the yield vault) based on the current and minimum reserve percentages.

@note (ATTENTION) reservedAssets must be up-to-date before using this function.

function _calculateAmountToReserve(uint256 assets, uint256 nonMintedShares)
    internal
    view
    returns (uint256 assetsToReserve);

Parameters

_depositIntoYieldVault

Deposit a specific amount of the underlying token into the yield vault.

function _depositIntoYieldVault(uint256 assets, bool exact) internal returns (uint256 nonDepositedAssets);

Parameters

Returns

performReversibleYieldVaultDeposit

Enables infinte deposits regardless of the behavior of the yield vault.

This function can be called by the this contract only.

This function reverts if the yield vault deposit fails, or the solvency check does not pass with revert data ABI-encoded in the following format: abi.encode(depositSucceeded, depositData, solvencyCheckPassed), which can be decoded in another function.

function performReversibleYieldVaultDeposit(uint256 assets) external whenNotPaused onlySelf;

_withdrawFromYieldVault

Withdraws a specific amount of the underlying token from the yield vault.

function _withdrawFromYieldVault(
    uint256 assets,
    bool exact,
    address receiver,
    uint256 originalTotalSupply,
    uint256 originalUncollectedYield,
    uint256 originalReservedAssets
) internal returns (uint256 nonWithdrawnAssets, uint256 receivedAssets);

Parameters

Returns

_receiveUnderlyingToken

Transfers the underlying token from an external account to self.

@note CAUTION! This function MUST NOT introduce reentrancy/crossentrancy vulnerabilities.

function _receiveUnderlyingToken(address from, uint256 value) internal;

_sendUnderlyingToken

Transfers the underlying token to an external account.

@note CAUTION! This function MUST NOT introduce reentrancy/crossentrancy vulnerabilities.

function _sendUnderlyingToken(address to, uint256 value) internal;

pause

Prevents usage of functions with the whenNotPaused modifier.

This function can be called by a pauser only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function pause() external virtual delegatedToPart2;

unpause

Allows usage of functions with the whenNotPaused modifier.

This function can be called by the owner only.

Delegates the call to VaultBridgeTokenPart2.

@note (ATTENTION) The virtual modifier allows VaultBridgeTokenPart2 to override this function. Do not override the function yourself.

function unpause() external virtual delegatedToPart2;

_delegateToPart2

Delegates the call to VaultBridgeTokenPart2.

function _delegateToPart2() private;

Events

ReserveRebalanced

event ReserveRebalanced(uint256 oldReservedAssets, uint256 newReservedAssets, uint256 reservePercentage);

YieldCollected

event YieldCollected(address indexed yieldRecipient, uint256 vbTokenAmount);

Burned

event Burned(uint256 vbTokenAmount);

DonatedAsYield

event DonatedAsYield(address indexed who, uint256 assets);

DonatedForCompletingMigration

event DonatedForCompletingMigration(address indexed who, uint256 assets);

MigrationCompleted

event MigrationCompleted(
    uint32 indexed originNetwork, uint256 indexed shares, uint256 indexed assets, uint256 migrationFeesFundUtilization
);

YieldRecipientSet

event YieldRecipientSet(address indexed yieldRecipient);

MinimumReservePercentageSet

event MinimumReservePercentageSet(uint256 minimumReservePercentage);

YieldVaultDrained

event YieldVaultDrained(uint256 redeemedShares, uint256 receivedAssets);

YieldVaultSet

event YieldVaultSet(address yieldVault);

YieldVaultMaximumSlippagePercentageSet

event YieldVaultMaximumSlippagePercentageSet(uint256 slippagePercentage);

Errors

Unauthorized

error Unauthorized();

InvalidInitializer

error InvalidInitializer();

InvalidOwner

error InvalidOwner();

InvalidName

error InvalidName();

InvalidSymbol

error InvalidSymbol();

InvalidUnderlyingToken

error InvalidUnderlyingToken();

InvalidMinimumReservePercentage

error InvalidMinimumReservePercentage();

InvalidYieldVault

error InvalidYieldVault();

InvalidYieldRecipient

error InvalidYieldRecipient();

InvalidLxLyBridge

error InvalidLxLyBridge();

InvalidMigrationManager

error InvalidMigrationManager();

InvalidYieldVaultMaximumSlippagePercentage

error InvalidYieldVaultMaximumSlippagePercentage();

InvalidVaultBridgeTokenPart2

error InvalidVaultBridgeTokenPart2();

InvalidAssets

error InvalidAssets();

InvalidDestinationNetworkId

error InvalidDestinationNetworkId();

InvalidReceiver

error InvalidReceiver();

InvalidPermitData

error InvalidPermitData();

InvalidShares

error InvalidShares();

IncorrectAmountOfSharesMinted

error IncorrectAmountOfSharesMinted(uint256 mintedShares, uint256 requiredShares);

AssetsTooLarge

error AssetsTooLarge(uint256 availableAssets, uint256 requestedAssets);

IncorrectAmountOfSharesRedeemed

error IncorrectAmountOfSharesRedeemed(uint256 redeemedShares, uint256 requiredShares);

CannotRebalanceReserve

error CannotRebalanceReserve();

NoNeedToRebalanceReserve

error NoNeedToRebalanceReserve();

NoYield

error NoYield();

InvalidOriginNetwork

error InvalidOriginNetwork();

CannotCompleteMigration

error CannotCompleteMigration(uint256 requiredAssets, uint256 receivedAssets, uint256 assetsInMigrationFund);

YieldVaultRedemptionFailed

error YieldVaultRedemptionFailed(uint256 sharesToRedeem, uint256 redemptionLimit);

MinimumYieldVaultDepositNotMet

error MinimumYieldVaultDepositNotMet(uint256 assetsToDeposit, uint256 minimumYieldVaultDeposit);

YieldVaultDepositFailed

error YieldVaultDepositFailed(uint256 assetsToDeposit, uint256 depositLimit);

InsufficientYieldVaultSharesMinted

error InsufficientYieldVaultSharesMinted(uint256 depositedAssets, uint256 mintedShares);

UnknownError

error UnknownError(bytes data);

YieldVaultWithdrawalFailed

error YieldVaultWithdrawalFailed(uint256 assetsToWithdraw, uint256 withdrawalLimit);

ExcessiveYieldVaultSharesBurned

error ExcessiveYieldVaultSharesBurned(uint256 burnedShares, uint256 withdrawnAssets);

InsufficientUnderlyingTokenReceived

error InsufficientUnderlyingTokenReceived(uint256 receivedAssets, uint256 requestedAssets);

UnknownFunction

error UnknownFunction(bytes4 functionSelector);

Structs

VaultBridgeTokenStorage

Storage of Vault Bridge Token contract.

It's implemented on a custom ERC-7201 namespace to reduce the risk of storage collisions when using with upgradeable contracts.

Note: storage-location: erc7201:agglayer.vault-bridge.VaultBridgeToken.storage

struct VaultBridgeTokenStorage {
    IERC20 underlyingToken;
    uint8 decimals;
    uint256 minimumReservePercentage;
    uint256 reservedAssets;
    IERC4626 yieldVault;
    address yieldRecipient;
    uint256 _netCollectedYield;
    uint32 lxlyId;
    ILxLyBridge lxlyBridge;
    uint256 migrationFeesFund;
    uint256 minimumYieldVaultDeposit;
    address migrationManager;
    uint256 yieldVaultMaximumSlippagePercentage;
    address _vaultBridgeTokenPart2;
}

InitializationParameters

Parameters for initializing Vault Bridge Token contract.

@note (ATTENTION) decimals will match the underlying token. Defaults to 18 decimals if the underlying token reverts on decimals.

struct InitializationParameters {
    address owner;
    string name;
    string symbol;
    address underlyingToken;
    uint256 minimumReservePercentage;
    address yieldVault;
    address yieldRecipient;
    address lxlyBridge;
    uint256 minimumYieldVaultDeposit;
    address migrationManager;
    uint256 yieldVaultMaximumSlippagePercentage;
    address vaultBridgeTokenPart2;
}

Properties

VaultBridgeTokenInitializer

Git Source

Inherits: IVaultBridgeTokenInitializer, VaultBridgeToken

Author: See https://github.com/agglayer/vault-bridge

A singleton contract used by Vault Bridge Token for initialization.

This contract exists because of the contract size limit of the EVM.

State Variables

_VAULT_BRIDGE_TOKEN_STORAGE

The storage slot at which Vault Bridge Token storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.VaultBridgeToken.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _VAULT_BRIDGE_TOKEN_STORAGE =
    hex"f082fbc4cfb4d172ba00d34227e208a31ceb0982bc189440d519185302e44700";

Functions

constructor

constructor();

__getVaultBridgeTokenStorage

Returns a pointer to the ERC-7201 storage namespace.

function __getVaultBridgeTokenStorage() private pure returns (VaultBridgeTokenStorage storage $);

initialize

Vault Bridge Token delegates the initialization to this contract.

function initialize(VaultBridgeToken.InitializationParameters calldata initParams)
    external
    override
    onlyInitializing
    nonReentrant;

VaultBridgeTokenPart2

Git Source

Inherits: VaultBridgeToken

Author: See https://github.com/agglayer/vault-bridge

This contract exists because of the contract size limit of the EVM.

State Variables

_VAULT_BRIDGE_TOKEN_STORAGE

The storage slot at which Vault Bridge Token storage starts, following the EIP-7201 standard.

Calculated as keccak256(abi.encode(uint256(keccak256("agglayer.vault-bridge.VaultBridgeToken.storage")) - 1)) & ~bytes32(uint256(0xff)).

bytes32 private constant _VAULT_BRIDGE_TOKEN_STORAGE =
    hex"f082fbc4cfb4d172ba00d34227e208a31ceb0982bc189440d519185302e44700";

Functions

fallback

fallback() external;

constructor

constructor();

__getVaultBridgeTokenStorage

Returns a pointer to the ERC-7201 storage namespace.

function __getVaultBridgeTokenStorage() private pure returns (VaultBridgeTokenStorage storage $);

rebalanceReserve

Rebalances the internal reserve by withdrawing the underlying token from, or depositing the underlying token into, the yield vault.

Delegates the call to VaultBridgeTokenPart2.

function rebalanceReserve() external override whenNotPaused onlyRole(REBALANCER_ROLE) nonReentrant;

collectYield

Transfers yield produced by the yield vault to the yield recipient in the form of vbToken.

Increases the net collected yield.

function collectYield() external override onlyRole(YIELD_COLLECTOR_ROLE) nonReentrant;

_collectYield

Transfers yield produced by the yield vault to the yield recipient in the form of vbToken.

Does not rebalance the reserve after collecting yield to allow usage while the contract is paused.

function _collectYield(bool force) internal;

Parameters

burn

Burns a specific amount of vbToken.

Decreases the net collected yield.

function burn(uint256 shares) external override onlyYieldRecipient nonReentrant;

donateAsYield

Adds a specific amount of the underlying token to the reserve by transferring it from the sender.

Delegates the call to VaultBridgeTokenPart2.

function donateAsYield(uint256 assets) external override nonReentrant;

completeMigration

Completes a migration of backing from a Layer Y to Layer X by minting and locking the required amount of vbToken in LxLy Bridge.

Backing for Custom Token minted by Native Converter on Layer Ys can be migrated to Layer X.

function completeMigration(uint32 originNetwork, uint256 shares, uint256 assets)
    external
    override
    whenNotPaused
    onlyMigrationManager
    nonReentrant;

Parameters

donateForCompletingMigration

Adds a specific amount of the underlying token to a dedicated fund for covering any fees on Layer Y during a migration of backing to Layer X by transferring it from the sender. Please refer to completeMigration for more information.

Delegates the call to VaultBridgeTokenPart2.

function donateForCompletingMigration(uint256 assets) external override whenNotPaused nonReentrant;

setYieldRecipient

Sets the yield recipient.

Delegates the call to VaultBridgeTokenPart2.

function setYieldRecipient(address yieldRecipient_)
    external
    override
    whenNotPaused
    onlyRole(DEFAULT_ADMIN_ROLE)
    nonReentrant;

setMinimumReservePercentage

Sets the minimum reserve percentage.

Delegates the call to VaultBridgeTokenPart2.

function setMinimumReservePercentage(uint256 minimumReservePercentage_)
    external
    override
    onlyRole(DEFAULT_ADMIN_ROLE)
    nonReentrant;

Parameters

drainYieldVault

Drains the yield vault by redeeming yield vault shares. Assets will be put into the internal reserve.

This function can be called by the owner only.

function drainYieldVault(uint256 shares, bool exact) external override onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;

Parameters

setYieldVault

Sets the yield vault.

Delegates the call to VaultBridgeTokenPart2.

function setYieldVault(address yieldVault_) external override onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;

setMinimumYieldVaultDeposit

The minimum amount of the underlying token that triggers a yield vault deposit.

Delegates the call to VaultBridgeTokenPart2.

function setMinimumYieldVaultDeposit(uint256 minimumYieldVaultDeposit_)
    external
    override
    onlyRole(DEFAULT_ADMIN_ROLE)
    nonReentrant;

Parameters

setYieldVaultMaximumSlippagePercentage

The maximum slippage percentage when depositing into or withdrawing from the yield vault.

Delegates the call to VaultBridgeTokenPart2.

function setYieldVaultMaximumSlippagePercentage(uint256 maximumSlippagePercentage)
    external
    override
    onlyRole(DEFAULT_ADMIN_ROLE)
    nonReentrant;

Parameters

pause

Prevents usage of functions with the whenNotPaused modifier.

Delegates the call to VaultBridgeTokenPart2.

function pause() external override onlyRole(PAUSER_ROLE) nonReentrant;

unpause

Allows usage of functions with the whenNotPaused modifier.

Delegates the call to VaultBridgeTokenPart2.

function unpause() external override onlyRole(DEFAULT_ADMIN_ROLE) nonReentrant;