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

​

Returns

None.

​

Emitted event

Deposit Event attributes

​

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

​

Returns

None.

​

Emitted event

DepositCancelRequest Event attributes

​

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

​

Returns

None.

​

Emitted event

DepositReclaimed Event attributes

​

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

​

Returns

None.

​

Emitted event

DepositWithMessage Event attributes

​

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

​

Returns

None.

​

Emitted event

DepositWithMessageCancelRequest Event attributes

​

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

​

Returns

None.

​

Emitted event

DepositWithMessageReclaimed Event attributes

​

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

​

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

​

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

​

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

​

Returns

​

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

​

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

​

Returns

​

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

​

Returns

​

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

​

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

​

Returns

​

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

​

State mutability

nonpayable

​

Returns

None.

​

Emitted event

Withdrawal Event attributes

​

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

​

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

​

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

​

Returns

​

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

​

Returns

​

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

​

Returns

​

Function definition

get_remaining_withdrawal_quota in token_bridge_interface.cairo

---

​

get_version

​

Description

Returns the current version of StarkGate.

​

Parameters

None.

​

Returns

​

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

​

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

​

Returns

​

Function definition

on_receive in receiver_interface.cairo.