StarkGate function and event reference

The StarkGate smart contracts include functions that you use to implement various flows in a dApp.

For information on the movement of funds between Ethereum and Starknet, see StarkGate bridge overview.

StarkGate 2.0 provides a contract that enables seamless backward compatibility with the previous version of StarkGate.

When you update the code in your contract, make sure that you use the most up-to-date versions of all StarkGate contracts.

The L1 functions and their interfaces, where available, are defined in the following smart contracts:

Contract Name Functions

StarkgateManager.sol

The StarkGate Manager.

Use the Manager to enroll a new token.

An interface is available through IStarkgateManager.sol.

StarkgateRegistry.sol

The StarkGate Registry.

Use the Registry to view the addresses of existing bridges and to stop servicing a specific token.

An interface is available through IStarkgateRegistry.sol.

StarknetTokenBridge.sol

The primary StarkGate bridge contract. The functions and events in this reference that provide the main user bridge functionality are defined in this contract.

IStarkgateService.sol

An interface to check if a contract is servicing a token.

The L2 functions and their interfaces, where available, are defined in the following smart contracts:

Contract Description Functions

token_bridge.cairo

The StarkGate bridge implementation on L2. This contract includes the standard functions for a token bridge.

An interface is available through token_bridge_interface.cairo.

L1 function reference

Functions are listed in alphabetical order.

deposit

Description

Deposits the specified amount of an ERC-20 token to the L1 StarkGate bridge contract.

The deposit function does the following:

  • Transfers the funds from the caller’s account to the Starknet bridge contract

  • Emits the Deposit event with the sender’s address on L1, the recipient’s address on L2, and the amount

Visibility

external

State Mutability

payable

Parameters

address token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 l2Recipient

The L2 address of the recipient.

Returns

None.

Emitted event

Deposit

Event attributes
address indexed sender

The L1 address of the account that sent the deposit.
address indexed token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 indexed l2Recipient

The L2 address of the recipient. The L2 address of the recipient.
uint256 nonce

The nonce for the L1 transaction.
uint256 fee

The Starknet fee sent with the transaction.

Function and event definitions

Contract: StarknetTokenBridge.sol

depositCancelRequest

Description

Sends a request to StarkGate to cancel a deposit.

You can send a cancellation request if the funds you transfer from L1 to L2 do not appear on L2 within a reasonable amount of time.

In order to guard against an attack on Starknet, it takes approximately five days to cancel a deposit. When StarkGate receives the cancellation request, a counter begins. When exactly five days have passed, and the funds still do not appear on L2, you can reclaim the deposit using the depositReclaim function.

The depositReclaim function can only be used once for any deposit cancellation request.

Visibility

external

State Mutability

nonpayable

Parameters

address token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 l2Recipient

The L2 address of the recipient.
uint256 nonce

The nonce of the deposit.

Returns

None.

Emitted event

DepositCancelRequest

Event attributes
address indexed sender

The L1 address of the account that sent the deposit.
address indexed token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 indexed l2Recipient

The L2 address of the recipient. The L2 address of the recipient.
uint256 nonce

The nonce of the deposit.

Function and event definitions

Contract: StarknetTokenBridge.sol

depositReclaim

Description

Reclaims a deposit after a five day period has passed from the time that StarkGate received a deposit cancellation request from the depositCancelRequest function.

Visibility

external

State Mutability

nonpayable

Parameters

address token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 l2Recipient

The L2 address of the recipient.
uint256 nonce

The nonce of the deposit.

Returns

None.

Emitted event

event DepositReclaimed

Event attributes
address indexed sender

The L1 address of the account that sent the deposit.
address indexed token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 indexed l2Recipient

The L2 address of the recipient. The L2 address of the recipient.
uint256 nonce

The nonce of the deposit.

Function and event definitions

Contract: StarknetTokenBridge.sol

See also

depositWithMessage

Description

Similar to deposit, with a message attached.

