Contract Management

Governance

The StarkEx contract is governed by one or more Governors of which the initial one is the deployer of the contract.

A governor has the sole authority to perform the following operations:

  1. Nominate additional governors (mainNominateNewGovernor)

  2. Remove other governors (mainRemoveGovernor)

  3. Remove Verifiers and AvailabilityVerifiers after a time-lock allows it

  4. Nominate Operators (see Operator) and Token Administrators (see Tokens)

Adding governors is performed in a two-step procedure:

  1. First, an existing governor nominates a new governor (mainNominateNewGovernor)

  2. Then, the new governor must accept governance to become a governor (mainAcceptGovernance)

This two-step procedure ensures that a Governor's public key cannot be nominated unless there is an entity that has the corresponding private key. This is intended to prevent errors in the addition process.

The Governor's private key should typically be held in a secure cold wallet.

Operator

The Operator of the contract is the entity entitled to submit state update requests by calling updateState.

An Operator may be instantly appointed or removed by the contract Governor (as explained above).

Typically, the Operator is the hot wallet of the StarkEx service submitting proofs for state updates.

Tokens

Registration of a new asset entails defining a new asset type within the system and associating it with an assetInfo array of bytes and a quantization factor (quantum).

To register a new asset, the tokenAdmin calls registerToken, providing assetType and assetInfo. A full explanation of how to compute both can be found here.

Once registered, assets cannot be removed from the system, as their IDs may be used by off-chain accounts.

A tokenAdmin may be instantly appointed or removed by the contract Governor (as explained above). Typically, the tokenAdmin’s private key should be kept in a cold wallet.

Verifiers

A Verifier contract is an implementation of a STARK verifier that the StarkEx service sends STARK proofs to (see STARK Cairo verifier). In addition, StarkEx contract can call a verifier to check if a valid proof has been accepted for a given state transition (typically described as a hash on the public input of the assumed proof).

The StarkEx contract will normally query only one verifier contract for proof validity checks. However, in the event that the verifier algorithm needs to be updated, additional verifiers may be registered by the contract Governor. Such new verifiers are then also required to attest to the validity of state transitions and only if all the verifiers attest to the validity the state transition is accepted.

This one verifier is our Universal Cairo verifier, capable of verifying any Cairo program.

In order to validate that the Cairo verifier has verified the correct off-chain Cairo program, StarkEx smart contract compares the hash of the off-chain program with the hash of the program that the Cairo Verifier verified. This hash is given as an input to the Cairo verifier along with the proof.

Removal of verifiers is also the responsibility of the Governor. The removal process is more sensitive than verifier registration as it may affect the soundness of the system. Hence, this is performed in two steps:

  1. The Governor first announces the intent to remove a verifier by calling announceVerifierRemovalIntent.

  2. After the expiration of a VERIFIER_REMOVAL_DELAY time-lock, actual removal may be performed by calling removeVerifier.

The removal delay ensures that a user concerned about the soundness of the system has ample time to leave the exchange.

Availability Verifiers

A Committee contract is a contract that the exchange service sends committee member signatures to attest that they have a copy of the data over which a new Merkle root is to be accepted as the new state root (See here). In addition, the exchange contract can call an availability verifier to check if such signatures were indeed provided by a sufficient number of committee members as defined in the Committee contract for a given state transition (as reflected by the old and new vault and order roots).

The committee mechanism is required only when StarkEx works in Validium mode. When StarkEx works in a ZK-Rollup mode, all the relevant data appears on-chain as part of the proof output - so there is no need for a committee.

The exchange contract will normally query only one Committee contract for data availability checks. However, in the event that the Committee needs to be updated, additional verifiers may be registered by the contract Governor. Such new availability verifiers are then also required to attest to the availability of the for state transitions and only if all the availability verifiers attest to it, the state transition is accepted.

Removal of availability verifiers is also the responsibility of the Governor. The removal process is more sensitive than availability verifier registration as it may affect the soundness of the system. Hence, this is performed in two steps:

  1. The Governor first announces the intent to remove an availability verifier by calling announceAvailabilityVerifierRemovalIntent.

  2. After the expiration of a VERIFIER_REMOVAL_DELAY time-lock, actual removal may be performed by calling removeAvailabilityVerifier.

The removal delay ensures that a user concerned about the soundness of the system has ample time to leave the exchange.

State Update

The StarkEx contract tracks the state of the off-chain exchange service by storing Merkle roots of the vault state (off-chain account state) and the order state (including orders and transfers).

The Operator is the only entity entitled to submit state updates by calling updateState and this is only allowed if the contract is not in the frozen state (see FullWithdrawals). The call includes the publicInput of a STARK proof, and additional data (applicationData) that includes information not attested to by the proof.

The publicInput includes the current (initial) and next (final) Merkle roots as mentioned above, the heights of the Merkle trees, a list of vault operations and a list of conditional transfers.

Vault Operations

A vault operation can be a ramping operation (deposit/withdrawal) or an indication to clear a forced operation request. Each vault operation is encoded in 3 words as follows:

  1. Word 0: Stark Key of the vault owner (or the requestor Stark Key for false full withdrawal).

  2. Word 1: Asset ID of the vault representing either the currency (for fungible tokens) or a unique token ID and its on-chain contract association (for non-fungible tokens).

  3. Word 2:

    1. ID of the vault (off-chain account)

    2. Vault balance change in biased representation (excess-2**63). A negative balance change implies a withdrawal while a positive amount implies a deposit. A zero balance change may be used for operations implying neither (e.g. a false full withdrawal request).

    3. A bit indicating whether the operation requires clearing a full withdrawal request.

The above information is used by the exchange contract in order to update the pending accounts used for deposits and withdrawals.

The next section in the publicInput is a list of encoded conditions corresponding to the conditional transfers in the batch.

The applicationData holds the following information:

  1. The ID of the current batch for which the operator is submitting the update.

  2. The expected ID of the last batch accepted on chain. This allows the operator submitting state updates to ensure the same batch order is accepted on-chain as was intended by the operator in the event that more than one valid update may have been generated based on different previous batches - an unlikely but possible event.

  3. For each conditional transfer in the batch two words are provided:

    1. Word 0: The address of a fact registry contract.

    2. Word 1: A fact to be verified on the above contract attesting that the condition has been met on-chain.

The STARK proof attesting to the validity of the state update is submitted separately by the exchange service to (one or more) STARK integrity verifier contract(s). Likewise, the signatures of committee members attesting to the availability of the vault and order data is submitted separately by the exchange service to (one or more) availability verifier contract(s).

The state update is only accepted by StarkEx contract if the integrity verifier and availability verifier contracts have indeed received such proof of soundness and data availability.

Upon a successful state update, the event LogRootUpdate is emitted.