StarkEx specific concepts
Asset quantities in StarkEx
In the Ethereum blockchain, token quantities are represented by a 256-bit number. However, to be efficient, 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 of 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 off-chain transactions and some on-chain requests are given in units of the off-chain asset, so the code that generates the transaction signature must use the correct factor for converting 256-bit quantities of on-chain asset quantities to a 64-bit StarkEx representation.
Converting on-chain asset quantities |
This factor is called the quantization factor or quantum. The quantum represents the smallest amount of an asset that users can trade off-chain, or with which they can pay off-chain 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 according to the requirements of your application’s business logic.
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 on-chain value of a quantity of a token in StarkEx, according to the following formula:
Consider one possible quantization for ETH, which is an on-chain asset:
On-chain asset |
The smallest unit of ETH is 1 WEI, which is \(10^{-18}\) ETH. |
Off-chain asset |
The smallest unit with which you can conduct transactions of the off-chain asset that corresponds to ETH represents \(10^{-11}\) on-chain ETH, or \(10^{7}\) on-chain WEI. |
So the operator defines the quantum for ETH to be \(10^{7}\).
This example shows how to find how many units of on-chain WEI are represented by 17 units of the corresponding off-chain 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 off-chain vault.
Plugging in these values to the formula above gives the following:
170,000,000 is the amount of WEI locked on-chain that is associated with the corresponding StarkEx off-chain vault, which is the same as \(10^{-11} \cdot 17\) ETH.
The quantum is necessary for every asset that can be represented on-chain. For example, in the deposit flow, the on-chain deposit transaction gets an unquantized amount of tokens from the user, yet the parameter to the on-chain call is a quantized amount. |
Identifiers for supported assets
The StarkEx API supports the following types of assets:
-
ETH
-
ERC-20
-
ERC-721
-
ERC-1155
Off-chain: The StarkEx API and SDK
The StarkEx API and SDK only apply off-chain.
The SDK and API use two different terms to refer to a unique off-chain asset:
-
The StarkEx SDK uses the term
assetId
. -
The StarkEx API uses the term
token_id
.
The StarkEx API does not include the keyword |
On-chain: StarkEx contracts
StarkEx contracts use the following terms:
selector
|
A 4-byte constant that specifies one of the following the asset standards:
|
address
|
The address of the on-chain contract for a givent asset type. |
assetInfo
|
The string concatenation of |
Be aware that in the ERC-721 and ERC-1155 on-chain StarkEx contracts, the terms assetId
and tokenId
have slightly different meanings from those in the contracts for ERC-20, ETH, and mintable ERC-721 assets.
Asset type | Description | ||||
---|---|---|---|---|---|
ERC-20, ETH |
There is no identifier for any one specific coin, unlike with ERC-721 or ERC-1155, because one unit of ETH or of an ERC-20 token has the same value as any other of the same type of token. StarkEx does not track individual assets of these types. The StarkEx system calculates the value for
|
||||
ERC-721, ERC-1155 |
An NFT has two identifiers:
For example, consider two NFTs within two separate contracts:
So the value of However, both Mitzy and Spot each have their own unique value for The value for
|
||||
Mintable ERC-721 |
This type of NFT is minted on L2. It does not exist on-chain until your user withdraws it from off-chain to on-chain. When your user withdraws the NFT from off-chain to on-chain, you need to provide them with the The value for
|
Computing assetInfo
, assetType
, and assetId
Below you can find a pseudo-code of the computation. Full implementation in JS can be found here.
ETH
def getEthAssetInfo():
ETH_SELECTOR = '0x8322fff2' # '0x8322fff2' = bytes4(keccak256(“ETH()”))
asset_info = ETH_SELECTOR
return asset_info
def getEthAssetType(quantum):
asset_info = getEthAssetInfo()
asset_type = keccak256(asset_info, quantum)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_type
def getEthAssetId(quantum):
asset_id = getEthAssetType(quantum)
return asset_id
ERC-20
def getErc20AssetInfo(address):
ERC20_SELECTOR = '0xf47261b0'
# '0xf47261b0' = bytes4(keccak256('ERC20Token(address)'))
asset_info = ERC20_SELECTOR + bytes.fromhex(address[2:]).rjust(32, b'\0')
# For ERC20, asset_info is 36 bytes long
return asset_info
def getErc20AssetType(quantum, address):
asset_info = getErc20AssetInfo(address)
asset_type = keccak256(asset_info, quantum)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_type
def getErc20AssetId(quantum, address):
asset_id = getErc20AssetType(quantum, address)
return asset_id
ERC-721
def getErc721AssetInfo(address):
ERC721_SELECTOR = '0x02571792'
# 0x02571792 = bytes4(keccak256('ERC721Token(address,uint256)'))
asset_info = ERC721_SELECTOR + bytes.fromhex(address[2:]).rjust(32, b'\0')
# For ERC721, asset_info is 36 bytes long.
return asset_info
def getErc721AssetType(address):
asset_info = getErc721AssetInfo(address)
asset_type = keccak256(asset_info, 1)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_type
def getErc721AssetId(token_id, address):
asset_type = getErc721AssetType(address)
asset_id = keccak256('NFT:', asset_type, token_id)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_id
ERC-1155
def getErc1155AssetInfo(address):
ERC1155_SELECTOR = `0x3348691d`
# 0x3348691d = bytes4(keccak256('ERC1155Token(address,uint256)'))
asset_info = ERC1155_SELECTOR + bytes.fromhex(address[2:]).rjust(32, b'\0')
return asset_info
def getErc1155AssetType(address):
asset_info = getErc1155AssetInfo(address)
quantum = 1
asset_type = keccak256(asset_info, quantum)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_type
def getErc1155AssetId(token_id, address):
asset_type = getErc1155AssetType(address)
asset_id = keccak256("NON_MINTABLE:", asset_type, token_id)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_id
Mintable ERC-721
def getErcMintable721AssetInfo(address):
MINTABLE_ERC721_SELECTOR = '0xb8b86672'
# 0xb8b86672 = bytes4(keccak256('MintableERC721Token(address,uint256)'))
asset_info = MINTABLE_ERC721_SELECTOR + bytes.fromhex(address[2:]).rjust(32, b'\0')
# For Mintable ERC721, asset_info is 36 bytes long.
return asset_info
def getMintableErc721AssetType(address):
asset_info = getErcMintable721AssetInfo(address)
asset_type = keccak256(asset_info, 1)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_type
def getMintableErc721AssetId(minting_blob, address):
asset_type = getMintableErc721AssetType(address)
blob_hash = keccak256(minting_blob)
asset_id = keccak256('MINTABLE:', asset_type, blob_hash)
& 0x0000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
asset_id = asset_id
| 0x400000000000000000000000000000000000000000000000000000000000000
return asset_id
Mintable ERC-1155
def getErcMintable1155AssetInfo(address):
MINTABLE_ERC1155_SELECTOR = '0xbae32628'
# 0xbae32628 = bytes4(keccak256('MintableERC1155Token(address,uint256)'))
asset_info = MINTABLE_ERC1155_SELECTOR + bytes.fromhex(address[2:]).rjust(32, b'\0')
# For Mintable ERC1155, asset_info is 36 bytes long.
return asset_info
def getMintableErc1155AssetType(address):
asset_info = getErcMintable1155AssetInfo(address)
asset_type = keccak256(asset_info, 1)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_type
def getMintableErc1155AssetId(minting_blob, address):
asset_type = getMintableErc1155AssetType(address)
blob_hash = keccak256(minting_blob)
asset_id = keccak256('MINTABLE:', asset_type, blob_hash)
& 0x0000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
asset_id = asset_id
| 0x400000000000000000000000000000000000000000000000000000000000000
return asset_id
Mintable ERC-20
def getErcMintable20AssetInfo(address):
MINTABLE_ERC20_SELECTOR = '0x68646e2d'
# 0x68646e2d = bytes4(keccak256('MintableERC20Token(address)'))
asset_info = MINTABLE_ERC20_SELECTOR + bytes.fromhex(address[2:]).rjust(32, b'\0')
# For Mintable ERC20, asset_info is 36 bytes long.
return asset_info
def getMintableErc20AssetType(address, quantum):
asset_info = getErcMintable20AssetInfo(address)
asset_type = keccak256(asset_info, quantum)
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
return asset_type
def getMintableErc20AssetId(minting_blob, address, quantum):
asset_type = getMintableErc20AssetType(address, quantum)
blob_hash = keccak256(minting_blob)
asset_id = keccak256('MINTABLE:', asset_type, blob_hash)
& 0x0000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
asset_id = asset_id
| 0x400000000000000000000000000000000000000000000000000000000000000
return asset_id