Skip to main content

Enable fast withdrawals on your Orbit chain

Optimistic Rollups must sustain a multi-day challenge period to allow time for fraud proofs. This delays finality for users and apps, resulting in multi-day withdrawal times and cross-chain communication delays.

Fast Withdrawals is a new configuration allowing Orbit chains to achieve fast finality. When an Orbit chains 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.

Fast Withdrawals the following:

Orbit chains can configure a fast withdrawal frequency of any time period (up to 15 minutes)

  • Users' withdrawals are confirmed on the parent chain at frequencies up to ~15 minutes
  • Cross-chain apps can read the finalized state at the same rate as the fast withdrawal frequency

While any Orbit chain can adopt Fast Withdrawals, we only recommend Fast Withdrawals for AnyTrust chains.

This is because AnyTrust chains, as an optimum, already have a minimum trust assumption placed in their Data Availability Committee (DAC) - which allows their nodes to provide data availability.

We recommend that Orbit chains built on AnyTrust set up their Fast Withdrawals Committee such that a

  • The optimal setup for an AnyTrust chain is to have all DAC members also run validators as part of the Fast Withdrawals committee, which leverages the existing trust assumption on the DAC. This means enabling Fast Withdrawals does not add any new trusted parties.

An Orbit rollup can 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.

Adoption Instructions (Example Script)​

To enable the Fast Withdrawals feature, there are three actions to take:

  1. Make sure the chain is using nitro-contracts v2.1.0 or above
  2. Activate the Fast Withdrawals feature
  3. Upgrade the node software to nitro v3.1.1 or above

Upgrading to nitro-contracts v2.1.0​

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.

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 will provide the upgrade paths needed to reach v2.1.0, but basically:

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 be running nitro v3.1.1 or above.

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. 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).

Activating Fast Withdrawals​

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.

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.

Orbit SDK script

The Orbit SDK provides an example script to set up a fast withdrawal committee by performing the following operations:

  1. Create a new n/n Safe wallet with the specified validators as signers
  2. Add the specified validators to the Rollup validators allowlist
  3. Set the new Safe wallet as the anytrustFastConfirmer in the Rollup contract
  4. Set the new minimumAssertionPeriod if needed
  5. Show how to configure the batch poster and validator nodes

To configure the script, you need to specify the following environment variables:

Variable NameDescription
CHAIN_OWNER_PRIVATE_KEYPrivate 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.
PARENT_CHAIN_IDChainId of the parent chain.
ROLLUP_ADDRESSAddress of the Rollup contract.
FC_VALIDATORSArray 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.
MINIMUM_ASSERTION_PERIODOptional parameter that defaults to 75 blocks (~15 minutes). Minimum number of blocks that have to pass in between assertions (measured in L1 blocks).

Finally, follow these steps to execute the script (from the examples/setup-fast-withdrawal folder):

  1. Install dependencies
yarn install
  1. Create a .env file and add the env vars
cp .env.example .env
  1. Run the script
yarn run dev

Orbit actions script

The Orbit actions repository also provides an action script to activate fast withdrawals by performing the following operations:

  1. Validate fast confirmation has not been enabled yet
  2. Create a Safe contract for the fast confirmation committee
  3. Set the Safe contract as the fast confirmer on the Rollup
  4. Set the Safe contract as a validator on the Rollup
  5. Set setMinimumAssertionPeriod to 1 block to allow more frequent assertion

To configure the action script, you need to specify the following environment variables:

Variable NameDescription
UPGRADE_ACTION_ADDRESSAddress of the upgrade action to execute. A standard version is deployed in all supported chains. If you need to deploy your own action, execute the first step of this process.
PARENT_UPGRADE_EXECUTOR_ADDRESSPrivate 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.
PARENT_CHAIN_RPCRPC endpoint of the parent chain.
ROLLUPAddress of the Rollup contract.
FAST_CONFIRM_COMMITTEEComma-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.

Finally, follow these steps to execute the script (from the scripts/foundry/fast-confirm folder):

  1. Install dependencies
yarn install
  1. Create a .env file and add the env vars
cp .env.example .env
  1. Execute the action. Upgrade can be executed using the cast CLI command (part of Foundry installation), using the owner account (the one with executor rights on parent chain UpgradeExecutor) to send the transaction:
(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)
# use --account XXX / --private-key XXX / --interactive / --ledger to set the account to send the transaction from

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:

(export $(cat .env | xargs) && cast calldata "execute(address, bytes)" $UPGRADE_ACTION_ADDRESS $(cast calldata "perform(address, address[])" $ROLLUP \[$FAST_CONFIRM_COMMITTEE\]))

Configure Fast Withdrawal on nitro v3.1.1 or above​

To be able to use Fast Withdrawal in your chain, the batch poster and the validators of the chain need to be running nitro v3.1.1 or above.

The following parameters need to be configured in those nodes.

Batch poster

  • --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.

Validators

  • --node.staker.enable-fast-confirmation=true
    • Enables fast withdrawals in the validator node
  • --node.staker.fast-confirm-safe-address=<address of the Safe deployed>
    • Configures the node to sign the transaction on the Safe wallet that acts as the fast confirmer
  • --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.