StarkEx Smart Contracts Architecture

High-Level Architecture

The StarkEx smart contract enforces a trader's self-custody. It maintains the Exchange state hash and allows a state transition only if both the integrity verifier (Verifier fact registry) and the Committee fact registry (supporting custom constraints) approve the new state.

Components

1. Proxy Contract

The Proxy contract holds the system state and owns all the funds deposited to the Exchange. It includes minimal functionality, implementing the (solidity) proxy pattern. It delegates all (but upgradability-related calls) to the dispatcher contract.

2. Dispatcher Contract

The Dispatcher contract invokes the business logic of the StarkEx smart contract.

Ethereum limits contract size to 24kB. To accommodate this, the logic is spread among several library contracts and invoked with delegate calls.

The Dispatcher contract implementation is similar to the suggested diamond pattern. It introduces an optimization by using a perfect hash with a small image (e.g., 4 bits), mapping function names to contract addresses. The contracts implementing these functions are called the sub-contracts.

3. Sub-Contracts

The sub-contracts implement different modules used by the StarkEx smart contract. They are executed in the context of the Proxy contract (both address and storage), using delegate calls.

4. Verifier Fact Registry

A contract linking the Exchange Application main contract (all the code executed in the context of the Proxy contract) to the Verifier contract (which is part of the SHARP proving service). It implements the fact registry API, and translates facts of the format the Exchange Application Contract uses to the format the SHARP Proving Service Verifier contract uses (e.g., by hashing it with the Cairo application program hash).

Please find further information about the fact registry API or view the API documentation.

5. Committee Fact Registry

A fact registry enforcing custom off-chain approval of state transitions (e.g., data availability on some off-chain repository).

6. Escape Verifier Fact Registry

This component serves the self-custody feature in the case of a frozen Exchange Application contract. Traders use it to prove possession of the frozen contract's funds, which allows them to withdraw those funds upon satisfaction.

Upgradability

Standard Flow

The Proxy contract supports upgradability by changing the address of the Dispatcher contract (i.e., the version) it delegates the calls to. To ensure self custody, an immediate upgrade is not supported.

The standard upgrade flow is:

  1. Register a new version of a contract.

  2. A timelock is applied. This allows any trader that does not approve the new version to leave the system.

  3. After the timelock period, the version can be switched to the new version.

Versions that already passed this standard flow can reinvoked. This enables the immediate return to a previous version in case of a bug in a new version.

Soundness Issues Immediate-Fix

In case of a soundness issue with the Verifier fact registry, a new Verifier can be added immediately. To ensure the operation does not harm the system soundness, this operation allows state transition only if all the Verifiers approve it. Note, the simplest scenario is that both old and new Verifiers approve the change. However, the list can be more extensive.

A Verifier can be removed from the list only after a timelock. This prevents the operator from causing harm to the system's soundness.

The same mechanism applies to Committee contracts.

See also fact registry for further information on the verification process.