Release notes: StarkEx Spot Trading 4.5

New features

Volition

Your users can now choose between off-chain data availability, known as Validium, and on-chain data availability.

StarkEx now provides two vault trees: one for on-chain data, and one for off-chain data.

The valid vault ranges are: [0, 231] for Validium vaults (off-chain) [263, 263+231] for the ZK-Rollup vaults (on-chain)

  • The vault size results in each signature having 63 bits allocated for vaults.

  • The StarkEx contract supports both vault ID ranges. When depositing to a rollup vault, the 63rd bit of vaultId must be on. The roots of both vault trees are updated when UpdateState is called. The updated balances of rollup vaults are also emitted on-chain as calldata.

  • An escape hatch is checked against the tree in which the escaped vault is located.

Additional resource

  • More about Validium on StarkWare’s site.

Transaction bundling

StarkEx now supports a new type of transaction: A bundle set of transactions. With a transaction bundle, you can send StarkEx a list of transactions, where all transactions in the list are guaranteed to go into the same batch if possible, and if not possible, the system prompts for an alternative transaction. If any transaction inside the transaction bundle is invalid, you need to send an alternative transaction bundle.

A transaction bundle is useful for trading multiple asset types in one operation. For example, you can use transaction bundling to sell a set of NFTs as one package.

ERC-1155 token support

StarkEx now fully supports existing ERC-1155 tokens for both L1 and L2 vaults. Minting ERC-1155 tokens is not supported.

  • Each ERC-1155 token contract should be registered once, given assetInfo, which includes a selector and contract address, and a quantum. The same quantum applies to all different assets that belong to that asset type.

  • If different quantums are required for different assets within the same ERC-1155 contract, the same contract can be registered once per quantum. Note that each such registration results in a different asset type. The same tokenIds with different assetTypes result in different assetIds.

  • ERC1155_SELECTOR = bytes4(keccak256("ERC1155Token(address,uint256)")) (0x3348691d)

  • ERC-1155 tokens are deposited and withdrawn similarly to NFTs, including assetType and tokenId, but also including a quantizedAmount argument.

  • tokenId is the internal token ID within the ERC-1155 contract.

  • assetId is a unique StarkEx identifier calculated as follows: uint256(keccak256(abi.encodePacked("NON_MINTABLE:", assetType, tokenId))) & MASK_250

New L2 vault functions

  • Deposit for both ERC-721 and ERC-1155, recommended. For ERC-721, quantizedAmount must equal one:

      function depositWithTokenId(
      uint256 starkKey,
      uint256 assetType,
      uint256 tokenId,
      uint256 vaultId,
      uint256 quantizedAmount
  )

  • A wrapper for depositWithTokenId that supports only ERC-1155 tokens:

      function depositERC1155(
      uint256 starkKey,
      uint256 assetType,
      uint256 tokenId,
      uint256 vaultId,
      uint256 quantizedAmount
  )

  • To reclaim a cancelled deposit.

      function depositWithTokenIdReclaim(
      uint256 starkKey,
      uint256 assetType,
      uint256 tokenId,
      uint256 vaultId
  )

  • Withdrawal function that supports both ERC-721 and ERC-1155

      function withdrawWithTokenId(
      uint256 ownerKey,
      uint256 assetType,
      uint256 tokenId
  )

  • Return the StarkEx asset ID of a specific ERC-721 or ERC-1155 token. You can use this function to cancel a deposit, check pending on-chain balances, and so forth. function calculateAssetIdWithTokenId(uint256 assetType, uint256 tokenId) public view returns (uint256)

New L1 Vaults Functions

function depositERC1155ToVault(
    uint256 assetType,
    uint256 tokenId,
    uint256 vaultId,
    uint256 quantizedAmount
)

function withdrawErc1155FromVault(
    uint256 assetType,
    uint256 tokenId,
    uint256 vaultId,
    uint256 quantizedAmount
)

function getQuantizedErc1155VaultBalance(
    address ethKey,
    uint256 assetType,
    uint256 tokenId,
    uint256 vaultId
)

Updates

Gas Price

The maximum gas price is now 200 gwei.

Unique minting

  • Each new-minted ERC-721 token is unique.

  • The hash of the minted asset is stored in the orders tree

  • As part of this change, the StarkEx 4.5 order tree has changed from a Merkle tree into a Patricia tree. So during the upgrade to StarkEx 4.5, the orders root must change. As a result, the upgrade causes 0 time delay on the contract.

API additions and changes

Gateway

