Frequently asked questions
When you integrate with the StarkEx system, your application should maintain its own state, in parallel with the StarkEx state, including the following:
unfulfilled or partially-fulfilled user orders
Your application’s state should provide your end users with a smooth experience, with little or no latency, which StarkEx, with its required L1 state updates, cannot provide. So your application should ensure that transactions that it submits to the StarkEx gateway are accepted before updating its own state, thus ensuring that both states are synchronized.
However, there are rare occurrences where despite a transaction being approved by the StarkEx gateway, it is subsequently rejected, often for reasons beyond your control. In such a case, the StarkEx state might diverge from the operator’s state.
In order to synchronize the two states when a transaction that was accepted by the gateway is rejected further down the pipeline, causing a state divergence, StarkEx requests that you send an alternative transaction to replace the failed transaction.
For more information, see Invalid transactions and alternative transactions
When StarkEx identifies an invalid transaction, StarkEx marks the transaction as invalid and sends a request to the application’s endpoint for a list of alternative transactions.
For more information, see Alternative transactions
Send a list of zero or more alternative transactions in
The StarkEx API and SDK only apply to L2.
The SDK and API use two different terms to refer to a unique asset on L2:
The StarkEx SDK uses the term
The StarkEx API uses the term
The StarkEx API does not include the keyword
Be aware that in the ERC-721 and ERC-1155 L1 StarkEx contracts, the terms
tokenId have slightly different meanings from those in the contracts for ERC-20, ETH, and mintable ERC-721 assets.
The value of
assetInfo is the address of the L1 contract for a given asset type. For example, for ERC-20 tokens, the value of
assetInfo is the address of the L1 ERC-20 contract.
There is no identifier for any one specific coin, unlike with ERC-721 or ERC-1155, because one unit of ETH or of an ERC-20 token has the same value as any other of the same type of token. StarkEx does not track individual assets of these types.
The StarkEx system calculates the value for
An NFT has two identifiers:
For example, consider two NFTs within two separate contracts:
So the value of
However, both Mitzy and Spot each have their own unique value for
The value for
This type of NFT is minted on L2. It does not exist on L1 until your user withdraws it from L2 to L1.
When your user withdraws the NFT from L2 to L1, you need to provide them with the
The value for
There is no API for this query because it normally is not reliable for synchronization between the StarkEx state and your applications’s state, for the following reasons:
StarkEx’s state is updated when a batch finishes processing. As a result, any transaction that is already accepted by StarkEx but not included in a batch is not reflected in this state.
In the event of an on-chain reorg, a batch for which a vault state is known might actually never become accepted on L1. So the only query we can answer is “What was the state of a vault at the end of a batch with ID
The StarkEx service generates an ID for a vault the first time that you specify a public Stark key in any of the following types of transactions:
deposit to the vault
transfer to the vault
minting an asset within the vault
The vault ID is paired with the public Stark key.
If, when a vault receives a transaction, the vault is not empty, you cannot assign it a new public Stark key.
An empty vault has a balance of 0.
An empty vault has no owner, that is, no public Stark key is assigned to the vault. So you can assign it an owner whether it has not yet been used, or it was in use and is now empty.
To work in parallel on the same environment, allocate one range of vaults for development, and another range for testing.
The StarkEx gateway returns a response to every request that it receives, including transactions. When it receives a transaction, it returns
When you receive this message, the gateway has accepted the transaction.
If you don’t receive this confirmation message, resend the transaction.
If you receive any other message, the transaction was not accepted.
Review the error message that you received and act accordingly.
If a transaction is accepted by the StarkEx gateway, but does not appear in the L1 state update, the following are possible reasons:
The batch has not finished processing.
The transaction failed during the batch processing. In this case, the StarkEx system sends a request for an alternative transaction.
If you don’t see a state update for a significant amount of time, check your logs for a message requesting an alternative transaction.