Skip to content

Commit 0eeaa86

Browse files
pete-vielhaberpete-vielhaber
authored
Merge branch 'master' into docs-bold-updates
2 parents ed4c546 + 57e3a44 commit 0eeaa86

File tree

2 files changed

+200
-207
lines changed

2 files changed

+200
-207
lines changed

‎arbitrum-docs/launch-orbit-chain/02-configure-your-chain/advanced-configurations/02-fast-withdrawals.mdx‎

Lines changed: 200 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,202 @@
11
---
2-
title: 'Fast withdrawals'
3-
description: 'Learn how to configure fast withdrawals on your Orbit chain'
4-
author:
5-
sme:
6-
content_type: how-to
2+
title: 'Enable fast withdrawals on your Orbit chain'
3+
sidebar_label: 'Enable fast withdrawals'
4+
description: 'Learn to deploy Fast Withdrawals'
5+
author: coopermidroni, tucksondev
6+
sme: tucksondev
7+
user_story: As a current or prospective Orbit chain owner, I need to understand how to integrate with the Fast Withdrawal feature.
8+
content_type: get-started
79
---
10+
11+
Optimistic Rollups must sustain a multi-day challenge period to allow time for fraud proofs. This delays finality for users and dApps, resulting in multi-day withdrawal times and cross-chain communication delays.
12+
13+
Fast withdrawals is a new configuration allowing Orbit chains to achieve fast finality. When an Orbit chain operates on Fast Withdrawals, its transactions will be processed by a committee of validators. Transactions reaching a unanimous vote across the committee will be immediately confirmed.
14+
15+
This will allow:
16+
17+
- Setting up a withdrawal frequency of any time period (up to 15 minutes)
18+
- Users' withdrawals confirmation on the parent chain at frequencies up to ~15 minutes
19+
- Cross-chain dApps to read the finalized state at the same rate as the fast withdrawal frequency
20+
21+
## Recommended configuration
22+
23+
While any Orbit chain can adopt Fast Withdrawals, we only _recommend_ that fast withdrawals be adopted by AnyTrust chains with a minimum validator and DAC member requirement. We explain both these recommendations below:
24+
25+
### Fast withdrawals for AnyTrust chains
26+
27+
As AnyTrust chains are an optimum (an optimistic rollup using a separate data availability layer), AnyTrust chains are already placing a trust assumption on their Data Availability Committee (DAC) to provide the data needed for fraud proofs and recreating the chain.
28+
29+
The optimal setup for an AnyTrust chain is to have all DAC members _also_ run validators as part of the fast withdrawals committee. This will leverage the existing trust assumption placed on the DAC operators such that **enabling fast withdrawals does not add any new trusted parties.**
30+
31+
It is possible for an Orbit Rollup to adopt fast withdrawals. However, it would technically no longer be a Rollup as the minimum trust assumption will shift to the trust placed in the Fast Confirmations committee.
32+
33+
### Minimum validator and DAC nodes
34+
35+
We recommend that any Fast Withdrawals-enabled chain have at least three DAC members and three validators acting in the fast withdrawals committee. Given that fast withdrawals will enable confirmation of new Rollup state much faster than the usual 6.4-day challenge period (15 minutes for L2s and 15 seconds for L3s), it becomes even more important to have additional parties involved in validation to further reduce trust assumptions. This requirement can be be met with three total operators, who each run a single DAS node and a single validator.
36+
37+
## Technical lower bound for fast withdrawals
38+
39+
Once fast withdrawals is enabled, the committee will confirm transactions at the configured frequency. However, a higher network load can cause the fast withdrawals committee to experience slight delays from the configured rate.
40+
41+
- For low-to-medium activity chains (< 1 Mgas/s), 15 seconds is considered to be the sustained lower bound for Fast Withdrawals.
42+
- For chains with higher throughput (>1 Mgas/s), the practical lower bound for fast withdrawals is between 1-2 minutes.
43+
44+
Chain owners and operators should be aware that the fast withdrawals committee may take longer to confirm new assertions under conditions with greater network load. This behavior is to be expected and does not interfere with the security or trust model of the fast withdrawals committee.
45+
46+
## Practical lower bounds concerning parent chain finality
47+
48+
While a fast withdrawals-enabled chain can be configured to finality in as little as 15 seconds, there are externalities on the parent chain and from cross-chain messaging layers that must be considered.
49+
50+
For an Ethereum-based Layer-2, we recommend that the fast withdrawal frequency remain above 12.8 minutes, which is the time for Ethereum to achieve finality. For non-Ethereum L1s, we similarly recommend staying above the accepted finality threshold specific to that L1.
51+
52+
For an Arbitrum One-based Layer-3, there are three tiers of finality to consider:
53+
54+
1. Soft finality from the sequencer's confirmation of transaction inclusion (~250ms)
55+
2. Safe finality from batch inclusion after Arbitrum One's assertion is included in an Ethereum block.
56+
3. Hard finality after the Ethereum block containing Arbitrum One's batch is finalized on Ethereum (~15 minutes)
57+
58+
Layer-3 Orbit chains can make their own determination about what level of finality to accept. We consider it safe to rely on soft finality, which would practically enable an Orbit chain to configure fast withdrawals down to 15 seconds.
59+
60+
## Adoption instructions (example script)
61+
62+
To enable the fast withdrawals feature, there are three actions to take:
63+
64+
1. Make sure the chain is using nitro-contracts v2.1.0 or above
65+
2. Activate the fast withdrawals feature
66+
3. Upgrade the node software to nitro v3.1.2 or above
67+
68+
### Upgrading to nitro-contracts v2.1.0
69+
70+
As mentioned above, the fast withdrawals feature is available for chains that are using nitro-contracts v2.1.0 or above, especially the `RollupAdminLogic` and the `RollupUserLogic` contracts. You can check what nitro-contracts version your chain is using by running the [orbit versioner script](https://github.com/OffchainLabs/orbit-actions/blob/main/README.md#check-version-and-upgrade-path).
71+
72+
If your chain is not running with nitro-contracts v2.1.0 or above, you’ll need to perform an upgrade to enable this version. The [orbit versioner script](https://github.com/OffchainLabs/orbit-actions/blob/main/README.md#check-version-and-upgrade-path) will provide the upgrade paths needed to reach v2.1.0, but basically:
73+
74+
- If the chain is running nitro-contracts v1.1.x, you need to [upgrade first to v1.2.1](https://github.com/OffchainLabs/orbit-actions/blob/main/scripts/foundry/contract-upgrades/1.2.1/README.md).
75+
- If the chain is running nitro-contracts v1.2.1, you need to [upgrade to v2.1.0](https://github.com/OffchainLabs/orbit-actions/blob/main/scripts/foundry/contract-upgrades/2.1.0/README.md).
76+
77+
Upgrading to the new nitro-contracts version also requires updating the node software. For v2.1.0, validator nodes and the batch poster node should run [nitro v3.1.2](https://github.com/OffchainLabs/nitro/releases/tag/v3.1.2) or above.
78+
79+
Suppose you’re upgrading your nitro-contracts from v1.2.1 to v2.1.0 and using the standard WASM module root (without customizations). In that case, there are [action contracts available in the supported chains](https://github.com/OffchainLabs/orbit-actions/blob/main/scripts/foundry/contract-upgrades/2.1.0/README.md#deployed-instances). If you’re using a customized nitro software, with a different WASM module root, you can still deploy the action contract referencing your modified WASM module root (pre and post upgrade).
80+
81+
### Activating fast withdrawals
82+
83+
Once the chain runs nitro-contracts v2.1.0 or above, the new fast withdrawal parameters will be available in the `RollupAdminLogic` and the `RollupUserLogic` contracts.
84+
85+
Both the Orbit SDK and the Orbit actions repository provide configurable scripts to activate and configure fast withdrawals on an AnyTrust chain. You can use either of those to activate the feature. Both scripts perform the same actions.
86+
87+
<aside>
88+
ℹ️ Even though two scripts are available to activate Fast Withdrawals, you only need to execute
89+
one of them. Both scripts perform the same actions.
90+
</aside>
91+
92+
**Orbit SDK script**
93+
94+
The Orbit SDK provides an [example script](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/setup-fast-withdrawal) to set up a fast withdrawal committee by performing the following operations:
95+
96+
1. Create a new n/n Safe wallet with the specified validators as signers
97+
2. Add the specified validators to the Rollup validators allowlist
98+
3. Set the new Safe wallet as the `anytrustFastConfirmer` in the Rollup contract
99+
4. Set the new `minimumAssertionPeriod` if needed
100+
5. Show how to configure the batch poster and validator nodes
101+
102+
To configure the script, you need to specify the following environment variables:
103+
104+
| Variable Name | Description |
105+
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106+
| `CHAIN_OWNER_PRIVATE_KEY` | Private key of the account with executor privileges in the UpgradeExecutor admin contract for the chain. It will be the deployer of the multi-sig Safe wallet. |
107+
| `PARENT_CHAIN_ID` | ChainId of the parent chain. |
108+
| `ROLLUP_ADDRESS` | Address of the Rollup contract. |
109+
| `FC_VALIDATORS` | Array of fast-withdrawal validators. They will be added as signers to the multisig Safe wallet and to the Rollup's validator allowlist. It is recommended that these are DAC members of the AnyTrust chain. |
110+
| `MINIMUM_ASSERTION_PERIOD` | Optional parameter that defaults to 75 blocks (~15 minutes). Minimum number of blocks that have to pass in between assertions (measured in L1 blocks). |
111+
112+
Finally, follow these steps to execute the script (from the `examples/setup-fast-withdrawal` folder):
113+
114+
1. Install dependencies
115+
116+
```shell
117+
yarn install
118+
```
119+
120+
2. Create a .env file and add the env vars
121+
122+
```shell
123+
cp .env.example .env
124+
```
125+
126+
3. Run the script
127+
128+
```shell
129+
yarn run dev
130+
```
131+
132+
**Orbit actions script**
133+
134+
The Orbit actions repository also provides an [action script](https://github.com/OffchainLabs/orbit-actions/blob/main/scripts/foundry/fast-confirm/README.md) to activate fast withdrawals by performing the following operations:
135+
136+
1. Make sure the "Validate fast confirmation" has not been enabled yet
137+
2. Create a Safe contract for the fast confirmation committee
138+
3. Set the Safe contract as the fast confirmer on the Rollup
139+
4. Set the Safe contract as a validator on the Rollup
140+
5. Set `setMinimumAssertionPeriod` to 1 block to allow more frequent assertion
141+
142+
To configure the action script, you need to specify the following environment variables:
143+
144+
| Variable Name | Description |
145+
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
146+
| `UPGRADE_ACTION_ADDRESS` | Address of the upgrade action to execute. A standard version is deployed in all [supported chains](https://github.com/OffchainLabs/orbit-actions/blob/main/scripts/foundry/fast-confirm/README.md#deployed-instances). If you need to deploy your own action, execute the first step of [this process](https://github.com/OffchainLabs/orbit-actions/blob/main/scripts/foundry/fast-confirm/README.md#how-to-use-it). |
147+
| `PARENT_UPGRADE_EXECUTOR_ADDRESS` | Private key of the account with executor privileges in the UpgradeExecutor admin contract on the parent chain. It will be the deployer of the multi-sig Safe wallet. |
148+
| `PARENT_CHAIN_RPC` | RPC endpoint of the parent chain. |
149+
| `ROLLUP` | Address of the Rollup contract. |
150+
| `FAST_CONFIRM_COMMITTEE` | Comma-separated list of fast-withdrawal validators. They must be allowlisted validators in the Rollup contract. They will be added as signers to the multisig Safe wallet. It is recommended that these are DAC members of the AnyTrust chain. |
151+
152+
Finally, follow these steps to execute the script (from the `scripts/foundry/fast-confirm` folder):
153+
154+
1. Install dependencies
155+
156+
```shell
157+
yarn install
158+
```
159+
160+
2. Create a .env file and add the env vars
161+
162+
```shell
163+
cp .env.example .env
164+
```
165+
166+
3. Execute the action. The upgrade can be executed using  `cast`  CLI command ([cast is a part of the Foundry tools](https://book.getfoundry.sh/cast/)), using the owner account (the one with executor rights on parent chain `UpgradeExecutor`) to send the transaction:
167+
168+
```shell
169+
(export $(cat .env | xargs) && cast send $PARENT_UPGRADE_EXECUTOR_ADDRESS "execute(address, bytes)" $UPGRADE_ACTION_ADDRESS $(cast calldata "perform(address, address[])" $ROLLUP \[$FAST_CONFIRM_COMMITTEE\]) --rpc-url $PARENT_CHAIN_RPC --account EXECUTOR)
170+
# use --account XXX / --private-key XXX / --interactive / --ledger to set the account to send the transaction from
171+
```
172+
173+
**NOTE:** If you have a multisig as executor, you can use the following command to create the payload for calling into the `PARENT_UPGRADE_EXECUTOR`:
174+
175+
```shell
176+
(export $(cat .env | xargs) && cast calldata "execute(address, bytes)" $UPGRADE_ACTION_ADDRESS $(cast calldata "perform(address, address[])" $ROLLUP \[$FAST_CONFIRM_COMMITTEE\]))
177+
```
178+
179+
### Configure fast withdrawal on nitro v3.1.2 or above
180+
181+
To be able to use Fast Withdrawal on your chain, the batch poster and the validators of the chain need to be running [nitro v3.1.2](https://github.com/OffchainLabs/nitro/releases/tag/v3.1.2) or above.
182+
183+
The following parameters need to be configured in those nodes.
184+
185+
**Batch poster**
186+
187+
| Option | Description |
188+
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
189+
| `--node.batch-poster.max-delay=0h15m0s` | Since batches need to be posted so validators can create and confirm assertions, the maximum delay should be set to an amount close to the `minimumAssertionPeriod` defined in the Rollup contract. Modify `0h15m0s` to the configured value. |
190+
191+
**Validators**
192+
193+
| Option | Description |
194+
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195+
| `--node.staker.enable-fast-confirmation=true` | Enables fast withdrawals in the validator node |
196+
| `--node.staker.make-assertion-interval=0h15m0s` | Since assertions need to be created for them to be confirmed, the minimum interval to create these assertions should be set to an amount close to the `minimumAssertionPeriod` defined in the Rollup contract. Modify `0h15m0s` to the configured value. |
197+
198+
:::note
199+
200+
Immediately after configuring fast withdrawals - your chain may not be operating fully at speed yet. This is because the validators have to work through the backlog of assertions which were not yet confirmed. You will see a series of NodeCreated and NodeConfirmed events. Once the backlog has been processed, your chain should operate fully at speed.
201+
202+
:::

0 commit comments

Comments
 (0)