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:

  • vault balances

  • 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.

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 .json format.

I received a REPLACED_BEFORE message. What should I do?

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 batch_id?”

Where and when is a particular vault assigned a starkKey?

The StarkEx service generates an ID for a vault the first time that you specify a starkKey in any of the following types of transactions:

  • deposit to the vault

  • transfer to the vault

  • minting an asset within the vault

  • settlement

The vault ID is paired with the starkKey.

If, when a vault receives a transaction, the vault is not empty, you cannot assign it a new starkKey.

An empty vault has a balance of 0.

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.