With this function, a deposit transaction can trigger subsequent actions. For example, you can deposit funds and include a message to transfer those funds to another address. depositWithMessage lets you execute these two separate transactions with a single user action.

After depositing to another recipient, the L1 handler in token_bridge.cairo calls the on_receive function in the contract of the recipient.

If on_receive returns true, then the on_receive function succeeded. If it returns false, or if it doesn’t return any value because the on_receive function is not implemented in the recipient contract, the operation fails and the transaction is reverted.

Visibility

external

State Mutability

payable

Parameters

address token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 l2Recipient

The L2 address of the recipient.
uint256[] calldata message

The message attached to the deposit.

Returns

None.

Emitted event

DepositWithMessage

Event attributes
address indexed sender

The L1 address of the account that sent the deposit.
address indexed token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 indexed l2Recipient

The L2 address of the recipient. The L2 address of the recipient.
uint256[] message

The message attached to the deposit.
uint256 nonce

The nonce for the L1 transaction.
uint256 fee

The Starknet fee sent with the transaction.

Function and event definitions

Contract: StarknetTokenBridge.sol

depositWithMessageCancelRequest

Description

Sends a request to StarkGate to cancel a deposit sent with depositWithMessage.

Similar to depositCancelRequest.

Visibility

external

State Mutability

nonpayable

Parameters

address token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 l2Recipient

The L2 address of the recipient.
uint256[] calldata message

The message attached to the deposit.
uint256 nonce

The nonce of the deposit.

Returns

None.

Emitted event

DepositWithMessageCancelRequest

Event attributes
address indexed sender

The L1 address of the account that sent the deposit.
address indexed token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 indexed l2Recipient

The L2 address of the recipient. The L2 address of the recipient.
uint256[] message

The message attached to the deposit.
uint256 nonce

The nonce for the L1 transaction.

Function and event definitions

Contract: StarknetTokenBridge.sol

See also

depositWithMessageReclaim

Description

Sends a request to StarkGate to cancel a deposit sent with depositWithMessage.

Similar to depositCancelRequest.

Reclaims a deposit sent with a message after a five day period has passed from the time that StarkGate received a deposit cancellation request from the depositWithMessageCancelRequest function.

Visibility

external

State Mutability

nonpayable

Parameters

address token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 l2Recipient

The L2 address of the recipient.
uint256 nonce

The nonce of the deposit.

Returns

None.

Emitted event

DepositWithMessageCancelRequest

Event attributes
address indexed sender

The L1 address of the account that sent the deposit.
address indexed token

The address of the contract for the desired token.
uint256 amount

The amount of the deposit.
uint256 indexed l2Recipient

The L2 address of the recipient. The L2 address of the recipient.
uint256[] message

The message attached to the deposit.
uint256 nonce

The nonce for the L1 transaction.

Function and event definitions

Contract: StarknetTokenBridge.sol

See also

enrollTokenBridge

Description

Creates a Starknet bridge for the specified ERC-20 token contract address in the multi-token bridge contracts and adds the token to the StarkGate Registry.

Does not work for any ERC-20 token bridge’s contract address that is already in the registry.

Enrolling a new bridge creates a new ERC-20 contract on L2. You can see the class hash for this contract using get_erc20_class_hash.

Enrolling a new bridge does not add it to the StarkGate GUI. You can use a block explorer to use the newly created bridge.

Visibility

external

State Mutability

payable

The message payload needs to include funds to cover the Starknet (L2) fee for executing this transaction. You can include this payload using a standard wrapper such as web3.js.

Parameters

address token

The address of the contract for the desired ERC-20 token.

Returns

None.

Emitted event

TokenEnrollmentInitiated

Function and event definition

estimateDepositFeeWei

Description

Returns an estimate of the fee, in Wei, for depositing funds to the L1 StarkGate bridge contract.

Visibility

external

State Mutability

view

Parameters

None.

Returns

uint256

An estimate of the fee, in Wei, for depositing funds to the L1 StarkGate bridge contract.

Emitted event

None.

Function definition

