agglayer · ZeroEkkusu · May 27, 2025 · May 27, 2025 · May 27, 2025 · May 27, 2025
diff --git a/.env.example b/.env.example
@@ -1,5 +1 @@
-API_KEY=
-INFURA_KEY=
-POLYGONSCAN_API_KEY=
-TATARA_TOKEN=
-KATANA_TOKEN=
+ETHERSCAN_API_KEY=
diff --git a/.github/workflows/certora.yml b/.github/workflows/certora.yml
@@ -0,0 +1,68 @@
+name: Certora - Verification
+
+on:
+  pull_request:
+    branches:
+      - staging
+
+env:
+  FOUNDRY_PROFILE: ci
+  CONFIGS: |
+    certora/confs/GenericVaultBridgeToken.conf
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/GenericVaultBridgeToken_invariants.spec --rule netCollectedYieldAccounted --rule netCollectedYieldLimited
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/GenericVaultBridgeToken_invariants.spec --rule minimumReservePercentageLimit --rule reserveBacked
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/GenericVaultBridgeToken_invariants.spec --rule vaultBridgeTokenSolvency --rule vaultBridgeTokenSolvency_simple
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/GenericVaultBridgeToken_invariants.spec --rule assetsMoreThanSupply --rule noSupplyIfNoAssets
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/GenericVaultBridgeToken_invariants.spec --rule zeroAllowanceOnAssets --rule zeroAllowanceOnShares
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/GenericVaultBridgeToken_allowedChanges.spec
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/GenericVaultBridgeToken_integrity.spec
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/GVBTBalances.spec
+    certora/confs/GenericVaultBridgeToken.conf --verify GenericVaultBridgeToken:certora/specs/tokenMockBalances.spec
+    certora/confs/GenericNativeConverter.conf
+    certora/confs/base/MigrationManager.conf --rule onMsgReceived_doesntAlwaysRevert
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      statuses: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: install foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: install bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: bun install
+        run: |
+          forge soldeer install
+          bun install || true
+
+      - name: setup bridge repo
+        run: |
+          git clone https://github.com/0xPolygonHermez/zkevm-contracts.git
+          cd zkevm-contracts/
+          git checkout v10.1.0-rc.1
+          npm install
+
+      - name: Certora munge
+        run: ./certora/scripts/munge.sh
+
+      - name: run configs
+        uses: Certora/certora-run-action@v2
+        with:
+          cli-release: beta
+          configurations: ${{ env.CONFIGS }}
+          solc-versions: 0.8.28 0.8.29
+          solc-remove-version-prefix: "0."
+          job-name: "Verified Rules"
+          certora-key: ${{ secrets.CERTORAKEY }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -29,14 +29,13 @@ jobs:
         run: |
           forge --version
 
-      - name: Run Forge fmt
-        run: |
-          forge fmt --check
-        id: fmt
+      # - name: Run Forge fmt
+      #   run: |
+      #     forge fmt --check
+      #   id: fmt
 
       - name: Run Forge build
         run: |
-          forge --version
           forge soldeer install
           forge build --sizes
         id: build
@@ -54,6 +53,4 @@ jobs:
         run: |
           npm install
           forge test --no-match-contract "Generic" -vvv
-        env:
-          TATARA_TOKEN: ${{ secrets.TATARA_TOKEN }}
         id: test
diff --git a/.gitignore b/.gitignore
@@ -21,4 +21,9 @@ docs/
 coverage
 lcov.info
 
-.DS_Store
+.DS_Store
+
+# certora
+.certora_internal/
+zkevm-contracts/
+emv-*/*
diff --git a/LICENSE-OPEN-LICENSE b/LICENSE-OPEN-LICENSE
diff --git a/LICENSE-SOURCE-AVAILABLE-LICENSE → LICENSE-SOURCE-AVAILABLE b/LICENSE-SOURCE-AVAILABLE-LICENSE → LICENSE-SOURCE-AVAILABLE
@@ -3,7 +3,7 @@ SPDX-License-Identifier: LicenseRef-PolygonLabs-Source-Available
 SOURCE AVAILABLE LICENSE
 
 Licensor: PT Services DMCC
-Licensed Work: VaultBridge
+Licensed Work: Vault Bridge
 The Licensed Work is Copyright (c) 2025 PT Services DMCC
 
 Permitted Use: The Licensor hereby grants you the right to copy, modify, create derivative 

diff --git a/README.md b/README.md
@@ -1,104 +1,148 @@
+<div align="center">
+
+# Vault Bridge
+
+**[⛓️ Deployments](#deployments)**
+**&nbsp;&nbsp; [📙 Documentation](#documentation)**
+**&nbsp;&nbsp; [🧭 Website](https://www.agglayer.dev/agglayer-vaultbridge)**
+**&nbsp;&nbsp; [🐈‍⬛ GitHub](https://github.com/agglayer/vault-bridge/)**
+**&nbsp;&nbsp; [🦙 DefiLllama](https://defillama.com/protocol/vault-bridge)**
+
+</div>
+
+<br>
+
 > [!IMPORTANT]
 > You are viewing a development version of the codebase.
 
-# Vault Bridge
+## Contents
 
-Vault Bridge Token is the core of the Vault Bridge protocol. Built from the ground up to be reusable, it offers full Vault Bridge functionality out of the box, allowing you to create vbTokens in just a few lines of code.
+- [Contents](#contents)
+- [Overview](#overview)
+  - [TL;DR](#tldr)
+  - [Vault Bridge Token](#vault-bridge-token)
+  - [Migration Manager](#migration-manager)
+  - [Custom Token](#custom-token)
+  - [Native Converter](#native-converter)
+- [Get Started](#get-started)
+- [Documentation](#documentation)
+- [Deployments](#deployments)
+- [Usage](#usage)
+- [License](#license)
+
+<br>
 
 ## Overview
 
-The Vault Bridge protocol is comprised of:
+Vault Bridge enables chains and apps to generate native yield on TVL by putting bridged assets to work.
+
+The protocol is comprised of:
 
-- Layer X (the main network)
-  - [Vault Bridge Token](#vault-bridge-token-)
-  - [Migration Manager (singleton)](#migration-manager-singleton-)
-- Layer Y (other networks)
-  - [Custom Token](#custom-token-)
-  - [Native Converter](#native-converter-)
+- One Primary Chain
+  - [Vault Bridge Token](#vault-bridge-token)
+  - [Migration Manager](#migration-manager)
+- Many Secondary Chains
+  - [Custom Token](#custom-token)
+  - [Native Converter](#native-converter)
 
-### Vault Bridge Token [↗](src/VaultBridgeToken.sol)
+### TL;DR
 
-A Vault Bridge Token is an
+Select assets are bridged from Primary Chain to Secondary Chain. These assets are deposited into Vault Bridge Token contract on Primary Chain, which mints and bridges vbToken to Secondary Chain. Deposited assets are used to generate yield on Primary Chain, while bridged vbTokens are used in DeFi on Secondary Chain. Generated yield gets distributed to chains and apps participating in the revenue sharing program.
+
+Native Converter contract can be deployed on Secondary Chain to enable acquisition of vbToken on Secondary Chain without having to bridge from Primary Chain. Accumulated backing in Native Converter on Secondary Chain gets migrated to Primary Chain and deposited into Vault Bridge Token contract.
+
+### Vault Bridge Token
+
+A Vault Bridge Token is:
 
 - [ERC-20](https://eips.ethereum.org/EIPS/eip-20) token
 - [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) vault
-- [LxLy Bridge](https://github.com/0xPolygonHermez/zkevm-contracts) extension
+- [Agglayer Bridge](https://github.com/agglayer/agglayer-contracts) extension
 
-enabling bridging of select assets, such as WBTC, WETH, USDT, USDC, and USDS, while producing yield.
+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 Secondary Chain via Native Converter, with backing migration to Primary Chain via Migration Manager.
 
-### Migration Manager (singleton) [↗](src/MigrationManager.sol)
+### Migration Manager
 
-The Migration Manager is a
+The Migration Manager is:
 
-- [Vault Bridge Token](#vault-bridge-token-) dependency
+- [Vault Bridge Token](#vault-bridge-token) dependency
 
-handling migration of backing from Native Converters.
+vbTokens can be minted directly on Secondary Chain. In order for an underlying asset that backs vbToken minted on Secondary Chain to be deposited in Vault Bridge Token contract on Primary Chain, backing is migrated to Primary Chain 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 [↗](src/CustomToken.sol)
+### Custom Token
 
-A Custom Token is an
+A Custom Token is:
 
 - [ERC-20](https://eips.ethereum.org/EIPS/eip-20) token
 
-an upgrade for [LxLy Bridge](https://github.com/0xPolygonHermez/zkevm-contracts)'s generic wrapped token.
+Bridged vbToken can be upgraded to Custom Token on Secondary Chain. This enables custom behavior, such as bridged vbETH to integrate WETH9 interface, replacing WETH on Secondary Chain.
+
+### Native Converter
+
+A Native Converter is:
 
-### Native Converter [↗](src/NativeConverter.sol)
+- [Vault Bridge Token](#vault-bridge-token) extension
+- [Agglayer Bridge](https://github.com/agglayer/agglayer-contracts) extension
 
-A Native Converter is a
+Native Converter can be deployed on Secondary Chain to enable minting of vbToken directly on Secondary Chain 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 Secondary Chain can be migrated to Primary Chain to be deposited into Vault Bridge Token contract via Migration Manger. For this reason, liqudity for deconverting to the bridged underlying token on Secondary Chain 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.
 
-- pseudo [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) vault
-- [LxLy Bridge](https://github.com/0xPolygonHermez/zkevm-contracts) extension
+## Get Started
 
-allowing conversion to, and deconversion of, Custom Token, as well as migration of backing to Vault Bridge Token.
+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](#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](https://info.polygon.technology/vaultbridge-intake-form) 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](https://info.polygon.technology/vaultbridge-intake-form) 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](https://info.polygon.technology/vaultbridge-intake-form) to register interest.
 
 ## Documentation
 
-Please see NatSpec documentation inside of the files.
+- [General Documentation](https://docs.agglayer.dev/)
+- [Technical Reference](https://agglayer.github.io/vault-bridge/)
+- [Source Code](https://github.com/agglayer/vault-bridge/tree/main/src): In addition to General Documentation and Technical Reference, the Source Code is 100% documented and you are encouraged to take a look.
+  - Pay attention to the following bookmarks: `@note CAUTION!`, `@note IMPORTANT:`, `@note (ATTENTION)`.
+
+## Deployments
 
-Please see `@note` documentation for important information.
+See [`broadcast/README.md`](https://github.com/agglayer/vault-bridge/blob/main/broadcast/README.md).
 
 ## Usage
 
-#### Prerequisite
+Clone:
 
 ```
-foundryup
+git clone [email protected]:agglayer/vault-bridge.git
 ```
 
-#### Install
+Install:
 
 ```
 forge soldeer install & npm install
 ```
 
-#### Build
+Build:
 
 ```
 forge build
 ```
 
-#### Test
+Test:
 
 ```
 forge test
 ```
 
-#### Coverage
+Coverage:
 
 ```
 forge coverage --ir-minimum --report lcov && genhtml -o coverage lcov.info
 ```
 
 ## License
 
-This codebase is licensed under a dual license model:
+This codebase is licensed under Source Available License.
 
-1. Open Attribution License – this license is similar to the MIT License and permits broad 
-use (including for commercial purposes), but is only available when the codebase is used in 
-connection with cryptoasset deposits into the Agglayer’s unified LxLy bridge. See: [LICENSE-OPEN-LICENSE](<LICENSE-OPEN-LICENSE>)
-2. Source Available License – for all other use cases, including cryptoasset deposits into 
-elsewhere than the Agglayer’s unified LxLy bridge, you may use the codebase under the Source 
-Available License. See: [LICENSE-SOURCE-AVAILABLE-LICENSE](<LICENSE-SOURCE-AVAILABLE-LICENSE>)
+See [`LICENSE-SOURCE-AVAILABLE`](https://github.com/agglayer/vault-bridge/blob/main/LICENSE-SOURCE-AVAILABLE).
 
-Your use of this software constitutes acceptance of these license terms. If you are unsure whether
-your use qualifies under the Open Attribution license, please contact: [email protected]
+Your use of this software constitutes acceptance of these license terms.