The trade flow

trade flow

1. Alice and Bob enter limit orders in the application.

Alice wants to sell 1 synthetic BTC for 30000 USDC and pay a maximum amount of 5 USDC as a fee for the trade. Bob wants to sell 30000 USDC for 0.99 synthetic BTC and pay a maximum amount of 10 USDC as a fee.

They both enter limit orders using the off-chain application.

2. The application sends a trade transaction to StarkEx.

The application matches the limit orders of Alice and Bob and creates a Trade transaction. This transaction includes both orders, alongside the actual transferred amounts between Alice and Bob’s vaults. In the example above, 0.99 BTC will be transferred from Alice to Bob in exchange for 30,000 USDC.

The request that the application sends to the StarkEx REST API includes the following information for each party:

order_type

The type of the order.
nonce

A nonce, to prevent replay attacks.
public_key

The public Stark key of the party as registered on the StarkEx contract.
amount_synthetic

The amount of synthetic asset in the order, after applying the resolution factor.
amount_collateral

The amount of collateral asset in the order, after applying the resolution factor.
amount_fee

The maximum fee that each party is willing to pay for the transaction.
asset_id_synthetic

The ID of the synthetic asset in the order, as registered on the contract.
asset_id_collateral

The ID of the collateral asset in the order, as registered on the contract.
position_id

The ID of the party’s position.
is_buying_synthetic

A boolean flag that indicates whether the party is buying or selling the synthetic asset.
expiration_timestamp

The timestamp after which this request is no longer valid. Specifies hours since the Unix epoch. A 32-bit number.
signature

The Signature of the party that issued the order.

Partial fulfillment is supported. So the amounts transferred between Alice and Bob can be smaller than the amounts they signed on, as long as the ratios of the settlement match the ratios of the orders. So after the settlement, Alice still has an open order with the remaining 0.01 BTC to sell and at least 300 USDC to receive for them. This order can be matched against further orders.

StarkEx monitors the fulfillment status of the orders with the orders tree.

3. StarkEx validates the transfer request.

StarkEx checks the following to validate the transfer request:

  • The ids of the assets of the two orders match.

  • Exactly one of the traded asset ids in each order corresponds to collateral.

  • The ratio between the sell amount and the buy amount for Alice and Bob is at least as good as the ratio each signed on.

  • The ratio between the actual amount of the fee taken and the actual amount of the collateral transferred is equal to or less than the ratio between the total fee and the total collateral transferred, signed by the user.

  • Neither order has already been fulfilled, and the amount to be traded does not cause Alice or Bob to transfer more than what they signed on in the order.

  • The balance in the sender’s position is sufficient to fulfill the transaction.

  • The maximum fee that the party is willing to pay for the transaction is not less than the actual fee.

  • The transaction request has not expired.

  • According to the orders tree, the order has not already been fulfilled.

  • All amounts in the request are ≥ 0.

  • Each asset’s ID corresponds to real assets registered in the system.

  • Every position involved is either empty or the position’s public Stark key matches the public Stark key in the request.

  • All signatures in the request are valid with respect to the corresponding public Stark key and message.

  • If a funding tick that occurs before the transaction is executed invalidates the transaction, the transaction is not completed and the funding tick is reverted.

  • Every balance that results from executing the order is within the range (-263, 263).

  • After the transaction is executed one of the following must be true:

    • The resulting position is well leveraged, that is: \(\text{total_value} \ge \text{total_risk}\)

    • Total value per risk (TV/TR) does not decrease after funding is applied, and the position’s total risk decreases or stays the same, which means that for every synthetic asset, \(|\text{new_balance}| \le |\text{old_balance}|\)

3. StarkEx includes the settlement in a batch.

If the settlement is valid, it is included in a batch to be submitted on-chain along with a validity proof. For information on the resulting on-chain state update, see State update.

As with any other transaction, funding ticks take place before the settlement is applied to the position.

Implementing a trade in your application

The transfer is included in a batch.

To implement trade functionality in your application, use the add_transaction API with the Trade transaction type.

The StarkEx REST API reference includes all necessary information.

Additional resources