StarkEx Playground Tutorial

Introduction

Welcome to the StarkEx Playground tutorial. 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 have questions, at any step of the way, please contact us at [email protected].

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. These transactions apply to pre-registered StarkEx users. 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, read the documentation here.

The Playground Package

Download the package here:

Your Playground package includes the following files:

  1. 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 users that were registered to the system in advance using their starkKey. This allows you to observe a full StarkEx operation cycle without getting into the details of the exact transaction for each operation.

  2. 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.

How do I run it?

Prerequisites:

  1. 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.

  2. Docker (Linux install via:apt install -y docker.io).

  3. A Goerli Eth account with enough Eth to pay for the deposit transaction gas. For your convenience, you can try this faucet.

Usage:

  1. Download the StarkEx_Playground.zip, open it, and change the directory to the StarkEx_Playground directory.

  2. Build and run a Docker image by running the following command (see also, the REAME.md): 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> --verboseYou 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

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

You will now see output prints of two types:

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

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

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

That’s it; you've submitted your first StarkEx transactions. Congratulations! You will be able to 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

  • the final argument 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 StarkEx smart contract at https://goerli.etherscan.io/address/0x471bDA7f420de34282AB8AF1F5F3DAf2a4C09746. 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/0xAB43bA48c9edF4C2C4bB01237348D1D7B28ef168. 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. This information can be queried off-chain by using the Feeder Gateway StarkEx API.

You can not query the last batch until it has been created. For that reason, it is recommended to query the last batch only when you can track the on-chain state update.

This can be done by running the following commands:

  1. Get the last batch_id: wget -nv -q -O- https://gw.playground-v2.starkex.co/feeder_gateway/get_last_batch_id The output of this command is a unique identifier that should be used as input for the next command.

  2. Get the content through the Feeder Gateway of the batch_id that was provided in the previous step (or query previous batches): wget -nv -q -O- https://gw.playground-v2.starkex.co/feeder_gateway/get_batch_info?batch_id=<batch_id> The output will be similar to the one presented in Fig. 3. 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 will be able to spot your transactions using the tx_id that you saw in the Player script output (e.g., line 27). Pay close attention to the field was_replaced ; invalid transactions get the value true (as per the first and second transactions in Fig. 3; lines 28 and 40), valid transactions are not replaced, and are assigned the value false (line 52, Fig. 3.b). The StarkEx Playground is configured to skip the invalid transactions and not to replace them; however, in practice, this is a good indicator of whether the transaction was executed or not.

Figure 3.a Output of the Feeder Gateway
Figure 3.b Output of the Feeder Gateway continued

This is so cool! I want to try submitting some of my own transactions. How do I do that?

If you want to take it up a notch, you can modify the list of transactions by yourself or create a new list. You can see the detailed definition of the StarkEx API here. This requires you to be able to sign transactions with a STARK signature. Your user'sstarkKeypairs are available at player_data.py. You can find the signature library here and an example of signing a limit order here.

When you send transactions to the StarkEx Playground, they should be valid according to StarkEx's business logic; otherwise, 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 [email protected].