Asset quantities in StarkEx

In the Ethereum blockchain, token quantities are represented by a 256-bit number. However, for the sake of efficiency, quantities in StarkEx are represented by a 64-bit number. The largest number of digits that a 64-bit number can represent is much less than that which a 256-bit number can represent. So in order to support trading in significant volume, the smallest unit that StarkEx can use for an asset is larger than the smallest unit that Ethereum can use.

The inputs to all offchain transactions and some onchain requests are given in units of the offchain asset, so the code that generates the transaction signature must use the correct factor for converting 256-bit quantities of onchain or synthetic ETH or ERC-20 asset quantities to a 64-bit StarkEx representation.

Converting onchain asset quantities

This factor is called the quantization factor or quantum. The quantum represents the smallest amount of an asset that users can trade offchain, or with which they can pay offchain fees.
Converting synthetic asset quantities

This factor is called the resolution factor. The resolution is the total number of the smallest part of a single synthetic token in the StarkEx system.

You decide the value of the quantum and resolution factor according to the requirements of your application’s business logic.

Balance of a synthetic asset

Every balance is a 64-bit value, where one bit represents the sign indicating if the value is positive or negative, and 63-bits represent the number. So every balance falls within the range (-263, 263).

Quantization

The quantum is the smallest unit of a token in the StarkEx system. It is similar to an exchange rate that you use to find the onchain value of a quantity of a token in StarkEx, according to the following formula:

\[\text{quantum} \cdot \text{StarkEx_amount} = \text{onchain_amount}\]
Example: Defining the quantum

Consider one possible quantization for ETH, which is an onchain asset:

Onchain asset

The smallest unit of ETH is 1 WEI, which is \(10^{-18}\) ETH.
Offchain asset

The smallest unit with which you can conduct transactions of the offchain asset that corresponds to ETH represents \(10^{-11}\) onchain ETH, or \(10^{7}\) onchain WEI.

So the operator defines the quantum for ETH to be \(10^{7}\).

Example: Calculating the amount of an onchain asset

This example shows how to find how many units of onchain WEI are represented by 17 units of the corresponding offchain asset.

  • In Ethereum, 1 WEI = \(10^{-18}\)ETH.

  • Let \(\text{quantum}=10^7\).

  • Let \(\text{StarkEx_amount}=17\). This is the number of corresponding assets in a StarkEx offchain position.

Plugging in these values to the formula above gives the following:

\[10^7 \cdot 17 = 170,000,000\]

170,000,000 is the amount of WEI locked onchain that is associated with the corresponding StarkEx offchain vault, which is the same as \(10^{-11} \cdot 17\) ETH.

The quantum is necessary for every asset that can be represented onchain. For example, in the deposit flow, the onchain deposit transaction gets an unquantized amount of tokens from the user, yet the parameter to the onchain call is a quantized amount.

Resolution

In contrast to collateral, synthetic assets do not necessarily correspond to onchain assets. For example, a barrel of oil can be a synthetic asset. So quantization, which is specifically for working with onchain assets, does not apply to synthetic assets. However, it is still necessary to work with a representation of the synthetic asset within the StarkEx system that defines the smallest unit of the asset that users can trade.

In StarkEx, synthetic assets are converted to StarkEx units by applying a calculation called resolution that uses a constant called a resolution factor.

For collateral, resolution is also necessary to simplify certain calculations.

Resolution provides the following benefits:

  • Signed external oracle prices are given in round units, such as BTC or ETH, rather than satoshi or WEI, so resolution makes the translation to the price used in the StarkEx system valid.

  • Resolution enables trading in synthetic assets that do not necessarily correspond to ERC-20 tokens, such as barrels of oil.

The resolution is the total number of a single asset in the StarkEx system that equals one synthetic token. For example, if the smallest unit of DOGE that you can trade on StarkEx is 10-6 DOGE, that means that one synthetic DOGE = 106 StarkEx units. This number, 106, is the resolution factor for DOGE in StarkEx.

The formula to find the amount of a synthetic asset is:

\[\text{synthetic_asset_amount} \cdot \text{resolution} = \text{StarkEx_amount}\]

Because every balance is within the range (-263, 263), then in the example above, each position can contain amounts of (10-6\(\cdot\)-263, 10-6\(\cdot\)263) DOGE.

Example

Consider synthetic ETH.

Consider that in Ethereum, 1 ETH = \(10^{18}\) WEI.

  • Let \(\text{resolution} = 10^8\). This means that the operator decided that the smallest unit of ETH their application supports is 10-8 synthetic ETH.

  • Alice has 2.25 synthetic ETH in her position.

What is the StarkEx amount of ETH in her position?

Plugging in these values to the formula above gives the following:

\[2.25 \cdot 10^8 = 225,000,000\]

225,000,000 is the number of StarkEx units Alice holds that correspond to synthetic ETH in her position.

Prices: Calculating StarkEx internal values

When calculating values to send to the StarkEx gateway, be aware that the StarkEx system represents prices as 64-bit fixed-point unsigned numbers, with 32 bits after the decimal point.

Example: Calculating the internal price of synthetic ETH

