Skip to content

Document flow rate parameters for mainnet #114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ermyas merged 5 commits into from
May 28, 2025
Merged

Document flow rate parameters for mainnet #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f6ed685
Document flow rate parameters for mainnet
ermyas May 27, 2025
69eb4b0
Add envs for coverage job in CI
ermyas May 27, 2025
f9fa92b
Update code owners to entire Rollups team
ermyas May 27, 2025
4aabb93
Fix incorrect link for IMX and USDC
ermyas May 27, 2025
b5e9626
Add link to Perimeter's report
ermyas May 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/CODEOWNERS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
* @ermyas @wcgcyx @Benjimmutable
* @immutable/rollups
9 changes: 8 additions & 1 deletion .github/workflows/coverage.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,16 @@ env:

jobs:
check:
env:
DEPLOYMENTS: ${{ vars.DEPLOYMENTS }}
MAINNET_BRIDGE_ADDRESS: ${{ vars.MAINNET_BRIDGE_ADDRESS }}
MAINNET_FLOW_RATED_TOKENS: ${{ vars.MAINNET_FLOW_RATED_TOKENS }}
TESTNET_BRIDGE_ADDRESS: ${{ vars.TESTNET_BRIDGE_ADDRESS }}
TESTNET_FLOW_RATED_TOKENS: ${{ vars.TESTNET_FLOW_RATED_TOKENS }}
MAINNET_RPC_URL: ${{ secrets.MAINNET_RPC_URL }}
TESTNET_RPC_URL: ${{ secrets.TESTNET_RPC_URL }}
strategy:
fail-fast: true

name: Foundry project
runs-on: ubuntu-latest
steps:
Expand Down
21 changes: 18 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ ABIs for contracts can be obtained from the blockchain explorer links for each c
|-------------|-----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Wrapped ETH | [`0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2`](https://etherscan.io/token/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2) | [`0x7b79995e5f793a07bc00c21412e50ecae098e7f9`](https://sepolia.etherscan.io/address/0x7b79995e5f793a07bc00c21412e50ecae098e7f9) |
| IMX | [`0xf57e7e7c23978c3caec3c3548e3d615c346e79ff`](https://etherscan.io/token/0xf57e7e7c23978c3caec3c3548e3d615c346e79ff) | [`0xe2629e08f4125d14e446660028bd98ee60ee69f2`](https://sepolia.etherscan.io/address/0xe2629e08f4125d14e446660028bd98ee60ee69f2) |
| USDC | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) | [`0x40b87d235A5B010a20A241F15797C9debf1ecd01`](https://sepolia.etherscan.io/address/0x40b87d235A5B010a20A241F15797C9debf1ecd01) |
| USDC | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) | [`0x40b87d235A5B010a20A241F15797C9debf1ecd01`](https://sepolia.etherscan.io/address/0x40b87d235A5B010a20A241F15797C9debf1ecd01) |

### Child Chain
#### Core Contracts
Expand All @@ -166,8 +166,22 @@ ABIs for contracts can be obtained from the blockchain explorer links for each c
| Guild of Guardians (GOG) | [`0xb00ed913aAFf8280C17BfF33CcE82fE6D79e85e8`](https://explorer.immutable.com/address/0xb00ed913aAFf8280C17BfF33CcE82fE6D79e85e8) | TBA |

## Flow Rate Parameters
The [flow rate parameters](./docs/high-level-architecture.md#flow-rate-detection) configured for assets can be queried from the L1 bridge contract using a block explorer ([mainnet](https://etherscan.io/address/0xBa5E35E26Ae59c7aea6F029B68c6460De2d13eB6#readProxyContract), [testnet](https://sepolia.etherscan.io/address/0x0d3c59c779fd552c27b23f723e80246c840100f5#readProxyContract)).
The `flowRateBuckets()` function provides the bucket capacity and refill rate, while the `largeTransferThreshold()` function provides the withdrawal size threshold configured for a token.
The [flow rate parameters](./docs/high-level-architecture.md#flow-rate-detection) configured for assets on the Immutable zkEVM mainnet bridge are listed below.
- The *Flow Rate Capacity* is the maximum cumulative amount of a token that can be withdrawn within a 4-hour window. If the total amount of tokens withdrawn within this time window exceeds this threshold, the global withdrawal queue is activated. Consequently, all subsequent withdrawals for all tokens will be queued for 24 hours until the queue is manually deactivated.
- The *Large Withdrawal Threshold* is the size threshold for any single withdrawal of a token. If a withdrawal exceeds this amount, that particular withdrawal is queued for 24 hours on the bridge before it can be redeemed. This queuing does not affect other withdrawals by the same user or other users.

| Token Name | Flow-Rate Capacity (4-Hour Window) | Large Withdrawal Threshold |
|---------------------------------------------------------------------------------------|------------------------------------|----------------------------|
| Ethereum | 148 | 29.60 |
| [IMX](https://etherscan.io/token/0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF) | 539,052 | 107,230 |
| [USDC](https://etherscan.io/token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) | 372,000 | 74,000 |
| [USDT](https://etherscan.io/token/0xdAC17F958D2ee523a2206206994597C13D831ec7) | 372,000 | 74,000 |
| [wBTC](https://etherscan.io/token/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599) | 3.37 | 0.67 |
| [GODS](https://etherscan.io/token/0xccC8cb5229B0ac8069C51fd58367Fd1e622aFD97) | 2,310,559 | 459,627 |
| [GOG](https://etherscan.io/token/0x9AB7bb7FdC60f4357ECFef43986818A2A3569c62) | 9,386,828 | 1,867,272 |
| [Space Nation](https://etherscan.io/token/0x6e7f11641c1ec71591828e531334192d622703f7) | 15,000,000 | 220,000 |

These parameters can also be queried from the L1 bridge contract using a block explorer ([mainnet](https://etherscan.io/address/0xBa5E35E26Ae59c7aea6F029B68c6460De2d13eB6#readProxyContract), [testnet](https://sepolia.etherscan.io/address/0x0d3c59c779fd552c27b23f723e80246c840100f5#readProxyContract)). The `flowRateBuckets()` function provides the bucket capacity and refill rate, while the `largeTransferThreshold()` function provides the withdrawal size threshold configured for a token.
The L1 address of the token to query parameters for needs to be provided as input to both functions.
If flow rate parameters have not been configured for a token, these functions will return zero values.

Expand All @@ -176,3 +190,4 @@ The process to manually bridge funds from Ethereum to Immutable zkEVM by directl

## Audits
The Immutable token bridge has been audited by [Trail of Bits](https://www.trailofbits.com/). The audit report can be found [here](./audits/Trail-of-Bits-2023-12-14.pdf).
Additionally, the bridge has undergone comprehensive fuzzing and invariant testing conducted by [Perimeter](https://www.perimetersec.io/). The report can be found [here](./audits/Perimeter-Fuzzing-2024-09-10.pdf).
Loading