Deprecated features

The Order type field from Settlement is deprecated. Support will be removed in a subsequent version.

Bundled transaction

The add_transaction method now accepts a bundled transaction, using the MultiTransactionRequest transaction type.

Example of a bundled transaction

"tx": {
     "txs": [
    	{
        	"vault_id": 1654615998,
        	"token_id": "0x2dd48fd7a024204f7c1bd874da5e709d4713d60c8a70639eb1167b367a9c378",
        	"stark_key": "0x7c65c1e82e2e662f728b4fa42485e3a0a5d2f346baa9455e3e70682c2094cac",
        	"amount": "4029557120079369747",
        	"type": "DepositRequest"
    	},
    	{
        	"vault_id": 1654615998,
        	"token_id": "0x5ba91fa7a024204f7c1bd874da5e709d4713d60c8a70639eb1167b367a9c378",
        	"stark_key": "0x7c65c1e82e2e662f728b4fa42485e3a0a5d2f346baa9455e3e70682c2094cac",
        	"amount": "4029557120079369747",
        	"type": "WithdrawalRequest"
    	},
        ]
      "type": "MultiTransactionRequest"
},
"tx_id": 1234

Availability gateway

  • The get_batch_data API now accepts an additional (optional) boolean GET parameter: validate_rollup.

    • If this parameter is omitted, the response is the same as in StarkEx 4.0 (for backward compatibility).

    • If this parameter is provided (regardless of its value), the response will include the rollup vault tree root (in a new response object type).

    • If this parameter is provided and set to True, the rollup vault changes are also included in the response.

    • The committee will validate the rollup vault tree root if the parameter is set to True, however, this root will not be hashed as part of the DA claim.

      The old object names vault and order are unchanged. vault refers to the Validium vaults tree.

      Old versions of the committee service cannot use the new parameter. The committee service might fail if validate_rollup is set.

Example 1 of query response

availability_gateway/get_batch_data?batch_id=1
    	"update": {
        	"order_root": "0000000000000000000000000000000000000000000000000000000000000000",
        	"prev_batch_id": 0,
        	"vaults": {
            	"23336622": {
                	    "stark_key": "0x0",
                    "balance": "0",
                	    "token": "0x0"
            	}
           }
        	"orders" {
            	"3065896435020512722": {
                	"fulfilled_amount": "0"
            	},
            	"4293697043586109717": {
                	"fulfilled_amount": "0"
            	}
        	},
        	"vault_root": "0298df9f3babf341237de93fdad83825cc0c25dadddf7ca15bcc596ff55bdea0"
      }

Example 2 of query response

availability_gateway/get_batch_data?batch_id=1&validate_rollup=True
    	"update": {
        	"order_root": "0000000000000000000000000000000000000000000000000000000000000000",
        	"prev_batch_id": 0,
        	"vaults": {
            	"23336622": {
                	    "stark_key": "0x0",
                    "balance": "0",
                	    "token": "0x0"
            	}
           },
           "rollup_vaults": {
            	"9223372036878112430": {
                	    "stark_key": "0x0",
                    "balance": "0",
                	    "token": "0x0"
            	}
           },
        	"orders": {
            	"3065896435020512722": {
                	"fulfilled_amount": "0"
            	},
            	"4293697043586109717": {
                	"fulfilled_amount": "0"
            	}
        	},
        	"vault_root": "0298df9f3babf341237de93fdad83825cc0c25dadddf7ca15bcc596ff55bdea0",
           "rollup_vault_root": "0298df9f3babf341237de93fdad83825cc0c25dadddf7ca15bcc596ff55bdea0"
      }

Feeder gateway

  • All URLs now begin with v2/. For example:

    /v2/feeder_gateway/get_batch_info

    URLs starting without v2/ are deprecated but are still supported in this version.

  • get_batch_info in version 2 does not return roots. It returns the following:

    • previous batch ID

    • number of the transaction in the sequence

    • time created

    • information about transactions

  • Previously, get_batch_info returned the roots of the orders tree and the vaults tree, that is, the Validium vaults tree. The root of the orders tree can be a root of a Patricia tree if the batch was created after upgrading to StarkEx 4.5, or the root of a Merkle tree, if the batch was created before upgrading to StarkEx 4.5.

  • get_batch_ids is a deprecated function, and is not supported with the updated URL prefix v2/. If you still require this function, do not include the v2/ URL prefix. The function still receives the vault root, the order root, and the sequence number.

    The vault root should be the Validium vault root.