Consider the following values:

  • The quantization of USDC is 1.

  • The resolution of USDC is 106, which means that the smallest unit of USDC in the StarkEx system is 10-6 USDC.

  • The resolution of synthetic ETH is 108.

  • A signature from the oracle provider sets the price of ETH to 383.3456178219832 USDC, which the oracle provider notates as 383345617821983200000.

The internal price of ETH in StarkEx is calculated as follows:

\[\text{price}_\text{StarkEx_ETH} = \text{ROUND_PRICE}\frac{\text{price}_\text{oracle_provider_ETH} \cdot \text{USDC_RESOLUTION} \cdot 2^{32}}{\text{ETH_RESOLUTION} \cdot 10^{18}}\]

Where \(\text{ROUND_PRICE}\) rounds the quotient to the nearest integer.

Plugging in the values gives the following:

\[\text{price}_\text{StarkEx_ETH} = \text{ROUND_PRICE}(\frac{383345617821983200000 \cdot 10^6 \cdot 2^{32}}{10^8 \cdot 10^{18}})\]

Which simplifies to:

\[\text{price}_\text{StarkEx_ETH} = \text{ROUND_PRICE}(16464568916.103325938614272)\]

Rounding this price to the nearest integer gives 16464568916, which is the value that the StarkEx system uses for the price of ETH.

Total value: Calculating StarkEx internal values

  • Collateral and synthetic asset values have resolution applied.

  • Total value is a 96-bit fixed-point signed integer, with 32 bits after the decimal point.

Consider the following applies to Alice’s position:

collateral:

Alice holds 500 USDC.
resolution for USDC: 106.
synthetic:

Alice holds 6 ETH, where 1 ETH = 1,000 USDC.
resolution for ETH: 108
price from the oracle provider: 16464568916

The total value of Alice’s position in end-user terms is:

500 + (6 * 1,000) = 6,500

To convert this value to a StarkEx internal value:

\[\text{Total_value} = (\text{collateral_quantity} \cdot \text{collateral_resolution} \cdot 2^{32}) + (\text{synthetic_quantity} \cdot \text{synthetic_resolution} \cdot \text{price_from_oracle})\]

Plugging in the values above gives:

\[(500 \cdot 10^6 \cdot 2^{32}) + (6 \cdot 10^8 \cdot 16464568916) = 1.2026225×10¹⁹\]

So total value, expressed as a 96-bit fixed-point signed integer, with 32 bits after the decimal point, is 12026225000000000000.

Total risk: Calculating StarkEx internal values

When StarkEx calculates total risk:

  • The risk factor is a positive number between 0 and 1. It is similar to the maintenance margin. For more information, see Margin and Total value and total risk.

  • The risk factor and prices are represented as 64-bit unsigned integers, with 32 bits after the decimal point.

  • Total risk is a 128-bit fixed-point unsigned integer, with 64 bits after the decimal point.

To calculate the internal representation of the risk factor:

\[\text{risk_factor} \cdot 2^{32}\]

For example, if the risk_factor for ETH is 0.1, the internal representation is 0.1 * 232 = 429496729.6. This number is rounded to 429496730, which is the value for risk_factor in the general configuration file.

Calculating total risk results in a 128-bit fixed-point unsigned number, with 64 bits to the right of the decimal point.

Example: Calculating internal StarkEx values

The risk factor for ETH is 0.1. The internal StarkEx value is 0.1 * 232= 429496729.6, which rounds to 429496730.

The resolution factors for USDC, BTC, and ETH are as follows:

  • USDC: 106

  • BTC: 107

  • ETH: 108

So the internal values of Alice’s USDC, BTC, and ETH positions are as follows:

  • 500 USDC * 106 = 500000000

  • 4 BTC * 107 = 40000000

  • 6 ETH * 108 = 600000000

Consider Alice’s total risk from Example: Total risk is 40,600:

Summary of Alice’s position and the total risk calculation:
collateral:

500 USDC
synthetic:

4 BTC. 1 BTC = 20,000 USDC. risk_factor = 0.5
6 ETH. 1 ETH = 1,000 USDC. risk_factor = 0.1

(4 * 20,000 * 0.5) + (6 * 1,000 * 0.1) = 40,600

Now convert the risk factors to 32-bit numbers:

  • \(\text{BTC_risk_factor}\) = 0.5 * 232 = 2147483648

  • \(\text{ETH_risk_factor}\) = 0.1 * 232 = 429496730

The internal StarkEx value of Alice’s total risk is calculated as follows:

\[\begin{split}(\text{BTC_amount} \cdot \text{BTC_price} \cdot \text{BTC_resolution} \cdot \text{BTC_risk_factor}) + \\ (\text{ETH_amount} \cdot \text{ETH_price} \cdot \text{ETH_resolution} \cdot \text{ETH_risk_factor})\end{split}\]

\(\text{BTC_risk_factor}\) is the internal StarkEx value of this risk factor, so it already has been multiplied by 232.

Plugging in the values from the example:

( (4 * 20,000) * 107 * 2147483648 ) + ((6 * 1,000) * 108 * 429496730) = 197568495600000000000

So the internal value of Alice’s total risk is 197568495600000000000.