StarkGate functions and events

​

L1 functions and events

​

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
• Function: deposit
• Event: Deposit

---

​

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
• Function: depositCancelRequest
• Event: DepositCancelRequest

---

​

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

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
• Function: depositReclaim
• Event: DepositReclaimed

​

See also

• depositCancelRequest

---

​

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
• Function: depositWithMessage
• Event: DepositWithMessage

---

​

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
• Function: depositWithMessageCancelRequest
• Event: DepositWithMessageCancelRequest

​

See also

• depositWithMessage
• depositCancelRequest

---

​

depositWithMessageReclaim

​

Description

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

DepositWithMessageReclaimed 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
• Function: depositWithMessageReclaim
• Event: DepositWithMessageReclaimed

​

See also

• depositCancelRequest
• depositReclaim
• depositWithMessageCancelRequest

---

​

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.

​

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

• Function: enrollTokenBridge in StarkgateManager.sol
• Event: TokenEnrollmentInitiated in StarknetTokenBridge.sol

---

​

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

• deposit
• depositWithMessage

---

​

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

• enrollTokenBridge

---

​

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.

​

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.

​

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
• Function: withdraw
• Event: Withdrawal

​

L2 functions and events

​

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.

​

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.