StarkEx smart contract architecture

High-level architecture

contracts arch

The StarkEx smart contract enforces a trader’s self-custody. It maintains the StarkEx state hash and allows a state transition only if both the integrity Verifier, that is, the Verifier Fact Registry, and the Committee Fact Registry, which supports custom constraints, approve the new state.


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 main contract the operator’s application, that is, all code that is executed in the context of the Proxy contract, to the Verifier contract, which is part of the SHARP proving service. The Verifier Fact Registry contract implements the Fact Registry API, and translates facts of the format that the operator’s application contract uses to the format that the SHARP Proving Service Verifier contract uses, such as by hashing the operator’s application contract with the Cairo application program hash).

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 operator application contract. Traders use the Escape Verifier Fact Registry to prove possession of the frozen contract’s funds, which allows traders to withdraw those funds upon satisfaction.


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 be 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.

Additional resources