estimateDepositFeeWei in StarknetTokenBridge.sol

Additional resources

estimateEnrollmentFeeWei

Description

Returns an estimate of the fee, in Wei, for creating and registering a new bridge using the enrollTokenBridge function.

Visibility

external

State Mutability

view

Parameters

None.

Returns

uint256

An estimate of the fee, in Wei, for creating and registering a new bridge.

Emitted event

None.

Function definition

estimateEnrollmentFeeWei in StarknetTokenBridge.sol

Additional resource

getBridge

Description

Returns the address of the bridge for the specified token, or a value indicating if the bridge does not exist, is blocked, or is deactivated.

Visibility

external

State Mutability

view

Parameters

address token

The address of the contract for the desired ERC-20 token.

Returns

address address

The address of the bridge for the specified token.
Address(0)

The bridge does not exist.
Address(1)

The bridge is blocked or deactivated.

Emitted event

None.

Function definition

getBridge in IStarkgateRegistry.sol

getRegistry

Description

Returns the address of the StarkGate Registry contract.

Only the Manager uses this function.

Visibility

external

State Mutability

view

Parameters

None

Returns

address

The address of the Registry contract.

Emitted event

None.

Function definition

getRegistry in StarkgateManager.sol

getStatus

Description

Returns the status of a token in StarkGate.

deploy transaction triggered by the enrollTokenBridge API.

Visibility

external

State Mutability

view

Parameters

address token

The address of the contract for the desired ERC-20 token.

Returns

TokenStatus

One of the following values:

0

Unknown. The bridge does not recognize the token.
1

Pending. The token has been enrolled to StarkGate, but the deploy transaction has not yet successfully completed. You can deposit funds.
2

Active. The deploy transaction for this token has completed successfully and StarkGate recognizes the token.
3

Deactivated. The token has been removed from StarkGate. You cannot deposit funds.

Emitted event

None.

Function definition

getStatus in StarknetTokenBridge.sol

getWithdrawalBridges

Description

Retrieves a list of all bridge addresses that have ever facilitated withdrawals for the specified token.

In a case where an inactive bridge for a specific token might still have funds locked, you can use this function to identify all bridges that ever serviced that token.

If you used a bridge for a given token that subsequently was replaced with a new or updated bridge, but you still have funds locked on the first bridge, you might not know the address of the old bridge. This function returns

Visibility

external

State Mutability

view

Parameters

address token

The address of the contract for the desired token.

Returns

address[] memory bridges

An array of addresses of all bridges that ever serviced token.

Emitted event

None.

Function definition

getWithdrawalBridges in StarkgateRegistry.sol.

identify

Description

Returns the name and version of the StarknetTokenBridge.sol contract.

Visibility

external

State Mutability

pure

Parameters

None.

Returns

string memory

The name and version of the StarknetTokenBridge.sol contract.

Emitted event

None.

Function definition

identify in StarknetTokenBridge.sol

isServicingToken

Description

Checks whether the calling contract is currently providing a service for the specified token.

Visibility

external

State Mutability

view

Parameters

address token

The address of the contract for the desired token.

Returns

true

The calling contract is currently providing a service for the token.
false

The calling contract is not currently providing a service for the token.

Emitted event

None.

Function definition

isServicingToken in IStarkgateService.sol.

withdraw

Description

Transfers the specified amount of the specified token to the address of the recipient specified in the l1_recipient parameter of the initiate_token_withdraw function on L2.

Anyone can call this function, but only after the withdraw message has been recorded on the Starknet Core Contract.

Parameters

address token

The address of the contract for the desired token.
uint256 amount

The amount of the withdrawal.
address recipient

(Optional) The recipient. If you don’t specify this parameter, the withdraw function uses the sender’s address.

State mutability

nonpayable

Returns

None.

Emitted event

Withdrawal

Event attributes
address indexed recipient

The recipient.
address indexed token

The address of the contract for the desired token.
uint256 amount

The amount of the withdrawal.

Function and event definition

