StarkEx Playground Tutorial

The StarkEx Playground is a StarkEx deployment on the Goerli testnet that provides a simple demonstration of the StarkEx scalability solution. You can use the Playground to:

  • easily submit transactions to StarkEx,

  • see these transactions in a StarkEx batch, and

  • watch how the state, including your transactions, is updated on-chain in the StarkEx contract.

If you want to skip a few steps and develop your own application, see the StarkEx SDK and the StarkEx crypto SDK.

If you have questions, at any step of the way, please contact us at info@starkware.co.

Try StarkEx: Deposit, Withdraw, Settle, and Mint

The StarkEx Playground package provides a list of valid, pre-prepared StarkEx transactions, such as deposits, withdrawals, settlements, and mint requests. You also get a Player script that submits these transactions to StarkEx.

Simply run the Player and:

  • observe the transactions as they propagate through StarkEx,

  • query StarkEx to see the latest off-chain batch with your transactions in it, and

  • watch as a new on-chain state is formed in the StarkEx smart contract.

For more information about StarkEx, see the High level overview.

Preparing the Playground package

Procedure
  1. Download starkex_playground.zip.

  2. Unzip starkex_playground.zip.

The Playground package includes the following files:

txs.json

A list of L2 transactions, including deposits, settlements, and withdrawals that are executed from the Vault range that you were assigned. These transactions are valid and signed by pre-defined users with their starkKey. This allows you to observe a full StarkEx operation cycle without getting into the details of the exact transaction for each operation.

player.py

A python script that checks and submits the list of transactions specified in txs.json to the StarkEx contract and the StarkEx off-chain service. These transactions are then submitted to the L2 StarkEx service, executed, and added to the batch to be submitted as a new on-chain state.

Running the Playground

Prerequisites
  • An Infura endpoint link for Goerli. If you don’t have one, please open an Ethereum account at https://infura.io/ to acquire a link.

  • Docker. To install Docker on Ubuntu or other Debian-based Linux distributions, enter the following command:

    $ sudo apt install -y docker.io
  • A Goerli Eth account with enough Eth to pay for the deposit transaction gas. For your convenience, you can try this faucet.

Procedure
  1. Change to the StarkEx_Playground directory.

  2. Build and run a Docker image by running the following commands:

    $ docker build -t <MEMORABLE_NAME> .
    $ docker run -it <MEMORABLE_NAME>
  3. Run the Player script by running the following command:

    $ ./player.py --txs txs.json --node_url <your infura node> --funder_private_key <your Goerli private key> --verbose

    You can export your Goerli private key from MetaMask:

    1. select Account Details from the menu next to the account address.

    2. select Export Private Key and provide your MetaMask password.

      This key is required to fund on-chain deposits and will only be used locally to sign the transactions.

Analyzing the output

The output includes two types:

  1. On-chain deposit transactions' description of the StarkEx contract with Etherscan links. See On-chain transactions.

  2. Off-chain StarkEx transactions' description containing the transaction type and unique tx_id. See Off-chain transactions.

On-chain transactions
Figure 1. On-chain transactions
Off-chain StarkEx transactions
Figure 2. Off-chain transactions

Congratulations! You’ve submitted your first StarkEx transactions. You can see the on-chain state update in a few minutes.

So, what happened here?

Which transactions did I submit?

The file txs.json contains an explicit list of transactions in StarkEx API format.

Let’s look at the following Deposit transaction as an example:

{
   "stark_key": "0xf8c6635f9cfe85f46759dc2eebe71a45b765687e35dbe5e74e8bde347813ef",
   "amount": "35",
   "token_id": "0x2761e6ac2b90cbef6f456a307e1715192da8eff78ceeb316a235e7cea822d71",
   "vault_id": 11454,
   "type": "DepositRequest"
}
  • stark_key is the cryptographic key that lets you sign transactions

  • amount is the value of the transfer

  • token_id is the ERC-20 token StarkEx identifier

  • vault_id is the account number in StarkEx that you are depositing to — this account must be an account that is associated with the specified stark_key

  • type describes the transaction type submitted, in this case, a DepositRequest.

How do I see the on-chain state update?

You can check the state in the StarkEx Playground smart contract at https://goerli.etherscan.io/address/0x5731aEa1809BE0454907423083fb879079FB69dF. If your batch is already submitted on-chain (allow about 5 minutes), you will see a state update transaction.

You can also check what happened in the Verifier smart contract, which verifies STARK proofs, at https://goerli.etherscan.io/address/0x8f97970aC5a9aa8D130d35146F5b59c4aef57963. You will see that a new proof was submitted for verification. Once the proof is verified, a new Fact is registered on-chain approving the proof validation. The StarkEx contract checks this Fact before updating the state.

How can I read the off-chain Vault balances?

Vault balances derive directly from the history of the transactions that were submitted to StarkEx batches. You can query this information off-chain by using the Feeder Gateway StarkEx API.

You cannot query the last batch until it has been created. So it is recommended to query the last batch only when you can track the on-chain state update.

Procedure
  1. Get the last batch_id:

    $ wget -nv -q -O- https://gw.playground-v2.starkex.co/v2/feeder_gateway/get_last_batch_id

    The output of this command is a unique identifier that you should use as the input for the next command.

  2. Get the content through the Feeder Gateway of the batch_id that was output in the previous step (or query previous batche):

    $ wget -nv -q -O- https://gw.playground-v2.starkex.co/v2/feeder_gateway/get_batch_info?batch_id=<batch_id>

Lines 2-14 provide the information about the order tree root and the vault tree root, which represents the state.

Lines 21 onward display the information about the transactions in the batch.

  • You can see your transactions using the tx_id that you saw in the Player script output, such as in line 27. Pay close attention to the field was_replaced.

  • Invalid transactions get the value true, as per the first and second transactions in lines 28 and 40 of Output of the feeder gateway.

  • Valid transactions are not replaced, and are assigned the value false, as per Output of the feeder gateway continued, line 52.

  • The StarkEx Playground is configured to skip invalid transactions rather than replacing them. However, in practice, this is a good indicator of whether the transaction was executed or not.

Output of the feeder gateway
Figure 3. Output of the feeder gateway
Output of the feeder gateway continued
Figure 4. Output of the feeder gateway continued

This is so cool! How do I submit some of my own transactions?

If you want to take it up a notch, you can modify the list of transactions by yourself or create a new list. To understand StarkEx flows better, see the following topics:

  • To onboard a new user, go to the deposit flow section

  • Off-chain transfers are described here

  • Off-chain settlements are described in thehttps://docs.starkware.co/starkex-v4/starkex-deep-dive/regular-flows/flows-for-off-chain-accounts/trade[trade section]

  • Off-chain minting is explainedhttps://docs.starkware.co/starkex-v4/starkex-deep-dive/regular-flows/flows-for-off-chain-accounts/offchain-minting[here]

  • In order to withdraw funds to L1, please read about the withdrawal flow

You can see the detailed definition of the StarkEx API here and use StarkEx SDK. In order to send your own transactions, you should be able to sign transactions with a STARK signature. You can generate your own starkKey pair or use our pre-defined starkKey pairs from player_data.py. You can use StarkEx js crypto SDK or use the python crypto library. An example of signing a limit order can be found here.

When you send transactions to the StarkEx Playground, they should be valid according to StarkEx’s business logic, or they will be rejected. For example, an invalid transaction is a deposit transaction with Alice’s starkKey to a Vault that corresponds to Bob’s starkKey.

I need some more guidance, can you help me?

Sure! Please contact us at info@starkware.co.