General configuration

The StarkEx Perpetual Trading system general configuration smart contract contains:

global configuration parameters
configuration parameters for each synthetic asset

The general configuration must be reflected on-chain in order to preserve soundness. In order to reduce gas costs, a hash committment of the full configuration is stored on-chain, rather than the full configuration smart contract itself.

To understand the importance of storing the general configuratio on-chain, consider the following example:

In a given system, one configuration dictates who is allowed to sign on price feeds of the different assets. If a batch is proven with respect to an invalid Oracle, which is different from what is reflected on-chain, then the proof is rejected. Otherwise, a malicious operator could change this configuration off-chain and sign any price feed with an arbitrary price.

If you are worried about the security of the system, check that you can access the full configuration, along with the hash calculations that attest to it corresponding to the general configuration commitment. You can get this information, for example, on the application site.

Global configuration

Contains the following fields:

collateral_asset_info

Contains asset_id and resolution for the collateral token.

fee_position_info

Contains position_id and the public Stark key, public_key, of the party that receives fees from users for transactions that take place in the system.

is_risk_by_balance_only

Used as part of the definition of risk_factor.

Boolean. Possible values are True and False.

`True`	The value for `upper_bound` refers to the quantity of the synthetic asset.
`False`	The value for `upper_bound` refers to the value of the synthetic asset, that is \(\text{price} \cdot \text{asset_quantity}\).

max_funding_rate

The maximum rate by which the system allows one or more funding ticks to influence the amount of a position’s collateral, over a period of eight hours, per amount of the synthentic assets in that position. The change in the amount of collateral correlates to the amount of a synthetic asset and its price.

Include max_funding_rate in the configuration file as follows:

max_funding_rate: '<integer>'

To calculate this value:

\(\text{max_funding_rate} = \frac{\text{percentage} \cdot 2^{32}}{100 \cdot 8 \cdot 3600}\)

For example, if \(\text{percentage}\) = 4%, then: \(\text{max_funding_rate} = \frac{\text{4} \cdot 2^{32}}{100 \cdot 8 \cdot 3600} = 5965\)

Example: Applying max_funding_rate

Consider the following conditions:

max_funding_rate = 5965
When the system time is 00:00, the system receives an oracle price tick.

The following holds true:

The total credits or debits an operator can apply to a position between 00:00 and 07:59 is 4% of the position’s value.
A funding tick at 00:59, which is 1/8 of the eight hour period, can affect the position up to 0.5%, which is 1/8 of max_funding_rate.
A funding tick at 02:59 can affect the position up to 1%, and so on.
If a funding tick does not occur until 10:59, then the maximum rate for that funding tick is 5.5%.

For information on funding ticks, see Funding tick.

orders_tree_height

The height of the Orders tree.

positions_tree_height

The height of the Balances tree.

timestamp_validation_config

Container for funding_validity_period and price_validity_period.

`funding_validity_period`	The period of time, in seconds, for which a funding tick is valid.
`price_validity_period`	The period of time, in seconds, for which an oracle price tick is valid.

Configuration per synthetic asset

Contains the following fields:

synthetic_assets_info

Contains asset IDs.

<ID>

A synthetic asset’s ID. A dictionary that contains all properties for the synthetic asset. A hexadecimal value.

oracle_price_quorum

The number of oracle signers required to approve a new price for a given synthetic asset. A hexadecimal value.

oracle_price_signed_asset_ids

A list of possible IDs to identify this asset, for use with different oracle companies. For more information, see Becoming an oracle provider for StarkEx. A hexadecimal value.

oracle_price_signers

A list of public Stark keys that have permission to sign on oracle prices for a given synthetic asset.

resolution

The asset’s resolution. A hexadecimal value.

risk_factor

risk_factor as described here is supported starting with StarkEx Perpetual Trading 2.1.

A tiered list, where the keyword segments is a collection of all tiers. Each tier has a corresponding upper bound, upper_bound, and risk factor, risk. You can define as many tiers as you require.

The final, or only, tier in the list must have an upper bound of 2¹²⁸⁠-⁠1.

For example, Table 1, “Tiers of risk” shows the risk_factor for an asset with three tiers:

Table 1. Tiers of risk
Amount of synthetic asset	`upper_bound`	`risk`
0-5,000	5,000	128849019
5,001 - 10,000	10,000	171798692
10,001 - 2¹²⁸-1	2¹²⁸-1	214748365