Contract: StarknetTokenBridge.sol

L2 function reference

Functions are listed in alphabetical order.

get_erc20_class_hash

Description

Returns the current class hash of the implementation used by the ERC-20 contract. Use the class hash as the type when deploying the ERC-20 contract on L2.

If StarkWare changes the class hash such that it is no longer the class hash that you used when deploying your bridge contract, this function returns the new class hash. If you want to refer to the class hash that you used when deploying your contract, see your deployed contract on Starknet.

Parameters

None.

Returns

ClassHash

The class hash of the ERC-20 token contract.

Function definition

get_erc20_class_hash in token_bridge.cairo.

get_identity

Description

Returns a string in a felt252 type with the identity of StarkGate.

Parameters

None.

Returns

felt252

The identity of StarkGate.

Function definition

get_identity in token_bridge_interface.cairo.

get_l1_token

Description

Returns the L1 address that corresponds to the matching L2 address of an ERC-20 token contract.

Parameters

l2_token_address: ContractAddress

The L2 address of the ERC-20 token contract.

Returns

EthAddress

The L1 address of the ERC-20 token contract.
EthAddressZeroable::zero()

The token is not found in the bridge.

Function definition

get_l1_token in token_bridge_interface.cairo.

get_l2_token

Description

Returns the L2 address that corresponds to the matching L1 address of an ERC-20 token contract.

If the token is not found in the bridge, this function returns 0.

Parameters

l1_token_address

The L1 address of the ERC-20 token contract.

Returns

ContractAddress address

The L2 address of the ERC-20 token contract.
ContractAddressZeroable::zero()

The token is not found in the bridge.

Function definition

get_l2_token in token_bridge_interface.cairo.

get_remaining_withdrawal_quota

Description

Returns the amount that the user can withdraw within the current 24-hour time period. The time period begins at 00:00 UTC.

Parameters

l1_token_address

The L1 address of the ERC-20 token contract.

Returns

u256

The amount that can currently be withdrawn from the bridge, in units defined by the ERC-20 token contract.

Function definition

get_remaining_withdrawal_quota in token_bridge_interface.cairo

get_version

Description

Returns the current version of StarkGate.

Parameters

None.

Returns

felt252

The current version of StarkGate.

Function definition

get_version in token_bridge_interface.cairo.

initiate_token_withdraw

Description

Initiates a withdrawal from L2. After initiating the withdrawal, the function does the following:

  1. Burns the transferred amount of tokens from the balance of the withdrawal’s initiator.

  2. Sends a message to the relevant L1 bridge with the amount to be transferred, and the recipient’s address.

Parameters

l1_token: EthAddress

The L1 address of the ERC-20 token contract.
l1_recipient: EthAddress

The L1 address of the recipient.
amount uint256

The amount to transfer.

Returns

None.

Function definition

initiate_token_withdraw in token_bridge_interface.cairo.

on_receive

Description

An interface to an implementation of the on_receive function that you must provide in your L2 contract in order to enable the depositWithMessage function to succeed.

The L2 contract that receives the message that is sent with the depositWithMessage function must implement a callback function named on_receive.

Upon completion, the depositWithMessage function triggers a call to the on_receive callback function on the receiving L2 contract. The on_receive function receives the deposit message as input, and it must return true for the deposit to succeed.

If on_receive returns false, or if the receiving contract does not implement on_receive, the depositWithMessage L1 handler fails, and the user can only recover their funds using the depositWithMessageCancelRequest function.

Parameters

l2_token: ContractAddress

The L2 address of the ERC-20 token contract.
amount: uint256

The amount deposited.
depositor: EthAddress

L1 address of the deposit sender.
message: Span<felt252>

The message that was sent with the depositWithMessage function.

Returns

true

The on_receive function completed successfully.
false

The on_receive function did not complete successfully. The transaction is reverted.
No value

If the recipients’s smart contract does not implement the on_receive function, the call fails to execute, and the transaction is reverted.

Function definition

on_receive in receiver_interface.cairo.