The trade flow

Trade flow for limit orders

1. Nora and Levi enter limit orders on Brine.

Nora wants to trade 1 ETH for 2000 USDC, and Bob wants to trade 2000 USDC for 1 ETH. They both enter limit orders using Brine.

2. Brine sends a settlement request transaction to Starkware.

Brine matches the limit orders of Nora and Levi, and sends a settlement request transaction to the Starkware gateway, using the add_transaction API with the SettlementRequest transaction type. The API call includes both orders, including the actual amounts transferred between Nora’s and Levi’s vaults.

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

vault_id_sell	The id of the vault from which sold funds should be taken.
vault_id_buy	The id of the vault from which bought funds should be put.
token_sell	The id of the asset to sell.
token_buy	The id of the asset to buy.
amount_sell	The quantized amount of the asset to sell.
amount_buy	The quantized amount of the asset to buy.
fee_info	The maximum fee that each party is willing to pay for the transaction.
expiration_timestamp	The expiration timestamp of the order.
nonce	A nonce, to prevent replay attacks.

3. Starkware validates the settlement request.

Starkware checks the following to validate the settlement request:

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

• The ratio between the amount to sell and the amount to buy matches the ratio that each party signed on. Both Nora and Levi want to trade at a ratio of 1 ETH to 2000 USDC.

• Each of the orders in the settlement request is signed by a Stark key that corresponds to the order’s vault id.

• The balance in each vault id is sufficient to fulfill the trade.

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

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

• The settlement request has not expired.

4. Starkware includes the settlement in a batch.

If the settlement request is valid, the settlement is included in a batch to be submitted on-chain along with a validity proof.