Off-chain state

Balances tree

The first element in the off-chain state of StarkEx is the Balances tree. The Balances tree is a Merkle Tree, whose leaves are StarkEx Vaults. Each vault contains a unique Stark key, which identifies the user in the off-chain state. Other elements in the vault are defined according to the business logic.

Additional resources

Orders tree

The Orders tree is a Patricia tree, which is easier to update and search than a Merkle tree. The Orders tree prevents the operator from replaying transactions in the system. To prevent this attack, StarkEx does the following:

  1. A leaf in the Orders tree represents an order. Each leaf has a key and a value. The leaf key, i, serves as the id of the leaf. The key value includes the already fulfilled amount of the limit order with the hash i. For example, if Alice signed a transfer request for 1000 USDC, with a hash value 0xdeadbeef, StarkEx stores 1000 quantized USDC in leaf index 0xdeadbeef in the Orders tree.

  2. If the Operator tries to resubmit Alice’s order, then when validating a transfer, StarkEx checks that this transfer was not previously executed by checking that the value in leaf number 0xdeadbeef is zero. Because the value is not zero, the on-chain Cairo Verifier cannot accept this order.

  3. StarkEx uses the Orders tree to keep track of assets that were previously minted.

The Orders tree also supports partial fulfillment of limit orders.
On trades, the Operator must provide the original user’s limit order, as well as the corresponding amount that is transferred in this settlement. StarkEx enforces that the value saved in the Orders tree, plus the new transferred amount, is still less than the amount that the user signed on in the original limit order.

Unique minting

With StarkEx, your users can trustlessly mint a cryptographically ensured, unique ERC-721 NFT, off-chain, and withdraw it to layer 1.

Enforcing consistency in the on-chain state

The StarkEx smart contract stores the root of the Balances tree and the root of the Orders tree, which are a commitment to the off-chain state. The off-chain state is the tuple of roots. The state is updated when the contract receives a new proof that there exists a valid sequence of transactions that, when executed, changes the current state to a new state.

Vault Structure

The vault contains the following fields:

  • starkKey - the public key of the vault’s owner. Transfers and trades from this vault must be signed with this key.

  • The assetId that this vault contains (only one type per vault).

  • The amount, quantized, that this vault contains.

An empty vault has a balance of 0.

An empty vault has no owner. You can reassign it.

Every vault contains one asset type. So limit orders have two vaults as input, as follows:

  • one vault for sold tokens

  • one vault for purchased tokens

Additional resources