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.

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.

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.

  • collateralAmount - the amount of collateral in the vault.

  • A list of synthetic assets. For each asset:

An empty vault has a balance of 0.

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

Additional Elements in the State

Global funding indices

When the application sends a funding tick, which is based on the median oracle price tick, it updates an index called the global funding index for each type of asset in the system. The global funding index updates a position’s balance before every transaction execution, according to the funding logic.

The on-chain state includes the most recent global funding index, according to the last funding tick.

A global funding index is a 64-bit fixed-point signed number, with 32 bits after the decimal point. The index uses USDC, quantized, as the basis for its pricing of all assets.

{
    "global_funding_indices": {
        "indices": {
            "0x0": "-431710025170174585",
            "0x1": "6084712057446794809"
        },
        "timestamp": "3900315155"
    },
    "type": "FUNDING_TICK"
}

Current system time

The current time of the system advances whenever a funding tick or an oracle price tick arrives. When closing a batch for submission, the system time must be a date within the last week.

Current prices

The current prices of all the assets in the system, as received from different Oracle price tick transactions.

Additional resources