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
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
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
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
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
See also
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
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.
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
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.
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:
- 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’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.