For information on the risk factor, see Total value and total risk.

segments

Required. A container for one or more tiers. Each tier includes a risk factor, risk, and an upper bound, upper_bound.

risk

An integer, delimited with single quotes.

risk has the following condition:

1 ≤ risk < 2³²

upper_bound

The inclusive upper bound for the tier. An integer representing either the maximum amount of a synthetic asset for the tier, or the maximum value of a synthetic asset for the tier, in terms of units of collateral currency. Select an option with the global configuration parameter is_risk_by_balance_only.

For example, consider that you want to set upper_bound for 5 synthetic BTC, where 1 BTC = 10,000 USDC. You can set upper_bound to its USDC value, 50,000, or to the quantity of BTC, 5.

upper_bound has the following conditions:

0 ≤ upper_bound ≤ 2¹²⁸-1
The value for upper_bound in any tier is greater than the value of upper_bound in the previous tier.
The value for upper_bound in the final tier is always 2¹²⁸-1.

Example of risk_factor

The following example defines two tiers for a given synthetic asset.

risk_factor:
  segments:
  - risk: '1111111' # The risk factor for the first, optional, tier.
                    # Notice that this integer is within single quotes.
    upper_bound: 5000 # The upper bound for this tier.
  - risk: '171798692' # The risk factor for the final, required, tier.
    upper_bound: 340282366920938463463374607431768211455 # The upper bound of the final
                                                         # tier. Equals 2^128^-1

Sample general configuration file

collateral_asset_info:
  asset_id: '0xa86f5c0071e91aee3c2f30b8f131f30c46a627958a709c652bc6e3cea487e8'
  resolution: '0xf4240'
fee_position_info:
  position_id: '123456'
  public_key: '0x1403704647573f33cb67bce993b7e47d14c0c800a1d0163840e573661bc8c39'
is_risk_by_balance_only: False
max_funding_rate: '1120'
orders_tree_height: 64
positions_tree_height: 64
synthetic_assets_info:
  '0x4254432d3130000000000000000000':
    oracle_price_quorum: '0x3'
    oracle_price_signed_asset_ids:
    - '0x425443555344000000000000000000004d616b6572'
    oracle_price_signers:
    - '0x17bc44da035fa2966a3de2f130ccff2a2332a51f3d89216d7fb36ce3b8d4d8'
    - '0x31e5f5e71e060d3f1a096e0b050fe5cdc87fd8b41bc1699a2ccaaec3510d9a'
    - '0x11085343381ac7f0b89d29b9ab223ca786dbd3998ce09c065bcf5825d25beb'
    resolution: '0x2540be400'
    risk_factor:
      segments:
      - risk: '171798692'
        upper_bound: 5000
      - risk: '214748365'
        upper_bound: 340282366920938463463374607431768211455
  '0x4554482d3800000000000000000000':
    oracle_price_quorum: '0x3'
    oracle_price_signed_asset_ids:
    - '0x455448555344000000000000000000004d616b6572'
    oracle_price_signers:
    - '0x6b67e88018defc69e26e073d9eae8466a51692b7a4e78449438b567c3080f4b'
    - '0x4fc354c014e97ca2abe8bd9b5d65ac30ba24b0e3a7e9a5c9e6b1839dceb12a4'
    - '0x2bba7576ab47db82b05581bb15c08cec78e71cdd2a5e5930120aacaad099bf4'
    resolution: '0x5f5e100'
    risk_factor:
      segments:
      - risk: '128849019'
        upper_bound: 10000
      - risk: '171798692'
        upper_bound: 340282366920938463463374607431768211455
  '0x4c494e4b2d37000000000000000000':
    oracle_price_quorum: '0x3'
    oracle_price_signed_asset_ids:
    - '0x4c494e4b5553440000000000000000004d616b6572'
    oracle_price_signers:
    - '0x12d71c0fd74ec779a6c835fac4783b538f98ded1f98414a634352c59ff5e4c6'
    - '0x43e7c55ac7398469ee7ac1be9656b599ba45af10d89821a9e97c3a4687ed126'
    - '0x494e83be1cc0b477c037c2c602111e32d4e8dbb3b26dc8a2c2fa176f2d11d8'
    resolution: '0x989680'
    risk_factor:
      segments:
      - risk: '214748365'
        upper_bound: 340282366920938463463374607431768211455
timestamp_validation_config:
  funding_validity_period: 86400
  price_validity_period: 86400