Integration

Search…
Integration
On this page, we describe the steps that are required in order to integrate an Application with StarkEx.
StarkEx Playground
Using StarkEx Playground is the first step that we recommend taking in order to get a hands-on experience of how StarkEx works and what the interfaces look like.
StarkEx playground is a StarkEx instance deployed on testnet that is open for everyone to try out StarkEx. It provides an easy-to-run demo of sending a pre-prepared list of transactions to StarkEx for beginners and an opportunity to build an Application and send your own transactions through StarkEx for more advanced users. 
Your own StarkEx Setup
Once you've decided that StarkEx is the solution that fits your application's requirements, we will spin up a new StarkEx instance just for you on testnet. On this setup you will be the only operator, so it will be under your full control and there won't be any resource collisions.
There are a few differences in this setup compared to the playground that you previously used.
1.On the playground, there was no guarantee that the vaultId that you chose for your transaction won't be taken by someone else. Now you are the only Operator and you manage the vaultId allocation as part of your Application.
2.On the playground, in order to get the next tx_id, you'll have to query StarkEx gateway and call get_first_unused_tx_id, this is needed since there are many users and they need to sync the next tx_id. Note that StarkEx won't process two transactions with the same tx_id and won't process a transaction if the previous sequential tx_id was not processed yet. On your own private setup, you don't need to query this parameter since you are the only one sending transactions and you manage the tx_id. You can send the transaction out of order but make sure you fill all the tx_id slots eventually; StarkEx will process the transactions by the order of their tx_id , so in case that one tx_id  is missing, StarkEx will stop proccessing and wait for it to be submitted. Moreover, since the gateway can process many transactions in parallel, it is not guaranteed to get the actual next unused tx_id, for that reason you must not use get_first_unused_tx_id at all on your own StarkEx setup. 
There are three additional components that you need to take care of in your environment:
1.Data Availability Committee - The objective of this interface is to make sure that the state you store in your DB (e.g. user's vaults) is perfectly synced with the state that StarkEx stores. We will not submit on-chain a new state without an approval (signature) from you that this is the correct state. So every time that a new batch of transactions is ready, you need to query StarkEx's Availability gateway, compute the new state - and approve it. Moreover, in Validium mode, other parties should also run this code as part of the data availability committee, which is important for the rainy day scenario where your server may stop responding and the users will need this data in order to withdraw their funds. 
Long story short, you can use this repository as a reference implementation of the code that queries and computes the state, you can use it, change it or write your own code according to your needs. There is also a hook there where you can add your own verification code to verify additional conditions on the state. You can run this code in a docker as explained in the repository documentation.
In order for you to be able to sign a new on-chain state update with the committee member that you just set up, we will ask you for your Ethereum public key and register it as a committee signer for this StarkEx instance.
2.Alternative transaction - 
Objective: Whenever an invalid transaction occurs in a batch, there is a risk that the following transactions in the same batch will become invalid as well since they may depend on the invalid transaction. This scenario can cause a cascading failure of transactions that may cause the system to get out of sync. In order to prevent this from happening, we offer the Application to replace an invalid transaction with a list of alternative transactions that will make up for the absence of the invalid transaction.
Transaction Verification on StarkEx: StarkEx gateway performs syntactic checks and context-free validation on the transaction it receives, and returns an error code if it isn’t valid. In general, the StarkEx approach is to detect errors as soon as possible in the pipeline. However, some errors can are detected later, when StarkEx performs the checks that depend on the current state (balances, etc) of the system. For example, if an on-chain deposit got lost due to a reorganization of the blockchain and then there aren’t enough funds in the on-chain contract to execute the deposit transaction. 
Mechanism: When an error is detected in the pipeline, an alternative transaction request is sent to the Application endpoint. In some cases, there are other transactions in the batch that depend on the invalid transaction so you would want to send an alternative transaction that satisfies these dependencies and makes the batch valid. The alternative can be a list of multiple transactions, one transaction, or an empty list, whatever works for you to solve it. The list of alternative transactions will be executed in an atomic manner, meaning, all or nothing. For this mechanism, the Application needs to provide an endpoint to send these requests to, this endpoint should be monitored regularly. 
An example of an alternative transaction request and response is attached below.
Handler: It is recommended to handle the alternative transaction request manually since it requires careful handling and some cases can be rather complicated to solve automatically.
3.Full Withdrawal handler - StarkEx is a self-custodial platform and as such, it has a censorship resistance mechanism for withdrawal requests (and also trade requests in perpetual trading). Make sure that you monitor the on-chain forced withdrawal requests and serve them in a timely manner. Note that if the Application censors these requests the exchange could be frozen.
alt_tx_request.json
2KB
Code
Alternative transaction request example
alt_tx_response.json
2KB
Code
Alternative transaction resposne example
​
Exit or Change a Strategy
Next - Crypto 🤓
STARK Curve
Last modified 1mo ago
Copy link
Contents
StarkEx Playground
Your own StarkEx Setup