StarkGate bridge

StarkGate general architecture

StarkGate is the Ethereum↔Starknet token bridge developed by StarkWare. Each supported token is associated with an L1 and L2 bridge contract that is communicating via Starknet’s messaging mechanism.

The bridges facilitate a user’s ability to conduct their transactions with their ETH and ERC-20 tokens that reside on L1, via the Starknet Alpha network and its STARK-based computational compression capabilities.

For simplicity, we use terms such as “deposit”, “transact”, and “transfer” to refer to various operations involving a bridge, even though ETH and ERC20 tokens never actually leave Ethereum.

StarkGate Alpha limitations

In order to reduce the risks involved in using an Alpha version, StarkGate Alpha on Mainnet has limitations involving the deposit amount and total value locked in the L1 bridge contract:

Token	Max total value locked
ETH	150,000 ETH
WBTC	200 WBTC
USDC	40,000,000 USDC
USDT	20,000,000 USDT
DAI	5,000,000 DAI
rETH	10,000 rETH
wstETH	5,000 wstETH

Token

Max total value locked

ETH

150,000 ETH

WBTC

200 WBTC

USDC

40,000,000 USDC

USDT

20,000,000 USDT

DAI

5,000,000 DAI

rETH

10,000 rETH

wstETH

5,000 wstETH

We plan to gradually ease these limitations and lift them completely, as confidence grows. Changes will be updated here, stay tuned.

L1→L2 transfer (deposit)

Step 1: Call the deposit function on L1

The user calls the function deposit (see ERC-20 deposit and ETH deposit), supplying as parameters the recipient address on Starknet and the amount to transfer in the case of ERC-20 token. The deposit function then:

Checks that the funds transferred are within the Alpha limitations
Transfers the funds from the user account to the Starknet bridge
Emits a deposit event with the sender address on L1, the recipient address on L2, and the amount
Sends a message to the relevant L2 bridge with the amount to be transferred, and the recipient address as parameters. Note that, since every single bridge is dedicated to one token type, the token type doesn’t have to be explicit here.

At the end of this step (i.e., after the execution on L1) the deposit transaction is known to Starknet’s sequencer, yet sequencers may wait for enough L1 confirmations before the corresponding deposit transaction is initiated on L2. During this step, the status of the L2 deposit transaction is NOT_RECEIVED.

Step 2: deposit triggered on Starknet

Once enough block confirmations are received for step 1, the sequencers may refer to the deposit request by triggering the L1 handler using the handle_deposit function on the L2 bridge.

The function handle_deposit verifies that the deposit indeed came from the corresponding L1 bridge. It then calls to the relevant ERC-20 contract (e.g. the ERC-20 representing ETH on Starknet) and mints the tokens for the user.

At the end of this step (i.e., after the sequencer processed this transaction, but before a proof is generated), the status of the deposit request will be ACCEPTED_ON_L2.

Step 3: The block that includes the transfer is proved

Once the sequencer completes the block construction, Starknet’s provers will prove its validity and submit a state update to L1.

When this happens, the message confirming the funds transfer will be cleared from the Starknet Core Contract, and the fact that the user has transferred their funds will be part of the now finalized state of Starknet.

Note that if the message wasn’t on L1 to begin with (meaning Starknet “invented” a deposit request), the state update would fail.

L2→L1 transfer (withdraw)

Step 1: Call the withdraw function on L2

To initiate a withdraw, a user calls the initiate_withdraw function on the L2 bridge contract, supplying as parameters the recipient address on Ethereum, as well as the amount to transfer. The withdraw function then:

Burns the transferred amount of tokens from the balance of the withdrawal’s initiator
Sends a message to the relevant L1 bridge with the amount to be transferred, and the recipient address as parameters. As before, since the bridges are token-specific, the token itself is implicit here.

Step 2: The block that includes the transaction is proved

Once the sequencer completes the block construction, Starknet’s provers will prove the validity of the block and submit a state update to L1. When this happens, the message from the previous step is stored in the Starknet Core Contract.

Step 3: Transfering the funds on L1

After the withdraw message has been recorded on the Starknet Core Contract, anyone can finalize the transfer on L1 from the bridge back to the user, by calling the withdraw function (see ERC-20 withdraw and ETH withdraw).

This step is permissionless, and may be performed by anyone. Since the user’s address is part of the recorded message on L1, he will be the recepient of the funds, regardless of who called the withdraw function on L1.