Frequently asked questions
Why are alternative transactions necessary?
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
What is an alternative transaction?
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
How do I handle a request for an alternative transaction?
Send a list of zero or more alternative transactions in
I received a
REPLACED_BEFORE message. What should I do?
What is the difference between
Layer 2: The StarkEx API and SDK
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
Layer 1: StarkEx Contracts
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
Why can’t I query the balance of a certain vault on StarkEx?
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
Where and when is a particular vault assigned a Stark key?
The StarkEx service generates an ID for a vault the first time that you specify a 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 Stark key.
If, when a vault receives a transaction, the vault is not empty, you cannot assign it a new Stark key.
An empty vault has a balance of 0.
An empty vault has no owner. You can reassign it.
How do I use the testing environment for both developing and QA testing?
To work in parallel on the same environment, allocate one range of vaults for development, and another range for testing.
How do I know that a transaction was accepted by the StarkEx gateway?
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.
What should I do when the transaction is not accepted by the StarkEx gateway?
Review the error message that you received and act accordingly.
What should I do when a transaction was not included in the StarkEx L1 state update?
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.